@sovereignfs/ui 0.45.0 → 0.83.1

package/src/hooks/__tests__/useSwipeStack.test.tsx

@@ -0,0 +1,155 @@
+// @vitest-environment jsdom
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { cleanup, fireEvent, render } from '@testing-library/react';
+import { useSwipeStack, type SwipeDirection, type UseSwipeStackOptions } from '../useSwipeStack';
+
+// jsdom doesn't implement pointer capture — stub it as a no-op so
+// `e.currentTarget.setPointerCapture(...)` doesn't throw.
+beforeEach(() => {
+  if (!HTMLElement.prototype.setPointerCapture) {
+    HTMLElement.prototype.setPointerCapture = vi.fn();
+  }
+});
+
+afterEach(cleanup);
+
+function Harness(props: UseSwipeStackOptions & { triggerDirection?: SwipeDirection }) {
+  const { triggerDirection, ...options } = props;
+  const { cardRef, wrapRef, handlers, touchAction, triggerCommit } = useSwipeStack(options);
+  return (
+    <div data-testid="wrap" ref={wrapRef}>
+      <div data-testid="card" ref={cardRef} data-touch-action={touchAction} {...handlers}>
+        card
+      </div>
+      {triggerDirection && (
+        <button data-testid="trigger" onClick={() => triggerCommit(triggerDirection)}>
+          trigger
+        </button>
+      )}
+    </div>
+  );
+}
+
+function pointer(x: number, y: number) {
+  return { clientX: x, clientY: y, pointerId: 1 };
+}
+
+function drag(el: HTMLElement, dx: number, dy: number) {
+  fireEvent.pointerDown(el, pointer(0, 0));
+  fireEvent.pointerMove(el, pointer(dx, dy));
+  fireEvent.pointerUp(el, pointer(dx, dy));
+}
+
+describe('useSwipeStack', () => {
+  it('commits when a drag crosses threshold in a live direction', () => {
+    const onCommit = vi.fn();
+    const { getByTestId } = render(
+      <Harness directions={['up', 'down', 'left', 'right']} threshold={100} onCommit={onCommit} />,
+    );
+    drag(getByTestId('card'), 0, -120);
+    expect(onCommit).toHaveBeenCalledWith('up');
+    expect(onCommit).toHaveBeenCalledOnce();
+  });
+
+  it('springs back without committing when under threshold', () => {
+    const onCommit = vi.fn();
+    const { getByTestId } = render(
+      <Harness directions={['up', 'down', 'left', 'right']} threshold={100} onCommit={onCommit} />,
+    );
+    drag(getByTestId('card'), 0, -40);
+    expect(onCommit).not.toHaveBeenCalled();
+  });
+
+  it('does not commit within the deadzone even if threshold is set very low', () => {
+    const onCommit = vi.fn();
+    const { getByTestId } = render(
+      <Harness directions={['up']} threshold={2} onCommit={onCommit} />,
+    );
+    drag(getByTestId('card'), 0, -5);
+    expect(onCommit).not.toHaveBeenCalled();
+  });
+
+  it('treats a non-configured direction as a wall — no commit even past what would be threshold distance', () => {
+    const onCommit = vi.fn();
+    const { getByTestId } = render(
+      <Harness directions={['up', 'down']} threshold={100} onCommit={onCommit} />,
+    );
+    drag(getByTestId('card'), 150, 0);
+    expect(onCommit).not.toHaveBeenCalled();
+  });
+
+  it('does nothing when disabled', () => {
+    const onCommit = vi.fn();
+    const { getByTestId } = render(
+      <Harness
+        directions={['up', 'down', 'left', 'right']}
+        threshold={100}
+        onCommit={onCommit}
+        disabled
+      />,
+    );
+    drag(getByTestId('card'), 0, -150);
+    expect(onCommit).not.toHaveBeenCalled();
+  });
+
+  it('ignores pointerup without a preceding pointerdown', () => {
+    const onCommit = vi.fn();
+    const { getByTestId } = render(
+      <Harness directions={['up', 'down', 'left', 'right']} threshold={100} onCommit={onCommit} />,
+    );
+    fireEvent.pointerUp(getByTestId('card'), pointer(0, -150));
+    expect(onCommit).not.toHaveBeenCalled();
+  });
+
+  it('triggerCommit commits a live direction without a drag', () => {
+    const onCommit = vi.fn();
+    const { getByTestId } = render(
+      <Harness directions={['up']} onCommit={onCommit} triggerDirection="up" />,
+    );
+    fireEvent.click(getByTestId('trigger'));
+    expect(onCommit).toHaveBeenCalledWith('up');
+    expect(onCommit).toHaveBeenCalledOnce();
+  });
+
+  it('triggerCommit no-ops for a direction that is not live', () => {
+    const onCommit = vi.fn();
+    const { getByTestId } = render(
+      <Harness directions={['up']} onCommit={onCommit} triggerDirection="down" />,
+    );
+    fireEvent.click(getByTestId('trigger'));
+    expect(onCommit).not.toHaveBeenCalled();
+  });
+
+  it('triggerCommit does nothing when disabled', () => {
+    const onCommit = vi.fn();
+    const { getByTestId } = render(
+      <Harness directions={['up']} onCommit={onCommit} triggerDirection="up" disabled />,
+    );
+    fireEvent.click(getByTestId('trigger'));
+    expect(onCommit).not.toHaveBeenCalled();
+  });
+
+  describe('touchAction', () => {
+    it('is none when both axes have a live direction', () => {
+      const { getByTestId } = render(
+        <Harness directions={['left', 'right', 'up', 'down']} onCommit={vi.fn()} />,
+      );
+      expect(getByTestId('card').dataset.touchAction).toBe('none');
+    });
+
+    it('is pan-y when only horizontal directions are live', () => {
+      const { getByTestId } = render(<Harness directions={['left', 'right']} onCommit={vi.fn()} />);
+      expect(getByTestId('card').dataset.touchAction).toBe('pan-y');
+    });
+
+    it('is pan-x when only vertical directions are live', () => {
+      const { getByTestId } = render(<Harness directions={['up', 'down']} onCommit={vi.fn()} />);
+      expect(getByTestId('card').dataset.touchAction).toBe('pan-x');
+    });
+
+    it('is auto when no directions are live', () => {
+      const { getByTestId } = render(<Harness directions={[]} onCommit={vi.fn()} />);
+      expect(getByTestId('card').dataset.touchAction).toBe('auto');
+    });
+  });
+});

