@sovereignfs/ui 0.23.0 → 0.33.1

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

@@ -0,0 +1,80 @@
+// @vitest-environment jsdom
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { act, cleanup, render } from '@testing-library/react';
+import { MOBILE_BREAKPOINT_PX, useIsMobile } from '../useIsMobile';
+
+// Capture the registered change listener so a test can drive a viewport change.
+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({ breakpoint }: { breakpoint?: number }) {
+  const isMobile = useIsMobile(breakpoint);
+  return <span data-testid="out">{String(isMobile)}</span>;
+}
+
+describe('useIsMobile', () => {
+  beforeEach(() => {
+    matches = false;
+    installMatchMedia();
+  });
+  afterEach(() => {
+    vi.unstubAllGlobals();
+    cleanup();
+  });
+
+  it('exports the canonical 768px breakpoint', () => {
+    expect(MOBILE_BREAKPOINT_PX).toBe(768);
+  });
+
+  it('defaults to the canonical breakpoint in its query', () => {
+    matches = true;
+    installMatchMedia();
+    render(<Harness />);
+    expect(lastQuery).toBe('(max-width: 768px)');
+  });
+
+  it('reflects the initial matchMedia result after mount', () => {
+    matches = true;
+    installMatchMedia();
+    const { getByTestId } = render(<Harness />);
+    expect(getByTestId('out').textContent).toBe('true');
+  });
+
+  it('updates when the viewport crosses the breakpoint', () => {
+    matches = false;
+    installMatchMedia();
+    const { getByTestId } = render(<Harness />);
+    expect(getByTestId('out').textContent).toBe('false');
+    act(() => changeHandler?.({ matches: true } as MediaQueryListEvent));
+    expect(getByTestId('out').textContent).toBe('true');
+  });
+
+  it('honours a custom breakpoint override', () => {
+    matches = false;
+    installMatchMedia();
+    render(<Harness breakpoint={640} />);
+    expect(lastQuery).toBe('(max-width: 640px)');
+  });
+});

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

