@sovereignfs/ui 0.21.0

package/src/components/Dialog/Dialog.tsx

@@ -0,0 +1,137 @@
+'use client';
+
+import { type ReactNode, useEffect, useRef } from 'react';
+import styles from './Dialog.module.css';
+
+export type DialogSize = 'sm' | 'md' | 'lg' | 'full';
+
+export interface DialogProps {
+  /** Whether the dialog is shown. When false, nothing renders. */
+  open: boolean;
+  /** Called on Esc, scrim click, or the close button. */
+  onClose: () => void;
+  /** Panel size on desktop. Mobile always renders as a full-screen sheet. */
+  size?: DialogSize;
+  /** Accessible name for the dialog (sets `aria-label` on the panel). */
+  'aria-label'?: string;
+  /** On mobile: shown in the top bar alongside the close button so the title
+   *  and dismiss affordance occupy the same row instead of stacking. */
+  title?: string;
+  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
+ * what `onClose` does (the runtime's `@modal` slot wires it to `router.back()`).
+ *
+ * Behaviour: Esc and scrim-click dismiss; focus moves into the panel on open and
+ * is restored to the previously-focused element on close; Tab is trapped within
+ * the panel. Styling references `--sv-*` tokens only; on mobile the panel becomes
+ * a full-screen sheet regardless of `size`.
+ */
+export function Dialog({
+  open,
+  onClose,
+  size = 'lg',
+  'aria-label': ariaLabel,
+  title,
+  children,
+}: DialogProps) {
+  const panelRef = useRef<HTMLDivElement>(null);
+  const previouslyFocused = useRef<HTMLElement | null>(null);
+
+  // 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]);
+
+  if (!open) return null;
+
+  return (
+    // role="presentation" removes the scrim from the AT (it is purely visual).
+    // e.target check lets clicks inside the panel bubble without triggering dismiss.
+    <div
+      className={styles.scrim}
+      role="presentation"
+      onClick={(e) => {
+        if (e.target === e.currentTarget) onClose();
+      }}
+      onKeyDown={(e) => {
+        if (e.key === 'Escape') onClose();
+      }}
+    >
+      <div
+        ref={panelRef}
+        role="dialog"
+        aria-modal="true"
+        aria-label={ariaLabel ?? title}
+        tabIndex={-1}
+        className={[styles.panel, styles[size]].join(' ')}
+      >
+        {/* Mobile: title + close button in one row (hidden on desktop via CSS). */}
+        <div className={styles.mobileBar}>
+          {title && <span className={styles.mobileBarTitle}>{title}</span>}
+          <button
+            type="button"
+            className={styles.mobileBarClose}
+            aria-label="Close"
+            onClick={onClose}
+          >
+            ×
+          </button>
+        </div>
+        {/* Desktop: absolute close button (hidden on mobile via CSS). */}
+        <button type="button" className={styles.close} aria-label="Close" onClick={onClose}>
+          ×
+        </button>
+        {/* The panel is a fixed-size box; only this region scrolls, so the
+            panel never resizes with its content and the close button stays
+            pinned. */}
+        <div className={styles.content}>{children}</div>
+      </div>
+    </div>
+  );
+}

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

@@ -0,0 +1,73 @@
+// @vitest-environment jsdom
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { cleanup, fireEvent, render, screen } from '@testing-library/react';
+import { Dialog } from '../Dialog';
+
+describe('Dialog', () => {
+  afterEach(cleanup);
+
+  it('renders nothing when closed', () => {
+    render(
+      <Dialog open={false} onClose={() => {}}>
+        Body
+      </Dialog>,
+    );
+    expect(screen.queryByRole('dialog')).toBeNull();
+  });
+
+  it('renders the panel with its accessible name when open', () => {
+    render(
+      <Dialog open onClose={() => {}} aria-label="Settings">
+        Body
+      </Dialog>,
+    );
+    const dialog = screen.getByRole('dialog', { name: 'Settings' });
+    expect(dialog.getAttribute('aria-modal')).toBe('true');
+  });
+
+  it('calls onClose on Escape', () => {
+    const onClose = vi.fn();
+    render(
+      <Dialog open onClose={onClose}>
+        Body
+      </Dialog>,
+    );
+    // Keyboard handler is registered on document (not the dialog element) so
+    // screen readers and keyboard users can dismiss from anywhere in the page.
+    fireEvent.keyDown(document, { key: 'Escape' });
+    expect(onClose).toHaveBeenCalledOnce();
+  });
+
+  it('calls onClose on scrim click but not on panel click', () => {
+    const onClose = vi.fn();
+    render(
+      <Dialog open onClose={onClose} aria-label="Panel">
+        Body
+      </Dialog>,
+    );
+    fireEvent.click(screen.getByRole('dialog')); // panel — should not close
+    expect(onClose).not.toHaveBeenCalled();
+    const closeButtons = screen.getAllByRole('button', { name: 'Close' });
+    expect(closeButtons.length).toBeGreaterThan(0);
+    fireEvent.click(closeButtons[0] as HTMLElement);
+    expect(onClose).toHaveBeenCalledOnce();
+  });
+
+  it('applies the size class', () => {
+    render(
+      <Dialog open onClose={() => {}} size="full" aria-label="Big">
+        Body
+      </Dialog>,
+    );
+    expect(screen.getByRole('dialog').className).toContain('full');
+  });
+
+  it('supports the sm size', () => {
+    render(
+      <Dialog open onClose={() => {}} size="sm" aria-label="Small">
+        Body
+      </Dialog>,
+    );
+    expect(screen.getByRole('dialog').className).toContain('sm');
+  });
+});

package/src/components/Drawer/Drawer.module.css

@@ -0,0 +1,30 @@
+/* Drawer — bottom-sheet surface (RFC 0013). Shares scrim/shadow tokens with
+ * Dialog but slides up from the bottom instead of centering. The panel has no
+ * fixed height — it sizes to content, capped at 80dvh so some page context
+ * remains visible above. Safe-area-aware: bottom padding clears the home
+ * indicator in standalone/fullscreen mode. */
+
+.scrim {
+  position: fixed;
+  inset: 0;
+  /* When the shell declares --sv-shell-footer-height (mobile nav bar), stop the
+     scrim above the footer so the panel never hides behind it. */
+  bottom: var(--sv-shell-footer-height, 0);
+  z-index: 100;
+  display: flex;
+  align-items: flex-end;
+  background: var(--sv-color-scrim);
+}
+
+.panel {
+  width: 100%;
+  max-height: 80dvh;
+  overflow-y: auto;
+  background: var(--sv-color-surface-raised);
+  border-top: 1px solid var(--sv-color-border);
+  border-radius: var(--sv-radius-3xl) var(--sv-radius-3xl) 0 0;
+  box-shadow: var(--sv-shadow-overlay);
+  /* Pull content above the home indicator / bottom bar in standalone mode. */
+  padding-bottom: env(safe-area-inset-bottom);
+  outline: none;
+}

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

@@ -0,0 +1,88 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { expect, userEvent, within } from 'storybook/test';
+import { useState } from 'react';
+import { Button } from '../Button/Button';
+import { Icon } from '../Icon/Icon';
+import { Drawer } from './Drawer';
+
+function DrawerDemo({ label = 'Navigation' }: { label?: string }) {
+  const [open, setOpen] = useState(false);
+  return (
+    <>
+      <Button onClick={() => setOpen(true)}>Open drawer</Button>
+      <Drawer open={open} onClose={() => setOpen(false)} aria-label={label}>
+        <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>
+    </>
+  );
+}
+
+const meta = {
+  title: 'Components/Drawer',
+  component: Drawer,
+  parameters: {
+    layout: 'centered',
+    docs: {
+      description: {
+        component:
+          'Dismissable bottom-sheet panel. Used by the mobile shell for plugin navigation. Supports Esc, scrim-click, focus trap. Respects `env(safe-area-inset-bottom)`. Use the viewport addon at 375px to see the intended mobile context.',
+      },
+    },
+    viewport: { defaultViewport: 'mobile' },
+  },
+} satisfies Meta<typeof Drawer>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+// ---------------------------------------------------------------------------
+
+export const Default: Story = {
+  args: { open: false, onClose: () => {}, children: null },
+  render: (_args) => <DrawerDemo />,
+};
+
+export const Closed: Story = {
+  args: { open: false, onClose: () => {}, children: null },
+  render: (_args) => (
+    <Drawer open={false} onClose={() => {}} aria-label="Closed drawer">
+      <p>Never seen</p>
+    </Drawer>
+  ),
+};
+
+/** Play function opens the drawer and asserts its list items are visible. */
+export const OpenViaInteraction: Story = {
+  args: { open: false, onClose: () => {}, children: null },
+  render: (_args) => <DrawerDemo label="Navigation menu" />,
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    await userEvent.click(canvas.getByRole('button', { name: /open drawer/i }));
+    const drawer = canvas.getByRole('navigation');
+    await expect(drawer).toBeVisible();
+  },
+};

package/src/components/Drawer/Drawer.tsx

@@ -0,0 +1,103 @@
+'use client';
+
+import { type ReactNode, useEffect, useRef } from 'react';
+import styles from './Drawer.module.css';
+
+export interface DrawerProps {
+  /** Whether the drawer is shown. When false, nothing renders. */
+  open: boolean;
+  /** Called on Esc or scrim click. */
+  onClose: () => void;
+  /** Accessible name for the drawer panel (sets `aria-label`). */
+  'aria-label'?: string;
+  children: ReactNode;
+}
+
+const FOCUSABLE =
+  'a[href], button:not([disabled]), textarea:not([disabled]), input:not([disabled]), select:not([disabled]), [tabindex]:not([tabindex="-1"])';
+
+/**
+ * Drawer — a dismissable bottom-sheet panel. Used by the mobile shell for
+ * plugin navigation; also available to plugins for any bottom-up surface.
+ *
+ * Behaviour: Esc and scrim-click dismiss; focus moves to the first focusable
+ * element on open and is restored on close; Tab is trapped within the panel.
+ * The panel respects `env(safe-area-inset-bottom)` so it clears the home
+ * indicator in standalone/fullscreen mode. Shares dismissal conventions and
+ * tokens (`--sv-color-scrim`, `--sv-shadow-overlay`) with `Dialog`.
+ */
+export function Drawer({ open, onClose, 'aria-label': ariaLabel, children }: DrawerProps) {
+  const panelRef = useRef<HTMLDivElement>(null);
+  const previouslyFocused = useRef<HTMLElement | null>(null);
+
+  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]);
+
+  if (!open) return null;
+
+  return (
+    // role="presentation" removes the scrim from the AT (it is purely visual).
+    // e.target check lets clicks inside the panel bubble without triggering dismiss.
+    <div
+      className={styles.scrim}
+      role="presentation"
+      onClick={(e) => {
+        if (e.target === e.currentTarget) onClose();
+      }}
+      onKeyDown={(e) => {
+        if (e.key === 'Escape') onClose();
+      }}
+    >
+      <div
+        ref={panelRef}
+        role="dialog"
+        aria-modal="true"
+        aria-label={ariaLabel}
+        tabIndex={-1}
+        className={styles.panel}
+      >
+        {children}
+      </div>
+    </div>
+  );
+}

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

