@sovereignfs/ui 0.21.0

package/src/components/Toggle/Toggle.stories.tsx

@@ -0,0 +1,95 @@
+import { useState } from 'react';
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { Toggle } from './Toggle';
+
+const meta = {
+  title: 'Components/Toggle',
+  component: Toggle,
+  parameters: {
+    layout: 'centered',
+    docs: {
+      description: {
+        component:
+          '38×22px binary switch for settings rows. Renders as `<button role="switch">` for reliable VoiceOver support. `aria-label` is required.',
+      },
+    },
+  },
+  argTypes: {
+    checked: { control: 'boolean' },
+    disabled: { control: 'boolean' },
+  },
+  args: {
+    checked: false,
+    onChange: () => {},
+    'aria-label': 'Toggle setting',
+  },
+} satisfies Meta<typeof Toggle>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+// ---------------------------------------------------------------------------
+
+export const Off: Story = { args: { checked: false } };
+export const On: Story = { args: { checked: true } };
+export const Disabled: Story = { args: { checked: false, disabled: true } };
+export const DisabledOn: Story = { args: { checked: true, disabled: true } };
+
+/** Interactive — click to toggle. */
+export const Interactive: Story = {
+  render: (args) => {
+    const [checked, setChecked] = useState(args.checked);
+    return <Toggle {...args} checked={checked} onChange={setChecked} />;
+  },
+};
+
+/** Settings rows — typical usage with adjacent label text. */
+export const SettingsRows: Story = {
+  render: (_args) => {
+    const [twoFA, setTwoFA] = useState(true);
+    const [email, setEmail] = useState(false);
+
+    const rowStyle: React.CSSProperties = {
+      display: 'flex',
+      alignItems: 'center',
+      justifyContent: 'space-between',
+      gap: 32,
+      padding: '12px 0',
+      borderBottom: '1px solid var(--sv-color-border)',
+      fontFamily: 'var(--sv-font-family)',
+    };
+    const labelStyle: React.CSSProperties = {
+      display: 'flex',
+      flexDirection: 'column',
+      gap: 2,
+    };
+    const titleStyle: React.CSSProperties = {
+      fontSize: 'var(--sv-font-size-sm)',
+      fontWeight: 'var(--sv-font-weight-medium)',
+      color: 'var(--sv-color-text-primary)',
+    };
+    const descStyle: React.CSSProperties = {
+      fontSize: 'var(--sv-font-size-caption)',
+      color: 'var(--sv-color-text-muted)',
+    };
+
+    return (
+      <div style={{ width: 320 }}>
+        <div style={rowStyle}>
+          <div style={labelStyle}>
+            <span style={titleStyle}>Two-factor authentication</span>
+            <span style={descStyle}>Require a code when signing in.</span>
+          </div>
+          <Toggle checked={twoFA} onChange={setTwoFA} aria-label="Two-factor authentication" />
+        </div>
+        <div style={rowStyle}>
+          <div style={labelStyle}>
+            <span style={titleStyle}>Email notifications</span>
+            <span style={descStyle}>Receive digests and alerts.</span>
+          </div>
+          <Toggle checked={email} onChange={setEmail} aria-label="Email notifications" />
+        </div>
+      </div>
+    );
+  },
+};

package/src/components/Toggle/Toggle.tsx

@@ -0,0 +1,39 @@
+'use client';
+
+import type { ButtonHTMLAttributes } from 'react';
+import styles from './Toggle.module.css';
+
+export interface ToggleProps extends Omit<
+  ButtonHTMLAttributes<HTMLButtonElement>,
+  'onChange' | 'aria-label'
+> {
+  checked: boolean;
+  onChange: (checked: boolean) => void;
+  disabled?: boolean;
+  'aria-label': string;
+}
+
+/**
+ * Toggle — 38×22px binary switch for settings rows.
+ *
+ * Renders as `<button role="switch">` rather than a hidden `<input type="checkbox">`
+ * to avoid iOS VoiceOver focus quirks on visually styled checkboxes. The `aria-label`
+ * prop is required because the control has no visible text label of its own.
+ */
+export function Toggle({ checked, onChange, disabled, className, ...rest }: ToggleProps) {
+  return (
+    <button
+      type="button"
+      role="switch"
+      aria-checked={checked}
+      disabled={disabled}
+      className={[styles.track, checked ? styles.on : styles.off, className]
+        .filter(Boolean)
+        .join(' ')}
+      onClick={() => onChange(!checked)}
+      {...rest}
+    >
+      <span className={styles.thumb} />
+    </button>
+  );
+}

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

