@sovereignfs/ui 0.21.0

package/src/components/Button/Button.module.css

@@ -0,0 +1,77 @@
+.button {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  gap: var(--sv-space-2);
+  border: 1px solid transparent;
+  border-radius: var(--sv-radius-md);
+  font-family: var(--sv-font-family);
+  font-weight: var(--sv-font-weight-medium);
+  line-height: 1;
+  cursor: pointer;
+  transition:
+    background-color 0.15s ease,
+    border-color 0.15s ease,
+    color 0.15s ease;
+}
+
+.button:focus-visible {
+  outline: 2px solid var(--sv-color-focus-ring);
+  outline-offset: 2px;
+}
+
+.button:disabled {
+  opacity: 0.5;
+  cursor: not-allowed;
+}
+
+/* Sizes */
+.sm {
+  padding: var(--sv-space-1) var(--sv-space-3);
+  font-size: var(--sv-font-size-sm);
+}
+
+.md {
+  padding: 13px var(--sv-space-4);
+  font-size: var(--sv-font-size-sm);
+  font-weight: var(--sv-font-weight-semibold);
+}
+
+/* Variants */
+.primary {
+  background-color: var(--sv-color-accent);
+  color: var(--sv-color-text-on-accent);
+}
+
+.primary:hover:not(:disabled) {
+  background-color: var(--sv-color-accent-hover);
+}
+
+.secondary {
+  background-color: var(--sv-color-surface);
+  color: var(--sv-color-text-primary);
+  border-color: var(--sv-color-border-strong);
+}
+
+.secondary:hover:not(:disabled) {
+  background-color: var(--sv-color-surface-sunken);
+}
+
+.ghost {
+  background-color: transparent;
+  color: var(--sv-color-text-primary);
+}
+
+.ghost:hover:not(:disabled) {
+  background-color: var(--sv-color-surface-sunken);
+}
+
+.destructive {
+  background-color: transparent;
+  color: var(--sv-color-error-text);
+  border-color: var(--sv-color-error-border);
+}
+
+.destructive:hover:not(:disabled) {
+  background-color: var(--sv-color-error-surface);
+}

package/src/components/Button/Button.stories.tsx

@@ -0,0 +1,76 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { Icon } from '../Icon/Icon';
+import { Button } from './Button';
+
+const meta = {
+  title: 'Components/Button',
+  component: Button,
+  parameters: {
+    layout: 'centered',
+    docs: {
+      description: {
+        component:
+          'The primitive interactive control. RSC-safe (no state, forwards props). All styling references `--sv-*` tokens; no hardcoded values.',
+      },
+    },
+  },
+  argTypes: {
+    variant: { control: 'select', options: ['primary', 'secondary', 'ghost', 'destructive'] },
+    size: { control: 'select', options: ['sm', 'md'] },
+    disabled: { control: 'boolean' },
+    children: { control: 'text' },
+  },
+  args: {
+    children: 'Button',
+  },
+} satisfies Meta<typeof Button>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+// ---------------------------------------------------------------------------
+
+export const Primary: Story = { args: { variant: 'primary' } };
+export const Secondary: Story = { args: { variant: 'secondary' } };
+export const Ghost: Story = { args: { variant: 'ghost' } };
+export const Destructive: Story = { args: { variant: 'destructive', children: 'Delete account' } };
+
+export const Small: Story = { args: { size: 'sm' } };
+export const Medium: Story = { args: { size: 'md' } };
+
+export const Disabled: Story = { args: { disabled: true } };
+export const DisabledSecondary: Story = { args: { variant: 'secondary', disabled: true } };
+
+export const WithLeadingIcon: Story = {
+  args: {
+    children: (
+      <>
+        <Icon name="plus" size="sm" aria-hidden />
+        Add item
+      </>
+    ),
+  },
+};
+
+export const IconOnly: Story = {
+  args: {
+    variant: 'ghost',
+    'aria-label': 'Settings',
+    children: <Icon name="settings" size="sm" aria-hidden />,
+  },
+};
+
+/** All variant × size combinations at a glance. */
+export const AllVariants: Story = {
+  render: (_args) => (
+    <div style={{ display: 'flex', flexDirection: 'column', gap: 16, alignItems: 'flex-start' }}>
+      {(['primary', 'secondary', 'ghost', 'destructive'] as const).map((v) =>
+        (['md', 'sm'] as const).map((s) => (
+          <Button key={`${v}-${s}`} variant={v} size={s}>
+            {v} / {s}
+          </Button>
+        )),
+      )}
+    </div>
+  ),
+};

package/src/components/Button/Button.tsx