@@ -0,0 +1,56 @@
+// @vitest-environment jsdom
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { cleanup, fireEvent, render, screen } from '@testing-library/react';
+import { Drawer } from '../Drawer';
+
+describe('Drawer', () => {
+  afterEach(cleanup);
+
+  it('renders nothing when closed', () => {
+    render(
+      <Drawer open={false} onClose={() => {}}>
+        Body
+      </Drawer>,
+    );
+    expect(screen.queryByRole('dialog')).toBeNull();
+  });
+
+  it('renders the panel with its accessible name when open', () => {
+    render(
+      <Drawer open onClose={() => {}} aria-label="Navigation">
+        Body
+      </Drawer>,
+    );
+    const panel = screen.getByRole('dialog', { name: 'Navigation' });
+    expect(panel.getAttribute('aria-modal')).toBe('true');
+  });
+
+  it('calls onClose on Escape', () => {
+    const onClose = vi.fn();
+    render(
+      <Drawer open onClose={onClose}>
+        Body
+      </Drawer>,
+    );
+    // Keyboard handler is registered on document (not the drawer element) so
+    // screen readers and keyboard users can dismiss from anywhere in the page.
+    fireEvent.keyDown(document, { key: 'Escape' });
+    expect(onClose).toHaveBeenCalledOnce();
+  });
+
+  it('calls onClose on scrim click but not on panel click', () => {
+    const onClose = vi.fn();
+    const { container } = render(
+      <Drawer open onClose={onClose} aria-label="Nav">
+        <button>Action</button>
+      </Drawer>,
+    );
+    // The scrim is the outermost div; the panel is a child.
+    fireEvent.click(screen.getByRole('dialog')); // panel — should not close
+    expect(onClose).not.toHaveBeenCalled();
+    // Click the scrim background (the container's first child).
+    const scrim = container.firstElementChild as HTMLElement;
+    fireEvent.click(scrim);
+    expect(onClose).toHaveBeenCalledOnce();
+  });
+});