@@ -0,0 +1,158 @@
+// @vitest-environment jsdom
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { act, cleanup, fireEvent, render } from '@testing-library/react';
+import { useLongPress, type UseLongPressOptions } from '../useLongPress';
+
+// Configurable matchMedia mock — usePrefersCoarsePointer reads
+// '(pointer: coarse)', and the SSR-safe hooks read it on mount. Default to a
+// coarse (touch) device so the suppression styles are exercised; individual
+// tests override `coarse` where they assert the desktop path.
+let coarse = true;
+function installMatchMedia() {
+  vi.stubGlobal(
+    'matchMedia',
+    vi.fn().mockImplementation((query: string) => ({
+      matches: query.includes('pointer: coarse') ? coarse : false,
+      media: query,
+      addEventListener: vi.fn(),
+      removeEventListener: vi.fn(),
+      addListener: vi.fn(),
+      removeListener: vi.fn(),
+      dispatchEvent: vi.fn(),
+    })),
+  );
+}
+
+// A tiny harness component: spreads the hook's handlers onto a div so we can
+// fire real pointer events at it via Testing Library.
+function Harness(props: UseLongPressOptions & { testId?: string }) {
+  const { testId = 'target', ...options } = props;
+  const handlers = useLongPress(options);
+  return (
+    <div data-testid={testId} {...handlers}>
+      target
+    </div>
+  );
+}
+
+function pointer(type: 'touch' | 'mouse', x = 0, y = 0) {
+  return { pointerType: type, clientX: x, clientY: y };
+}
+
+describe('useLongPress', () => {
+  beforeEach(() => {
+    coarse = true;
+    installMatchMedia();
+    vi.useFakeTimers();
+  });
+
+  afterEach(() => {
+    vi.runOnlyPendingTimers();
+    vi.useRealTimers();
+    vi.unstubAllGlobals();
+    cleanup();
+  });
+
+  it('fires onLongPress after the delay on a touch press held still', () => {
+    const onLongPress = vi.fn();
+    const { getByTestId } = render(<Harness onLongPress={onLongPress} delay={500} />);
+    fireEvent.pointerDown(getByTestId('target'), pointer('touch'));
+    expect(onLongPress).not.toHaveBeenCalled();
+    act(() => void vi.advanceTimersByTime(500));
+    expect(onLongPress).toHaveBeenCalledOnce();
+  });
+
+  it('does not arm for a mouse pointer (desktop keeps its own affordance)', () => {
+    const onLongPress = vi.fn();
+    const { getByTestId } = render(<Harness onLongPress={onLongPress} delay={500} />);
+    fireEvent.pointerDown(getByTestId('target'), pointer('mouse'));
+    act(() => void vi.advanceTimersByTime(1000));
+    expect(onLongPress).not.toHaveBeenCalled();
+  });
+
+  it('tolerates finger jitter within moveTolerance', () => {
+    const onLongPress = vi.fn();
+    const { getByTestId } = render(
+      <Harness onLongPress={onLongPress} delay={500} moveTolerance={10} />,
+    );
+    const el = getByTestId('target');
+    fireEvent.pointerDown(el, pointer('touch', 0, 0));
+    fireEvent.pointerMove(el, pointer('touch', 4, 4)); // ~5.7px < 10
+    act(() => void vi.advanceTimersByTime(500));
+    expect(onLongPress).toHaveBeenCalledOnce();
+  });
+
+  it('cancels when movement exceeds moveTolerance', () => {
+    const onLongPress = vi.fn();
+    const { getByTestId } = render(
+      <Harness onLongPress={onLongPress} delay={500} moveTolerance={10} />,
+    );
+    const el = getByTestId('target');
+    fireEvent.pointerDown(el, pointer('touch', 0, 0));
+    fireEvent.pointerMove(el, pointer('touch', 20, 0)); // 20px > 10
+    act(() => void vi.advanceTimersByTime(500));
+    expect(onLongPress).not.toHaveBeenCalled();
+  });
+
+  it('cancels on pointercancel (touch converted to scroll)', () => {
+    const onLongPress = vi.fn();
+    const { getByTestId } = render(<Harness onLongPress={onLongPress} delay={500} />);
+    const el = getByTestId('target');
+    fireEvent.pointerDown(el, pointer('touch'));
+    fireEvent.pointerCancel(el, pointer('touch'));
+    act(() => void vi.advanceTimersByTime(500));
+    expect(onLongPress).not.toHaveBeenCalled();
+  });
+
+  it('suppresses the click that may follow, but only for a bounded window', () => {
+    const onLongPress = vi.fn();
+    const { getByTestId } = render(
+      <Harness onLongPress={onLongPress} delay={500} suppressClickMs={700} />,
+    );
+    const el = getByTestId('target');
+    fireEvent.pointerDown(el, pointer('touch'));
+    act(() => void vi.advanceTimersByTime(500));
+    expect(onLongPress).toHaveBeenCalledOnce();
+
+    // A click arriving right after the long-press is swallowed.
+    const suppressed = fireEvent.click(el);
+    expect(suppressed).toBe(false); // preventDefault called → fireEvent returns false
+
+    // After the suppression window, a genuinely unrelated later tap is NOT eaten.
+    act(() => void vi.advanceTimersByTime(800));
+    const allowed = fireEvent.click(el);
+    expect(allowed).toBe(true);
+  });
+
+  it('prevents the OS context menu while a press is pending', () => {
+    const { getByTestId } = render(<Harness onLongPress={vi.fn()} delay={500} />);
+    const el = getByTestId('target');
+    fireEvent.pointerDown(el, pointer('touch'));
+    const prevented = fireEvent.contextMenu(el);
+    expect(prevented).toBe(false); // preventDefault called
+  });
+
+  it('does nothing when disabled', () => {
+    const onLongPress = vi.fn();
+    const { getByTestId } = render(<Harness onLongPress={onLongPress} delay={500} disabled />);
+    fireEvent.pointerDown(getByTestId('target'), pointer('touch'));
+    act(() => void vi.advanceTimersByTime(500));
+    expect(onLongPress).not.toHaveBeenCalled();
+  });
+
+  it('emits suppression styles only on coarse-pointer devices', () => {
+    coarse = true;
+    installMatchMedia();
+    const { getByTestId, rerender } = render(<Harness onLongPress={vi.fn()} testId="coarse" />);
+    // jsdom applies the inline style object; user-select none is the tell.
+    expect(getByTestId('coarse').style.userSelect).toBe('none');
+
+    coarse = false;
+    installMatchMedia();
+    rerender(<Harness onLongPress={vi.fn()} testId="coarse" />);
+    // A remount picks up the new (fine-pointer) matchMedia result.
+    cleanup();
+    const fine = render(<Harness onLongPress={vi.fn()} testId="fine" />);
+    expect(fine.getByTestId('fine').style.userSelect).toBe('');
+  });
+});

