@sovereignfs/ui 0.21.0

package/src/components/Tabs/Tabs.stories.tsx

@@ -0,0 +1,100 @@
+import { useState } from 'react';
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { Tabs } from './Tabs';
+
+const meta = {
+  title: 'Components/Tabs',
+  component: Tabs,
+  parameters: {
+    layout: 'padded',
+    docs: {
+      description: {
+        component:
+          'Underline tab nav. Stateless — caller owns `value` + `onChange` and renders the active panel. Mobile: scrolls horizontally with the scrollbar hidden.',
+      },
+    },
+  },
+  args: {
+    items: [{ label: 'Tab', value: 'tab' }],
+    value: 'tab',
+    onChange: () => {},
+    'aria-label': 'Tabs',
+  },
+} satisfies Meta<typeof Tabs>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+// ---------------------------------------------------------------------------
+
+const CONSOLE_TABS = [
+  { label: 'Overview', value: 'overview' },
+  { label: 'Users', value: 'users' },
+  { label: 'Plugins', value: 'plugins' },
+  { label: 'Settings', value: 'settings' },
+  { label: 'Health', value: 'health' },
+];
+
+const ACCOUNT_TABS = [
+  { label: 'Profile', value: 'profile' },
+  { label: 'Security', value: 'security' },
+  { label: 'Appearance', value: 'appearance' },
+  { label: 'Notifications', value: 'notifications' },
+  { label: 'Billing', value: 'billing' },
+  { label: 'Data', value: 'data' },
+];
+
+/** Console panel navigation. */
+export const Console: Story = {
+  render: (_args) => {
+    const [tab, setTab] = useState('overview');
+    return (
+      <div style={{ fontFamily: 'var(--sv-font-family)' }}>
+        <Tabs items={CONSOLE_TABS} value={tab} onChange={setTab} aria-label="Console" />
+        <div
+          style={{
+            padding: 'var(--sv-space-4)',
+            color: 'var(--sv-color-text-muted)',
+            fontSize: 'var(--sv-font-size-sm)',
+          }}
+        >
+          Showing: <strong style={{ color: 'var(--sv-color-text-primary)' }}>{tab}</strong>
+        </div>
+      </div>
+    );
+  },
+};
+
+/** Account settings — more tabs, scrolls on narrow viewports. */
+export const Account: Story = {
+  render: (_args) => {
+    const [tab, setTab] = useState('profile');
+    return (
+      <div style={{ fontFamily: 'var(--sv-font-family)', maxWidth: 480 }}>
+        <Tabs items={ACCOUNT_TABS} value={tab} onChange={setTab} aria-label="Account settings" />
+        <div
+          style={{
+            padding: 'var(--sv-space-4)',
+            color: 'var(--sv-color-text-muted)',
+            fontSize: 'var(--sv-font-size-sm)',
+          }}
+        >
+          Showing: <strong style={{ color: 'var(--sv-color-text-primary)' }}>{tab}</strong>
+        </div>
+      </div>
+    );
+  },
+};
+
+/** Narrow viewport — confirms horizontal scroll behaviour. */
+export const NarrowScroll: Story = {
+  parameters: { viewport: { defaultViewport: 'mobile1' } },
+  render: (_args) => {
+    const [tab, setTab] = useState('profile');
+    return (
+      <div style={{ fontFamily: 'var(--sv-font-family)' }}>
+        <Tabs items={ACCOUNT_TABS} value={tab} onChange={setTab} aria-label="Account settings" />
+      </div>
+    );
+  },
+};

package/src/components/Tabs/Tabs.tsx

@@ -0,0 +1,46 @@
+'use client';
+
+import styles from './Tabs.module.css';
+
+export interface TabItem {
+  label: string;
+  value: string;
+}
+
+export interface TabsProps {
+  items: TabItem[];
+  value: string;
+  onChange: (value: string) => void;
+  'aria-label': string;
+}
+
+/**
+ * Tabs — underline tab nav for section switching.
+ *
+ * Stateless: the active tab is fully controlled via `value` + `onChange`, so the
+ * caller owns state and controls the rendered panel content. This keeps the
+ * component RSC-compatible when wrapped by a client boundary upstream.
+ *
+ * Mobile: the tab bar scrolls horizontally with the native scrollbar hidden.
+ */
+export function Tabs({ items, value, onChange, 'aria-label': ariaLabel }: TabsProps) {
+  return (
+    <div role="tablist" aria-label={ariaLabel} className={styles.tablist}>
+      {items.map((item) => {
+        const active = item.value === value;
+        return (
+          <button
+            key={item.value}
+            type="button"
+            role="tab"
+            aria-selected={active}
+            className={[styles.tab, active ? styles.active : styles.inactive].join(' ')}
+            onClick={() => onChange(item.value)}
+          >
+            {item.label}
+          </button>
+        );
+      })}
+    </div>
+  );
+}

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

