@sovereignfs/ui 0.45.0 → 0.54.0

package/src/hooks/index.ts

@@ -2,5 +2,23 @@ export { useLongPress } from './useLongPress';
 export type { UseLongPressOptions, LongPressHandlers } from './useLongPress';
 export { useDoubleTapHandler, useSingleOrDoubleTap } from './useDoubleTap';
 export { useIsMobile, MOBILE_BREAKPOINT_PX } from './useIsMobile';
+export { useIsOffline } from './useIsOffline';
+export { useOfflineTileState } from './useOfflineTileState';
+export type { OfflineTileState } from './useOfflineTileState';
 export { useCommitOnEnterOrBlur } from './useCommitOnEnterOrBlur';
 export type { CommitOnEnterOrBlurHandlers } from './useCommitOnEnterOrBlur';
+export { useSwipeReveal } from './useSwipeReveal';
+export type {
+  UseSwipeRevealOptions,
+  UseSwipeRevealHandlers,
+  UseSwipeRevealResult,
+} from './useSwipeReveal';
+export { useSnapCarousel } from './useSnapCarousel';
+export type { UseSnapCarouselOptions, UseSnapCarouselResult } from './useSnapCarousel';
+export { useResponsiveLayout } from './useResponsiveLayout';
+export type { UseResponsiveLayoutOptions, UseResponsiveLayoutResult } from './useResponsiveLayout';
+export { useCarouselRouteSync } from './useCarouselRouteSync';
+export type {
+  UseCarouselRouteSyncOptions,
+  UseCarouselRouteSyncResult,
+} from './useCarouselRouteSync';

package/src/hooks/useCarouselRouteSync.ts

@@ -0,0 +1,92 @@
+'use client';
+
+import { useEffect, useRef, useState } from 'react';
+
+export interface UseCarouselRouteSyncOptions {
+  /** Maps the current pathname to a slide index — the caller's own routing
+   *  logic (e.g. special-casing a virtual "starred" slide), unchanged from
+   *  whatever a plugin already has today. This hook has no idea what a
+   *  plugin's routes look like, by design — it never imports a router. */
+  indexForPathname: (pathname: string) => number;
+  /** Inverse mapping — given a settled slide index, the path to navigate to. */
+  pathForIndex: (index: number) => string;
+  /** The current pathname. The caller reads this via their own router (e.g.
+   *  `usePathname()` from `next/navigation`) and passes it in every render —
+   *  this package stays framework-generic and has zero runtime dependencies. */
+  pathname: string;
+  /** Called when this hook wants to navigate — typically
+   *  `(path) => router.replace(path, { scroll: false })`. */
+  onNavigate: (path: string) => void;
+}
+
+export interface UseCarouselRouteSyncResult {
+  /** Feed directly into SwipableMobileCarousel's `activeIndex` prop. */
+  activeIndex: number;
+  /** Feed directly into SwipableMobileCarousel's `onSettle` prop. */
+  onSettle: (index: number) => void;
+}
+
+/**
+ * useCarouselRouteSync — centralizes the pathname↔slide-index mapping and the
+ * "was this pathname change our own settle, or an external navigation"
+ * distinction that carousel-driving plugins otherwise hand-roll per plugin
+ * (a tapped `<Link>`, browser back/forward, vs. this hook's own
+ * `router.replace` after a swipe settles). Router-agnostic on purpose: the
+ * caller owns the actual `usePathname()`/`router.replace()` calls and only
+ * hands this hook plain values/callbacks.
+ *
+ * Deliberately does not own neighbor-prefetch (SwipableMobileCarousel's
+ * `prefetchDistance`/mount-window covers that) or scroll mechanics (the
+ * carousel component reacts to `activeIndex` changes itself) — this hook is
+ * pathname↔index mapping only, keeping routing glue decoupled from
+ * data-fetching and DOM scrolling.
+ */
+export function useCarouselRouteSync({
+  indexForPathname,
+  pathForIndex,
+  pathname,
+  onNavigate,
+}: UseCarouselRouteSyncOptions): UseCarouselRouteSyncResult {
+  // Kept in refs and refreshed every render (not effect deps) so an inline
+  // arrow function passed by the caller each render doesn't retrigger the
+  // pathname-sync effect below — only an actual pathname change should.
+  const indexForPathnameRef = useRef(indexForPathname);
+  indexForPathnameRef.current = indexForPathname;
+  const pathForIndexRef = useRef(pathForIndex);
+  pathForIndexRef.current = pathForIndex;
+  const onNavigateRef = useRef(onNavigate);
+  onNavigateRef.current = onNavigate;
+
+  const [activeIndex, setActiveIndex] = useState(() => indexForPathname(pathname));
+  // Set synchronously inside onSettle, right before this hook's own
+  // navigation call — lets the pathname-sync effect below tell "this
+  // pathname change is our own settle, already reflected in activeIndex"
+  // apart from a genuinely external navigation.
+  const isInternalNavRef = useRef(false);
+  const didMountRef = useRef(false);
+
+  useEffect(() => {
+    if (!didMountRef.current) {
+      // The very first render's activeIndex already reflects pathname via
+      // the lazy useState initializer above — nothing to resync on mount.
+      didMountRef.current = true;
+      return;
+    }
+    if (isInternalNavRef.current) {
+      isInternalNavRef.current = false;
+      return;
+    }
+    const newIndex = indexForPathnameRef.current(pathname);
+    setActiveIndex((current) => (newIndex === current ? current : newIndex));
+    // Only re-run when pathname itself changes — indexForPathname is read
+    // through a ref precisely so its identity doesn't matter here.
+  }, [pathname]);
+
+  function onSettle(index: number) {
+    isInternalNavRef.current = true;
+    setActiveIndex(index);
+    onNavigateRef.current(pathForIndexRef.current(index));
+  }
+
+  return { activeIndex, onSettle };
+}

