reactify rest pages (#25005)

Author: rachmari

Dockerfile

@@ -46,7 +46,6 @@ COPY stylesheets ./stylesheets
 COPY pages ./pages
 COPY components ./components
 COPY lib ./lib
-
 # One part of the build relies on this content file to pull all-products
 COPY content/index.md ./content/index.md
 

components/article/ArticlePage.tsx

@@ -1,4 +1,4 @@
-import { useState, useEffect } from 'react'
+import { useState, useEffect, ReactNode } from 'react'
 import { useRouter } from 'next/router'
 import dynamic from 'next/dynamic'
 import cx from 'classnames'
@@ -50,7 +50,11 @@ const interactiveAlternatives: Record<string, { href: string }> = {
     },
 }
 
-export const ArticlePage = () => {
+export type StructuredContentT = {
+  structuredContent?: ReactNode
+}
+
+export const ArticlePage = ({ structuredContent }: StructuredContentT) => {
   const { asPath } = useRouter()
   const {
     title,
@@ -65,6 +69,7 @@ export const ArticlePage = () => {
     miniTocItems,
     currentLearningTrack,
   } = useArticleContext()
+  const renderedContent = structuredContent || renderedPage
   const { t } = useTranslation('pages')
   const currentPath = asPath.split('?')[0]
 
@@ -236,7 +241,7 @@ export const ArticlePage = () => {
           }
         >
           <div id="article-contents">
-            <MarkdownContent>{renderedPage}</MarkdownContent>
+            <MarkdownContent>{renderedContent}</MarkdownContent>
             {effectiveDate && (
               <div className="mt-4" id="effectiveDate">
                 Effective as of:{' '}

components/context/ArticleContext.tsx

@@ -17,7 +17,7 @@ export type ArticleContextT = {
   title: string
   intro: string
   effectiveDate: string
-  renderedPage: string
+  renderedPage: string | JSX.Element[]
   miniTocItems: Array<MiniTocItem>
   contributor: { name: string; URL: string } | null
   permissions?: string

components/context/MainContext.tsx

@@ -21,11 +21,16 @@ export type ProductGroupT = {
 }
 
 type VersionItem = {
+  // free-pro-team@latest, enterprise-cloud@latest, enterprise-server@3.3 ...
   version: string
   versionTitle: string
   currentRelease: string
   latestVersion: string
   shortName: string
+  // api.github.com, ghes-3.3, github.ae
+  openApiVersionName: string
+  // api.github.com, ghes-, github.ae
+  openApiBaseName: string
 }
 
 export type ProductTreeNode = {

components/page-header/RestBanner.tsx

@@ -4,17 +4,17 @@ import { useRouter } from 'next/router'
 import { Link } from 'components/Link'
 
 const restRepoDisplayPages = [
-  '/rest/reference/branches',
-  '/rest/reference/collaborators',
-  '/rest/reference/commits',
-  '/rest/reference/deployments',
-  '/rest/reference/pages',
-  '/rest/reference/releases',
-  '/rest/reference/repos',
-  '/rest/reference/metrics',
-  '/rest/reference/webhooks',
+  'branches',
+  'collaborators',
+  'commits',
+  'deployments',
+  'pages',
+  'releases',
+  'repos',
+  'metrics',
+  'webhooks',
 ]
-const restEnterpriseDisplayPages = ['/rest/reference/enterprise-admin']
+const restEnterpriseDisplayPages = ['enterprise-admin']
 const restRepoCategoryExceptionsTitles = {
   branches: 'Branches',
   collaborators: 'Collaborators',
@@ -28,18 +28,14 @@ const restRepoCategoryExceptionsTitles = {
 
 export const RestBanner = () => {
   const router = useRouter()
-  const restPage = (router.query.restPage as string[]) || []
-  const asPathRoot = `/${router.query.productId}/${restPage.join('/')}`
-  if (
-    !restRepoDisplayPages.includes(asPathRoot) &&
-    !restEnterpriseDisplayPages.includes(asPathRoot)
-  ) {
+  const restPage = router.query.category as string
+  if (!restRepoDisplayPages.includes(restPage) && !restEnterpriseDisplayPages.includes(restPage)) {
     return null
   }
 
   let noticeString
 
-  if (restRepoDisplayPages.includes(asPathRoot)) {
+  if (restRepoDisplayPages.includes(restPage)) {
     const pages = Object.keys(restRepoCategoryExceptionsTitles) as Array<
       keyof typeof restRepoCategoryExceptionsTitles
     >
@@ -58,7 +54,7 @@ export const RestBanner = () => {
         pages.
       </React.Fragment>
     )
-  } else if (restEnterpriseDisplayPages.includes(asPathRoot)) {
+  } else if (restEnterpriseDisplayPages.includes(restPage)) {
     noticeString = (
       <React.Fragment>
         If you can't find what you're looking for, you might try the{' '}

components/rest/CodeBlock.module.scss

@@ -0,0 +1,8 @@
+.codeBlock {
+  pre {
+    margin-bottom: 0;
+    border: 1px solid var(--color-border-default);
+    max-height: 32rem;
+    overflow: auto;
+  }
+}

components/rest/CodeBlock.tsx

@@ -0,0 +1,29 @@
+import cx from 'classnames'
+
+import styles from './CodeBlock.module.scss'
+
+type Props = {
+  verb?: string
+  codeBlock: string
+  setHTML?: boolean
+}
+
+export function CodeBlock({ verb, codeBlock, setHTML = false }: Props) {
+  return setHTML ? (
+    <div
+      className={cx(styles.codeBlock, 'rounded')}
+      dangerouslySetInnerHTML={{ __html: codeBlock }}
+    />
+  ) : (
+    <pre className={cx(styles.methodCodeBlock, 'mb-3 rounded-1 border')}>
+      <code>
+        {verb && (
+          <span className="color-bg-accent-emphasis color-fg-on-emphasis rounded-1 px-2 py-1 text-uppercase">
+            {verb}
+          </span>
+        )}{' '}
+        {codeBlock}
+      </code>
+    </pre>
+  )
+}

components/rest/RestCodeSamples.tsx

@@ -0,0 +1,48 @@
+import { xCodeSample } from './types'
+import { useTranslation } from 'components/hooks/useTranslation'
+import { CodeBlock } from './CodeBlock'
+
+type Props = {
+  slug: string
+  xCodeSamples: Array<xCodeSample>
+}
+
+export function RestCodeSamples({ slug, xCodeSamples }: Props) {
+  const { t } = useTranslation('products')
+
+  return (
+    <>
+      <h4 className="pt-3 my-4" id={`${slug}--code-samples`}>
+        <a href={`#${slug}--code-samples`}>{`${t('rest.reference.code_samples')}`}</a>
+      </h4>
+      {xCodeSamples.map((sample: xCodeSample, index: number) => {
+        const sampleElements: JSX.Element[] = []
+        if (sample.lang !== 'Ruby') {
+          sampleElements.push(
+            sample.lang === 'JavaScript' ? (
+              <h5 key={`${sample.lang}-${index}`} className="pt-3">
+                {sample.lang} (
+                <a className="text-underline" href="https://github.com/octokit/core.js#readme">
+                  @octokit/core.js
+                </a>
+                )
+              </h5>
+            ) : (
+              <h5 key={`${sample.lang}-${index}`} className="pt-3">
+                {sample.lang}
+              </h5>
+            )
+          )
+          sampleElements.push(
+            <CodeBlock
+              key={sample.lang + index}
+              codeBlock={sample.sourceHTML}
+              setHTML={true}
+            ></CodeBlock>
+          )
+        }
+        return sampleElements
+      })}
+    </>
+  )
+}

components/rest/RestHTTPMethod.tsx

@@ -0,0 +1,10 @@
+import { CodeBlock } from './CodeBlock'
+
+type Props = {
+  verb: string
+  requestPath: string
+}
+
+export function RestHTTPMethod({ verb, requestPath }: Props) {
+  return <CodeBlock verb={verb} codeBlock={requestPath}></CodeBlock>
+}

components/rest/RestNotes.tsx

@@ -0,0 +1,26 @@
+import { useTranslation } from 'components/hooks/useTranslation'
+
+type Props = {
+  notes: Array<string>
+  enabledForGitHubApps: boolean
+}
+
+export function RestNotes({ notes, enabledForGitHubApps }: Props) {
+  const { t } = useTranslation('products')
+
+  return (
+    <>
+      <h4 className="pt-4">{t('rest.reference.notes')}</h4>
+      <ul className="mt-2 pl-3 pb-2">
+        {enabledForGitHubApps && (
+          <li>
+            <a href="/developers/apps">Works with GitHub Apps</a>
+          </li>
+        )}
+        {notes.map((note: string) => {
+          return <li>{note}</li>
+        })}
+      </ul>
+    </>
+  )
+}

components/rest/RestOperation.tsx

@@ -0,0 +1,53 @@
+import { RestOperationHeading } from './RestOperationHeading'
+import { RestHTTPMethod } from './RestHTTPMethod'
+import { RestParameterTable } from './RestParameterTable'
+import { RestCodeSamples } from './RestCodeSamples'
+import { RestResponse } from './RestResponse'
+import { Operation } from './types'
+import { RestNotes } from './RestNotes'
+import { RestPreviewNotice } from './RestPreviewNotice'
+
+type Props = {
+  operation: Operation
+  index: number
+}
+
+export function RestOperation({ operation }: Props) {
+  const previews = operation['x-github'].previews
+  const hasRequiredPreviews = previews
+    ? previews.filter((preview) => preview.required).length > 0
+    : false
+
+  return (
+    <div>
+      <RestOperationHeading
+        slug={operation.slug}
+        summary={operation.summary}
+        descriptionHTML={operation.descriptionHTML}
+      />
+      <RestHTTPMethod verb={operation.verb} requestPath={operation.requestPath} />
+      {operation.parameters && (
+        <RestParameterTable
+          slug={operation.slug}
+          hasRequiredPreviews={hasRequiredPreviews}
+          xGitHub={operation['x-github']}
+          parameters={operation.parameters}
+          bodyParameters={operation.bodyParameters}
+        />
+      )}
+      {operation['x-codeSamples'] && operation['x-codeSamples'].length > 0 && (
+        <RestCodeSamples slug={operation.slug} xCodeSamples={operation['x-codeSamples']} />
+      )}
+      <RestResponse responses={operation.responses} />
+      {(operation.notes.length > 0 || operation['x-github'].enabledForGitHubApps) && (
+        <RestNotes
+          notes={operation.notes}
+          enabledForGitHubApps={operation['x-github'].enabledForGitHubApps}
+        />
+      )}
+      {previews && (
+        <RestPreviewNotice slug={operation.slug} previews={operation['x-github'].previews} />
+      )}
+    </div>
+  )
+}

components/rest/RestOperationHeading.tsx

@@ -0,0 +1,21 @@
+import { LinkIcon } from '@primer/octicons-react'
+
+type Props = {
+  slug: string
+  summary: string
+  descriptionHTML: string
+}
+
+export function RestOperationHeading({ slug, summary, descriptionHTML }: Props) {
+  return (
+    <>
+      <h3 id={slug}>
+        <a href={`#${slug}`}>
+          <LinkIcon size={16} className="m-1" />
+        </a>
+        {summary}
+      </h3>
+      <div dangerouslySetInnerHTML={{ __html: descriptionHTML }} />
+    </>
+  )
+}

components/rest/RestParameterTable.module.scss

@@ -0,0 +1,43 @@
+.parameterTable {
+  display: table;
+  border-collapse: collapse;
+  position: relative;
+  width: 100%;
+  line-height: 1.5;
+  table-layout: auto;
+
+  thead {
+    tr {
+      border-top: none;
+
+      th {
+        border: 0;
+        font-weight: normal;
+      }
+    }
+  }
+
+  tr:nth-child(2n) {
+    background: none !important;
+  }
+
+  td {
+    padding: 0.75rem 0.5rem !important;
+    border: 0 !important;
+    vertical-align: top;
+  }
+
+  tbody {
+    tr td:first-child {
+      font-weight: bold;
+    }
+
+    table tr td:not(:first-child) {
+      font-weight: normal;
+    }
+  }
+
+  code {
+    background-color: var(--color-canvas-subtle);
+  }
+}