@@ -0,0 +1,45 @@
+// @vitest-environment jsdom
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { cleanup, render, screen, fireEvent } from '@testing-library/react';
+import { Tabs } from '../Tabs';
+
+afterEach(cleanup);
+
+const items = [
+  { label: 'Overview', value: 'overview' },
+  { label: 'Users', value: 'users' },
+  { label: 'Plugins', value: 'plugins' },
+];
+
+describe('Tabs', () => {
+  it('renders all items as tab buttons', () => {
+    render(<Tabs items={items} value="overview" onChange={() => {}} aria-label="Console" />);
+    expect(screen.getAllByRole('tab').length).toBe(3);
+  });
+
+  it('marks the active tab as selected', () => {
+    render(<Tabs items={items} value="users" onChange={() => {}} aria-label="Console" />);
+    expect(screen.getByRole('tab', { name: 'Users' }).getAttribute('aria-selected')).toBe('true');
+    expect(screen.getByRole('tab', { name: 'Overview' }).getAttribute('aria-selected')).toBe(
+      'false',
+    );
+  });
+
+  it('applies active class to the selected tab', () => {
+    render(<Tabs items={items} value="plugins" onChange={() => {}} aria-label="Console" />);
+    expect(screen.getByRole('tab', { name: 'Plugins' }).className).toContain('active');
+    expect(screen.getByRole('tab', { name: 'Overview' }).className).toContain('inactive');
+  });
+
+  it('calls onChange with the clicked tab value', () => {
+    const onChange = vi.fn();
+    render(<Tabs items={items} value="overview" onChange={onChange} aria-label="Console" />);
+    fireEvent.click(screen.getByRole('tab', { name: 'Users' }));
+    expect(onChange).toHaveBeenCalledWith('users');
+  });
+
+  it('exposes a tablist with the given aria-label', () => {
+    render(<Tabs items={items} value="overview" onChange={() => {}} aria-label="Nav" />);
+    expect(screen.getByRole('tablist', { name: 'Nav' })).toBeDefined();
+  });
+});

package/src/components/Toast/Toast.module.css

@@ -0,0 +1,130 @@
+/* Toast — transient notification snackbar.
+ *
+ * Fixed top-right, 320px. Slides in from above. Each toast auto-dismisses
+ * after `duration` ms. Leading status icon reinforces category at a glance.
+ *
+ * Category variants map to the semantic status tokens (info/success/warning/
+ * error) so the visual language is consistent with banners and badges.
+ * The announcement category uses the accent colour (neutral brand highlight).
+ * `security` matches the error palette — draws maximum attention. */
+
+.region {
+  position: fixed;
+  top: var(--sv-space-4);
+  right: var(--sv-space-4);
+  z-index: 200;
+  display: flex;
+  flex-direction: column;
+  gap: var(--sv-space-2);
+  width: 320px;
+  max-width: calc(100vw - var(--sv-space-8));
+  pointer-events: none;
+}
+
+.toast {
+  display: flex;
+  align-items: flex-start;
+  gap: var(--sv-space-3);
+  padding: var(--sv-space-3) var(--sv-space-4);
+  background: var(--sv-color-surface-raised);
+  color: var(--sv-color-text-primary);
+  border: 1px solid var(--sv-color-border);
+  border-radius: var(--sv-radius-md);
+  box-shadow: var(--sv-shadow-overlay);
+  pointer-events: all;
+  animation: toastIn 200ms ease-out;
+}
+
+.toast.exiting {
+  animation: toastOut 200ms ease-in forwards;
+}
+
+/* Leading status icon */
+.icon {
+  flex: 0 0 auto;
+  display: flex;
+  align-items: center;
+  padding-top: 1px;
+  color: var(--sv-color-border-strong);
+}
+
+.toast.info .icon,
+.toast.announcement .icon {
+  color: var(--sv-color-accent);
+}
+
+.toast.success .icon {
+  color: var(--sv-color-success-text);
+}
+
+.toast.warning .icon {
+  color: var(--sv-color-warning-text);
+}
+
+.toast.error .icon,
+.toast.security .icon {
+  color: var(--sv-color-error-text);
+}
+
+.body {
+  flex: 1 1 auto;
+  min-width: 0;
+}
+
+.title {
+  font-size: var(--sv-font-size-sm);
+  font-weight: 600;
+  line-height: 1.4;
+  color: var(--sv-color-text-primary);
+}
+
+.message {
+  font-size: var(--sv-font-size-sm);
+  color: var(--sv-color-text-secondary);
+  margin-top: var(--sv-space-1);
+  line-height: 1.4;
+}
+
+.close {
+  flex: 0 0 auto;
+  background: none;
+  border: none;
+  padding: 0;
+  cursor: pointer;
+  color: var(--sv-color-text-tertiary);
+  line-height: 1;
+  font-size: var(--sv-font-size-base);
+}
+
+.close:hover {
+  color: var(--sv-color-text-primary);
+}
+
+@keyframes toastIn {
+  from {
+    opacity: 0;
+    transform: translateY(-8px);
+  }
+  to {
+    opacity: 1;
+    transform: translateY(0);
+  }
+}
+
+@keyframes toastOut {
+  from {
+    opacity: 1;
+    transform: translateY(0);
+  }
+  to {
+    opacity: 0;
+    transform: translateY(-8px);
+  }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .toast,
+  .toast.exiting {
+    animation: none;
+  }
+}