@@ -0,0 +1,47 @@
+// @vitest-environment jsdom
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { cleanup, render, screen, fireEvent } from '@testing-library/react';
+
+afterEach(cleanup);
+import { Toggle } from '../Toggle';
+
+describe('Toggle', () => {
+  it('renders as a switch button', () => {
+    render(<Toggle checked={false} onChange={() => {}} aria-label="Notifications" />);
+    expect(screen.getByRole('switch', { name: 'Notifications' })).toBeDefined();
+  });
+
+  it('reflects checked state via aria-checked', () => {
+    const { rerender } = render(
+      <Toggle checked={false} onChange={() => {}} aria-label="Setting" />,
+    );
+    expect(screen.getByRole('switch').getAttribute('aria-checked')).toBe('false');
+
+    rerender(<Toggle checked={true} onChange={() => {}} aria-label="Setting" />);
+    expect(screen.getByRole('switch').getAttribute('aria-checked')).toBe('true');
+  });
+
+  it('calls onChange with toggled value on click', () => {
+    const onChange = vi.fn();
+    render(<Toggle checked={false} onChange={onChange} aria-label="Setting" />);
+    fireEvent.click(screen.getByRole('switch'));
+    expect(onChange).toHaveBeenCalledWith(true);
+  });
+
+  it('does not call onChange when disabled', () => {
+    const onChange = vi.fn();
+    render(<Toggle checked={false} onChange={onChange} disabled aria-label="Setting" />);
+    fireEvent.click(screen.getByRole('switch'));
+    expect(onChange).not.toHaveBeenCalled();
+  });
+
+  it('applies on class when checked', () => {
+    render(<Toggle checked={true} onChange={() => {}} aria-label="Setting" />);
+    expect(screen.getByRole('switch').className).toContain('on');
+  });
+
+  it('applies off class when unchecked', () => {
+    render(<Toggle checked={false} onChange={() => {}} aria-label="Setting" />);
+    expect(screen.getByRole('switch').className).toContain('off');
+  });
+});

package/src/components/Tooltip/Tooltip.module.css

@@ -0,0 +1,51 @@
+.wrapper {
+  position: relative;
+  display: inline-flex;
+}
+
+.tip {
+  position: absolute;
+  z-index: 50;
+  white-space: nowrap;
+  padding: var(--sv-space-1) var(--sv-space-2);
+  background: var(--sv-color-surface-raised);
+  border: 1px solid var(--sv-color-border);
+  border-radius: var(--sv-radius-md);
+  box-shadow: var(--sv-shadow-popover);
+  font-size: var(--sv-font-size-xs);
+  color: var(--sv-color-text-primary);
+  font-family: var(--sv-font-family);
+  pointer-events: none;
+  opacity: 0;
+  transition: opacity 0.1s ease;
+}
+
+.wrapper:hover .tip,
+.wrapper:focus-within .tip {
+  opacity: 1;
+}
+
+/* Placement */
+.top {
+  bottom: calc(100% + var(--sv-space-2));
+  left: 50%;
+  transform: translateX(-50%);
+}
+
+.bottom {
+  top: calc(100% + var(--sv-space-2));
+  left: 50%;
+  transform: translateX(-50%);
+}
+
+.left {
+  right: calc(100% + var(--sv-space-2));
+  top: 50%;
+  transform: translateY(-50%);
+}
+
+.right {
+  left: calc(100% + var(--sv-space-2));
+  top: 50%;
+  transform: translateY(-50%);
+}

package/src/components/Tooltip/Tooltip.tsx

@@ -0,0 +1,30 @@
+import type { ReactElement } from 'react';
+import { useId } from 'react';
+import styles from './Tooltip.module.css';
+
+export interface TooltipProps {
+  content: string;
+  children: ReactElement;
+  side?: 'top' | 'bottom' | 'left' | 'right';
+}
+
+const sideClass: Record<NonNullable<TooltipProps['side']>, string> = {
+  top: styles.top as string,
+  bottom: styles.bottom as string,
+  left: styles.left as string,
+  right: styles.right as string,
+};
+
+export function Tooltip({ content, children, side = 'top' }: TooltipProps) {
+  const tipId = useId();
+
+  return (
+    <span className={styles.wrapper}>
+      {/* aria-describedby wires the tooltip text to the trigger for screen readers */}
+      <span aria-describedby={tipId}>{children}</span>
+      <span id={tipId} role="tooltip" className={[styles.tip, sideClass[side]].join(' ')}>
+        {content}
+      </span>
+    </span>
+  );
+}

package/src/css-modules.d.ts

@@ -0,0 +1,4 @@
+declare module '*.module.css' {
+  const classes: Readonly<Record<string, string>>;
+  export default classes;
+}

package/src/index.ts

