@sovereignfs/ui 0.45.0 → 0.83.1

package/src/components/SwipableMobileCarousel/context.ts

@@ -0,0 +1,13 @@
+'use client';
+
+import { createContext } from 'react';
+
+export interface CarouselSlideMountContextValue {
+  /** Whether this slide is within the carousel's mount window (the active
+   *  slide ± its configured prefetchDistance). Kept out of the main .tsx
+   *  file for React Fast Refresh hygiene (a file exporting only components
+   *  refreshes more reliably than one mixing components and plain values). */
+  isMounted: boolean;
+}
+
+export const CarouselSlideMountContext = createContext<CarouselSlideMountContextValue | null>(null);

package/src/components/SwipableMobileCarouselDots/SwipableMobileCarouselDots.module.css

@@ -0,0 +1,64 @@
+.dots {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  gap: var(--sv-space-2);
+}
+
+/* Opt-in — see the `density` prop doc comment. Shrinks both the gap and each
+   dot's own hit target (20px -> 16px) — for a carousel with enough slides
+   that even the space-1 gap alone still read as too wide. The visible 6px
+   dot is unchanged; only the surrounding tap-target box shrinks, via the
+   descendant override below rather than a second dot variant, so this stays
+   a pure CSS opt-in with no JS/prop plumbing beyond `density` itself. */
+.dotsCompact {
+  gap: var(--sv-space-1);
+}
+
+.dotsCompact .dot {
+  width: 16px;
+  height: 16px;
+}
+
+.dot {
+  /* A 6px visible dot is too small a hit target on its own — the button's
+     real box is larger (20px) with the dot itself painted by ::before and
+     centered inside, so tap area grows without changing the visible dot
+     size or the row's gap-based spacing math. */
+  position: relative;
+  width: 20px;
+  height: 20px;
+  padding: 0;
+  border: none;
+  background: transparent;
+  cursor: pointer;
+}
+
+.dot::before {
+  content: '';
+  position: absolute;
+  top: 50%;
+  left: 50%;
+  width: 6px;
+  height: 6px;
+  border-radius: 50%;
+  background: var(--sv-color-border-strong);
+  transform: translate(-50%, -50%);
+  transition: background 0.15s ease;
+}
+
+.dot:focus-visible {
+  outline: 2px solid var(--sv-color-focus-ring);
+  outline-offset: 2px;
+  border-radius: 50%;
+}
+
+.dotActive::before {
+  background: var(--sv-color-text-primary);
+}
+
+@media (hover: hover) {
+  .dot:not(.dotActive):hover::before {
+    background: var(--sv-color-text-muted);
+  }
+}

package/src/components/SwipableMobileCarouselDots/SwipableMobileCarouselDots.tsx

