feat(web): add scroll-spy active indicator to TOC

src/generators/web/ui/components/MetaBar/index.jsx

@@ -1,9 +1,12 @@
+/* eslint-disable react-x/no-use-context, react-x/no-context-provider -- preact/compat does not export `use`, so React 19 patterns are unavailable at runtime */
 import { CodeBracketIcon, DocumentIcon } from '@heroicons/react/24/outline';
 import Badge from '@node-core/ui-components/Common/Badge';
 import MetaBar from '@node-core/ui-components/Containers/MetaBar';
 import GitHubIcon from '@node-core/ui-components/Icons/Social/GitHub';
+import { createContext, useContext } from 'react';
 
 import styles from './index.module.css';
+import { useScrollSpy } from '../../hooks/useScrollSpy.mjs';
 
 const iconMap = {
   JSON: CodeBracketIcon,
@@ -23,6 +26,8 @@ const STABILITY_KINDS = ['error', 'warning', null, 'info'];
 const STABILITY_LABELS = ['D', 'E', null, 'L'];
 const STABILITY_TOOLTIPS = ['Deprecated', 'Experimental', null, 'Legacy'];
 
+const ActiveSlugContext = createContext(null);
+
 /**
  * Renders a heading value with an optional stability badge
  * @param {{ value: string, stability: number }} props
@@ -54,6 +59,25 @@ const HeadingValue = ({ value, stability }) => {
   );
 };
 
+/**
+ * Anchor element that highlights itself when it matches the active TOC slug.
+ * @param {{ href: string, className?: string }} props
+ */
+const ActiveLink = ({ href, className, ...props }) => {
+  const activeSlug = useContext(ActiveSlugContext);
+
+  return (
+    <a
+      href={href}
+      aria-current={href === `#${activeSlug}` ? 'true' : undefined}
+      className={[className, href === `#${activeSlug}` ? styles.tocActive : '']
+        .filter(Boolean)
+        .join(' ')}
+      {...props}
+    />
+  );
+};
+
 /**
  * MetaBar component that displays table of contents and page metadata
  * @param {MetaBarProps} props - Component props
@@ -64,42 +88,49 @@ export default ({
   readingTime,
   viewAs = [],
   editThisPage,
-}) => (
-  <MetaBar
-    heading="Table of Contents"
-    headings={{
-      items: headings.map(({ value, stability, ...heading }) => ({
-        ...heading,
-        value: <HeadingValue value={value} stability={stability} />,
-      })),
-    }}
-    items={{
-      'Reading Time': readingTime,
-      'Added In': addedIn,
-      'View As': (
-        <ol>
-          {viewAs.map(([title, path]) => {
-            const Icon = iconMap[title];
-
-            return (
-              <li key={title}>
-                <a href={path}>
-                  {Icon && <Icon className={styles.icon} />}
-
-                  {title}
-                </a>
-              </li>
-            );
-          })}
-        </ol>
-      ),
-      Contribute: (
-        <>
-          <GitHubIcon className="fill-neutral-700 dark:fill-neutral-100" />
-
-          <a href={editThisPage}>Edit this page</a>
-        </>
-      ),
-    }}
-  />
-);
+}) => {
+  const activeSlug = useScrollSpy(headings);
+
+  return (
+    <ActiveSlugContext.Provider value={activeSlug}>
+      <MetaBar
+        heading="Table of Contents"
+        as={ActiveLink}
+        headings={{
+          items: headings.map(({ value, stability, ...heading }) => ({
+            ...heading,
+            value: <HeadingValue value={value} stability={stability} />,
+          })),
+        }}
+        items={{
+          'Reading Time': readingTime,
+          'Added In': addedIn,
+          'View As': (
+            <ol>
+              {viewAs.map(([title, path]) => {
+                const Icon = iconMap[title];
+
+                return (
+                  <li key={title}>
+                    <a href={path}>
+                      {Icon && <Icon className={styles.icon} />}
+
+                      {title}
+                    </a>
+                  </li>
+                );
+              })}
+            </ol>
+          ),
+          Contribute: (
+            <>
+              <GitHubIcon className="fill-neutral-700 dark:fill-neutral-100" />
+
+              <a href={editThisPage}>Edit this page</a>
+            </>
+          ),
+        }}
+      />
+    </ActiveSlugContext.Provider>
+  );
+};

src/generators/web/ui/components/MetaBar/index.module.css

@@ -9,3 +9,10 @@
   display: inline-block;
   margin-left: 0.25rem;
 }
+
+.tocActive {
+  color: var(--color-primary, #0078d4);
+  font-weight: 600;
+  border-left: 2px solid var(--color-primary, #0078d4);
+  padding-left: 0.25rem;
+}

src/generators/web/ui/hooks/__tests__/useScrollSpy.test.mjs

@@ -0,0 +1,38 @@
+import { strictEqual } from 'node:assert';
+import { describe, it } from 'node:test';
+
+import { getActiveSlug } from '../useScrollSpy.mjs';
+
+describe('getActiveSlug', () => {
+  it('should return null for an empty entries array', () => {
+    strictEqual(getActiveSlug([]), null);
+  });
+
+  it('should return null when no entry is intersecting', () => {
+    const entries = [
+      { isIntersecting: false, target: { id: 'intro' } },
+      { isIntersecting: false, target: { id: 'usage' } },
+    ];
+
+    strictEqual(getActiveSlug(entries), null);
+  });
+
+  it('should return the id of the first intersecting entry', () => {
+    const entries = [
+      { isIntersecting: false, target: { id: 'intro' } },
+      { isIntersecting: true, target: { id: 'usage' } },
+      { isIntersecting: true, target: { id: 'api' } },
+    ];
+
+    strictEqual(getActiveSlug(entries), 'usage');
+  });
+
+  it('should return the id when only one entry is intersecting', () => {
+    const entries = [
+      { isIntersecting: false, target: { id: 'intro' } },
+      { isIntersecting: true, target: { id: 'config' } },
+    ];
+
+    strictEqual(getActiveSlug(entries), 'config');
+  });
+});

src/generators/web/ui/hooks/useScrollSpy.mjs

@@ -0,0 +1,49 @@
+import { useState, useEffect } from 'react';
+
+/**
+ * Determines the active heading slug from IntersectionObserver entries.
+ * Exported as a named function to allow unit testing without a DOM environment.
+ *
+ * @param {IntersectionObserverEntry[]} entries
+ * @returns {string | null}
+ */
+export const getActiveSlug = entries => {
+  const visible = entries.find(e => e.isIntersecting);
+
+  return visible ? visible.target.id : null;
+};
+
+/**
+ * Tracks which heading is currently visible in the viewport using IntersectionObserver.
+ *
+ * @param {Array<{ slug: string }>} headings
+ * @returns {string | null} The slug of the active heading
+ */
+export const useScrollSpy = headings => {
+  const [activeSlug, setActiveSlug] = useState(null);
+
+  useEffect(() => {
+    const observer = new IntersectionObserver(
+      entries => {
+        const slug = getActiveSlug(entries);
+
+        if (slug !== null) {
+          setActiveSlug(slug);
+        }
+      },
+      { rootMargin: '0px 0px -70% 0px', threshold: 0 }
+    );
+
+    headings.forEach(({ slug }) => {
+      const el = document.getElementById(slug);
+
+      if (el) {
+        observer.observe(el);
+      }
+    });
+
+    return () => observer.disconnect();
+  }, [headings]);
+
+  return activeSlug;
+};