From 3e9b6cd8d736c7786102837bb3d3a4c784c1191b Mon Sep 17 00:00:00 2001
From: sarah <129242944+sarah-inkeep@users.noreply.github.com>
Date: Mon, 29 Jun 2026 17:23:00 -0700
Subject: [PATCH] Fix mobile nav scroll lock left stranded on resize to desktop
 (#2270)

* fix(docs): release mobile nav scroll lock on resize

The marketing site mobile nav locked body scroll on open and only released
it when the menu closed via a state change. Widening the window past the md
breakpoint hid the menu via CSS without closing it, so the scroll lock was
stranded and the desktop page became unscrollable.

Rebuild the menu on the shadcn Sheet (Radix Dialog), which owns the focus
trap, Escape handling, and body scroll lock and releases all three on close.
Add a matchMedia listener that closes the sheet when crossing into desktop
width. Present it as a bottom drawer with an icon and label on every row and
a content-aligned close button.

* fix(docs): contain overscroll on mobile nav drawer

Add overscroll-contain to the Sheet drawer's scroll container so touch
overscroll can't chain to the locked body when the nav exceeds the
viewport.

GitOrigin-RevId: 84403240c4b3c0e71565cb6e889c47e5e8e9d110
---
 docs/src/app/(home)/site-nav.tsx | 200 ++++++++++++++++---------------
 docs/src/components/ui/sheet.tsx | 134 +++++++++++++++++++++
 2 files changed, 240 insertions(+), 94 deletions(-)
 create mode 100644 docs/src/components/ui/sheet.tsx

diff --git a/docs/src/app/(home)/site-nav.tsx b/docs/src/app/(home)/site-nav.tsx
index 57cc809c..b173bc77 100644
--- a/docs/src/app/(home)/site-nav.tsx
+++ b/docs/src/app/(home)/site-nav.tsx
@@ -1,13 +1,14 @@
 'use client';
 
-import { Menu, Star, X } from 'lucide-react';
+import { BookOpen, Menu, Star, X } from 'lucide-react';
 import Link from 'next/link';
 import type { FC, SVGProps } from 'react';
-import { useEffect, useRef, useState } from 'react';
+import { useEffect, useState } from 'react';
 import { DiscordIcon } from '@/components/icons/discord';
 import { GitHubIcon } from '@/components/icons/github';
 import { XIcon } from '@/components/icons/x';
 import { OkWordmark } from '@/components/ok-wordmark';
+import { Sheet, SheetClose, SheetContent, SheetTitle, SheetTrigger } from '@/components/ui/sheet';
 import { DOWNLOAD_ROUTE } from '@/lib/site';
 import { MarketingButton } from './marketing-button';
 
@@ -17,15 +18,22 @@ type NavLink = {
   external: boolean;
   icon?: FC<SVGProps<SVGSVGElement>>;
   iconOnly?: boolean;
+  desktopIconHidden?: boolean;
   showStars?: boolean;
 };
 
-const docsLink: NavLink = { href: '/docs', label: 'Docs', external: false };
+const docsLink: NavLink = {
+  href: '/docs',
+  label: 'Docs',
+  external: false,
+  icon: BookOpen,
+  desktopIconHidden: true,
+};
 
 const socialLinks: NavLink[] = [
   {
     href: 'https://x.com/OpenKnowledgeAI',
-    label: 'X',
+    label: 'X (Twitter)',
     external: true,
     icon: XIcon,
     iconOnly: true,
@@ -49,8 +57,6 @@ const githubLink: NavLink = {
 
 const mobileLinks: NavLink[] = [docsLink, ...socialLinks, githubLink];
 
-const FOCUSABLE_SELECTOR = 'a[href], button:not([disabled]), [tabindex]:not([tabindex="-1"])';
-
 const starFormatter = new Intl.NumberFormat('en-US', {
   notation: 'compact',
   maximumFractionDigits: 1,
@@ -58,31 +64,44 @@ const starFormatter = new Intl.NumberFormat('en-US', {
 
 const fullStarFormatter = new Intl.NumberFormat('en-US');
 
-function NavLinkContent({ link }: { link: NavLink }) {
+function NavLinkContent({ link, surface }: { link: NavLink; surface: 'desktop' | 'mobile' }) {
   const Icon = link.icon;
+  const showIcon = !!Icon && (surface === 'mobile' || !link.desktopIconHidden);
+  const showLabel = surface === 'mobile' || !link.iconOnly;
   return (
     <>
-      {Icon ? <Icon className="size-4 shrink-0" aria-hidden="true" /> : null}
-      {link.iconOnly ? null : link.label}
+      {showIcon ? <Icon className="size-4 shrink-0" aria-hidden="true" /> : null}
+      {showLabel ? link.label : null}
     </>
   );
 }
 
-function NavItem({ link, className }: { link: NavLink; className: string }) {
-  const ariaLabel = link.iconOnly ? link.label : undefined;
+function NavItem({
+  link,
+  className,
+  surface,
+  onSelect,
+}: {
+  link: NavLink;
+  className: string;
+  surface: 'desktop' | 'mobile';
+  onSelect?: () => void;
+}) {
+  const ariaLabel = surface === 'desktop' && link.iconOnly ? link.label : undefined;
   return link.external ? (
     <a
       href={link.href}
       target="_blank"
       rel="noreferrer"
       aria-label={ariaLabel}
+      onClick={onSelect}
       className={className}
     >
-      <NavLinkContent link={link} />
+      <NavLinkContent link={link} surface={surface} />
     </a>
   ) : (
-    <Link href={link.href} aria-label={ariaLabel} className={className}>
-      <NavLinkContent link={link} />
+    <Link href={link.href} aria-label={ariaLabel} onClick={onSelect} className={className}>
+      <NavLinkContent link={link} surface={surface} />
     </Link>
   );
 }
@@ -103,10 +122,12 @@ function GitHubStarButton({
   link,
   stars,
   variant,
+  onSelect,
 }: {
   link: NavLink;
   stars: number | null;
   variant: 'pill' | 'row';
+  onSelect?: () => void;
 }) {
   const Icon = link.icon;
   const title = stars != null ? `${fullStarFormatter.format(stars)} GitHub stars` : undefined;
@@ -118,6 +139,7 @@ function GitHubStarButton({
         target="_blank"
         rel="noreferrer"
         title={title}
+        onClick={onSelect}
         className="flex items-center justify-between gap-2 rounded-md px-3 py-2 text-slide-text transition-colors hover:bg-slide-bg-elevated"
       >
         <span className="flex items-center gap-2">
@@ -158,47 +180,16 @@ function GitHubStarButton({
 
 export function SiteNav({ stars }: { stars: number | null }) {
   const [open, setOpen] = useState(false);
-  const triggerRef = useRef<HTMLButtonElement>(null);
-  const menuRef = useRef<HTMLDivElement>(null);
 
   useEffect(() => {
-    if (!open) return;
-
-    const previouslyFocused = document.activeElement as HTMLElement | null;
-    const prevBodyOverflow = document.body.style.overflow;
-    document.body.style.overflow = 'hidden';
-
-    const menu = menuRef.current;
-    const firstFocusable = menu?.querySelector<HTMLElement>(FOCUSABLE_SELECTOR);
-    firstFocusable?.focus();
-
-    const onKey = (e: KeyboardEvent) => {
-      if (e.key === 'Escape') {
-        setOpen(false);
-        return;
-      }
-      if (e.key !== 'Tab' || !menu) return;
-      const focusables = menu.querySelectorAll<HTMLElement>(FOCUSABLE_SELECTOR);
-      if (focusables.length === 0) return;
-      const first = focusables[0];
-      const last = focusables[focusables.length - 1];
-      const active = document.activeElement as HTMLElement | null;
-      if (e.shiftKey && active === first) {
-        e.preventDefault();
-        last.focus();
-      } else if (!e.shiftKey && active === last) {
-        e.preventDefault();
-        first.focus();
-      }
-    };
-    document.addEventListener('keydown', onKey);
-
-    return () => {
-      document.removeEventListener('keydown', onKey);
-      document.body.style.overflow = prevBodyOverflow;
-      (triggerRef.current ?? previouslyFocused)?.focus();
+    const mq = window.matchMedia('(min-width: 768px)');
+    const closeOnDesktop = () => {
+      if (mq.matches) setOpen(false);
     };
-  }, [open]);
+    closeOnDesktop();
+    mq.addEventListener('change', closeOnDesktop);
+    return () => mq.removeEventListener('change', closeOnDesktop);
+  }, []);
 
   return (
     <header className="sticky top-0 z-50 bg-fd-background/80 backdrop-blur supports-backdrop-filter:bg-fd-background/70">
@@ -213,6 +204,7 @@ export function SiteNav({ stars }: { stars: number | null }) {
           >
             <NavItem
               link={docsLink}
+              surface="desktop"
               className="inline-flex items-center gap-1.5 transition-colors hover:text-slide-text"
             />
           </nav>
@@ -226,6 +218,7 @@ export function SiteNav({ stars }: { stars: number | null }) {
             <NavItem
               key={link.href}
               link={link}
+              surface="desktop"
               className="inline-flex items-center gap-1.5 transition-colors hover:text-slide-text"
             />
           ))}
@@ -236,48 +229,67 @@ export function SiteNav({ stars }: { stars: number | null }) {
           </MarketingButton>
         </nav>
 
-        <button
-          ref={triggerRef}
-          type="button"
-          className="inline-flex h-10 w-10 items-center justify-center rounded-md text-slide-muted opacity-60 transition-colors hover:bg-slide-bg-elevated hover:text-slide-text md:hidden"
-          aria-expanded={open}
-          aria-controls="site-nav-mobile"
-          aria-label={open ? 'Close menu' : 'Open menu'}
-          onClick={() => setOpen((v) => !v)}
-        >
-          {open ? (
-            <X className="size-5" aria-hidden="true" />
-          ) : (
-            <Menu className="size-5" aria-hidden="true" />
-          )}
-        </button>
-      </div>
-
-      <div
-        ref={menuRef}
-        id="site-nav-mobile"
-        hidden={!open}
-        className="border-t bg-fd-background md:hidden"
-      >
-        <nav
-          aria-label="Mobile"
-          className="container mx-auto flex flex-col gap-1 px-6 py-4 text-base uppercase font-mono"
-        >
-          {mobileLinks.map((link) =>
-            link.showStars ? (
-              <GitHubStarButton key={link.href} link={link} stars={stars} variant="row" />
-            ) : (
-              <NavItem
-                key={link.href}
-                link={link}
-                className="flex items-center gap-2 rounded-md px-3 py-2 text-slide-text transition-colors hover:bg-slide-bg-elevated"
-              />
-            ),
-          )}
-          <MarketingButton href={DOWNLOAD_ROUTE} size="md" className="text-base" showIcon>
-            Download
-          </MarketingButton>
-        </nav>
+        <Sheet open={open} onOpenChange={setOpen}>
+          <SheetTrigger asChild>
+            <button
+              type="button"
+              className="inline-flex h-10 w-10 items-center justify-center rounded-md text-slide-muted opacity-60 transition-colors hover:bg-slide-bg-elevated hover:text-slide-text md:hidden"
+              aria-label="Open menu"
+            >
+              <Menu className="size-5" aria-hidden="true" />
+            </button>
+          </SheetTrigger>
+          <SheetContent
+            side="bottom"
+            aria-describedby={undefined}
+            showCloseButton={false}
+            className="border-t bg-fd-background md:hidden z-[1300]"
+          >
+            <SheetTitle className="sr-only">Site navigation</SheetTitle>
+            <nav
+              aria-label="Mobile"
+              className="container mx-auto flex flex-col gap-1 px-6 pt-4 pb-6 text-base uppercase font-mono overscroll-contain"
+            >
+              <SheetClose asChild>
+                <button
+                  type="button"
+                  aria-label="Close menu"
+                  className="mb-1 inline-flex h-10 w-10 items-center justify-center self-end rounded-md text-slide-muted opacity-60 transition-colors hover:bg-slide-bg-elevated hover:text-slide-text"
+                >
+                  <X className="size-5" aria-hidden="true" />
+                </button>
+              </SheetClose>
+              {mobileLinks.map((link) =>
+                link.showStars ? (
+                  <GitHubStarButton
+                    key={link.href}
+                    link={link}
+                    stars={stars}
+                    variant="row"
+                    onSelect={() => setOpen(false)}
+                  />
+                ) : (
+                  <NavItem
+                    key={link.href}
+                    link={link}
+                    surface="mobile"
+                    onSelect={() => setOpen(false)}
+                    className="flex items-center gap-2 rounded-md px-3 py-2 text-slide-text transition-colors hover:bg-slide-bg-elevated"
+                  />
+                ),
+              )}
+              <MarketingButton
+                href={DOWNLOAD_ROUTE}
+                size="md"
+                className="text-base"
+                showIcon
+                onClick={() => setOpen(false)}
+              >
+                Download
+              </MarketingButton>
+            </nav>
+          </SheetContent>
+        </Sheet>
       </div>
     </header>
   );
diff --git a/docs/src/components/ui/sheet.tsx b/docs/src/components/ui/sheet.tsx
new file mode 100644
index 00000000..3f9e7be8
--- /dev/null
+++ b/docs/src/components/ui/sheet.tsx
@@ -0,0 +1,134 @@
+'use client';
+
+import { XIcon } from 'lucide-react';
+import { Dialog as SheetPrimitive } from 'radix-ui';
+import type * as React from 'react';
+
+import { cn } from '@/lib/utils';
+
+function Sheet({ ...props }: React.ComponentProps<typeof SheetPrimitive.Root>) {
+  return <SheetPrimitive.Root data-slot="sheet" {...props} />;
+}
+
+function SheetTrigger({ ...props }: React.ComponentProps<typeof SheetPrimitive.Trigger>) {
+  return <SheetPrimitive.Trigger data-slot="sheet-trigger" {...props} />;
+}
+
+function SheetClose({ ...props }: React.ComponentProps<typeof SheetPrimitive.Close>) {
+  return <SheetPrimitive.Close data-slot="sheet-close" {...props} />;
+}
+
+function SheetPortal({ ...props }: React.ComponentProps<typeof SheetPrimitive.Portal>) {
+  return <SheetPrimitive.Portal data-slot="sheet-portal" {...props} />;
+}
+
+function SheetOverlay({
+  className,
+  ...props
+}: React.ComponentProps<typeof SheetPrimitive.Overlay>) {
+  return (
+    <SheetPrimitive.Overlay
+      data-slot="sheet-overlay"
+      className={cn(
+        'fixed inset-0 z-50 bg-black/50 data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:animate-in data-[state=open]:fade-in-0',
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+
+function SheetContent({
+  className,
+  children,
+  side = 'right',
+  showCloseButton = true,
+  ...props
+}: React.ComponentProps<typeof SheetPrimitive.Content> & {
+  side?: 'top' | 'right' | 'bottom' | 'left';
+  showCloseButton?: boolean;
+}) {
+  return (
+    <SheetPortal>
+      <SheetOverlay />
+      <SheetPrimitive.Content
+        data-slot="sheet-content"
+        className={cn(
+          'fixed z-50 flex flex-col gap-4 bg-background shadow-lg transition ease-in-out data-[state=closed]:animate-out data-[state=closed]:duration-300 data-[state=open]:animate-in data-[state=open]:duration-500',
+          side === 'right' &&
+            'inset-y-0 right-0 h-full w-3/4 border-l data-[state=closed]:slide-out-to-right data-[state=open]:slide-in-from-right sm:max-w-sm',
+          side === 'left' &&
+            'inset-y-0 left-0 h-full w-3/4 border-r data-[state=closed]:slide-out-to-left data-[state=open]:slide-in-from-left sm:max-w-sm',
+          side === 'top' &&
+            'inset-x-0 top-0 h-auto border-b data-[state=closed]:slide-out-to-top data-[state=open]:slide-in-from-top',
+          side === 'bottom' &&
+            'inset-x-0 bottom-0 h-auto border-t data-[state=closed]:slide-out-to-bottom data-[state=open]:slide-in-from-bottom',
+          className,
+        )}
+        {...props}
+      >
+        {children}
+        {showCloseButton && (
+          <SheetPrimitive.Close className="absolute top-4 right-4 rounded-xs opacity-70 ring-offset-background transition-opacity hover:opacity-100 focus:ring-2 focus:ring-ring focus:ring-offset-2 focus:outline-hidden disabled:pointer-events-none data-[state=open]:bg-secondary">
+            <XIcon className="size-4" />
+            <span className="sr-only">Close</span>
+          </SheetPrimitive.Close>
+        )}
+      </SheetPrimitive.Content>
+    </SheetPortal>
+  );
+}
+
+function SheetHeader({ className, ...props }: React.ComponentProps<'div'>) {
+  return (
+    <div
+      data-slot="sheet-header"
+      className={cn('flex flex-col gap-1.5 p-4', className)}
+      {...props}
+    />
+  );
+}
+
+function SheetFooter({ className, ...props }: React.ComponentProps<'div'>) {
+  return (
+    <div
+      data-slot="sheet-footer"
+      className={cn('mt-auto flex flex-col gap-2 p-4', className)}
+      {...props}
+    />
+  );
+}
+
+function SheetTitle({ className, ...props }: React.ComponentProps<typeof SheetPrimitive.Title>) {
+  return (
+    <SheetPrimitive.Title
+      data-slot="sheet-title"
+      className={cn('font-semibold text-foreground', className)}
+      {...props}
+    />
+  );
+}
+
+function SheetDescription({
+  className,
+  ...props
+}: React.ComponentProps<typeof SheetPrimitive.Description>) {
+  return (
+    <SheetPrimitive.Description
+      data-slot="sheet-description"
+      className={cn('text-sm text-muted-foreground', className)}
+      {...props}
+    />
+  );
+}
+
+export {
+  Sheet,
+  SheetClose,
+  SheetContent,
+  SheetDescription,
+  SheetFooter,
+  SheetHeader,
+  SheetTitle,
+  SheetTrigger,
+};