@@ -0,0 +1,73 @@
+'use client';
+
+import styles from './SwipableMobileCarouselDots.module.css';
+
+export interface SwipableMobileCarouselDotsProps {
+  count: number;
+  activeIndex: number;
+  onJump: (index: number) => void;
+  /** Per-dot accessible names, e.g. ["Lists", "Starred", "Groceries"]. Falls
+   *  back to "Slide N of count" for any index without one. */
+  labels?: (string | undefined)[];
+  /** Labels the whole group — required, no generic fallback (mirrors
+   *  SwipableMobileCarousel's own required aria-label). */
+  'aria-label': string;
+  /** `'compact'` halves the gap between dots (`--sv-space-2` → `--sv-space-1`)
+   *  and shrinks each dot's own hit target (20px → 16px) — for a carousel
+   *  with enough slides that even the reduced gap alone still reads as too
+   *  wide on a narrow viewport (e.g. a many-list mobile app). The visible
+   *  6px dot itself is unchanged; only its surrounding tap-target box
+   *  shrinks. Defaults to `'default'` — every existing consumer's spacing is
+   *  unaffected unless it opts in. */
+  density?: 'default' | 'compact';
+  className?: string;
+}
+
+/**
+ * SwipableMobileCarouselDots — a real, tappable, labeled slide indicator.
+ * Standalone (not carousel-only): reusable anywhere a set of positions needs
+ * a dot indicator (e.g. an image gallery, an onboarding stepper), and is also
+ * SwipableMobileCarousel's default `renderIndicator`.
+ *
+ * Replaces the `aria-hidden`, non-interactive dots pattern both
+ * sovereign-tasks and sovereign-shopper currently hand-roll — every dot here
+ * is a real `role="tab"` button with its own accessible name, reachable by
+ * keyboard. No roving tabIndex/arrow-key handling: `Tabs` (this library's
+ * other `role="tablist"` component) has none either, so this stays
+ * consistent with it rather than gold-plating past its sibling.
+ */
+export function SwipableMobileCarouselDots({
+  count,
+  activeIndex,
+  onJump,
+  labels,
+  'aria-label': ariaLabel,
+  density = 'default',
+  className,
+}: SwipableMobileCarouselDotsProps) {
+  return (
+    <div
+      role="tablist"
+      aria-label={ariaLabel}
+      className={[styles.dots, density === 'compact' ? styles.dotsCompact : '', className]
+        .filter(Boolean)
+        .join(' ')}
+    >
+      {Array.from({ length: count }, (_, i) => {
+        const active = i === activeIndex;
+        const label = labels?.[i] ?? `Slide ${i + 1} of ${count}`;
+        return (
+          <button
+            key={i}
+            type="button"
+            role="tab"
+            aria-selected={active}
+            aria-label={label}
+            className={[styles.dot, active ? styles.dotActive : ''].filter(Boolean).join(' ')}
+            onClick={() => onJump(i)}
+          />
+        );
+      })}
+    </div>
+  );
+}

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

@@ -0,0 +1,63 @@
+// @vitest-environment jsdom
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { cleanup, fireEvent, render, screen } from '@testing-library/react';
+import { SwipableMobileCarouselDots } from '../SwipableMobileCarouselDots';
+
+afterEach(cleanup);
+
+describe('SwipableMobileCarouselDots', () => {
+  it('renders a tablist with one tab per count, none aria-hidden', () => {
+    render(
+      <SwipableMobileCarouselDots count={3} activeIndex={0} onJump={() => {}} aria-label="Lists" />,
+    );
+    const list = screen.getByRole('tablist', { name: 'Lists' });
+    expect(list.getAttribute('aria-hidden')).toBeNull();
+    const tabs = screen.getAllByRole('tab');
+    expect(tabs).toHaveLength(3);
+    tabs.forEach((tab) => expect(tab.getAttribute('aria-hidden')).toBeNull());
+  });
+
+  it('marks only the active dot as aria-selected', () => {
+    render(
+      <SwipableMobileCarouselDots count={3} activeIndex={1} onJump={() => {}} aria-label="Lists" />,
+    );
+    const tabs = screen.getAllByRole('tab');
+    expect(tabs[0]?.getAttribute('aria-selected')).toBe('false');
+    expect(tabs[1]?.getAttribute('aria-selected')).toBe('true');
+    expect(tabs[2]?.getAttribute('aria-selected')).toBe('false');
+  });
+
+  it('uses the provided per-dot labels, falling back to "Slide N of count"', () => {
+    render(
+      <SwipableMobileCarouselDots
+        count={3}
+        activeIndex={0}
+        onJump={() => {}}
+        labels={['Lists', undefined, 'Groceries']}
+        aria-label="Lists"
+      />,
+    );
+    expect(screen.getByRole('tab', { name: 'Lists' })).toBeDefined();
+    expect(screen.getByRole('tab', { name: 'Slide 2 of 3' })).toBeDefined();
+    expect(screen.getByRole('tab', { name: 'Groceries' })).toBeDefined();
+  });
+
+  it('clicking a dot calls onJump with its index', () => {
+    const onJump = vi.fn();
+    render(
+      <SwipableMobileCarouselDots count={3} activeIndex={0} onJump={onJump} aria-label="Lists" />,
+    );
+    const thirdTab = screen.getAllByRole('tab')[2];
+    if (!thirdTab) throw new Error('expected a 3rd tab');
+    fireEvent.click(thirdTab);
+    expect(onJump).toHaveBeenCalledWith(2);
+  });
+
+  it('every dot is a real, focusable button (not a decorative element)', () => {
+    render(
+      <SwipableMobileCarouselDots count={2} activeIndex={0} onJump={() => {}} aria-label="Lists" />,
+    );
+    const tabs = screen.getAllByRole('tab');
+    tabs.forEach((tab) => expect(tab.tagName).toBe('BUTTON'));
+  });
+});