package/src/components/EmptyState/EmptyState.module.css

@@ -0,0 +1,27 @@
+.root {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  justify-content: center;
+  gap: var(--sv-space-3);
+  padding: var(--sv-space-12) var(--sv-space-6);
+  text-align: center;
+}
+
+.icon {
+  color: var(--sv-color-text-subtle);
+}
+
+.heading {
+  margin: 0;
+  font-size: var(--sv-font-size-md);
+  font-weight: var(--sv-font-weight-semibold);
+  color: var(--sv-color-text-primary);
+}
+
+.description {
+  margin: 0;
+  font-size: var(--sv-font-size-sm);
+  color: var(--sv-color-text-muted);
+  max-width: 36ch;
+}

package/src/components/EmptyState/EmptyState.tsx

@@ -0,0 +1,27 @@
+import type { ReactNode } from 'react';
+import { Icon } from '../Icon/Icon';
+import type { IconName } from '../Icon/Icon';
+import styles from './EmptyState.module.css';
+
+export interface EmptyStateProps {
+  icon?: IconName;
+  heading: string;
+  description?: string;
+  action?: ReactNode;
+  className?: string;
+}
+
+export function EmptyState({ icon, heading, description, action, className }: EmptyStateProps) {
+  return (
+    <div className={[styles.root, className].filter(Boolean).join(' ')}>
+      {icon && (
+        <span className={styles.icon}>
+          <Icon name={icon} size="lg" aria-hidden={true} />
+        </span>
+      )}
+      <h2 className={styles.heading}>{heading}</h2>
+      {description && <p className={styles.description}>{description}</p>}
+      {action}
+    </div>
+  );
+}

