@sovereignfs/ui 0.41.0 → 0.54.0

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

@@ -0,0 +1,87 @@
+// @vitest-environment jsdom
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { act, cleanup, render } from '@testing-library/react';
+import { useResponsiveLayout } from '../useResponsiveLayout';
+
+// Same matchMedia mocking approach as useIsMobile.test.tsx, since this hook
+// is a thin wrapper over it and must not diverge in SSR/breakpoint behavior.
+let changeHandler: ((e: MediaQueryListEvent) => void) | null = null;
+let matches = false;
+let lastQuery = '';
+
+function installMatchMedia() {
+  changeHandler = null;
+  vi.stubGlobal(
+    'matchMedia',
+    vi.fn().mockImplementation((query: string) => {
+      lastQuery = query;
+      return {
+        matches,
+        media: query,
+        addEventListener: (_: string, cb: (e: MediaQueryListEvent) => void) => {
+          changeHandler = cb;
+        },
+        removeEventListener: vi.fn(),
+        addListener: vi.fn(),
+        removeListener: vi.fn(),
+        dispatchEvent: vi.fn(),
+      };
+    }),
+  );
+}
+
+function Harness({ breakpointPx }: { breakpointPx?: number }) {
+  const { isMobile, value } = useResponsiveLayout({
+    web: 'web-tree',
+    mobile: 'mobile-tree',
+    breakpointPx,
+  });
+  return (
+    <span data-testid="out" data-is-mobile={String(isMobile)}>
+      {value}
+    </span>
+  );
+}
+
+describe('useResponsiveLayout', () => {
+  beforeEach(() => {
+    matches = false;
+    installMatchMedia();
+  });
+  afterEach(() => {
+    vi.unstubAllGlobals();
+    cleanup();
+  });
+
+  it('defaults to the web value before/without a mobile match (SSR-safe default)', () => {
+    matches = false;
+    installMatchMedia();
+    const { getByTestId } = render(<Harness />);
+    expect(getByTestId('out').textContent).toBe('web-tree');
+    expect(getByTestId('out').dataset.isMobile).toBe('false');
+  });
+
+  it('picks the mobile value once matchMedia reports a match', () => {
+    matches = true;
+    installMatchMedia();
+    const { getByTestId } = render(<Harness />);
+    expect(getByTestId('out').textContent).toBe('mobile-tree');
+    expect(getByTestId('out').dataset.isMobile).toBe('true');
+  });
+
+  it('swaps live when the viewport crosses the breakpoint', () => {
+    matches = false;
+    installMatchMedia();
+    const { getByTestId } = render(<Harness />);
+    expect(getByTestId('out').textContent).toBe('web-tree');
+    act(() => changeHandler?.({ matches: true } as MediaQueryListEvent));
+    expect(getByTestId('out').textContent).toBe('mobile-tree');
+  });
+
+  it('passes a custom breakpointPx straight through to useIsMobile', () => {
+    matches = false;
+    installMatchMedia();
+    render(<Harness breakpointPx={640} />);
+    expect(lastQuery).toBe('(max-width: 640px)');
+  });
+});

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

