@sovereignfs/ui 0.41.0 → 0.54.0

package/src/components/SwipableMobileCarousel/SwipableMobileCarouselSlide.tsx

@@ -0,0 +1,35 @@
+'use client';
+
+import { useContext, type ReactNode } from 'react';
+import { CarouselSlideMountContext } from './context';
+
+export interface SwipableMobileCarouselSlideProps {
+  /** Stable identity for this slide, independent of its position among
+   *  siblings — required. This is what makes SwipableMobileCarousel's
+   *  reorder-jump fix possible: a plain array index can't distinguish "this
+   *  slide moved to position 2" from "this slide was removed and a
+   *  different one is now at position 2." Reuse whatever id the caller
+   *  already keys their `.map()` on (e.g. a list's own id). */
+  slideKey: string;
+  /** Accessible label surfaced to the default dots indicator (e.g.
+   *  "Groceries"). Falls back to "Slide N of count" if omitted — omitting it
+   *  logs a dev-mode warning, since every real slide usually has a title
+   *  available synchronously already. */
+  label?: string;
+  /** SwipableMobileCarouselSlideHeader/Body/Footer, in any order/subset. */
+  children: ReactNode;
+}
+
+/**
+ * SwipableMobileCarouselSlide — a single slide of a SwipableMobileCarousel.
+ * Renders its children only while within the carousel's mount window (the
+ * active slide ± its configured prefetchDistance); outside that window it
+ * renders nothing, matching both sovereign-tasks and sovereign-shopper's
+ * existing "never fetch/render a non-neighbor slide" behavior, now
+ * centralized instead of hand-rolled per plugin.
+ */
+export function SwipableMobileCarouselSlide({ children }: SwipableMobileCarouselSlideProps) {
+  const ctx = useContext(CarouselSlideMountContext);
+  if (!ctx?.isMounted) return null;
+  return <>{children}</>;
+}

package/src/components/SwipableMobileCarousel/SwipableMobileCarouselSlideBody.tsx

@@ -0,0 +1,42 @@
+import type { ReactNode } from 'react';
+import styles from './SwipableMobileCarouselSlideParts.module.css';
+
+export interface SwipableMobileCarouselSlideBodyProps {
+  children: ReactNode;
+  /** While true, renders `loadingFallback` INSTEAD OF children — scoped to
+   *  just this region, not the whole slide. This is what fixes the
+   *  "whole slide blanks out, title included, until its own fetch resolves"
+   *  bug: a caller renders `<SwipableMobileCarouselSlideHeader>` from
+   *  already-known metadata unconditionally, and gates only this component's
+   *  `loading` on the slower fetch — the natural way to compose
+   *  Header/Body/Footer as siblings already produces that behavior, instead
+   *  of gating the entire slide behind one boolean. */
+  loading?: boolean;
+  loadingFallback?: ReactNode;
+  className?: string;
+}
+
+const defaultLoadingFallback = <div className={styles.loading}>Loading…</div>;
+
+/**
+ * SwipableMobileCarouselSlideBody — the scrollable region of a slide.
+ *
+ * Deliberately does not set `touch-action: pan-y` on its scroll container
+ * (see SwipableMobileCarouselSlideParts.module.css's `.body` rule) — that
+ * would intersect-to-empty against the carousel's own horizontal
+ * touch-action handling (docs/architecture-rules.md's touch-action
+ * intersection rule), breaking both the vertical scroll here and the
+ * horizontal swipe between slides.
+ */
+export function SwipableMobileCarouselSlideBody({
+  children,
+  loading = false,
+  loadingFallback,
+  className,
+}: SwipableMobileCarouselSlideBodyProps) {
+  return (
+    <div className={[styles.body, className].filter(Boolean).join(' ')}>
+      {loading ? (loadingFallback ?? defaultLoadingFallback) : children}
+    </div>
+  );
+}

package/src/components/SwipableMobileCarousel/SwipableMobileCarouselSlideFooter.tsx

@@ -0,0 +1,18 @@
+import type { ReactNode } from 'react';
+import styles from './SwipableMobileCarouselSlideParts.module.css';
+
+export interface SwipableMobileCarouselSlideFooterProps {
+  children: ReactNode;
+  className?: string;
+}
+
+/**
+ * SwipableMobileCarouselSlideFooter — always renders its children, no
+ * loading concept. See SwipableMobileCarouselSlideHeader's doc comment.
+ */
+export function SwipableMobileCarouselSlideFooter({
+  children,
+  className,
+}: SwipableMobileCarouselSlideFooterProps) {
+  return <div className={[styles.footer, className].filter(Boolean).join(' ')}>{children}</div>;
+}

