@sovereignfs/ui 0.41.0 → 0.54.0

package/src/components/DeviceStorageKeyGate/DeviceStorageKeyGate.tsx

@@ -0,0 +1,100 @@
+'use client';
+
+import type { ReactNode } from 'react';
+import { EmptyState } from '../EmptyState/EmptyState';
+
+/**
+ * `'checking'` covers the moment before the caller's own async status check
+ * resolves — same transitional-state pattern `EncryptionSection`'s local
+ * `LocalState` uses, so this gate never flashes an empty state before the
+ * real answer is known. `'no-device-auth'` is the hard-block case (RFC 0093
+ * §5, epic task 1.22): the environment supports the tier, but this device
+ * has no passcode, fingerprint, or face unlock configured, so a key cannot
+ * be created here at all — distinct from `'not-set-up'`, where it can.
+ */
+export type DeviceStorageKeyGateStatus =
+  'checking' | 'unsupported' | 'no-device-auth' | 'not-set-up' | 'set-up';
+
+export interface DeviceStorageKeyGateProps {
+  children: ReactNode;
+  /** Defaults to a generic "This app" phrasing — pass the plugin's own name. */
+  surfaceName?: string;
+  /**
+   * The caller's own `getDeviceStorageKeyStatus()` result (from
+   * `@sovereignfs/sdk/device-only-storage`) — taken as a plain status rather
+   * than computed inside this component, so `@sovereignfs/ui` never depends
+   * on `@sovereignfs/sdk` (same boundary `DeviceOnlyGate`'s `available` prop
+   * draws — this package must stay usable standalone, outside the plugin
+   * runtime — RFC 0073).
+   */
+  status: DeviceStorageKeyGateStatus;
+  /**
+   * Rendered under the "not set up" message — typically a link to Account →
+   * Security. Not built in here: this package depends on no router, so the
+   * caller supplies its own navigable element (a plain `<a>`, a framework
+   * `<Link>`, whatever the host app uses).
+   */
+  setupAction?: ReactNode;
+  className?: string;
+}
+
+/**
+ * DeviceStorageKeyGate — blocks a `device-only`-tier plugin's content until
+ * the user has set up their Device Storage Key (RFC 0093 §2, epic task
+ * 1.22). Distinct from `DeviceOnlyGate`: that one checks whether the *tier
+ * itself* is available on this surface (native shell, secure-storage bridge
+ * present); this one checks whether the user has actually completed the
+ * one-time, per-device enrollment that tier depends on. A `device-only`
+ * plugin typically wants both — `DeviceOnlyGate` outermost (no point
+ * checking enrollment on a surface that cannot offer the tier at all), this
+ * gate inside it.
+ *
+ * Enrollment is centralized and decoupled from any single plugin (RFC 0093
+ * §2): a plugin that finds no key set up does not run its own enrollment
+ * ceremony inline. It stops here and points the user at Account → Security —
+ * the one place enrollment happens for every `device-only` plugin on this
+ * device — via `setupAction`, the same opt-in, self-applied pattern
+ * `OfflineGate`/`DeviceOnlyGate` already use for their own surfaces.
+ */
+export function DeviceStorageKeyGate({
+  children,
+  surfaceName,
+  status,
+  setupAction,
+  className,
+}: DeviceStorageKeyGateProps) {
+  if (status === 'checking') return null;
+  if (status === 'set-up') return <>{children}</>;
+
+  if (status === 'unsupported') {
+    return (
+      <EmptyState
+        icon="smartphone"
+        heading="Phone only"
+        description={`${surfaceName ?? 'This app'} needs a security feature (WebAuthn PRF and Origin Private File System support) that isn't available here.`}
+        className={className}
+      />
+    );
+  }
+
+  if (status === 'no-device-auth') {
+    return (
+      <EmptyState
+        icon="alert-triangle"
+        heading="Set up a device passcode"
+        description={`${surfaceName ?? 'This app'} needs a passcode, fingerprint, or face unlock set up on this device before its Device Storage Key can be created. Set one up in your device's system settings, then come back.`}
+        className={className}
+      />
+    );
+  }
+
+  return (
+    <EmptyState
+      icon="lock"
+      heading="Set up your Device Storage Key"
+      description={`${surfaceName ?? 'This app'} keeps its data only on this device, protected by a Device Storage Key you set up once in Account → Security.`}
+      action={setupAction}
+      className={className}
+    />
+  );
+}

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

