@sovereignfs/ui 0.41.0 → 0.54.0

package/dist/tokens/primitives.css

@@ -77,20 +77,44 @@
   --sv-font-weight-semibold: 600;
   --sv-font-weight-bold: 700;
 
+  /* In-app text-size control (task 10.2), discharging the pinch-zoom-disabled
+     accessibility debt (runtime/app/layout.tsx sets userScalable: false).
+     Every --sv-font-size-* above is rem-based, so scaling the root font size
+     scales the whole type system with no per-component changes. Driven by
+     [data-text-size] on <html>, set pre-paint by runtime/src/theme-script.ts
+     from the `sv-text-size` cookie — same mechanism as [data-theme]. Like
+     --sv-radius-scale, this is a theme-stable scale token with no separate
+     semantic tier. */
+  --sv-text-size-scale: 1;
+
   /* Icon sizes — scale tokens used directly by the Icon component */
   --sv-icon-size-xs: 0.75rem; /* 12px — inline metadata (e.g. a due-date badge) */
   --sv-icon-size-sm: 1rem; /* 16px — inline with body text */
   --sv-icon-size-md: 1.25rem; /* 20px — standard affordance */
   --sv-icon-size-lg: 1.5rem; /* 24px — prominent / standalone */
 
-  /* Border radii (v3.1 spec values) */
-  --sv-radius-sm: 0.375rem; /* 6px — badge, tag */
-  --sv-radius-md: 0.5rem; /* 8px — button, input */
-  --sv-radius-lg: 0.6875rem; /* 11px — sidebar icon, card */
-  --sv-radius-xl: 0.75rem; /* 12px — card, panel */
-  --sv-radius-2xl: 0.875rem; /* 14px — popover */
-  --sv-radius-3xl: 1.25rem; /* 20px — bottom sheet (Drawer top corners) */
-  --sv-radius-full: 9999px; /* pill / avatar */
+  /* Border radii (v3.1 spec values). --sv-radius-scale is the one
+     instance-controllable exception to "scale tokens are theme-stable"
+     (RFC 0077) — an operator's corner-radius preset (None/XS/S/M/L)
+     overrides it at :root via the InstanceProvider style injection
+     (runtime/src/instance-provider.tsx), same pipeline as --sv-color-accent.
+     Every corner token below is proportional to it, so a plugin author never
+     references --sv-radius-scale directly — they keep using --sv-radius-sm
+     etc. exactly as before. --sv-radius-full is deliberately NOT derived
+     from the scale: it's a shape token (circle/pill), not a corner-rounding
+     one, and stays fixed regardless of the instance preset. */
+  --sv-radius-scale: 1;
+  --sv-radius-sm: calc(var(--sv-radius-scale) * 0.375rem); /* 6px @ scale 1 — badge, tag */
+  --sv-radius-md: calc(var(--sv-radius-scale) * 0.5rem); /* 8px @ scale 1 — button, input */
+  --sv-radius-lg: calc(
+    var(--sv-radius-scale) * 0.6875rem
+  ); /* 11px @ scale 1 — sidebar icon, card */
+  --sv-radius-xl: calc(var(--sv-radius-scale) * 0.75rem); /* 12px @ scale 1 — card, panel */
+  --sv-radius-2xl: calc(var(--sv-radius-scale) * 0.875rem); /* 14px @ scale 1 — popover */
+  --sv-radius-3xl: calc(
+    var(--sv-radius-scale) * 1.25rem
+  ); /* 20px @ scale 1 — bottom sheet (Drawer top corners) */
+  --sv-radius-full: 9999px; /* pill / avatar — unaffected by --sv-radius-scale */
 
   /* Touch targets — minimum hit-area dimension for interactive controls.
      44px follows the WCAG 2.5.5 / Apple HIG / Material guideline for reliable
@@ -116,3 +140,18 @@
     1
   ); /* slight overshoot — playful emphasis, use sparingly */
 }