package/src/components/SwipeStack/SwipeStack.module.css

@@ -0,0 +1,101 @@
+.wrap {
+  display: flex;
+  flex-direction: column;
+  gap: var(--sv-space-3);
+  height: 100%;
+  width: 100%;
+}
+
+.stack {
+  position: relative;
+  flex: 1 1 auto;
+  min-height: 0;
+}
+
+.peek {
+  position: absolute;
+  inset: 0;
+  transform: scale(0.94) translateY(var(--sv-space-3));
+  opacity: 0.6;
+  pointer-events: none;
+}
+
+.cardSlot {
+  position: absolute;
+  inset: 0;
+}
+
+/* Styled directly rather than wrapping the Card component: Card doesn't
+   forward a ref, and this element must be the exact node useSwipeStack
+   translates/rotates as one unit — a Card wrapping an inner dragged div
+   would leave its own border/shadow visually static while only the inner
+   div moved. */
+.card {
+  position: relative;
+  height: 100%;
+  width: 100%;
+  overflow: hidden;
+  background: var(--sv-color-surface-raised);
+  border: var(--sv-border-width-hairline) solid var(--sv-color-border);
+  border-radius: var(--sv-radius-lg);
+  box-shadow: var(--sv-shadow-card);
+  touch-action: none; /* always overridden inline with useSwipeStack's computed value */
+  user-select: none;
+  cursor: grab;
+}
+
+.card:active {
+  cursor: grabbing;
+}
+
+.stamp {
+  position: absolute;
+  z-index: 1;
+  display: flex;
+  align-items: center;
+  gap: var(--sv-space-1);
+  padding: var(--sv-space-1) var(--sv-space-3);
+  border: 2px solid var(--sv-color-text-primary);
+  border-radius: var(--sv-radius-md);
+  background: var(--sv-color-surface-raised);
+  color: var(--sv-color-text-primary);
+  font-family: var(--sv-font-family);
+  font-size: var(--sv-font-size-sm);
+  font-weight: var(--sv-font-weight-semibold);
+  pointer-events: none;
+}
+
+.stampUp {
+  top: var(--sv-space-4);
+  left: 50%;
+  transform: translateX(-50%);
+  opacity: var(--sv-stack-progress-up, 0);
+}
+
+.stampDown {
+  bottom: var(--sv-space-4);
+  left: 50%;
+  transform: translateX(-50%);
+  opacity: var(--sv-stack-progress-down, 0);
+}
+
+.stampLeft {
+  top: var(--sv-space-4);
+  left: var(--sv-space-4);
+  transform: rotate(-8deg);
+  opacity: var(--sv-stack-progress-left, 0);
+}
+
+.stampRight {
+  top: var(--sv-space-4);
+  right: var(--sv-space-4);
+  transform: rotate(8deg);
+  opacity: var(--sv-stack-progress-right, 0);
+}
+
+.actions {
+  display: flex;
+  justify-content: center;
+  gap: var(--sv-space-2);
+  flex: 0 0 auto;
+}

package/src/components/SwipeStack/SwipeStack.tsx