package/src/components/SwipableMobileCarousel/SwipableMobileCarouselSlideHeader.tsx

@@ -0,0 +1,21 @@
+import type { ReactNode } from 'react';
+import styles from './SwipableMobileCarouselSlideParts.module.css';
+
+export interface SwipableMobileCarouselSlideHeaderProps {
+  children: ReactNode;
+  className?: string;
+}
+
+/**
+ * SwipableMobileCarouselSlideHeader — always renders its children, no
+ * loading concept. Meant for content already known synchronously (a list's
+ * title, color, item count from data the caller already has) so it can
+ * render immediately even while SwipableMobileCarouselSlideBody's own
+ * content is still loading — see that component's doc comment.
+ */
+export function SwipableMobileCarouselSlideHeader({
+  children,
+  className,
+}: SwipableMobileCarouselSlideHeaderProps) {
+  return <div className={[styles.header, className].filter(Boolean).join(' ')}>{children}</div>;
+}

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

@@ -0,0 +1,29 @@
+.header,
+.footer {
+  flex: 0 0 auto;
+}
+
+.body {
+  flex: 1 1 auto;
+  min-height: 0; /* allow shrinking inside the slide's flex column, so it can scroll instead of overflowing */
+  overflow-y: auto;
+  overflow-x: hidden;
+  /* Deliberately does NOT set touch-action: pan-y here. touch-action's
+     effective value is the INTERSECTION of this element's and every
+     ancestor's value (docs/architecture-rules.md) — the ancestor .scroller
+     (SwipableMobileCarousel.module.css) needs the horizontal swipe gesture,
+     so pan-y here ∩ that horizontal handling would resolve to neither axis
+     working natively. Relying on the browser's default touch-action (auto)
+     here lets native gesture arbitration between the two nested scrollers
+     sort out which axis wins per-gesture — don't "fix" perceived nested-
+     scroll jank by adding pan-y; it silently breaks horizontal swipe instead. */
+}
+
+.loading {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  height: 100%;
+  color: var(--sv-color-text-subtle);
+  font-size: var(--sv-font-size-sm);
+}

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

