@sovereignfs/ui 0.41.0 → 0.45.0

package/src/components/Combobox/Combobox.tsx

@@ -0,0 +1,186 @@
+'use client';
+
+import { useEffect, useId, useMemo, useRef, useState } from 'react';
+import type { KeyboardEvent as ReactKeyboardEvent } from 'react';
+import { useIsMobile } from '../../hooks';
+import { Drawer } from '../Drawer/Drawer';
+import { Icon } from '../Icon/Icon';
+import { Popover } from '../Popover/Popover';
+import styles from './Combobox.module.css';
+
+export interface ComboboxOption {
+  value: string;
+  label: string;
+}
+
+export interface ComboboxProps {
+  options: ComboboxOption[];
+  value: string | null;
+  onChange: (value: string) => void;
+  placeholder?: string;
+  searchPlaceholder?: string;
+  emptyMessage?: string;
+  'aria-label': string;
+  disabled?: boolean;
+  className?: string;
+}
+
+function matches(option: ComboboxOption, query: string): boolean {
+  if (!query) return true;
+  return option.label.toLowerCase().includes(query.toLowerCase());
+}
+
+/**
+ * Combobox — a searchable single-select: `Popover` on desktop, a bottom-sheet
+ * `Drawer` on mobile (the platform's standard adaptive-surface pattern,
+ * matching `Menu` and `DatePicker`). For a fixed, short option list where
+ * search adds no value, use `Select`'s native `<select>` instead — this is
+ * for option lists long enough that typing to filter beats scanning.
+ *
+ * The trigger is built in, like `DatePicker` — a combobox is a form field,
+ * not an arbitrary action-menu trigger.
+ */
+export function Combobox({
+  options,
+  value,
+  onChange,
+  placeholder = 'Select…',
+  searchPlaceholder = 'Search…',
+  emptyMessage = 'No matches.',
+  'aria-label': ariaLabel,
+  disabled = false,
+  className,
+}: ComboboxProps) {
+  const [open, setOpen] = useState(false);
+  const [query, setQuery] = useState('');
+  const [highlightedIndex, setHighlightedIndex] = useState(0);
+  const isMobile = useIsMobile();
+  const inputRef = useRef<HTMLInputElement>(null);
+  const listId = useId();
+
+  const selected = options.find((o) => o.value === value) ?? null;
+  const filtered = useMemo(
+    () => options.filter((option) => matches(option, query)),
+    [options, query],
+  );
+
+  useEffect(() => {
+    setHighlightedIndex(0);
+  }, [query, open]);
+
+  useEffect(() => {
+    if (open) {
+      setQuery('');
+      requestAnimationFrame(() => inputRef.current?.focus());
+    }
+  }, [open]);
+
+  function commit(option: ComboboxOption) {
+    onChange(option.value);
+    setOpen(false);
+  }
+
+  function handleKeyDown(e: ReactKeyboardEvent<HTMLInputElement>) {
+    if (e.key === 'ArrowDown') {
+      e.preventDefault();
+      setHighlightedIndex((i) => Math.min(i + 1, filtered.length - 1));
+    } else if (e.key === 'ArrowUp') {
+      e.preventDefault();
+      setHighlightedIndex((i) => Math.max(i - 1, 0));
+    } else if (e.key === 'Enter') {
+      e.preventDefault();
+      const option = filtered[highlightedIndex];
+      if (option) commit(option);
+    }
+  }
+
+  const highlightedId = filtered[highlightedIndex]
+    ? `${listId}-${filtered[highlightedIndex].value}`
+    : undefined;
+
+  const trigger = (
+    <button
+      type="button"
+      className={[styles.trigger, className].filter(Boolean).join(' ')}
+      disabled={disabled}
+      aria-label={ariaLabel}
+      aria-haspopup="listbox"
+      aria-expanded={open}
+      onClick={() => setOpen((o) => !o)}
+    >
+      <span className={selected ? styles.triggerValue : styles.triggerPlaceholder}>
+        {selected ? selected.label : placeholder}
+      </span>
+      <Icon name="chevron-down" size="sm" aria-hidden />
+    </button>
+  );
+
+  const body = (
+    <div className={styles.body}>
+      <input
+        ref={inputRef}
+        type="text"
+        role="combobox"
+        aria-expanded={filtered.length > 0}
+        aria-controls={listId}
+        aria-activedescendant={highlightedId}
+        aria-autocomplete="list"
+        className={styles.search}
+        placeholder={searchPlaceholder}
+        value={query}
+        onChange={(e) => setQuery(e.target.value)}
+        onKeyDown={handleKeyDown}
+      />
+      <ul id={listId} role="listbox" className={styles.list}>
+        {filtered.length === 0 && <li className={styles.empty}>{emptyMessage}</li>}
+        {filtered.map((option, index) => {
+          const isHighlighted = index === highlightedIndex;
+          const isSelected = option.value === value;
+          return (
+            <li key={option.value}>
+              <button
+                id={`${listId}-${option.value}`}
+                type="button"
+                role="option"
+                aria-selected={isSelected}
+                className={[styles.option, isHighlighted ? styles.optionHighlighted : '']
+                  .filter(Boolean)
+                  .join(' ')}
+                onMouseEnter={() => setHighlightedIndex(index)}
+                onClick={() => commit(option)}
+              >
+                <span className={styles.check}>
+                  {isSelected && <Icon name="check" size="sm" aria-hidden />}
+                </span>
+                {option.label}
+              </button>
+            </li>
+          );
+        })}
+      </ul>
+    </div>
+  );
+
+  if (isMobile) {
+    return (
+      <>
+        {trigger}
+        <Drawer open={open} onClose={() => setOpen(false)} aria-label={ariaLabel}>
+          {body}
+        </Drawer>
+      </>
+    );
+  }
+
+  return (
+    <Popover
+      trigger={trigger}
+      open={open}
+      onClose={() => setOpen(false)}
+      aria-label={ariaLabel}
+      width="trigger"
+    >
+      {body}
+    </Popover>
+  );
+}

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

