@sovereignfs/ui 0.41.0 → 0.54.0

package/src/components/Select/Select.module.css

@@ -8,8 +8,11 @@
 .select {
   display: block;
   width: 100%;
-  /* Right-pad to clear the custom chevron */
-  padding: var(--sv-space-2) var(--sv-space-8) var(--sv-space-2) var(--sv-space-3);
+  /* 36px rendered height. Explicit height + border-box, same technique as
+     Input. Right-pad to clear the custom chevron. */
+  height: 36px;
+  box-sizing: border-box;
+  padding: 4px var(--sv-space-8) 4px var(--sv-space-3);
   font-family: var(--sv-font-family);
   font-size: var(--sv-font-size-sm);
   line-height: 1.5;
@@ -25,8 +28,9 @@
     box-shadow 0.15s ease;
 }
 
-/* sm — compact for table cells and inline controls */
+/* sm — compact for table cells and inline controls. 32px height. */
 .sm .select {
+  height: 32px;
   padding: 2px var(--sv-space-6) 2px var(--sv-space-2);
   font-size: var(--sv-font-size-sm);
   line-height: 1.4;

package/src/components/Sheet/Sheet.tsx

@@ -1,8 +1,12 @@
 'use client';
 
-import { type ReactNode, useEffect, useRef } from 'react';
-import { lockBodyScroll, unlockBodyScroll } from '../../scroll-lock';
+import { type ReactNode, useRef } from 'react';
 import { useMountTransition, usePrefersReducedMotion } from '../../motion';
+import {
+  useOverlayFocusCapture,
+  useOverlayKeyboardTrap,
+  useOverlayScrollLock,
+} from '../../overlay-shell';
 import { OverlayHeader } from '../OverlayHeader/OverlayHeader';
 import styles from './Sheet.module.css';
 
@@ -36,9 +40,6 @@ export interface SheetProps {
   children: ReactNode;
 }
 
-const FOCUSABLE =
-  'a[href], button:not([disabled]), textarea:not([disabled]), input:not([disabled]), select:not([disabled]), [tabindex]:not([tabindex="-1"])';
-
 // Matches --sv-motion-duration-base (Sheet.module.css) — see Dialog.tsx's
 // identical constant for why this stays a plain JS number.
 const MOTION_DURATION_MS = 250;
@@ -71,55 +72,12 @@ export function Sheet({
   children,
 }: SheetProps) {
   const panelRef = useRef<HTMLDivElement>(null);
-  const previouslyFocused = useRef<HTMLElement | null>(null);
   const reducedMotion = usePrefersReducedMotion();
   const { mounted, phase } = useMountTransition(open, reducedMotion ? 0 : MOTION_DURATION_MS);
 
-  useEffect(() => {
-    if (!mounted) return;
-    lockBodyScroll();
-    return unlockBodyScroll;
-  }, [mounted]);
-
-  useEffect(() => {
-    if (!mounted) return;
-    previouslyFocused.current = document.activeElement as HTMLElement | null;
-    const panel = panelRef.current;
-    const first = panel?.querySelector<HTMLElement>(FOCUSABLE);
-    (first ?? panel)?.focus();
-    return () => previouslyFocused.current?.focus();
-  }, [mounted]);
-
-  useEffect(() => {
-    if (!open) return;
-    function handleKeyDown(e: KeyboardEvent) {
-      if (e.key === 'Escape') {
-        e.stopPropagation();
-        onClose();
-        return;
-      }
-      if (e.key !== 'Tab') return;
-      const panel = panelRef.current;
-      if (!panel) return;
-      const focusable = [...panel.querySelectorAll<HTMLElement>(FOCUSABLE)];
-      const first = focusable[0];
-      const last = focusable.at(-1);
-      if (!first || !last) {
-        e.preventDefault();
-        return;
-      }
-      const active = document.activeElement;
-      if (e.shiftKey && active === first) {
-        e.preventDefault();
-        last.focus();
-      } else if (!e.shiftKey && active === last) {
-        e.preventDefault();
-        first.focus();
-      }
-    }
-    document.addEventListener('keydown', handleKeyDown);
-    return () => document.removeEventListener('keydown', handleKeyDown);
-  }, [open, onClose]);
+  useOverlayScrollLock(mounted);
+  useOverlayFocusCapture(panelRef, mounted);
+  useOverlayKeyboardTrap(panelRef, open, onClose);
 
   if (!mounted) return null;
 

package/src/components/Slider/Slider.module.css

@@ -0,0 +1,95 @@
+.root {
+  display: flex;
+  flex-direction: column;
+  gap: var(--sv-space-2);
+}
+
+.label {
+  font-size: var(--sv-font-size-sm);
+  color: var(--sv-color-text-primary);
+}
+
+.slider {
+  appearance: none;
+  width: 100%;
+  height: 20px;
+  background: transparent;
+  cursor: pointer;
+  margin: 0;
+}
+
+/* Expand the vertical hit area for touch dragging without thickening the
+   visible track — same rationale as Button/Checkbox's touch-target
+   expansion, gated to the primary pointer. */
+@media (pointer: coarse) {
+  .slider {
+    height: var(--sv-touch-target-min, 44px);
+  }
+}
+
+.slider:disabled {
+  opacity: 0.5;
+  cursor: not-allowed;
+}
+
+.slider:focus-visible {
+  outline: 2px solid var(--sv-color-focus-ring);
+  outline-offset: 2px;
+}
+
+/* Track — WebKit/Blink. The filled portion is a gradient computed from the
+   --slider-fill custom property the component sets inline; no JS-measured
+   pixel math, just a CSS variable driving a hard color stop. */
+.slider::-webkit-slider-runnable-track {
+  height: 4px;
+  border-radius: var(--sv-radius-full);
+  background: linear-gradient(
+    to right,
+    var(--sv-color-accent) var(--slider-fill),
+    var(--sv-color-border-strong) var(--slider-fill)
+  );
+}
+
+.slider::-webkit-slider-thumb {
+  appearance: none;
+  width: 16px;
+  height: 16px;
+  margin-top: -6px;
+  border-radius: var(--sv-radius-full);
+  background: var(--sv-color-accent);
+  box-shadow: var(--sv-shadow-control);
+  cursor: pointer;
+}
+
+.slider:disabled::-webkit-slider-thumb {
+  cursor: not-allowed;
+}
+
+/* Track — Firefox. Separate track/progress pseudo-elements instead of a
+   gradient — Firefox renders the filled portion natively via
+   ::-moz-range-progress. */
+.slider::-moz-range-track {
+  height: 4px;
+  border-radius: var(--sv-radius-full);
+  background: var(--sv-color-border-strong);
+}
+
+.slider::-moz-range-progress {
+  height: 4px;
+  border-radius: var(--sv-radius-full);
+  background: var(--sv-color-accent);
+}
+
+.slider::-moz-range-thumb {
+  width: 16px;
+  height: 16px;
+  border: none;
+  border-radius: var(--sv-radius-full);
+  background: var(--sv-color-accent);
+  box-shadow: var(--sv-shadow-control);
+  cursor: pointer;
+}
+
+.slider:disabled::-moz-range-thumb {
+  cursor: not-allowed;
+}

package/src/components/Slider/Slider.stories.tsx

@@ -0,0 +1,64 @@
+import { useState } from 'react';
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { Slider } from './Slider';
+
+const meta = {
+  title: 'Components/Slider',
+  component: Slider,
+  parameters: {
+    layout: 'padded',
+    docs: {
+      description: {
+        component:
+          'Single-thumb range input. A native <input type="range"> under custom styling — arrow keys, Home/End, and touch-drag all come from the browser.',
+      },
+    },
+  },
+  args: {
+    value: 50,
+    onChange: () => {},
+    min: 0,
+    max: 100,
+    'aria-label': 'Value',
+  },
+} satisfies Meta<typeof Slider>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+// ---------------------------------------------------------------------------
+
+export const Default: Story = {
+  render: (args) => {
+    const [value, setValue] = useState(args.value);
+    return <Slider {...args} value={value} onChange={setValue} />;
+  },
+};
+
+export const WithLabel: Story = {
+  render: (args) => {
+    const [value, setValue] = useState(args.value);
+    return <Slider {...args} label="Volume" value={value} onChange={setValue} />;
+  },
+};
+
+export const AtMin: Story = {
+  args: { value: 0 },
+};
+
+export const AtMax: Story = {
+  args: { value: 100 },
+};
+
+export const SteppedRange: Story = {
+  render: (_args) => {
+    const [value, setValue] = useState(5);
+    return (
+      <Slider value={value} onChange={setValue} min={0} max={10} step={1} label="Rating (0–10)" />
+    );
+  },
+};
+
+export const Disabled: Story = {
+  args: { disabled: true },
+};

package/src/components/Slider/Slider.tsx

@@ -0,0 +1,77 @@
+'use client';
+
+import { useId } from 'react';
+import type { CSSProperties } from 'react';
+import styles from './Slider.module.css';
+
+export interface SliderProps {
+  value: number;
+  onChange: (value: number) => void;
+  min: number;
+  max: number;
+  step?: number;
+  /** Renders a visible label above the track. Omit and pass `aria-label`
+   * instead for a standalone, unlabeled slider. */
+  label?: string;
+  disabled?: boolean;
+  id?: string;
+  className?: string;
+  'aria-label'?: string;
+  'aria-describedby'?: string;
+  'aria-invalid'?: boolean;
+  required?: boolean;
+}
+
+/**
+ * Slider — single-thumb range input.
+ *
+ * A native `<input type="range">` under custom track/thumb styling — arrow
+ * key (adjust by `step`), Home/End (jump to min/max), and touch-drag
+ * support all come from the browser, nothing hand-rolled. Dual-thumb/range
+ * selection is out of scope until a consumer needs it.
+ */
+export function Slider({
+  value,
+  onChange,
+  min,
+  max,
+  step,
+  label,
+  disabled,
+  id,
+  className,
+  'aria-label': ariaLabel,
+  'aria-describedby': ariaDescribedBy,
+  'aria-invalid': ariaInvalid,
+  required,
+}: SliderProps) {
+  const generatedId = useId();
+  const inputId = id ?? generatedId;
+  const fillPercent = max > min ? ((value - min) / (max - min)) * 100 : 0;
+
+  return (
+    <div className={[styles.root, className].filter(Boolean).join(' ')}>
+      {label && (
+        <label htmlFor={inputId} className={styles.label}>
+          {label}
+        </label>
+      )}
+      <input
+        id={inputId}
+        type="range"
+        min={min}
+        max={max}
+        step={step}
+        value={value}
+        disabled={disabled}
+        required={required}
+        aria-label={label ? undefined : ariaLabel}
+        aria-describedby={ariaDescribedBy}
+        aria-invalid={ariaInvalid}
+        className={styles.slider}
+        style={{ '--slider-fill': `${fillPercent}%` } as CSSProperties}
+        onChange={(e) => onChange(Number(e.target.value))}
+      />
+    </div>
+  );
+}

package/src/components/Slider/__tests__/Slider.test.tsx

@@ -0,0 +1,45 @@
+// @vitest-environment jsdom
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { cleanup, render, screen, fireEvent } from '@testing-library/react';
+import { Slider } from '../Slider';
+
+afterEach(cleanup);
+
+describe('Slider', () => {
+  it('renders a range input with the given min/max/value', () => {
+    render(<Slider value={50} onChange={() => {}} min={0} max={100} aria-label="Volume" />);
+    const input = screen.getByRole('slider') as HTMLInputElement;
+    expect(input.min).toBe('0');
+    expect(input.max).toBe('100');
+    expect(input.value).toBe('50');
+  });
+
+  it('calls onChange with a number when the value changes', () => {
+    const onChange = vi.fn();
+    render(<Slider value={50} onChange={onChange} min={0} max={100} aria-label="Volume" />);
+    fireEvent.change(screen.getByRole('slider'), { target: { value: '75' } });
+    expect(onChange).toHaveBeenCalledWith(75);
+  });
+
+  it('respects a step prop', () => {
+    render(<Slider value={5} onChange={() => {}} min={0} max={10} step={5} aria-label="Volume" />);
+    expect((screen.getByRole('slider') as HTMLInputElement).step).toBe('5');
+  });
+
+  it('renders a visible label and associates it via htmlFor', () => {
+    render(<Slider value={50} onChange={() => {}} min={0} max={100} label="Volume" />);
+    expect(screen.getByRole('slider', { name: 'Volume' })).toBeDefined();
+  });
+
+  it('falls back to aria-label when no visible label is given', () => {
+    render(<Slider value={50} onChange={() => {}} min={0} max={100} aria-label="Volume" />);
+    expect(screen.getByRole('slider', { name: 'Volume' })).toBeDefined();
+  });
+
+  it('disables the input when disabled is set', () => {
+    render(
+      <Slider value={50} onChange={() => {}} min={0} max={100} aria-label="Volume" disabled />,
+    );
+    expect(screen.getByRole('slider')).toHaveProperty('disabled', true);
+  });
+});

package/src/components/SwipableMobileCarousel/SwipableMobileCarousel.module.css

@@ -0,0 +1,55 @@
+.wrap {
+  position: relative;
+  height: 100%;
+  width: 100%;
+}
+
+.scroller {
+  height: 100%;
+  width: 100%;
+  display: flex;
+  overflow-x: auto;
+  overflow-y: hidden;
+  scroll-snap-type: x mandatory;
+  /* Momentum + rubber-banding come from the browser's native scroll physics —
+     no hand-rolled pointer/touch dragging. Deliberately NOT
+     -webkit-overflow-scrolling: touch: that legacy iOS <13 hint promotes its
+     element to its own compositing layer for GPU-accelerated momentum
+     scroll, and that layer's paint order relative to siblings/fixed
+     descendants elsewhere in the tree isn't always reliable on real iOS
+     Safari (confirmed via sovereign-tasks' and sovereign-shopper's own
+     carousels, which hit and fixed this exact bug — a position:fixed
+     overlay opened above the scroller painted BEHIND it instead of above).
+     Removing it doesn't disable momentum scrolling on any iOS version this
+     platform realistically targets. */
+}
+
+.slide {
+  flex: 0 0 100%;
+  width: 100%;
+  height: 100%;
+  min-width: 0;
+  overflow: hidden;
+  scroll-snap-align: start;
+  scroll-snap-stop: always;
+  /* Slide content is a flex column so Header/Footer stay their natural size
+     and Body (flex: 1 1 auto, min-height: 0) fills and scrolls the rest —
+     see SwipableMobileCarouselSlideParts.module.css. */
+  display: flex;
+  flex-direction: column;
+}
+
+.dots {
+  /* Overlays the bottom of .wrap rather than taking its own layout row —
+     matches both sovereign-tasks' and sovereign-shopper's existing dots
+     placement. */
+  position: absolute;
+  left: 0;
+  right: 0;
+  bottom: var(--sv-space-3);
+  pointer-events: none;
+}
+
+.dots > * {
+  pointer-events: auto;
+}

package/src/components/SwipableMobileCarousel/SwipableMobileCarousel.tsx

@@ -0,0 +1,227 @@
+'use client';
+
+import {
+  Children,
+  isValidElement,
+  useEffect,
+  useLayoutEffect,
+  useMemo,
+  useRef,
+  type ReactElement,
+  type ReactNode,
+} from 'react';
+import { useSnapCarousel } from '../../hooks/useSnapCarousel';
+import { SwipableMobileCarouselDots } from '../SwipableMobileCarouselDots/SwipableMobileCarouselDots';
+import { SwipableMobileCarouselSlide } from './SwipableMobileCarouselSlide';
+import { CarouselSlideMountContext } from './context';
+import styles from './SwipableMobileCarousel.module.css';
+
+export interface SwipableMobileCarouselIndicatorProps {
+  count: number;
+  activeIndex: number;
+  labels: (string | undefined)[];
+  onJump: (index: number) => void;
+}
+
+export interface SwipableMobileCarouselProps {
+  /** Controlled active slide index — the caller owns this (typically via
+   *  useCarouselRouteSync, or plain useState). */
+  activeIndex: number;
+  /** Called when a swipe gesture settles on a different index, or when the
+   *  reorder-jump fix re-snaps after the active slide's position changes.
+   *  The caller is responsible for updating `activeIndex` in response. */
+  onSettle: (index: number) => void;
+  /** How many slides on each side of the active one stay mounted. Default 1
+   *  matches both sovereign-tasks' and sovereign-shopper's existing "swipe
+   *  never shows a spinner" behavior. Slides outside this window keep their
+   *  DOM slot (so scroll-snap's position-based indexing stays correct) but
+   *  their children are not mounted at all. */
+  prefetchDistance?: number;
+  /** Passed straight through to the internal useSnapCarousel. */
+  settleDebounceMs?: number;
+  /** Required — labels the scroller region for assistive tech. No generic
+   *  fallback, since one would be wrong for every actual consumer. */
+  'aria-label': string;
+  /** Renders the indicator. Defaults to SwipableMobileCarouselDots. Pass
+   *  `null` to render no indicator at all. */
+  renderIndicator?: null | ((props: SwipableMobileCarouselIndicatorProps) => ReactNode);
+  className?: string;
+  /** Must be SwipableMobileCarouselSlide elements (nullish/boolean children
+   *  are safely skipped for conditional slides). A dev-mode warning is
+   *  logged for any other child type — see resolveSlides below. */
+  children: ReactNode;
+}
+
+interface ResolvedSlide {
+  key: string;
+  label: string | undefined;
+  element: ReactElement;
+}
+
+function describeChild(child: unknown): string {
+  if (isValidElement(child)) {
+    const type = child.type;
+    if (typeof type === 'string') return `<${type}>`;
+    if (typeof type === 'function') {
+      const named = type as { displayName?: string; name?: string };
+      return `<${named.displayName ?? named.name ?? 'Component'}>`;
+    }
+    return '<unknown>';
+  }
+  if (typeof child === 'string') return `string "${child}"`;
+  return String(child);
+}
+
+function resolveSlides(children: ReactNode): ResolvedSlide[] {
+  const slides: ResolvedSlide[] = [];
+  Children.forEach(children, (child, index) => {
+    if (child === null || child === undefined || child === false || child === true) return;
+    if (!isValidElement(child) || child.type !== SwipableMobileCarouselSlide) {
+      if (process.env.NODE_ENV !== 'production') {
+        console.error(
+          '[SwipableMobileCarousel] Every child must be a <SwipableMobileCarouselSlide>. ' +
+            `Found ${describeChild(child)} at position ${index}. A non-Slide child shifts every ` +
+            "subsequent slide's index, desyncing scroll-snap position from activeIndex.",
+        );
+      }
+      return;
+    }
+    const slideProps = child.props as { slideKey: string; label?: string };
+    if (process.env.NODE_ENV !== 'production' && !slideProps.label) {
+      console.warn(
+        `[SwipableMobileCarousel] SwipableMobileCarouselSlide "${slideProps.slideKey}" has no ` +
+          'label — it will show as "Slide N of count" in the default dots indicator.',
+      );
+    }
+    slides.push({ key: slideProps.slideKey, label: slideProps.label, element: child });
+  });
+  return slides;
+}
+
+/**
+ * SwipableMobileCarousel — a compound component for swiping between full-
+ * width slides (each an independent route/view on mobile), wrapping
+ * useSnapCarousel. This library's first compound component: every other
+ * component here is flat/prop-based, but slide content is large, arbitrary,
+ * per-plugin subtrees that need a header-known/body-loading split an
+ * array-of-objects prop would only express with worse JSX ergonomics.
+ *
+ * Owns rendering and mount-window mechanics only — it has no opinion on
+ * where slide data lives. Do NOT: (a) aggregate cross-slide data inside a
+ * SwipableMobileCarouselSlideBody (that recomputes on every slide render
+ * regardless of which slide is active — belongs in the parent, which
+ * already knows every slide exists); (b) mount a detail overlay (Sheet,
+ * Dialog) inside a Slide's children — mount it as a sibling of
+ * SwipableMobileCarousel instead, controlled by the same state that would
+ * otherwise drive a routed page's overlay. sovereign-tasks' current
+ * hand-rolled carousel does both and is measurably laggier than
+ * sovereign-shopper's equivalent, which keeps its overlay in the routed pane.
+ */
+export function SwipableMobileCarousel({
+  activeIndex,
+  onSettle,
+  prefetchDistance = 1,
+  settleDebounceMs = 120,
+  'aria-label': ariaLabel,
+  renderIndicator,
+  className,
+  children,
+}: SwipableMobileCarouselProps) {
+  const slides = useMemo(() => resolveSlides(children), [children]);
+  const count = slides.length;
+  const clampedActiveIndex = count === 0 ? 0 : Math.max(0, Math.min(count - 1, activeIndex));
+
+  const { scrollRef, scrollToIndex } = useSnapCarousel({
+    itemCount: count,
+    onSettle,
+    debounceMs: settleDebounceMs,
+  });
+
+  // Initial scroll position, once — subsequent activeIndex changes come
+  // either from the user's own swipe (already reflected in DOM scroll
+  // position; re-syncing to the same index below is a harmless no-op) or an
+  // external navigation, which the effect below scrolls to explicitly.
+  const initialActiveIndexRef = useRef(clampedActiveIndex);
+  useLayoutEffect(() => {
+    scrollToIndex(initialActiveIndexRef.current, 'instant');
+    // Runs once on mount only, matching both existing plugins' identical pattern.
+  }, []);
+
+  const didMountActiveIndexSyncRef = useRef(false);
+  useEffect(() => {
+    if (!didMountActiveIndexSyncRef.current) {
+      didMountActiveIndexSyncRef.current = true;
+      return;
+    }
+    scrollToIndex(clampedActiveIndex, 'smooth');
+  }, [clampedActiveIndex, scrollToIndex]);
+
+  // Reorder-jump fix: scroll-snap position tracks DOM order, not slide
+  // identity. If the previously-active slide's key still exists but moved
+  // (a caller re-sorted their slide array while mounted), re-snap to its
+  // new position and report it via onSettle so the caller's activeIndex
+  // stays in sync — otherwise scroll position silently desyncs from slide
+  // identity. Runs every commit (no dependency array) since it needs to
+  // notice any children change, not just a specific prop.
+  const prevKeysRef = useRef<string[] | null>(null);
+  useLayoutEffect(() => {
+    const currentKeys = slides.map((s) => s.key);
+    const prevKeys = prevKeysRef.current;
+    if (prevKeys) {
+      const sameOrder =
+        prevKeys.length === currentKeys.length && prevKeys.every((k, i) => k === currentKeys[i]);
+      if (!sameOrder) {
+        const activeKey = prevKeys[clampedActiveIndex];
+        if (activeKey !== undefined) {
+          const newIndex = currentKeys.indexOf(activeKey);
+          if (newIndex !== -1 && newIndex !== clampedActiveIndex) {
+            scrollToIndex(newIndex, 'instant');
+            onSettle(newIndex);
+          }
+        }
+      }
+    }
+    prevKeysRef.current = currentKeys;
+  });
+
+  function handleJump(index: number) {
+    // scrollToIndex sets useSnapCarousel's own dedupe ref synchronously, so
+    // the natural scroll-settle detection will NOT re-report this index —
+    // onSettle must be called directly here, same pairing as the
+    // reorder-jump fix above.
+    scrollToIndex(index, 'smooth');
+    onSettle(index);
+  }
+
+  const labels = slides.map((s) => s.label);
+  const indicator =
+    renderIndicator === null ? null : renderIndicator ? (
+      renderIndicator({ count, activeIndex: clampedActiveIndex, labels, onJump: handleJump })
+    ) : (
+      <SwipableMobileCarouselDots
+        className={styles.dots}
+        count={count}
+        activeIndex={clampedActiveIndex}
+        labels={labels}
+        aria-label={ariaLabel}
+        onJump={handleJump}
+      />
+    );
+
+  return (
+    <div className={[styles.wrap, className].filter(Boolean).join(' ')}>
+      <div className={styles.scroller} ref={scrollRef} role="region" aria-label={ariaLabel}>
+        {slides.map((slide, i) => (
+          <div className={styles.slide} key={slide.key}>
+            <CarouselSlideMountContext.Provider
+              value={{ isMounted: Math.abs(i - clampedActiveIndex) <= prefetchDistance }}
+            >
+              {slide.element}
+            </CarouselSlideMountContext.Provider>
+          </div>
+        ))}
+      </div>
+      {indicator}
+    </div>
+  );
+}