feat(www): useActiveHash hook for highlighting links in Docs' table of contents

www/src/components/docs-table-of-contents.js

@@ -1,7 +1,33 @@
 /** @jsx jsx */
 import { jsx } from "theme-ui"
 import { Link } from "gatsby"
-import { colors, mediaQueries } from "gatsby-design-tokens/dist/theme-gatsbyjs-org"
+import {
+  mediaQueries,
+  breakpoints,
+} from "gatsby-design-tokens/dist/theme-gatsbyjs-org"
+import { useEffect, useState } from "react"
+import { useActiveHash } from "../hooks/use-active-hash"
+
+const getHeadingIds = (toc, traverseFullDepth = false) => {
+  const idList = []
+  const hashToId = str => str.slice(1)
+
+  if (toc) {
+    for (const item of toc) {
+      // Sometimes url does not exist on item. See #19851
+      if (item.url) {
+        idList.push(hashToId(item.url))
+      }
+
+      // Only traverse sub-items if specified (they are not displayed in ToC)
+      if (item.items && traverseFullDepth) {
+        idList.push(...getHeadingIds(item.items, true))
+      }
+    }
+  }
+
+  return idList
+}
 
 function isUnderDepthLimit(depth, maxDepth) {
   if (maxDepth === null) {
@@ -14,54 +40,71 @@ function isUnderDepthLimit(depth, maxDepth) {
 
 // depth and maxDepth are used to figure out how many bullets deep to render in the ToC sidebar, if no
 // max depth is set via the tableOfContentsDepth field in the frontmatter, all headings will be rendered
-function createItems(items, location, depth, maxDepth) {
+function createItems(items, location, depth, maxDepth, activeHash, isDesktop) {
   return (
     items &&
-    items.map((item, index) => (
-      <li
-        sx={{ [mediaQueries.xl]: { fontSize: 1 } }}
-        key={location.pathname + (item.url || depth + `-` + index)}
-      >
-        {item.url && (
-          <Link
-            sx={{
-              "&&": {
-                color: `textMuted`,
-                border: 0,
-                transition: t =>
-                  `all ${t.transition.speed.fast} ${t.transition.curve.default}`,
-                ":hover": {
-                  color: `link.color`,
-                  borderBottom: t => `1px solid ${t.colors.link.hoverBorder}`,
+    items.map((item, index) => {
+      const isActive = isDesktop && item.url === `#${activeHash}`
+      return (
+        <li
+          sx={{ [mediaQueries.xl]: { fontSize: 1 } }}
+          key={location.pathname + (item.url || depth + `-` + index)}
+        >
+          {item.url && (
+            <Link
+              sx={{
+                "&&": {
+                  color: isActive ? `link.color` : `textMuted`,
+                  border: 0,
+                  borderBottom: t =>
+                    isActive
+                      ? `1px solid ${t.colors.link.hoverBorder}`
+                      : `none`,
+                  transition: t =>
+                    `all ${t.transition.speed.fast} ${t.transition.curve.default}`,
+                  ":hover": {
+                    color: `link.color`,
+                    borderBottom: t => `1px solid ${t.colors.link.hoverBorder}`,
+                  },
                 },
-              },
-            }}
-            getProps={({ href, location }) =>
-              location && location.href && location.href.includes(href)
-                ? {
-                    style: {
-                      color: colors.link.color,
-                      borderBottom: `1px solid ${colors.link.hoverBorder}`,
-                    },
-                  }
-                : null
-            }
-            to={location.pathname + item.url}
-          >
-            {item.title}
-          </Link>
-        )}
-        {item.items && isUnderDepthLimit(depth, maxDepth) && (
-          <ul sx={{ color: `textMuted`, listStyle: `none`, ml: 5 }}>
-            {createItems(item.items, location, depth + 1, maxDepth)}
-          </ul>
-        )}
-      </li>
-    ))
+              }}
+              to={location.pathname + item.url}
+            >
+              {item.title}
+            </Link>
+          )}
+          {item.items && isUnderDepthLimit(depth, maxDepth) && (
+            <ul sx={{ color: `textMuted`, listStyle: `none`, ml: 5 }}>
+              {createItems(
+                item.items,
+                location,
+                depth + 1,
+                maxDepth,
+                activeHash,
+                isDesktop
+              )}
+            </ul>
+          )}
+        </li>
+      )
+    })
   )
 }
 
-function TableOfContents({ page, location }) {
+function TableOfContents({ page, toc, location }) {
+  const [isDesktop, setIsDesktop] = useState(false)
+  const activeHash = useActiveHash(getHeadingIds(toc))
+
+  useEffect(() => {
+    const isDesktopQuery = window.matchMedia(`(min-width: ${breakpoints[4]})`) // 1200px
+
+    setIsDesktop(isDesktopQuery.matches)
+
+    const updateIsDesktop = e => setIsDesktop(e.matches)
+    isDesktopQuery.addListener(updateIsDesktop)
+    return () => isDesktopQuery.removeListener(updateIsDesktop)
+  }, [])
+
   return page.tableOfContents.items ? (
     <nav
       sx={{
@@ -98,7 +141,9 @@ function TableOfContents({ page, location }) {
           page.tableOfContents.items,
           location,
           1,
-          page.frontmatter.tableOfContentsDepth
+          page.frontmatter.tableOfContentsDepth,
+          activeHash,
+          isDesktop
         )}
       </ul>
     </nav>

www/src/hooks/use-active-hash.js

@@ -0,0 +1,30 @@
+import { useEffect, useState } from "react"
+
+export const useActiveHash = (itemIds, rootMargin = undefined) => {
+  const [activeHash, setActiveHash] = useState(``)
+
+  useEffect(() => {
+    const observer = new IntersectionObserver(
+      entries => {
+        entries.forEach(entry => {
+          if (entry.isIntersecting) {
+            setActiveHash(entry.target.id)
+          }
+        })
+      },
+      { rootMargin: rootMargin || `0% 0% -80% 0%` }
+    )
+
+    itemIds.forEach(id => {
+      observer.observe(document.getElementById(id))
+    })
+
+    return () => {
+      itemIds.forEach(id => {
+        observer.unobserve(document.getElementById(id))
+      })
+    }
+  }, [])
+
+  return activeHash
+}

www/src/templates/template-docs-markdown.js

@@ -96,7 +96,7 @@ function DocsTemplate({ data, location, pageContext: { next, prev } }) {
                 },
               }}
             >
-              <TableOfContents location={location} page={page} />
+              <TableOfContents toc={toc} location={location} page={page} />
             </div>
           )}
           <div