Fixes and improvements (thanks AK for the feedback!)

Author: benface

package.json

@@ -2,7 +2,7 @@
   "name": "graph-docs",
   "private": true,
   "version": "1.0.0",
-  "packageManager": "pnpm@10.2.1",
+  "packageManager": "pnpm@10.3.0",
   "scripts": {
     "dev": "turbo run dev",
     "build": "NODE_OPTIONS='--max_old_space_size=4096' turbo run build",
@@ -30,7 +30,7 @@
     "remark-lint-heading-increment": "^4.0.1",
     "remark-lint-no-heading-punctuation": "^4.0.1",
     "remark-lint-restrict-elements": "workspace:*",
-    "turbo": "^2.4.0",
+    "turbo": "^2.4.1",
     "typescript": "^5.7.3"
   },
   "resolutions": {

pnpm-lock.yaml

@@ -17,15 +17,15 @@
   "dependencies": {
     "@docsearch/react": "^3.8.3",
     "@edgeandnode/common": "^6.51.0",
-    "@edgeandnode/gds": "6.3.0-for-docs-1738980344062-6f60ec89903dd9f5d85ba069d3cdaa620c4e4c74",
-    "@edgeandnode/go": "8.9.0-for-docs-1738980344062-6f60ec89903dd9f5d85ba069d3cdaa620c4e4c74",
+    "@edgeandnode/gds": "6.3.0-for-docs-1739233638767-5000c1abd82fa2fa01effd5029f0eb2992db1b86",
+    "@edgeandnode/go": "8.9.0-for-docs-1739233638767-5000c1abd82fa2fa01effd5029f0eb2992db1b86",
     "@emotion/react": "^11.14.0",
     "@graphprotocol/contracts": "6.2.1",
     "@pinax/graph-networks-registry": "^0.6.7",
     "lodash": "^4.17.21",
     "mixpanel-browser": "^2.60.0",
-    "motion": "^12.4.1",
-    "next": "^14.2.23",
+    "motion": "^12.4.2",
+    "next": "^14.2.24",
     "next-seo": "^6.6.0",
     "next-sitemap": "^4.2.3",
     "nextra": "^3.3.1",
@@ -47,7 +47,7 @@
     "@types/react-dom": "^18.3.5",
     "autoprefixer": "^10.4.20",
     "fast-xml-parser": "^4.5.1",
-    "postcss": "^8.5.1",
+    "postcss": "^8.5.2",
     "tailwindcss": "^3.4.17",
     "tsup": "^8.3.6",
     "tsx": "^4.19.2"

website/package.json

@@ -16,7 +16,7 @@ export default function HomePage() {
   return (
     <>
       <div className="graph-docs-not-markdown grid grid-cols-subgrid">
-        <div className="absolute inset-x-0 -top-8 flex h-90 justify-center">
+        <div className="pointer-events-none absolute inset-x-0 -top-8 flex h-72 justify-center xs:h-90">
           <img alt="" src={`${process.env.BASE_PATH}/img/home-bg.svg`} className="h-full max-w-none" />
         </div>
         <div className="col-[container] py-20 xs:py-30">
@@ -25,7 +25,7 @@ export default function HomePage() {
               {t('index.hero.title')}
             </h1>
             <p className="mt-2">{t('index.hero.description')}</p>
-            <ExperimentalButtonGroup className="mt-4">
+            <ExperimentalButtonGroup className="mt-4 prop-orientation-vertical xs:prop-orientation-horizontal">
               <ExperimentalButton href="/about">{t('index.hero.cta1')}</ExperimentalButton>
               <ExperimentalButton href="/subgraphs/quick-start">{t('index.hero.cta2')}</ExperimentalButton>
             </ExperimentalButtonGroup>

website/src/HomePage.tsx

@@ -14,6 +14,7 @@ import {
   type ReactNode,
   useContext,
   useEffect,
+  useLayoutEffect,
   useState,
 } from 'react'
 import { useSet } from 'react-use'
@@ -33,7 +34,6 @@ import {
   BookOpenText,
   Files,
   House,
-  List,
   MagnifyingGlass,
   RoleIndexer,
   SidebarSimple,
@@ -43,7 +43,6 @@ import {
   Substreams,
   SubstreamsPoweredSubgraph,
   TheGraph,
-  X,
 } from '@edgeandnode/gds/icons'
 
 import {
@@ -104,11 +103,20 @@ export default function Layout({ pageOpts, children }: NextraThemeLayoutProps<Fr
   const [sidebarExpandedOnDesktop, setSidebarExpandedOnDesktop] = useState(true)
 
   // Collapse the sidebar on mobile when the route changes
-  // TODO: Also collapse it when clicking outside the sidebar
   useEffect(() => {
     setSidebarExpandedOnMobile(false)
   }, [router.pathname])
 
+  // TODO: Create `useTailwindScreen` hook in GDS, with usage like `const screen = useTailwindScreen()` and then you can check `screen.md`, etc.
+  const [mobile, setMobile] = useState(false)
+  useLayoutEffect(() => {
+    const mediaQueryList = matchMedia('(min-width: 768px)')
+    setMobile(!mediaQueryList.matches)
+    const onChange = (event: MediaQueryListEvent) => setMobile(!event.matches)
+    mediaQueryList.addEventListener('change', onChange)
+    return () => mediaQueryList.removeEventListener('change', onChange)
+  }, [])
+
   const normalizedPages = normalizePages({
     list: pageMap,
     route: fsPath,
@@ -297,93 +305,80 @@ export default function Layout({ pageOpts, children }: NextraThemeLayoutProps<Fr
 
       <div
         className={`
-          isolate overflow-x-clip
+          isolate
           [--graph-docs-content-padding-bottom:theme(spacing.12)]
           [--graph-docs-content-padding-top:theme(spacing.12)]
           [--graph-docs-content-padding:theme(spacing.6)]
-          [--graph-docs-header-height:theme(spacing.14)]
+          [--graph-docs-header-height:theme(spacing.16)]
           [--graph-docs-header-padding:theme(spacing.4)]
           [--graph-docs-layout-transition-duration:300ms]
           [--graph-docs-sidebar-width:theme(spacing.64)]
           [--graph-docs-toc-width:theme(spacing.66)]
-          xs:[--graph-docs-header-height:theme(spacing.16)]
-          xs:[--graph-docs-header-padding:theme(spacing.6)]
           md:[--graph-docs-content-padding-bottom:theme(spacing.16)]
           md:[--graph-docs-content-padding:theme(spacing.16)]
+          md:[--graph-docs-header-padding:theme(spacing.6)]
         `}
       >
         <header
           className={`
-            sticky top-0 z-10 grid h-[var(--graph-docs-header-height)] grid-cols-[1fr_auto_1fr] border-b border-white/8 bg-background
+            sticky top-0 z-10 grid h-[var(--graph-docs-header-height)] grid-cols-[1fr_auto_1fr] items-center border-b border-white/8 bg-background
             md:grid-cols-[var(--graph-docs-sidebar-width),auto]
           `}
         >
-          <div className="flex items-center px-[var(--graph-docs-header-padding)] md:hidden">
-            {/* TODO: Use tertiary `ExperimentalButton` after new design is implemented */}
-            <button
-              type="button"
-              data-sidebar-expanded={sidebarExpandedOnMobile || undefined}
-              className={`
-                flex size-8 items-center justify-center text-white/88 transition
-                hocus-visible:text-white
-                active:text-white/64
-                active:transition-none
-              `}
-              onClick={() => {
-                setSidebarExpandedOnMobile((expanded) => !expanded)
-              }}
-            >
-              <List
-                alt={t('global.navigation.show')}
-                variant="regular"
-                className="prop-size-5 in-clickable-[[data-sidebar-expanded]]:hidden xs:prop-size-6"
-              />
-              <X
-                alt={t('global.navigation.hide')}
-                className="prop-size-5 in-clickable-not-[[data-sidebar-expanded]]:hidden xs:prop-size-6"
-              />
-            </button>
-          </div>
-          <div className="flex items-center justify-center md:ps-[var(--graph-docs-header-padding)]">
-            <ButtonOrLink href="https://thegraph.com" className="outline-offset-2">
+          <div className="contents md:flex md:items-center md:justify-center md:ps-[var(--graph-docs-header-padding)]">
+            <ButtonOrLink href="https://thegraph.com" className="outline-offset-2 md:-ms-1.5">
               <span className="absolute -inset-2" />
-              <TheGraph className="prop-size-6 xs:prop-size-7" />
+              <TheGraph size={7} />
             </ButtonOrLink>
-            <div className="me-4.5 ms-3.5 h-7 w-px shrink-0 bg-white/8 xs:h-9" />
-            <div className="text-body-small me-auto text-text xs:text-body-large">Docs</div>
+            <div className="me-auto hidden md:flex md:items-center">
+              <div className="me-4.5 ms-3.5 h-9 w-px shrink-0 bg-white/8" />
+              <div className="text-body-large text-text">Docs</div>
+            </div>
             {/* TODO: Use naked `ExperimentalButton` after new design is implemented */}
-            <button
-              type="button"
-              data-sidebar-expanded={sidebarExpandedOnDesktop || undefined}
-              className={`
-                hidden size-8 items-center justify-center text-white/88 transition
-                hocus-visible:text-white
-                active:text-white/64
-                active:transition-none
-                md:flex
-              `}
-              onClick={() => {
-                if (!sidebarExpandedOnDesktop) {
-                  setSidebarExpandedOnDesktop(true)
-                } else {
-                  setSidebarExpandedOnDesktop(false)
-                  setSidebarExpandedOnMobile(false)
-                }
-              }}
-            >
-              <SidebarSimple
-                alt={t('global.navigation.show')}
-                variant="regular"
-                size={6}
-                className="in-clickable-[[data-sidebar-expanded]]:hidden"
-              />
-              <SidebarSimple
-                alt={t('global.navigation.hide')}
-                variant="fill"
-                size={6}
-                className="in-clickable-not-[[data-sidebar-expanded]]:hidden"
-              />
-            </button>
+            <div className="order-first px-[var(--graph-docs-header-padding)] md:order-none md:px-0">
+              <button
+                type="button"
+                data-sidebar-expanded-on-mobile={sidebarExpandedOnMobile || undefined}
+                data-sidebar-expanded-on-desktop={sidebarExpandedOnDesktop || undefined}
+                className={`
+                  flex size-8 items-center justify-center text-white/88 transition
+                  hocus-visible:text-white
+                  active:text-white/64
+                  active:transition-none
+                `}
+                onClick={() => {
+                  if (mobile) {
+                    setSidebarExpandedOnMobile((expanded) => !expanded)
+                  } else {
+                    if (!sidebarExpandedOnDesktop) {
+                      setSidebarExpandedOnDesktop(true)
+                    } else {
+                      setSidebarExpandedOnDesktop(false)
+                      setSidebarExpandedOnMobile(false)
+                    }
+                  }
+                }}
+              >
+                <SidebarSimple
+                  alt={t('global.navigation.show')}
+                  variant="regular"
+                  size={6}
+                  className={`
+                    max-md:in-clickable-[[data-sidebar-expanded-on-mobile]]:hidden
+                    md:in-clickable-[[data-sidebar-expanded-on-desktop]]:hidden
+                  `}
+                />
+                <SidebarSimple
+                  alt={t('global.navigation.hide')}
+                  variant="fill"
+                  size={6}
+                  className={`
+                    max-md:in-clickable-not-[[data-sidebar-expanded-on-mobile]]:hidden
+                    md:in-clickable-not-[[data-sidebar-expanded-on-desktop]]:hidden
+                  `}
+                />
+              </button>
+            </div>
             <div className="ms-3.5 hidden h-9 w-px shrink-0 bg-white/8 md:block" />
           </div>
           <div className="flex items-center gap-4 px-[var(--graph-docs-header-padding)]">
@@ -441,6 +436,7 @@ export default function Layout({ pageOpts, children }: NextraThemeLayoutProps<Fr
                 </button>
               )}
             </DocSearch>
+            {/* TODO: Implement new design */}
             <ExperimentalLocaleSwitcher className="prop-display-format-short lg:prop-display-format-full" />
             {/* TODO: Fix app launcher */}
             {/* <ExperimentalAppLauncher /> */}
@@ -457,6 +453,16 @@ export default function Layout({ pageOpts, children }: NextraThemeLayoutProps<Fr
             md:data-[sidebar-expanded-on-desktop]:grid-cols-[var(--graph-docs-sidebar-width),auto]
           `}
         >
+          <div
+            onClick={() => setSidebarExpandedOnMobile(false)}
+            className={`
+              pointer-events-none absolute inset-0 z-10 hidden bg-background/64 opacity-0
+              transition-[opacity,display] duration-[var(--graph-docs-layout-transition-duration)] transition-allow-discrete +:starting:opacity-0
+              max-md:group-data-[sidebar-expanded-on-mobile]/layout-sidebar-grid:pointer-events-auto
+              max-md:group-data-[sidebar-expanded-on-mobile]/layout-sidebar-grid:block
+              max-md:group-data-[sidebar-expanded-on-mobile]/layout-sidebar-grid:opacity-100
+            `}
+          />
           <div className="sticky top-[var(--graph-docs-header-height)] z-10 h-[calc(100vh-var(--graph-docs-header-height))]">
             <nav
               aria-label={t('global.navigation.title')}
@@ -604,7 +610,7 @@ function MDXContent({ toc: headings, children }: ComponentPropsWithoutRef<Nextra
       <main
         data-hide-table-of-contents={frontMatter.hideTableOfContents || undefined}
         className={`
-          group/layout-toc-grid grid grid-cols-[auto,0]
+          group/layout-toc-grid grid grid-cols-[auto,0] overflow-x-clip
           transition-[grid-template-columns]
           duration-[var(--graph-docs-layout-transition-duration)]
           xl:not-data-[hide-table-of-contents]:grid-cols-[auto,var(--graph-docs-toc-width)]
@@ -683,6 +689,7 @@ function MDXContent({ toc: headings, children }: ComponentPropsWithoutRef<Nextra
               mdx-[hr]:bg-white/8
               mdx-[li]:ps-1.5
               mdx-[ul,ol]:ps-5
+              mdx-[b,strong]:font-medium
               mdx-[b,strong]:text-white
               mdx-[h2,h3,h4,h5,h6]:text-white
               mdx-[ul>li]:after:absolute

website/src/Layout.tsx

@@ -55,10 +55,12 @@ export const Card = ({
       ])}
       {...props}
     >
-      <div className="flex h-full flex-col gap-6 nested-icon:default-size-6">
-        {icon && iconPosition === 'top' ? <div className="shrink-0 grow-[9999]">{icon}</div> : null}
+      <div className="flex h-full flex-col gap-6">
+        {icon && iconPosition === 'top' ? (
+          <div className="shrink-0 grow-[9999] nested-icon:default-size-6">{icon}</div>
+        ) : null}
         <div className="flex grow gap-4">
-          {icon && iconPosition === 'side' ? <div className="shrink-0">{icon}</div> : null}
+          {icon && iconPosition === 'side' ? <div className="shrink-0 nested-icon:default-size-6">{icon}</div> : null}
           <div className="flex flex-col gap-1">
             {slotAboveTitle}
             <h3 className="text-body-small font-medium text-white/88">{title}</h3>

website/src/components/Card.tsx

@@ -194,7 +194,7 @@ export function DocSearch({ children, ...props }: DocSearchProps) {
               },
               '.DocSearch-Hit-title': {
                 fontSize: FontSize['16px'],
-                fontWeight: FontWeight.SEMIBOLD,
+                fontWeight: FontWeight.MEDIUM,
                 overflow: 'hidden',
                 textOverflow: 'ellipsis',
               },

website/src/components/DocSearch.tsx

@@ -39,13 +39,14 @@ export const Link = forwardRef(
           {...(props.href === undefined ? { asSpan: true } : {})}
           className={`
             group/link -mx-1 whitespace-nowrap rounded-4 border border-transparent box-decoration-clone px-1 py-0.5 text-[#4c9eff] outline-none transition
-            hover:text-[#70b1ff]
+            hocus-visible:text-[#70b1ff]
             focus-visible:border-current
             active:text-[#3f80d1]
             active:transition-none
             +:disabled:text-white/48
             nested-icon:top-[0.075em]
             nested-icon:inline-block
+            +:nested-icon:default-size-[1em] ${/* This is the default, but it prevents an ancestor from overriding it accidentally */ ''}
           `}
           {...props}
         >

website/src/components/Link.tsx

@@ -23,7 +23,7 @@ export const Table = ({ className, children, ...props }: TableProps) => {
           nested-[th,td]:px-4
           nested-[th,td]:py-3
           nested-[th]:text-center
-          nested-[th]:font-semibold
+          nested-[th]:font-medium
         `}
         {...props}
       >