@primer/doctocat-nextjs 0.1.0 → 0.2.0-rc.eeac884

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # @primer/doctocat-nextjs
 
+## 0.2.0
+
+### Minor Changes
+
+- [#20](https://github.com/primer/doctocat-nextjs/pull/20) [`be8bc6a`](https://github.com/primer/doctocat-nextjs/commit/be8bc6af733ba40bdd4393b876b2653017d7e846) Thanks [@rezrah](https://github.com/rezrah)! - Dropped support for Next.js Pages router in favor of App Router + Nextra v4
+
+  - [Read the migration guide from `v0.1.0` to `v0.2.0`](https://github.com/primer/doctocat-nextjs/blob/main/migration-guides/v0.2.0-app-router.md)
+
 ## 0.1.0
 
 ### Minor Changes

package/components/content/caption/Caption.tsx

@@ -1,6 +1,6 @@
-import React from 'react'
+import React, {PropsWithChildren} from 'react'
 import {Text} from '@primer/react'
 
-export function Caption(props) {
-  return <Text as="p" {...props} sx={{mt: 2, mb: 3, fontSize: 1, color: 'gray.5'}} />
+export function Caption(props: PropsWithChildren) {
+  return <Text as="p" {...props} sx={{mt: 2, mb: 3, fontSize: 1, color: 'var(--brand-color-text-default)'}} />
 }

package/components/content/dos-and-donts/DosAndDonts.module.css

@@ -0,0 +1,60 @@
+.container {
+  display: grid;
+  gap: 1rem;
+  margin: 1.5rem 0;
+}
+
+@media (min-width: 768px) {
+  .container:not(.stacked) {
+    grid-template-columns: 1fr 1fr;
+  }
+}
+
+.doDontBase {
+  display: flex;
+  flex-direction: column;
+}
+
+.doLabel .header {
+  background-color: var(--brand-color-success-fg);
+}
+
+.dontLabel .header {
+  background-color: var(--brand-color-error-fg);
+}
+
+.header {
+  display: flex;
+  align-self: start;
+  flex-direction: row;
+  align-items: center;
+  margin-bottom: 0.5rem;
+  border-radius: 0.25rem;
+  padding: 0 0.5rem;
+}
+
+.headerText {
+  font-weight: bold;
+  font-size: 0.875rem;
+  color: var(--base-color-scale-white-0);
+}
+
+.content {
+  display: flex;
+  flex-direction: column;
+}
+
+.content :last-child {
+  margin-bottom: 0;
+}
+
+.content img {
+  max-width: 100%;
+  margin-block-end: 0 !important;
+}
+
+.indentedContent {
+  margin: 0;
+  border-left: 4px solid;
+  padding-left: 1rem;
+}

package/components/content/dos-and-donts/DosAndDonts.tsx

@@ -1,25 +1,22 @@
 import React from 'react'
-import {Box, Text} from '@primer/react'
+import {Box} from '@primer/react'
+import clsx from 'clsx'
+import styles from './DosAndDonts.module.css'
 
 type DoDontContainerProps = {
   stacked?: boolean
 }
 
 export function DoDontContainer({stacked = false, children}: React.PropsWithChildren<DoDontContainerProps>) {
-  return (
-    <Box sx={{display: 'grid', gridTemplateColumns: ['1fr', null, stacked ? '1fr' : '1fr 1fr'], gridGap: 4, my: 6}}>
-      {children}
-    </Box>
-  )
+  return <div className={`${styles.container} ${stacked ? styles.stacked : ''}`}>{children}</div>
 }
-
 type DoDontProps = {
   indented?: boolean
 }
 
 export function Do({children, ...rest}: React.PropsWithChildren<DoDontProps>) {
   return (
-    <DoDontBase title="Do" bg="success.fg" borderColor="success.muted" {...rest}>
+    <DoDontBase title="Do" className={styles.doLabel} {...rest}>
       {children}
     </DoDontBase>
   )
@@ -27,7 +24,7 @@ export function Do({children, ...rest}: React.PropsWithChildren<DoDontProps>) {
 
 export function Dont({children, ...rest}: React.PropsWithChildren<DoDontProps>) {
   return (
-    <DoDontBase title="Don’t" bg="danger.fg" borderColor="danger.muted" {...rest}>
+    <DoDontBase title="Don’t" className={styles.dontLabel} {...rest}>
       {children}
     </DoDontBase>
   )
@@ -35,54 +32,30 @@ export function Dont({children, ...rest}: React.PropsWithChildren<DoDontProps>)
 
 type DoDontBaseProps = {
   title: string
-  bg: string
-  borderColor: string
+  className?: string
   indented?: boolean
 }
 
-export function DoDontBase({children, title, bg, borderColor, indented}: React.PropsWithChildren<DoDontBaseProps>) {
+export function DoDontBase({children, title, indented, className, ...rest}: React.PropsWithChildren<DoDontBaseProps>) {
   return (
-    <Box className="exclude-from-prose" sx={{display: 'flex', flexDirection: 'column'}}>
+    <div className={clsx(`exclude-from-prose`, styles.doDontBase, className)} {...rest}>
       <Box
+        className={styles.header}
         sx={{
-          display: 'flex',
-          alignSelf: 'start',
-          flexDirection: 'row',
-          alignItems: 'center',
-          mb: '2',
-          backgroundColor: bg,
-          borderRadius: '2',
-          color: 'fg.onEmphasis',
-          paddingX: '2',
+          color: 'var(--fgColor-onEmphasis, var(--color-fg-on-emphasis))',
         }}
       >
-        <Text sx={{fontWeight: 'bold', fontSize: '1', color: 'fg.onEmphasis'}}>{title}</Text>
+        <span className={styles.headerText}>{title}</span>
       </Box>
-      <Box
-        sx={{
-          '& *:last-child': {mb: 0},
-          ' img': {maxWidth: '100%', marginBlockEnd: 0},
-          display: 'flex',
-          flexDirection: 'column',
-        }}
-      >
+      <div className={styles.content}>
         {indented ? (
-          <Box
-            as="blockquote"
-            sx={{
-              margin: '0',
-              borderLeftWidth: '4px',
-              borderLeftStyle: 'solid',
-              borderLeftColor: borderColor,
-              paddingLeft: '3',
-            }}
-          >
+          <blockquote className={styles.indentedContent} style={{borderLeftColor: 'var(--brand-color-border-default)'}}>
             {children}
-          </Box>
+          </blockquote>
         ) : (
           children
         )}
-      </Box>
-    </Box>
+      </div>
+    </div>
   )
 }

package/components/context/color-modes/ColorModeProvider.tsx

@@ -1,7 +1,7 @@
-import React, {useState, useEffect, useCallback} from 'react'
+import React, {useState, useEffect, useCallback, PropsWithChildren} from 'react'
 import {ColorMode, ColorModeContext} from './context'
 
-const ColorModeProvider = ({children}) => {
+const ColorModeProvider = ({children}: PropsWithChildren) => {
   const [colorMode, setColorMode] = useState<ColorMode>('light')
 
   useEffect(() => {

package/components/index.ts

@@ -0,0 +1,9 @@
+/**
+ * Documentation components
+ */
+export {DoDontContainer, Do, Dont} from './content/dos-and-donts/DosAndDonts'
+export {Caption} from './content/caption/Caption'
+export * from './library'
+export {TableOfContents} from './layout/table-of-contents/TableOfContents'
+export {Article} from './layout/article/Article'
+export {HeadingLink} from './layout/heading-link/HeadingLinks'

package/components/layout/article/Article.module.css

@@ -0,0 +1,8 @@
+.Article {
+  display: grid;
+}
+
+.Article--withToc {
+  grid-template-columns: 1fr 200px;
+  gap: var(--base-size-48);
+}

package/components/layout/article/Article.tsx

@@ -0,0 +1,24 @@
+import React, {PropsWithChildren} from 'react'
+import {TableOfContents} from '../table-of-contents/TableOfContents'
+import styles from './Article.module.css'
+import bodyStyles from '../../../css/prose.module.css'
+import {Heading as HeadingType} from 'nextra'
+
+import clsx from 'clsx'
+
+type Props = {
+  toc: HeadingType[]
+  metadata: {
+    layout?: string
+  }
+}
+
+export function Article({children, toc, metadata}: PropsWithChildren<Props>) {
+  const hasToc = toc.length > 0
+  return (
+    <div className={clsx(styles.Article, hasToc && styles['Article--withToc'])}>
+      <div className={clsx(metadata.layout !== 'custom' && bodyStyles.Prose)}>{children}</div>
+      {hasToc && <TableOfContents headings={toc} />}
+    </div>
+  )
+}

package/components/layout/footer/Footer.tsx

@@ -0,0 +1,41 @@
+import React from 'react'
+import {PencilIcon} from '@primer/octicons-react'
+import {Box, InlineLink, Stack, Text} from '@primer/react-brand'
+
+type FooterProps = {
+  filePath: string
+  repoURL: string
+  repoSrcPath: string
+}
+
+export function Footer({repoURL, repoSrcPath, filePath}: FooterProps) {
+  return (
+    <footer>
+      <Box marginBlockStart={64}>
+        <Stack direction="vertical" padding="none" gap={16}>
+          <Stack direction="horizontal" padding="none" alignItems="center" gap={8}>
+            <PencilIcon size={16} fill="var(--brand-InlineLink-color-rest)" />
+
+            <InlineLink
+              target="_blank"
+              href={`${repoURL}/blob/main/${repoSrcPath ? `${repoSrcPath}/` : ''}${filePath}`}
+            >
+              Edit this page
+            </InlineLink>
+          </Stack>
+          <Box
+            marginBlockStart={8}
+            paddingBlockStart={24}
+            borderStyle="solid"
+            borderBlockStartWidth="thin"
+            borderColor="default"
+          >
+            <Text as="p" variant="muted" size="100">
+              &copy; {new Date().getFullYear()} GitHub, Inc. All rights reserved.
+            </Text>
+          </Box>
+        </Stack>
+      </Box>
+    </footer>
+  )
+}

package/components/layout/header/Header.tsx

@@ -1,10 +1,9 @@
+import React, {useCallback, useEffect, useMemo, useRef, useState} from 'react'
 import {MarkGithubIcon, MoonIcon, SearchIcon, SunIcon, ThreeBarsIcon, XIcon} from '@primer/octicons-react'
 import {Box, FormControl, IconButton, TextInput} from '@primer/react'
 import {Heading, Stack, Text} from '@primer/react-brand'
 import {clsx} from 'clsx'
 import {MdxFile, Folder, PageMapItem} from 'nextra'
-import type {PageItem} from 'nextra/normalize-pages'
-import React, {useCallback, useEffect, useMemo, useRef, useState} from 'react'
 import {debounce} from 'lodash'
 
 import Link from 'next/link'
@@ -17,8 +16,6 @@ import {DocsItem} from '../../../types'
 
 type HeaderProps = {
   pageMap: PageMapItem[]
-  docsDirectories: PageItem[]
-  menuItems: PageItem[]
   siteTitle: string
 }
 
@@ -28,7 +25,7 @@ type SearchResults = {
   url: string
 }
 
-export function Header({pageMap, docsDirectories, siteTitle}: HeaderProps) {
+export function Header({pageMap, siteTitle}: HeaderProps) {
   const {colorMode, setColorMode} = useColorMode()
   const inputRef = useRef<HTMLInputElement | null>(null)
   const searchResultsRef = useRef<HTMLElement | null>(null)
@@ -76,7 +73,7 @@ export function Header({pageMap, docsDirectories, siteTitle}: HeaderProps) {
     document.documentElement.setAttribute('data-color-mode', colorMode)
   }, [colorMode])
 
-  const setSearchResultsDebounced = debounce(data => setSearchResults(data), 1000)
+  const setSearchResultsDebounced = debounce((data: SearchResults[] | undefined) => setSearchResults(data), 1000)
 
   const searchData = useMemo(
     () =>
@@ -91,7 +88,9 @@ export function Header({pageMap, docsDirectories, siteTitle}: HeaderProps) {
         })
         .flat()
         .filter(Boolean)
-        .map(({frontMatter, route}: MdxFile) => {
+        .map(item => {
+          const {frontMatter, route} = item as MdxFile
+
           if (!frontMatter) return null
           const result = {
             title: frontMatter.title ? frontMatter.title : '',
@@ -148,7 +147,7 @@ export function Header({pageMap, docsDirectories, siteTitle}: HeaderProps) {
     }
   }
 
-  const handleSubmit = e => {
+  const handleSubmit = (e: React.FormEvent) => {
     e.preventDefault()
     if (!inputRef.current) return
     if (!inputRef.current.value) {
@@ -176,7 +175,7 @@ export function Header({pageMap, docsDirectories, siteTitle}: HeaderProps) {
           {siteTitle}
         </Text>
       </Link>
-      <Box className={clsx(styles.Header__searchArea, isSearchOpen && styles['Header__searchArea--open'])}>
+      <div className={clsx(styles.Header__searchArea, isSearchOpen && styles['Header__searchArea--open'])}>
         <FormControl>
           <FormControl.Label visuallyHidden>Search</FormControl.Label>
           <TextInput
@@ -294,7 +293,7 @@ export function Header({pageMap, docsDirectories, siteTitle}: HeaderProps) {
             />
           </Stack>
         </div>
-      </Box>
+      </div>
       <div>
         <Stack direction="horizontal" padding="none" gap={4}>
           <IconButton
@@ -318,11 +317,7 @@ export function Header({pageMap, docsDirectories, siteTitle}: HeaderProps) {
               aria-expanded={isNavDrawerOpen}
               onClick={() => setIsNavDrawerOpen(true)}
             />
-            <NavDrawer
-              isOpen={isNavDrawerOpen}
-              onDismiss={() => setIsNavDrawerOpen(false)}
-              navItems={docsDirectories}
-            />
+            <NavDrawer isOpen={isNavDrawerOpen} onDismiss={() => setIsNavDrawerOpen(false)} navItems={pageMap} />
           </Box>
         </Stack>
       </div>

package/components/layout/heading-link/HeadingLink.module.css

@@ -0,0 +1,16 @@
+.Heading__anchor {
+  color: var(--brand-color-text-default) !important;
+  text-decoration: none !important;
+}
+
+.Heading__anchorIcon {
+  position: relative;
+  visibility: hidden;
+  margin-left: var(--base-size-4);
+  vertical-align: middle !important;
+  top: -1px;
+}
+
+.Heading__anchor:hover .Heading__anchorIcon {
+  visibility: visible;
+}

package/components/layout/heading-link/HeadingLinks.tsx

@@ -0,0 +1,31 @@
+'use client'
+import React from 'react'
+import type {ComponentProps, ReactElement} from 'react'
+import {LinkIcon} from '@primer/octicons-react'
+import styles from './HeadingLink.module.css'
+import NextLink from 'next/link'
+import {Heading, type HeadingProps} from '@primer/react-brand'
+
+const headingSizeMap: Record<string, HeadingProps['size']> = {
+  h1: '4',
+  h2: '5',
+  h3: '6',
+  h4: 'subhead-large',
+  h5: 'subhead-medium',
+}
+
+export function HeadingLink({
+  tag,
+  children,
+  ...props
+}: ComponentProps<'h2'> & {
+  tag: `h${2 | 3 | 4 | 5 | 6}`
+}): ReactElement {
+  return (
+    <Heading as={tag} size={headingSizeMap[tag]} {...props}>
+      <NextLink href={`#${props.id}`} className={styles.Heading__anchor}>
+        {children} <LinkIcon className={styles.Heading__anchorIcon} size={14} />
+      </NextLink>
+    </Heading>
+  )
+}

package/components/layout/nav-drawer/Drawer.tsx

@@ -1,9 +1,14 @@
-import React from 'react'
+import React, {PropsWithChildren} from 'react'
 import {Box} from '@primer/react'
 import {AnimatePresence, motion} from 'framer-motion'
 import {FocusOn} from 'react-focus-on'
 
-export function Drawer({isOpen, onDismiss, children}) {
+type Drawer = {
+  isOpen: boolean
+  onDismiss: () => void
+}
+
+export function Drawer({isOpen, onDismiss, children}: PropsWithChildren<Drawer>) {
   return (
     <AnimatePresence>
       {isOpen ? (

package/components/layout/nav-drawer/NavDrawer.module.css

@@ -0,0 +1,51 @@
+.scrollContainer {
+  overflow: auto;
+  -webkit-overflow-scrolling: touch;
+  display: flex;
+  flex-direction: column;
+  height: 100%;
+  background-color: var(--brand-color-canvas-default);
+}
+
+.header {
+  display: flex;
+  flex-direction: column;
+  flex: 0 0 auto;
+  color: var(--brand-color-text-default);
+  background-color: var(--brand-color-canvas-default);
+}
+
+.headerBorder {
+  border-width: 0;
+  border-radius: 0;
+  border-bottom-width: 1px;
+  border-color: var(--brand-color-border-muted);
+  border-style: solid;
+}
+
+.headerContent {
+  padding: 20px;
+  padding-left: 16px;
+  padding-right: 12px;
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+}
+
+.headerLink {
+  font-weight: bold;
+  color: inherit;
+}
+
+.navContainer {
+  display: flex;
+  flex-direction: column;
+}
+
+.sidebarWrapper {
+  display: flex;
+  flex-direction: column;
+  flex: 1 0 auto;
+  color: var(--brand-color-text-default);
+  background-color: var(--brand-color-canvas-subtle);
+}

package/components/layout/nav-drawer/NavDrawer.tsx

@@ -1,64 +1,44 @@
 import React from 'react'
 import NextLink from 'next/link'
-import {Box, IconButton, Link, ThemeProvider} from '@primer/react'
+import {IconButton, Link, ThemeProvider} from '@primer/react'
 import {XIcon} from '@primer/octicons-react'
 
 import {Drawer} from './Drawer'
-import type {PageItem} from 'nextra/normalize-pages'
+import type {PageMapItem} from 'nextra'
 import {Sidebar} from '../sidebar/Sidebar'
 import {useColorMode} from '../../context/color-modes/useColorMode'
+import styles from './NavDrawer.module.css'
 
 type NavDrawerProps = {
   isOpen: boolean
   onDismiss: () => void
-  navItems?: PageItem[]
+  navItems?: PageMapItem[]
 }
 
 export function NavDrawer({isOpen, onDismiss, navItems}: NavDrawerProps) {
   const {colorMode} = useColorMode()
   return (
     <Drawer isOpen={isOpen} onDismiss={onDismiss}>
-      <Box
-        style={{overflow: 'auto', WebkitOverflowScrolling: 'touch'}}
-        sx={{flexDirection: 'column', height: '100%', bg: 'canvas.default', display: 'flex'}}
-      >
-        <Box
-          sx={{flexDirection: 'column', flex: '0 0 auto', color: 'fg.default', bg: 'canvas.default', display: 'flex'}}
-        >
-          <Box
-            sx={{
-              borderWidth: 0,
-              borderRadius: 0,
-              borderBottomWidth: 1,
-              borderColor: 'border.muted',
-              borderStyle: 'solid',
-            }}
-          >
-            <Box sx={{py: 20, pl: 4, pr: 3, alignItems: 'center', justifyContent: 'space-between', display: 'flex'}}>
-              <Link as={NextLink} href="https://primer.style" sx={{fontWeight: 'bold', color: 'inherit'}}>
+      <div className={styles.scrollContainer}>
+        <div className={styles.header}>
+          <div className={styles.headerBorder}>
+            <div className={styles.headerContent}>
+              <Link as={NextLink} href="https://primer.style" className={styles.headerLink}>
                 Explore
               </Link>
               <IconButton icon={XIcon} aria-label="Close" onClick={onDismiss} variant="invisible" />
-            </Box>
-          </Box>
-          <Box sx={{flexDirection: 'column', display: 'flex'}}>{/* <PrimerNavItems items={primerNavItems} /> */}</Box>
-        </Box>
+            </div>
+          </div>
+          <div className={styles.navContainer}>{/* <PrimerNavItems items={primerNavItems} /> */}</div>
+        </div>
         {navItems && navItems.length > 0 ? (
           <ThemeProvider colorMode={colorMode}>
-            <Box
-              sx={{
-                flexDirection: 'column',
-                flex: '1 0 auto',
-                color: 'fg.default',
-                bg: 'canvas.subtle',
-                display: 'flex',
-              }}
-            >
+            <div className={styles.sidebarWrapper}>
               <Sidebar pageMap={navItems} />
-            </Box>
+            </div>
           </ThemeProvider>
         ) : null}
-      </Box>
+      </div>
     </Drawer>
   )
 }

package/components/layout/nav-drawer/useNavDrawerState.ts

@@ -1,7 +1,7 @@
 import {useCallback, useEffect, useMemo, useState} from 'react'
 import debounce from 'lodash.debounce'
 
-export function useNavDrawerState(breakpoint): [boolean, (value: boolean) => void] {
+export function useNavDrawerState(breakpoint: string | number): [boolean, (value: boolean) => void] {
   if (typeof breakpoint === 'string') {
     breakpoint = parseInt(breakpoint, 10)
   }

package/components/layout/related-content-links/RelatedContentLinks.tsx

@@ -10,15 +10,16 @@ export type RelatedContentLink = MdxFile & {
 }
 
 export type RelatedContentLinksProps = {
-  links: RelatedContentLink[]
+  links?: RelatedContentLink[] | []
 }
 
 export function RelatedContentLinks({links}: RelatedContentLinksProps) {
-  if (!links.length) return null
-
+  if (!links?.length) return null
   return (
     <div className="custom-component">
-      <Heading as="h2">Related content</Heading>
+      <Heading as="h2" size="subhead-large">
+        Related content
+      </Heading>
       <UnorderedList className={styles.list}>
         {links.map(page => (
           <UnorderedList.Item key={page.route}>

package/components/layout/related-content-links/getRelatedPages.tsx

@@ -0,0 +1,57 @@
+import {DocsItem, FrontMatter} from '../../../types'
+import {RelatedContentLink} from './RelatedContentLinks'
+
+type GetRelatedPages = (
+  route: string,
+  activeMetadata?: FrontMatter,
+  flatDocsDirectories?: DocsItem[],
+) => RelatedContentLink[]
+
+/**
+ * Uses a frontmatter 'keywords' value (as an array)
+ * to find adjacent pages that share the same values.
+ * @returns {RelatedContentLink[]}
+ */
+export const getRelatedPages: GetRelatedPages = (route, activeMetadata, flatDocsDirectories) => {
+  if (!activeMetadata || !flatDocsDirectories) return []
+  const currentPageKeywords = activeMetadata.keywords || []
+
+  const relatedLinks = activeMetadata['related'] || []
+  const matches: RelatedContentLink[] = []
+
+  if (!relatedLinks.length || !flatDocsDirectories.length) return []
+  // 1. Check keywords property and find local matches
+  for (const page of flatDocsDirectories) {
+    if (page.route === route) continue
+
+    const pageKeywords = activeMetadata.keywords || []
+    const intersection = pageKeywords.filter(keyword => currentPageKeywords.includes(keyword))
+
+    if (intersection.length) {
+      matches.push(page)
+    }
+  }
+
+  // 2. Check related property for internal and external links
+  for (const link of relatedLinks) {
+    if (!link.title || !link.href || link.href === route) continue
+    if (link.href.startsWith('/')) {
+      const page = flatDocsDirectories.find(localPage => localPage.route === link.href) as
+        | RelatedContentLink
+        | undefined
+
+      if (page) {
+        const entry = {
+          ...page,
+          title: link.title || page.title,
+          route: link.href || page.route,
+        }
+        matches.push(entry)
+      }
+    } else {
+      matches.push({...link, route: link.href, name: link.title})
+    }
+  }
+
+  return matches
+}