@@ -0,0 +1,45 @@
+export { Badge } from './components/Badge/Badge';
+export type { BadgeProps, BadgeVariant, BadgeStatus } from './components/Badge/Badge';
+export { Icon } from './components/Icon/Icon';
+export { Toggle } from './components/Toggle/Toggle';
+export type { ToggleProps } from './components/Toggle/Toggle';
+export { SegmentedControl } from './components/SegmentedControl/SegmentedControl';
+export type {
+  SegmentedControlProps,
+  SegmentedOption,
+} from './components/SegmentedControl/SegmentedControl';
+export { Tabs } from './components/Tabs/Tabs';
+export type { TabsProps, TabItem } from './components/Tabs/Tabs';
+export { Select } from './components/Select/Select';
+export type { SelectProps } from './components/Select/Select';
+export { SystemBanner } from './components/SystemBanner/SystemBanner';
+export type { SystemBannerProps, BannerVariant } from './components/SystemBanner/SystemBanner';
+export { Popover } from './components/Popover/Popover';
+export type { PopoverProps } from './components/Popover/Popover';
+export type { IconProps, IconName } from './components/Icon/Icon';
+export { Button } from './components/Button/Button';
+export type { ButtonProps, ButtonVariant, ButtonSize } from './components/Button/Button';
+export { Input } from './components/Input/Input';
+export type { InputProps } from './components/Input/Input';
+export { Dialog } from './components/Dialog/Dialog';
+export type { DialogProps, DialogSize } from './components/Dialog/Dialog';
+export { Drawer } from './components/Drawer/Drawer';
+export type { DrawerProps } from './components/Drawer/Drawer';
+export { ToastProvider, useToast } from './components/Toast/Toast';
+export type { ToastItem, ToastContextValue } from './components/Toast/Toast';
+export { Card } from './components/Card/Card';
+export type { CardProps } from './components/Card/Card';
+export { FormField } from './components/FormField/FormField';
+export type { FormFieldProps } from './components/FormField/FormField';
+export { PageHeader } from './components/PageHeader/PageHeader';
+export type { PageHeaderProps } from './components/PageHeader/PageHeader';
+export { EmptyState } from './components/EmptyState/EmptyState';
+export type { EmptyStateProps } from './components/EmptyState/EmptyState';
+export { Spinner } from './components/Spinner/Spinner';
+export type { SpinnerProps } from './components/Spinner/Spinner';
+export { Avatar } from './components/Avatar/Avatar';
+export type { AvatarProps } from './components/Avatar/Avatar';
+export { NavTabs } from './components/NavTabs/NavTabs';
+export type { NavTabsProps, NavTabItem } from './components/NavTabs/NavTabs';
+export { Tooltip } from './components/Tooltip/Tooltip';
+export type { TooltipProps } from './components/Tooltip/Tooltip';

package/src/stories/Avatar.stories.tsx

@@ -0,0 +1,44 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { Avatar } from '../components/Avatar/Avatar';
+
+const meta = {
+  title: 'Components/Avatar',
+  component: Avatar,
+  parameters: { layout: 'centered' },
+} satisfies Meta<typeof Avatar>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Initials: Story = {
+  args: { name: 'Jane Smith' },
+};
+
+export const SingleName: Story = {
+  args: { name: 'Admin' },
+};
+
+export const WithImage: Story = {
+  args: {
+    name: 'Jane Smith',
+    src: 'https://i.pravatar.cc/150?u=jane',
+  },
+};
+
+export const BrokenImage: Story = {
+  args: {
+    name: 'Jane Smith',
+    src: 'https://broken.invalid/avatar.png',
+  },
+};
+
+export const AllSizes: Story = {
+  args: { name: 'Jane Smith' },
+  render: () => (
+    <div style={{ display: 'flex', alignItems: 'center', gap: 12 }}>
+      <Avatar name="Jane Smith" size="sm" />
+      <Avatar name="Jane Smith" size="md" />
+      <Avatar name="Jane Smith" size="lg" />
+    </div>
+  ),
+};

package/src/stories/Card.stories.tsx

@@ -0,0 +1,35 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { Card } from '../components/Card/Card';
+
+const meta = {
+  title: 'Components/Card',
+  component: Card,
+  parameters: { layout: 'padded' },
+  args: { children: 'Card content goes here.' },
+} satisfies Meta<typeof Card>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {};
+
+export const SmallPadding: Story = { args: { padding: 'sm' } };
+export const LargePadding: Story = { args: { padding: 'lg' } };
+
+export const Interactive: Story = {
+  args: {
+    as: 'article',
+    interactive: true,
+    children: 'Click me — I have hover + focus styles.',
+  },
+};
+
+export const AsListItem: Story = {
+  render: () => (
+    <ul style={{ listStyle: 'none', padding: 0, display: 'flex', flexDirection: 'column', gap: 8 }}>
+      <Card as="li">First item</Card>
+      <Card as="li">Second item</Card>
+      <Card as="li">Third item</Card>
+    </ul>
+  ),
+};