package/src/components/Toast/Toast.stories.tsx

@@ -0,0 +1,191 @@
+import { useState } from 'react';
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { ToastProvider, useToast } from './Toast';
+
+const meta = {
+  title: 'Components/Toast',
+  component: ToastProvider,
+  parameters: {
+    layout: 'centered',
+    docs: {
+      description: {
+        component:
+          'Fixed top-right notification stack. Use `<ToastProvider>` at the app root and `useToast()` to imperatively show toasts. Each toast has a leading status icon matched to its category.',
+      },
+    },
+  },
+  args: {
+    children: null,
+  },
+} satisfies Meta<typeof ToastProvider>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+// ---------------------------------------------------------------------------
+
+function ToastTrigger({ category, label }: { category: string; label: string }) {
+  const { show } = useToast();
+  return (
+    <button
+      type="button"
+      onClick={() =>
+        show({
+          title: label,
+          message: `This is a ${category} toast notification.`,
+          category,
+        })
+      }
+      style={{
+        padding: '8px 16px',
+        borderRadius: 'var(--sv-radius-md)',
+        border: '1px solid var(--sv-color-border)',
+        background: 'var(--sv-color-surface)',
+        color: 'var(--sv-color-text-primary)',
+        fontFamily: 'var(--sv-font-family)',
+        fontSize: 'var(--sv-font-size-sm)',
+        cursor: 'pointer',
+      }}
+    >
+      {label}
+    </button>
+  );
+}
+
+/** All toast categories — each button fires a toast with the matching leading icon. */
+export const AllCategories: Story = {
+  render: (_args) => (
+    <ToastProvider>
+      <div
+        style={{
+          display: 'flex',
+          flexDirection: 'column',
+          gap: 8,
+          alignItems: 'flex-start',
+        }}
+      >
+        <ToastTrigger category="info" label="Info toast" />
+        <ToastTrigger category="success" label="Success toast" />
+        <ToastTrigger category="warning" label="Warning toast" />
+        <ToastTrigger category="error" label="Error toast" />
+        <ToastTrigger category="security" label="Security toast" />
+        <ToastTrigger category="announcement" label="Announcement toast" />
+      </div>
+    </ToastProvider>
+  ),
+};
+
+/** Toast with no body — title only. */
+export const TitleOnly: Story = {
+  render: (_args) => {
+    function Trigger() {
+      const { show } = useToast();
+      return (
+        <button
+          type="button"
+          onClick={() => show({ title: 'Session expires in 5 minutes', category: 'warning' })}
+          style={{
+            padding: '8px 16px',
+            borderRadius: 'var(--sv-radius-md)',
+            border: '1px solid var(--sv-color-border)',
+            background: 'var(--sv-color-surface)',
+            color: 'var(--sv-color-text-primary)',
+            fontFamily: 'var(--sv-font-family)',
+            fontSize: 'var(--sv-font-size-sm)',
+            cursor: 'pointer',
+          }}
+        >
+          Show title-only toast
+        </button>
+      );
+    }
+    return (
+      <ToastProvider>
+        <Trigger />
+      </ToastProvider>
+    );
+  },
+};
+
+/** Persistent toast — pass `duration: 0` to disable auto-dismiss. */
+export const Persistent: Story = {
+  render: (_args) => {
+    function Trigger() {
+      const { show } = useToast();
+      return (
+        <button
+          type="button"
+          onClick={() =>
+            show({
+              title: 'Maintenance mode active',
+              message: 'Platform is in read-only mode. Dismiss when resolved.',
+              category: 'error',
+              duration: 0,
+            })
+          }
+          style={{
+            padding: '8px 16px',
+            borderRadius: 'var(--sv-radius-md)',
+            border: '1px solid var(--sv-color-border)',
+            background: 'var(--sv-color-surface)',
+            color: 'var(--sv-color-text-primary)',
+            fontFamily: 'var(--sv-font-family)',
+            fontSize: 'var(--sv-font-size-sm)',
+            cursor: 'pointer',
+          }}
+        >
+          Show persistent toast
+        </button>
+      );
+    }
+    return (
+      <ToastProvider>
+        <Trigger />
+      </ToastProvider>
+    );
+  },
+};
+
+/** Multiple toasts stack vertically below the first. */
+export const Stacked: Story = {
+  render: (_args) => {
+    function Trigger() {
+      const { show } = useToast();
+      const [fired, setFired] = useState(false);
+      return (
+        <button
+          type="button"
+          disabled={fired}
+          onClick={() => {
+            show({ title: 'Plugin installed', category: 'success' });
+            show({
+              title: 'License warning',
+              message: 'Expires in 3 days.',
+              category: 'warning',
+            });
+            show({ title: 'Backup failed', message: 'Check storage quota.', category: 'error' });
+            setFired(true);
+          }}
+          style={{
+            padding: '8px 16px',
+            borderRadius: 'var(--sv-radius-md)',
+            border: '1px solid var(--sv-color-border)',
+            background: 'var(--sv-color-surface)',
+            color: 'var(--sv-color-text-primary)',
+            fontFamily: 'var(--sv-font-family)',
+            fontSize: 'var(--sv-font-size-sm)',
+            cursor: fired ? 'default' : 'pointer',
+            opacity: fired ? 0.5 : 1,
+          }}
+        >
+          Fire 3 toasts
+        </button>
+      );
+    }
+    return (
+      <ToastProvider>
+        <Trigger />
+      </ToastProvider>
+    );
+  },
+};

