@sovereignfs/ui 0.41.0 → 0.54.0

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/LegalLinks/LegalLinks.module.css

@@ -0,0 +1,24 @@
+.root {
+  margin: var(--sv-space-5) 0 0;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  gap: var(--sv-space-2);
+  font-size: var(--sv-font-size-xs);
+  color: var(--sv-color-text-muted);
+}
+
+.link {
+  color: var(--sv-color-text-muted);
+  text-decoration: underline;
+  text-underline-offset: 2px;
+  text-decoration-color: var(--sv-color-border);
+}
+
+.link:hover {
+  color: var(--sv-color-text-primary);
+}
+
+.dot {
+  color: var(--sv-color-border);
+}

package/src/components/LegalLinks/LegalLinks.stories.tsx

@@ -0,0 +1,22 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { LegalLinks } from './LegalLinks';
+
+const meta = {
+  title: 'Components/LegalLinks',
+  component: LegalLinks,
+  parameters: { layout: 'padded' },
+} satisfies Meta<typeof LegalLinks>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+// ---------------------------------------------------------------------------
+
+export const Default: Story = {};
+
+export const CustomHrefs: Story = {
+  args: {
+    privacyHref: 'https://example.com/legal/privacy',
+    tosHref: 'https://example.com/legal/tos',
+  },
+};

package/src/components/LegalLinks/LegalLinks.tsx

@@ -0,0 +1,40 @@
+import type { ReactNode } from 'react';
+import styles from './LegalLinks.module.css';
+
+export interface LegalLinksProps {
+  privacyHref?: string;
+  tosHref?: string;
+  /** Renders a linked item. Defaults to a plain `<a href>`, which causes a
+   * full page reload — pass Next's `<Link>` (or equivalent) to keep
+   * navigation client-side. Not needed for a full-reload navigation away
+   * from a standalone auth page, but matters if this is ever mounted inside
+   * an SPA-like shell. */
+  renderLink?: (href: string, label: string) => ReactNode;
+  className?: string;
+}
+
+export function LegalLinks({
+  privacyHref = '/privacy',
+  tosHref = '/tos',
+  renderLink,
+  className,
+}: LegalLinksProps) {
+  const link = (href: string, label: string) =>
+    renderLink ? (
+      renderLink(href, label)
+    ) : (
+      <a href={href} className={styles.link}>
+        {label}
+      </a>
+    );
+
+  return (
+    <p className={[styles.root, className].filter(Boolean).join(' ')}>
+      {link(privacyHref, 'Privacy Policy')}
+      <span aria-hidden="true" className={styles.dot}>
+        ·
+      </span>
+      {link(tosHref, 'Terms of Service')}
+    </p>
+  );
+}

package/src/components/Markdown/Markdown.module.css

@@ -0,0 +1,49 @@
+/* Spacing lives on this wrapper div, not on the Typography-rendered tag
+   inside it — Typography's own variants reset margin: 0, which would tie
+   for CSS specificity against a bare `.root > * + *` sibling rule and make
+   the outcome depend on module load order. A dedicated class avoids that. */
+.block {
+  margin-top: var(--sv-space-4);
+}
+
+.block:first-child {
+  margin-top: 0;
+}
+
+.block[data-heading] {
+  margin-top: var(--sv-space-8);
+}
+
+.block[data-heading]:first-child {
+  margin-top: 0;
+}
+
+.blockquote {
+  margin: 0;
+  padding: var(--sv-space-4);
+  border-left: 3px solid var(--sv-color-border);
+  background: var(--sv-color-surface-sunken);
+  border-radius: var(--sv-radius-sm);
+}
+
+.list {
+  margin: 0;
+  padding-left: var(--sv-space-6);
+  display: flex;
+  flex-direction: column;
+  gap: var(--sv-space-2);
+}
+
+.root a {
+  color: var(--sv-color-text-primary);
+  text-decoration: underline;
+  text-underline-offset: 2px;
+}
+
+.root code {
+  font-family: var(--sv-font-family-mono);
+  font-size: 0.9em;
+  background: var(--sv-color-surface-sunken);
+  padding: 0.1em 0.35em;
+  border-radius: var(--sv-radius-sm);
+}

package/src/components/Markdown/Markdown.stories.tsx

@@ -0,0 +1,30 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { Markdown } from './Markdown';
+
+const sample = `# Privacy Policy
+
+This document describes the built-in, default behavior of **Sovereign**.
+
+> Replaced content from an operator overrides this default.
+
+## What we collect
+
+- **Email address** and password.
+- *Time zone*, detected automatically at signup.
+
+See the [project source](https://github.com/sovereignfs/sovereign) for details.
+`;
+
+const meta = {
+  title: 'Components/Markdown',
+  component: Markdown,
+  parameters: { layout: 'padded' },
+  args: { content: sample },
+} satisfies Meta<typeof Markdown>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+// ---------------------------------------------------------------------------
+
+export const Default: Story = {};

package/src/components/Markdown/Markdown.tsx

