@primer/doctocat-nextjs 0.2.0 → 0.3.0-rc.c313ac3

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # @primer/doctocat-nextjs
 
+## 0.3.0
+
+### Minor Changes
+
+- [#22](https://github.com/primer/doctocat-nextjs/pull/22) [`2b57bc4`](https://github.com/primer/doctocat-nextjs/commit/2b57bc456efc03c99255ca90098ca3e035da1206) Thanks [@rezrah](https://github.com/rezrah)! - Add live code editing and previews for `jsx` code blocks in Markdown. All other code blocks will continue to render as normal.
+
+  E.g.
+
+  <pre>
+  ```jsx
+  <p>Your React code here</p>
+  ```
+  </pre>
+
 ## 0.2.0
 
 ### Minor Changes

package/components/content/caption/Caption.tsx

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

package/components/context/color-modes/context.ts

@@ -1,6 +1,8 @@
 import {createContext} from 'react'
 
-export type ColorMode = 'light' | 'dark'
+export const colorModes = ['light', 'dark'] as const
+
+export type ColorMode = (typeof colorModes)[number]
 
 export type ColorModeContextProps = {
   colorMode: ColorMode

package/components/index.ts

@@ -7,3 +7,5 @@ export * from './library'
 export {TableOfContents} from './layout/table-of-contents/TableOfContents'
 export {Article} from './layout/article/Article'
 export {HeadingLink} from './layout/heading-link/HeadingLinks'
+export {CodeBlock} from './layout/code-block/CodeBlock'
+export {PropTableValues} from './layout/prop-values/PropValues'

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

@@ -0,0 +1,21 @@
+.reviewedLabel {
+  display: flex;
+  align-items: center;
+  gap: var(--base-size-8);
+  background-color: var(--base-color-scale-purple-0);
+  border-color: transparent;
+  color: var(--brand-color-text-default);
+  font-weight: var(--brand-text-weight-300);
+}
+
+[data-color-mode='dark'] .reviewedLabel {
+  background-color: var(--base-color-scale-purple-8);
+}
+
+.icon {
+  fill: var(--base-color-scale-purple-5);
+}
+
+[data-color-mode='dark'] .icon {
+  fill: var(--base-color-scale-purple-1);
+}

package/components/layout/article/AccessibilityLabel.tsx

@@ -0,0 +1,19 @@
+'use client'
+import {Label} from '@primer/react'
+import {AccessibilityInsetIcon} from '@primer/octicons-react'
+import React from 'react'
+
+import styles from './AccessibilityLabel.module.css'
+
+type AccessibilityLabelProps = {
+  short?: boolean
+}
+
+export function AccessibilityLabel({short}: AccessibilityLabelProps) {
+  return (
+    <Label size="large" className={styles.reviewedLabel}>
+      <AccessibilityInsetIcon className={styles.icon} />
+      {short ? 'Reviewed' : 'Reviewed for accessibility'}
+    </Label>
+  )
+}

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

@@ -3,6 +3,27 @@
 }
 
 .Article--withToc {
-  grid-template-columns: 1fr 200px;
   gap: var(--base-size-48);
 }
+
+.main {
+  order: 1;
+}
+
+.aside {
+  order: 0;
+}
+
+@media screen and (min-width: 768px) {
+  .main {
+    order: 0;
+  }
+
+  .aside {
+    order: 1;
+  }
+
+  .Article--withToc {
+    grid-template-columns: 1fr 200px;
+  }
+}

package/components/layout/article/Article.tsx

@@ -1,3 +1,4 @@
+'use client'
 import React, {PropsWithChildren} from 'react'
 import {TableOfContents} from '../table-of-contents/TableOfContents'
 import styles from './Article.module.css'
@@ -5,20 +6,58 @@ import bodyStyles from '../../../css/prose.module.css'
 import {Heading as HeadingType} from 'nextra'
 
 import clsx from 'clsx'
+import {AccessibilityLabel} from './AccessibilityLabel'
+import {Box, Stack} from '@primer/react-brand'
+import {ReadinessLabel} from './ReadinessLabel'
+import {SourceLink} from './SourceLink'
 
 type Props = {
   toc: HeadingType[]
   metadata: {
     layout?: string
+    [key: string]: unknown
+    figma?: string
+    source?: string
+    storybook?: string
   }
 }
 
 export function Article({children, toc, metadata}: PropsWithChildren<Props>) {
   const hasToc = toc.length > 0
+
+  const hasMetadata = Boolean(
+    metadata.ready || metadata.a11yReviewed || metadata.source || metadata.figma || metadata.storybook,
+  )
+
   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>
+    <>
+      <div className={clsx(styles.Article, hasToc && styles['Article--withToc'])}>
+        <div className={styles.main}>
+          {hasMetadata ? (
+            <Box marginBlockEnd={48}>
+              <Stack padding="none" direction="horizontal" justifyContent="space-between">
+                {metadata.ready || metadata.a11yReviewed ? (
+                  <Stack direction="horizontal" gap={8} padding="none">
+                    {metadata.ready === true && <ReadinessLabel />}
+                    {typeof metadata.a11yReviewed === 'boolean' && metadata.a11yReviewed && <AccessibilityLabel />}
+                  </Stack>
+                ) : null}
+                <Stack direction="horizontal" gap={16} padding="none">
+                  {metadata.source ? <SourceLink type="github" href={metadata.source} /> : null}
+                  {metadata.figma ? <SourceLink type="figma" href={metadata.figma} /> : null}
+                  {metadata.storybook ? <SourceLink type="storybook" href={metadata.storybook} /> : null}
+                </Stack>
+              </Stack>
+            </Box>
+          ) : null}
+          <div className={clsx(metadata.layout !== 'custom' && bodyStyles.Prose)}>{children}</div>
+        </div>
+        {hasToc && (
+          <div className={styles.aside}>
+            <TableOfContents headings={toc} />
+          </div>
+        )}
+      </div>
+    </>
   )
 }

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

