@sovereignfs/ui 0.41.0 → 0.45.0

package/src/components/Item/Item.module.css

@@ -0,0 +1,70 @@
+.root {
+  display: flex;
+  align-items: center;
+  gap: var(--sv-space-3);
+  width: 100%;
+  padding: var(--sv-space-3);
+  border: none;
+  border-radius: var(--sv-radius-md);
+  background: transparent;
+  text-align: left;
+  font-family: var(--sv-font-family);
+  color: inherit;
+}
+
+.interactive {
+  cursor: pointer;
+}
+
+@media (hover: hover) {
+  .interactive:not(:disabled):hover {
+    background: var(--sv-color-surface-sunken);
+  }
+}
+
+.interactive:focus-visible {
+  outline: 2px solid var(--sv-color-focus-ring);
+  outline-offset: -2px;
+}
+
+.interactive:disabled {
+  opacity: 0.5;
+  cursor: not-allowed;
+}
+
+@media (pointer: coarse) {
+  .root {
+    min-height: var(--sv-touch-target-min, 44px);
+  }
+}
+
+.leading,
+.trailing {
+  flex-shrink: 0;
+  display: flex;
+  align-items: center;
+}
+
+.content {
+  display: flex;
+  flex-direction: column;
+  min-width: 0;
+  flex: 1;
+}
+
+.title {
+  font-size: var(--sv-font-size-sm);
+  font-weight: var(--sv-font-weight-medium);
+  color: var(--sv-color-text-primary);
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.description {
+  font-size: var(--sv-font-size-caption);
+  color: var(--sv-color-text-muted);
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}

package/src/components/Item/Item.stories.tsx

@@ -0,0 +1,62 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { Item } from './Item';
+import { Icon } from '../Icon/Icon';
+
+const meta = {
+  title: 'Components/Item',
+  component: Item,
+  parameters: { layout: 'padded' },
+  args: {
+    title: 'Notifications',
+  },
+} satisfies Meta<typeof Item>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+// ---------------------------------------------------------------------------
+
+export const Default: Story = {};
+
+export const WithDescription: Story = {
+  args: { description: 'Manage email and push alerts' },
+};
+
+export const Interactive: Story = {
+  args: {
+    description: 'Manage email and push alerts',
+    leading: <Icon name="bell" aria-hidden />,
+    trailing: <Icon name="chevron-right" size="sm" aria-hidden />,
+    onClick: () => {},
+  },
+};
+
+export const Disabled: Story = {
+  args: {
+    description: 'Requires admin role',
+    onClick: () => {},
+    disabled: true,
+  },
+};
+
+export const List: Story = {
+  render: () => (
+    <div style={{ display: 'flex', flexDirection: 'column', gap: 2 }}>
+      <Item
+        title="Notifications"
+        description="Manage email and push alerts"
+        leading={<Icon name="bell" aria-hidden />}
+        trailing={<Icon name="chevron-right" size="sm" aria-hidden />}
+        onClick={() => {}}
+      />
+      <Item
+        title="Privacy"
+        description="Control what others can see"
+        leading={<Icon name="shield" aria-hidden />}
+        trailing={<Icon name="chevron-right" size="sm" aria-hidden />}
+        onClick={() => {}}
+      />
+      <Item title="Sign out" leading={<Icon name="log-out" aria-hidden />} onClick={() => {}} />
+    </div>
+  ),
+};

package/src/components/Item/Item.tsx

@@ -0,0 +1,54 @@
+import type { ReactNode } from 'react';
+import styles from './Item.module.css';
+
+export interface ItemProps {
+  leading?: ReactNode;
+  title: ReactNode;
+  description?: ReactNode;
+  trailing?: ReactNode;
+  /** Renders as a button when given; a plain row otherwise. */
+  onClick?: () => void;
+  disabled?: boolean;
+  className?: string;
+}
+
+/**
+ * Item — generic row primitive: leading slot, title + optional description,
+ * trailing slot. The building block for settings rows, list rows, and
+ * menu-adjacent rows that don't fit `Menu`'s own item shape.
+ */
+export function Item({
+  leading,
+  title,
+  description,
+  trailing,
+  onClick,
+  disabled,
+  className,
+}: ItemProps) {
+  const interactive = Boolean(onClick);
+  const classes = [styles.root, interactive ? styles.interactive : '', className]
+    .filter(Boolean)
+    .join(' ');
+
+  const content = (
+    <>
+      {leading && <span className={styles.leading}>{leading}</span>}
+      <span className={styles.content}>
+        <span className={styles.title}>{title}</span>
+        {description && <span className={styles.description}>{description}</span>}
+      </span>
+      {trailing && <span className={styles.trailing}>{trailing}</span>}
+    </>
+  );
+
+  if (interactive) {
+    return (
+      <button type="button" onClick={onClick} disabled={disabled} className={classes}>
+        {content}
+      </button>
+    );
+  }
+
+  return <div className={classes}>{content}</div>;
+}

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

@@ -0,0 +1,39 @@
+// @vitest-environment jsdom
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { cleanup, render, screen, fireEvent } from '@testing-library/react';
+import { Item } from '../Item';
+
+afterEach(cleanup);
+
+describe('Item', () => {
+  it('renders as a plain row when no onClick is given', () => {
+    render(<Item title="Notifications" description="Manage email and push alerts" />);
+    expect(screen.queryByRole('button')).toBeNull();
+    expect(screen.getByText('Notifications')).toBeDefined();
+    expect(screen.getByText('Manage email and push alerts')).toBeDefined();
+  });
+
+  it('renders as a button and fires onClick when given', () => {
+    const onClick = vi.fn();
+    render(<Item title="Notifications" onClick={onClick} />);
+    fireEvent.click(screen.getByRole('button', { name: 'Notifications' }));
+    expect(onClick).toHaveBeenCalled();
+  });
+
+  it('renders leading and trailing slots', () => {
+    render(
+      <Item
+        title="Notifications"
+        leading={<span data-testid="leading">icon</span>}
+        trailing={<span data-testid="trailing">chevron</span>}
+      />,
+    );
+    expect(screen.getByTestId('leading')).toBeDefined();
+    expect(screen.getByTestId('trailing')).toBeDefined();
+  });
+
+  it('disables the button when disabled is set', () => {
+    render(<Item title="Notifications" onClick={() => {}} disabled />);
+    expect(screen.getByRole('button')).toHaveProperty('disabled', true);
+  });
+});

package/src/components/Kbd/Kbd.module.css

@@ -0,0 +1,14 @@
+.kbd {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  min-width: 1.5em;
+  padding: var(--sv-space-1) var(--sv-space-2);
+  border: 1px solid var(--sv-color-border-strong);
+  border-radius: var(--sv-radius-sm);
+  background: var(--sv-color-surface-sunken);
+  color: var(--sv-color-text-primary);
+  font-family: var(--sv-font-family-mono);
+  font-size: var(--sv-font-size-xs);
+  line-height: 1;
+}

package/src/components/Kbd/Kbd.stories.tsx

@@ -0,0 +1,32 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { Kbd } from './Kbd';
+
+const meta = {
+  title: 'Components/Kbd',
+  component: Kbd,
+  parameters: { layout: 'padded' },
+  args: { children: '⌘K' },
+} satisfies Meta<typeof Kbd>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+// ---------------------------------------------------------------------------
+
+export const Default: Story = {};
+
+export const Letter: Story = {
+  args: { children: 'S' },
+};
+
+export const Sequence: Story = {
+  render: () => (
+    <span style={{ display: 'inline-flex', alignItems: 'center', gap: 4 }}>
+      <Kbd>Ctrl</Kbd>
+      <span>+</span>
+      <Kbd>Shift</Kbd>
+      <span>+</span>
+      <Kbd>P</Kbd>
+    </span>
+  ),
+};

package/src/components/Kbd/Kbd.tsx

@@ -0,0 +1,12 @@
+import type { ReactNode } from 'react';
+import styles from './Kbd.module.css';
+
+export interface KbdProps {
+  children: ReactNode;
+  className?: string;
+}
+
+/** Kbd — inline keyboard-key styling. Renders a real `<kbd>` element. */
+export function Kbd({ children, className }: KbdProps) {
+  return <kbd className={[styles.kbd, className].filter(Boolean).join(' ')}>{children}</kbd>;
+}

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

@@ -0,0 +1,14 @@
+// @vitest-environment jsdom
+import { afterEach, describe, expect, it } from 'vitest';
+import { cleanup, render, screen } from '@testing-library/react';
+import { Kbd } from '../Kbd';
+
+afterEach(cleanup);
+
+describe('Kbd', () => {
+  it('renders a real <kbd> element', () => {
+    render(<Kbd>⌘K</Kbd>);
+    const el = screen.getByText('⌘K');
+    expect(el.tagName).toBe('KBD');
+  });
+});

package/src/components/Label/Label.module.css

@@ -0,0 +1,11 @@
+.label {
+  font-size: var(--sv-font-size-sm);
+  font-weight: var(--sv-font-weight-medium);
+  color: var(--sv-color-text-primary);
+  cursor: default;
+}
+
+.disabled {
+  opacity: 0.5;
+  cursor: not-allowed;
+}

package/src/components/Label/Label.stories.tsx

@@ -0,0 +1,40 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { Label } from './Label';
+
+const meta = {
+  title: 'Components/Label',
+  component: Label,
+  parameters: { layout: 'padded' },
+  args: { children: 'Label text' },
+} satisfies Meta<typeof Label>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+// ---------------------------------------------------------------------------
+
+export const Default: Story = {};
+
+export const Disabled: Story = {
+  args: { disabled: true },
+};
+
+export const WithControl: Story = {
+  render: () => (
+    <div style={{ display: 'flex', flexDirection: 'column', gap: 4 }}>
+      <Label htmlFor="example-input">Email address</Label>
+      <input
+        id="example-input"
+        type="email"
+        placeholder="you@example.com"
+        style={{
+          padding: 'var(--sv-space-2) var(--sv-space-3)',
+          border: '1px solid var(--sv-color-border-strong)',
+          borderRadius: 'var(--sv-radius-md)',
+          fontFamily: 'var(--sv-font-family)',
+          fontSize: 'var(--sv-font-size-sm)',
+        }}
+      />
+    </div>
+  ),
+};

package/src/components/Label/Label.tsx

@@ -0,0 +1,24 @@
+import type { LabelHTMLAttributes } from 'react';
+import styles from './Label.module.css';
+
+export interface LabelProps extends LabelHTMLAttributes<HTMLLabelElement> {
+  disabled?: boolean;
+}
+
+/**
+ * Label — standalone accessible form label, independent of `FormField`.
+ * Use `FormField` when a control needs hint/error text too; use `Label`
+ * directly for a bare label (e.g. next to a `Checkbox` group heading).
+ */
+export function Label({ disabled, className, children, ...rest }: LabelProps) {
+  return (
+    <label
+      className={[styles.label, disabled ? styles.disabled : '', className]
+        .filter(Boolean)
+        .join(' ')}
+      {...rest}
+    >
+      {children}
+    </label>
+  );
+}

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

@@ -0,0 +1,32 @@
+// @vitest-environment jsdom
+import { afterEach, describe, expect, it } from 'vitest';
+import { cleanup, render, screen } from '@testing-library/react';
+import { Label } from '../Label';
+
+afterEach(cleanup);
+
+describe('Label', () => {
+  it('renders a real <label> element', () => {
+    render(<Label htmlFor="agree">I agree</Label>);
+    expect(screen.getByText('I agree').tagName).toBe('LABEL');
+  });
+
+  it('associates with a control via htmlFor', () => {
+    render(
+      <>
+        <Label htmlFor="agree">I agree to the terms</Label>
+        <input id="agree" type="checkbox" />
+      </>,
+    );
+    expect(screen.getByLabelText('I agree to the terms')).toBeDefined();
+  });
+
+  it('applies disabled styling without disabling the underlying element', () => {
+    render(
+      <Label htmlFor="agree" disabled>
+        I agree
+      </Label>,
+    );
+    expect(screen.getByText('I agree').className).toContain('disabled');
+  });
+});

package/src/components/Marker/Marker.module.css

@@ -0,0 +1,33 @@
+.marker {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  min-width: 16px;
+  height: 16px;
+  padding: 0 4px;
+  margin: 0 1px;
+  border: none;
+  border-radius: var(--sv-radius-full);
+  background: var(--sv-color-accent-subtle);
+  color: var(--sv-color-accent);
+  font-family: var(--sv-font-family);
+  font-size: var(--sv-font-size-label);
+  font-weight: var(--sv-font-weight-semibold);
+  line-height: 1;
+  vertical-align: super;
+}
+
+button.marker {
+  cursor: pointer;
+}
+
+button.marker:focus-visible {
+  outline: 2px solid var(--sv-color-focus-ring);
+  outline-offset: 1px;
+}
+
+@media (hover: hover) {
+  button.marker:hover {
+    background: color-mix(in srgb, var(--sv-color-accent-subtle) 70%, var(--sv-color-accent) 30%);
+  }
+}

package/src/components/Marker/Marker.stories.tsx

@@ -0,0 +1,39 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { Marker } from './Marker';
+
+const meta = {
+  title: 'Components/Marker',
+  component: Marker,
+  parameters: {
+    layout: 'padded',
+    docs: {
+      description: {
+        component:
+          'Inline citation/reference marker, for attributing part of an assistant answer to a source (Sovereign Harness "source trace").',
+      },
+    },
+  },
+  args: { index: 1, label: 'Source: Notes' },
+} satisfies Meta<typeof Marker>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+// ---------------------------------------------------------------------------
+
+export const Static: Story = {};
+
+export const Clickable: Story = {
+  args: { onClick: () => {} },
+};
+
+export const InContext: Story = {
+  render: () => (
+    <p style={{ fontSize: 14, maxWidth: 400 }}>
+      Your next task deadline is Thursday
+      <Marker index={1} label="Source: Tasks" onClick={() => {}} />, and you have two unread
+      messages from the team
+      <Marker index={2} label="Source: Notes" onClick={() => {}} />.
+    </p>
+  ),
+};

package/src/components/Marker/Marker.tsx

@@ -0,0 +1,34 @@
+import styles from './Marker.module.css';
+
+export interface MarkerProps {
+  /** The number shown in the marker, e.g. 1, 2, 3. */
+  index: number;
+  /** Accessible label describing the citation, e.g. "Source: Notes". */
+  label: string;
+  /** Reveals source details (e.g. opens a source trace panel) when given. */
+  onClick?: () => void;
+  className?: string;
+}
+
+/**
+ * Marker — inline citation/reference marker, for attributing part of an
+ * assistant's answer to a source (matches RFC 0040's "source trace" —
+ * Harness shows which plugin/data source informed an answer).
+ */
+export function Marker({ index, label, onClick, className }: MarkerProps) {
+  const classes = [styles.marker, className].filter(Boolean).join(' ');
+
+  if (onClick) {
+    return (
+      <button type="button" onClick={onClick} aria-label={label} className={classes}>
+        {index}
+      </button>
+    );
+  }
+
+  return (
+    <span aria-label={label} className={classes}>
+      {index}
+    </span>
+  );
+}

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

@@ -0,0 +1,23 @@
+// @vitest-environment jsdom
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { cleanup, render, screen } from '@testing-library/react';
+import { Marker } from '../Marker';
+
+afterEach(cleanup);
+
+describe('Marker', () => {
+  it('renders as a static span with an accessible label when no onClick is given', () => {
+    render(<Marker index={1} label="Source: Notes" />);
+    const el = screen.getByLabelText('Source: Notes');
+    expect(el.tagName).toBe('SPAN');
+    expect(el.textContent).toBe('1');
+  });
+
+  it('renders as a button and fires onClick when given', () => {
+    const onClick = vi.fn();
+    render(<Marker index={2} label="Source: Tasks" onClick={onClick} />);
+    const el = screen.getByRole('button', { name: 'Source: Tasks' });
+    el.click();
+    expect(onClick).toHaveBeenCalled();
+  });
+});

package/src/components/Menu/Menu.module.css

@@ -1,6 +1,13 @@
 /* Menu — the item list shared by both presentations (Popover panel on
  * desktop, Drawer panel on mobile); the presentational chrome around it is
- * entirely owned by those two components, not duplicated here. */
+ * entirely owned by those two components, not duplicated here.
+ *
+ * Sizing audit: reviewed against this scale's other compact controls —
+ * --sv-radius-sm (6px) and --sv-font-size-sm (14px) already fit. The 44px
+ * min-height is a deliberate design choice, kept unconditional (not gated
+ * to pointer:coarse like Button/Checkbox) because this menu doubles as a
+ * full Drawer sheet on mobile, where every item must stay comfortably
+ * tappable. */
 
 .list {
   list-style: none;

package/src/components/Menu/Menu.tsx

@@ -70,10 +70,21 @@ export interface MenuProps {
  * Selecting an item both closes the menu and calls its `onSelect` — a
  * consumer's `onSelect` never needs to call `onClose` itself.
  */
-export function Menu({ trigger, open, onClose, items, 'aria-label': ariaLabel, align }: MenuProps) {
-  const isMobile = useIsMobile();
-
-  const list = (
+/**
+ * MenuEntries — the `<ul role="menu">` item list itself, factored out of
+ * `Menu` so other adaptive-surface components (e.g. `ContextMenu`) can
+ * render the exact same items/destructive/checked/icon markup inside their
+ * own positioning shell, instead of re-deriving it and risking drift.
+ */
+export function MenuEntries({
+  items,
+  onSelect,
+}: {
+  items: MenuEntry[];
+  /** Called after an item's own onSelect — typically the surface's onClose. */
+  onSelect: (entry: MenuItem) => void;
+}) {
+  return (
     <ul className={styles.list} role="menu">
       {items.map((entry, index) => {
         // Entries are a static, order-stable list per render — nothing
@@ -99,10 +110,7 @@ export function Menu({ trigger, open, onClose, items, 'aria-label': ariaLabel, a
                 .filter(Boolean)
                 .join(' ')}
               disabled={entry.disabled}
-              onClick={() => {
-                onClose();
-                entry.onSelect();
-              }}
+              onClick={() => onSelect(entry)}
             >
               {isCheckable && (
                 <span className={styles.check} aria-hidden>
@@ -117,6 +125,20 @@ export function Menu({ trigger, open, onClose, items, 'aria-label': ariaLabel, a
       })}
     </ul>
   );
+}
+
+export function Menu({ trigger, open, onClose, items, 'aria-label': ariaLabel, align }: MenuProps) {
+  const isMobile = useIsMobile();
+
+  const list = (
+    <MenuEntries
+      items={items}
+      onSelect={(entry) => {
+        onClose();
+        entry.onSelect();
+      }}
+    />
+  );
 
   if (isMobile) {
     return (

package/src/components/Menubar/Menubar.stories.tsx

@@ -0,0 +1,52 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { Menubar } from './Menubar';
+
+const meta = {
+  title: 'Components/Menubar',
+  component: Menubar,
+  parameters: {
+    layout: 'padded',
+    docs: {
+      description: {
+        component:
+          "Desktop app-style menu bar (File/Edit/View...). A thin composition of NavigationMenu with MenuEntries as each item's flyout content — no positioning or list-rendering logic duplicated.",
+      },
+    },
+  },
+} satisfies Meta<typeof Menubar>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+// ---------------------------------------------------------------------------
+
+export const Default: Story = {
+  args: {
+    menus: [
+      {
+        label: 'File',
+        items: [
+          { label: 'New conversation', onSelect: () => {} },
+          { label: 'Export', onSelect: () => {} },
+          { type: 'separator' },
+          { label: 'Close', onSelect: () => {} },
+        ],
+      },
+      {
+        label: 'Edit',
+        items: [
+          { label: 'Undo', onSelect: () => {} },
+          { label: 'Redo', onSelect: () => {} },
+        ],
+      },
+      {
+        label: 'View',
+        items: [
+          { type: 'label', label: 'Layout' },
+          { label: 'Compact', checked: false, onSelect: () => {} },
+          { label: 'Comfortable', checked: true, onSelect: () => {} },
+        ],
+      },
+    ],
+  },
+};