+
+/* Root font size scales with --sv-text-size-scale — see the token comment
+   above. calc(...  * 100%) keeps the browser/OS text-zoom default intact at
+   scale 1 rather than hardcoding a px value. */
+html {
+  font-size: calc(var(--sv-text-size-scale) * 100%);
+}
+
+:root[data-text-size='large'] {
+  --sv-text-size-scale: 1.125; /* +12.5% */
+}
+
+:root[data-text-size='larger'] {
+  --sv-text-size-scale: 1.25; /* +25% */
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sovereignfs/ui",
-  "version": "0.41.0",
+  "version": "0.54.0",
   "type": "module",
   "description": "Sovereign Design System — design tokens and React components.",
   "keywords": [
@@ -36,16 +36,17 @@
     "react-dom": "^19.0.0"
   },
   "devDependencies": {
-    "@storybook/addon-a11y": "^10.4.6",
-    "@storybook/addon-themes": "^10.4.6",
-    "@storybook/react-vite": "^10.4.6",
+    "@playwright/test": "^1.62.1",
+    "@storybook/addon-a11y": "^10.5.5",
+    "@storybook/addon-themes": "^10.5.5",
+    "@storybook/react-vite": "^10.5.5",
     "@testing-library/dom": "^10.4.1",
     "@testing-library/react": "^16.3.2",
-    "@types/react": "^19.0.0",
-    "@types/react-dom": "^19.0.0",
-    "react": "^19.0.0",
-    "react-dom": "^19.0.0",
-    "storybook": "^10.4.6",
+    "@types/react": "^19.2.18",
+    "@types/react-dom": "^19.2.4",
+    "react": "^19.2.8",
+    "react-dom": "^19.2.8",
+    "storybook": "^10.5.5",
     "tsup": "^8.5.1",
     "typescript": "^5.9.3",
     "@sovereignfs/tsconfig": "0.0.0"
@@ -53,7 +54,10 @@
   "scripts": {
     "build": "tsup",
     "storybook": "storybook dev -p 6006",
+    "storybook:visual": "storybook dev -p 6100 --ci --quiet",
     "build-storybook": "storybook build --output-dir storybook-static",
+    "test:visual": "playwright test --config=playwright.visual.config.ts",
+    "test:visual:update": "playwright test --config=playwright.visual.config.ts --update-snapshots",
     "typecheck": "tsc --noEmit"
   },
   "types": "./dist/index.d.ts"

package/src/components/Accordion/Accordion.module.css

@@ -0,0 +1,3 @@
+.root {
+  border-top: 1px solid var(--sv-color-border);
+}

package/src/components/Accordion/Accordion.stories.tsx

@@ -0,0 +1,110 @@
+import { useState } from 'react';
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { expect, userEvent, within } from 'storybook/test';
+import { Accordion } from './Accordion';
+
+const meta = {
+  title: 'Components/Accordion',
+  component: Accordion,
+  parameters: {
+    layout: 'padded',
+    docs: {
+      description: {
+        component:
+          'One or more Collapsible sections. type="single" closes other sections when one opens; type="multiple" allows any number open at once.',
+      },
+    },
+  },
+  args: { items: [], type: 'single', openIds: [], onOpenIdsChange: () => {} },
+} satisfies Meta<typeof Accordion>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+// ---------------------------------------------------------------------------
+
+const FAQ_ITEMS = [
+  {
+    id: 'plugins',
+    trigger: 'What plugins ship by default?',
+    content: 'Only the platform plugins (Console, Launcher, Account) plus Sovereign Tasks.',
+  },
+  {
+    id: 'hosting',
+    trigger: 'Can I self-host this?',
+    content: 'Yes — Sovereign is designed to be self-hosted via Docker Compose.',
+  },
+  {
+    id: 'pricing',
+    trigger: 'Is it free?',
+    content: 'The platform is open source. Individual plugins may have their own pricing.',
+  },
+];
+
+export const Default: Story = {
+  render: () => {
+    const [openIds, setOpenIds] = useState<string[]>(['plugins']);
+    return (
+      <Accordion items={FAQ_ITEMS} type="single" openIds={openIds} onOpenIdsChange={setOpenIds} />
+    );
+  },
+};
+
+export const MultipleOpen: Story = {
+  render: () => {
+    const [openIds, setOpenIds] = useState<string[]>(['plugins', 'hosting']);
+    return (
+      <Accordion items={FAQ_ITEMS} type="multiple" openIds={openIds} onOpenIdsChange={setOpenIds} />
+    );
+  },
+};
+
+export const LongContent: Story = {
+  render: () => {
+    const [openIds, setOpenIds] = useState<string[]>(['changelog']);
+    return (
+      <Accordion
+        items={[
+          {
+            id: 'changelog',
+            trigger: 'Full changelog',
+            content: (
+              <ul style={{ margin: 0, paddingLeft: 20 }}>
+                <li>Added component sizing alignment across the design system</li>
+                <li>Added RadioGroup, Slider, Progress, Table, Alert primitives</li>
+                <li>Added Breadcrumb, Pagination, and Kbd primitives</li>
+                <li>Added Accordion and Collapsible primitives</li>
+              </ul>
+            ),
+          },
+        ]}
+        type="single"
+        openIds={openIds}
+        onOpenIdsChange={setOpenIds}
+      />
+    );
+  },
+};
+
+export const KeyboardInteraction: Story = {
+  render: () => {
+    const [openIds, setOpenIds] = useState<string[]>([]);
+    return (
+      <Accordion items={FAQ_ITEMS} type="single" openIds={openIds} onOpenIdsChange={setOpenIds} />
+    );
+  },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    const trigger = canvas.getByRole('button', { name: 'What plugins ship by default?' });
+
+    await expect(trigger).toHaveAttribute('aria-expanded', 'false');
+
+    trigger.focus();
+    await userEvent.keyboard('{Enter}');
+    await expect(trigger).toHaveAttribute('aria-expanded', 'true');
+    await expect(canvas.getByText(/Only the platform plugins/)).toBeVisible();
+
+    await userEvent.keyboard(' ');
+    await expect(trigger).toHaveAttribute('aria-expanded', 'false');
+  },
+};

package/src/components/Accordion/Accordion.tsx

@@ -0,0 +1,53 @@
+import type { ReactNode } from 'react';
+import { Collapsible } from '../Collapsible/Collapsible';
+import styles from './Accordion.module.css';
+
+export interface AccordionItem {
+  id: string;
+  trigger: ReactNode;
+  content: ReactNode;
+}
+
+export interface AccordionProps {
+  items: AccordionItem[];
+  /** `single` closes other sections when one opens. `multiple` allows any
+   * number of sections open at once. */
+  type: 'single' | 'multiple';
+  openIds: string[];
+  onOpenIdsChange: (openIds: string[]) => void;
+  className?: string;
+}
+
+/**
+ * Accordion — one or more `Collapsible` sections.
+ *
+ * Keyboard support (Enter/Space toggles the focused trigger) comes from
+ * `Collapsible`'s real `<button>` — no arrow-key roving-tabindex handling
+ * here, since accordion sections aren't a roving-tabindex widget per the
+ * WAI-ARIA accordion pattern (each trigger is independently Tab-focusable).
+ */
+export function Accordion({ items, type, openIds, onOpenIdsChange, className }: AccordionProps) {
+  function handleOpenChange(id: string, open: boolean) {
+    if (type === 'single') {
+      onOpenIdsChange(open ? [id] : []);
+      return;
+    }
+    onOpenIdsChange(open ? [...openIds, id] : openIds.filter((openId) => openId !== id));
+  }
+
+  return (
+    <div className={[styles.root, className].filter(Boolean).join(' ')}>
+      {items.map((item) => (
+        <Collapsible
+          key={item.id}
+          id={item.id}
+          trigger={item.trigger}
+          open={openIds.includes(item.id)}
+          onOpenChange={(open) => handleOpenChange(item.id, open)}
+        >
+          {item.content}
+        </Collapsible>
+      ))}
+    </div>
+  );
+}

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

@@ -0,0 +1,61 @@
+// @vitest-environment jsdom
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { cleanup, render, screen, fireEvent } from '@testing-library/react';
+import { Accordion } from '../Accordion';
+
+afterEach(cleanup);
+
+const items = [
+  { id: 'a', trigger: 'Section A', content: 'Content A' },
+  { id: 'b', trigger: 'Section B', content: 'Content B' },
+];
+
+describe('Accordion', () => {
+  it('renders a trigger button per item', () => {
+    render(<Accordion items={items} type="single" openIds={[]} onOpenIdsChange={() => {}} />);
+    expect(screen.getByRole('button', { name: 'Section A' })).toBeDefined();
+    expect(screen.getByRole('button', { name: 'Section B' })).toBeDefined();
+  });
+
+  it('type="single": opening one section replaces the open set entirely', () => {
+    const onOpenIdsChange = vi.fn();
+    render(
+      <Accordion items={items} type="single" openIds={['a']} onOpenIdsChange={onOpenIdsChange} />,
+    );
+    fireEvent.click(screen.getByRole('button', { name: 'Section B' }));
+    expect(onOpenIdsChange).toHaveBeenCalledWith(['b']);
+  });
+
+  it('type="multiple": opening a section adds to the open set', () => {
+    const onOpenIdsChange = vi.fn();
+    render(
+      <Accordion items={items} type="multiple" openIds={['a']} onOpenIdsChange={onOpenIdsChange} />,
+    );
+    fireEvent.click(screen.getByRole('button', { name: 'Section B' }));
+    expect(onOpenIdsChange).toHaveBeenCalledWith(['a', 'b']);
+  });
+
+  it('type="multiple": closing an open section removes only that id', () => {
+    const onOpenIdsChange = vi.fn();
+    render(
+      <Accordion
+        items={items}
+        type="multiple"
+        openIds={['a', 'b']}
+        onOpenIdsChange={onOpenIdsChange}
+      />,
+    );
+    fireEvent.click(screen.getByRole('button', { name: 'Section A' }));
+    expect(onOpenIdsChange).toHaveBeenCalledWith(['b']);
+  });
+
+  it('reflects openIds via aria-expanded on each trigger', () => {
+    render(<Accordion items={items} type="single" openIds={['a']} onOpenIdsChange={() => {}} />);
+    expect(screen.getByRole('button', { name: 'Section A' }).getAttribute('aria-expanded')).toBe(
+      'true',
+    );
+    expect(screen.getByRole('button', { name: 'Section B' }).getAttribute('aria-expanded')).toBe(
+      'false',
+    );
+  });
+});

package/src/components/Alert/Alert.module.css

@@ -0,0 +1,62 @@
+.alert {
+  display: flex;
+  align-items: flex-start;
+  gap: var(--sv-space-2);
+  padding: var(--sv-space-3) var(--sv-space-4);
+  border: 1px solid transparent;
+  border-radius: var(--sv-radius-md);
+  font-size: var(--sv-font-size-sm);
+}
+
+.icon {
+  flex-shrink: 0;
+  /* Optically align to the first line of text rather than the box's
+     vertical center — matches how the heading/body cap-height sits. */
+  margin-top: 2px;
+}
+
+.content {
+  display: flex;
+  flex-direction: column;
+  gap: var(--sv-space-1);
+  min-width: 0;
+}
+
+.heading {
+  margin: 0;
+  font-weight: var(--sv-font-weight-semibold);
+}
+
+.body {
+  margin: 0;
+}
+
+.info {
+  background: var(--sv-color-info-surface);
+  border-color: var(--sv-color-info-border);
+  color: var(--sv-color-info-text);
+}
+
+.success {
+  background: var(--sv-color-success-surface);
+  border-color: var(--sv-color-success-border);
+  color: var(--sv-color-success-text);
+}
+
+.warning {
+  background: var(--sv-color-warning-surface);
+  border-color: var(--sv-color-warning-border);
+  color: var(--sv-color-warning-text);
+}
+
+.error {
+  background: var(--sv-color-error-surface);
+  border-color: var(--sv-color-error-border);
+  color: var(--sv-color-error-text);
+}
+
+.neutral {
+  background: var(--sv-color-surface-sunken);
+  border-color: var(--sv-color-border);
+  color: var(--sv-color-text-primary);
+}

package/src/components/Alert/Alert.stories.tsx

@@ -0,0 +1,96 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { Alert } from './Alert';
+
+const meta = {
+  title: 'Components/Alert',
+  component: Alert,
+  parameters: {
+    layout: 'padded',
+    docs: {
+      description: {
+        component:
+          'Inline, non-dismissible banner. Distinct from Toast (transient) and SystemBanner (instance-wide) — for form-level errors or explaining an empty/blocked state. A leading icon defaults per variant (none for neutral) — pass `icon` to override it or `icon={false}` to suppress it.',
+      },
+    },
+  },
+  argTypes: {
+    variant: { control: 'select', options: ['info', 'success', 'warning', 'error', 'neutral'] },
+  },
+  args: {
+    variant: 'info',
+    children: 'This is an informational message.',
+  },
+} satisfies Meta<typeof Alert>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+// ---------------------------------------------------------------------------
+
+export const Info: Story = {
+  args: { variant: 'info' },
+};
+
+export const Success: Story = {
+  args: { variant: 'success', children: 'Your changes have been saved.' },
+};
+
+export const Warning: Story = {
+  args: { variant: 'warning', children: 'This action cannot be undone.' },
+};
+
+export const ErrorVariant: Story = {
+  name: 'Error',
+  args: { variant: 'error', children: 'Select a size to continue.' },
+};
+
+export const Neutral: Story = {
+  args: { variant: 'neutral', children: 'This project has no members yet.' },
+};
+
+export const WithHeading: Story = {
+  args: {
+    variant: 'error',
+    heading: 'Something went wrong',
+    children: 'We couldn’t save your changes. Check your connection and try again.',
+  },
+};
+
+export const WithoutHeading: Story = {
+  args: { variant: 'success', children: 'Invite sent.' },
+};
+
+/** Icon + heading + body — the pattern most alert examples use. */
+export const IconHeadingAndBody: Story = {
+  args: {
+    variant: 'success',
+    heading: 'Payment successful',
+    children:
+      'Your payment of $29.99 has been processed. A receipt has been sent to your email address.',
+  },
+};
+
+export const CustomIcon: Story = {
+  args: { variant: 'neutral', icon: 'bell', children: 'You have 3 unread notifications.' },
+};
+
+export const NoIcon: Story = {
+  args: { variant: 'success', icon: false, children: 'Your changes have been saved.' },
+};
+
+/** Every variant with its default icon, at a glance. */
+export const AllVariants: Story = {
+  render: () => (
+    <div style={{ display: 'flex', flexDirection: 'column', gap: 12, maxWidth: 480 }}>
+      <Alert variant="info" heading="New feature available">
+        We’ve added dark mode support. You can enable it in your account settings.
+      </Alert>
+      <Alert variant="success" heading="Payment successful">
+        Your payment of $29.99 has been processed. A receipt has been sent to your email address.
+      </Alert>
+      <Alert variant="warning">This action cannot be undone.</Alert>
+      <Alert variant="error">Select a size to continue.</Alert>
+      <Alert variant="neutral">This project has no members yet.</Alert>
+    </div>
+  ),
+};

package/src/components/Alert/Alert.tsx

@@ -0,0 +1,58 @@
+import type { ReactNode } from 'react';
+import { Icon, type IconName } from '../Icon/Icon';
+import styles from './Alert.module.css';
+
+export type AlertVariant = 'info' | 'success' | 'warning' | 'error' | 'neutral';
+
+/** Sensible default icon per variant. `neutral` has none — there's no
+ * universal "neutral" glyph, so it stays icon-less unless `icon` is set
+ * explicitly. */
+const DEFAULT_ICON: Record<AlertVariant, IconName | undefined> = {
+  info: 'info',
+  success: 'circle-check',
+  warning: 'alert-triangle',
+  error: 'circle-x',
+  neutral: undefined,
+};
+
+export interface AlertProps {
+  variant: AlertVariant;
+  heading?: string;
+  /** Leading icon next to the heading. Defaults to a per-variant icon (see
+   * `DEFAULT_ICON`) — pass an `IconName` to override it, or `false` to
+   * suppress the icon entirely. Purely decorative: the variant's colour and
+   * `heading`/`children` text already carry the meaning. */
+  icon?: IconName | false;
+  children: ReactNode;
+  id?: string;
+  className?: string;
+}
+
+/**
+ * Alert — inline, non-dismissible banner.
+ *
+ * Distinct from `Toast` (transient, auto-dismissing) and `SystemBanner`
+ * (instance-wide): Alert is for in-context messaging — form-level errors,
+ * or explaining an empty/blocked state.
+ *
+ * `role="alert"` for `error` (interrupts screen readers immediately, since
+ * an error demands attention); `role="status"` for the other variants
+ * (announced politely, without interrupting).
+ */
+export function Alert({ variant, heading, icon, children, id, className }: AlertProps) {
+  const resolvedIcon = icon === undefined ? DEFAULT_ICON[variant] : icon || undefined;
+
+  return (
+    <div
+      id={id}
+      role={variant === 'error' ? 'alert' : 'status'}
+      className={[styles.alert, styles[variant], className].filter(Boolean).join(' ')}
+    >
+      {resolvedIcon && <Icon name={resolvedIcon} size="sm" className={styles.icon} aria-hidden />}
+      <div className={styles.content}>
+        {heading && <p className={styles.heading}>{heading}</p>}
+        <div className={styles.body}>{children}</div>
+      </div>
+    </div>
+  );
+}

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

@@ -0,0 +1,75 @@
+// @vitest-environment jsdom
+import { afterEach, describe, expect, it } from 'vitest';
+import { cleanup, render, screen } from '@testing-library/react';
+import { Alert } from '../Alert';
+
+afterEach(cleanup);
+
+describe('Alert', () => {
+  it('uses role="alert" for the error variant', () => {
+    render(<Alert variant="error">Something went wrong.</Alert>);
+    expect(screen.getByRole('alert')).toBeDefined();
+  });
+
+  it.each(['info', 'success', 'warning', 'neutral'] as const)(
+    'uses role="status" for the %s variant',
+    (variant) => {
+      render(<Alert variant={variant}>Message</Alert>);
+      expect(screen.getByRole('status')).toBeDefined();
+    },
+  );
+
+  it('renders a heading when given one', () => {
+    render(
+      <Alert variant="warning" heading="Heads up">
+        Body text.
+      </Alert>,
+    );
+    expect(screen.getByText('Heads up')).toBeDefined();
+    expect(screen.getByText('Body text.')).toBeDefined();
+  });
+
+  it('renders without a heading', () => {
+    render(<Alert variant="info">Just the body.</Alert>);
+    expect(screen.getByText('Just the body.')).toBeDefined();
+  });
+
+  it('renders a default icon for info, success, warning, and error, but none for neutral', () => {
+    const info = render(<Alert variant="info">Message</Alert>);
+    expect(info.container.querySelector('svg')).not.toBeNull();
+    info.unmount();
+
+    const success = render(<Alert variant="success">Message</Alert>);
+    expect(success.container.querySelector('svg')).not.toBeNull();
+    success.unmount();
+
+    const warning = render(<Alert variant="warning">Message</Alert>);
+    expect(warning.container.querySelector('svg')).not.toBeNull();
+    warning.unmount();
+
+    const error = render(<Alert variant="error">Message</Alert>);
+    expect(error.container.querySelector('svg')).not.toBeNull();
+    error.unmount();
+
+    const neutral = render(<Alert variant="neutral">Message</Alert>);
+    expect(neutral.container.querySelector('svg')).toBeNull();
+  });
+
+  it('suppresses the default icon when icon={false}', () => {
+    const { container } = render(
+      <Alert variant="success" icon={false}>
+        Message
+      </Alert>,
+    );
+    expect(container.querySelector('svg')).toBeNull();
+  });
+
+  it('overrides the default icon when icon is set explicitly', () => {
+    const { container } = render(
+      <Alert variant="neutral" icon="info">
+        Message
+      </Alert>,
+    );
+    expect(container.querySelector('svg')).not.toBeNull();
+  });
+});

package/src/components/AspectRatio/AspectRatio.module.css

@@ -0,0 +1,15 @@
+.root {
+  position: relative;
+  width: 100%;
+  overflow: hidden;
+  border-radius: var(--sv-radius-md);
+}
+
+/* A single direct child (img/video/iframe) fills the ratio box. */
+.root > :global(*) {
+  position: absolute;
+  inset: 0;
+  width: 100%;
+  height: 100%;
+  object-fit: cover;
+}