@@ -0,0 +1,21 @@
+.label {
+  display: flex;
+  align-items: center;
+  gap: var(--base-size-8);
+  background-color: var(--base-color-scale-green-0);
+  border-color: transparent;
+  color: var(--brand-color-text-default);
+  font-weight: var(--brand-text-weight-300);
+}
+
+[data-color-mode='dark'] .label {
+  background-color: var(--base-color-scale-green-8);
+}
+
+.icon {
+  fill: var(--base-color-scale-green-5);
+}
+
+[data-color-mode='dark'] .icon {
+  fill: var(--base-color-scale-green-1);
+}

package/components/layout/article/ReadinessLabel.tsx

@@ -0,0 +1,15 @@
+'use client'
+import React from 'react'
+import {Label} from '@primer/react'
+import {CheckIcon} from '@primer/octicons-react'
+
+import styles from './ReadinessLabel.module.css'
+
+export function ReadinessLabel() {
+  return (
+    <Label size="large" className={styles.label}>
+      <CheckIcon className={styles.icon} />
+      Ready to use
+    </Label>
+  )
+}

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

@@ -0,0 +1,7 @@
+.link:not(:hover):not(:focus):not(:active) {
+  text-decoration: none !important;
+}
+
+.icon {
+  fill: var(--brand-InlineLink-color-rest);
+}

package/components/layout/article/SourceLink.tsx

@@ -0,0 +1,64 @@
+import {InlineLink, Stack, Text} from '@primer/react-brand'
+import {BookIcon, MarkGithubIcon} from '@primer/octicons-react'
+import React from 'react'
+
+import styles from './SourceLink.module.css'
+
+type SourceLinkProps = {
+  type: 'github' | 'storybook' | 'figma'
+  href: string
+}
+
+export function SourceLink({href, type}: SourceLinkProps) {
+  return (
+    <div className="custom-component">
+      <Stack padding="none" direction="horizontal" alignItems="center" gap={4}>
+        {type === 'github' ? <MarkGithubIcon className={styles.icon} /> : null}
+        {type === 'storybook' ? <BookIcon className={styles.icon} /> : null}
+        {type === 'figma' ? <FigmaLogo className={styles.icon} /> : null}
+
+        {type === 'github' ? (
+          <Text size="100">
+            <InlineLink href={href} className={styles.link} target="_blank">
+              GitHub
+            </InlineLink>
+          </Text>
+        ) : null}
+        {type === 'storybook' ? (
+          <Text size="100">
+            <InlineLink href={href} className={styles.link} target="_blank">
+              Storybook
+            </InlineLink>
+          </Text>
+        ) : null}
+        {type === 'figma' ? (
+          <Text size="100">
+            <InlineLink href={href} className={styles.link} target="_blank">
+              Figma
+            </InlineLink>
+          </Text>
+        ) : null}
+      </Stack>
+    </div>
+  )
+}
+
+function FigmaLogo({className}: {className?: string}) {
+  return (
+    <svg
+      className={className}
+      viewBox="0 0 16 16"
+      aria-hidden="true"
+      width={16}
+      height={16}
+      fill="currentColor"
+      xmlns="http://www.w3.org/2000/svg"
+    >
+      <path
+        fillRule="evenodd"
+        clipRule="evenodd"
+        d="M5.417 0A3.167 3.167 0 0 0 3.37 5.583 3.16 3.16 0 0 0 2.25 8a3.16 3.16 0 0 0 1.12 2.417 3.167 3.167 0 1 0 5.213 2.417V10.687a3.165 3.165 0 0 0 3.87-4.964A3.167 3.167 0 0 0 10.582 0H5.417Zm4.727 6.333h.21a1.665 1.665 0 1 1-.21 0Zm.25-1.5h.19a1.667 1.667 0 1 0 0-3.333H5.416a1.667 1.667 0 1 0 0 3.333h4.687a3.226 3.226 0 0 1 .29 0ZM3.75 8c0-.92.746-1.667 1.667-1.667h1.666v3.334H5.417C4.497 9.667 3.75 8.92 3.75 8Zm1.667 3.167a1.667 1.667 0 1 0 1.666 1.667v-1.667H5.417Z"
+      />
+    </svg>
+  )
+}

package/components/layout/code-block/CodeBlock.tsx

@@ -0,0 +1,18 @@
+'use client'
+import React, {PropsWithChildren} from 'react'
+
+import {ReactCodeBlock} from './ReactCodeBlock'
+import {Pre} from 'nextra/components'
+
+type CodeBlockProps = {
+  'data-language': string
+  jsxScope: Record<string, unknown>
+} & PropsWithChildren<HTMLElement>
+
+export function CodeBlock(props: CodeBlockProps) {
+  if (['tsx', 'jsx'].includes(props['data-language'])) {
+    return <ReactCodeBlock {...props} />
+  }
+
+  return <Pre>{props.children}</Pre>
+}

package/components/layout/code-block/ReactCodeBlock.module.css