@@ -0,0 +1,199 @@
+'use client';
+
+import { Children, isValidElement, useEffect, useRef, useState } from 'react';
+import type { ReactElement, ReactNode } from 'react';
+import { Button } from '../Button/Button';
+import { Icon, type IconName } from '../Icon/Icon';
+import { useSwipeStack, SWIPE_STACK_TRANSITION_MS } from '../../hooks/useSwipeStack';
+import type { SwipeDirection } from '../../hooks/useSwipeStack';
+import { SwipeStackCard } from './SwipeStackCard';
+import styles from './SwipeStack.module.css';
+
+export interface SwipeDirectionMeta {
+  /** Visible text on the fallback button and the in-drag stamp. */
+  label: string;
+  icon?: IconName;
+}
+
+export interface SwipeStackProps {
+  /** Required — labels the swipeable region for assistive tech. No generic
+   *  fallback, since one would be wrong for every actual consumer. */
+  'aria-label': string;
+  /** Which of the 4 directions are live, and what each is called. A
+   *  direction absent here cannot be dragged toward at all (useSwipeStack
+   *  treats it as a wall) and gets no fallback button or stamp. SwipeStack
+   *  itself has no opinion on what a direction *means* — that vocabulary
+   *  belongs entirely to the caller. */
+  directions: Partial<Record<SwipeDirection, SwipeDirectionMeta>>;
+  /** Fires once a drag (or a fallback button) commits to a direction. Every
+   *  configured direction behaves the same way: the card leaves for good —
+   *  there is no reversible "go back" state. SwipeStack has no opinion on
+   *  where card data lives; the caller is responsible for eventually no
+   *  longer including this cardId in children (e.g. once a mutation lands). */
+  onSwipe: (direction: SwipeDirection, cardId: string) => void;
+  /** Effective drag distance (px) required to commit. Passed straight
+   *  through to useSwipeStack. */
+  threshold?: number;
+  className?: string;
+  /** Must be SwipeStackCard elements (nullish/boolean children are safely
+   *  skipped for conditional cards). A dev-mode warning is logged for any
+   *  other child type — see resolveCards below. */
+  children: ReactNode;
+}
+
+interface ResolvedCard {
+  key: string;
+  element: ReactElement;
+}
+
+const DIRECTION_KEYS: readonly SwipeDirection[] = ['up', 'down', 'left', 'right'];
+
+const STAMP_CLASS: Record<SwipeDirection, string> = {
+  up: styles.stampUp as string,
+  down: styles.stampDown as string,
+  left: styles.stampLeft as string,
+  right: styles.stampRight as string,
+};
+
+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 resolveCards(children: ReactNode): ResolvedCard[] {
+  const cards: ResolvedCard[] = [];
+  Children.forEach(children, (child, index) => {
+    if (child === null || child === undefined || child === false || child === true) return;
+    if (!isValidElement(child) || child.type !== SwipeStackCard) {
+      if (process.env.NODE_ENV !== 'production') {
+        console.error(
+          '[SwipeStack] Every child must be a <SwipeStackCard>. ' +
+            `Found ${describeChild(child)} at position ${index}.`,
+        );
+      }
+      return;
+    }
+    const cardProps = child.props as { cardId: string };
+    cards.push({ key: cardProps.cardId, element: child });
+  });
+  return cards;
+}
+
+/**
+ * SwipeStack — a compound component for triaging one card at a time by
+ * dragging it left/right/up/down (wrapping useSwipeStack), plus an
+ * always-visible non-gesture fallback: a button per configured direction,
+ * wired to the identical commit path and exit animation as a real drag.
+ *
+ * Every direction is independently optional and behaves the same way once
+ * triggered — the card leaves for good, there is no reversible "go back".
+ * SwipeStack owns rendering, drag physics, and the stamp/fallback UI only;
+ * it has no opinion on where card data lives or what a direction means —
+ * see SwipeStackProps.onSwipe.
+ */
+export function SwipeStack({
+  'aria-label': ariaLabel,
+  directions,
+  onSwipe,
+  threshold,
+  className,
+  children,
+}: SwipeStackProps) {
+  const cards = resolveCards(children);
+  const [dismissed, setDismissed] = useState<ReadonlySet<string>>(() => new Set());
+  const [exiting, setExiting] = useState<ResolvedCard | null>(null);
+  const exitTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+
+  useEffect(
+    () => () => {
+      if (exitTimerRef.current) clearTimeout(exitTimerRef.current);
+    },
+    [],
+  );
+
+  const available = cards.filter((c) => !dismissed.has(c.key));
+  const nextUp = available[0];
+  const current = exiting ?? nextUp ?? null;
+  const peek = exiting ? nextUp : available[1];
+
+  const liveDirections = DIRECTION_KEYS.filter((d) => directions[d]);
+
+  const { cardRef, wrapRef, handlers, touchAction, triggerCommit } = useSwipeStack({
+    directions: liveDirections,
+    threshold,
+    disabled: !!exiting || !nextUp,
+    onCommit(direction) {
+      const committed = current;
+      if (!committed) return;
+      setDismissed((prev) => new Set(prev).add(committed.key));
+      setExiting(committed);
+      if (exitTimerRef.current) clearTimeout(exitTimerRef.current);
+      exitTimerRef.current = setTimeout(() => {
+        setExiting((prev) => (prev?.key === committed.key ? null : prev));
+      }, SWIPE_STACK_TRANSITION_MS);
+      onSwipe(direction, committed.key);
+    },
+  });
+
+  return (
+    <div className={[styles.wrap, className].filter(Boolean).join(' ')}>
+      <div className={styles.stack} role="region" aria-label={ariaLabel}>
+        {peek && (
+          <div className={styles.peek} key={peek.key} aria-hidden="true">
+            {peek.element}
+          </div>
+        )}
+        {current && (
+          <div className={styles.cardSlot} key={current.key} ref={wrapRef}>
+            {liveDirections.map((d) => {
+              const meta = directions[d];
+              if (!meta) return null;
+              return (
+                <div
+                  key={d}
+                  className={[styles.stamp, STAMP_CLASS[d]].join(' ')}
+                  aria-hidden="true"
+                >
+                  {meta.icon && <Icon name={meta.icon} size="sm" aria-hidden />}
+                  <span>{meta.label}</span>
+                </div>
+              );
+            })}
+            <div className={styles.card} ref={cardRef} style={{ touchAction }} {...handlers}>
+              {current.element}
+            </div>
+          </div>
+        )}
+      </div>
+      {liveDirections.length > 0 && (
+        <div className={styles.actions} role="group" aria-label={`${ariaLabel} actions`}>
+          {liveDirections.map((d) => {
+            const meta = directions[d];
+            if (!meta) return null;
+            return (
+              <Button
+                key={d}
+                variant="secondary"
+                size="sm"
+                disabled={!current}
+                onClick={() => triggerCommit(d)}
+              >
+                {meta.icon && <Icon name={meta.icon} size="sm" aria-hidden />}
+                {meta.label}
+              </Button>
+            );
+          })}
+        </div>
+      )}
+    </div>
+  );
+}

package/src/components/SwipeStack/SwipeStackCard.tsx

@@ -0,0 +1,22 @@
+import type { ReactNode } from 'react';
+
+export interface SwipeStackCardProps {
+  /** Stable identity for this card, independent of its position among
+   *  siblings — required. This is what SwipeStack reads (via child.props,
+   *  not React's own `key`, which a component can't see on itself) to know
+   *  which card is on top and what id to report through onSwipe. Reuse
+   *  whatever id the caller already keys their `.map()` on. */
+  cardId: string;
+  children: ReactNode;
+}
+
+/**
+ * SwipeStackCard — a single card of a SwipeStack. Unlike
+ * SwipableMobileCarouselSlide, this has no mount-window logic of its own:
+ * SwipeStack only ever renders the top two cards' elements at all (there is
+ * no scroll-position reason to keep every sibling in the DOM the way the
+ * carousel's scroll-snap track does), so there is nothing here to gate.
+ */
+export function SwipeStackCard({ children }: SwipeStackCardProps) {
+  return <>{children}</>;
+}