package/src/components/Toast/Toast.tsx

@@ -0,0 +1,139 @@
+'use client';
+
+import {
+  createContext,
+  useCallback,
+  useContext,
+  useEffect,
+  useId,
+  useMemo,
+  useRef,
+  useState,
+} from 'react';
+import { Icon, type IconName } from '../Icon/Icon';
+import styles from './Toast.module.css';
+
+export interface ToastItem {
+  id: string;
+  title: string;
+  message?: string;
+  /** `'info'` | `'success'` | `'warning'` | `'error'` | `'security'` | `'announcement'` */
+  category?: string;
+  /** Auto-dismiss delay in ms. Default 5000. Pass `0` to disable auto-dismiss. */
+  duration?: number;
+  exiting?: boolean;
+}
+
+export interface ToastContextValue {
+  /** Show a toast notification. Returns the generated toast id. */
+  show(item: Omit<ToastItem, 'id'>): string;
+  /** Dismiss a toast by id. */
+  dismiss(id: string): void;
+}
+
+const ToastContext = createContext<ToastContextValue | null>(null);
+
+/** Consume the toast context to imperatively show toasts from any client component. */
+export function useToast(): ToastContextValue {
+  const ctx = useContext(ToastContext);
+  if (!ctx) throw new Error('useToast() must be used inside <ToastProvider>');
+  return ctx;
+}
+
+export function ToastProvider({ children }: { children: React.ReactNode }) {
+  const [toasts, setToasts] = useState<ToastItem[]>([]);
+  const timers = useRef<Map<string, ReturnType<typeof setTimeout>>>(new Map());
+  const seedId = useId();
+  const counter = useRef(0);
+
+  const dismiss = useCallback((id: string) => {
+    setToasts((prev) => prev.map((t) => (t.id === id ? { ...t, exiting: true } : t)));
+    setTimeout(() => {
+      setToasts((prev) => prev.filter((t) => t.id !== id));
+    }, 220);
+  }, []);
+
+  const show = useCallback(
+    (item: Omit<ToastItem, 'id'>): string => {
+      const id = `${seedId}-${++counter.current}`;
+      const duration = item.duration ?? 5000;
+      setToasts((prev) => [...prev, { ...item, id }]);
+      if (duration > 0) {
+        const timer = setTimeout(() => dismiss(id), duration);
+        timers.current.set(id, timer);
+      }
+      return id;
+    },
+    [seedId, dismiss],
+  );
+
+  useEffect(() => {
+    const currentTimers = timers.current;
+    return () => {
+      currentTimers.forEach((t) => clearTimeout(t));
+    };
+  }, []);
+
+  const value = useMemo(() => ({ show, dismiss }), [show, dismiss]);
+
+  return (
+    <ToastContext.Provider value={value}>
+      {children}
+      <ol
+        className={styles.region}
+        aria-label="Notifications"
+        aria-live="polite"
+        aria-atomic="false"
+      >
+        {toasts.map((toast) => (
+          <Toast key={toast.id} {...toast} onDismiss={dismiss} />
+        ))}
+      </ol>
+    </ToastContext.Provider>
+  );
+}
+
+/** Maps toast category to a leading Icon name. */
+const CATEGORY_ICON: Record<string, IconName> = {
+  info: 'info',
+  announcement: 'info',
+  success: 'check',
+  warning: 'alert-triangle',
+  error: 'alert-triangle',
+  security: 'alert-triangle',
+};
+
+function Toast({
+  id,
+  title,
+  message,
+  category = 'info',
+  exiting,
+  onDismiss,
+}: ToastItem & { onDismiss(id: string): void }) {
+  const categoryClass = styles[category as keyof typeof styles] ?? styles.info;
+  const iconName = CATEGORY_ICON[category] ?? 'info';
+
+  return (
+    <li
+      role="status"
+      className={`${styles.toast} ${String(categoryClass)} ${exiting ? styles.exiting : ''}`}
+    >
+      <span className={styles.icon} aria-hidden="true">
+        <Icon name={iconName} size="sm" aria-hidden />
+      </span>
+      <div className={styles.body}>
+        <div className={styles.title}>{title}</div>
+        {message && <div className={styles.message}>{message}</div>}
+      </div>
+      <button
+        type="button"
+        className={styles.close}
+        aria-label="Dismiss notification"
+        onClick={() => onDismiss(id)}
+      >
+        ✕
+      </button>
+    </li>
+  );
+}

