@primer/doctocat-nextjs 0.2.0-rc.eeac884 → 0.3.0-rc.0fe5c68

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) => {