package/src/components/FormField/FormField.module.css

@@ -0,0 +1,28 @@
+.field {
+  display: flex;
+  flex-direction: column;
+  gap: var(--sv-space-1);
+}
+
+.label {
+  font-size: var(--sv-font-size-sm);
+  font-weight: var(--sv-font-weight-medium);
+  color: var(--sv-color-text-primary);
+}
+
+.required {
+  color: var(--sv-color-error-text);
+  margin-left: var(--sv-space-1);
+}
+
+.hint {
+  margin: 0;
+  font-size: var(--sv-font-size-xs);
+  color: var(--sv-color-text-muted);
+}
+
+.error {
+  margin: 0;
+  font-size: var(--sv-font-size-xs);
+  color: var(--sv-color-error-text);
+}

package/src/components/FormField/FormField.tsx

@@ -0,0 +1,53 @@
+import type { ReactNode } from 'react';
+import { useId } from 'react';
+import styles from './FormField.module.css';
+
+export interface FormFieldProps {
+  label: string;
+  hint?: string;
+  error?: string;
+  htmlFor?: string;
+  required?: boolean;
+  children: ReactNode;
+  className?: string;
+}
+
+export function FormField({
+  label,
+  hint,
+  error,
+  htmlFor,
+  required = false,
+  children,
+  className,
+}: FormFieldProps) {
+  const hintId = useId();
+  const errorId = useId();
+  const describedBy = [hint && hintId, error && errorId].filter(Boolean).join(' ') || undefined;
+
+  return (
+    <div className={[styles.field, className].filter(Boolean).join(' ')}>
+      <label className={styles.label} htmlFor={htmlFor}>
+        {label}
+        {required && (
+          <span className={styles.required} aria-hidden="true">
+            *
+          </span>
+        )}
+      </label>
+      {/* Clone the child to inject aria-describedby — or just render children
+          and let the consumer wire htmlFor/id themselves */}
+      <div aria-describedby={describedBy}>{children}</div>
+      {hint && !error && (
+        <p id={hintId} className={styles.hint}>
+          {hint}
+        </p>
+      )}
+      {error && (
+        <p id={errorId} className={styles.error} role="alert">
+          {error}
+        </p>
+      )}
+    </div>
+  );
+}

package/src/components/Icon/Icon.module.css

@@ -0,0 +1,22 @@
+.root {
+  display: inline-block;
+  flex-shrink: 0;
+  /* Prevent the inline-block from adding line-height whitespace below the SVG. */
+  line-height: 0;
+  /* Color follows the surrounding text via currentColor — no token needed. */
+}
+
+.sm {
+  width: var(--sv-icon-size-sm);
+  height: var(--sv-icon-size-sm);
+}
+
+.md {
+  width: var(--sv-icon-size-md);
+  height: var(--sv-icon-size-md);
+}
+
+.lg {
+  width: var(--sv-icon-size-lg);
+  height: var(--sv-icon-size-lg);
+}