feat(web): make the top navigation bar sticky

.changeset/sticky-navigation-bar.md

@@ -0,0 +1,5 @@
+---
+'@node-core/doc-kit': minor
+---
+
+Make the web top navigation bar sticky while scrolling, and offset the sticky meta bar, anchor scrolling, and Radix popups so they are not covered by it

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

@@ -62,6 +62,11 @@ export default ({ metadata, headings = [], readingTime }) => {
   return (
     <MetaBar
       heading="Table of Contents"
+      // Offset the sticky position by the sticky navigation bar's height,
+      // otherwise the navigation bar covers the top of the meta bar.
+      // `--header-height` comes from `@node-core/ui-components` base styles;
+      // fall back to its current value (4rem) in case it is ever renamed
+      style={{ top: 'var(--header-height, 4rem)' }}
       headings={{
         items: headings.map(({ value, stability, ...heading }) => ({
           ...heading,

packages/core/src/generators/web/ui/components/NavBar.jsx

@@ -16,23 +16,25 @@ export default ({ metadata }) => {
   const [themePreference, setThemePreference] = useTheme();
 
   return (
-    <NavBar
-      Logo={Logo}
-      sidebarItemTogglerAriaLabel="Toggle navigation menu"
-      navItems={[]}
-    >
-      {showSearchBox && <SearchBox pathname={metadata.path} />}
-      <ThemeToggle
-        onChange={setThemePreference}
-        currentTheme={themePreference}
-      />
-      <a
-        href={`https://github.com/${repository}`}
-        aria-label={`View ${repository} on GitHub`}
-        className={styles.ghIconWrapper}
+    <div className="nav-bar-sticky">
+      <NavBar
+        Logo={Logo}
+        sidebarItemTogglerAriaLabel="Toggle navigation menu"
+        navItems={[]}
       >
-        <GitHubIcon />
-      </a>
-    </NavBar>
+        {showSearchBox && <SearchBox pathname={metadata.path} />}
+        <ThemeToggle
+          onChange={setThemePreference}
+          currentTheme={themePreference}
+        />
+        <a
+          href={`https://github.com/${repository}`}
+          aria-label={`View ${repository} on GitHub`}
+          className={styles.ghIconWrapper}
+        >
+          <GitHubIcon />
+        </a>
+      </NavBar>
+    </div>
   );
 };

packages/core/src/generators/web/ui/index.css

@@ -10,6 +10,28 @@
   --font-ibm-plex-mono: 'IBM Plex Mono', monospace;
 }
 
+/* Keep the top navigation bar visible while scrolling. The hidden sidebar
+   toggler checkbox inside the NavBar is translated above the bar, so clip it:
+   inside this stacking context it would otherwise cover the banner above */
+.nav-bar-sticky {
+  position: sticky;
+  top: 0;
+  z-index: 40;
+  overflow: hidden;
+}
+
+/* Radix popups (theme switcher, selects) must paint above the sticky
+   navigation bar; they render in a portal and slightly overlap the bar.
+   `!important` is needed because Radix sets an inline `z-index: auto` */
+[data-radix-popper-content-wrapper] {
+  z-index: 50 !important;
+}
+
+/* Keep anchored headings below the sticky navigation bar */
+main [id] {
+  scroll-margin-top: calc(var(--header-height, 4rem) + 1rem);
+}
+
 main {
   /* Code should inherit its font size */
   code {