package/src/hooks/useIsOffline.ts

@@ -0,0 +1,41 @@
+'use client';
+
+import { useEffect, useState } from 'react';
+
+/**
+ * useIsOffline — whether the browser currently has no network connection.
+ *
+ * SSR-safe: always initialises to `false` (online) so the server-rendered HTML
+ * matches the first client render, then reads the real `navigator.onLine`
+ * value in `useEffect`. This picks up the case where the page loaded already
+ * offline (e.g. served from the service-worker cache) at the cost of an
+ * imperceptible one-frame delay before the offline state appears — the same
+ * trade-off `OfflineBanner` makes, which this hook was extracted from so every
+ * consumer shares one connectivity source instead of re-deriving it slightly
+ * differently (research 0012, epic task 2.32).
+ *
+ * Reflects only `navigator.onLine` — true whenever the OS reports a network
+ * interface is up, even without real upstream connectivity (e.g. Wi-Fi with no
+ * internet). That is a known limitation of the browser API itself, not of this
+ * hook; there is currently no better cross-browser signal available.
+ */
+export function useIsOffline(): boolean {
+  const [isOffline, setIsOffline] = useState(false);
+
+  useEffect(() => {
+    setIsOffline(!navigator.onLine);
+
+    const handleOffline = () => setIsOffline(true);
+    const handleOnline = () => setIsOffline(false);
+
+    window.addEventListener('offline', handleOffline);
+    window.addEventListener('online', handleOnline);
+
+    return () => {
+      window.removeEventListener('offline', handleOffline);
+      window.removeEventListener('online', handleOnline);
+    };
+  }, []);
+
+  return isOffline;
+}

package/src/hooks/useOfflineTileState.ts