@@ -0,0 +1,133 @@
+// @vitest-environment jsdom
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { act, cleanup, fireEvent, render, screen } from '@testing-library/react';
+import { SwipableMobileCarousel } from '../SwipableMobileCarousel';
+import { SwipableMobileCarouselSlide } from '../SwipableMobileCarouselSlide';
+import { SwipableMobileCarouselSlideHeader } from '../SwipableMobileCarouselSlideHeader';
+import { SwipableMobileCarouselSlideBody } from '../SwipableMobileCarouselSlideBody';
+
+// Same jsdom scroll polyfill/fake-timer setup as useSnapCarousel.test.tsx,
+// since this component wraps that hook directly.
+beforeEach(() => {
+  vi.useFakeTimers();
+  if (!Element.prototype.scrollTo) {
+    Element.prototype.scrollTo = vi.fn();
+  }
+});
+
+afterEach(() => {
+  vi.runOnlyPendingTimers();
+  vi.useRealTimers();
+  cleanup();
+});
+
+function setLayout(el: HTMLElement, clientWidth: number, scrollLeft: number) {
+  Object.defineProperty(el, 'clientWidth', { value: clientWidth, configurable: true });
+  Object.defineProperty(el, 'scrollLeft', { value: scrollLeft, configurable: true });
+}
+
+const KEYS = ['a', 'b', 'c', 'd', 'e'];
+
+function FiveSlides({
+  activeIndex,
+  onSettle,
+}: {
+  activeIndex: number;
+  onSettle: (i: number) => void;
+}) {
+  return (
+    <SwipableMobileCarousel activeIndex={activeIndex} onSettle={onSettle} aria-label="Test slides">
+      {KEYS.map((key) => (
+        <SwipableMobileCarouselSlide key={key} slideKey={key} label={key}>
+          <SwipableMobileCarouselSlideHeader>{`header-${key}`}</SwipableMobileCarouselSlideHeader>
+          <SwipableMobileCarouselSlideBody>{`body-${key}`}</SwipableMobileCarouselSlideBody>
+        </SwipableMobileCarouselSlide>
+      ))}
+    </SwipableMobileCarousel>
+  );
+}
+
+describe('SwipableMobileCarousel', () => {
+  it('only mounts the active slide and its immediate neighbors (default prefetchDistance=1)', () => {
+    render(<FiveSlides activeIndex={2} onSettle={() => {}} />);
+    // active (c) and neighbors (b, d) are mounted
+    expect(screen.getByText('header-b')).toBeDefined();
+    expect(screen.getByText('header-c')).toBeDefined();
+    expect(screen.getByText('header-d')).toBeDefined();
+    // out-of-window slides (a, e) render nothing at all
+    expect(screen.queryByText('header-a')).toBeNull();
+    expect(screen.queryByText('body-a')).toBeNull();
+    expect(screen.queryByText('header-e')).toBeNull();
+    expect(screen.queryByText('body-e')).toBeNull();
+  });
+
+  it("SlideBody's loading prop only hides that region, not the Header", () => {
+    render(
+      <SwipableMobileCarousel activeIndex={0} onSettle={() => {}} aria-label="Test slides">
+        <SwipableMobileCarouselSlide slideKey="only" label="Only">
+          <SwipableMobileCarouselSlideHeader>the-title</SwipableMobileCarouselSlideHeader>
+          <SwipableMobileCarouselSlideBody loading>tasks-content</SwipableMobileCarouselSlideBody>
+        </SwipableMobileCarouselSlide>
+      </SwipableMobileCarousel>,
+    );
+    expect(screen.getByText('the-title')).toBeDefined();
+    expect(screen.queryByText('tasks-content')).toBeNull();
+    expect(screen.getByText('Loading…')).toBeDefined();
+  });
+
+  it('calls onSettle with the new index after a swipe settles', () => {
+    const onSettle = vi.fn();
+    render(<FiveSlides activeIndex={0} onSettle={onSettle} />);
+    const scroller = screen.getByRole('region', { name: 'Test slides' });
+    setLayout(scroller, 300, 300); // scrollLeft 300 / width 300 -> index 1
+    fireEvent.scroll(scroller);
+    act(() => void vi.advanceTimersByTime(120));
+    expect(onSettle).toHaveBeenCalledWith(1);
+  });
+
+  it('clicking a dot calls onSettle directly with that index', () => {
+    const onSettle = vi.fn();
+    render(<FiveSlides activeIndex={0} onSettle={onSettle} />);
+    const dots = screen.getAllByRole('tab');
+    const fourthDot = dots[3];
+    if (!fourthDot) throw new Error('expected a 4th dot');
+    setLayout(screen.getByRole('region', { name: 'Test slides' }), 300, 0);
+    fireEvent.click(fourthDot);
+    expect(onSettle).toHaveBeenCalledWith(3);
+  });
+
+  it('re-snaps and reports the new index when the active slide moves position (reorder-jump fix)', () => {
+    function Reorderable({ order, onSettle }: { order: string[]; onSettle: (i: number) => void }) {
+      return (
+        <SwipableMobileCarousel activeIndex={1} onSettle={onSettle} aria-label="Test slides">
+          {order.map((key) => (
+            <SwipableMobileCarouselSlide key={key} slideKey={key} label={key}>
+              <SwipableMobileCarouselSlideHeader>{`header-${key}`}</SwipableMobileCarouselSlideHeader>
+            </SwipableMobileCarouselSlide>
+          ))}
+        </SwipableMobileCarousel>
+      );
+    }
+    const onSettle = vi.fn();
+    const { rerender } = render(<Reorderable order={['a', 'b', 'c']} onSettle={onSettle} />);
+    const scroller = screen.getByRole('region', { name: 'Test slides' });
+    setLayout(scroller, 300, 0);
+    const spy = vi.spyOn(scroller, 'scrollTo');
+
+    // 'b' (index 1, active) moves to index 0.
+    rerender(<Reorderable order={['b', 'a', 'c']} onSettle={onSettle} />);
+
+    expect(onSettle).toHaveBeenCalledWith(0);
+    expect(spy).toHaveBeenCalledWith({ left: 0, behavior: 'instant' });
+  });
+
+  it('does not re-snap when slide order is unchanged', () => {
+    function Reorderable({ onSettle }: { onSettle: (i: number) => void }) {
+      return <FiveSlides activeIndex={2} onSettle={onSettle} />;
+    }
+    const onSettle = vi.fn();
+    const { rerender } = render(<Reorderable onSettle={onSettle} />);
+    rerender(<Reorderable onSettle={onSettle} />);
+    expect(onSettle).not.toHaveBeenCalled();
+  });
+});