@@ -0,0 +1,36 @@
+import type { ButtonHTMLAttributes, ReactNode } from 'react';
+import styles from './Button.module.css';
+
+export type ButtonVariant = 'primary' | 'secondary' | 'ghost' | 'destructive';
+export type ButtonSize = 'sm' | 'md';
+
+export interface ButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> {
+  variant?: ButtonVariant;
+  size?: ButtonSize;
+  children: ReactNode;
+}
+
+/**
+ * Button — the primitive interactive control. Presentational and RSC-safe: it
+ * holds no state and simply forwards props to the underlying `<button>`, so it
+ * renders in both Server and Client Components. All styling references `--sv-*`
+ * tokens via CSS Modules; there are no hardcoded values.
+ */
+export function Button({
+  variant = 'primary',
+  size = 'md',
+  type = 'button',
+  className,
+  children,
+  ...rest
+}: ButtonProps) {
+  const classes = [styles.button, styles[variant], styles[size], className]
+    .filter(Boolean)
+    .join(' ');
+
+  return (
+    <button type={type} className={classes} {...rest}>
+      {children}
+    </button>
+  );
+}

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

@@ -0,0 +1,37 @@
+// @vitest-environment jsdom
+import { describe, expect, it } from 'vitest';
+import { render, screen } from '@testing-library/react';
+import { Button } from '../Button';
+
+describe('Button', () => {
+  it('renders its children', () => {
+    render(<Button>Click me</Button>);
+    expect(screen.getByRole('button', { name: 'Click me' })).toBeDefined();
+  });
+
+  it('applies the variant and size classes', () => {
+    render(
+      <Button variant="ghost" size="sm">
+        Go
+      </Button>,
+    );
+    const button = screen.getByRole('button', { name: 'Go' });
+    expect(button.className).toContain('ghost');
+    expect(button.className).toContain('sm');
+  });
+
+  it('defaults to type="button"', () => {
+    render(<Button>Save</Button>);
+    expect(screen.getByRole('button', { name: 'Save' }).getAttribute('type')).toBe('button');
+  });
+
+  it('forwards native button props', () => {
+    render(<Button disabled>Nope</Button>);
+    expect((screen.getByRole('button', { name: 'Nope' }) as HTMLButtonElement).disabled).toBe(true);
+  });
+
+  it('applies destructive variant class', () => {
+    render(<Button variant="destructive">Delete</Button>);
+    expect(screen.getByRole('button', { name: 'Delete' }).className).toContain('destructive');
+  });
+});

package/src/components/Card/Card.module.css

@@ -0,0 +1,34 @@
+.card {
+  background: var(--sv-color-surface-raised);
+  border: 1px solid var(--sv-color-border);
+  border-radius: var(--sv-radius-lg);
+  box-shadow: var(--sv-shadow-card);
+}
+
+.paddingSm {
+  padding: var(--sv-space-3);
+}
+
+.paddingMd {
+  padding: var(--sv-space-5);
+}
+
+.paddingLg {
+  padding: var(--sv-space-8);
+}
+
+.interactive {
+  cursor: pointer;
+  text-decoration: none;
+  display: block;
+  transition: border-color 0.15s ease;
+}
+
+.interactive:hover {
+  border-color: var(--sv-color-border-strong);
+}
+
+.interactive:focus-visible {
+  outline: 2px solid var(--sv-color-focus-ring);
+  outline-offset: 2px;
+}

package/src/components/Card/Card.tsx

@@ -0,0 +1,34 @@
+import type { HTMLAttributes, ReactNode } from 'react';
+import styles from './Card.module.css';
+
+export interface CardProps extends HTMLAttributes<HTMLElement> {
+  as?: 'div' | 'article' | 'li';
+  interactive?: boolean;
+  padding?: 'sm' | 'md' | 'lg';
+  children: ReactNode;
+}
+
+const paddingClass: Record<NonNullable<CardProps['padding']>, string> = {
+  sm: styles.paddingSm as string,
+  md: styles.paddingMd as string,
+  lg: styles.paddingLg as string,
+};
+
+export function Card({
+  as: Tag = 'div',
+  interactive = false,
+  padding = 'md',
+  className,
+  children,
+  ...rest
+}: CardProps) {
+  const cls = [styles.card, paddingClass[padding], interactive && styles.interactive, className]
+    .filter(Boolean)
+    .join(' ');
+
+  return (
+    <Tag className={cls} {...rest}>
+      {children}
+    </Tag>
+  );
+}

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