package/src/hooks/index.ts

@@ -0,0 +1,4 @@
+export { useLongPress } from './useLongPress';
+export type { UseLongPressOptions, LongPressHandlers } from './useLongPress';
+export { useDoubleTapHandler, useSingleOrDoubleTap } from './useDoubleTap';
+export { useIsMobile, MOBILE_BREAKPOINT_PX } from './useIsMobile';

package/src/hooks/useDoubleTap.ts

@@ -0,0 +1,91 @@
+'use client';
+
+import { useRef } from 'react';
+
+// Real double-clicks (desktop mouse) report e.detail === 2 natively — no extra
+// work needed there. Touch-generated click events always report detail === 1
+// (no browser synthesizes a dblclick-style count from two taps), so
+// double-tap has to be detected by timing two clicks against each other
+// instead. Sharing one implementation for both means every double-click-style
+// affordance behaves the same way on mouse and touch without the caller
+// duplicating the two code paths.
+const DOUBLE_TAP_MS = 350;
+
+/**
+ * useDoubleTapHandler — fires `onDoubleTap` on a real double-click (desktop)
+ * or two taps within `DOUBLE_TAP_MS` (touch).
+ *
+ * Only safe when the *single* tap/click has no default action of its own to
+ * preempt — e.g. a colour swatch with nothing to cancel. If the single tap
+ * navigates, opens something, or otherwise does something a following double
+ * needs to be able to undo before it happens, use `useSingleOrDoubleTap`
+ * instead: this hook fires `onDoubleTap` only, leaving any single-tap handling
+ * to the caller's own `onClick`, which already ran immediately and can't be
+ * un-done here.
+ *
+ * The event is passed through to `onDoubleTap` rather than calling
+ * `preventDefault` internally — not every call site needs to cancel
+ * something, so the decision is left to the caller.
+ */
+export function useDoubleTapHandler<E extends { detail: number }>(
+  onDoubleTap: (e: E) => void,
+): (e: E) => void {
+  const lastTime = useRef(0);
+  return (e: E) => {
+    if (e.detail === 2) {
+      onDoubleTap(e);
+      return;
+    }
+    const now = Date.now();
+    if (now - lastTime.current < DOUBLE_TAP_MS) {
+      lastTime.current = 0;
+      onDoubleTap(e);
+    } else {
+      lastTime.current = now;
+    }
+  };
+}
+
+/**
+ * useSingleOrDoubleTap — for call sites where the single tap/click *does*
+ * have a default action (e.g. navigating) that a following double-tap must be
+ * able to preempt.
+ *
+ * A real double-click gets away with firing the single action immediately and
+ * only detecting the double afterward, because `e.detail === 2` is the
+ * browser's own resolved signal, arriving on the very click that matters. A
+ * touch double-tap has no equivalent "hold on, there might be a second one"
+ * signal — the only way to know is to wait out the window before committing
+ * to the single action, which is what this hook does: `onSingle` is deferred
+ * by `DOUBLE_TAP_MS` and only actually runs if no second tap arrives in that
+ * time. This means every single tap through this hook incurs that latency —
+ * only use it where a genuine double-tap gesture must be able to preempt the
+ * single action; `useDoubleTapHandler` above has no such delay.
+ */
+export function useSingleOrDoubleTap<E extends { detail: number }>(
+  onSingle: (e: E) => void,
+  onDouble: (e: E) => void,
+): (e: E) => void {
+  const timer = useRef<ReturnType<typeof setTimeout> | null>(null);
+
+  return (e: E) => {
+    if (e.detail === 2) {
+      if (timer.current) {
+        clearTimeout(timer.current);
+        timer.current = null;
+      }
+      onDouble(e);
+      return;
+    }
+    if (timer.current) {
+      clearTimeout(timer.current);
+      timer.current = null;
+      onDouble(e);
+      return;
+    }
+    timer.current = setTimeout(() => {
+      timer.current = null;
+      onSingle(e);
+    }, DOUBLE_TAP_MS);
+  };
+}