@@ -0,0 +1,45 @@
+'use client';
+
+import { useIsOffline } from './useIsOffline';
+
+/**
+ * The two reasons an app tile can be non-interactive, kept structurally
+ * distinct because they have different causes and must never read as the same
+ * thing to a user (research 0012, epic task 2.33):
+ *
+ * - `'connectivity-dimmed'` — a no-offline-tier app, dimmed only while the
+ *   device is **actually offline right now**. Reactive and temporary; clears
+ *   the instant connectivity returns.
+ * - `'capability-restricted'` — a `device-only` app on a surface without the
+ *   durable, encrypted, device-auth-gated store it needs. Static and
+ *   unrelated to connectivity — it stays restricted even when fully online,
+ *   and must never say "offline" to a user who plainly isn't.
+ */
+export type OfflineTileState = 'connectivity-dimmed' | 'capability-restricted' | null;
+
+/**
+ * Which of the two states, if any, applies to an app tile given its declared
+ * offline tier.
+ *
+ * `deviceOnlyAvailable` is the caller's own
+ * `isDeviceOnlyTierAvailable()` result (from
+ * `@sovereignfs/sdk/device-client`) — deliberately taken as a plain boolean
+ * parameter rather than computed inside this hook, so `@sovereignfs/ui` never
+ * depends on `@sovereignfs/sdk` (this package must stay usable standalone,
+ * outside the plugin runtime — RFC 0073).
+ *
+ * An `offline-first` app is never restricted by either state: that tier's
+ * whole point is working with no network, so it stays fully interactive both
+ * online and offline. A `device-only` app that *is* available behaves the
+ * same way — the restriction is about availability, not connectivity.
+ */
+export function useOfflineTileState(
+  offline: 'offline-first' | 'device-only' | undefined,
+  deviceOnlyAvailable: boolean,
+): OfflineTileState {
+  const isOffline = useIsOffline();
+
+  if (offline === 'device-only' && !deviceOnlyAvailable) return 'capability-restricted';
+  if (offline === undefined && isOffline) return 'connectivity-dimmed';
+  return null;
+}

package/src/hooks/useResponsiveLayout.ts

@@ -0,0 +1,36 @@
+'use client';
+
+import { useIsMobile } from './useIsMobile';
+
+export interface UseResponsiveLayoutOptions<TWeb, TMobile> {
+  web: TWeb;
+  mobile: TMobile;
+  breakpointPx?: number;
+}
+
+export interface UseResponsiveLayoutResult<TWeb, TMobile> {
+  isMobile: boolean;
+  value: TWeb | TMobile;
+}
+
+/**
+ * useResponsiveLayout — picks between a `web` and `mobile` value for the
+ * current viewport, built on `useIsMobile` (same breakpoint/SSR-safe-default
+ * behavior, not reimplemented here). Generic over the value type so it works
+ * for JSX (the common case — forking an entire component tree, not just a
+ * class name) or any other per-breakpoint value a plugin wants to pick
+ * without repeating the isMobile-ternary boilerplate every call site.
+ *
+ * This formalizes the `if (isMobile) return <mobile/>; return <web/>;` fork
+ * plugins have hand-rolled per-plugin (e.g. a `MobileAwareShell` component
+ * that swaps an entire routed page tree for a client-only mobile one) —
+ * see `ResponsiveSurface` for the equivalent as a plain JSX component.
+ */
+export function useResponsiveLayout<TWeb, TMobile>({
+  web,
+  mobile,
+  breakpointPx,
+}: UseResponsiveLayoutOptions<TWeb, TMobile>): UseResponsiveLayoutResult<TWeb, TMobile> {
+  const isMobile = useIsMobile(breakpointPx);
+  return { isMobile, value: isMobile ? mobile : web };
+}

package/src/hooks/useSnapCarousel.ts

