@sovereignfs/ui 0.83.1 → 0.89.1

package/src/hooks/useLongPress.ts

@@ -1,185 +0,0 @@
-'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/hooks/useOfflineTileState.ts

@@ -1,45 +0,0 @@
-'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

@@ -1,96 +0,0 @@
-'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

@@ -1,88 +0,0 @@
-'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

@@ -1,36 +0,0 @@
-'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 };
-}