@@ -0,0 +1,68 @@
+.CodeBlock {
+  margin-block: var(--base-size-24);
+  background-color: var(--brand-color-canvas-default);
+  border: var(--brand-borderWidth-thin) solid var(--brand-color-border-default);
+  border-radius: var(--brand-borderRadius-large);
+  display: flex;
+  flex-direction: column;
+  overflow: hidden;
+  width: 100%;
+  position: relative;
+}
+
+.Preview {
+  display: flex;
+  width: 100%;
+  padding: var(--base-size-16);
+  padding-block: var(--base-size-64);
+  min-height: 240px;
+  flex: 1 1;
+  align-items: center;
+  justify-content: center;
+}
+
+.Editor {
+  font-size: var(--brand-text-size-100);
+  line-height: var(--brand-text-lineHeight-100);
+  font-family: var(--brand-fontStack-monospace);
+  background-color: var(--brand-color-canvas-subtle);
+  overflow: auto;
+}
+
+.Editor pre {
+  font-size: inherit;
+  border-radius: 0;
+  padding: var(--base-size-16) !important;
+  background-color: var(--brand-color-canvas-subtle) !important;
+}
+
+.Toolbar {
+  display: flex;
+  gap: var(--base-size-8);
+  padding-inline: var(--base-size-16);
+  padding-block-start: var(--base-size-16);
+  border-top: var(--brand-borderWidth-thin) solid var(--brand-color-border-default);
+  background-color: var(--brand-color-canvas-subtle);
+}
+
+.Error pre {
+  margin-block: 0 !important;
+  border-radius: 0;
+  font-size: var(--brand-text-size-100);
+  line-height: var(--brand-text-lineHeight-100);
+  font-family: var(--brand-fontStack-monospace);
+  color: var(--brand-color-error-fg);
+}
+
+.colorModeMenu {
+  display: inline-block;
+  position: absolute;
+  top: var(--base-size-16);
+  right: var(--base-size-2);
+  z-index: 19;
+  width: 200px;
+}
+
+.colorModeButtonActive {
+  background-color: var(--brand-color-canvas-subtle);
+}

package/components/layout/code-block/ReactCodeBlock.tsx

@@ -0,0 +1,101 @@
+'use client'
+import React, {PropsWithChildren, useCallback, useState} from 'react'
+import clsx from 'clsx'
+import {LiveProvider, LiveEditor, LiveError, LivePreview} from 'react-live'
+import {useColorMode} from '../../context/color-modes/useColorMode'
+import styles from './ReactCodeBlock.module.css'
+import {ActionBar, Button, ThemeProvider} from '@primer/react'
+import {CopyIcon, MoonIcon, SunIcon, UndoIcon} from '@primer/octicons-react'
+import {colorModes} from '../../context/color-modes/context'
+
+import {lightTheme, darkTheme} from './syntax-highlighting-themes'
+
+type ReactCodeBlockProps = {
+  'data-language': string
+  'data-filename'?: string
+  jsxScope: Record<string, unknown>
+} & PropsWithChildren<HTMLElement>
+
+export function ReactCodeBlock(props: ReactCodeBlockProps) {
+  const {colorMode, setColorMode} = useColorMode()
+  const initialCode = getCodeFromChildren(props.children)
+  const [code, setCode] = useState(initialCode)
+  const shouldShowPreview = ['tsx', 'jsx'].includes(props['data-language'])
+
+  const handleReset = useCallback(() => {
+    setCode(initialCode)
+  }, [initialCode, setCode])
+
+  const handleCopy = useCallback(() => {
+    navigator.clipboard.writeText(code)
+  }, [code])
+
+  const noInline = props['data-filename'] === 'noinline' || false
+
+  return (
+    <>
+      <LiveProvider code={code} scope={props.jsxScope} noInline={noInline}>
+        <div className={clsx(styles.CodeBlock, 'custom-component')}>
+          {shouldShowPreview && (
+            <div>
+              <div className={styles.colorModeMenu}>
+                <ActionBar aria-label="Toolbar">
+                  {colorModes.map((mode, index) => {
+                    const Icon = mode === 'light' ? SunIcon : MoonIcon
+                    return (
+                      <ActionBar.IconButton
+                        className={clsx(styles.colorModeButton, colorMode === mode && styles.colorModeButtonActive)}
+                        key={`color-mode-${mode}-${index}`}
+                        icon={Icon}
+                        aria-label={mode}
+                        onClick={() => setColorMode(mode)}
+                      />
+                    )
+                  })}
+                </ActionBar>
+              </div>
+              <ThemeProvider colorMode={colorMode}>
+                <div className="custom-component">
+                  <LivePreview className={styles.Preview} />
+                </div>
+              </ThemeProvider>
+            </div>
+          )}
+          <div className={styles.Toolbar}>
+            <Button size="small" leadingVisual={CopyIcon} onClick={handleCopy}>
+              Copy
+            </Button>
+            <Button size="small" leadingVisual={UndoIcon} onClick={handleReset}>
+              Reset
+            </Button>
+          </div>
+          <div className={styles.Editor}>
+            <LiveEditor theme={colorMode === 'light' ? lightTheme : darkTheme} onChange={setCode} />
+          </div>
+          {shouldShowPreview && (
+            <div className={styles.Error}>
+              <LiveError />
+            </div>
+          )}
+        </div>
+      </LiveProvider>
+    </>
+  )
+}
+
+/**
+ * Helper function to turn Nextra <code> children into plain text
+ */
+function getCodeFromChildren(children: React.ReactNode) {
+  if (!React.isValidElement(children) || !children.props?.children) return ''
+
+  // Flattens the nested spans and combine their text content if it's a react child
+  const extractText = (node: React.ReactNode): string => {
+    if (typeof node === 'string') return node
+    if (Array.isArray(node)) return node.map(extractText).join('')
+    if (React.isValidElement(node) && node.props?.children) return extractText(node.props.children)
+    return ''
+  }
+
+  return extractText(children)
+}

package/components/layout/code-block/syntax-highlighting-themes.ts