@@ -0,0 +1,79 @@
+'use client';
+
+import { useEffect, useRef } from 'react';
+import type { RefObject } from 'react';
+
+export interface UseSnapCarouselOptions {
+  /** Total number of slides — settle detection clamps to this range. */
+  itemCount: number;
+  /** Called when the user's scroll gesture settles on a different slide
+   *  index than the last one reported. */
+  onSettle?: (index: number) => void;
+  /** Debounce delay (ms) after the last `scroll` event before checking where
+   *  the container settled. Default 120 — matches the value this hook was
+   *  extracted from. Debounced rather than keyed to the `scrollend` event,
+   *  which pre-17.4 iOS Safari/WKWebView doesn't support. */
+  debounceMs?: number;
+}
+
+export interface UseSnapCarouselResult {
+  /** Attach to the `scroll-snap-type: x` scroll container. */
+  scrollRef: RefObject<HTMLDivElement | null>;
+  /** Imperatively scrolls the container to a slide index. */
+  scrollToIndex: (index: number, behavior?: ScrollBehavior) => void;
+}
+
+/**
+ * useSnapCarousel — debounced "settled slide" detection over a native
+ * `scroll-snap-type: x` container, extracted from `sovereign-tasks`'s
+ * `MobileTasksCarousel` and independently reimplemented in
+ * `sovereign-shopper`'s `MobileShopperCarousel` (RFC 0079, epic task 9.20).
+ * Gives swipe-between-slides physics for free via native scroll-snap, with
+ * this hook only handling "which slide did we land on."
+ */
+export function useSnapCarousel({
+  itemCount,
+  onSettle,
+  debounceMs = 120,
+}: UseSnapCarouselOptions): UseSnapCarouselResult {
+  const scrollRef = useRef<HTMLDivElement>(null);
+  const timerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const lastIndexRef = useRef<number | null>(null);
+  // Kept in a ref so the scroll listener always calls the latest callback
+  // without needing to be torn down and re-attached on every render.
+  const onSettleRef = useRef(onSettle);
+  onSettleRef.current = onSettle;
+
+  useEffect(() => {
+    const el = scrollRef.current;
+    if (!el) return;
+    function handleScroll() {
+      if (timerRef.current) clearTimeout(timerRef.current);
+      timerRef.current = setTimeout(() => {
+        const current = scrollRef.current;
+        if (!current) return;
+        const width = current.clientWidth;
+        if (!width) return;
+        const rawIndex = Math.round(current.scrollLeft / width);
+        const newIndex = Math.max(0, Math.min(itemCount - 1, rawIndex));
+        if (newIndex === lastIndexRef.current) return;
+        lastIndexRef.current = newIndex;
+        onSettleRef.current?.(newIndex);
+      }, debounceMs);
+    }
+    el.addEventListener('scroll', handleScroll, { passive: true });
+    return () => {
+      el.removeEventListener('scroll', handleScroll);
+      if (timerRef.current) clearTimeout(timerRef.current);
+    };
+  }, [itemCount, debounceMs]);
+
+  function scrollToIndex(index: number, behavior: ScrollBehavior = 'smooth') {
+    const el = scrollRef.current;
+    if (!el) return;
+    lastIndexRef.current = index;
+    el.scrollTo({ left: index * el.clientWidth, behavior });
+  }
+
+  return { scrollRef, scrollToIndex };
+}

package/src/hooks/useSwipeReveal.ts