@@ -0,0 +1,119 @@
+// @vitest-environment jsdom
+import { afterEach, describe, expect, it } from 'vitest';
+import { cleanup, render, screen } from '@testing-library/react';
+import { DeviceStorageKeyGate } from '../DeviceStorageKeyGate';
+
+describe('DeviceStorageKeyGate', () => {
+  afterEach(cleanup);
+
+  it('renders nothing while checking', () => {
+    const { container } = render(
+      <DeviceStorageKeyGate status="checking">
+        <p>Notes content</p>
+      </DeviceStorageKeyGate>,
+    );
+    expect(container.firstChild).toBeNull();
+  });
+
+  it('renders children unchanged once set up', () => {
+    render(
+      <DeviceStorageKeyGate status="set-up">
+        <p>Notes content</p>
+      </DeviceStorageKeyGate>,
+    );
+    expect(screen.getByText('Notes content')).toBeDefined();
+  });
+
+  it('shows a "Phone only"-style message when the environment is unsupported', () => {
+    render(
+      <DeviceStorageKeyGate status="unsupported">
+        <p>Notes content</p>
+      </DeviceStorageKeyGate>,
+    );
+    expect(screen.queryByText('Notes content')).toBeNull();
+    expect(screen.getByText('Phone only')).toBeDefined();
+  });
+
+  it('shows the setup message and prompt when not-set-up', () => {
+    render(
+      <DeviceStorageKeyGate status="not-set-up">
+        <p>Notes content</p>
+      </DeviceStorageKeyGate>,
+    );
+    expect(screen.queryByText('Notes content')).toBeNull();
+    expect(screen.getByText('Set up your Device Storage Key')).toBeDefined();
+  });
+
+  it('names the surface in the not-set-up message when provided', () => {
+    render(
+      <DeviceStorageKeyGate status="not-set-up" surfaceName="Notes">
+        <p>Notes content</p>
+      </DeviceStorageKeyGate>,
+    );
+    expect(screen.getByText(/Notes keeps its data only on this device/)).toBeDefined();
+  });
+
+  it('falls back to generic phrasing with no surface name', () => {
+    render(
+      <DeviceStorageKeyGate status="not-set-up">
+        <p>Notes content</p>
+      </DeviceStorageKeyGate>,
+    );
+    expect(screen.getByText(/This app keeps its data only on this device/)).toBeDefined();
+  });
+
+  it('renders the caller-supplied setupAction when not-set-up', () => {
+    render(
+      <DeviceStorageKeyGate
+        status="not-set-up"
+        setupAction={<a href="/account/security">Go to Account → Security</a>}
+      >
+        <p>Notes content</p>
+      </DeviceStorageKeyGate>,
+    );
+    expect(screen.getByRole('link', { name: 'Go to Account → Security' })).toBeDefined();
+  });
+
+  it('renders no setupAction when unsupported, even if one is passed', () => {
+    render(
+      <DeviceStorageKeyGate
+        status="unsupported"
+        setupAction={<a href="/account/security">Go to Account → Security</a>}
+      >
+        <p>Notes content</p>
+      </DeviceStorageKeyGate>,
+    );
+    expect(screen.queryByRole('link')).toBeNull();
+  });
+
+  it('shows the hard-block message when no-device-auth', () => {
+    render(
+      <DeviceStorageKeyGate status="no-device-auth">
+        <p>Notes content</p>
+      </DeviceStorageKeyGate>,
+    );
+    expect(screen.queryByText('Notes content')).toBeNull();
+    expect(screen.getByText('Set up a device passcode')).toBeDefined();
+  });
+
+  it('names the surface in the no-device-auth message when provided', () => {
+    render(
+      <DeviceStorageKeyGate status="no-device-auth" surfaceName="Notes">
+        <p>Notes content</p>
+      </DeviceStorageKeyGate>,
+    );
+    expect(screen.getByText(/Notes needs a passcode, fingerprint, or face unlock/)).toBeDefined();
+  });
+
+  it('renders no setupAction when no-device-auth, even if one is passed — fixing this is a device settings change, not a Sovereign link', () => {
+    render(
+      <DeviceStorageKeyGate
+        status="no-device-auth"
+        setupAction={<a href="/account/security">Go to Account → Security</a>}
+      >
+        <p>Notes content</p>
+      </DeviceStorageKeyGate>,
+    );
+    expect(screen.queryByRole('link')).toBeNull();
+  });
+});

