From cc2f93e338cd21b0edcd3871f7125ba3a6ce9c6b Mon Sep 17 00:00:00 2001
From: BigSimmo <87357024+BigSimmo@users.noreply.github.com>
Date: Sat, 4 Jul 2026 16:12:31 +0800
Subject: [PATCH] feat(mobile): hide universal header on scroll to maximise
 phone screen space

On screens below 640px the universal header now hides once the user scrolls down and returns as soon as they scroll up, keeping content edge-to-edge.

- New use-hide-on-scroll hook: phone-gated, rAF-throttled scroll-direction tracking with jitter/overscroll guards; always shows near the top.
- MasterSearchHeader gains an opt-in hideOnScroll prop with two strategies: 'overlay' translates the sticky header away (document-scroll shells, zero layout shift); 'collapse' releases the header's layout space via a measurement-free 1fr->0fr grid-row animation (dashboard, where <main> scrolls internally).
- Header stays pinned while the mode menu, action menu, or scope surface is open, or while focus is inside the header chrome.
- Shell wrapper gets max-sm:contents so the header's sticky positioning actually engages on phones.
- Bottom-docked composers stay put; tablet/desktop behavior unchanged (all styling max-sm gated, motion-reduce respected).
---
 src/components/ClinicalDashboard.tsx          |  3 +
 .../global-mockup-search-shell.tsx            |  9 +-
 .../master-search-header.tsx                  | 73 +++++++++++++-
 .../clinical-dashboard/use-hide-on-scroll.ts  | 98 +++++++++++++++++++
 4 files changed, 181 insertions(+), 2 deletions(-)
 create mode 100644 src/components/clinical-dashboard/use-hide-on-scroll.ts