@@ -0,0 +1,93 @@
+// @vitest-environment jsdom
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { act, cleanup, fireEvent, render } from '@testing-library/react';
+import { useSnapCarousel, type UseSnapCarouselOptions } from '../useSnapCarousel';
+
+// jsdom doesn't implement scrollTo on elements.
+beforeEach(() => {
+  vi.useFakeTimers();
+  if (!Element.prototype.scrollTo) {
+    Element.prototype.scrollTo = vi.fn();
+  }
+});
+
+afterEach(() => {
+  vi.runOnlyPendingTimers();
+  vi.useRealTimers();
+  cleanup();
+});
+
+function setLayout(el: HTMLElement, clientWidth: number, scrollLeft: number) {
+  Object.defineProperty(el, 'clientWidth', { value: clientWidth, configurable: true });
+  Object.defineProperty(el, 'scrollLeft', { value: scrollLeft, configurable: true });
+}
+
+function Harness(
+  props: UseSnapCarouselOptions & { onScrollTo?: (fn: (i: number) => void) => void },
+) {
+  const { onScrollTo, ...options } = props;
+  const { scrollRef, scrollToIndex } = useSnapCarousel(options);
+  onScrollTo?.(scrollToIndex);
+  return <div data-testid="scroller" ref={scrollRef} />;
+}
+
+describe('useSnapCarousel', () => {
+  it('calls onSettle with the new index after the debounce window', () => {
+    const onSettle = vi.fn();
+    const { getByTestId } = render(<Harness itemCount={3} onSettle={onSettle} debounceMs={120} />);
+    const el = getByTestId('scroller');
+    setLayout(el, 300, 300); // scrollLeft 300 / width 300 -> index 1
+    fireEvent.scroll(el);
+    expect(onSettle).not.toHaveBeenCalled();
+    act(() => void vi.advanceTimersByTime(120));
+    expect(onSettle).toHaveBeenCalledWith(1);
+  });
+
+  it('debounces repeated scroll events into a single settle call', () => {
+    const onSettle = vi.fn();
+    const { getByTestId } = render(<Harness itemCount={3} onSettle={onSettle} debounceMs={120} />);
+    const el = getByTestId('scroller');
+    setLayout(el, 300, 0);
+    fireEvent.scroll(el);
+    act(() => void vi.advanceTimersByTime(60));
+    setLayout(el, 300, 300);
+    fireEvent.scroll(el);
+    act(() => void vi.advanceTimersByTime(120));
+    expect(onSettle).toHaveBeenCalledOnce();
+    expect(onSettle).toHaveBeenCalledWith(1);
+  });
+
+  it('does not call onSettle again for the same index', () => {
+    const onSettle = vi.fn();
+    const { getByTestId } = render(<Harness itemCount={3} onSettle={onSettle} debounceMs={120} />);
+    const el = getByTestId('scroller');
+    setLayout(el, 300, 300);
+    fireEvent.scroll(el);
+    act(() => void vi.advanceTimersByTime(120));
+    fireEvent.scroll(el);
+    act(() => void vi.advanceTimersByTime(120));
+    expect(onSettle).toHaveBeenCalledOnce();
+  });
+
+  it('clamps the settled index within [0, itemCount - 1]', () => {
+    const onSettle = vi.fn();
+    const { getByTestId } = render(<Harness itemCount={2} onSettle={onSettle} debounceMs={120} />);
+    const el = getByTestId('scroller');
+    setLayout(el, 300, 900); // rounds to index 3, clamps to itemCount - 1 = 1
+    fireEvent.scroll(el);
+    act(() => void vi.advanceTimersByTime(120));
+    expect(onSettle).toHaveBeenCalledWith(1);
+  });
+
+  it('scrollToIndex scrolls the container to the target slide', () => {
+    let scrollToIndex: ((index: number) => void) | undefined;
+    const { getByTestId } = render(
+      <Harness itemCount={3} onScrollTo={(fn) => (scrollToIndex = fn)} />,
+    );
+    const el = getByTestId('scroller');
+    setLayout(el, 400, 0);
+    const spy = vi.spyOn(el, 'scrollTo');
+    scrollToIndex?.(2);
+    expect(spy).toHaveBeenCalledWith({ left: 800, behavior: 'smooth' });
+  });
+});

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