package/src/hooks/useIsMobile.ts

@@ -0,0 +1,33 @@
+'use client';
+
+import { useEffect, useState } from 'react';
+
+// The platform's canonical mobile breakpoint — matches the shell chrome and
+// Dialog's own full-screen-sheet switch (`runtime/app/globals.css`,
+// `Dialog.module.css`). A plugin whose own layout genuinely needs a different
+// threshold may still hardcode its own value (e.g. a three-column layout that
+// only needs to fork earlier than 768px) — this constant is the *default* every
+// consumer should reach for first, so the platform's idea of "mobile" doesn't
+// silently drift across components again.
+export const MOBILE_BREAKPOINT_PX = 768;
+
+/**
+ * useIsMobile — whether the viewport is at or below the platform's mobile
+ * breakpoint. SSR-safe: defaults to `false` (desktop) until the client mounts
+ * and reads the real viewport, avoiding a hydration mismatch on first paint.
+ */
+export function useIsMobile(breakpointPx: number = MOBILE_BREAKPOINT_PX): boolean {
+  const [isMobile, setIsMobile] = useState(false);
+
+  useEffect(() => {
+    const mql = window.matchMedia(`(max-width: ${breakpointPx}px)`);
+    setIsMobile(mql.matches);
+    function handleChange(e: MediaQueryListEvent) {
+      setIsMobile(e.matches);
+    }
+    mql.addEventListener('change', handleChange);
+    return () => mql.removeEventListener('change', handleChange);
+  }, [breakpointPx]);
+
+  return isMobile;
+}

package/src/hooks/useLongPress.ts

