feat(guide): pin guide chrome controls to shared scroll-hide behavior

docs/branch-review-records/69f8c9afc87b9d9cc96b53a279a21343d9958028c10817d02e7c975f91014522.record.md

@@ -0,0 +1 @@
+| 2026-08-16 | PR #2007 / codex/guide-search-chrome-20260815 | 82576f737912e5fc2b601ec1e4f4ca74ebb04e69 | end-to-end PR review and base sync | Merged main without loss; fixed hidden Sheet safe-area retention; preserved focused Guide chrome coverage | Manual adversarial diff pass; TypeScript syntax probes; merge-tree and exact-head CI rechecked |

docs/branch-review-records/6cdaa052c37673355af42b196c2bb613fd5ed4615778a6e59fa3c4e010706922.record.md

@@ -0,0 +1 @@
+| 2026-08-16 | PR #2007 / codex/guide-search-chrome-20260815 | 0874f3f7faa9539b6db30a58cee360adff4bf7a1 | design-system CI repair | Replaced the retired elevated shadow alias and removed two layout-transition exceptions from Guide chrome | Design-system contract diagnosis from exact-head CI; targeted source verification; exact-head CI re-run |

docs/branch-review-records/d9883c1c107d462f6ba5bf9e1447b570eb90fa0026059959a4ca253be147df3a.record.md

@@ -0,0 +1 @@
+| 2026-08-17 | codex/guide-search-chrome-20260815 | 7365c7f36751b15f155b5228bdce075d9c4e09ec | PR #2007 CI fix: prettier format, design-sync contract regen, guide-centre scroll-hide race, ui-smoke scroll threshold + a11y (bodyTabIndex) | Fixed 4 CI failures (Static PR checks, Unit coverage x2, Production UI) so PR is ready to merge once CI reruns | npx vitest run (design-sync-contract, design-sync-visual-exports, guide-centre.dom, guide-centre-design-contract.dom); npx eslint on touched files; npx prettier --check; local Playwright production build+run of tests/ui-smoke.spec.ts guide centre test (3 iterations to isolate/fix/verify) and tests/guide-centre-chrome.spec.ts (found unmatched by testMatch, noted not fixed) |

src/components/clinical-dashboard/guide-dialog.tsx

@@ -23,7 +23,7 @@ import {
   X,
   type LucideIcon,
 } from "lucide-react";