package/src/components/Dialog/Dialog.module.css

@@ -79,6 +79,9 @@
   }
 }
 
+/* Sizing audit: reviewed padding/radius against this scale's other
+   surfaces. --sv-radius-lg (shared with Card via .panel below) left
+   unchanged for the same blast-radius reason as Card.module.css. */
 .content {
   flex: 1 1 auto;
   overflow-y: auto;

package/src/components/Dialog/Dialog.tsx

@@ -1,8 +1,12 @@
 'use client';
 
 import { createContext, type ReactNode, useContext, useEffect, useRef, useState } from 'react';
-import { lockBodyScroll, unlockBodyScroll } from '../../scroll-lock';
 import { useMountTransition, usePrefersReducedMotion } from '../../motion';
+import {
+  useOverlayFocusCapture,
+  useOverlayKeyboardTrap,
+  useOverlayScrollLock,
+} from '../../overlay-shell';
 import { OverlayHeader } from '../OverlayHeader/OverlayHeader';
 import styles from './Dialog.module.css';
 
@@ -69,9 +73,6 @@ export interface DialogProps {
   children: ReactNode;
 }
 
-const FOCUSABLE =
-  'a[href], button:not([disabled]), textarea:not([disabled]), input:not([disabled]), select:not([disabled]), [tabindex]:not([tabindex="-1"])';
-
 /**
  * Dialog — a modal surface (scrim + panel) for overlay-shell plugins and any
  * plugin that needs a dismissable layer. Router-agnostic: the caller decides
@@ -97,65 +98,13 @@ export function Dialog({
   children,
 }: DialogProps) {
   const panelRef = useRef<HTMLDivElement>(null);
-  const previouslyFocused = useRef<HTMLElement | null>(null);
   const reducedMotion = usePrefersReducedMotion();
   const { mounted, phase } = useMountTransition(open, reducedMotion ? 0 : MOTION_DURATION_MS);
   const [secondRow, setSecondRow] = useState<ReactNode | null>(null);
 
-  // Prevent document-level scroll for the whole mounted lifetime, including
-  // the exit animation — not just while `open` — so the background can't
-  // scroll while the panel is still visibly sliding/fading away. Ref-counted
-  // so nested overlays (e.g. a confirmation dialog inside an overlay plugin)
-  // don't release the lock while a sibling is still open.
-  useEffect(() => {
-    if (!mounted) return;
-    lockBodyScroll();
-    return unlockBodyScroll;
-  }, [mounted]);
-
-  // Capture focus on open; restore it on close/unmount.
-  useEffect(() => {
-    if (!open) 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();
-  }, [open]);
-
-  // Keyboard handling: Escape closes, Tab cycles within the panel (focus trap).
-  // Attached at document level so no keyboard listener is needed on the dialog
-  // div itself (which would trigger jsx-a11y/no-noninteractive-element-interactions).
-  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, open);
+  useOverlayKeyboardTrap(panelRef, open, onClose);
 
   if (!mounted) return null;
   const isOpenPhase = phase === 'open';

package/src/components/Drawer/Drawer.stories.tsx

@@ -75,6 +75,50 @@ export const Closed: Story = {
   ),
 };
 
+function DrawerWithTitleDemo() {
+  const [open, setOpen] = useState(false);
+  return (
+    <>
+      <Button onClick={() => setOpen(true)}>Open drawer</Button>
+      <Drawer open={open} onClose={() => setOpen(false)} title="Apps">
+        <ul style={{ listStyle: 'none', margin: 0, padding: '8px 0' }}>
+          {(['house', 'grid-2x2', 'settings', 'user'] as const).map((icon) => (
+            <li key={icon}>
+              <button
+                onClick={() => setOpen(false)}
+                style={{
+                  display: 'flex',
+                  alignItems: 'center',
+                  gap: 12,
+                  width: '100%',
+                  padding: '12px 20px',
+                  background: 'none',
+                  border: 'none',
+                  cursor: 'pointer',
+                  fontSize: 15,
+                  color: 'var(--sv-color-text-primary)',
+                  fontFamily: 'system-ui',
+                }}
+              >
+                <Icon name={icon} size="md" aria-hidden />
+                {icon.replace(/-/g, ' ')}
+              </button>
+            </li>
+          ))}
+        </ul>
+      </Drawer>
+    </>
+  );
+}
+
+/** Opt-in `title` prop renders a built-in `OverlayHeader` (title + close)
+ * below the grab handle — hidden by default (see the `Default` story), for
+ * consumers that want one instead of building their own header markup. */
+export const WithTitle: Story = {
+  args: { open: false, onClose: () => {}, children: null },
+  render: (_args) => <DrawerWithTitleDemo />,
+};
+
 /** Play function opens the drawer and asserts its list items are visible. */
 export const OpenViaInteraction: Story = {
   args: { open: false, onClose: () => {}, children: null },

package/src/components/Drawer/Drawer.tsx

@@ -1,8 +1,13 @@
 'use client';
 
-import { type PointerEvent as ReactPointerEvent, type ReactNode, useEffect, useRef } from 'react';
-import { lockBodyScroll, unlockBodyScroll } from '../../scroll-lock';
+import { type PointerEvent as ReactPointerEvent, 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 './Drawer.module.css';
 
 // Matches --sv-motion-duration-base (Drawer.module.css) — see Dialog.tsx's
@@ -22,12 +27,15 @@ export interface DrawerProps {
    *  "half screen or less" convention for Drawer, this is the only other
    *  supported size; taller content should use `Sheet` instead. */
   snapHeight?: 'content' | 'half';
+  /** Renders a built-in `OverlayHeader` (title + close) below the grab
+   *  handle. Omit when the content supplies its own header, or none is
+   *  needed at all — e.g. the mobile shell's Apps drawer, whose grab handle
+   *  and swipe-down/scrim-tap dismissal are enough on their own. Mirrors
+   *  `Sheet`'s identical `title` prop. */
+  title?: string;
   children: ReactNode;
 }
 
-const FOCUSABLE =
-  'a[href], button:not([disabled]), textarea:not([disabled]), input:not([disabled]), select:not([disabled]), [tabindex]:not([tabindex="-1"])';
-
 // Downward drag distance (px) past which releasing dismisses the drawer
 // instead of snapping back open. Distance-only, no velocity tracking — matches
 // the swipe-to-reveal gesture already established in consuming plugins (see
@@ -61,10 +69,10 @@ export function Drawer({
   onClose,
   'aria-label': ariaLabel,
   snapHeight = 'content',
+  title,
   children,
 }: DrawerProps) {
   const panelRef = useRef<HTMLDivElement>(null);
-  const previouslyFocused = useRef<HTMLElement | null>(null);
   const reducedMotion = usePrefersReducedMotion();
   const { mounted, phase } = useMountTransition(open, reducedMotion ? 0 : MOTION_DURATION_MS);
   // Tracks an in-progress handle drag. Kept in a ref (not state) so pointermove
@@ -72,56 +80,9 @@ export function Drawer({
   // same technique as the tasks plugin's swipe-to-reveal rows.
   const dragStartY = useRef<number | null>(null);
 
-  // Locked for the whole mounted lifetime (including the exit animation), not
-  // just while `open` — see Dialog.tsx's identical comment for why.
-  useEffect(() => {
-    if (!mounted) return;
-    lockBodyScroll();
-    return unlockBodyScroll;
-  }, [mounted]);
-
-  useEffect(() => {
-    if (!open) 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();
-  }, [open]);
-
-  // Keyboard handling: Escape closes, Tab cycles within the panel (focus trap).
-  // Attached at document level so no keyboard listener is needed on the dialog
-  // div itself (which would trigger jsx-a11y/no-noninteractive-element-interactions).
-  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, open);
+  useOverlayKeyboardTrap(panelRef, open, onClose);
 
   // Swipe-down-to-dismiss, initiated only from the grab handle (see the
   // component doc comment for why not the whole panel). Drags the panel
@@ -207,6 +168,7 @@ export function Drawer({
           onPointerUp={(e) => releaseDrag(e, true)}
           onPointerCancel={(e) => releaseDrag(e, false)}
         />
+        {title && <OverlayHeader title={title} onClose={onClose} />}
         {children}
       </div>
     </div>

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

@@ -110,6 +110,28 @@ describe('Drawer', () => {
     expect(screen.getByRole('dialog').className).not.toMatch(/panelHalf/);
   });
 
+  it('does not render OverlayHeader when title is omitted (hidden by default)', () => {
+    render(
+      <Drawer open onClose={() => {}} aria-label="Nav">
+        <button type="button">Own action</button>
+      </Drawer>,
+    );
+    // Only the content's own button — no OverlayHeader close button.
+    expect(screen.getAllByRole('button')).toHaveLength(1);
+  });
+
+  it('renders OverlayHeader (title + close) when title is provided', () => {
+    const onClose = vi.fn();
+    render(
+      <Drawer open onClose={onClose} aria-label="Nav" title="Apps">
+        Body
+      </Drawer>,
+    );
+    expect(screen.getByText('Apps')).toBeTruthy();
+    fireEvent.click(screen.getByRole('button', { name: 'Close' }));
+    expect(onClose).toHaveBeenCalledOnce();
+  });
+
   describe('swipe-down-to-dismiss (grab handle)', () => {
     // The handle is the panel's first child, aria-hidden and unlabeled —
     // same "select via DOM position" approach the scrim-click test above

package/src/components/HoverCard/HoverCard.module.css

@@ -0,0 +1,3 @@
+.root {
+  display: inline-flex;
+}

package/src/components/HoverCard/HoverCard.stories.tsx

@@ -0,0 +1,66 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { HoverCard } from './HoverCard';
+import { Avatar } from '../Avatar/Avatar';
+
+const meta = {
+  title: 'Components/HoverCard',
+  component: HoverCard,
+  parameters: {
+    layout: 'padded',
+    docs: {
+      description: {
+        component:
+          'Hover-triggered popover on desktop, tap-to-toggle on touch. Built on Popover for positioning/collision detection — this only adds hover-intent timing and the touch fallback. Opens on keyboard focus too.',
+      },
+    },
+  },
+  args: { trigger: <span />, children: null, 'aria-label': 'Preview' },
+} satisfies Meta<typeof HoverCard>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+// ---------------------------------------------------------------------------
+
+export const Default: Story = {
+  render: () => (
+    <HoverCard
+      aria-label="User preview"
+      trigger={
+        <button
+          type="button"
+          style={{ background: 'none', border: 'none', padding: 0, cursor: 'pointer' }}
+        >
+          <Avatar name="Jane Smith" size="sm" />
+        </button>
+      }
+    >
+      <div style={{ padding: 'var(--sv-space-3)', fontSize: 14 }}>
+        <div style={{ fontWeight: 600 }}>Jane Smith</div>
+        <div style={{ color: 'var(--sv-color-text-muted)' }}>jane@example.com</div>
+      </div>
+    </HoverCard>
+  ),
+};
+
+export const WithLink: Story = {
+  render: () => (
+    <p style={{ fontSize: 14 }}>
+      Assigned to{' '}
+      <HoverCard
+        aria-label="Assignee preview"
+        trigger={
+          <a href="/console/users/jane-smith" style={{ color: 'var(--sv-color-text-primary)' }}>
+            Jane Smith
+          </a>
+        }
+      >
+        <div style={{ padding: 'var(--sv-space-3)', fontSize: 14 }}>
+          <div style={{ fontWeight: 600 }}>Jane Smith</div>
+          <div style={{ color: 'var(--sv-color-text-muted)' }}>12 tasks completed this month</div>
+        </div>
+      </HoverCard>
+      .
+    </p>
+  ),
+};