@@ -0,0 +1,185 @@
+'use client';
+
+import { useCallback, useEffect, useRef, useState } from 'react';
+import type {
+  CSSProperties,
+  MouseEvent as ReactMouseEvent,
+  PointerEvent as ReactPointerEvent,
+} from 'react';
+
+export interface UseLongPressOptions {
+  /** Called once the press has been held for `delay` without exceeding `moveTolerance`. */
+  onLongPress: () => void;
+  /** Hold duration in ms before `onLongPress` fires. Default 500. */
+  delay?: number;
+  /** Accumulated pointer movement (px) that cancels a pending press. Default 10 —
+   *  a real finger jitters a couple of px on a still hold; this must be forgiving
+   *  of that or the gesture never fires. */
+  moveTolerance?: number;
+  /** How long (ms) after firing to swallow the click that may or may not follow.
+   *  Default 700. Time-boxed rather than "clear on next click" — iOS frequently
+   *  sends no click at all after a long hold, so a flag that only clears on the
+   *  next click stays armed forever and silently eats the user's next real tap. */
+  suppressClickMs?: number;
+  /** Fire `navigator.vibrate(10)` when the press triggers, where supported. Default true. */
+  vibrate?: boolean;
+  /** Skip entirely (hooks can't be called conditionally, so this is the escape hatch
+   *  for a caller whose long-press action isn't available in the current state). */
+  disabled?: boolean;
+}
+
+export interface LongPressHandlers {
+  onPointerDown: (e: ReactPointerEvent) => void;
+  onPointerMove: (e: ReactPointerEvent) => void;
+  onPointerUp: (e: ReactPointerEvent) => void;
+  onPointerCancel: (e: ReactPointerEvent) => void;
+  onPointerLeave: (e: ReactPointerEvent) => void;
+  onContextMenu: (e: ReactMouseEvent) => void;
+  onClick: (e: ReactMouseEvent) => void;
+  /** Spread onto the target element. Empty on devices whose primary pointer
+   *  isn't coarse (desktop mouse/trackpad) — see the coarse-pointer gate below. */
+  style: CSSProperties;
+}
+
+const DEFAULT_DELAY_MS = 500;
+const DEFAULT_MOVE_TOLERANCE_PX = 10;
+const DEFAULT_SUPPRESS_CLICK_MS = 700;
+
+// SSR-safe, same defer-to-client-mount pattern as useIsMobile: defaults to
+// false (no suppression styles) until the client can actually read the
+// device's primary pointer, avoiding a hydration mismatch.
+function usePrefersCoarsePointer(): boolean {
+  const [coarse, setCoarse] = useState(false);
+
+  useEffect(() => {
+    const mql = window.matchMedia('(pointer: coarse)');
+    setCoarse(mql.matches);
+    function handleChange(e: MediaQueryListEvent) {
+      setCoarse(e.matches);
+    }
+    mql.addEventListener('change', handleChange);
+    return () => mql.removeEventListener('change', handleChange);
+  }, []);
+
+  return coarse;
+}
+
+/**
+ * useLongPress — touch-and-hold gesture with the full suppression recipe a
+ * long-press needs to behave, not just a bare timer.
+ *
+ * A naive `setTimeout` started on `pointerdown` and cleared on `pointermove`
+ * fails in three specific ways this hook exists to fix:
+ *  1. Any movement at all cancels it — but a real finger jitters a few px even
+ *     on a "still" hold, so the gesture misfires constantly. `moveTolerance`
+ *     requires deliberate movement before cancelling.
+ *  2. `pointercancel` (the browser converting the touch into a scroll) isn't
+ *     handled — the timer survives and fires mid-scroll. Handled here.
+ *  3. Nothing suppresses the OS's own reaction to a long touch-hold: iOS shows
+ *     its link-preview callout, Android starts text selection or opens a
+ *     context menu, and either can fire *alongside* the gesture this hook
+ *     triggers. `onContextMenu` + the returned `style` (touch-callout,
+ *     user-select, touch-action) close all three, gated to coarse-pointer
+ *     devices only — unconditionally disabling `user-select` would break
+ *     mouse text selection on desktop, which never held this long-press to
+ *     begin with (see `onPointerDown`'s own `pointerType` check).
+ *
+ * The click that may or may not follow a fired long-press (iOS often sends
+ * none at all) is swallowed for `suppressClickMs`, not indefinitely — an
+ * unbounded suppression flag left armed by a browser that never sends that
+ * click silently eats the user's *next* unrelated tap on the same element.
+ */
+export function useLongPress({
+  onLongPress,
+  delay = DEFAULT_DELAY_MS,
+  moveTolerance = DEFAULT_MOVE_TOLERANCE_PX,
+  suppressClickMs = DEFAULT_SUPPRESS_CLICK_MS,
+  vibrate = true,
+  disabled = false,
+}: UseLongPressOptions): LongPressHandlers {
+  const timerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const startRef = useRef<{ x: number; y: number } | null>(null);
+  const suppressUntilRef = useRef(0);
+
+  const clearTimer = useCallback(() => {
+    if (timerRef.current) {
+      clearTimeout(timerRef.current);
+      timerRef.current = null;
+    }
+  }, []);
+
+  // A press pending when the component unmounts (its target left the view
+  // mid-hold — e.g. the row it's on was deleted by a sync elsewhere) must not
+  // fire onLongPress against state that's no longer there.
+  useEffect(() => clearTimer, [clearTimer]);
+
+  const onPointerDown = useCallback(
+    (e: ReactPointerEvent) => {
+      if (disabled || e.pointerType !== 'touch') return;
+      startRef.current = { x: e.clientX, y: e.clientY };
+      clearTimer();
+      timerRef.current = setTimeout(() => {
+        timerRef.current = null;
+        suppressUntilRef.current = Date.now() + suppressClickMs;
+        if (vibrate && typeof navigator !== 'undefined' && navigator.vibrate) {
+          navigator.vibrate(10);
+        }
+        onLongPress();
+      }, delay);
+    },
+    [disabled, delay, suppressClickMs, vibrate, onLongPress, clearTimer],
+  );
+
+  const onPointerMove = useCallback(
+    (e: ReactPointerEvent) => {
+      const start = startRef.current;
+      if (!start || !timerRef.current) return;
+      const dx = e.clientX - start.x;
+      const dy = e.clientY - start.y;
+      if (Math.hypot(dx, dy) > moveTolerance) clearTimer();
+    },
+    [moveTolerance, clearTimer],
+  );
+
+  const cancelPress = useCallback(() => {
+    clearTimer();
+    startRef.current = null;
+  }, [clearTimer]);
+
+  // Preempts the OS's own long-press menu (Android's link/image context menu)
+  // whenever our gesture is pending or has just fired — either way, this
+  // hook's action is the one that should win, not a native menu appearing on
+  // top of (or instead of) it. iOS's equivalent (the touch-callout link
+  // preview) isn't a JS event at all — that one is closed by `style` below.
+  const onContextMenu = useCallback((e: ReactMouseEvent) => {
+    if (timerRef.current || Date.now() < suppressUntilRef.current) e.preventDefault();
+  }, []);
+
+  const onClick = useCallback((e: ReactMouseEvent) => {
+    if (Date.now() < suppressUntilRef.current) {
+      e.preventDefault();
+      e.stopPropagation();
+    }
+  }, []);
+
+  const isCoarsePointer = usePrefersCoarsePointer();
+  const style: CSSProperties = isCoarsePointer
+    ? {
+        WebkitTouchCallout: 'none',
+        WebkitUserSelect: 'none',
+        userSelect: 'none',
+        touchAction: 'manipulation',
+      }
+    : {};
+
+  return {
+    onPointerDown,
+    onPointerMove,
+    onPointerUp: cancelPress,
+    onPointerCancel: cancelPress,
+    onPointerLeave: cancelPress,
+    onContextMenu,
+    onClick,
+    style,
+  };
+}