@@ -0,0 +1,107 @@
+'use client';
+
+import { useRef } from 'react';
+import type { PointerEvent as ReactPointerEvent, RefObject } from 'react';
+
+export interface UseSwipeRevealOptions {
+  /** Max reveal distance in px — the row translates by `-revealWidth` when open. */
+  revealWidth: number;
+  /** Whether the reveal is currently open. Controlled by the caller so a
+   *  list of rows can coordinate "only one open at a time" — this hook has
+   *  no open state of its own. */
+  open: boolean;
+  /** Called when a drag releases past the halfway point — the caller should
+   *  set `open` to true. */
+  onOpen: () => void;
+  /** Called when a drag releases before the halfway point — the caller
+   *  should set `open` to false. */
+  onClose: () => void;
+  /** Skip entirely (hooks can't be called conditionally). */
+  disabled?: boolean;
+}
+
+export interface UseSwipeRevealHandlers {
+  onPointerDown: (e: ReactPointerEvent) => void;
+  onPointerMove: (e: ReactPointerEvent) => void;
+  onPointerUp: (e: ReactPointerEvent) => void;
+  onPointerCancel: (e: ReactPointerEvent) => void;
+}
+
+export interface UseSwipeRevealResult {
+  /** Attach to the swipeable row element — the hook writes a live transform
+   *  to it directly during the drag (not via React state) so the row tracks
+   *  the finger at 60fps with no re-render per pointermove. */
+  rowRef: RefObject<HTMLDivElement | null>;
+  /** Spread onto the row's pointer event handlers. */
+  handlers: UseSwipeRevealHandlers;
+}
+
+/**
+ * useSwipeReveal — horizontal swipe-to-reveal (e.g. Done/Delete actions
+ * behind a list row), extracted from `sovereign-tasks`'s `TaskItem`/
+ * `ListSidebar`, which independently hand-rolled the identical gesture twice
+ * with only `revealWidth` differing (RFC 0079, epic task 9.20).
+ *
+ * Axis-locks on the first 8px of movement (so a vertical scroll or the
+ * carousel's own horizontal swipe-between-slides gesture isn't hijacked by a
+ * diagonal drag) and only resolves to open/closed on release, past the
+ * halfway point of `revealWidth`.
+ */
+export function useSwipeReveal({
+  revealWidth,
+  open,
+  onOpen,
+  onClose,
+  disabled = false,
+}: UseSwipeRevealOptions): UseSwipeRevealResult {
+  const rowRef = useRef<HTMLDivElement>(null);
+  const dragState = useRef<{
+    startX: number;
+    startY: number;
+    locked: 'horizontal' | 'vertical' | null;
+  } | null>(null);
+
+  function onPointerDown(e: ReactPointerEvent) {
+    if (disabled) return;
+    e.currentTarget.setPointerCapture(e.pointerId);
+    dragState.current = { startX: e.clientX, startY: e.clientY, locked: null };
+  }
+
+  function onPointerMove(e: ReactPointerEvent) {
+    const state = dragState.current;
+    if (!state) return;
+    const dx = e.clientX - state.startX;
+    const dy = e.clientY - state.startY;
+    if (!state.locked) {
+      if (Math.abs(dx) < 8 && Math.abs(dy) < 8) return;
+      state.locked = Math.abs(dx) > Math.abs(dy) ? 'horizontal' : 'vertical';
+    }
+    if (state.locked !== 'horizontal') return;
+    e.preventDefault();
+    const base = open ? -revealWidth : 0;
+    const next = Math.min(0, Math.max(-revealWidth, base + dx));
+    if (rowRef.current) rowRef.current.style.transform = `translateX(${next}px)`;
+  }
+
+  function releaseDrag(e: ReactPointerEvent) {
+    const state = dragState.current;
+    dragState.current = null;
+    if (!state || state.locked !== 'horizontal') return;
+    const dx = e.clientX - state.startX;
+    const base = open ? -revealWidth : 0;
+    const finalX = Math.min(0, Math.max(-revealWidth, base + dx));
+    if (rowRef.current) rowRef.current.style.transform = '';
+    if (finalX < -revealWidth / 2) onOpen();
+    else onClose();
+  }
+
+  return {
+    rowRef,
+    handlers: {
+      onPointerDown,
+      onPointerMove,
+      onPointerUp: releaseDrag,
+      onPointerCancel: releaseDrag,
+    },
+  };
+}

package/src/index.ts

@@ -1,3 +1,7 @@
+export { LegalLinks } from './components/LegalLinks/LegalLinks';
+export type { LegalLinksProps } from './components/LegalLinks/LegalLinks';
+export { Markdown } from './components/Markdown/Markdown';
+export type { MarkdownProps } from './components/Markdown/Markdown';
 export { Badge } from './components/Badge/Badge';
 export type { BadgeProps, BadgeVariant, BadgeStatus } from './components/Badge/Badge';
 export { Icon } from './components/Icon/Icon';
@@ -57,14 +61,34 @@ export { FormField } from './components/FormField/FormField';
 export type { FormFieldProps, FormFieldRenderProps } from './components/FormField/FormField';
 export { PageHeader } from './components/PageHeader/PageHeader';
 export type { PageHeaderProps } from './components/PageHeader/PageHeader';
+export { PageContainer } from './components/PageContainer/PageContainer';
+export type { PageContainerProps } from './components/PageContainer/PageContainer';
+export { MobileHeader } from './components/MobileHeader/MobileHeader';
+export type { MobileHeaderProps } from './components/MobileHeader/MobileHeader';
+export { MobileFooter } from './components/MobileFooter/MobileFooter';
+export type { MobileFooterProps, FooterIcon } from './components/MobileFooter/MobileFooter';
+export { MobileAppsDrawer } from './components/MobileAppsDrawer/MobileAppsDrawer';
+export type {
+  MobileAppsDrawerProps,
+  MobileAppsDrawerItem,
+} from './components/MobileAppsDrawer/MobileAppsDrawer';
 export { EmptyState } from './components/EmptyState/EmptyState';
 export type { EmptyStateProps } from './components/EmptyState/EmptyState';