@@ -0,0 +1,158 @@
+// @vitest-environment jsdom
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { cleanup, fireEvent, render, screen } from '@testing-library/react';
+import { Combobox, type ComboboxOption } from '../Combobox';
+
+let mobile = false;
+function installMatchMedia() {
+  vi.stubGlobal(
+    'matchMedia',
+    vi.fn().mockImplementation((query: string) => ({
+      // useIsMobile's query is '(max-width: ...)'; Drawer's own
+      // prefers-reduced-motion check defaults to false — see DatePicker's
+      // identical test setup for why.
+      matches: query.includes('max-width') ? mobile : false,
+      media: query,
+      addEventListener: vi.fn(),
+      removeEventListener: vi.fn(),
+      addListener: vi.fn(),
+      removeListener: vi.fn(),
+      dispatchEvent: vi.fn(),
+    })),
+  );
+}
+
+const options: ComboboxOption[] = [
+  { value: 'tasks', label: 'sovereign-tasks' },
+  { value: 'ledger', label: 'sovereign-ledger' },
+  { value: 'shopper', label: 'sovereign-shopper' },
+];
+
+// Popover's width="trigger" mode observes the trigger's size via
+// ResizeObserver, which jsdom does not implement.
+class MockResizeObserver {
+  observe() {}
+  unobserve() {}
+  disconnect() {}
+}
+
+describe('Combobox', () => {
+  beforeEach(() => {
+    mobile = false;
+    installMatchMedia();
+    vi.stubGlobal('ResizeObserver', MockResizeObserver);
+  });
+  afterEach(() => {
+    vi.unstubAllGlobals();
+    cleanup();
+  });
+
+  it('shows the placeholder when nothing is selected', () => {
+    render(
+      <Combobox
+        options={options}
+        value={null}
+        onChange={() => {}}
+        placeholder="Pick a plugin"
+        aria-label="Plugin"
+      />,
+    );
+    expect(screen.getByRole('button', { name: 'Plugin' }).textContent).toContain('Pick a plugin');
+  });
+
+  it('shows the selected option label', () => {
+    render(<Combobox options={options} value="ledger" onChange={() => {}} aria-label="Plugin" />);
+    expect(screen.getByRole('button', { name: 'Plugin' }).textContent).toContain(
+      'sovereign-ledger',
+    );
+  });
+
+  it('opens as a Popover on desktop', () => {
+    render(<Combobox options={options} value={null} onChange={() => {}} aria-label="Plugin" />);
+    fireEvent.click(screen.getByRole('button', { name: 'Plugin' }));
+    const panel = screen.getByRole('dialog', { name: 'Plugin' });
+    expect(panel.getAttribute('aria-modal')).toBe('false');
+    expect(screen.getAllByRole('option')).toHaveLength(3);
+  });
+
+  it('opens as a Drawer on mobile', () => {
+    mobile = true;
+    installMatchMedia();
+    render(<Combobox options={options} value={null} onChange={() => {}} aria-label="Plugin" />);
+    fireEvent.click(screen.getByRole('button', { name: 'Plugin' }));
+    const panel = screen.getByRole('dialog', { name: 'Plugin' });
+    expect(panel.getAttribute('aria-modal')).toBe('true');
+    expect(screen.getAllByRole('option')).toHaveLength(3);
+  });
+
+  it('filters options by label', () => {
+    render(<Combobox options={options} value={null} onChange={() => {}} aria-label="Plugin" />);
+    fireEvent.click(screen.getByRole('button', { name: 'Plugin' }));
+    fireEvent.change(screen.getByRole('combobox'), { target: { value: 'led' } });
+    expect(screen.getAllByRole('option')).toHaveLength(1);
+    expect(screen.getByRole('option', { name: 'sovereign-ledger' })).toBeDefined();
+  });
+
+  it('shows an empty message when nothing matches', () => {
+    render(
+      <Combobox
+        options={options}
+        value={null}
+        onChange={() => {}}
+        aria-label="Plugin"
+        emptyMessage="No plugins"
+      />,
+    );
+    fireEvent.click(screen.getByRole('button', { name: 'Plugin' }));
+    fireEvent.change(screen.getByRole('combobox'), { target: { value: 'zzz' } });
+    expect(screen.queryAllByRole('option')).toHaveLength(0);
+    expect(screen.getByText('No plugins')).toBeDefined();
+  });
+
+  it('marks the currently selected option with aria-selected', () => {
+    render(<Combobox options={options} value="shopper" onChange={() => {}} aria-label="Plugin" />);
+    fireEvent.click(screen.getByRole('button', { name: 'Plugin' }));
+    expect(
+      screen.getByRole('option', { name: 'sovereign-shopper' }).getAttribute('aria-selected'),
+    ).toBe('true');
+    expect(
+      screen.getByRole('option', { name: 'sovereign-tasks' }).getAttribute('aria-selected'),
+    ).toBe('false');
+  });
+
+  it('clicking an option calls onChange with its value and closes', () => {
+    const onChange = vi.fn();
+    render(<Combobox options={options} value={null} onChange={onChange} aria-label="Plugin" />);
+    fireEvent.click(screen.getByRole('button', { name: 'Plugin' }));
+    fireEvent.click(screen.getByRole('option', { name: 'sovereign-ledger' }));
+    expect(onChange).toHaveBeenCalledWith('ledger');
+    expect(screen.queryByRole('listbox')).toBeNull();
+  });
+
+  it('Enter selects the highlighted option', () => {
+    const onChange = vi.fn();
+    render(<Combobox options={options} value={null} onChange={onChange} aria-label="Plugin" />);
+    fireEvent.click(screen.getByRole('button', { name: 'Plugin' }));
+    fireEvent.keyDown(screen.getByRole('combobox'), { key: 'Enter' });
+    expect(onChange).toHaveBeenCalledWith('tasks');
+  });
+
+  it('ArrowDown moves the highlighted option before Enter selects it', () => {
+    const onChange = vi.fn();
+    render(<Combobox options={options} value={null} onChange={onChange} aria-label="Plugin" />);
+    fireEvent.click(screen.getByRole('button', { name: 'Plugin' }));
+    const input = screen.getByRole('combobox');
+    fireEvent.keyDown(input, { key: 'ArrowDown' });
+    fireEvent.keyDown(input, { key: 'Enter' });
+    expect(onChange).toHaveBeenCalledWith('ledger');
+  });
+
+  it('disables the trigger when disabled', () => {
+    render(
+      <Combobox options={options} value={null} onChange={() => {}} aria-label="Plugin" disabled />,
+    );
+    expect((screen.getByRole('button', { name: 'Plugin' }) as HTMLButtonElement).disabled).toBe(
+      true,
+    );
+  });
+});