package/src/index.ts

@@ -23,10 +23,32 @@ export { Input } from './components/Input/Input';
 export type { InputProps } from './components/Input/Input';
 export { Textarea } from './components/Textarea/Textarea';
 export type { TextareaProps } from './components/Textarea/Textarea';
-export { Dialog } from './components/Dialog/Dialog';
+export { CodeTextarea } from './components/CodeTextarea/CodeTextarea';
+export type { CodeTextareaProps } from './components/CodeTextarea/CodeTextarea';
+export { StatusBadge } from './components/StatusBadge/StatusBadge';
+export type { StatusBadgeProps, StatusBadgeStatus } from './components/StatusBadge/StatusBadge';
+export { SplitPane } from './components/SplitPane/SplitPane';
+export type { SplitPaneProps } from './components/SplitPane/SplitPane';
+export { TagInput } from './components/TagInput/TagInput';
+export type { TagInputProps } from './components/TagInput/TagInput';
+export { Dialog, useOverlaySecondRow } from './components/Dialog/Dialog';
 export type { DialogProps, DialogSize } from './components/Dialog/Dialog';
 export { Drawer } from './components/Drawer/Drawer';
 export type { DrawerProps } from './components/Drawer/Drawer';
+export { OverlayHeader } from './components/OverlayHeader/OverlayHeader';
+export type { OverlayHeaderProps } from './components/OverlayHeader/OverlayHeader';
+export { Sheet } from './components/Sheet/Sheet';
+export type { SheetProps } from './components/Sheet/Sheet';
+export { ConfirmDialog } from './components/ConfirmDialog/ConfirmDialog';
+export type { ConfirmDialogProps } from './components/ConfirmDialog/ConfirmDialog';
+export { Menu } from './components/Menu/Menu';
+export type {
+  MenuProps,
+  MenuItem,
+  MenuLabel,
+  MenuSeparator,
+  MenuEntry,
+} from './components/Menu/Menu';
 export { ToastProvider, useToast } from './components/Toast/Toast';
 export type { ToastItem, ToastContextValue } from './components/Toast/Toast';
 export { Card } from './components/Card/Card';
@@ -49,3 +71,10 @@ export { Checkbox } from './components/Checkbox/Checkbox';
 export type { CheckboxProps } from './components/Checkbox/Checkbox';
 export { DragHandleRow } from './components/DragHandleRow/DragHandleRow';
 export type { DragHandleRowProps } from './components/DragHandleRow/DragHandleRow';