@@ -0,0 +1,55 @@
+export const lightTheme = {
+  plain: {
+    backgroundColor: '#ffffff',
+    color: '#24292e',
+  },
+  styles: [
+    {
+      types: ['comment'],
+      style: {
+        color: '#6a737d',
+        fontStyle: 'italic' as const,
+      },
+    },
+    {
+      types: ['string', 'number', 'builtin', 'variable'],
+      style: {
+        color: '#032f62',
+      },
+    },
+    {
+      types: ['class-name', 'function', 'tag', 'attr-name'],
+      style: {
+        color: '#005CC5',
+      },
+    },
+  ],
+}
+
+export const darkTheme = {
+  plain: {
+    backgroundColor: '#0d1117',
+    color: '#c9d1d9',
+  },
+  styles: [
+    {
+      types: ['comment'],
+      style: {
+        color: '#8b949e',
+        fontStyle: 'italic' as const,
+      },
+    },
+    {
+      types: ['string', 'number', 'builtin', 'variable'],
+      style: {
+        color: '#a5d6ff',
+      },
+    },
+    {
+      types: ['class-name', 'function', 'tag', 'attr-name'],
+      style: {
+        color: '#d2a8ff',
+      },
+    },
+  ],
+}

package/components/layout/header/Header.module.css

@@ -6,6 +6,7 @@
   padding: var(--base-size-20) var(--base-size-12) var(--base-size-20) var(--base-size-16);
   border-bottom: var(--brand-borderWidth-thin) solid var(--brand-color-border-default);
   background: var(--brand-color-canvas-default);
