Use GDS components for List, Link, and Code + misc. fixes and improvements (#453)

* Use GDS components for `List`, `Link`, and `Code` + misc. fixes and improvements

* Use released versions of `@edgeandnode/gds` and `@edgeandnode/organisms`

* Comment out `NPSForm` for now

* Remove outdated comment

Author: benface

algolia-crawler.config.js

@@ -19,7 +19,7 @@ new Crawler({
       indexName: 'thegraph-docs',
       pathsToMatch: ['https://thegraph.com/docs/**'],
       recordExtractor: ({ helpers }) => {
-        return helpers.docsearch({
+        const data = helpers.docsearch({
           recordProps: {
             lvl0: {
               selectors: '.graph-docs-current-group',
@@ -34,6 +34,15 @@ new Crawler({
             content: '.graph-docs-content p, .graph-docs-content li',
           },
         })
+        // See https://github.com/algolia/docsearch/issues/1723
+        data.forEach((record) => {
+          Object.entries(record.hierarchy)
+            .filter(([_level, content]) => content)
+            .forEach(([level, content]) => {
+              record.hierarchy[level] = content.replaceAll('&lt;', '<').replaceAll('&gt;', '>').replaceAll('&amp;', '&')
+            })
+        })
+        return data
       },
     },
   ],

package.json

@@ -23,7 +23,7 @@
   },
   "devDependencies": {
     "@edgeandnode/eslint-config": "^1.3.5",
-    "eslint": "^8.45.0",
+    "eslint": "^8.46.0",
     "eslint-plugin-mdx": "^2.1.0",
     "husky": "^8.0.3",
     "lint-staged": "^13.2.3",
@@ -34,7 +34,7 @@
     "remark-lint-heading-increment": "^3.1.2",
     "remark-lint-no-heading-punctuation": "^3.1.2",
     "remark-lint-restrict-elements": "workspace:*",
-    "turbo": "^1.10.9",
+    "turbo": "^1.10.12",
     "typescript": "^5.1.6"
   },
   "lint-staged": {

packages/nextra-theme/package.json

@@ -25,8 +25,8 @@
     "typecheck": "tsc --noEmit"
   },
   "peerDependencies": {
-    "@edgeandnode/gds": "^2.7.0",
-    "@edgeandnode/organisms": "^2.7.0",
+    "@edgeandnode/gds": "^2.8.0",
+    "@edgeandnode/organisms": "^2.9.0",
     "@emotion/react": "^11.10.6",
     "next": "^13.4.5",
     "next-seo": "^5.15.0",
@@ -39,18 +39,17 @@
     "@radix-ui/react-collapsible": "^1.0.3",
     "@radix-ui/react-visually-hidden": "^1.0.3",
     "lodash": "^4.17.21",
-    "prism-react-renderer": "^1.3.5",
     "react-intersection-observer": "^9.5.2",
     "react-use": "^17.4.0"
   },
   "devDependencies": {
-    "@edgeandnode/gds": "^2.7.1",
-    "@edgeandnode/organisms": "^2.8.1",
+    "@edgeandnode/gds": "^2.8.0",
+    "@edgeandnode/organisms": "^2.9.0",
     "@emotion/react": "^11.11.1",
-    "@types/lodash": "^4.14.195",
-    "@types/react": "^18.2.15",
+    "@types/lodash": "^4.14.196",
+    "@types/react": "^18.2.17",
     "@types/react-dom": "^18.2.7",
-    "next": "^13.4.11",
+    "next": "^13.4.12",
     "next-seo": "^6.1.0",
     "nextra": "2.7.1",
     "react": "^18.2.0",

packages/nextra-theme/src/components/Blockquote.tsx

@@ -1,15 +1,19 @@
-import { HTMLAttributes } from 'react'
+import { BlockquoteHTMLAttributes } from 'react'
 
 import { buildBorder, Spacing, Text, TextProps } from '@edgeandnode/gds'
 
-export type BlockquoteProps = Omit<TextProps & HTMLAttributes<HTMLQuoteElement>, 'color'>
+export type BlockquoteProps = Omit<TextProps & BlockquoteHTMLAttributes<HTMLQuoteElement>, 'color'>
 
 export const Blockquote = ({ children, ...props }: BlockquoteProps) => {
   return (
     <Text
       as="blockquote"
       sx={{
         my: Spacing['32px'],
+        '/* emotion-disable-server-rendering-unsafe-selector-warning-please-do-not-use-this-the-warning-exists-for-a-reason */ &:nth-child(1 of :not(style))':
+          { mt: 0 },
+        '/* emotion-disable-server-rendering-unsafe-selector-warning-please-do-not-use-this-the-warning-exists-for-a-reason */ &:nth-last-child(1 of :not(style))':
+          { mb: 0 },
         p: Spacing['24px'],
         borderInlineStart: buildBorder('Purple', '4px'),
         bg: 'Purple8',

packages/nextra-theme/src/components/Code.tsx

@@ -1,78 +1,49 @@
-import Highlight, { defaultProps, Language, PrismTheme } from 'prism-react-renderer'
-import { HTMLAttributes } from 'react'
+import { HTMLAttributes, ReactNode } from 'react'
 
-import { BorderRadius, FontFamily, Spacing } from '@edgeandnode/gds'
+import { Code, Spacing } from '@edgeandnode/gds'
 
-export type CodeBlockProps = HTMLAttributes<HTMLPreElement>
-export type CodeInlineProps = HTMLAttributes<HTMLElement>
-
-import theme from 'prism-react-renderer/themes/duotoneDark'
+export type CodeBlockProps = {
+  children?:
+    | ReactNode
+    | {
+        props: {
+          children: string
+          className?: string
+        }
+      }
+} & Omit<HTMLAttributes<HTMLPreElement>, 'children'>
 
 export const CodeBlock = ({ children, ...props }: CodeBlockProps) => {
-  const data = (
-    children as {
-      props: {
-        children: string
-        className?: string
-      }
-    }
-  ).props
-  const code = data.children.trim()
-  let language = data.className?.substring('language-'.length)
+  const code =
+    children && typeof children === 'object' && 'props' in children
+      ? children.props.children.trim()
+      : (children as string)
+  let language =
+    children && typeof children === 'object' && 'props' in children
+      ? children.props.className?.substring('language-'.length)
+      : null
 
   if (!language || language === 'sh') {
     language = 'bash'
   }
 
   return (
-    <div sx={{ my: Spacing['24px'] }}>
-      <Highlight {...defaultProps} code={code} language={language as Language} theme={theme}>
-        {({ className, tokens, getLineProps, getTokenProps }) => (
-          <pre
-            className={className}
-            sx={{
-              overflowX: 'auto',
-              p: Spacing['16px'],
-              borderRadius: BorderRadius.M,
-              border: 'White4',
-              bg: 'White4',
-              fontFamily: FontFamily.MONOSPACE,
-              fontSize: '16px',
-              lineHeight: '24px',
-            }}
-            {...props}
-          >
-            {tokens.map((line, i) => (
-              // eslint-disable-next-line react/jsx-key
-              <div {...getLineProps({ line, key: i })}>
-                {line.map((token, key) => (
-                  // eslint-disable-next-line react/jsx-key
-                  <span {...getTokenProps({ token, key })} />
-                ))}
-              </div>
-            ))}
-          </pre>
-        )}
-      </Highlight>
-    </div>
-  )
-}
-
-export const CodeInline = ({ children, ...props }: CodeInlineProps) => {
-  return (
-    <code
+    <Code.Block
+      language={language}
       sx={{
-        px: Spacing['4px'],
-        py: Spacing['2px'],
-        borderRadius: BorderRadius.S,
-        border: 'White4',
-        bg: 'White4',
-        fontFamily: FontFamily.MONOSPACE,
-        fontSize: '0.75em',
+        my: Spacing['24px'],
+        '/* emotion-disable-server-rendering-unsafe-selector-warning-please-do-not-use-this-the-warning-exists-for-a-reason */ &:nth-child(1 of :not(style))':
+          { mt: 0 },
+        '/* emotion-disable-server-rendering-unsafe-selector-warning-please-do-not-use-this-the-warning-exists-for-a-reason */ &:nth-last-child(1 of :not(style))':
+          { mb: 0 },
       }}
       {...props}
     >
-      {children}
-    </code>
+      {code}
+    </Code.Block>
   )
 }
+
+export const CodeInline = ({ children, ...props }: HTMLAttributes<HTMLElement>) => {
+  return <Code.Inline {...props}>{children as string}</Code.Inline>
+}

packages/nextra-theme/src/components/DocSearch.tsx

@@ -69,13 +69,7 @@ export function DocSearch(props: DocSearchProps) {
         >
           <Icon.Search size="14px" title="" sx={{ flexShrink: 0 }} />
           <Text.P14 size="14px">{props.translations?.button?.buttonText ?? 'Search'}</Text.P14>
-          {/* TODO: Remove `fontFamily: 'inherit'` when it's included in `@edgeandnode/gds`'s global styles */}
-          <Text.P14
-            as="kbd"
-            size="14px"
-            color="White48"
-            sx={{ marginInlineStart: 'auto', px: Spacing['8px'], fontFamily: 'inherit' }}
-          >
+          <Text.P14 as="kbd" size="14px" color="White48" sx={{ marginInlineStart: 'auto', px: Spacing['8px'] }}>
             <abbr title="Command" sx={{ textDecoration: 'none' }}>
               ⌘
             </abbr>

packages/nextra-theme/src/components/EditPageLink.tsx

@@ -2,8 +2,8 @@ import { HTMLAttributes, useContext } from 'react'
 
 import {
   BorderRadius,
-  buildShadow,
   buildTransition,
+  ButtonOrLink,
   Flex,
   Icon,
   Opacity,
@@ -12,7 +12,6 @@ import {
   useI18n,
 } from '@edgeandnode/gds'
 
-import { Link } from '@/components'
 import { NavContext } from '@/layout/NavContext'
 
 export type EditPageLinkProps = {
@@ -31,14 +30,14 @@ export const EditPageLink = ({ mobile = false, ...props }: EditPageLinkProps) =>
         ['en', '[locale]'].includes(fileLocale) ? fileLocale : 'en'
       }/${filePathSegments.join('/')}`
   return (
-    <Link
+    <ButtonOrLink
       href={path}
       target="_blank"
       sx={{
         display: 'block',
         py: Spacing['4px'],
         borderRadius: BorderRadius.S,
-        '&:hover': { color: 'White', textShadow: buildShadow('M') },
+        '&:hover': { color: 'White' },
         transition: buildTransition(),
       }}
       {...props}
@@ -56,6 +55,6 @@ export const EditPageLink = ({ mobile = false, ...props }: EditPageLinkProps) =>
           }}
         />
       </Flex.Row>
-    </Link>
+    </ButtonOrLink>
   )
 }

packages/nextra-theme/src/components/Heading.tsx

@@ -3,7 +3,7 @@ import { HTMLAttributes, useContext } from 'react'
 import { useInView } from 'react-intersection-observer'
 import { useDebounce } from 'react-use'
 
-import { buildShadow, buildTransition, Opacity, Spacing, Text, TextProps, useI18n } from '@edgeandnode/gds'
+import { buildTransition, Opacity, Spacing, Text, TextProps, useI18n } from '@edgeandnode/gds'
 
 import { LinkInline } from '@/components'
 import { DocumentContext } from '@/layout/DocumentContext'
@@ -12,8 +12,6 @@ export type HeadingProps = TextProps & {
   level: 1 | 2 | 3 | 4 | 5 | 6
 } & HTMLAttributes<HTMLHeadingElement>
 
-export type HeadingSpecificProps = Omit<HeadingProps, 'level' | 'color'>
-
 const BaseHeading = ({ level, id, children, ...props }: HeadingProps) => {
   const { markOutlineItem } = useContext(DocumentContext)!
   const { ref, inView: inOrAboveView } = useInView({
@@ -31,8 +29,8 @@ const BaseHeading = ({ level, id, children, ...props }: HeadingProps) => {
   const { t } = useI18n<any>()
 
   return (
-    <Text ref={ref} as={`h${level}`} id={id} weight="SEMIBOLD" color="White" sx={{ whiteSpace: 'nowrap' }} {...props}>
-      <span sx={{ whiteSpace: 'normal' }}>{children}</span>
+    <Text ref={ref} as={`h${level}`} id={id} weight="SEMIBOLD" color="White" {...props}>
+      {children}
       {id ? (
         <span
           sx={{
@@ -42,6 +40,8 @@ const BaseHeading = ({ level, id, children, ...props }: HeadingProps) => {
             transition: buildTransition('OPACITY'),
           }}
         >
+          {/* Non-breaking invisible space, to prevent a line break between the `#` and the previous word */}
+          &#8288;
           <LinkInline href={`#${id}`}>
             <span aria-hidden="true">#</span>
             <VisuallyHidden.Root>{t('global.linkToThisSection')}</VisuallyHidden.Root>
@@ -52,8 +52,10 @@ const BaseHeading = ({ level, id, children, ...props }: HeadingProps) => {
   )
 }
 
+export type HeadingSpecificProps = Omit<HeadingProps, 'level' | 'color'>
+
 const H1 = (props: HeadingSpecificProps) => {
-  return <BaseHeading level={1} size="48px" sx={{ mb: Spacing['16px'], textShadow: buildShadow('L') }} {...props} />
+  return <BaseHeading level={1} size="48px" sx={{ mb: Spacing['16px'] }} {...props} />
 }
 
 const H2 = (props: HeadingSpecificProps) => {
@@ -64,55 +66,26 @@ const H2 = (props: HeadingSpecificProps) => {
       sx={{
         mt: Spacing['48px'],
         mb: Spacing['24px'],
-        textShadow: buildShadow('M'),
       }}
       {...props}
     />
   )
 }
 
 const H3 = (props: HeadingSpecificProps) => {
-  return (
-    <BaseHeading
-      level={3}
-      size="24px"
-      sx={{ mt: Spacing['32px'], mb: Spacing['24px'], textShadow: buildShadow('M') }}
-      {...props}
-    />
-  )
+  return <BaseHeading level={3} size="24px" sx={{ mt: Spacing['32px'], mb: Spacing['24px'] }} {...props} />
 }
 
 const H4 = (props: HeadingSpecificProps) => {
-  return (
-    <BaseHeading
-      level={4}
-      size="20px"
-      sx={{ mt: Spacing['32px'], mb: Spacing['16px'], textShadow: buildShadow('S') }}
-      {...props}
-    />
-  )
+  return <BaseHeading level={4} size="20px" sx={{ mt: Spacing['32px'], mb: Spacing['16px'] }} {...props} />
 }
 
 const H5 = (props: HeadingSpecificProps) => {
-  return (
-    <BaseHeading
-      level={5}
-      size="18px"
-      sx={{ mt: Spacing['32px'], mb: Spacing['16px'], textShadow: buildShadow('S') }}
-      {...props}
-    />
-  )
+  return <BaseHeading level={5} size="18px" sx={{ mt: Spacing['32px'], mb: Spacing['16px'] }} {...props} />
 }
 
 const H6 = (props: HeadingSpecificProps) => {
-  return (
-    <BaseHeading
-      level={6}
-      size="16px"
-      sx={{ mt: Spacing['32px'], mb: Spacing['16px'], textShadow: buildShadow('S') }}
-      {...props}
-    />
-  )
+  return <BaseHeading level={6} size="16px" sx={{ mt: Spacing['32px'], mb: Spacing['16px'] }} {...props} />
 }
 
 const Heading = Object.assign({}, BaseHeading, {