package/src/components/Command/Command.module.css

@@ -0,0 +1,80 @@
+/* Command — rendered inside Dialog's own panel/scroll chrome; this file only
+ * owns the search input and the filtered result list beneath it. */
+
+.root {
+  display: flex;
+  flex-direction: column;
+  /* Panel content area is otherwise unbounded; cap so a long result list
+     scrolls internally instead of growing the dialog indefinitely. */
+  max-height: min(60vh, 420px);
+}
+
+.input {
+  flex-shrink: 0;
+  width: 100%;
+  border: none;
+  border-bottom: 1px solid var(--sv-color-border);
+  background: transparent;
+  color: var(--sv-color-text-primary);
+  font: inherit;
+  font-size: var(--sv-font-size-md);
+  padding: var(--sv-space-3);
+}
+
+.input:focus {
+  outline: none;
+}
+
+.input::placeholder {
+  color: var(--sv-color-text-muted);
+}
+
+.list {
+  list-style: none;
+  margin: 0;
+  padding: var(--sv-space-1);
+  overflow-y: auto;
+}
+
+.groupList {
+  list-style: none;
+  margin: 0;
+  padding: 0;
+}
+
+.groupLabel {
+  padding: var(--sv-space-2) var(--sv-space-3) var(--sv-space-1);
+  font-size: var(--sv-font-size-label);
+  font-weight: var(--sv-font-weight-semibold);
+  color: var(--sv-color-text-muted);
+  text-transform: uppercase;
+  letter-spacing: 0.04em;
+}
+
+.item {
+  display: flex;
+  align-items: center;
+  gap: var(--sv-space-2);
+  width: 100%;
+  min-height: var(--sv-touch-target-min, 44px);
+  padding: var(--sv-space-2) var(--sv-space-3);
+  border: none;
+  border-radius: var(--sv-radius-sm);
+  background: transparent;
+  color: var(--sv-color-text-primary);
+  font: inherit;
+  font-size: var(--sv-font-size-sm);
+  text-align: left;
+  cursor: pointer;
+}
+
+.itemHighlighted {
+  background: var(--sv-color-surface-sunken);
+}
+
+.empty {
+  padding: var(--sv-space-4) var(--sv-space-3);
+  color: var(--sv-color-text-muted);
+  font-size: var(--sv-font-size-sm);
+  text-align: center;
+}