+export { OfflineGate } from './components/OfflineGate/OfflineGate';
+export type { OfflineGateProps } from './components/OfflineGate/OfflineGate';
+export { DeviceOnlyGate } from './components/DeviceOnlyGate/DeviceOnlyGate';
+export type { DeviceOnlyGateProps } from './components/DeviceOnlyGate/DeviceOnlyGate';
+export { DeviceStorageKeyGate } from './components/DeviceStorageKeyGate/DeviceStorageKeyGate';
+export type {
+  DeviceStorageKeyGateProps,
+  DeviceStorageKeyGateStatus,
+} from './components/DeviceStorageKeyGate/DeviceStorageKeyGate';
 export { Spinner } from './components/Spinner/Spinner';
 export type { SpinnerProps } from './components/Spinner/Spinner';
 export { Avatar } from './components/Avatar/Avatar';
 export type { AvatarProps } from './components/Avatar/Avatar';
 export { NavTabs } from './components/NavTabs/NavTabs';
-export type { NavTabsProps, NavTabItem } from './components/NavTabs/NavTabs';
+export type { NavTabsProps, NavTabItem, NavTabLinkProps } from './components/NavTabs/NavTabs';
 export { Tooltip } from './components/Tooltip/Tooltip';
 export type { TooltipProps } from './components/Tooltip/Tooltip';
 export { Checkbox } from './components/Checkbox/Checkbox';
@@ -184,7 +208,44 @@ export {
   useDoubleTapHandler,
   useSingleOrDoubleTap,
   useIsMobile,
+  useIsOffline,
+  useOfflineTileState,
   useCommitOnEnterOrBlur,
+  useSwipeReveal,
+  useSnapCarousel,
+  useResponsiveLayout,
+  useCarouselRouteSync,
 } from './hooks';
+export type { OfflineTileState } from './hooks';
 export { MOBILE_BREAKPOINT_PX } from './hooks';
-export type { UseLongPressOptions, LongPressHandlers, CommitOnEnterOrBlurHandlers } from './hooks';
+export type {
+  UseLongPressOptions,
+  LongPressHandlers,
+  CommitOnEnterOrBlurHandlers,
+  UseSwipeRevealOptions,
+  UseSwipeRevealHandlers,
+  UseSwipeRevealResult,
+  UseSnapCarouselOptions,
+  UseSnapCarouselResult,
+  UseResponsiveLayoutOptions,
+  UseResponsiveLayoutResult,
+  UseCarouselRouteSyncOptions,
+  UseCarouselRouteSyncResult,
+} from './hooks';
+export { ResponsiveSurface } from './components/ResponsiveSurface/ResponsiveSurface';
+export type { ResponsiveSurfaceProps } from './components/ResponsiveSurface/ResponsiveSurface';
+export { SwipableMobileCarouselDots } from './components/SwipableMobileCarouselDots/SwipableMobileCarouselDots';
+export type { SwipableMobileCarouselDotsProps } from './components/SwipableMobileCarouselDots/SwipableMobileCarouselDots';
+export { SwipableMobileCarousel } from './components/SwipableMobileCarousel/SwipableMobileCarousel';
+export type {
+  SwipableMobileCarouselProps,
+  SwipableMobileCarouselIndicatorProps,
+} from './components/SwipableMobileCarousel/SwipableMobileCarousel';
+export { SwipableMobileCarouselSlide } from './components/SwipableMobileCarousel/SwipableMobileCarouselSlide';
+export type { SwipableMobileCarouselSlideProps } from './components/SwipableMobileCarousel/SwipableMobileCarouselSlide';
+export { SwipableMobileCarouselSlideHeader } from './components/SwipableMobileCarousel/SwipableMobileCarouselSlideHeader';
+export type { SwipableMobileCarouselSlideHeaderProps } from './components/SwipableMobileCarousel/SwipableMobileCarouselSlideHeader';
+export { SwipableMobileCarouselSlideBody } from './components/SwipableMobileCarousel/SwipableMobileCarouselSlideBody';
+export type { SwipableMobileCarouselSlideBodyProps } from './components/SwipableMobileCarousel/SwipableMobileCarouselSlideBody';
+export { SwipableMobileCarouselSlideFooter } from './components/SwipableMobileCarousel/SwipableMobileCarouselSlideFooter';
+export type { SwipableMobileCarouselSlideFooterProps } from './components/SwipableMobileCarousel/SwipableMobileCarouselSlideFooter';