@@ -0,0 +1,168 @@
+import type { ReactNode } from 'react';
+import { Typography } from '../Typography/Typography';
+import styles from './Markdown.module.css';
+
+export interface MarkdownProps {
+  /** Raw markdown source. Supports the subset used by Sovereign's own
+   * long-form content pages: headings (#/##/###), paragraphs, **bold**,
+   * *italic*, `code`, [links](url), unordered lists (-), and blockquotes
+   * (>), including soft-wrapped continuation lines within a paragraph or
+   * list item. Not a general-purpose CommonMark parser — no tables,
+   * images, ordered lists, or nested blocks. */
+  content: string;
+  className?: string;
+}
+
+let inlineKey = 0;
+
+/** Parses **bold**, *italic*, `code`, and [text](url) within a line of text. */
+function parseInline(text: string): ReactNode[] {
+  const nodes: ReactNode[] = [];
+  const pattern = /\[([^\]]+)\]\(([^)]+)\)|\*\*([^*]+)\*\*|\*([^*]+)\*|`([^`]+)`/;
+  let remaining = text;
+
+  while (remaining.length > 0) {
+    const match = pattern.exec(remaining);
+    if (!match) {
+      nodes.push(remaining);
+      break;
+    }
+    if (match.index > 0) nodes.push(remaining.slice(0, match.index));
+
+    const [full, linkText, linkHref, boldText, italicText, codeText] = match;
+    const key = `md-inline-${inlineKey++}`;
+    if (linkHref !== undefined) {
+      nodes.push(
+        <a key={key} href={linkHref}>
+          {linkText}
+        </a>,
+      );
+    } else if (boldText !== undefined) {
+      nodes.push(<strong key={key}>{boldText}</strong>);
+    } else if (italicText !== undefined) {
+      nodes.push(<em key={key}>{italicText}</em>);
+    } else if (codeText !== undefined) {
+      nodes.push(<code key={key}>{codeText}</code>);
+    }
+    remaining = remaining.slice(match.index + full.length);
+  }
+
+  return nodes;
+}
+
+const isQuote = (l: string) => l.startsWith('> ') || l === '>';
+const isListItem = (l: string) => l.startsWith('- ');
+const isHeading = (l: string) => /^#{1,3}\s+/.test(l);
+/** A line that ends the current *paragraph* run — a blank line, or the
+ * start of a heading, quote, or list block. Anything else (including an
+ * indented continuation line) is folded into the paragraph, matching how
+ * the source markdown soft-wraps prose across lines. */
+const endsParagraph = (l: string) => l.trim() === '' || isHeading(l) || isQuote(l) || isListItem(l);
+/** A line that ends the current *list* run — a blank line, or the start of
+ * a heading or quote. Deliberately does NOT include `isListItem`: a list
+ * item's own opening line legitimately satisfies `isListItem`, so reusing
+ * `endsParagraph` here (which does) would treat the first line of every
+ * list as ending the list before it started — the list-collection loop
+ * would then never advance, looping forever. */
+const endsList = (l: string) => l.trim() === '' || isHeading(l) || isQuote(l);
+
+function parseBlocks(content: string): ReactNode[] {
+  const lines = content.replace(/\r\n/g, '\n').split('\n');
+  const blocks: ReactNode[] = [];
+  let i = 0;
+  let blockKey = 0;
+
+  while (i < lines.length) {
+    const line = lines[i] ?? '';
+
+    if (line.trim() === '') {
+      i++;
+      continue;
+    }
+
+    const heading = /^(#{1,3})\s+(.*)$/.exec(line);
+    if (heading) {
+      const level = (heading[1]?.length ?? 1) as 1 | 2 | 3;
+      blocks.push(
+        <div key={blockKey++} className={styles.block} data-heading>
+          <Typography variant={`h${level}` as 'h1' | 'h2' | 'h3'}>
+            {parseInline(heading[2] ?? '')}
+          </Typography>
+        </div>,
+      );
+      i++;
+      continue;
+    }
+
+    if (isQuote(line)) {
+      const quoteLines: string[] = [];
+      while (i < lines.length && isQuote(lines[i] ?? '')) {
+        quoteLines.push((lines[i] ?? '').slice(2));
+        i++;
+      }
+      blocks.push(
+        <div key={blockKey++} className={styles.block}>
+          <blockquote className={styles.blockquote}>
+            <Typography variant="body" as="p">
+              {parseInline(quoteLines.join(' '))}
+            </Typography>
+          </blockquote>
+        </div>,
+      );
+      continue;
+    }
+
+    if (isListItem(line)) {
+      const items: string[] = [];
+      while (i < lines.length && !endsList(lines[i] ?? '')) {
+        const current = lines[i] ?? '';
+        if (isListItem(current)) {
+          items.push(current.slice(2));
+        } else {
+          // Continuation of the previous item's wrapped text.
+          const lastIndex = items.length - 1;
+          items[lastIndex] = `${items[lastIndex] ?? ''} ${current.trim()}`;
+        }
+        i++;
+      }
+      blocks.push(
+        <div key={blockKey++} className={styles.block}>
+          <ul className={styles.list}>
+            {items.map((item, idx) => (
+              <Typography key={idx} variant="body" as="li">
+                {parseInline(item)}
+              </Typography>
+            ))}
+          </ul>
+        </div>,
+      );
+      continue;
+    }
+
+    const paraLines: string[] = [];
+    while (i < lines.length && !endsParagraph(lines[i] ?? '')) {
+      paraLines.push((lines[i] ?? '').trim());
+      i++;
+    }
+    blocks.push(
+      <div key={blockKey++} className={styles.block}>
+        <Typography variant="body" as="p">
+          {parseInline(paraLines.join(' '))}
+        </Typography>
+      </div>,
+    );
+  }
+
+  return blocks;
+}
+
+/** Renders a constrained markdown subset (see MarkdownProps) as styled React
+ * elements built from Typography — no HTML string injection. Meant for
+ * long-form, first-party content pages (privacy policy, terms of service)
+ * sourced from a single markdown file, not for rendering arbitrary or
+ * user-supplied markdown. */
+export function Markdown({ content, className }: MarkdownProps) {
+  return (
+    <div className={[styles.root, className].filter(Boolean).join(' ')}>{parseBlocks(content)}</div>
+  );
+}

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 (