@@ -0,0 +1,188 @@
+/* Dialog — scrim + centered panel. Tokens only (z-index is structural, not a
+ * theming value, so it has no token).
+ *
+ * Each size is a FIXED box (width AND height) — the panel never grows or
+ * shrinks with its content, so switching views inside it (e.g. overlay-plugin
+ * tabs) keeps the dialog the exact same size. Overflow scrolls inside `.content`
+ * while the panel and its close button stay put. The scrim's padding is the
+ * fixed margin `lg` leaves around the viewport; `sm`/`md` are centered and cap
+ * to that available space on short screens. On mobile every size becomes a
+ * full-screen sheet.
+ *
+ * `--sv-dialog-inset-left` lets a host inset the scrim past a fixed left nav
+ * rail (e.g. the platform sidebar) so the overlay's left margin is measured
+ * from the rail, not the viewport edge, and the rail stays visible/usable.
+ * `--sv-dialog-inset-top` (RFC 0013) mirrors this on the vertical axis: the
+ * shell sets it to the mobile header height so the header stays visible and
+ * interactive above the dialog sheet. Defaults to 0 for standalone use. */
+
+.scrim {
+  position: fixed;
+  top: var(--sv-dialog-inset-top, 0);
+  right: 0;
+  bottom: 0;
+  left: 0;
+  z-index: 100;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  /* left edge always 0 so the backdrop covers the full viewport incl. sidebar.
+     padding-left offsets the panel's available area to start at the rail edge. */
+  padding: var(--sv-space-8);
+  padding-left: calc(var(--sv-dialog-inset-left, 0px) + var(--sv-space-8));
+  background: var(--sv-color-scrim);
+}
+
+.panel {
+  position: relative;
+  display: flex;
+  flex-direction: column;
+  overflow: hidden;
+  background: var(--sv-color-surface-raised);
+  color: var(--sv-color-text-primary);
+  border: 1px solid var(--sv-color-border);
+  border-radius: var(--sv-radius-lg);
+  box-shadow: var(--sv-shadow-overlay);
+}
+
+.content {
+  flex: 1 1 auto;
+  overflow-y: auto;
+  padding: var(--sv-space-6);
+}
+
+/* Fixed sizes. `max-*: 100%` caps to the scrim's content box (viewport minus
+ * margin) so a size never overflows a small viewport. */
+.sm {
+  width: 24rem;
+  height: 28rem;
+  max-width: 100%;
+  max-height: 100%;
+}
+
+.md {
+  width: 36rem;
+  height: 42rem;
+  max-width: 100%;
+  max-height: 100%;
+}
+
+.lg,
+.full {
+  width: 100%;
+  height: 100%;
+}
+
+.close {
+  position: absolute;
+  top: var(--sv-space-3);
+  right: var(--sv-space-3);
+  z-index: 1;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: var(--sv-space-8);
+  height: var(--sv-space-8);
+  border: none;
+  border-radius: var(--sv-radius-md);
+  background: transparent;
+  color: var(--sv-color-text-muted);
+  font-size: var(--sv-font-size-xl);
+  line-height: 1;
+  cursor: pointer;
+}
+
+.close:hover {
+  background: var(--sv-color-surface-sunken);
+  color: var(--sv-color-text-primary);
+}
+
+.close:focus-visible {
+  outline: 2px solid var(--sv-color-focus-ring);
+  outline-offset: 2px;
+}
+
+/* Hidden on desktop; shown only on mobile where it replaces the close button. */
+.mobileBar {
+  display: none;
+}
+
+/* Mobile: full-screen sheet (RFC 0001 §3, breakpoint unified to 768px per
+ * RFC 0013). Every size fills the scrim's available area (which is already
+ * inset from the top by --sv-dialog-inset-top when a fixed header is shown).
+ * The panel therefore fills height: 100% of the remaining space, not 100dvh. */
+@media (max-width: 768px) {
+  /* On mobile the overlay feels like a full-page push, not a floating modal.
+     Remove the dim scrim and panel chrome so it's indistinguishable from a
+     regular page render. router.back() still closes it correctly. */
+  .scrim {
+    padding: 0;
+    background: transparent;
+  }
+
+  .panel,
+  .sm,
+  .md,
+  .lg,
+  .full {
+    width: 100%;
+    height: 100%;
+    max-width: none;
+    max-height: none;
+    border: none;
+    border-radius: 0;
+    box-shadow: none;
+    background: var(--sv-color-surface);
+  }
+
+  /* Desktop close button is replaced by mobileBar on mobile. */
+  .close {
+    display: none;
+  }
+
+  /* Title + close button in one solid row. Being a flex sibling before
+     .content means it never scrolls — the content area scrolls below it. */
+  .mobileBar {
+    display: flex;
+    align-items: center;
+    flex-shrink: 0;
+    padding: var(--sv-space-3) var(--sv-space-4);
+    background: var(--sv-color-surface);
+    border-bottom: 1px solid var(--sv-color-border);
+  }
+
+  .mobileBarTitle {
+    flex: 1;
+    font-size: var(--sv-font-size-xl);
+    font-weight: var(--sv-font-weight-semibold);
+    color: var(--sv-color-text-primary);
+  }
+
+  .mobileBarClose {
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    width: var(--sv-space-8);
+    height: var(--sv-space-8);
+    flex-shrink: 0;
+    border: none;
+    border-radius: var(--sv-radius-md);
+    background: transparent;
+    color: var(--sv-color-text-muted);
+    font-size: var(--sv-font-size-xl);
+    line-height: 1;
+    cursor: pointer;
+  }
+
+  .mobileBarClose:hover {
+    background: var(--sv-color-surface-sunken);
+    color: var(--sv-color-text-primary);
+  }
+
+  /* Remove top padding so the sticky plugin header sits flush against the
+     mobileBar — no gap for scrolling content to bleed through. */
+  .content {
+    padding-top: 0;
+    padding-bottom: calc(var(--sv-shell-footer-height, 60px) + var(--sv-space-6, 24px));
+  }
+}

