@sovereignfs/ui 0.54.0 → 0.83.1

package/src/hooks/useSnapCarousel.ts

@@ -1,6 +1,6 @@
 'use client';
 
-import { useEffect, useRef } from 'react';
+import { useCallback, useEffect, useRef, useState } from 'react';
 import type { RefObject } from 'react';
 
 export interface UseSnapCarouselOptions {
@@ -14,6 +14,14 @@ export interface UseSnapCarouselOptions {
    *  extracted from. Debounced rather than keyed to the `scrollend` event,
    *  which pre-17.4 iOS Safari/WKWebView doesn't support. */
   debounceMs?: number;
+  /** The index to seed `liveIndex` with before any scroll event has fired —
+   *  must match whatever the caller initially scrolls/renders to (typically
+   *  the same value used for `SwipableMobileCarousel`'s `activeIndex`).
+   *  Without this, `liveIndex` would start at 0 regardless of where the
+   *  carousel actually opens (e.g. a deep link straight to slide 8),
+   *  briefly unmounting every slide except the first few until the first
+   *  scroll event arrives to correct it. */
+  initialIndex?: number;
 }
 
 export interface UseSnapCarouselResult {
@@ -21,6 +29,11 @@ export interface UseSnapCarouselResult {
   scrollRef: RefObject<HTMLDivElement | null>;
   /** Imperatively scrolls the container to a slide index. */
   scrollToIndex: (index: number, behavior?: ScrollBehavior) => void;
+  /** The slide index nearest the container's *current* scroll position,
+   *  updated synchronously on every `scroll` event — not debounced, and not
+   *  the same thing as the last-reported `onSettle` index. See its own
+   *  assignment below for why a consumer needs both. */
+  liveIndex: number;
 }
 
 /**
@@ -35,21 +48,128 @@ export function useSnapCarousel({
   itemCount,
   onSettle,
   debounceMs = 120,
+  initialIndex = 0,
 }: UseSnapCarouselOptions): UseSnapCarouselResult {
   const scrollRef = useRef<HTMLDivElement>(null);
   const timerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
   const lastIndexRef = useRef<number | null>(null);
+  // Cleanup for scrollToIndex's scroll-snap-suspension workaround (see that
+  // function's own comment) — lets an overlapping call cancel a still-
+  // pending restore from an earlier one instead of two racing to re-enable
+  // snap at the wrong time.
+  const restoreSnapRef = useRef<(() => void) | null>(null);
+  // Real-time (synchronous, not debounced) read of "which slide is the
+  // container's scroll position nearest right now." A fast flick can carry
+  // native scroll-snap momentum straight past an intermediate slide to one
+  // two or more away in a single continuous gesture — the settle-detection
+  // above deliberately still waits out the full debounce window before
+  // reporting that via onSettle (so it can tell a real settle from drift,
+  // see chainTrustedRef's own comment). But `SwipableMobileCarousel`'s mount
+  // window is keyed off the *settled* index, so during that debounce window
+  // the slide the container had already scrolled to — visually, right now —
+  // was never in the mount window and had never been rendered at all: a
+  // real, reproduced-on-video gap where the carousel shows nothing (not even
+  // a loading skeleton) for the length of one full debounce cycle after a
+  // multi-slide flick. `liveIndex` exists so the mount window can track
+  // wherever the container currently visually is, independent of whether
+  // that position has been confirmed as a real settle yet.
+  const [liveIndex, setLiveIndex] = useState(initialIndex);
   // 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;
+  // Timestamp (Date.now()) of the most recent real input (touch, wheel/
+  // trackpad, or a mouse drag) — see the doc comment above `noteGesture`
+  // below for why settle-detection is gated on this instead of firing for
+  // any `scroll` event.
+  const lastGestureAtRef = useRef(0);
+  // Whether the *current* run of scroll events (since the last time the
+  // container went quiet for debounceMs) was kicked off by real input. Set
+  // at the start of each run by checking lastGestureAtRef, then held for the
+  // whole run regardless of how long it continues — see `handleScroll`'s own
+  // comment for why this can't just be "was there a gesture event within the
+  // last debounceMs" re-checked at settle time: native momentum/snap-
+  // correction after a real swipe can keep producing scroll events for
+  // longer than any fixed slack window without a single further touch event,
+  // and a first version of this fix that compared elapsed time against a
+  // fixed `debounceMs * 2` slack dropped exactly those settles — silently
+  // leaving activeIndex stuck on the old slide while the container had
+  // already visually scrolled to the new one, which is worse than the bug
+  // being fixed (the mount window then unmounts whatever's actually on
+  // screen, since it's keyed off the now-stale index — a blank, un-
+  // recoverable-without-reload carousel). `noteGesture` can also upgrade
+  // trust mid-run, for a real gesture that starts while an untrusted run's
+  // debounce timer is still pending.
+  const chainTrustedRef = useRef(false);
 
   useEffect(() => {
     const el = scrollRef.current;
     if (!el) return;
+    // A `scroll-snap-type: mandatory` container has no legitimate reason to
+    // move on its own — every real position change is either (a) driven by
+    // the finger/wheel/mouse still in contact, (b) the browser's own
+    // momentum/snap-correction settling immediately after release, or (c)
+    // our own scrollToIndex() call, which already updates lastIndexRef
+    // synchronously so settle-detection for it is a no-op regardless. A
+    // `scroll` event that arrives with none of the above recently active is
+    // drift, not a settle — most commonly a slide's own content changing
+    // size while it's still loading, which can nudge scrollLeft by a
+    // fraction of a slide width. Previously any such event that happened to
+    // round to a different index than the currently active one was treated
+    // as a genuine settle, silently "auto-swiping" the carousel back to
+    // whatever slide that rounding landed on — reproduced live via a user
+    // screen recording (swiping forward to a still-loading slide, then the
+    // carousel snapping back to the previous one ~150ms later with no
+    // further touch input) and confirmed via a unit test showing a second,
+    // unrelated `scroll` event alone was enough to trigger a second,
+    // contradicting `onSettle` call.
+    function noteGesture() {
+      lastGestureAtRef.current = Date.now();
+      // Upgrades the currently in-flight run too, not just the next one —
+      // covers a real gesture starting while an untrusted run's debounce
+      // timer (started by an earlier, unrelated drift scroll event) is
+      // still pending.
+      chainTrustedRef.current = true;
+    }
+    function handlePointerMove(event: PointerEvent) {
+      // Ignore hover — only a held button (mouse drag) counts as input.
+      if (event.buttons) noteGesture();
+    }
+    function updateLiveIndexNow() {
+      const current = scrollRef.current;
+      if (!current) return;
+      const width = current.clientWidth;
+      if (!width) return;
+      const idx = Math.max(0, Math.min(itemCount - 1, Math.round(current.scrollLeft / width)));
+      // Bails out (same reference, no re-render) when the index hasn't
+      // actually changed — a scroll container fires many `scroll` events
+      // while passing through the same slide's territory, not just at its
+      // boundaries. Synchronous rather than rAF-throttled: jsdom (this
+      // hook's own test environment) doesn't reliably run
+      // requestAnimationFrame callbacks under fake timers, and browsers
+      // already coalesce native scroll events to roughly once per frame on
+      // their own, so a second throttle here bought nothing but test
+      // fragility.
+      setLiveIndex((prev) => (prev === idx ? prev : idx));
+    }
     function handleScroll() {
-      if (timerRef.current) clearTimeout(timerRef.current);
+      updateLiveIndexNow();
+      if (timerRef.current) {
+        clearTimeout(timerRef.current);
+      } else {
+        // No debounce timer pending means the container had been fully
+        // quiet — this scroll event starts a new run. Trust it only if real
+        // input happened recently; once granted, trust holds for the whole
+        // run (see chainTrustedRef's own doc comment above) no matter how
+        // long momentum/snap-correction keeps producing scroll events after
+        // this point with no further input.
+        chainTrustedRef.current = Date.now() - lastGestureAtRef.current <= debounceMs;
+      }
       timerRef.current = setTimeout(() => {
+        timerRef.current = null;
+        const trusted = chainTrustedRef.current;
+        chainTrustedRef.current = false;
+        if (!trusted) return;
         const current = scrollRef.current;
         if (!current) return;
         const width = current.clientWidth;
@@ -62,18 +182,103 @@ export function useSnapCarousel({
       }, debounceMs);
     }
     el.addEventListener('scroll', handleScroll, { passive: true });
+    el.addEventListener('touchstart', noteGesture, { passive: true });
+    el.addEventListener('touchmove', noteGesture, { passive: true });
+    el.addEventListener('wheel', noteGesture, { passive: true });
+    el.addEventListener('pointerdown', noteGesture);
+    el.addEventListener('pointermove', handlePointerMove);
     return () => {
       el.removeEventListener('scroll', handleScroll);
+      el.removeEventListener('touchstart', noteGesture);
+      el.removeEventListener('touchmove', noteGesture);
+      el.removeEventListener('wheel', noteGesture);
+      el.removeEventListener('pointerdown', noteGesture);
+      el.removeEventListener('pointermove', handlePointerMove);
       if (timerRef.current) clearTimeout(timerRef.current);
     };
   }, [itemCount, debounceMs]);
 
-  function scrollToIndex(index: number, behavior: ScrollBehavior = 'smooth') {
+  // Memoized so its reference stays stable across renders — SwipableMobile
+  // Carousel depends on it in a useEffect deps array alongside
+  // clampedActiveIndex, and an unmemoized function recreated on every
+  // render (e.g. every time liveIndex itself changes below) would make that
+  // effect re-fire on every scroll, calling scrollToIndex again and — since
+  // it also resets liveIndex to whatever index it was told to scroll to —
+  // immediately stomping the very liveIndex update that triggered the
+  // re-render in the first place. Caught by this hook's own test suite
+  // (a live-index test that failed until this was memoized), not just
+  // reasoned about — worth keeping as a regression guard, not just a
+  // performance nicety.
+  const scrollToIndex = useCallback((index: number, behavior: ScrollBehavior = 'smooth') => {
     const el = scrollRef.current;
     if (!el) return;
     lastIndexRef.current = index;
-    el.scrollTo({ left: index * el.clientWidth, behavior });
-  }
+    // Belt-and-suspenders: a real scrollTo() also fires its own 'scroll'
+    // event, which updates liveIndex synchronously too — but jsdom's mocked
+    // scrollTo (this hook's own test environment) doesn't, and the initial
+    // mount scroll / reorder-jump fix both need the target slide mounted
+    // immediately regardless.
+    setLiveIndex(index);
+
+    // Cancel any still-pending restore from an earlier smooth scroll before
+    // starting this one, so they don't race to re-enable snap at the wrong
+    // time (e.g. a dot-jump fired while a previous jump's restore timer is
+    // still pending).
+    if (restoreSnapRef.current) {
+      restoreSnapRef.current();
+      restoreSnapRef.current = null;
+    }
+
+    const target = index * el.clientWidth;
+
+    if (behavior === 'smooth') {
+      // A programmatic `scrollTo({ behavior: 'smooth' })` on this element
+      // can silently do nothing at all — not a jank/timing issue, the
+      // container just never moves, with no error and no scroll events.
+      // Reproduced live via the design system's own footer/dot-jump
+      // navigation in sovereign-tasks (routes external activeIndex changes
+      // through this exact path): the identical call with
+      // `behavior: 'instant'` moved the container immediately, `'smooth'`
+      // did nothing — reproduced both with `scroll-snap-type: mandatory` in
+      // place *and*, isolating further, on a plain scroll-snap-free element
+      // in the same environment, so `scroll-snap-type` alone doesn't fully
+      // explain it. Two independent mitigations, since the exact trigger
+      // isn't nailed down: (1) suspend snap for the duration of the
+      // animated scroll on the chance it *is* a snap/animation conflict in
+      // some engines; (2) below, a correctness-net instant scrollTo if the
+      // container still isn't at the target once the animation should have
+      // finished — cheap and idempotent when the smooth scroll *did* work
+      // (already at the target, the check is a no-op), and the difference
+      // between a graceful animation and an abrupt correction if it didn't,
+      // rather than a carousel that silently desyncs forever with nothing
+      // to ever correct it.
+      // Narrowed, stable binding for the closures below — TS can't carry
+      // the `if (!el) return` narrowing of the outer `el` into a nested
+      // function declaration.
+      const scrollEl = el;
+      const prevSnapType = scrollEl.style.scrollSnapType;
+      scrollEl.style.scrollSnapType = 'none';
+      let settled = false;
+      // Matches typical browser smooth-scroll duration; also the fallback
+      // for engines with no `scrollend` (pre-17.4 iOS Safari/WKWebView).
+      const timeoutId = setTimeout(finish, 500);
+      function finish() {
+        if (settled) return;
+        settled = true;
+        clearTimeout(timeoutId);
+        scrollEl.removeEventListener('scrollend', finish);
+        scrollEl.style.scrollSnapType = prevSnapType;
+        restoreSnapRef.current = null;
+        if (Math.abs(scrollEl.scrollLeft - target) > 1) {
+          scrollEl.scrollTo({ left: target, behavior: 'instant' });
+        }
+      }
+      scrollEl.addEventListener('scrollend', finish, { once: true });
+      restoreSnapRef.current = finish;
+    }
+
+    el.scrollTo({ left: target, behavior });
+  }, []);
 
-  return { scrollRef, scrollToIndex };
+  return { scrollRef, scrollToIndex, liveIndex };
 }

package/src/hooks/useSwipeStack.ts

@@ -0,0 +1,235 @@
+'use client';
+
+import { useRef } from 'react';
+import type { PointerEvent as ReactPointerEvent, RefObject } from 'react';
+
+export type SwipeDirection = 'left' | 'right' | 'up' | 'down';
+
+/** Minimum effective drag distance (px) before a direction is read at all —
+ *  keeps a tap or a tiny jitter from registering as a swipe. Matches
+ *  useSwipeReveal's own deadzone. */
+const DEADZONE_PX = 8;
+
+/** Horizontal drag distance (px) that reaches the full tilt cap. */
+const ROTATION_RANGE_PX = 240;
+const ROTATION_MAX_DEG = 12;
+
+/** Duration (ms) of both the commit fling-out and the spring-back-under-
+ *  threshold transition. Exported so SwipeStack can hold a just-committed
+ *  card in place for exactly this long before advancing to the next one. */
+export const SWIPE_STACK_TRANSITION_MS = 220;
+
+const ALL_DIRECTIONS: readonly SwipeDirection[] = ['left', 'right', 'up', 'down'];
+
+/** Unit vector per direction — reused for both the fling-out offset and the
+ *  tilt sign (horizontal directions tilt, vertical ones don't: x is ±1/0). */
+const UNIT_VECTOR: Record<SwipeDirection, readonly [number, number]> = {
+  left: [-1, 0],
+  right: [1, 0],
+  up: [0, -1],
+  down: [0, 1],
+};
+
+export interface UseSwipeStackOptions {
+  /** Directions this drag can move toward and resolve to. A direction left
+   *  out of this list is a wall, not just an unreachable outcome — the card
+   *  will not visually move that way at all (see clampToLiveDirections). */
+  directions: readonly SwipeDirection[];
+  /** Effective distance (px) a drag must cross before release commits to
+   *  that direction instead of springing back. No velocity component — a
+   *  fast short flick under this distance still springs back. */
+  threshold?: number;
+  /** Fires once, synchronously, when a drag (or triggerCommit) resolves to
+   *  a live direction past threshold. This hook has already started the
+   *  fling-out animation on cardRef's element by the time this is called —
+   *  the caller only needs to react to the outcome, not drive the motion. */
+  onCommit: (direction: SwipeDirection) => void;
+  /** Disables both the drag and triggerCommit — e.g. while there is no
+   *  current card to act on. */
+  disabled?: boolean;
+}
+
+export interface UseSwipeStackHandlers {
+  onPointerDown: (e: ReactPointerEvent) => void;
+  onPointerMove: (e: ReactPointerEvent) => void;
+  onPointerUp: (e: ReactPointerEvent) => void;
+  onPointerCancel: (e: ReactPointerEvent) => void;
+}
+
+export interface UseSwipeStackResult {
+  /** Attach to the card element that should translate/rotate with the drag. */
+  cardRef: RefObject<HTMLDivElement | null>;
+  /** Attach to the ancestor of both the card and any direction-stamp
+   *  overlays. The hook writes live drag progress here as CSS custom
+   *  properties (--sv-stack-progress-left/right/up/down, each 0–1) so
+   *  stamps — siblings of the card, not the card itself — can react without
+   *  a re-render per pointermove. */
+  wrapRef: RefObject<HTMLDivElement | null>;
+  handlers: UseSwipeStackHandlers;
+  /** CSS touch-action for the card, derived from which directions are live
+   *  — an axis with nothing configured on it stays native (pan-x/pan-y) so
+   *  a page can still scroll through a stack that only uses the other axis;
+   *  `none` only once both axes are actually needed. */
+  touchAction: string;
+  /** Programmatically commits a direction — the same fling animation and
+   *  onCommit call a real drag past threshold would produce. Backs the
+   *  non-gesture fallback buttons: they are not a separate code path, just
+   *  a different way to call this. No-ops if the direction isn't live or
+   *  the hook is disabled. */
+  triggerCommit: (direction: SwipeDirection) => void;
+}
+
+function clamp(value: number, min: number, max: number): number {
+  return Math.min(max, Math.max(min, value));
+}
+
+/** Zeroes out movement toward any direction not in `live` — the card
+ *  behaves as if a wall exists there instead of just being an unreachable
+ *  commit outcome, so e.g. a left/right-only stack never visually drifts
+ *  vertically. */
+function clampToLiveDirections(
+  dx: number,
+  dy: number,
+  live: ReadonlySet<SwipeDirection>,
+): [number, number] {
+  const x = dx > 0 ? (live.has('right') ? dx : 0) : live.has('left') ? dx : 0;
+  const y = dy > 0 ? (live.has('down') ? dy : 0) : live.has('up') ? dy : 0;
+  return [x, y];
+}
+
+function resolveDirection(
+  dx: number,
+  dy: number,
+  live: ReadonlySet<SwipeDirection>,
+): SwipeDirection | null {
+  const absX = Math.abs(dx);
+  const absY = Math.abs(dy);
+  if (absX < DEADZONE_PX && absY < DEADZONE_PX) return null;
+  const candidate: SwipeDirection =
+    absX > absY ? (dx > 0 ? 'right' : 'left') : dy > 0 ? 'down' : 'up';
+  return live.has(candidate) ? candidate : null;
+}
+
+/**
+ * useSwipeStack — hand-rolled 4-directional free drag, extending
+ * useSwipeReveal's pattern (raw Pointer Events, a deadzone, transform
+ * written straight to a ref, resolved only on release) from one axis with
+ * two outcomes to four directions with a tilt. Threshold-only on purpose,
+ * matching useSwipeReveal — no velocity tracking, so a fast short flick
+ * under `threshold` still springs back.
+ */
+export function useSwipeStack({
+  directions,
+  threshold = 96,
+  onCommit,
+  disabled = false,
+}: UseSwipeStackOptions): UseSwipeStackResult {
+  const cardRef = useRef<HTMLDivElement>(null);
+  const wrapRef = useRef<HTMLDivElement>(null);
+  const dragState = useRef<{ startX: number; startY: number } | null>(null);
+  const live = new Set(directions);
+
+  function writeProgress(direction: SwipeDirection | null, progress: number) {
+    const wrap = wrapRef.current;
+    if (!wrap) return;
+    for (const d of ALL_DIRECTIONS) {
+      wrap.style.setProperty(`--sv-stack-progress-${d}`, d === direction ? String(progress) : '0');
+    }
+  }
+
+  function writeTransform(dx: number, dy: number) {
+    const card = cardRef.current;
+    if (!card) return;
+    const rotation = clamp(
+      (dx / ROTATION_RANGE_PX) * ROTATION_MAX_DEG,
+      -ROTATION_MAX_DEG,
+      ROTATION_MAX_DEG,
+    );
+    card.style.transform = `translate(${dx}px, ${dy}px) rotate(${rotation}deg)`;
+  }
+
+  function springBack() {
+    const card = cardRef.current;
+    if (!card) return;
+    card.style.transition = `transform ${SWIPE_STACK_TRANSITION_MS}ms ease`;
+    card.style.transform = '';
+  }
+
+  function flingOut(direction: SwipeDirection) {
+    const card = cardRef.current;
+    if (!card) return;
+    const distance = 1.4 * Math.max(window.innerWidth, window.innerHeight);
+    const [ux, uy] = UNIT_VECTOR[direction];
+    card.style.transition = `transform ${SWIPE_STACK_TRANSITION_MS}ms ease`;
+    card.style.transform = `translate(${ux * distance}px, ${uy * distance}px) rotate(${ux * ROTATION_MAX_DEG}deg)`;
+  }
+
+  function onPointerDown(e: ReactPointerEvent) {
+    if (disabled) return;
+    e.currentTarget.setPointerCapture(e.pointerId);
+    dragState.current = { startX: e.clientX, startY: e.clientY };
+    if (cardRef.current) cardRef.current.style.transition = '';
+  }
+
+  function onPointerMove(e: ReactPointerEvent) {
+    const state = dragState.current;
+    if (!state) return;
+    const [dx, dy] = clampToLiveDirections(
+      e.clientX - state.startX,
+      e.clientY - state.startY,
+      live,
+    );
+    writeTransform(dx, dy);
+    const direction = resolveDirection(dx, dy, live);
+    if (direction) e.preventDefault();
+    writeProgress(
+      direction,
+      direction ? clamp(Math.max(Math.abs(dx), Math.abs(dy)) / threshold, 0, 1) : 0,
+    );
+  }
+
+  function release(e: ReactPointerEvent) {
+    const state = dragState.current;
+    dragState.current = null;
+    if (!state) return;
+    const [dx, dy] = clampToLiveDirections(
+      e.clientX - state.startX,
+      e.clientY - state.startY,
+      live,
+    );
+    const direction = resolveDirection(dx, dy, live);
+    writeProgress(null, 0);
+    const distance = Math.max(Math.abs(dx), Math.abs(dy));
+    if (direction && distance >= threshold) {
+      flingOut(direction);
+      onCommit(direction);
+    } else {
+      springBack();
+    }
+  }
+
+  function triggerCommit(direction: SwipeDirection) {
+    if (disabled || !live.has(direction)) return;
+    flingOut(direction);
+    onCommit(direction);
+  }
+
+  const hasHorizontal = live.has('left') || live.has('right');
+  const hasVertical = live.has('up') || live.has('down');
+  const touchAction =
+    hasHorizontal && hasVertical
+      ? 'none'
+      : hasHorizontal
+        ? 'pan-y'
+        : hasVertical
+          ? 'pan-x'
+          : 'auto';
+
+  return {
+    cardRef,
+    wrapRef,
+    handlers: { onPointerDown, onPointerMove, onPointerUp: release, onPointerCancel: release },
+    touchAction,
+    triggerCommit,
+  };
+}

package/src/index.ts

@@ -1,5 +1,7 @@
 export { LegalLinks } from './components/LegalLinks/LegalLinks';
 export type { LegalLinksProps } from './components/LegalLinks/LegalLinks';
+export { ConsentPrompt } from './components/ConsentPrompt/ConsentPrompt';
+export type { ConsentPromptProps } from './components/ConsentPrompt/ConsentPrompt';
 export { Markdown } from './components/Markdown/Markdown';
 export type { MarkdownProps } from './components/Markdown/Markdown';
 export { Badge } from './components/Badge/Badge';
@@ -53,16 +55,34 @@ export type {
   MenuSeparator,
   MenuEntry,
 } from './components/Menu/Menu';
+export { UserMenu } from './components/UserMenu/UserMenu';
+export type { UserMenuProps, UserMenuItem } from './components/UserMenu/UserMenu';
+export { AppsLauncher } from './components/AppsLauncher/AppsLauncher';
+export type { AppsLauncherProps, AppsLauncherItem } from './components/AppsLauncher/AppsLauncher';
+export { NotificationsPanel } from './components/NotificationsPanel/NotificationsPanel';
+export type {
+  NotificationsPanelProps,
+  NotificationsPanelItem,
+} from './components/NotificationsPanel/NotificationsPanel';
 export { ToastProvider, useToast } from './components/Toast/Toast';
 export type { ToastItem, ToastContextValue } from './components/Toast/Toast';
 export { Card } from './components/Card/Card';
 export type { CardProps } from './components/Card/Card';
+
+export { CardTile, CardTileGrid, NewCardTile } from './components/CardTile/CardTile';
+export type {
+  CardTileProps,
+  CardTileGridProps,
+  NewCardTileProps,
+} from './components/CardTile/CardTile';
 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 { Header } from './components/Header/Header';
+export type { HeaderProps, HeaderPlugin } from './components/Header/Header';
 export { MobileHeader } from './components/MobileHeader/MobileHeader';
 export type { MobileHeaderProps } from './components/MobileHeader/MobileHeader';
 export { MobileFooter } from './components/MobileFooter/MobileFooter';
@@ -172,6 +192,10 @@ export { Combobox } from './components/Combobox/Combobox';
 export type { ComboboxProps, ComboboxOption } from './components/Combobox/Combobox';
 export { DragHandleRow } from './components/DragHandleRow/DragHandleRow';
 export type { DragHandleRowProps } from './components/DragHandleRow/DragHandleRow';
+export { GripIcon } from './components/GripIcon/GripIcon';
+export type { GripIconProps } from './components/GripIcon/GripIcon';
+export { StepStrip } from './components/StepStrip/StepStrip';
+export type { StepStripProps, StepStripItem } from './components/StepStrip/StepStrip';
 export { FileDropzone } from './components/FileDropzone/FileDropzone';
 export type { FileDropzoneProps } from './components/FileDropzone/FileDropzone';
 export { Calendar } from './components/Calendar/Calendar';
@@ -185,6 +209,8 @@ export type {
 } from './components/SuggestionInput/SuggestionInput';
 export { IconPicker } from './components/IconPicker/IconPicker';
 export type { IconPickerProps } from './components/IconPicker/IconPicker';
+export { ColorPicker } from './components/ColorPicker/ColorPicker';
+export type { ColorPickerProps, ColorPickerSwatch } from './components/ColorPicker/ColorPicker';
 export { QuantityStepper } from './components/QuantityStepper/QuantityStepper';
 export type { QuantityStepperProps } from './components/QuantityStepper/QuantityStepper';
 export { CheckableListRow } from './components/CheckableListRow/CheckableListRow';
@@ -215,9 +241,12 @@ export {
   useSnapCarousel,
   useResponsiveLayout,
   useCarouselRouteSync,
+  useReorderSensors,
+  shouldHandleDndEvent,
+  useSwipeStack,
 } from './hooks';
 export type { OfflineTileState } from './hooks';
-export { MOBILE_BREAKPOINT_PX } from './hooks';
+export { MOBILE_BREAKPOINT_PX, SWIPE_STACK_TRANSITION_MS } from './hooks';
 export type {
   UseLongPressOptions,
   LongPressHandlers,
@@ -231,6 +260,11 @@ export type {
   UseResponsiveLayoutResult,
   UseCarouselRouteSyncOptions,
   UseCarouselRouteSyncResult,
+  UseReorderSensorsOptions,
+  SwipeDirection,
+  UseSwipeStackOptions,
+  UseSwipeStackHandlers,
+  UseSwipeStackResult,
 } from './hooks';
 export { ResponsiveSurface } from './components/ResponsiveSurface/ResponsiveSurface';
 export type { ResponsiveSurfaceProps } from './components/ResponsiveSurface/ResponsiveSurface';
@@ -249,3 +283,29 @@ export { SwipableMobileCarouselSlideBody } from './components/SwipableMobileCaro
 export type { SwipableMobileCarouselSlideBodyProps } from './components/SwipableMobileCarousel/SwipableMobileCarouselSlideBody';
 export { SwipableMobileCarouselSlideFooter } from './components/SwipableMobileCarousel/SwipableMobileCarouselSlideFooter';
 export type { SwipableMobileCarouselSlideFooterProps } from './components/SwipableMobileCarousel/SwipableMobileCarouselSlideFooter';
+export { SwipeStack } from './components/SwipeStack/SwipeStack';
+export type { SwipeStackProps, SwipeDirectionMeta } from './components/SwipeStack/SwipeStack';
+export { SwipeStackCard } from './components/SwipeStack/SwipeStackCard';
+export type { SwipeStackCardProps } from './components/SwipeStack/SwipeStackCard';
+export { ThreeColumnLayout } from './components/ThreeColumnLayout/ThreeColumnLayout';
+export type { ThreeColumnLayoutProps } from './components/ThreeColumnLayout/ThreeColumnLayout';
+export { HeaderFooterLayout } from './components/HeaderFooterLayout/HeaderFooterLayout';
+export type { HeaderFooterLayoutProps } from './components/HeaderFooterLayout/HeaderFooterLayout';
+export { RootLayout } from './components/RootLayout/RootLayout';
+export type { RootLayoutProps, RootLayoutVariant } from './components/RootLayout/RootLayout';
+export { PageLayout } from './components/PageLayout/PageLayout';
+export type { PageLayoutProps, PageLayoutPadding } from './components/PageLayout/PageLayout';
+export { NavList } from './components/NavList/NavList';
+export type {
+  NavListProps,
+  NavListGroup,
+  NavListItem,
+  NavListLinkProps,
+} from './components/NavList/NavList';
+
+// Theme presets (RFC 0094) — the closed, built-in preset data. Consumed
+// directly by runtime/src/instance-style.ts (RFC 0095); Storybook and
+// standalone consumers instead import the generated
+// '@sovereignfs/ui/tokens/theme-presets.css'.
+export { THEME_PRESETS, THEME_PRESET_NAMES } from './tokens/theme-presets';
+export type { ThemePresetName, ThemePresetTokens } from './tokens/theme-presets';