package/src/components/SwipableMobileCarousel/__tests__/SwipableMobileCarouselDevGuard.test.tsx

@@ -0,0 +1,61 @@
+// @vitest-environment jsdom
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { cleanup, render } from '@testing-library/react';
+import { SwipableMobileCarousel } from '../SwipableMobileCarousel';
+import { SwipableMobileCarouselSlide } from '../SwipableMobileCarouselSlide';
+
+beforeEach(() => {
+  if (!Element.prototype.scrollTo) {
+    Element.prototype.scrollTo = vi.fn();
+  }
+});
+
+afterEach(() => {
+  cleanup();
+  vi.restoreAllMocks();
+});
+
+function renderWithStrayChild() {
+  return render(
+    <SwipableMobileCarousel activeIndex={0} onSettle={() => {}} aria-label="Test slides">
+      <SwipableMobileCarouselSlide slideKey="a" label="A">
+        content
+      </SwipableMobileCarouselSlide>
+      {/* stray non-Slide child — shifts index math for anything after it */}
+      <div>oops</div>
+      <SwipableMobileCarouselSlide slideKey="b" label="B">
+        content
+      </SwipableMobileCarouselSlide>
+    </SwipableMobileCarousel>,
+  );
+}
+
+describe('SwipableMobileCarousel dev-mode child-type guard', () => {
+  it('warns via console.error in development, mentioning the offending child', () => {
+    const originalEnv = process.env.NODE_ENV;
+    vi.stubEnv('NODE_ENV', 'development');
+    const errorSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
+
+    expect(() => renderWithStrayChild()).not.toThrow();
+
+    expect(errorSpy).toHaveBeenCalledWith(expect.stringContaining('<div>'));
+    vi.stubEnv('NODE_ENV', originalEnv ?? 'test');
+  });
+
+  it('does not call console.error in production', () => {
+    const originalEnv = process.env.NODE_ENV;
+    vi.stubEnv('NODE_ENV', 'production');
+    const errorSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
+
+    expect(() => renderWithStrayChild()).not.toThrow();
+
+    expect(errorSpy).not.toHaveBeenCalled();
+    vi.stubEnv('NODE_ENV', originalEnv ?? 'test');
+  });
+
+  it('never throws, even with a stray child (a miscounted slide degrades, it does not crash)', () => {
+    vi.stubEnv('NODE_ENV', 'development');
+    vi.spyOn(console, 'error').mockImplementation(() => {});
+    expect(() => renderWithStrayChild()).not.toThrow();
+  });
+});

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,49 @@
+.dots {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  gap: var(--sv-space-2);
+}
+
+.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,62 @@
+'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;
+  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,
+  className,
+}: SwipableMobileCarouselDotsProps) {
+  return (
+    <div
+      role="tablist"
+      aria-label={ariaLabel}
+      className={[styles.dots, 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/Table/Table.module.css

@@ -0,0 +1,45 @@
+/* Horizontal scroll container — masked-edge fade + hidden scrollbar, same
+   technique as NavTabs. Always active (not gated to a narrow viewport):
+   unlike NavTabs' item count, a table's column count is content-driven and
+   can overflow at any screen size. */
+.scrollContainer {
+  overflow-x: auto;
+  scrollbar-width: none;
+  -webkit-overflow-scrolling: touch;
+  mask-image: linear-gradient(to right, black calc(100% - 32px), transparent 100%);
+}
+
+.scrollContainer::-webkit-scrollbar {
+  display: none;
+}
+
+.table {
+  width: 100%;
+  border-collapse: collapse;
+  font-size: var(--sv-font-size-sm);
+}
+
+.head .row {
+  border-bottom: 1px solid var(--sv-color-border-strong);
+}
+
+.body .row {
+  border-bottom: 1px solid var(--sv-color-border);
+}
+
+.body .row:last-child {
+  border-bottom: none;
+}
+
+.th {
+  padding: var(--sv-space-2) var(--sv-space-3);
+  text-align: left;
+  font-weight: var(--sv-font-weight-semibold);
+  color: var(--sv-color-text-muted);
+  white-space: nowrap;
+}
+
+.td {
+  padding: var(--sv-space-2) var(--sv-space-3);
+  color: var(--sv-color-text-primary);
+}