package/src/components/Dialog/Dialog.stories.tsx

@@ -0,0 +1,97 @@
+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 { Dialog } from './Dialog';
+
+// Controlled wrapper so the play function can open/inspect the dialog.
+function DialogDemo({
+  size = 'lg',
+  label = 'Example dialog',
+}: {
+  size?: 'sm' | 'md' | 'lg' | 'full';
+  label?: string;
+}) {
+  const [open, setOpen] = useState(false);
+  return (
+    <>
+      <Button onClick={() => setOpen(true)}>Open {size} dialog</Button>
+      <Dialog open={open} onClose={() => setOpen(false)} size={size} aria-label={label}>
+        <div style={{ padding: 24, fontFamily: 'system-ui' }}>
+          <h2
+            style={{
+              fontSize: 18,
+              fontWeight: 600,
+              color: 'var(--sv-color-text-primary)',
+              marginBottom: 12,
+            }}
+          >
+            {label}
+          </h2>
+          <p style={{ color: 'var(--sv-color-text-muted)', marginBottom: 24 }}>
+            This is a <strong>{size}</strong> dialog. Press Esc or click the scrim to dismiss.
+          </p>
+          <Button variant="secondary" onClick={() => setOpen(false)}>
+            Close
+          </Button>
+        </div>
+      </Dialog>
+    </>
+  );
+}
+
+const meta = {
+  title: 'Components/Dialog',
+  component: Dialog,
+  parameters: {
+    layout: 'centered',
+    docs: {
+      description: {
+        component:
+          'Modal surface (scrim + panel). Router-agnostic — caller provides `onClose`. Supports Esc, scrim-click, focus trap and focus restoration. Sizes: `sm` / `md` / `lg` / `full`. Mobile always renders as a full-screen sheet.',
+      },
+    },
+  },
+} satisfies Meta<typeof Dialog>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+// ---------------------------------------------------------------------------
+
+export const Small: Story = {
+  args: { open: false, onClose: () => {}, children: null },
+  render: (_args) => <DialogDemo size="sm" label="Small dialog" />,
+};
+
+export const Medium: Story = {
+  args: { open: false, onClose: () => {}, children: null },
+  render: (_args) => <DialogDemo size="md" label="Medium dialog" />,
+};
+
+export const Large: Story = {
+  args: { open: false, onClose: () => {}, children: null },
+  render: (_args) => <DialogDemo size="lg" label="Large dialog" />,
+};
+
+export const Closed: Story = {
+  args: { open: false, onClose: () => {}, children: null },
+  render: (_args) => (
+    <Dialog open={false} onClose={() => {}} aria-label="Closed dialog">
+      <p>Never seen</p>
+    </Dialog>
+  ),
+};
+
+/** Play function opens the dialog and asserts it is visible. */
+export const OpenViaInteraction: Story = {
+  args: { open: false, onClose: () => {}, children: null },
+  render: (_args) => <DialogDemo size="md" label="Interaction test dialog" />,
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    const trigger = canvas.getByRole('button', { name: /open md dialog/i });
+    await userEvent.click(trigger);
+    const dialog = canvas.getByRole('dialog');
+    await expect(dialog).toBeVisible();
+  },
+};