package/src/components/Command/Command.stories.tsx

@@ -0,0 +1,104 @@
+import { useState } from 'react';
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { Command } from './Command';
+import { Button } from '../Button/Button';
+
+const meta = {
+  title: 'Components/Command',
+  component: Command,
+  parameters: {
+    layout: 'padded',
+    docs: {
+      description: {
+        component:
+          '⌘K-style command palette. Opened via Dialog, which supplies the modal shell — this adds the search input, substring filtering, and arrow-key/Enter selection on top of it. Controlled: the consumer owns the open state and any global shortcut listener that flips it.',
+      },
+    },
+  },
+  args: { open: false, onClose: () => {}, items: [] },
+} satisfies Meta<typeof Command>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+// ---------------------------------------------------------------------------
+
+function CommandDemo() {
+  const [open, setOpen] = useState(false);
+  const [lastSelected, setLastSelected] = useState<string | null>(null);
+
+  return (
+    <div>
+      <Button onClick={() => setOpen(true)}>Open command palette</Button>
+      {lastSelected && (
+        <p
+          style={{
+            marginTop: 'var(--sv-space-3)',
+            fontSize: 14,
+            color: 'var(--sv-color-text-muted)',
+          }}
+        >
+          Last selected: {lastSelected}
+        </p>
+      )}
+      <Command
+        open={open}
+        onClose={() => setOpen(false)}
+        aria-label="Command palette"
+        items={[
+          {
+            id: 'new',
+            label: 'New conversation',
+            group: 'Actions',
+            icon: 'plus',
+            onSelect: () => setLastSelected('New conversation'),
+          },
+          {
+            id: 'export',
+            label: 'Export chat',
+            group: 'Actions',
+            icon: 'upload',
+            keywords: 'download save',
+            onSelect: () => setLastSelected('Export chat'),
+          },
+          {
+            id: 'profile',
+            label: 'Go to profile',
+            group: 'Navigation',
+            icon: 'user',
+            onSelect: () => setLastSelected('Go to profile'),
+          },
+          {
+            id: 'settings',
+            label: 'Open settings',
+            group: 'Navigation',
+            icon: 'settings',
+            onSelect: () => setLastSelected('Open settings'),
+          },
+        ]}
+      />
+    </div>
+  );
+}
+
+export const Default: Story = {
+  render: () => <CommandDemo />,
+};
+
+export const OpenWithNoResults: Story = {
+  render: () => {
+    function Demo() {
+      const [open, setOpen] = useState(true);
+      return (
+        <Command
+          open={open}
+          onClose={() => setOpen(false)}
+          aria-label="Command palette"
+          placeholder="Try typing something with no matches…"
+          items={[{ id: 'a', label: 'Alpha', onSelect: () => {} }]}
+        />
+      );
+    }
+    return <Demo />;
+  },
+};

