@sovereignfs/ui 0.45.0 → 0.54.0

package/src/components/NavTabs/NavTabs.tsx

@@ -1,3 +1,4 @@
+import { Fragment, type ReactNode } from 'react';
 import styles from './NavTabs.module.css';
 
 export interface NavTabItem {
@@ -6,28 +7,55 @@ export interface NavTabItem {
   active?: boolean;
 }
 
+/** Props to spread onto a consumer-supplied link element — keeps NavTabs' own
+ * class names and a11y attributes in sync with whatever the consumer renders. */
+export interface NavTabLinkProps {
+  href: string;
+  className: string;
+  'aria-current': 'page' | undefined;
+  children: ReactNode;
+}
+
 export interface NavTabsProps {
   items: NavTabItem[];
   className?: string;
   'aria-label'?: string;
+  /** Render a tab as something other than a plain `<a href>` — e.g. Next's
+   * `<Link replace>` inside an overlay-shell plugin, where a full page
+   * navigation would break the dialog's history contract. Receives the item
+   * plus the class name/aria attributes NavTabs would otherwise apply. */
+  renderLink?: (item: NavTabItem, linkProps: NavTabLinkProps) => ReactNode;
 }
 
-export function NavTabs({ items, className, 'aria-label': ariaLabel }: NavTabsProps) {
+export function NavTabs({ items, className, 'aria-label': ariaLabel, renderLink }: NavTabsProps) {
   return (
     <nav
       className={[styles.nav, className].filter(Boolean).join(' ')}
       aria-label={ariaLabel ?? 'Page navigation'}
     >
-      {items.map((item) => (
-        <a
-          key={item.href}
-          href={item.href}
-          className={[styles.link, item.active && styles.active].filter(Boolean).join(' ')}
-          aria-current={item.active ? 'page' : undefined}
-        >
-          {item.label}
-        </a>
-      ))}
+      {items.map((item) => {
+        const linkProps: NavTabLinkProps = {
+          href: item.href,
+          className: [styles.link, item.active && styles.active].filter(Boolean).join(' '),
+          'aria-current': item.active ? 'page' : undefined,
+          children: item.label,
+        };
+        return (
+          <Fragment key={item.href}>
+            {renderLink ? (
+              renderLink(item, linkProps)
+            ) : (
+              <a
+                href={linkProps.href}
+                className={linkProps.className}
+                aria-current={linkProps['aria-current']}
+              >
+                {linkProps.children}
+              </a>
+            )}
+          </Fragment>
+        );
+      })}
     </nav>
   );
 }

package/src/components/OfflineGate/OfflineGate.tsx

@@ -0,0 +1,44 @@
+'use client';
+
+import type { ReactNode } from 'react';
+import { useIsOffline } from '../../hooks/useIsOffline';
+import { EmptyState } from '../EmptyState/EmptyState';
+
+export interface OfflineGateProps {
+  children: ReactNode;
+  /** Defaults to a generic "this section" phrasing — pass the surface's own name. */
+  surfaceName?: string;
+  className?: string;
+}
+
+/**
+ * OfflineGate — blocks administrative/settings surfaces from rendering
+ * (possibly stale) cached content while the device has no network, showing an
+ * explanatory empty state instead (research 0012, epic task 2.32).
+ *
+ * Distinct from `OfflineBanner`: the banner is an informational overlay that
+ * coexists with normal content everywhere in the shell. This is a hard block
+ * for surfaces where operating against stale data is actively wrong — e.g. a
+ * Console user list or an Account billing page reflects a point-in-time
+ * snapshot the moment it's server-rendered, and any cached copy replayed
+ * later has no way to signal that it may already be stale. `OfflineGate`
+ * doesn't try to tell staleness apart from freshness; it removes the
+ * question by not rendering the content at all while offline.
+ *
+ * `children` is rendered unconditionally while online, so this adds no cost
+ * to the common case — it only decides what to show, never how the wrapped
+ * content itself is fetched or cached.
+ */
+export function OfflineGate({ children, surfaceName, className }: OfflineGateProps) {
+  const isOffline = useIsOffline();
+  if (!isOffline) return <>{children}</>;
+
+  return (
+    <EmptyState
+      icon="alert-triangle"
+      heading="You're offline"
+      description={`${surfaceName ?? 'This section'} needs a connection — reconnect to continue.`}
+      className={className}
+    />
+  );
+}

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

@@ -0,0 +1,66 @@
+// @vitest-environment jsdom
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { act, cleanup, render, screen } from '@testing-library/react';
+import { OfflineGate } from '../OfflineGate';
+
+describe('OfflineGate', () => {
+  beforeEach(() => {
+    vi.stubGlobal('navigator', { ...window.navigator, onLine: true });
+  });
+  afterEach(() => {
+    vi.unstubAllGlobals();
+    cleanup();
+  });
+
+  it('renders children unchanged while online', () => {
+    render(
+      <OfflineGate>
+        <p>Live content</p>
+      </OfflineGate>,
+    );
+    expect(screen.getByText('Live content')).toBeDefined();
+  });
+
+  it('replaces children with an explanatory empty state while offline', () => {
+    vi.stubGlobal('navigator', { ...window.navigator, onLine: false });
+    render(
+      <OfflineGate>
+        <p>Live content</p>
+      </OfflineGate>,
+    );
+    expect(screen.queryByText('Live content')).toBeNull();
+    expect(screen.getByText("You're offline")).toBeDefined();
+  });
+
+  it('names the surface in the offline message when provided', () => {
+    vi.stubGlobal('navigator', { ...window.navigator, onLine: false });
+    render(
+      <OfflineGate surfaceName="Console">
+        <p>Live content</p>
+      </OfflineGate>,
+    );
+    expect(screen.getByText(/Console needs a connection/)).toBeDefined();
+  });
+
+  it('falls back to generic phrasing with no surface name', () => {
+    vi.stubGlobal('navigator', { ...window.navigator, onLine: false });
+    render(
+      <OfflineGate>
+        <p>Live content</p>
+      </OfflineGate>,
+    );
+    expect(screen.getByText(/This section needs a connection/)).toBeDefined();
+  });
+
+  it('swaps back to children on reconnect', () => {
+    vi.stubGlobal('navigator', { ...window.navigator, onLine: false });
+    render(
+      <OfflineGate>
+        <p>Live content</p>
+      </OfflineGate>,
+    );
+    expect(screen.getByText("You're offline")).toBeDefined();
+    act(() => window.dispatchEvent(new Event('online')));
+    expect(screen.getByText('Live content')).toBeDefined();
+  });
+});

package/src/components/PageContainer/PageContainer.module.css

@@ -0,0 +1,20 @@
+.container {
+  width: 100%;
+  margin-inline: auto;
+}
+
+.sm {
+  max-width: 640px;
+}
+
+.md {
+  max-width: 960px;
+}
+
+.lg {
+  max-width: 1200px;
+}
+
+.full {
+  max-width: none;
+}

package/src/components/PageContainer/PageContainer.tsx

@@ -0,0 +1,31 @@
+import type { HTMLAttributes, ReactNode } from 'react';
+import styles from './PageContainer.module.css';
+
+export interface PageContainerProps extends HTMLAttributes<HTMLDivElement> {
+  /** Constrains and centers content width. Adds no padding of its own — the
+   * runtime shell already pads plugin content. Defaults to 'md'. */
+  maxWidth?: 'sm' | 'md' | 'lg' | 'full';
+  children: ReactNode;
+}
+
+const maxWidthClass: Record<NonNullable<PageContainerProps['maxWidth']>, string> = {
+  sm: styles.sm as string,
+  md: styles.md as string,
+  lg: styles.lg as string,
+  full: styles.full as string,
+};
+
+export function PageContainer({
+  maxWidth = 'md',
+  className,
+  children,
+  ...rest
+}: PageContainerProps) {
+  const cls = [styles.container, maxWidthClass[maxWidth], className].filter(Boolean).join(' ');
+
+  return (
+    <div className={cls} {...rest}>
+      {children}
+    </div>
+  );
+}

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

@@ -0,0 +1,37 @@
+// @vitest-environment jsdom
+import { afterEach, describe, expect, it } from 'vitest';
+import { cleanup, render, screen } from '@testing-library/react';
+import { PageContainer } from '../PageContainer';
+
+afterEach(cleanup);
+
+describe('PageContainer', () => {
+  it('renders its children', () => {
+    render(<PageContainer>content</PageContainer>);
+    expect(screen.getByText('content')).toBeDefined();
+  });
+
+  it('defaults to md max-width', () => {
+    render(<PageContainer>content</PageContainer>);
+    expect(screen.getByText('content').className).toContain('md');
+  });
+
+  it('applies sm, lg, and full max-width classes', () => {
+    const { rerender } = render(<PageContainer maxWidth="sm">content</PageContainer>);
+    expect(screen.getByText('content').className).toContain('sm');
+    rerender(<PageContainer maxWidth="lg">content</PageContainer>);
+    expect(screen.getByText('content').className).toContain('lg');
+    rerender(<PageContainer maxWidth="full">content</PageContainer>);
+    expect(screen.getByText('content').className).toContain('full');
+  });
+
+  it('forwards className and other div props', () => {
+    render(
+      <PageContainer className="custom" data-testid="container">
+        content
+      </PageContainer>,
+    );
+    const el = screen.getByTestId('container');
+    expect(el.className).toContain('custom');
+  });
+});

package/src/components/PageHeader/PageHeader.tsx

@@ -6,13 +6,27 @@ export interface PageHeaderProps {
   description?: string;
   action?: ReactNode;
   className?: string;
+  /** Heading level for the title. Defaults to `1` for standalone use; pass
+   * `2` or `3` when the page already sits under a shell/plugin `<h1>`, to
+   * avoid a duplicate top-level heading. Visual style is unchanged at every
+   * level — only the rendered tag changes. */
+  headingLevel?: 1 | 2 | 3;
 }
 
-export function PageHeader({ title, description, action, className }: PageHeaderProps) {
+const HEADING_TAG = { 1: 'h1', 2: 'h2', 3: 'h3' } as const;
+
+export function PageHeader({
+  title,
+  description,
+  action,
+  className,
+  headingLevel = 1,
+}: PageHeaderProps) {
+  const Heading = HEADING_TAG[headingLevel];
   return (
     <header className={[styles.header, className].filter(Boolean).join(' ')}>
       <div className={styles.text}>
-        <h1 className={styles.title}>{title}</h1>
+        <Heading className={styles.title}>{title}</Heading>
         {description && <p className={styles.description}>{description}</p>}
       </div>
       {action && <div className={styles.action}>{action}</div>}

package/src/components/ResponsiveSurface/ResponsiveSurface.tsx

@@ -0,0 +1,24 @@
+import type { ReactNode } from 'react';
+import { useResponsiveLayout } from '../../hooks/useResponsiveLayout';
+
+export interface ResponsiveSurfaceProps {
+  web: ReactNode;
+  mobile: ReactNode;
+  breakpointPx?: number;
+}
+
+/**
+ * ResponsiveSurface — thin JSX convenience wrapper around
+ * `useResponsiveLayout` for the common two-tree case: render an entirely
+ * different component tree below the breakpoint, not a CSS squeeze of the
+ * same one. Renders only whichever side is active — the other tree is never
+ * mounted.
+ *
+ * This does not replace a plugin's own shell component (e.g. a
+ * `MobileAwareShell` that also threads plugin-specific props like a refresh
+ * signal) — those stay a thin per-plugin wrapper around this.
+ */
+export function ResponsiveSurface({ web, mobile, breakpointPx }: ResponsiveSurfaceProps) {
+  const { value } = useResponsiveLayout({ web, mobile, breakpointPx });
+  return <>{value}</>;
+}

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

@@ -0,0 +1,73 @@
+// @vitest-environment jsdom
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { act, cleanup, render, screen } from '@testing-library/react';
+import { ResponsiveSurface } from '../ResponsiveSurface';
+
+let changeHandler: ((e: MediaQueryListEvent) => void) | null = null;
+let matches = false;
+
+function installMatchMedia() {
+  changeHandler = null;
+  vi.stubGlobal(
+    'matchMedia',
+    vi.fn().mockImplementation((query: string) => ({
+      matches,
+      media: query,
+      addEventListener: (_: string, cb: (e: MediaQueryListEvent) => void) => {
+        changeHandler = cb;
+      },
+      removeEventListener: vi.fn(),
+      addListener: vi.fn(),
+      removeListener: vi.fn(),
+      dispatchEvent: vi.fn(),
+    })),
+  );
+}
+
+describe('ResponsiveSurface', () => {
+  beforeEach(() => {
+    matches = false;
+    installMatchMedia();
+  });
+  afterEach(() => {
+    vi.unstubAllGlobals();
+    cleanup();
+  });
+
+  it('renders the web tree by default and never mounts the mobile tree', () => {
+    render(
+      <ResponsiveSurface
+        web={<div data-testid="web">web</div>}
+        mobile={<div data-testid="mobile">mobile</div>}
+      />,
+    );
+    expect(screen.getByTestId('web')).toBeDefined();
+    expect(screen.queryByTestId('mobile')).toBeNull();
+  });
+
+  it('renders only the mobile tree below the breakpoint', () => {
+    matches = true;
+    installMatchMedia();
+    render(
+      <ResponsiveSurface
+        web={<div data-testid="web">web</div>}
+        mobile={<div data-testid="mobile">mobile</div>}
+      />,
+    );
+    expect(screen.getByTestId('mobile')).toBeDefined();
+    expect(screen.queryByTestId('web')).toBeNull();
+  });
+
+  it('swaps trees live when the viewport crosses the breakpoint', () => {
+    render(
+      <ResponsiveSurface
+        web={<div data-testid="web">web</div>}
+        mobile={<div data-testid="mobile">mobile</div>}
+      />,
+    );
+    expect(screen.getByTestId('web')).toBeDefined();
+    act(() => changeHandler?.({ matches: true } as MediaQueryListEvent));
+    expect(screen.getByTestId('mobile')).toBeDefined();
+    expect(screen.queryByTestId('web')).toBeNull();
+  });
+});

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/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;
+}