-import { useMemo, useRef, useState, useSyncExternalStore, type UIEvent } from "react";
+import { useMemo, useRef, useState, type RefObject, type UIEvent } from "react";
 
 import {
   guideQuickTasks,
@@ -44,6 +44,7 @@ import {
   saveGuideProgress,
   type GuideProgress,
 } from "@/components/clinical-dashboard/guide-progress";
+import { readChromeCollapseMetrics, useScrollHideReporter } from "@/components/clinical-dashboard/use-hide-on-scroll";
 import { Sheet } from "@/components/ui/sheet";
 import {
   chatComposerIconButton,
@@ -57,23 +58,6 @@ import {
 } from "@/components/ui-primitives";
 
 const guideAccessibleNameId = "clinical-kb-guide-accessible-name";
-const phoneMediaQuery = "(max-width: 639px)";
-
-function subscribeToPhoneMedia(callback: () => void) {
-  if (typeof window === "undefined" || typeof window.matchMedia !== "function") return () => undefined;
-  const media = window.matchMedia(phoneMediaQuery);
-  media.addEventListener("change", callback);
-  return () => media.removeEventListener("change", callback);
-}
-
-function getPhoneMediaSnapshot() {
-  if (typeof window === "undefined" || typeof window.matchMedia !== "function") return false;
-  return window.matchMedia(phoneMediaQuery).matches;
-}
-
-function usePhoneViewport() {
-  return useSyncExternalStore(subscribeToPhoneMedia, getPhoneMediaSnapshot, () => false);
-}
 
 const topicIcons: Record<GuideTopicId, LucideIcon> = {
   "getting-started": BookOpen,
@@ -88,12 +72,23 @@ const topicIcons: Record<GuideTopicId, LucideIcon> = {
 
 const quickTaskIcons: readonly LucideIcon[] = [HelpCircle, SlidersHorizontal, ShieldCheck, LockKeyhole];
 
-function GuideSearch({ query, onQueryChange }: { query: string; onQueryChange: (query: string) => void }) {
+function GuideSearch({
+  query,
+  inputRef,
+  onFocusChange,
+  onQueryChange,
+}: {
+  query: string;
+  inputRef: RefObject<HTMLInputElement | null>;
+  onFocusChange: (focused: boolean) => void;
+  onQueryChange: (query: string) => void;
+}) {
   return (
     <form
       role="search"
       aria-label="Search guide content"
       onSubmit={(event) => event.preventDefault()}
+      data-guide-universal-search
       className="mx-auto w-full max-w-3xl"
     >
       <div
@@ -108,9 +103,12 @@ function GuideSearch({ query, onQueryChange }: { query: string; onQueryChange: (
         <label className="min-w-0 flex-1">
           <span className="sr-only">Search the guide</span>
           <input
+            ref={inputRef}
             type="search"
             value={query}
             onChange={(event) => onQueryChange(event.target.value)}
+            onFocus={() => onFocusChange(true)}
+            onBlur={() => onFocusChange(false)}
             placeholder="Search the guide"
             className={cn(chatComposerInput, "answer-footer-search-input w-full min-w-0")}
             autoComplete="off"
@@ -139,7 +137,10 @@ function GuideTopNavigation({ view, onNavigate }: { view: GuideView; onNavigate:
     { view: "topics", label: "All topics", icon: Grid2X2 },
   ];
   return (
-    <nav aria-label="Guide views" className="grid grid-cols-3 border-y border-[color:var(--border)]">
+    <nav
+      aria-label="Guide views"
+      className="grid grid-cols-3 border-t border-[color:var(--border)] bg-[color:var(--surface-raised)]"
+    >
       {items.map((item) => {
         const active = view === item.view || (view === "topic" && item.view === "topics");
         const Icon = item.icon;
@@ -150,7 +151,7 @@ function GuideTopNavigation({ view, onNavigate }: { view: GuideView; onNavigate:
             onClick={() => onNavigate(item.view)}
             aria-current={active ? "page" : undefined}
             className={cn(
-              "relative inline-flex min-h-tap items-center justify-center gap-2 px-2 text-xs font-semibold transition focus-visible:outline focus-visible:outline-2 focus-visible:outline-offset-[-2px] focus-visible:outline-[color:var(--focus)] sm:text-sm",
+              "relative inline-flex min-h-tap items-center justify-center gap-1.5 px-1.5 text-xs font-semibold transition focus-visible:outline focus-visible:outline-2 focus-visible:outline-offset-[-2px] focus-visible:outline-[color:var(--focus)] sm:gap-2 sm:px-2 sm:text-sm",
               active
                 ? "text-[color:var(--clinical-accent)] after:absolute after:inset-x-4 after:bottom-0 after:h-0.5 after:bg-[color:var(--clinical-accent)]"
                 : "text-[color:var(--text-muted)] hover:bg-[color:var(--surface-subtle)] hover:text-[color:var(--text)]",
@@ -679,33 +680,46 @@ function GuideDialogSession({ onClose }: { onClose: () => void }) {
   const [progress, setProgress] = useState<GuideProgress>(() => loadGuideProgress());
   const [tourStepIndex, setTourStepIndex] = useState(0);
   const [tourComplete, setTourComplete] = useState(false);
+  const [searchFocused, setSearchFocused] = useState(false);
   const contentStartRef = useRef<HTMLDivElement | null>(null);
   const scrollBodyRef = useRef<HTMLDivElement | null>(null);
+  const headerRef = useRef<HTMLDivElement | null>(null);
+  const searchInputRef = useRef<HTMLInputElement | null>(null);
   const lastScrollTopRef = useRef(0);
-  const [mobileFooterHidden, setMobileFooterHidden] = useState(false);
-  const isPhoneViewport = usePhoneViewport();
-  const footerHidden = isPhoneViewport && mobileFooterHidden;
+  const chromeScrollHide = useScrollHideReporter(
+    searchFocused,
+    false,
+    `${view}:${activeTopicId}:${tourStepIndex}:${tourComplete}`,
+  );
+  const chromeHidden = chromeScrollHide.hidden;
 
   function focusPageStart() {
     window.requestAnimationFrame(() => {
       if (scrollBodyRef.current) scrollBodyRef.current.scrollTop = 0;
       lastScrollTopRef.current = 0;
-      setMobileFooterHidden(false);
+      chromeScrollHide.reset();
       contentStartRef.current?.querySelector<HTMLElement>("[data-guide-page-heading]")?.focus({ preventScroll: true });
     });
   }
 
   function handleBodyScroll(event: UIEvent<HTMLDivElement>) {
-    const nextScrollTop = event.currentTarget.scrollTop;
-    if (!isPhoneViewport) {
-      lastScrollTopRef.current = nextScrollTop;
-      setMobileFooterHidden(false);
-      return;
+    const target = event.currentTarget;
+    const nextScrollTop = target.scrollTop;
+    if (document.activeElement === searchInputRef.current && Math.abs(nextScrollTop - lastScrollTopRef.current) > 4) {
+      searchInputRef.current?.blur();
     }
-    const delta = nextScrollTop - lastScrollTopRef.current;
-    if (nextScrollTop <= 12) setMobileFooterHidden(false);
-    else if (delta > 6) setMobileFooterHidden(true);
-    else if (delta < -6) setMobileFooterHidden(false);
+    const collapseMetrics = readChromeCollapseMetrics(target);
+    const headerRelease = headerRef.current?.getBoundingClientRect().height ?? 0;
+    const reserveRelease = collapseMetrics.collapseBudget ?? 0;
+    chromeScrollHide.reportScroll({
+      offset: nextScrollTop,
+      maxOffset: Math.max(0, target.scrollHeight - target.clientHeight),
+      ...collapseMetrics,
+      collapseBudget: headerRelease + reserveRelease,
+      collapseKind: headerRelease > 0 ? "in-flow" : collapseMetrics.collapseKind,
+      combinedChrome: headerRelease > 0 && reserveRelease > 0,
+      source: target,
+    });
     lastScrollTopRef.current = nextScrollTop;
   }
 
@@ -764,14 +778,11 @@ function GuideDialogSession({ onClose }: { onClose: () => void }) {
   const footer = (
     <div
       data-guide-mobile-footer
-      aria-hidden={footerHidden}
-      inert={footerHidden || undefined}
-      className="flex min-w-0 items-center justify-center gap-3 sm:justify-between"
+      aria-hidden={chromeHidden}
+      inert={chromeHidden || undefined}
+      className="mx-auto grid w-full max-w-3xl min-w-0 gap-2.5"
     >
-      <p className={cn("hidden min-w-0 items-center gap-2 text-xs sm:flex", textMuted)}>
-        <ShieldCheck aria-hidden="true" className="size-icon-md shrink-0" /> Demo content only · Do not enter PHI
-      </p>
-      <div className="flex min-w-0 items-center justify-center gap-2 sm:ml-auto sm:justify-end">
+      <div data-guide-tour-action-row className="flex min-w-0 items-center justify-center gap-2">
         {view === "tour" && !tourComplete ? (
           <>
             <button
@@ -834,6 +845,23 @@ function GuideDialogSession({ onClose }: { onClose: () => void }) {
           </>
         )}
       </div>
+      <GuideSearch
+        query={query}
+        inputRef={searchInputRef}
+        onFocusChange={setSearchFocused}
+        onQueryChange={(nextQuery) => {
+          setQuery(nextQuery);
+          if (nextQuery.trim()) {
+            window.requestAnimationFrame(() => {
+              if (scrollBodyRef.current) scrollBodyRef.current.scrollTop = 0;
+              chromeScrollHide.reset();
+            });
+          }
+        }}
+      />
+      <p className={cn("hidden items-center justify-center gap-2 text-xs sm:flex", textMuted)}>
+        <ShieldCheck aria-hidden="true" className="size-icon-md shrink-0" /> Demo content only · Do not enter PHI
+      </p>
     </div>
   );
 
@@ -855,13 +883,21 @@ function GuideDialogSession({ onClose }: { onClose: () => void }) {
       contentClassName="relative font-sans sm:max-w-none lg:h-[min(56rem,calc(100dvh-3rem))] lg:max-w-[min(94vw,90rem)]"
       bodyClassName="p-0 sm:p-0"
       bodyRef={scrollBodyRef}
+      bodyTabIndex={0}
       onBodyScroll={handleBodyScroll}
-      headerClassName="pt-[max(1rem,env(safe-area-inset-top))] sm:pt-5"
+      headerRef={headerRef}
+      headerHidden={chromeHidden}
+      headerBottom={<GuideTopNavigation view={view} onNavigate={navigate} />}
+      headerClassName={cn(
+        "guide-centre-header max-h-48 overflow-hidden pt-[max(1rem,env(safe-area-inset-top))] transition-[border-color,opacity] duration-[var(--duration-moderate)] motion-reduce:transition-none sm:pt-5",
+        chromeHidden &&
+          "max-h-0 border-transparent p-0 opacity-0 sm:max-h-48 sm:border-[color:var(--border)] sm:p-5 sm:opacity-100",
+      )}
       mobilePlacement="fullscreen"
       footer={footer}
       footerClassName={cn(
-        "absolute inset-x-0 bottom-0 z-30 pl-[max(0.75rem,env(safe-area-inset-left))] pr-[max(0.75rem,env(safe-area-inset-right))] pb-[max(0.75rem,env(safe-area-inset-bottom))] pt-3 transition-[transform,opacity] duration-[var(--duration-quick)] sm:static sm:p-4",
-        footerHidden &&
+        "absolute inset-x-0 bottom-0 z-30 border-t border-[color:var(--border)] bg-[color:var(--surface-raised)] pl-[max(0.75rem,env(safe-area-inset-left))] pr-[max(0.75rem,env(safe-area-inset-right))] pb-[max(0.75rem,env(safe-area-inset-bottom))] pt-3 shadow-[var(--e4)] transition-[transform,opacity] duration-[var(--duration-moderate)] motion-reduce:transition-none sm:static sm:p-4 sm:shadow-none",
+        chromeHidden &&
           "pointer-events-none translate-y-full opacity-0 sm:pointer-events-auto sm:translate-y-0 sm:opacity-100",
       )}
       testId="clinical-kb-guide-centre"
@@ -870,14 +906,12 @@ function GuideDialogSession({ onClose }: { onClose: () => void }) {
       <span id={guideAccessibleNameId} className="sr-only">
         Clinical KB guide
       </span>
-      <div className="sticky top-0 z-20 bg-[color:var(--surface-raised)] px-3 pb-3 sm:px-5">
-        <GuideSearch query={query} onQueryChange={setQuery} />
-      </div>
-      <GuideTopNavigation view={view} onNavigate={navigate} />
       <div
         ref={contentStartRef}
         data-guide-content
-        className={cn("space-y-4 p-3 sm:p-5", footerHidden ? "pb-0" : "pb-28")}
+        data-reserve-owner="guide-search-dock"
+        data-reserve-hidden-pad="0"
+        className={cn("space-y-4 p-3 sm:p-5", chromeHidden ? "pb-0 sm:pb-5" : "pb-40 sm:pb-5")}
       >
         {hasSearch ? (
           <SearchResults query={query} onSelect={openTopic} />

src/components/ui/sheet.tsx

@@ -52,13 +52,23 @@ type SheetBaseProps = {
   titleAccessory?: ReactNode;
   descriptionContent?: ReactNode;
   headerActions?: ReactNode;
+  headerBottom?: ReactNode;
+  headerHidden?: boolean;
+  headerRef?: RefObject<HTMLDivElement | null>;
   headerClassName?: string;
   titleClassName?: string;
   closeButtonClassName?: string;
   contentClassName?: string;
   contentStyle?: CSSProperties;
   bodyClassName?: string;
   bodyRef?: RefObject<HTMLDivElement | null>;
+  /**
+   * Makes the scrollable body reachable by keyboard when its content may not
+   * always include a focusable descendant (WCAG 2.1.1 / axe
+   * scrollable-region-focusable). Omit for bodies that always contain
+   * interactive content.
+   */
+  bodyTabIndex?: number;
   onBodyScroll?: UIEventHandler<HTMLDivElement>;
   footerClassName?: string;
   placement?: "default" | "left";
@@ -108,13 +118,17 @@ export function Sheet({
   titleAccessory,
   descriptionContent,
   headerActions,
+  headerBottom,
+  headerHidden = false,
+  headerRef,
   headerClassName,
   titleClassName,
   closeButtonClassName,
   contentClassName,
   contentStyle,
   bodyClassName,
   bodyRef,
+  bodyTabIndex,
   onBodyScroll,
   footerClassName,
   placement = "default",
@@ -459,12 +473,20 @@ export function Sheet({
         </div>
         {title ? (
           <div
+            ref={headerRef}
             data-sheet-header="true"
+            aria-hidden={headerHidden}
+            inert={headerHidden || undefined}
             className={cn(
-              "flex items-center justify-between gap-3 border-b border-[color:var(--border)] p-4 sm:p-5",
+              "flex items-center justify-between gap-x-3 border-b border-[color:var(--border)] p-4 sm:p-5",
+              Boolean(headerBottom) && "flex-wrap",
               headerClassName,
-              resolvedMobileHeaderSafeArea === "padding" && "pt-[max(1rem,var(--safe-area-top))] sm:pt-5",
-              resolvedMobileHeaderSafeArea === "offset" && "top-[max(0.75rem,var(--safe-area-top))] sm:top-4",
+              !headerHidden &&
+                resolvedMobileHeaderSafeArea === "padding" &&
+                "pt-[max(1rem,var(--safe-area-top))] sm:pt-5",
+              !headerHidden &&
+                resolvedMobileHeaderSafeArea === "offset" &&
+                "top-[max(0.75rem,var(--safe-area-top))] sm:top-4",
             )}
           >
             <div className="flex min-w-0 flex-1 items-center gap-3">
@@ -502,11 +524,17 @@ export function Sheet({
                 <X aria-hidden="true" className="h-4 w-4" />
               </button>
             </div>
+            {headerBottom ? (
+              <div className="order-last -mx-4 mt-3 w-[calc(100%+2rem)] basis-full sm:-mx-5 sm:w-[calc(100%+2.5rem)]">
+                {headerBottom}
+              </div>
+            ) : null}
           </div>
         ) : null}
         <div
           ref={bodyRef}
           onScroll={onBodyScroll}
+          tabIndex={bodyTabIndex}
           className={cn("min-h-0 min-w-0 flex-1 overflow-y-auto p-4 polished-scroll sm:p-5", bodyClassName)}
         >
           {children}