package/src/hooks/index.ts

@@ -2,5 +2,32 @@ 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';
+export { useReorderSensors, shouldHandleDndEvent } from './useReorderSensors';
+export type { UseReorderSensorsOptions } from './useReorderSensors';
+export { useSwipeStack, SWIPE_STACK_TRANSITION_MS } from './useSwipeStack';
+export type {
+  SwipeDirection,
+  UseSwipeStackOptions,
+  UseSwipeStackHandlers,
+  UseSwipeStackResult,
+} from './useSwipeStack';

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/usePublishShellChromeHeight.ts

@@ -0,0 +1,96 @@
+'use client';
+
+import { useLayoutEffect } from 'react';
+import type { RefObject } from 'react';
+
+/**
+ * Internal implementation detail of `MobileHeader`/`MobileFooter` — not part
+ * of the package's public surface (not re-exported from `hooks/index.ts`).
+ *
+ * Measures `ref`'s own rendered height and publishes it as an inline
+ * `var(--sv-shell-header-height|--sv-shell-footer-height)` override on
+ * `#sv-app-shell` (the runtime shell's stable root id, `runtime/app/
+ * (platform)/layout.tsx`), removing it on unmount. This is what makes a
+ * *self-rendered* `MobileHeader`/`MobileFooter` — the sanctioned pattern for
+ * a plugin that opts out of the platform's own chrome via
+ * `shellConfig.mobileHeader`/`mobileFooter: false` (RFC 0075/0088) — work
+ * correctly with `Sheet`/`Drawer`/`Dialog`, which all size themselves against
+ * these same two variables so they stop above/below the chrome instead of
+ * sliding underneath it.
+ *
+ * Before this existed, only the *platform's own* header/footer had its
+ * height accounted for (a fixed CSS `calc()` in `shell.module.css`, driven by
+ * `data-mobile-header-hidden`/`data-mobile-footer-hidden`, which collapses
+ * the variable to `0px` whenever a plugin hides that chrome) — a plugin
+ * self-rendering its own via this same component instead had no path to tell
+ * the shell what its real height was, and silently inherited that `0px`.
+ * `Sheet`/`Drawer` then extended full-height, and since the header/footer's
+ * own `z-index` (101) beats an overlay's (100), the chrome visibly covered
+ * the overlay's last ~60px. First found and fixed ad hoc in `sovereign-tasks`
+ * (measuring in the plugin itself, `getBoundingClientRect()` in a
+ * `useLayoutEffect`); moved here so every consumer of these two components —
+ * present and future, in this repo or externally maintained — gets it for
+ * free, without having to know the mechanism exists. See
+ * `docs/architecture-rules.md` for the full rule.
+ *
+ * Deliberately **not** `ResizeObserver`: in live testing (both this repo's
+ * own Chromium-based browser-preview tooling and a real WebKit iOS Simulator
+ * session) a freshly created `ResizeObserver` never fired its callback even
+ * once for an already-rendered, stably-sized, non-zero element — cause not
+ * fully root-caused. A synchronous `getBoundingClientRect()` read in
+ * `useLayoutEffect`, re-run on `window`'s `resize` event, worked immediately
+ * and reliably in both environments instead.
+ *
+ * No-ops safely wherever `#sv-app-shell` doesn't exist (Storybook, a unit
+ * test, or any host other than the platform's own runtime shell) — every CSS
+ * consumer reads these variables with a `60px` fallback, so an absent
+ * override is harmless.
+ *
+ * For `--sv-shell-header-height` specifically, this also mirrors the same
+ * measured height onto `--sv-dialog-inset-top` on `:root` (`document.
+ * documentElement`, not `#sv-app-shell`) — `Dialog`'s mobile `.scrim` is
+ * `position: fixed` and reads that variable for its own `top` offset, and
+ * per `globals.css`'s own comment, iOS Safari has a documented quirk where a
+ * `position: fixed` element inherits custom properties from `:root` rather
+ * than from its DOM ancestors, so a value set only on `#sv-app-shell` (an
+ * ancestor, not `:root`) silently never reaches it there. The platform's own
+ * header already keeps `--sv-dialog-inset-top` correct this way, via
+ * `ClientShell.tsx`'s own `syncViewport()` — but that function is part of
+ * `(platform)/layout.tsx` and never runs for a `shell: minimal` plugin, so a
+ * self-rendered `MobileHeader` (this hook's entire reason to exist) had no
+ * equivalent, and `--sv-dialog-inset-top` silently kept `globals.css`'s
+ * hardcoded platform-header-height fallback (60px) regardless of this
+ * header's real height. Found live in `sovereign-plugin-kanban`: its
+ * self-rendered header measures 69px, so its card-detail `Dialog` opened
+ * with a real, reproducible ~9px misalignment against that header's own
+ * bottom edge — confirmed via `getBoundingClientRect()` on both elements,
+ * not just visually. */
+export function usePublishShellChromeHeight(
+  ref: RefObject<HTMLElement | null>,
+  cssVariable: '--sv-shell-header-height' | '--sv-shell-footer-height',
+) {
+  useLayoutEffect(() => {
+    const el = ref.current;
+    if (!el) return;
+
+    function publish() {
+      const shell = document.getElementById('sv-app-shell');
+      if (!shell || !el) return;
+      const height = `${el.getBoundingClientRect().height}px`;
+      shell.style.setProperty(cssVariable, height);
+      if (cssVariable === '--sv-shell-header-height') {
+        document.documentElement.style.setProperty('--sv-dialog-inset-top', height);
+      }
+    }
+
+    publish();
+    window.addEventListener('resize', publish);
+    return () => {
+      window.removeEventListener('resize', publish);
+      document.getElementById('sv-app-shell')?.style.removeProperty(cssVariable);
+      if (cssVariable === '--sv-shell-header-height') {
+        document.documentElement.style.removeProperty('--sv-dialog-inset-top');
+      }
+    };
+  }, [ref, cssVariable]);
+}