+export { Calendar } from './components/Calendar/Calendar';
+export type { CalendarProps } from './components/Calendar/Calendar';
+export { DatePicker } from './components/DatePicker/DatePicker';
+export type { DatePickerProps } from './components/DatePicker/DatePicker';
+export { useLongPress, useDoubleTapHandler, useSingleOrDoubleTap, useIsMobile } from './hooks';
+export { MOBILE_BREAKPOINT_PX } from './hooks';
+export type { UseLongPressOptions, LongPressHandlers } from './hooks';

package/src/motion.ts

@@ -0,0 +1,78 @@
+'use client';
+
+import { useEffect, useState } from 'react';
+
+export type TransitionPhase = 'entering' | 'open' | 'closing' | 'closed';
+
+/**
+ * useMountTransition — generic two-phase-mount state machine for animated
+ * overlays (Dialog, Drawer, and their Phase-B successors: Sheet,
+ * ConfirmDialog, Menu). Internal to the design system — not exported from
+ * `index.ts`; each component wires its own CSS classes to the returned phase.
+ *
+ * The `open` prop controls mounting from the outside, but both directions need
+ * two renders to actually animate rather than snap: entering needs a frame at
+ * the closed-position styles before flipping to open (so the browser has
+ * something to interpolate from), and exiting needs to stay mounted *after*
+ * `open` goes false long enough to play in reverse — so `mounted` and `open`
+ * diverge for `durationMs` on close:
+ *
+ *   open=true  -> phase 'entering' (closed-position styles — this applies
+ *                 equally to a fresh mount that starts open, e.g. a
+ *                 route-driven overlay, and to an existing instance whose
+ *                 `open` prop just flipped true; both should animate in the
+ *                 same way) -> next frame, phase 'open' (open-position styles;
+ *                 the CSS transition between the two animates the entrance).
+ *   open=false -> phase 'closing' (still mounted, rendered back at the
+ *                 closed-position styles so the transition reverses) -> after
+ *                 durationMs, phase 'closed' (unmounts).
+ *
+ * A component only needs one conditional class: apply the "open" variant
+ * when `phase === 'open'`, and leave the base (closed-position) styles as the
+ * unconditional default — entering, closing, and the pre-transition instant
+ * all render as that same base state, which is exactly what should animate
+ * to/from.
+ */
+export function useMountTransition(
+  open: boolean,
+  durationMs: number,
+): { mounted: boolean; phase: TransitionPhase } {
+  const [phase, setPhase] = useState<TransitionPhase>(open ? 'entering' : 'closed');
+
+  useEffect(() => {
+    if (open) {
+      setPhase('entering');
+      const raf = requestAnimationFrame(() => setPhase('open'));
+      return () => cancelAnimationFrame(raf);
+    }
+    setPhase((p) => (p === 'closed' ? 'closed' : 'closing'));
+    const timer = setTimeout(() => setPhase('closed'), durationMs);
+    return () => clearTimeout(timer);
+  }, [open, durationMs]);
+
+  return { mounted: phase !== 'closed', phase };
+}
+
+/**
+ * usePrefersReducedMotion — SSR-safe (defaults to `false` until the client
+ * mounts, matching every other SSR-safe hook in this system). Components pair
+ * this with a `durationMs` of ~0 passed to `useMountTransition` and a matching
+ * `@media (prefers-reduced-motion: reduce)` CSS rule collapsing the same
+ * transition to near-instant — both sides must agree, or the JS unmount timer
+ * and the CSS animation duration drift apart.
+ */
+export function usePrefersReducedMotion(): boolean {
+  const [reduced, setReduced] = useState(false);
+
+  useEffect(() => {
+    const mql = window.matchMedia('(prefers-reduced-motion: reduce)');
+    setReduced(mql.matches);
+    function handleChange(e: MediaQueryListEvent) {
+      setReduced(e.matches);
+    }
+    mql.addEventListener('change', handleChange);
+    return () => mql.removeEventListener('change', handleChange);
+  }, []);
+
+  return reduced;
+}