@@ -0,0 +1,110 @@
+// @vitest-environment jsdom
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { cleanup, fireEvent, render } from '@testing-library/react';
+import { useSwipeReveal, type UseSwipeRevealOptions } from '../useSwipeReveal';
+
+// 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: UseSwipeRevealOptions) {
+  const { rowRef, handlers } = useSwipeReveal(props);
+  return (
+    <div data-testid="row" ref={rowRef} {...handlers}>
+      row
+    </div>
+  );
+}
+
+function pointer(x: number, y: number) {
+  return { clientX: x, clientY: y, pointerId: 1 };
+}
+
+describe('useSwipeReveal', () => {
+  it('calls onOpen when a horizontal drag crosses the halfway point', () => {
+    const onOpen = vi.fn();
+    const onClose = vi.fn();
+    const { getByTestId } = render(
+      <Harness revealWidth={100} open={false} onOpen={onOpen} onClose={onClose} />,
+    );
+    const el = getByTestId('row');
+    fireEvent.pointerDown(el, pointer(0, 0));
+    fireEvent.pointerMove(el, pointer(-60, 0));
+    fireEvent.pointerUp(el, pointer(-60, 0));
+    expect(onOpen).toHaveBeenCalledOnce();
+    expect(onClose).not.toHaveBeenCalled();
+  });
+
+  it('calls onClose when the drag does not cross the halfway point', () => {
+    const onOpen = vi.fn();
+    const onClose = vi.fn();
+    const { getByTestId } = render(
+      <Harness revealWidth={100} open={false} onOpen={onOpen} onClose={onClose} />,
+    );
+    const el = getByTestId('row');
+    fireEvent.pointerDown(el, pointer(0, 0));
+    fireEvent.pointerMove(el, pointer(-20, 0));
+    fireEvent.pointerUp(el, pointer(-20, 0));
+    expect(onClose).toHaveBeenCalledOnce();
+    expect(onOpen).not.toHaveBeenCalled();
+  });
+
+  it('locks to vertical and ignores a mostly-vertical drag', () => {
+    const onOpen = vi.fn();
+    const onClose = vi.fn();
+    const { getByTestId } = render(
+      <Harness revealWidth={100} open={false} onOpen={onOpen} onClose={onClose} />,
+    );
+    const el = getByTestId('row');
+    fireEvent.pointerDown(el, pointer(0, 0));
+    fireEvent.pointerMove(el, pointer(2, 60));
+    fireEvent.pointerUp(el, pointer(2, 60));
+    expect(onOpen).not.toHaveBeenCalled();
+    expect(onClose).not.toHaveBeenCalled();
+  });
+
+  it('does nothing when disabled', () => {
+    const onOpen = vi.fn();
+    const onClose = vi.fn();
+    const { getByTestId } = render(
+      <Harness revealWidth={100} open={false} onOpen={onOpen} onClose={onClose} disabled />,
+    );
+    const el = getByTestId('row');
+    fireEvent.pointerDown(el, pointer(0, 0));
+    fireEvent.pointerMove(el, pointer(-60, 0));
+    fireEvent.pointerUp(el, pointer(-60, 0));
+    expect(onOpen).not.toHaveBeenCalled();
+    expect(onClose).not.toHaveBeenCalled();
+  });
+
+  it('closes from an already-open state when dragged back past halfway', () => {
+    const onOpen = vi.fn();
+    const onClose = vi.fn();
+    const { getByTestId } = render(
+      <Harness revealWidth={100} open onOpen={onOpen} onClose={onClose} />,
+    );
+    const el = getByTestId('row');
+    fireEvent.pointerDown(el, pointer(0, 0));
+    fireEvent.pointerMove(el, pointer(60, 0));
+    fireEvent.pointerUp(el, pointer(60, 0));
+    expect(onClose).toHaveBeenCalledOnce();
+    expect(onOpen).not.toHaveBeenCalled();
+  });
+
+  it('ignores pointerup without a preceding pointerdown', () => {
+    const onOpen = vi.fn();
+    const onClose = vi.fn();
+    const { getByTestId } = render(
+      <Harness revealWidth={100} open={false} onOpen={onOpen} onClose={onClose} />,
+    );
+    fireEvent.pointerUp(getByTestId('row'), pointer(-60, 0));
+    expect(onOpen).not.toHaveBeenCalled();
+    expect(onClose).not.toHaveBeenCalled();
+  });
+});

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