REST operations sidebar (github#26225)

* testing out a rest operations sidebar * cleanup * renamed 5 files * renamed 5 files * set redirect_from on 5 files * renamed 1 files * renamed 1 files * renamed 3 files * renamed 1 files * renamed 1 files * renamed 3 files * renamed 1 files * renamed 2 files * renamed 1 files * renamed 4 files * renamed 15 files * renamed 2 files * renamed 6 files * renamed 1 files * renamed 4 files * renamed 7 files * renamed 1 files * renamed 3 files * renamed 3 files * renamed 1 files * renamed 5 files * renamed 1 files * renamed 1 files * renamed 3 files * renamed 4 files * renamed 1 files * renamed 1 files * renamed 2 files * renamed 4 files * renamed 1 files * renamed 1 files * renamed 1 files * renamed 6 files * renamed 6 files * renamed 4 files * move files * adding more * updating to add restcontext and start of removing data/reusables/rest-reference * removed data/reusables * add a RestMiniTocItem and updating the filtering to add a subcategory so all manually added H3s are in mini tocs in addition to operations * remove console log * [WIP]: REST New Proposal Sidebar (github#26471) * saving * update sidebar * remove console log * update guides and overview * import Category for category level rest pages * update undefined restOperations * update restOperationData category and subcategory levels" * minor updates * update get mini toc items function * updating REST context for sidebar * updating rest data * remove console logs * WIP: mini-toc-ing the sidebar Co-authored-by: Robert Sese <rsese@github.com> * A little cleanup * Fix first subcategory link and add some comments * updating anchor links in sidebar * adding updates * remove standalone * update product and maptopic pages using article context * add conditional link wrapper * fix sidebar toggle and versions for enterprise admin * update versions per subcategory * Highlight sidebar link for current page * Update miniToc hash links and hash change tracking * fix unique key in CollapsibleSection * Fix list markup * remove title * update permissions * Hide minitocs on landing (github#26594) * hide minitocs on landing page * simplify page components and remove minitoc from sidebar for guides/overview * fix carats and category fix * remove id Co-authored-by: Grace Park <gracepark@github.com> * updating content based on versions script check with the OpenAPI * update script and content files * update script and content/rest files * update to add TocLanding * update script * update index files * add codespaces repository-secrets * remove openapi schema check script * remove minitocs at the top * add h2 about the {title} api * fix tests/unit/openapi-schema.js * Fix linting tests * fix search/topics test * fix tests/unit/pages test * update rest/reference links in components * run prettier * Update components/rest/RestReferencePage.tsx Co-authored-by: Rachael Sewell <rachmari@github.com> * Update components/rest/RestReferencePage.tsx Co-authored-by: Rachael Sewell <rachmari@github.com> * Update pages/[versionId]/rest/[category]/[subcategory].tsx Co-authored-by: Rachael Sewell <rachmari@github.com> * Update pages/[versionId]/rest/[category]/[subcategory].tsx Co-authored-by: Rachael Sewell <rachmari@github.com> * Update pages/[versionId]/rest/[category]/[subcategory].tsx Co-authored-by: Rachael Sewell <rachmari@github.com> * Update pages/[versionId]/rest/[category]/[subcategory].tsx Co-authored-by: Rachael Sewell <rachmari@github.com> * Update tests/unit/openapi-schema.js Co-authored-by: Rachael Sewell <rachmari@github.com> * updating comment location * remove dependabot override * remove path-utils current product update for rest * run linter * remove dependabot.md and remove h2 heading on restreference * update the correct product to rest for rest pages * adding comments for updates to path-utils * remove console log * REST sidebar: handle legacy v3 redirects (github#26686) * Add script to handle legacy v3 REST redirects * Run the script * Handle a redirect to a redirect * Update REST test URLs * 'await' and test runs subcategory of checks * Update REST URLs for routing/developer-site-redirects tests * Update developer-redirects fixture with new REST URLs * Resolve merge conflicts * Update rest-redirects fixture with new REST URLs * Fix broken links with REST pages re-org * redirectTo could be undefined * Fix script for posterity, can't redirect paths with hashes * Remove invalid hash redirects * Typically don't need to save one-off scripts * Undo redirect changes (not necessary for handling v3 redirects) * Remove script-added redirects * Update old v3 redirects with new REST URLs * No more GHES search indexing page * 'org' not 'organization' * Update fixture data for new REST URLs * revert any content directory changes Co-authored-by: Grace Park <gracepark@github.com> Co-authored-by: Rachael Sewell <rachmari@github.com> * Adding test rest (github#26750) * add test to check openapi schema versions and content rest frontmatter versions * update lib/redirects * fix test and add error messages * adding repository secrets * adding repository-secrets.md * Revert "update lib/redirects" This reverts commit 3aafe28265764d5bc09c0c478c8e0ca099c8fbcf. * remove lib/redirects changes and console logs * Update lib/rest/index.js Co-authored-by: Rachael Sewell <rachmari@github.com> * update unique key * Rest client side redirects (github#26754) * adding tags subcategory for the rest content repos category * run prettier * bug fix for anchor scrolls" (github#26892) * updating width size for rest reference page * Rest sidebar consolidation (github#26862) * refactor sidebar * fix articlecontext provider issue on rest product landing page for all versions * fix a bug, create new component * revert change to create new component and fix bug Co-authored-by: Rachael Sewell <rachmari@github.com> * Set currentAnchor with a hashchange handler (github#26923) * Rest sidebar design tweaks (github#26807) * Rest sidebar design tweaks * tweak color to subtle * use muted color and margin for line * update to design feedback Co-authored-by: Grace Park <gracepark@github.com> * Remove cheerio from rest-collapsible (github#26948) * remove cheerio from rest-collapsible * update type * adding endswith instead * use productId instead * one off edge case for secret-scanning * Reorganize subcategory and category, Update pre -> div, Add RestContext (github#26950) * reorganize subcategory and category * add RestContext * update comment * update for endpoints page * add comment * move object to restcontext * remove effectiveDate in restcontext * remove width calculation for rest reference page * fix adding manual writer's minitocs to sidebar * update with feedback * update comment * update isRestReferencePage * remove page component and fix bug * adding back rest/index.tsx Co-authored-by: Rachael Sewell <rachmari@github.com> * update content/rest" * add back design tweak * update to div * update margins on rest api reference * remove page component * adding tests * separate product from rest sidebar (github#27065) * separate product from rest sidebar * Use ProductCollapsibleSections for product pages * fix tests Co-authored-by: Robert Sese <rsese@github.com> Co-authored-by: Grace Park <gracepark@github.com> * Rest sidebar translations (github#27052) * update translations * remove general test Co-authored-by: Robert Sese <rsese@github.com> Co-authored-by: Rachael Sewell <rachmari@github.com>
michaelarnauts · Apr 20, 2022 · b98c83e · b98c83e
1 parent 5515db7
commit b98c83e
Show file tree

Hide file tree

Showing 1,175 changed files with 20,315 additions and 7,517 deletions.
diff --git a/components/DefaultLayout.tsx b/components/DefaultLayout.tsx
@@ -88,10 +88,7 @@ export const DefaultLayout = (props: Props) => {
       <SidebarNav />
       {/* Need to set an explicit height for sticky elements since we also
           set overflow to auto */}
-      <div
-        className="flex-column flex-1 overflow-auto print-overflow-visible"
-        style={{ height: '100vh' }}
-      >
+      <div className="flex-column flex-1">
         <Header />
         <main id="main-content" style={{ scrollMarginTop: '5rem' }}>
           <DeprecationBanner />

diff --git a/components/article/ClientSideHighlightJS.tsx b/components/article/ClientSideHighlightJS.tsx
@@ -26,7 +26,7 @@ const SUPPORTED_LANGUAGES = ['json', 'javascript', 'curl']
 //     </pre>
 //
 const CODE_ELEMENTS_PARENT_SELECTOR = '[data-highlight]'
-const CODE_SELECTOR = 'pre code'
+const CODE_SELECTOR = 'div code' || 'pre code'
 
 export default function ClientSideHighlightJS() {
   const { asPath } = useRouter()

diff --git a/components/context/RestContext.tsx b/components/context/RestContext.tsx
@@ -0,0 +1,37 @@
+import { createContext, useContext } from 'react'
+
+export type MiniTocItem = {
+  platform: string
+  contents: string & { title: string; href: string }
+  items?: MiniTocItem[]
+}
+
+export type RestContextT = {
+  title: string
+  intro: string
+  renderedPage: string | JSX.Element[]
+  miniTocItems: Array<MiniTocItem>
+}
+
+export const RestContext = createContext<RestContextT | null>(null)
+
+export const useRestContext = (): RestContextT => {
+  const context = useContext(RestContext)
+
+  if (!context) {
+    throw new Error('"useRestContext" may only be used inside "RestContext.Provider"')
+  }
+
+  return context
+}
+
+export const getRestContextFromRequest = (req: any): RestContextT => {
+  const page = req.context.page
+
+  return {
+    title: page.titlePlainText,
+    intro: page.intro,
+    renderedPage: req.context.renderedPage || '',
+    miniTocItems: req.context.miniTocItems || [],
+  }
+}
diff --git a/components/landing/TocLanding.tsx b/components/landing/TocLanding.tsx
@@ -1,3 +1,7 @@
+import { useState, useEffect } from 'react'
+import { useRouter } from 'next/router'
+import dynamic from 'next/dynamic'
+
 import { DefaultLayout } from 'components/DefaultLayout'
 import { TableOfContents } from 'components/landing/TableOfContents'
 import { useTocLandingContext } from 'components/context/TocLandingContext'
@@ -10,6 +14,13 @@ import { Callout } from 'components/ui/Callout'
 import { Lead } from 'components/ui/Lead'
 import { LearningTrackNav } from 'components/article/LearningTrackNav'
 
+const ClientSideRedirectExceptions = dynamic(
+  () => import('components/article/ClientsideRedirectExceptions'),
+  {
+    ssr: false,
+  }
+)
+
 export const TocLanding = () => {
   const {
     title,
@@ -23,8 +34,38 @@ export const TocLanding = () => {
   } = useTocLandingContext()
   const { t } = useTranslation('toc')
 
+  const { asPath } = useRouter()
+  // We have some one-off redirects for rest api docs
+  // currently those are limited to the repos page, but
+  // that will grow soon as we restructure the rest api docs.
+  // This is a workaround to updating the hardcoded links
+  // directly in the REST API code in a separate repo, which
+  // requires many file changes and teams to sign off.
+  // While the organization is turbulent, we can do this.
+  // Once it's more settled, we can refactor the rest api code
+  // to leverage the OpenAPI urls rather than hardcoded urls.
+  // The code below determines if we should bother loading this redirecting
+  // component at all.
+  // The reason this isn't done at the server-level is because there you
+  // can't possibly access the URL hash. That's only known in client-side
+  // code.
+  const [loadClientsideRedirectExceptions, setLoadClientsideRedirectExceptions] = useState(false)
+  useEffect(() => {
+    const { hash } = window.location
+    // Today, Jan 2022, it's known explicitly what the pathname.
+    // In the future there might be more.
+    // Hopefully, we can some day delete all of this and no longer
+    // be dependent on the URL hash to do the redirect.
+    if (hash && asPath.startsWith('/rest')) {
+      setLoadClientsideRedirectExceptions(true)
+    }
+  }, [])
+
   return (
     <DefaultLayout>
+      {/* Doesn't matter *where* this is included because it will
+      never render anything. It always just return null. */}
+      {loadClientsideRedirectExceptions && <ClientSideRedirectExceptions />}
       <div className="container-xl px-3 px-md-6 my-4">
         <ArticleGridLayout>
           <ArticleTitle>{title}</ArticleTitle>

diff --git a/components/page-header/Header.tsx b/components/page-header/Header.tsx
@@ -52,7 +52,7 @@ export const Header = () => {
   return (
     <div
       className={cx(
-        'border-bottom d-unset color-border-muted no-print z-3 color-bg-default',
+        'border-bottom d-unset color-border-muted no-print z-3 color-bg-default position-sticky top-0',
         styles.header
       )}
     >

diff --git a/components/page-header/RestBanner.tsx b/components/page-header/RestBanner.tsx
@@ -43,7 +43,7 @@ export const RestBanner = () => {
     >
     const newRestPagesText = pages.map((page, i) => [
       <React.Fragment key={page}>
-        <Link href={`/${router.locale}/rest/reference/${page}`}>
+        <Link href={`/${router.locale}/rest/${page}`}>
           {restRepoCategoryExceptionsTitles[page]}
         </Link>
         {i < pages.length - 1 && ', '}
@@ -60,7 +60,7 @@ export const RestBanner = () => {
     noticeString = (
       <React.Fragment>
         If you can't find what you're looking for, you might try the{' '}
-        <Link href={`/${router.locale}/rest/reference/actions`}>Actions</Link> REST API page.
+        <Link href={`/${router.locale}/rest/actions`}>Actions</Link> REST API page.
       </React.Fragment>
     )
   }

diff --git a/components/rest/CodeBlock.module.scss b/components/rest/CodeBlock.module.scss
@@ -1,4 +1,14 @@
 .codeBlock {
   max-height: 32rem;
   overflow: auto;
+  padding: 1rem;
+  margin-bottom: 1rem;
+  line-height: 1.45;
+  background-color: var(--color-canvas-subtle);
+  white-space: pre-wrap;
+  word-break: break-all;
+
+  code {
+    background-color: transparent;
+  }
 }
diff --git a/components/rest/CodeBlock.tsx b/components/rest/CodeBlock.tsx
@@ -31,7 +31,7 @@ export function CodeBlock({ verb, headingLang, codeBlock, highlight }: Props) {
           </Tooltip>
         </header>
       )}
-      <pre className={cx(styles.codeBlock, 'rounded-1 border')} data-highlight={highlight}>
+      <div className={cx(styles.codeBlock, 'rounded-1 border')} data-highlight={highlight}>
         <code>
           {verb && (
             <>
@@ -43,7 +43,7 @@ export function CodeBlock({ verb, headingLang, codeBlock, highlight }: Props) {
           )}
           {codeBlock}
         </code>
-      </pre>
+      </div>
     </div>
   )
 }
diff --git a/components/rest/RestReferencePage.tsx b/components/rest/RestReferencePage.tsx
@@ -1,18 +1,13 @@
 import React, { useState, useEffect } from 'react'
-import cx from 'classnames'
 import { useRouter } from 'next/router'
 import dynamic from 'next/dynamic'
 
 import { DefaultLayout } from 'components/DefaultLayout'
-import { useMainContext } from 'components/context/MainContext'
 import { MarkdownContent } from 'components/ui/MarkdownContent'
 import { Lead } from 'components/ui/Lead'
-import { MiniTocItem } from 'components/context/ArticleContext'
-import { RestCategoryOperationsT } from './types'
+import { useRestContext } from 'components/context/RestContext'
+import { Operation } from './types'
 import { RestOperation } from './RestOperation'
-import { ChevronDownIcon, ChevronUpIcon, SearchIcon } from '@primer/octicons-react'
-import { useTranslation } from 'components/hooks/useTranslation'
-import { ActionList } from '@primer/react'
 
 const ClientSideHighlightJS = dynamic(() => import('components/article/ClientSideHighlightJS'), {
   ssr: false,
@@ -26,24 +21,12 @@ const ClientSideRedirectExceptions = dynamic(
 )
 
 export type StructuredContentT = {
-  descriptions: any
-  introContent: string
-  restOperations: RestCategoryOperationsT
-  miniTocItems?: MiniTocItem[]
+  restOperations: Operation[]
 }
 
-export const RestReferencePage = ({
-  descriptions,
-  introContent,
-  restOperations,
-  miniTocItems,
-}: StructuredContentT) => {
-  const { t } = useTranslation('pages')
+export const RestReferencePage = ({ restOperations }: StructuredContentT) => {
   const { asPath } = useRouter()
-  const { page } = useMainContext()
-  const subcategories = Object.keys(restOperations)
-  const [collapsed, setCollapsed] = useState({} as Record<number, boolean>)
-
+  const { title, intro, renderedPage } = useRestContext()
   // We have some one-off redirects for rest api docs
   // currently those are limited to the repos page, but
   // that will grow soon as we restructure the rest api docs.
@@ -60,17 +43,13 @@ export const RestReferencePage = ({
   // code.
   const [loadClientsideRedirectExceptions, setLoadClientsideRedirectExceptions] = useState(false)
   useEffect(() => {
-    const { hash, pathname } = window.location
+    const { hash } = window.location
+
     // Today, Jan 2022, it's known explicitly what the pathname.
     // In the future there might be more.
     // Hopefully, we can some day delete all of this and no longer
     // be dependent on the URL hash to do the redirect.
-    if (
-      hash &&
-      (pathname.endsWith('/rest/reference/repos') ||
-        pathname.endsWith('/rest/reference/enterprise-admin') ||
-        pathname.endsWith('/rest/reference/deployments'))
-    ) {
+    if (hash && asPath.startsWith('/rest')) {
       setLoadClientsideRedirectExceptions(true)
     }
   }, [])
@@ -110,113 +89,31 @@ export const RestReferencePage = ({
     // consecutive one does.
   }, [asPath])
 
-  // Resetting the collapsed array when we move to another REST page
-  useEffect(() => {
-    setCollapsed({})
-  }, [asPath])
-
-  const handleClick = (param: number) => {
-    setCollapsed((prevState) => {
-      return { ...prevState, [param]: !prevState[param] }
-    })
-  }
-
-  const renderTocItem = (item: MiniTocItem, index: number) => {
-    return (
-      <ActionList.Item
-        as="li"
-        key={item.contents}
-        className={item.platform}
-        sx={{
-          listStyle: 'none',
-          padding: '2px',
-          ':hover': {
-            bg: 'var(--color-canvas-inset)',
-          },
-        }}
-      >
-        <div className={cx('lh-condensed d-block width-full')}>
-          <div className="d-inline-flex" dangerouslySetInnerHTML={{ __html: item.contents }} />
-          {item.items && item.items.length > 0 && (
-            <button
-              className="background-transparent border-0 ml-1"
-              onClick={() => handleClick(index)}
-            >
-              {!collapsed[index] ? <ChevronDownIcon /> : <ChevronUpIcon />}
-            </button>
-          )}
-          {collapsed[index] && item.items && item.items.length > 0 ? (
-            <ul className="ml-3">{item.items.map(renderTocItem)}</ul>
-          ) : null}
-        </div>
-      </ActionList.Item>
-    )
-  }
-
   return (
     <DefaultLayout>
       {/* Doesn't matter *where* this is included because it will
       never render anything. It always just return null. */}
       {loadClientsideRedirectExceptions && <ClientSideRedirectExceptions />}
       {lazyLoadHighlightJS && <ClientSideHighlightJS />}
-
-      <div className="container-xl px-3 px-md-6 my-4 mx-xl-12 mx-lg-12">
-        <h1>{page.title}</h1>
-        {page.introPlainText && (
+      <div className={'px-3 px-md-6 my-4 mx-xl-12 mx-lg-12'}>
+        <h1 className="mb-3">{title}</h1>
+        {intro && (
           <Lead data-testid="lead" data-search="lead" className="markdown-body">
-            {page.introPlainText}
+            {intro}
           </Lead>
         )}
-        <div className="my-3 d-flex">
-          <div className="pr-3 mt-1">
-            <Circle className="color-fg-on-emphasis color-bg-emphasis">
-              <SearchIcon className="" size={15} />
-            </Circle>
-          </div>
-          <div id="article-contents">
-            <h3>{t('miniToc')}</h3>
-            {miniTocItems && (
-              <ActionList
-                key={page.title}
-                items={miniTocItems.map((items, i) => {
-                  return {
-                    key: page.title + i,
-                    text: page.title,
-                    renderItem: () => <ul>{renderTocItem(items, i)}</ul>,
-                  }
-                })}
-              />
-            )}
-          </div>
-        </div>
-        <div key={`restCategory-introContent`}>
-          <div dangerouslySetInnerHTML={{ __html: introContent }} />
-        </div>
         <MarkdownContent>
-          {subcategories.map((subcategory, index) => (
-            <div key={`${subcategory}-${index}`}>
-              <div dangerouslySetInnerHTML={{ __html: descriptions[subcategory] }} />
-              {restOperations[subcategory].map((operation, index) => (
-                <RestOperation
-                  key={`${subcategory}-${operation.title}-${index}`}
-                  operation={operation}
-                />
-              ))}
-            </div>
-          ))}
+          <MarkdownContent>{renderedPage}</MarkdownContent>
+          {restOperations &&
+            restOperations.length > 0 &&
+            restOperations.map((operation, index) => (
+              <RestOperation
+                key={`restOperation-${operation.title}-${index}`}
+                operation={operation}
+              />
+            ))}
         </MarkdownContent>
       </div>
     </DefaultLayout>
   )
 }
-
-const Circle = ({ className, children }: { className?: string; children?: React.ReactNode }) => {
-  return (
-    <div
-      className={cx('circle d-flex flex-justify-center flex-items-center', className)}
-      style={{ width: 24, height: 24 }}
-    >
-      {children}
-    </div>
-  )
-}
diff --git a/components/rest/types.ts b/components/rest/types.ts
@@ -69,7 +69,3 @@ export interface ChildParameter {
   description: string
   type: string
 }
-
-export interface RestCategoryOperationsT {
-  [subcategory: string]: Operation[]
-}