+  z-index: 20;
 }
 
 @media (max-width: 768px) {

package/components/layout/header/Header.tsx

@@ -3,7 +3,7 @@ import {MarkGithubIcon, MoonIcon, SearchIcon, SunIcon, ThreeBarsIcon, XIcon} fro
 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 {MdxFile, PageMapItem} from 'nextra'
 import {debounce} from 'lodash'
 
 import Link from 'next/link'
@@ -11,11 +11,11 @@ import styles from './Header.module.css'
 import {NavDrawer} from '../nav-drawer/NavDrawer'
 import {useNavDrawerState} from '../nav-drawer/useNavDrawerState'
 import {useColorMode} from '../../context/color-modes/useColorMode'
-import {hasChildren} from '../../../helpers/hasChildren'
 import {DocsItem} from '../../../types'
 
 type HeaderProps = {
   pageMap: PageMapItem[]
+  flatDocsDirectories: DocsItem[]
   siteTitle: string
 }
 
@@ -25,7 +25,7 @@ type SearchResults = {
   url: string
 }
 
-export function Header({pageMap, siteTitle}: HeaderProps) {
+export function Header({pageMap, siteTitle, flatDocsDirectories}: HeaderProps) {
   const {colorMode, setColorMode} = useColorMode()
   const inputRef = useRef<HTMLInputElement | null>(null)
   const searchResultsRef = useRef<HTMLElement | null>(null)
@@ -74,32 +74,30 @@ export function Header({pageMap, siteTitle}: HeaderProps) {
   }, [colorMode])
 
   const setSearchResultsDebounced = debounce((data: SearchResults[] | undefined) => setSearchResults(data), 1000)
-
   const searchData = useMemo(
     () =>
-      pageMap
+      flatDocsDirectories
         .map(item => {
-          if (hasChildren(item)) {
-            return (item as Folder).children.filter(child => !hasChildren(child))
-          }
-          if ((item as DocsItem).type === 'doc') {
-            return item
-          }
+          if (item.route === '/') return null // remove homepage
+          return item
         })
-        .flat()
         .filter(Boolean)
         .map(item => {
           const {frontMatter, route} = item as MdxFile
-
           if (!frontMatter) return null
           const result = {
-            title: frontMatter.title ? frontMatter.title : '',
+            title:
+              frontMatter['show-tabs'] && frontMatter['tab-label']
+                ? `${frontMatter.title} | ${frontMatter['tab-label']}`
+                : frontMatter.title
+                  ? frontMatter.title
+                  : '',
             description: frontMatter.description ? frontMatter.description : '',
             url: route,
           }
           return result
         }),
-    [pageMap],
+    [flatDocsDirectories],
   )
 
   const handleChange = () => {

package/components/layout/index-cards/IndexCards.tsx

@@ -11,7 +11,13 @@ type IndexCardsProps = {
 }
 
 export function IndexCards({route, folderData}: IndexCardsProps) {
-  const filteredData = folderData.filter(item => item.type === 'doc' && item.route.includes(`${route}/`))
+  // We don't want to show children of these pages. E.g. tabbed pages
+  const onlyDirectChildren = folderData.filter(
+    item => item.route.includes(`${route}/`) && item.route.split('/').length === 3,
+  )
+
+  const filteredData = onlyDirectChildren.filter(item => item.type === 'doc' && item.route.includes(`${route}/`))
+
   return (
     <Stack direction="vertical" padding="none" gap="spacious">
       {filteredData.map((item: DocsItem) => {

package/components/layout/prop-values/PropValues.tsx

@@ -0,0 +1,54 @@
+'use client'
+import React from 'react'
+
+type PropTableValuesProps = {
+  values: (string | number)[]
+  addLineBreaks?: boolean
+  commaSeparated?: boolean
+  removeApostrophes?: boolean
+}
+
+export function PropTableValues({values, addLineBreaks, commaSeparated, removeApostrophes}: PropTableValuesProps) {
+  const valuesToRender = values.map(value => {
+    if (typeof value === 'string' && !removeApostrophes) {
+      return (
+        <span key={value}>
+          <code>&apos;{value}&apos;</code>
+        </span>
+      )
+    }
+    return (
+      <span key={value}>
+        <code> {value}</code>
+      </span>
+    )
+  })
+
+  if (commaSeparated) {
+    return (
+      <>
+        {valuesToRender.reduce((acc, curr, index) => (
+          <React.Fragment key={index}>
+            {acc}
+            {index > 0 && ', '}
+            {curr}
+          </React.Fragment>
+        ))}
+        {addLineBreaks && <br />}
+      </>
+    )
+  }
+
+  return (
+    <>
+      {valuesToRender.map(value => {
+        return (
+          <React.Fragment key={value.key}>
+            {value}
+            {addLineBreaks && <br />}
+          </React.Fragment>
+        )
+      })}
+    </>
+  )
+}

package/components/layout/root-layout/Theme.tsx

@@ -5,7 +5,8 @@ import Head from 'next/head'
 import type {Folder, MdxFile, PageMapItem} from 'nextra'
 import {useFSRoute} from 'nextra/hooks'
 import {BaseStyles, Box as PRCBox, Breadcrumbs, PageLayout, ThemeProvider} from '@primer/react'
-
+import '@primer/primitives/dist/css/functional/themes/light.css'
+import '@primer/primitives/dist/css/functional/themes/dark.css'
 import {
   Animate,
   AnimationProvider,
@@ -83,6 +84,7 @@ export function Theme({children, pageMap}: ThemeProps) {
   const filteredTabData: MdxFile[] = data && hasChildren(data) ? ((data as Folder).children as MdxFile[]) : []
 
   const relatedLinks = getRelatedPages(route, activeMetadata, flatDocsDirectories)
+  const disablePageAnimation = activeMetadata?.options?.disablePageAnimation || false
   return (
     <>
       <BrandThemeProvider dir="ltr" colorMode={colorMode}>
@@ -104,132 +106,153 @@ export function Theme({children, pageMap}: ThemeProps) {
               </Head>
             )}
 
-            <AnimationProvider runOnce visibilityOptions={1} autoStaggerChildren={false}>
-              <Animate animate="fade-in">
-                <PRCBox
-                  sx={{
-                    position: 'sticky',
-                    top: 0,
-                    zIndex: 99,
-                  }}
-                >
-                  <SkipToMainContent href="#main">Skip to main content</SkipToMainContent>
-                  <Header pageMap={pageMap} siteTitle={siteTitle} />
-                </PRCBox>
-                <PageLayout rowGap="none" columnGap="none" padding="none" containerWidth="full">
-                  <PageLayout.Content padding="normal">
-                    <div id="main">
-                      <PRCBox sx={!isHomePage && {maxWidth: 1200, width: '100%', margin: '0 auto'}}>
-                        <Stack direction="vertical" padding="none" gap="spacious">
-                          {!isHomePage && (
-                            <>
-                              {activePath.length && (
-                                <Breadcrumbs>
-                                  {siteTitle && (
+            <ContentWrapper disableAnimations={disablePageAnimation}>
+              <PRCBox
+                sx={{
+                  position: 'sticky',
+                  top: 0,
+                  zIndex: 99,
+                }}
+              >
+                <SkipToMainContent href="#main">Skip to main content</SkipToMainContent>
+                <Header pageMap={pageMap} flatDocsDirectories={flatDocsDirectories} siteTitle={siteTitle} />
+              </PRCBox>
+              <PageLayout rowGap="none" columnGap="none" padding="none" containerWidth="full">
+                <PageLayout.Content padding="normal">
+                  <div id="main">
+                    <PRCBox sx={!isHomePage && {maxWidth: 1200, width: '100%', margin: '0 auto'}}>
+                      <Stack direction="vertical" padding="none" gap="spacious">
+                        {!isHomePage && (
+                          <>
+                            {activePath.length && (
+                              <Breadcrumbs>
+                                {siteTitle && (
+                                  <Breadcrumbs.Item
+                                    as={NextLink}
+                                    href="/"
+                                    sx={{
+                                      color: 'var(--brand-InlineLink-color-rest)',
+                                    }}
+                                  >
+                                    {siteTitle}
+                                  </Breadcrumbs.Item>
+                                )}
+                                {activePath.map((item, index) => {
+                                  return (
                                     <Breadcrumbs.Item
                                       as={NextLink}
-                                      href="/"
+                                      key={item.name}
+                                      href={item.route}
+                                      selected={index === activePath.length - 1}
                                       sx={{
+                                        textTransform: 'capitalize',
                                         color: 'var(--brand-InlineLink-color-rest)',
                                       }}
                                     >
-                                      {siteTitle}
+                                      {item.title.replace(/-/g, ' ')}
                                     </Breadcrumbs.Item>
-                                  )}
-                                  {activePath.map((item, index) => {
-                                    return (
-                                      <Breadcrumbs.Item
-                                        as={NextLink}
-                                        key={item.name}
-                                        href={item.route}
-                                        selected={index === activePath.length - 1}
-                                        sx={{
-                                          textTransform: 'capitalize',
-                                          color: 'var(--brand-InlineLink-color-rest)',
-                                        }}
-                                      >
-                                        {item.title.replace(/-/g, ' ')}
-                                      </Breadcrumbs.Item>
-                                    )
-                                  })}
-                                </Breadcrumbs>
-                              )}
+                                  )
+                                })}
+                              </Breadcrumbs>
+                            )}
 
-                              <Box>
-                                <Stack direction="vertical" padding="none" gap={12} alignItems="flex-start">
-                                  {activeMetadata?.title && (
-                                    <Heading as="h1" size="3">
-                                      {activeMetadata.title}
-                                    </Heading>
-                                  )}
-                                  {activeMetadata?.description && (
-                                    <Text as="p" variant="muted" size="300">
-                                      {activeMetadata.description}
-                                    </Text>
-                                  )}
-                                  {activeMetadata?.image && (
-                                    <Box paddingBlockStart={16} style={{width: '100%'}}>
-                                      <Hero.Image src={activeMetadata.image} alt={activeMetadata['image-alt']} />
-                                    </Box>
-                                  )}
-                                  {activeMetadata && activeMetadata['action-1-text'] && (
-                                    <Box paddingBlockStart={16}>
-                                      <ButtonGroup>
-                                        <Button as="a" href={activeMetadata['action-1-link']}>
-                                          {activeMetadata['action-1-text']}
+                            <Box>
+                              <Stack direction="vertical" padding="none" gap={12} alignItems="flex-start">
+                                {activeMetadata?.title && (
+                                  <Heading as="h1" size="3">
+                                    {activeMetadata.title}
+                                  </Heading>
+                                )}
+                                {activeMetadata?.description && (
+                                  <Text as="p" variant="muted" size="300">
+                                    {activeMetadata.description}
+                                  </Text>
+                                )}
+                                {activeMetadata?.image && (
+                                  <Box paddingBlockStart={16} style={{width: '100%'}}>
+                                    <Hero.Image src={activeMetadata.image} alt={activeMetadata['image-alt']} />
+                                  </Box>
+                                )}
+                                {activeMetadata && activeMetadata['action-1-text'] && (
+                                  <Box paddingBlockStart={16}>
+                                    <ButtonGroup>
+                                      <Button as="a" href={activeMetadata['action-1-link']}>
+                                        {activeMetadata['action-1-text']}
+                                      </Button>
+                                      {activeMetadata['action-2-text'] && (
+                                        <Button as="a" variant="secondary" href={activeMetadata['action-2-link']}>
+                                          {activeMetadata['action-2-text']}
                                         </Button>
-                                        {activeMetadata['action-2-text'] && (
-                                          <Button as="a" variant="secondary" href={activeMetadata['action-2-link']}>
-                                            {activeMetadata['action-2-text']}
-                                          </Button>
-                                        )}
-                                      </ButtonGroup>
-                                    </Box>
-                                  )}
-                                </Stack>
-                              </Box>
-                              {activeMetadata && activeMetadata['show-tabs'] && (
-                                <UnderlineNav tabData={filteredTabData} />
+                                      )}
+                                    </ButtonGroup>
+                                  </Box>
+                                )}
+                              </Stack>
+                            </Box>
+                            {activeMetadata && activeMetadata['show-tabs'] && (
+                              <UnderlineNav tabData={filteredTabData} />
+                            )}
+                          </>
+                        )}
+                        <article>
+                          {isIndexPage ? (
+                            <IndexCards folderData={flatDocsDirectories} route={route} />
+                          ) : (
+                            <>
+                              <>{children}</>
+
+                              {relatedLinks.length > 0 && (
+                                <PRCBox sx={{pt: 5}}>
+                                  <RelatedContentLinks links={relatedLinks} />
+                                </PRCBox>
                               )}
                             </>
                           )}
-                          <article>
-                            {isIndexPage ? (
-                              <IndexCards folderData={flatDocsDirectories} route={route} />
-                            ) : (
-                              <>
-                                <>{children}</>
-
-                                {relatedLinks.length > 0 && (
-                                  <PRCBox sx={{pt: 5}}>
-                                    <RelatedContentLinks links={relatedLinks} />
-                                  </PRCBox>
-                                )}
-                              </>
-                            )}
-                          </article>
-                          <Footer filePath={filePath} repoURL={repoURL} repoSrcPath={repoSrcPath} />
-                        </Stack>
-                      </PRCBox>
-                    </div>
-                  </PageLayout.Content>
-                  <PageLayout.Pane
-                    aria-label="Side navigation"
-                    width="small"
-                    sticky
-                    padding="none"
-                    position="start"
-                    hidden={{narrow: true}}
-                    divider="line"
-                  >
-                    <Sidebar pageMap={pageMap} />
-                  </PageLayout.Pane>
-                </PageLayout>
-              </Animate>
-            </AnimationProvider>
+                        </article>
+                        <Footer filePath={filePath} repoURL={repoURL} repoSrcPath={repoSrcPath} />
+                      </Stack>
+                    </PRCBox>
+                  </div>
+                </PageLayout.Content>
+                <PageLayout.Pane
+                  aria-label="Side navigation"
+                  width="small"
+                  sticky
+                  padding="none"
+                  position="start"
+                  hidden={{narrow: true}}
+                  divider="line"
+                >
+                  <Sidebar pageMap={pageMap} />
+                </PageLayout.Pane>
+              </PageLayout>
+            </ContentWrapper>
           </BaseStyles>
         </ThemeProvider>
       </BrandThemeProvider>
     </>
   )
 }
+
+type ContentWrapperProps = PropsWithChildren<{
+  disableAnimations?: boolean
+}>
+
+/**
+ * The fade in animation masks the layout repainting issues.
+ * That animation however, interferes with nested AnimationProviders so we need
+ * to disable it for certain pages that use that.
+ */
+function ContentWrapper({children, disableAnimations}: ContentWrapperProps) {
+  if (disableAnimations) {
+    return <>{children}</>
+  }
+
+  return (
+    <>
+      <AnimationProvider runOnce visibilityOptions={1} autoStaggerChildren={false}>
+        <Animate animate="fade-in">{children}</Animate>
+      </AnimationProvider>
+    </>
+  )
+}

package/components/layout/underline-nav/UnderlineNav.tsx

@@ -41,7 +41,7 @@ export function UnderlineNav({tabData}: UnderlineNavProps) {
               href={`${item.route}`}
               aria-current={currentRoute === item.route ? 'page' : undefined}
             >
-              {(item.frontMatter && item.frontMatter.title) || item.name}
+              {(item.frontMatter && (item.frontMatter['tab-label'] || item.frontMatter.title)) || item.name}
             </PrimerUnderlineNav.Item>
           )
         })}

package/css/prose.module.css

@@ -32,25 +32,11 @@
 /* 2. Element spacing                                         */
 /* ---------------------------------------------------------- */
 
-/* .Prose * + * {
-  margin-block-start: var(--spacing, 1em);
-} */
-
-.Prose h1:not(:global(.custom-component) h1),
-.Prose h2:not(:global(.custom-component) h2),
-.Prose h3:not(:global(.custom-component) h3),
-.Prose h4:not(:global(.custom-component) h4),
-.Prose h5:not(:global(.custom-component) h5),
-.Prose h6:not(:global(.custom-component) h6),
-.Prose p:not(:global(.custom-component) p),
-.Prose ul:not(:global(.custom-component) ul),
-.Prose ol:not(:global(.custom-component) ol),
-.Prose blockquote:not(:global(.custom-component) blockquote),
-.Prose hr:not(:global(.custom-component) hr),
-.Prose table:not(:global(.custom-component) table),
-.Prose pre:not(:global(.custom-component) pre),
-.Prose dl:not(:global(.custom-component) dl),
-.Prose figure:not(:global(.custom-component) figure) {
+.Prose
+  :is(h1, h2, h3, h4, h5, h6, p, ul, ol, blockquote, figure, hr, table, pre, dl):not(
+    :first-child,
+    :global(.custom-component) :is(h1, h2, h3, h4, h5, h6, p, ul, ol, blockquote, figure, hr, table, pre, dl)
+  ) {
   margin-block-start: var(--spacing, 1em);
 }
 
@@ -66,7 +52,7 @@
 /* 4. Headings                                                */
 /* ---------------------------------------------------------- */
 
-.Prose h1 {
+.Prose h1:not(:global(.custom-component) h1) {
   font-weight: var(--brand-heading-weight-900);
   font-size: var(--base-size-32);
   line-height: 1.5;
@@ -74,11 +60,11 @@
   letter-spacing: var(--brand-text-letterSpacing-800);
 }
 
-.Prose--lineLength h1 {
+.Prose--lineLength h1:not(:global(.custom-component) h1) {
   max-width: 22ch;
 }
 
-.Prose h2 {
+.Prose h2:not(:global(.custom-component) h2) {
   font-weight: var(--brand-heading-weight-700);
   font-size: var(--base-size-24);
   line-height: var(--base-size-24);
@@ -86,11 +72,11 @@
   letter-spacing: var(--brand-text-letterSpacing-700);
 }
 
-.Prose--lineLength h2 {
+.Prose--lineLength h2:not(:global(.custom-component) h2) {
   max-width: 26ch;
 }
 
-.Prose h3 {
+.Prose h3:not(:global(.custom-component) h3) {
   font-weight: var(--brand-heading-weight-600);
   font-size: var(--base-size-20);
   line-height: var(--base-size-20);
@@ -98,11 +84,11 @@
   letter-spacing: var(--brand-heading-letterSpacing-600);
 }
 
-.Prose--lineLength h1 {
+.Prose--lineLength h3:not(:global(.custom-component) h3) {
   max-width: 32ch;
 }
 
-.Prose h4 {
+.Prose h4:not(:global(.custom-component) h4) {
   --spacing: var(--base-size-40);
   font-weight: var(--brand-text-weight-500);
   font-size: var(--base-size-18);
@@ -111,7 +97,7 @@
   letter-spacing: var(--brand-heading-letterSpacing-500);
 }
 
-.Prose h5 {
+.Prose h5:not(:global(.custom-component) h5) {
   --spacing: var(--base-size-40);
   font-weight: var(--brand-text-weight-400);
   font-size: var(--base-size-16);
@@ -120,7 +106,7 @@
   letter-spacing: var(--brand-heading-letterSpacing-400);
 }
 
-.Prose h6 {
+.Prose h6:not(:global(.custom-component) h6) {
   --spacing: var(--base-size-48);
   font-weight: var(--brand-text-subhead-weight-large);
   font-size: var(--base-size-14);
@@ -129,12 +115,12 @@
   letter-spacing: var(--brand-heading-letterSpacing-300);
 }
 
-.Prose :is(h1) {
+.Prose :is(h1):not(:global(.custom-component) h1) {
   --spacing: var(--base-size-64);
   margin-block-end: var(--spacing);
 }
 
-.Prose :is(h2, h3) + * {
+.Prose :is(h2, h3):not(:global(.custom-component) :is(h2, h3)) + * {
   --spacing: var(--base-size-40);
 }
 
@@ -142,7 +128,7 @@
 /* 5. Paragraphs                                              */
 /* ---------------------------------------------------------- */
 
-.Prose p {
+.Prose p:not(:global(.custom-component) p) {
   --spacing: var(--base-size-24);
 }
 
@@ -150,8 +136,8 @@
 /* 6. Lists                                                   */
 /* ---------------------------------------------------------- */
 
-.Prose ul,
-.Prose ol {
+.Prose ul:not(:global(.custom-component) ul),
+.Prose ol:not(:global(.custom-component) ol) {
   --spacing: var(--base-size-16);
   display: flex;
   flex-direction: column;
@@ -161,12 +147,12 @@
   line-height: var(--brand-text-lineHeight-300);
 }
 
-.Prose ul {
+.Prose ul:not(:global(.custom-component) ul) {
   list-style-type: image;
   list-style-image: var(--brand-Prose-unorderedList-imageUrl);
 }
 
-.Prose li {
+.Prose li:not(:global(.custom-component) li) {
   --spacing: 0;
 }
 
@@ -174,11 +160,11 @@
 /* 7. Inline elements                                         */
 /* ---------------------------------------------------------- */
 
-.Prose strong {
+.Prose strong:not(:global(.custom-component) strong) {
   font-weight: var(--brand-text-weight-800);
 }
 
-.Prose em {
+.Prose em:not(:global(.custom-component) em) {
   font-variation-settings: 'ital' 10;
   font-synthesis: none;
 }
@@ -215,7 +201,7 @@
   border-color: var(--brand-InlineLink-color-pressed);
 }
 
-.Prose code {
+.Prose code:not(:global(.custom-component) code) {
   font-family: var(--brand-fontStack-monospace);
   font-size: var(--brand-text-size-100);
   white-space: break-spaces;
@@ -224,7 +210,7 @@
   background-color: var(--base-color-scale-indigo-0);
 }
 
-[data-color-mode='dark'] .Prose code {
+[data-color-mode='dark'] .Prose code:not(:global(.custom-component) code) {
   background-color: var(--base-color-scale-indigo-9);
 }
 
@@ -232,7 +218,7 @@
 /* 8. Images                                                  */
 /* ---------------------------------------------------------- */
 
-.Prose img {
+.Prose img:not(:global(.custom-component) img) {
   --spacing: var(--brand-Prose-img-spacing);
   display: block;
   max-width: 100%;
@@ -244,7 +230,7 @@
   overflow: hidden;
 }
 
-.Prose video {
+.Prose video:not(:global(.custom-component) video) {
   --spacing: var(--brand-Prose-img-spacing);
   display: block;
   max-width: 100%;
@@ -256,7 +242,7 @@
 /* 9. Block elements                                          */
 /* ---------------------------------------------------------- */
 
-.Prose blockquote {
+.Prose blockquote:not(:global(.custom-component) blockquote) {
   font-family: var(--brand-fontStack-sansSerif);
   --spacing: var(--brand-Prose-blockquote-spacing);
   position: relative;
@@ -264,11 +250,11 @@
   line-height: var(--brand-text-lineHeight-400);
   padding-top: var(--base-size-48);
   padding-left: var(--base-size-40);
-  padding-bottom: var(--base-size-8);
+  padding-bottom: var (--base-size-8);
   margin-bottom: var(--spacing);
 }
 
-.Prose blockquote::before {
+.Prose blockquote:not(:global(.custom-component) blockquote)::before {
   content: '“';
   font-size: var(--base-size-48);
   line-height: var(--base-size-64);
@@ -277,7 +263,7 @@
   top: 0;
 }
 
-.Prose blockquote::after {
+.Prose blockquote:not(:global(.custom-component) blockquote)::after {
   content: '';
   display: block;
   position: absolute;
@@ -289,14 +275,14 @@
   background-image: linear-gradient(180deg, var(--base-color-scale-blue-5), var(--base-color-scale-purple-5));
 }
 
-.Prose figure figcaption {
+.Prose figure figcaption:not(:global(.custom-component) figure figcaption) {
   font-family: var(--brand-fontStack-monospace);
   font-size: var(--brand-text-size-100);
   line-height: var(--brand-text-lineHeight-100);
   color: var(--brand-color-text-muted);
 }
 
-.Prose hr {
+.Prose hr:not(:global(.custom-component) hr) {
   --spacing: var(--base-size-64);
   border: 0;
   height: 1px;
@@ -304,7 +290,61 @@
 }
 
 /**
-* 10. Custom stuff - Move out to separate stylesheet
+* 10. Tables
+*/
+
+.Prose table:not(:global(.custom-component) table) {
+  width: 100%;
+  overflow: auto;
+  border-collapse: separate;
+  border-spacing: 0;
+}
+
+.Prose th:not(:global(.custom-component) th) {
+  font-weight: var(--brand-text-weight-600);
+  background-color: var(--brand-color-bg-subtle);
+}
+
+.Prose :is(th, td):not(:global(.custom-component) :is(th, td)) {
+  padding: var(--base-size-8) var(--base-size-16);
+  border-color: var(--brand-color-border-muted);
+  border-style: solid;
+  border-width: 0;
+  border-left-width: var(--brand-borderWidth-thin);
+  border-top-width: var(--brand-borderWidth-thin);
+}
+
+.Prose tr:last-child td:not(:global(.custom-component) tr:last-child td) {
+  border-bottom-width: var(--brand-borderWidth-thin);
+}
+
+.Prose tr :is(td, th):last-child:not(:global(.custom-component) tr :is(td, th):last-child) {
+  border-right-width: var(--brand-borderWidth-thin);
+}
+
+.Prose thead th:first-child:not(:global(.custom-component) thead th:first-child) {
+  border-top-left-radius: var(--brand-borderRadius-medium);
+}
+
+.Prose thead th:last-child:not(:global(.custom-component) thead th:last-child) {
+  border-top-right-radius: var(--brand-borderRadius-medium);
+}
+
+.Prose tbody tr:last-child td:last-child:not(:global(.custom-component) tbody tr:last-child td:last-child) {
+  border-bottom-right-radius: var(--brand-borderRadius-medium);
+}
+
+.Prose tbody tr:last-child td:first-child:not(:global(.custom-component) tbody tr:last-child td:first-child) {
+  border-bottom-left-radius: var(--brand-borderRadius-medium);
+}
+
+.Prose table img:not(:global(.custom-component) table img) {
+  background-color: transparent;
+  vertical-align: middle;
+}
+
+/**
+* 11. Custom stuff - Move out to separate stylesheet
 */
 .customPageHero {
   padding-top: 0;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@primer/doctocat-nextjs",
-  "version": "0.2.0",
+  "version": "0.3.0-rc.c313ac3",
   "description": "A Next.js theme for building Primer documentation sites",
   "main": "index.js",
   "type": "module",
@@ -27,7 +27,8 @@
     "nextra": "^4.2.1",
     "react": "18.3.1",
     "react-dom": "18.3.1",
-    "react-focus-on": "3.9.4"
+    "react-focus-on": "3.9.4",
+    "react-live": "^4.1.8"
   },
   "devDependencies": {
     "@github/prettier-config": "^0.0.6",