package/src/components/Toggle/Toggle.module.css

@@ -0,0 +1,52 @@
+.track {
+  /* 38×22px pill — spec dimensions */
+  display: inline-flex;
+  align-items: center;
+  width: 38px;
+  height: 22px;
+  border-radius: var(--sv-radius-full);
+  border: none;
+  padding: 0;
+  cursor: pointer;
+  flex-shrink: 0;
+  transition: background-color 0.15s ease;
+  position: relative;
+}
+
+.track:focus-visible {
+  outline: 2px solid var(--sv-color-focus-ring);
+  outline-offset: 2px;
+}
+
+.track:disabled {
+  opacity: 0.5;
+  cursor: not-allowed;
+}
+
+.on {
+  background-color: var(--sv-color-accent);
+}
+
+.off {
+  background-color: var(--sv-color-border-strong);
+}
+
+/* 18px thumb, 2px inset on each side */
+.thumb {
+  position: absolute;
+  width: 18px;
+  height: 18px;
+  border-radius: var(--sv-radius-full);
+  background: var(--sv-white);
+  transition: transform 0.15s ease;
+  left: 2px;
+  box-shadow: 0 1px 3px rgba(0, 0, 0, 0.2);
+}
+
+.on .thumb {
+  transform: translateX(16px); /* 38 - 18 - 2 - 2 = 16 */
+}
+
+.off .thumb {
+  transform: translateX(0);
+}