package/src/components/Command/Command.tsx

@@ -0,0 +1,168 @@
+'use client';
+
+import { useEffect, useId, useMemo, useRef, useState } from 'react';
+import type { KeyboardEvent as ReactKeyboardEvent } from 'react';
+import { Dialog } from '../Dialog/Dialog';
+import { Icon, type IconName } from '../Icon/Icon';
+import styles from './Command.module.css';
+
+export interface CommandItem {
+  id: string;
+  label: string;
+  onSelect: () => void;
+  icon?: IconName;
+  /** Section header this item is grouped under. */
+  group?: string;
+  /** Extra searchable text beyond the label (keywords, description). */
+  keywords?: string;
+}
+
+export interface CommandProps {
+  open: boolean;
+  onClose: () => void;
+  items: CommandItem[];
+  placeholder?: string;
+  'aria-label'?: string;
+}
+
+/** Case-insensitive substring match against label + keywords. Not a scored
+ * fuzzy matcher — a real fuzzy-match algorithm is a meaningfully bigger
+ * undertaking than this primitive needs until a consumer's command list
+ * is large enough that substring filtering stops being good enough. */
+function matches(item: CommandItem, query: string): boolean {
+  if (!query) return true;
+  const haystack = `${item.label} ${item.keywords ?? ''}`.toLowerCase();
+  return haystack.includes(query.toLowerCase());
+}
+
+/**
+ * Command — a ⌘K-style palette. Opened via `Dialog`, which supplies the
+ * modal shell (scrim, panel, mobile full-screen sheet, focus handling) —
+ * this only adds the search input, filtering, and arrow-key/Enter
+ * selection on top of it. Controlled (`open`/`onClose`): the consumer wires
+ * up their own global shortcut listener to flip `open` — a DS primitive
+ * shouldn't own a document-level keydown listener itself.
+ */
+export function Command({
+  open,
+  onClose,
+  items,
+  placeholder = 'Type a command…',
+  'aria-label': ariaLabel = 'Command palette',
+}: CommandProps) {
+  const [query, setQuery] = useState('');
+  const [highlightedIndex, setHighlightedIndex] = useState(0);
+  const inputRef = useRef<HTMLInputElement>(null);
+  const listId = useId();
+
+  const filtered = useMemo(() => items.filter((item) => matches(item, query)), [items, query]);
+
+  // Reset on every open, and whenever the query narrows/widens the result
+  // set — the top match should always be the one Enter would select.
+  useEffect(() => {
+    setHighlightedIndex(0);
+  }, [query, open]);
+
+  useEffect(() => {
+    if (open) {
+      setQuery('');
+      // Dialog mounts its content in the same tick it flips `open`; focus
+      // needs the next paint to land on an element that actually exists.
+      requestAnimationFrame(() => inputRef.current?.focus());
+    }
+  }, [open]);
+
+  function handleKeyDown(e: ReactKeyboardEvent<HTMLInputElement>) {
+    if (e.key === 'ArrowDown') {
+      e.preventDefault();
+      setHighlightedIndex((i) => Math.min(i + 1, filtered.length - 1));
+    } else if (e.key === 'ArrowUp') {
+      e.preventDefault();
+      setHighlightedIndex((i) => Math.max(i - 1, 0));
+    } else if (e.key === 'Enter') {
+      e.preventDefault();
+      const item = filtered[highlightedIndex];
+      if (item) {
+        onClose();
+        item.onSelect();
+      }
+    }
+  }
+
+  // Group items in their original order, without moving an item's position
+  // relative to its own group even if groups aren't contiguous in `items`.
+  const groups = useMemo(() => {
+    const order: (string | undefined)[] = [];
+    const byGroup = new Map<string | undefined, CommandItem[]>();
+    for (const item of filtered) {
+      let bucket = byGroup.get(item.group);
+      if (!bucket) {
+        bucket = [];
+        order.push(item.group);
+        byGroup.set(item.group, bucket);
+      }
+      bucket.push(item);
+    }
+    return order.map((group) => ({ group, items: byGroup.get(group) ?? [] }));
+  }, [filtered]);
+
+  const highlightedId = filtered[highlightedIndex]
+    ? `${listId}-${filtered[highlightedIndex].id}`
+    : undefined;
+
+  return (
+    <Dialog open={open} onClose={onClose} aria-label={ariaLabel} size="sm">
+      <div className={styles.root}>
+        <input
+          ref={inputRef}
+          type="text"
+          role="combobox"
+          aria-expanded={filtered.length > 0}
+          aria-controls={listId}
+          aria-activedescendant={highlightedId}
+          aria-autocomplete="list"
+          className={styles.input}
+          placeholder={placeholder}
+          value={query}
+          onChange={(e) => setQuery(e.target.value)}
+          onKeyDown={handleKeyDown}
+        />
+        <ul id={listId} role="listbox" className={styles.list}>
+          {filtered.length === 0 && <li className={styles.empty}>No matching commands.</li>}
+          {groups.map(({ group, items: groupItems }) => (
+            <li key={group ?? '__ungrouped'}>
+              {group && <div className={styles.groupLabel}>{group}</div>}
+              <ul className={styles.groupList}>
+                {groupItems.map((item) => {
+                  const index = filtered.indexOf(item);
+                  const isHighlighted = index === highlightedIndex;
+                  return (
+                    <li key={item.id}>
+                      <button
+                        id={`${listId}-${item.id}`}
+                        type="button"
+                        role="option"
+                        aria-selected={isHighlighted}
+                        className={[styles.item, isHighlighted ? styles.itemHighlighted : '']
+                          .filter(Boolean)
+                          .join(' ')}
+                        onMouseEnter={() => setHighlightedIndex(index)}
+                        onClick={() => {
+                          onClose();
+                          item.onSelect();
+                        }}
+                      >
+                        {item.icon && <Icon name={item.icon} size="sm" aria-hidden />}
+                        {item.label}
+                      </button>
+                    </li>
+                  );
+                })}
+              </ul>
+            </li>
+          ))}
+        </ul>
+      </div>
+    </Dialog>
+  );
+}