diff --git a/src/components/ClinicalDashboard.tsx b/src/components/ClinicalDashboard.tsx
index 49ba42517..e5b3e2118 100644
--- a/src/components/ClinicalDashboard.tsx
+++ b/src/components/ClinicalDashboard.tsx
@@ -5546,6 +5546,9 @@ export function ClinicalDashboard({
           mobileSearchPlacement={hasMobileBottomSearch ? "bottom" : "default"}
           desktopHomeComposerSlotId={desktopHomeComposerSlotId}
           heroComposerFromTablet={Boolean(desktopHomeComposerSlotId)}
+          // Phone-only: the header sits above the internally scrolling <main>,
+          // so hiding must collapse its layout space to hand it to content.
+          hideOnScroll={{ strategy: "collapse", containerRef: mainRef }}
         />
 
         <main
diff --git a/src/components/clinical-dashboard/global-mockup-search-shell.tsx b/src/components/clinical-dashboard/global-mockup-search-shell.tsx
index 98edfc237..9ef81b5ea 100644
--- a/src/components/clinical-dashboard/global-mockup-search-shell.tsx
+++ b/src/components/clinical-dashboard/global-mockup-search-shell.tsx
@@ -329,7 +329,11 @@ function GlobalMockupSearchShellClient({
       ) : null}
 
       <div className="flex min-h-dvh min-w-0 flex-col">
-        <div className={cn(!mobileChromeVisible && "hidden lg:block")}>
+        {/* max-sm:contents lets the header's own `sticky top-0` engage against
+            the document scroll on phones (a plain wrapper div otherwise caps
+            its sticking range at its own height), which the phone
+            hide-on-scroll overlay relies on. */}
+        <div className={mobileChromeVisible ? "max-sm:contents" : "hidden lg:block"}>
           <MasterSearchHeader
             documents={[]}
             documentTotal={0}
@@ -369,6 +373,9 @@ function GlobalMockupSearchShellClient({
             searchComposerVisible={shouldShowSearchComposer}
             desktopHomeComposerSlotId={isStandaloneModeHome ? modeHomeDesktopComposerSlotId : undefined}
             heroComposerFromTablet={isStandaloneModeHome}
+            // Phone-only: the document scrolls here and the header is sticky,
+            // so a translate overlay hides it with zero layout shift.
+            hideOnScroll={{ strategy: "overlay" }}
           />
         </div>
 
diff --git a/src/components/clinical-dashboard/master-search-header.tsx b/src/components/clinical-dashboard/master-search-header.tsx
index 99cbde6b4..4041e4254 100644
--- a/src/components/clinical-dashboard/master-search-header.tsx
+++ b/src/components/clinical-dashboard/master-search-header.tsx
@@ -7,8 +7,10 @@ import {
   useMemo,
   useRef,
   useState,
+  type FocusEvent as ReactFocusEvent,
   type KeyboardEvent as ReactKeyboardEvent,
   type Ref,
+  type RefObject,
 } from "react";
 import { createPortal } from "react-dom";
 
@@ -45,6 +47,7 @@ import {
 
 import { DocumentTagCloud } from "@/components/DocumentTagCloud";
 import { useDismissableLayer } from "@/components/use-dismissable-layer";
+import { useHideOnScroll } from "@/components/clinical-dashboard/use-hide-on-scroll";
 import {
   ModeActionPopup,
   modeActionItemsFor,
@@ -208,6 +211,7 @@ export function MasterSearchHeader({
   heroComposerFromTablet = false,
   mobileLeadingAction = "menu",
   onMobileBack,
+  hideOnScroll,
 }: {
   documents: ClinicalDocument[];
   documentTotal?: number;
@@ -247,6 +251,12 @@ export function MasterSearchHeader({
   heroComposerFromTablet?: boolean;
   mobileLeadingAction?: "menu" | "back";
   onMobileBack?: () => void;
+  /** Phone-only hide-on-scroll for the universal header. "overlay" translates
+   *  the sticky header away (host scrolls the document, content already flows
+   *  beneath); "collapse" also releases the header's layout space (host keeps
+   *  the header above an internally scrolling element). `containerRef` points
+   *  at the scrolling element; omit it to observe window scroll. */
+  hideOnScroll?: { strategy: "overlay" | "collapse"; containerRef?: RefObject<HTMLElement | null> };
 }) {
   const visibleAppModeOptions = defaultVisibleAppModeOptions;
   const trimmedQuery = query.trim();
@@ -279,6 +289,16 @@ export function MasterSearchHeader({
   const [usesScopeSheet, setUsesScopeSheet] = useState(false);
   const [usesPhoneSearchLayout, setUsesPhoneSearchLayout] = useState(false);
   const [desktopHomeComposerActive, setDesktopHomeComposerActive] = useState(false);
+  // Phone-only hide-on-scroll: never hide while a header-owned surface is open
+  // or while focus sits inside the header chrome (keyboard users must not tab
+  // into invisible controls).
+  const [headerChromeFocused, setHeaderChromeFocused] = useState(false);
+  const scrollHidden = useHideOnScroll({
+    containerRef: hideOnScroll?.containerRef,
+    disabled: !hideOnScroll,
+  });
+  const headerChromeHidden =
+    scrollHidden && !modeMenuOpen && !actionMenuOpen && !scopeOpen && !scopeSheetOpen && !headerChromeFocused;
   // Stable, header-owned element the composer is portaled into; we move it in and
   // out of the page-owned slot rather than portaling into the slot directly.
   const [desktopHomeComposerHost, setDesktopHomeComposerHost] = useState<HTMLDivElement | null>(null);
@@ -1361,13 +1381,32 @@ export function MasterSearchHeader({
     );
   }
 
-  return (
+  const hideStrategy = hideOnScroll?.strategy;
+  const chromeFocusProps = hideOnScroll
+    ? {
+        onFocusCapture: () => setHeaderChromeFocused(true),
+        onBlurCapture: (event: ReactFocusEvent<HTMLElement>) => {
+          if (!event.currentTarget.contains(event.relatedTarget as Node | null)) setHeaderChromeFocused(false);
+        },
+      }
+    : undefined;
+
+  const headerAndComposer = (
     <>
       <header
         id="search"
         className={cn(
           "edge-glass-header universal-header sticky top-0 z-30 border-b border-[color:var(--border)] py-2 pt-[max(0.5rem,env(safe-area-inset-top))] text-[color:var(--text)] backdrop-blur-xl",
+          // Overlay hide-on-scroll (phones): the header is sticky over document
+          // scroll, so a plain translate reveals the content already flowing
+          // beneath it with zero layout shift. No transform is applied while
+          // visible so the fixed-position mobile mode menu keeps the viewport
+          // as its containing block.
+          hideStrategy === "overlay" &&
+            "max-sm:transition-transform max-sm:duration-200 max-sm:ease-out motion-reduce:transition-none",
+          hideStrategy === "overlay" && headerChromeHidden && "max-sm:-translate-y-full",
         )}
+        {...(hideStrategy === "overlay" ? chromeFocusProps : undefined)}
       >
         <div
           className={cn(
@@ -1552,4 +1591,36 @@ export function MasterSearchHeader({
       ) : null}
     </>
   );
+
+  if (hideStrategy === "collapse") {
+    // Collapse hide-on-scroll (phones): the host renders the header above an
+    // internally scrolling element, so hiding must also release the header's
+    // layout space. A 1fr -> 0fr grid row animates the collapse without any
+    // height measurement; the bottom-anchored inner track makes the chrome
+    // slide up out of the viewport top. Fixed-position composers (answer
+    // footer, mobile bottom search) escape the wrapper naturally because it
+    // never carries a transform, and everything is inert from sm up.
+    return (
+      <div
+        className={cn(
+          "max-sm:grid max-sm:transition-[grid-template-rows] max-sm:duration-200 max-sm:ease-out motion-reduce:transition-none",
+          headerChromeHidden ? "max-sm:[grid-template-rows:0fr]" : "max-sm:[grid-template-rows:1fr]",
+        )}
+        {...chromeFocusProps}
+      >
+        <div
+          className={cn(
+            "max-sm:flex max-sm:min-h-0 max-sm:flex-col max-sm:justify-end",
+            // Clip only while hiding so the edge-glass-header gradient that
+            // extends below the header keeps painting when the chrome is shown.
+            headerChromeHidden && "max-sm:overflow-hidden",
+          )}
+        >
+          {headerAndComposer}
+        </div>
+      </div>
+    );
+  }
+
+  return headerAndComposer;
 }
diff --git a/src/components/clinical-dashboard/use-hide-on-scroll.ts b/src/components/clinical-dashboard/use-hide-on-scroll.ts
new file mode 100644
index 000000000..90549e40e
--- /dev/null
+++ b/src/components/clinical-dashboard/use-hide-on-scroll.ts
@@ -0,0 +1,98 @@
+"use client";
+
+import { useEffect, useState, useSyncExternalStore, type RefObject } from "react";
+
+// Matches phoneSearchLayoutMediaQuery in master-search-header.tsx — the repo's
+// phone/tablet seam. Hide-on-scroll only ever runs below the sm breakpoint.
+const phoneMediaQuery = "(max-width: 639px)";
+
+// Scroll offset (px) that must be passed before the chrome may hide; roughly
+// the header's own height so it never vanishes while still fully in view.
+const hideActivationOffset = 56;
+// Offset (px) at or below which the chrome is always shown.
+const topRevealOffset = 8;
+// Minimum per-event delta (px) before we treat movement as intentional, to
+// avoid jitter from momentum settling and fractional scroll positions.
+const minimumDelta = 4;
+
+function subscribeToPhoneMedia(onChange: () => void) {
+  const media = window.matchMedia(phoneMediaQuery);
+  media.addEventListener("change", onChange);
+  return () => media.removeEventListener("change", onChange);
+}
+
+function readPhoneMedia() {
+  return window.matchMedia(phoneMediaQuery).matches;
+}
+
+function readPhoneMediaServer() {
+  return false;
+}
+
+interface UseHideOnScrollOptions {
+  /**
+   * Element that owns the scrolling. When omitted the window/document scroll
+   * position is observed instead.
+   */
+  containerRef?: RefObject<HTMLElement | null>;
+  /** Disables the behavior entirely (state resets to visible). */
+  disabled?: boolean;
+}
+
+/**
+ * Tracks scroll direction on phones and reports when top chrome (the
+ * universal header) should hide to maximise content space. Hidden while
+ * scrolling down past the header, shown again on any deliberate scroll up or
+ * when near the top. Inert (always visible) above the phone breakpoint.
+ */
+export function useHideOnScroll({ containerRef, disabled = false }: UseHideOnScrollOptions): boolean {
+  const [hidden, setHidden] = useState(false);
+  const isPhone = useSyncExternalStore(subscribeToPhoneMedia, readPhoneMedia, readPhoneMediaServer);
+  const active = isPhone && !disabled;
+
+  useEffect(() => {
+    if (!active) return;
+
+    const container = containerRef?.current ?? null;
+    const target: HTMLElement | Window = container ?? window;
+    const readOffset = () => (container ? container.scrollTop : window.scrollY);
+
+    let lastOffset = readOffset();
+    let frame = 0;
+
+    const evaluate = () => {
+      frame = 0;
+      const offset = readOffset();
+      // Ignore iOS rubber-band overscroll at the top.
+      if (offset < 0) return;
+      const delta = offset - lastOffset;
+      if (offset <= topRevealOffset) {
+        lastOffset = offset;
+        setHidden(false);
+        return;
+      }
+      if (Math.abs(delta) < minimumDelta) return;
+      lastOffset = offset;
+      if (delta > 0) {
+        if (offset > hideActivationOffset) setHidden(true);
+      } else {
+        setHidden(false);
+      }
+    };
+
+    const onScroll = () => {
+      if (frame) return;
+      frame = window.requestAnimationFrame(evaluate);
+    };
+
+    target.addEventListener("scroll", onScroll, { passive: true });
+    return () => {
+      target.removeEventListener("scroll", onScroll);
+      if (frame) window.cancelAnimationFrame(frame);
+      // Leaving the phone breakpoint (or unmounting) always restores the chrome.
+      setHidden(false);
+    };
+  }, [active, containerRef]);
+
+  return active && hidden;
+}