@sovereignfs/ui 0.21.3 → 0.33.0

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

@@ -21,16 +21,40 @@ export { Button } from './components/Button/Button';
 export type { ButtonProps, ButtonVariant, ButtonSize } from './components/Button/Button';
 export { Input } from './components/Input/Input';
 export type { InputProps } from './components/Input/Input';
-export { Dialog } from './components/Dialog/Dialog';
+export { Textarea } from './components/Textarea/Textarea';
+export type { TextareaProps } from './components/Textarea/Textarea';
+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';
 export type { CardProps } from './components/Card/Card';
 export { FormField } from './components/FormField/FormField';
-export type { FormFieldProps } 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 { EmptyState } from './components/EmptyState/EmptyState';
@@ -43,3 +67,14 @@ export { NavTabs } from './components/NavTabs/NavTabs';
 export type { NavTabsProps, NavTabItem } from './components/NavTabs/NavTabs';
 export { Tooltip } from './components/Tooltip/Tooltip';
 export type { TooltipProps } from './components/Tooltip/Tooltip';
+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;
+}

package/src/stories/Checkbox.stories.tsx

@@ -0,0 +1,45 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { useState } from 'react';
+import { Checkbox } from '../components/Checkbox/Checkbox';
+
+const meta: Meta<typeof Checkbox> = {
+  title: 'Components/Checkbox',
+  component: Checkbox,
+  parameters: { layout: 'centered' },
+  tags: ['autodocs'],
+};
+
+export default meta;
+type Story = StoryObj<typeof Checkbox>;
+
+export const Default: Story = {
+  render: () => {
+    const [checked, setChecked] = useState(false);
+    return <Checkbox checked={checked} onChange={setChecked} label="Task title" />;
+  },
+};
+
+export const Checked: Story = {
+  render: () => {
+    const [checked, setChecked] = useState(true);
+    return <Checkbox checked={checked} onChange={setChecked} label="Already done" />;
+  },
+};
+
+export const WithStrikeThrough: Story = {
+  name: 'Strike-through on complete',
+  render: () => {
+    const [checked, setChecked] = useState(false);
+    return (
+      <Checkbox checked={checked} onChange={setChecked} label="Click to complete" strikeThrough />
+    );
+  },
+};
+
+export const Disabled: Story = {
+  render: () => <Checkbox checked={false} onChange={() => {}} label="Cannot interact" disabled />,
+};
+
+export const DisabledChecked: Story = {
+  render: () => <Checkbox checked onChange={() => {}} label="Locked complete" disabled />,
+};