package/src/hooks/useReorderSensors.ts

@@ -0,0 +1,88 @@
+'use client';
+
+import {
+  KeyboardSensor,
+  MouseSensor as LibMouseSensor,
+  TouchSensor as LibTouchSensor,
+  useSensor,
+  useSensors,
+} from '@dnd-kit/core';
+import { sortableKeyboardCoordinates } from '@dnd-kit/sortable';
+import type { MouseEvent as ReactMouseEvent, TouchEvent as ReactTouchEvent } from 'react';
+
+/** Plain pointer drag (desktop, handle-initiated). */
+const DEFAULT_MOUSE_ACTIVATION_DISTANCE_PX = 8;
+
+/** Long-press-to-lift on touch. `delay` is how long a still hold takes before
+ *  the row lifts; `tolerance` is how far the finger may drift during that
+ *  hold before it's treated as a scroll instead — a finger that moves further
+ *  than this within the delay window cancels activation and the native
+ *  vertical scroll wins. */
+const DEFAULT_TOUCH_ACTIVATION_DELAY_MS = 300;
+const DEFAULT_TOUCH_ACTIVATION_TOLERANCE_PX = 8;
+
+/**
+ * True when a drag should be allowed to start from `target`. Refused when
+ * `target` sits inside an element marked `data-no-dnd` — a nested control
+ * (e.g. a visibility toggle) opts out so tapping it fires its own handler
+ * instead of lifting the row. Exported standalone so it's unit-testable
+ * without spinning up dnd-kit.
+ */
+export function shouldHandleDndEvent(target: EventTarget | null): boolean {
+  if (!(target instanceof Element)) return true;
+  return target.closest('[data-no-dnd]') === null;
+}
+
+export interface UseReorderSensorsOptions {
+  mouseActivationDistancePx?: number;
+  touchActivationDelayMs?: number;
+  touchActivationTolerancePx?: number;
+}
+
+// dnd-kit's documented pattern for scoping sensor activation to specific
+// elements: subclass the built-in sensor and replace its static `activators`
+// with a handler that inspects the originating event's target before
+// deferring to the base activation logic (distance/delay/tolerance), which
+// dnd-kit re-checks internally regardless of what this returns.
+class MouseSensor extends LibMouseSensor {
+  static override activators = [
+    {
+      eventName: 'onMouseDown' as const,
+      handler: ({ nativeEvent: event }: ReactMouseEvent) => shouldHandleDndEvent(event.target),
+    },
+  ];
+}
+
+class TouchSensor extends LibTouchSensor {
+  static override activators = [
+    {
+      eventName: 'onTouchStart' as const,
+      handler: ({ nativeEvent: event }: ReactTouchEvent) => shouldHandleDndEvent(event.target),
+    },
+  ];
+}
+
+/**
+ * Sensor set for a `data-no-dnd`-aware drag-reorder list — MouseSensor for
+ * desktop's handle-initiated drag, TouchSensor for mobile's long-press lift
+ * (fixes reordering being unusable on iOS PWA/Safari, which never implements
+ * the native HTML5 Drag-and-Drop API for touch input), KeyboardSensor
+ * unchanged. A bare call keeps the historical 8px/300ms/8px defaults.
+ */
+export function useReorderSensors(options: UseReorderSensorsOptions = {}) {
+  const {
+    mouseActivationDistancePx = DEFAULT_MOUSE_ACTIVATION_DISTANCE_PX,
+    touchActivationDelayMs = DEFAULT_TOUCH_ACTIVATION_DELAY_MS,
+    touchActivationTolerancePx = DEFAULT_TOUCH_ACTIVATION_TOLERANCE_PX,
+  } = options;
+  return useSensors(
+    useSensor(MouseSensor, { activationConstraint: { distance: mouseActivationDistancePx } }),
+    useSensor(TouchSensor, {
+      activationConstraint: {
+        delay: touchActivationDelayMs,
+        tolerance: touchActivationTolerancePx,
+      },
+    }),
+    useSensor(KeyboardSensor, { coordinateGetter: sortableKeyboardCoordinates }),
+  );
+}

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 };
+}