package/src/overlay-shell.ts

@@ -0,0 +1,94 @@
+'use client';
+
+import { type RefObject, useEffect, useRef } from 'react';
+import { lockBodyScroll, unlockBodyScroll } from './scroll-lock';
+
+// Internal to the design system — not exported from `index.ts`. Shared by
+// Dialog, Drawer, and Sheet, which independently implemented identical
+// scrim/focus-trap/Escape/scroll-lock logic before this consolidation
+// (RFC 0079, epic task 9.19). ConfirmDialog is deliberately not migrated
+// here — it stays on the native `<dialog>` element, which already provides
+// equivalent focus-trap/backdrop semantics more reliably for its use case.
+
+export const OVERLAY_FOCUSABLE_SELECTOR =
+  'a[href], button:not([disabled]), textarea:not([disabled]), input:not([disabled]), select:not([disabled]), [tabindex]:not([tabindex="-1"])';
+
+/**
+ * Locks document scroll for the whole mounted lifetime of an overlay
+ * (including its exit animation), not just while `open` — so the background
+ * can't scroll while the panel is still visibly sliding/fading away.
+ * Ref-counted via `scroll-lock.ts` so nested overlays (e.g. a confirmation
+ * dialog inside an overlay-shell plugin) don't release the lock while a
+ * sibling is still open.
+ */
+export function useOverlayScrollLock(mounted: boolean): void {
+  useEffect(() => {
+    if (!mounted) return;
+    lockBodyScroll();
+    return unlockBodyScroll;
+  }, [mounted]);
+}
+
+/**
+ * Captures the element focused before the overlay opened, moves focus into
+ * the panel when `active` becomes true, and restores the original focus on
+ * cleanup. Callers pass whichever prop should trigger the capture — `open`
+ * for Dialog/Drawer, `mounted` for Sheet (which restores focus on unmount
+ * rather than on the raw `open` transition).
+ */
+export function useOverlayFocusCapture(
+  panelRef: RefObject<HTMLElement | null>,
+  active: boolean,
+): void {
+  const previouslyFocused = useRef<HTMLElement | null>(null);
+  useEffect(() => {
+    if (!active) return;
+    previouslyFocused.current = document.activeElement as HTMLElement | null;
+    const panel = panelRef.current;
+    const first = panel?.querySelector<HTMLElement>(OVERLAY_FOCUSABLE_SELECTOR);
+    (first ?? panel)?.focus();
+    return () => previouslyFocused.current?.focus();
+  }, [active, panelRef]);
+}
+
+/**
+ * Escape-to-close plus a Tab focus trap cycling within the panel. Attached
+ * at `document` level so no keyboard listener is needed on the overlay's own
+ * element (which would trigger `jsx-a11y/no-noninteractive-element-interactions`).
+ */
+export function useOverlayKeyboardTrap(
+  panelRef: RefObject<HTMLElement | null>,
+  open: boolean,
+  onClose: () => void,
+): void {
+  useEffect(() => {
+    if (!open) return;
+    function handleKeyDown(e: KeyboardEvent) {
+      if (e.key === 'Escape') {
+        e.stopPropagation();
+        onClose();
+        return;
+      }
+      if (e.key !== 'Tab') return;
+      const panel = panelRef.current;
+      if (!panel) return;
+      const focusable = [...panel.querySelectorAll<HTMLElement>(OVERLAY_FOCUSABLE_SELECTOR)];
+      const first = focusable[0];
+      const last = focusable.at(-1);
+      if (!first || !last) {
+        e.preventDefault();
+        return;
+      }
+      const active = document.activeElement;
+      if (e.shiftKey && active === first) {
+        e.preventDefault();
+        last.focus();
+      } else if (!e.shiftKey && active === last) {
+        e.preventDefault();
+        first.focus();
+      }
+    }
+    document.addEventListener('keydown', handleKeyDown);
+    return () => document.removeEventListener('keydown', handleKeyDown);
+  }, [open, onClose, panelRef]);
+}