altitude-design 0.3.2 → 0.4.1

package/dist/guidance/components/Tabs/README.md

@@ -0,0 +1,73 @@
+# Tabs
+
+Switches between views of the same content.
+
+**`variant="folder"` (default): the sheet on top is the one you're reading.** Every tab is the top edge of its own sheet. The chosen tab and its panel are one raised piece (`surface-raised`, `elev-2`) with concave fillets where they meet; the other tabs lie flush on the ground behind it. Choosing a tab brings its sheet up from behind: its tab rises 10px into place on `ease-settle` while the old tab drops back, and the panel's shadow swells from `elev-1` as the new sheet surfaces, its content emerging 3px below. Hovering an unchosen tab peeks its sheet up a little: a ghost of the tab, before you commit.
+
+**`variant="segmented"`:** a compact control for ranges and modes. The options sit in a well and one raised pill glides between them on `ease-settle`; hovering an option shows a faint ghost of the pill.
+
+Arrow keys, Home and End move between tabs in both.
+
+**Narrow.** A tab list that doesn't fit scrolls within itself, so the page never scrolls sideways: the chosen tab stays in view, and an edge with more tabs past it fades out.
+
+**You provide:** `Tabs` with `value`/`onValueChange` or `defaultValue` and optionally `variant`; a `TabsList` (with an `aria-label`) of `TabsTrigger value="…"`; one `TabsContent value="…"` per trigger. In the folder variant put the `TabsContent`s directly after the `TabsList`: together they're one folder.
+
+- Keep labels to one or two words.
+- Don't use tabs for sequential steps; they imply the views are peers.
+
+`TabsContent` takes `forceMount` to keep an unchosen panel mounted (inert, hidden from assistive technology, `data-state="inactive"`), for views that hold state or cross-fade, as a chart's Chart | Table views do.
+
+<!-- example: generated from build/previews.txt by build/previews.mjs. Edit the preview, not this section. -->
+## Example
+
+`Tabs` as first used in its preview:
+
+```tsx
+import { Tabs, TabsContent, TabsList, TabsTrigger } from 'altitude-design';
+
+<Tabs defaultValue="overview">
+  <TabsList aria-label="Project">
+    <TabsTrigger value="overview">Overview</TabsTrigger>
+    <TabsTrigger value="activity">Activity</TabsTrigger>
+    <TabsTrigger value="settings">Settings</TabsTrigger>
+    <TabsTrigger value="members">Members</TabsTrigger>
+  </TabsList>
+  <TabsContent value="overview"><p className="body">Three deployments this week. Everything is healthy.</p></TabsContent>
+  <TabsContent value="activity"><p className="body">Mara merged “Faster cold starts” 2 hours ago.</p></TabsContent>
+  <TabsContent value="settings"><p className="body">Region, domains and environment variables.</p></TabsContent>
+  <TabsContent value="members"><p className="body">Six people have access to this project.</p></TabsContent>
+</Tabs>
+```
+
+The full preview, as rendered in Storybook and checked in CI (`stack`, `body` are the preview page's own layout classes, not Altitude's):
+
+```tsx
+import { Tabs, TabsContent, TabsList, TabsTrigger } from 'altitude-design';
+
+export default function App() {
+  return (
+    <div className="stack">
+      <Tabs defaultValue="overview">
+        <TabsList aria-label="Project">
+          <TabsTrigger value="overview">Overview</TabsTrigger>
+          <TabsTrigger value="activity">Activity</TabsTrigger>
+          <TabsTrigger value="settings">Settings</TabsTrigger>
+          <TabsTrigger value="members">Members</TabsTrigger>
+        </TabsList>
+        <TabsContent value="overview"><p className="body">Three deployments this week. Everything is healthy.</p></TabsContent>
+        <TabsContent value="activity"><p className="body">Mara merged “Faster cold starts” 2 hours ago.</p></TabsContent>
+        <TabsContent value="settings"><p className="body">Region, domains and environment variables.</p></TabsContent>
+        <TabsContent value="members"><p className="body">Six people have access to this project.</p></TabsContent>
+      </Tabs>
+      <Tabs defaultValue="week" variant="segmented">
+        <TabsList aria-label="Range">
+          <TabsTrigger value="day">Day</TabsTrigger>
+          <TabsTrigger value="week">Week</TabsTrigger>
+          <TabsTrigger value="month">Month</TabsTrigger>
+        </TabsList>
+      </Tabs>
+    </div>
+  );
+}
+```
+<!-- /example -->

package/dist/guidance/components/TagInput/README.md

@@ -0,0 +1,116 @@
+# TagInput
+
+Edit a set of short values in one field: labels on an issue, recipients, skills, keywords, allowed domains. Type and press Enter or comma to add; Backspace twice takes the last one back; each tag has a remove button; Enter, F2 or a double-click edits a tag in place. `Tag` is the same plate on its own, for showing a set outside a field.
+
+```tsx
+<Field label="Labels">
+  <TagInput
+    value={labels}
+    onValueChange={setLabels}
+    suggestions={allLabels}                          // optional; free entry is allowed unless `restrict`
+    max={10}
+    normalize={(tag) => tag.trim().toLowerCase()}    // duplicates are compared after this
+    validate={(tag) => tag.length <= 24 ? undefined : 'Use 24 characters or fewer.'}
+    noun={['label', 'labels']}
+  />
+</Field>
+```
+
+Without `onAdd` and `onRemove` it's a controlled form value. With them, each tag is persisted on its own: `onAdd(tag)` returns `{ ok: true, value }` with the canonical text or `{ ok: false, error }`, the result contract `InlineEdit` uses. The tag waits, pending, until the result. A rejected tag's text comes back to the input with the error so it can be corrected.
+
+## Elevation
+
+- **The field** is an opening, built like `Input`: an empty field shows its back wall (the well). Once it holds a tag its floor rises flush, so the field reads as filled. Invalid fields drop to trench depth on `critical-soft`.
+- **A tag** is a label and part of the record, so it's a Badge plate (ground, level 0) stamped flush into the floor. A new tag is stamped in (down 3px, settling), as a Badge is when its label changes.
+- **Armed** (the first Backspace on an empty input): the last tag lifts one level (`elev-1`) on a `critical-soft` tint, and the status says “Press Backspace again to remove <tag>”. The second Backspace lifts it off (up 8px, fading), and the gap closes. Typing anything disarms it.
+- **Pending** (waiting on `onAdd` or `onRemove`): after `dur-grace` the tag hovers at level 2 (`surface-lifted`, `elev-2`), with `aria-busy`. **Rejected**: the tag drops to a trench with a critical rim; the message is shown and announced.
+- **Being edited**: the plate becomes a small well with an input labelled “Edit <tag>”.
+- **Suggestions** are the `Combobox` list at level 3, with its ranking and gliding highlight.
+
+Without height: tags are text in a list named by their count; the armed tag is announced; pending tags are `aria-busy`; errors are text wired to the input's `aria-describedby`. Under forced colours tags are 1px outlined, the armed tag is outlined in Highlight, pending dotted, failed thick dashed, and an empty field dashed. Under `contrast="more"` the armed tag gets a 2px ink slab.
+
+## Keyboard
+
+- **In the input** (a `combobox`): Enter or a separator adds what's typed (Enter on an active suggestion adds it); ↓/↑ move through suggestions; Backspace on an empty input arms the last tag, and a second removes it; ← from the start moves to the last tag; Escape closes the list or disarms. Nothing acts during IME composition, and a separator typed as text (a soft keyboard's comma) adds too. A paste containing separators or newlines adds one tag per entry, up to `max`; what doesn't fit stays in the input.
+- **On a tag**: the tags are one Tab stop (roving `tabindex`); ←/→ move between them and → from the last returns to the input; Home/End go to the ends. Delete or Backspace removes the tag and focuses the next tag, else the previous, else the input. Enter or F2 edits it in place (Enter saves, Escape cancels); editing is off when `onAdd` or `onRemove` persist tags, because a rename would be two writes.
+- **At `max`** the input stays rendered, focused and read-only, and the description says “Limit reached (10).” Focus is never lost.
+
+The remove buttons are for pointers (`tabIndex={-1}`, named “Remove <tag>”); the keyboard path is Delete on the focused tag. One polite status announces “Added design”, “Removed design”, “design is already added.” and errors. The input is described by the count and the separators (“3 labels. Press comma or Enter to add.”).
+
+## Props
+
+| Prop | |
+|---|---|
+| `value`, `defaultValue`, `onValueChange` | the tags, a `string[]` |
+| `suggestions`, `restrict` | strings or `SelectOption`s offered as you type; with `restrict` only they can be added |
+| `separators` | default `[',', 'Enter']`; single characters also split a paste |
+| `max`, `validate`, `normalize` | a limit; a per-tag error; applied before validating and comparing (default trim) |
+| `onAdd`, `onRemove` | persist one tag at a time (see above) |
+| `renderTag`, `noun` | draw a tag's contents; words for the count (default `['tag', 'tags']`) |
+| `placeholder`, `id`, `name`, `disabled`, `required`, `invalid`, `size` | as `Combobox`; `name` submits each tag through a hidden input |
+
+`Tag`: `children`, optional `onRemove` (adds a remove button) and `label` (names it when the children aren't text).
+
+## You provide
+
+The set, its policy (what's allowed, the limit, normalizing), and any persistence. TagInput doesn't fetch suggestions; pass the current list.
+
+## Do and don't
+
+- **Do** use it for sets of short, free values. For one value from a list, use `Combobox`; for several from a short fixed list, use `Checkbox`es.
+- **Do** normalize (case, spaces) so duplicates are caught.
+- **Don't** put long text in tags; a tag is cut at 24 characters with an ellipsis.
+
+## Demo and verification
+
+The `TagInput` section of `build/previews.txt` shows labels (suggestions, a limit of 6, coloured dots), recipients persisted one at a time (a fictional invite service rejects other domains), a disabled set and standalone `Tag`s. `node checks/tag-input.mjs` (from `build/`; `ALT_FIXTURE_ROOT` selects React 19 fixtures) covers adding, suggestions, duplicates, double Backspace, focus after removal, editing, paste splitting, the limit, IME, pending and rejected adds, removal, and 320/960px layouts in both schemes under reduced motion, forced colours and `contrast="more"`.
+
+<!-- example: generated from build/previews.txt by build/previews.mjs. Edit the preview, not this section. -->
+## Example
+
+`TagInput` as first used in its preview:
+
+```tsx
+import { TagInput } from 'altitude-design';
+
+<TagInput value={labels} onValueChange={setLabels} suggestions={TAG_LABELS} max={6} noun={['label', 'labels']}
+  placeholder="Add a label" normalize={tag => tag.trim().toLowerCase()} validate={tag => tag.length <= 24 ? undefined : 'Use 24 characters or fewer.'}
+  renderTag={tag => <>{TAG_DOTS[tag] && <span className="tags-dot" style={{ '--dot': TAG_DOTS[tag] }} aria-hidden="true" />}{tag}</>} />
+```
+
+The full preview, as rendered in Storybook and checked in CI (`tags-demo`, `tags-dot`, `tags-caption`, `tags-row` are the preview page's own layout classes, not Altitude's):
+
+```tsx
+import * as React from 'react';
+import { Field, Tag, TagInput } from 'altitude-design';
+
+const TAG_LABELS = ['bug', 'design', 'docs', 'performance', 'accessibility', 'onboarding', 'billing', 'mobile'];
+const TAG_DOTS = { bug: 'var(--critical)', design: 'var(--accent)', accessibility: 'var(--positive)', performance: 'var(--caution)' };
+const tagWait = ms => new Promise(resolve => setTimeout(resolve, ms));
+export default function App() {
+  const [labels, setLabels] = React.useState(['design', 'accessibility']);
+  const [recipients, setRecipients] = React.useState(['mara@northwind.example']);
+  const [skills, setSkills] = React.useState(['Figma', 'Research', 'Writing']);
+  return <div className="tags-demo">
+    <Field label="Labels">
+      <TagInput value={labels} onValueChange={setLabels} suggestions={TAG_LABELS} max={6} noun={['label', 'labels']}
+        placeholder="Add a label" normalize={tag => tag.trim().toLowerCase()} validate={tag => tag.length <= 24 ? undefined : 'Use 24 characters or fewer.'}
+        renderTag={tag => <>{TAG_DOTS[tag] && <span className="tags-dot" style={{ '--dot': TAG_DOTS[tag] }} aria-hidden="true" />}{tag}</>} />
+    </Field>
+    <Field label="Share with">
+      <TagInput value={recipients} onValueChange={setRecipients} noun={['person', 'people']} placeholder="name@northwind.example"
+        validate={tag => /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(tag) ? undefined : `${tag} isn’t an email address.`}
+        onAdd={async tag => { await tagWait(500); return tag.endsWith('@northwind.example') ? { ok: true, value: tag.toLowerCase() } : { ok: false, error: `Only people at northwind.example can be invited. ${tag} wasn’t added.` }; }}
+        onRemove={async () => { await tagWait(300); return { ok: true }; }} />
+    </Field>
+    <Field label="Skills">
+      <TagInput value={skills} onValueChange={setSkills} noun={['skill', 'skills']} disabled />
+    </Field>
+    <div>
+      <p className="tags-caption">Standalone tags</p>
+      <div className="tags-row"><Tag>Figma</Tag><Tag>Research</Tag><Tag onRemove={() => {}}>Writing</Tag></div>
+    </div>
+  </div>;
+}
+```
+<!-- /example -->

package/dist/guidance/components/Terminal/README.md

@@ -0,0 +1,69 @@
+# Terminal
+
+A command's output as it runs, with how it ended. Coding agents run `npm test`, `git status` or a migration; the person watches the output arrive, then reads the exit. `CodeBlock streaming` is for code being written; a process also has stderr, an exit status, a duration and Stop.
+
+**Elevation: CodeBlock's frame, with a process's states.**
+- **The frame** is flush on the ground with a 1px `line` rim, mono, no shadow, named by its command (`$ npm test`).
+- **Running** isn't the record yet: a dashed `line-control` rule down the left, "Running", and Stop (secondary, level 1).
+- **Finished**, the rule goes solid with one afterglow and the exit is said in words: "Exited with 0 · 4.2s" with a check, "Exited with 1 · 4.2s" with a critical mark (the edge stays neutral; Distinctiveness, CM3), or "Stopped by you".
+- **stderr lines** carry a critical mark in the gutter and say "stderr" to screen readers.
+- **"Jump to latest output"** floats at level 3 when you scroll up while it runs, as in `Conversation`.
+
+**Accessibility.** A `figure` with a focusable `log` region that isn't live, so output isn't read line by line; completion is announced once ("npm test exited with 1 after 4.2 seconds."). Tab reaches the output, Stop and Copy; arrows scroll; Escape in the output stops a running command when `stopOnEscape` is set.
+
+**ANSI.** With `ansi` (default), red, yellow and green map to `critical`, `caution` and `positive`, blue and cyan to `accent-ink`, dim to `ink-muted`, bold to 600; everything else is stripped. The status inks clear 4.5:1 as text on `surface-ground` in both schemes (lowest: `positive` in daylight, 5.31). A carriage return overwrites its line, so progress bars settle on their last state.
+
+**Props:** `command`, `output` (a string, or `{ text, stream?: 'stdout' | 'stderr' }[]`), `status` (`'running' | 'exited' | 'stopped'`), `exitCode`, `duration`, `onStop`, `stopOnEscape`, `maxLines` (default 400; earlier lines behind "Show N earlier lines"), `ansi`, `copyable`.
+
+**You provide:** the chunks as they arrive, the status, and the exit code and duration when it ends.
+
+```tsx
+<Terminal command="npm test" output={chunks} status={run.status} exitCode={run.code} duration={run.ms}
+  onStop={run.status === 'running' ? stop : undefined} />
+```
+
+- Do keep stderr marked as stderr; it's how a failing line is found.
+- Do say the exit, even when it's 0.
+- Don't use it for code the agent is writing (that's `CodeBlock streaming`).
+
+<!-- example: generated from build/previews.txt by build/previews.mjs. Edit the preview, not this section. -->
+## Example
+
+`Terminal` as first used in its preview:
+
+```tsx
+import { Terminal } from 'altitude-design';
+
+<Terminal command="npm test" output={testRun} status="exited" exitCode={1} duration={4200} />
+```
+
+The full preview, as rendered in Storybook and checked in CI (`tm` is the preview page's own layout class, not Altitude's):
+
+```tsx
+import * as React from 'react';
+import { Terminal } from 'altitude-design';
+
+const E = String.fromCharCode(27);
+const testRun = [
+  { text: '> altitude@0.2.1 test\n> vitest run\n\n' },
+  { text: E + '[32m ✓' + E + '[0m src/format.test.ts ' + E + '[2m(12 tests)' + E + '[0m\n' },
+  { text: E + '[32m ✓' + E + '[0m src/tokens.test.ts ' + E + '[2m(31 tests)' + E + '[0m\n' },
+  { text: E + '[31m ✗' + E + '[0m src/billing.test.ts > refunds an annual plan\n' },
+  { text: '   AssertionError: expected 240 to equal 200\n', stream: 'stderr' },
+  { text: '\n' + E + '[1m Tests' + E + '[0m  ' + E + '[31m1 failed' + E + '[0m | ' + E + '[32m43 passed' + E + '[0m (44)\n' },
+];
+export default function App() {
+  const [n, setN] = React.useState(0);
+  const [stopped, setStopped] = React.useState(false);
+  React.useEffect(() => { if (stopped || n >= 30) return; const t = setTimeout(() => setN(n + 1), 140); return () => clearTimeout(t); }, [n, stopped]);
+  const lines = Array.from({ length: n }, (_, i) => `[migrate] applying 2026_10_${String(i + 1).padStart(2, '0')}_add_index.sql … ok\n`).join('');
+  return (
+    <div className="tm">
+      <Terminal command="npm test" output={testRun} status="exited" exitCode={1} duration={4200} />
+      <Terminal command="npm run migrate" output={lines} status={stopped ? 'stopped' : n >= 30 ? 'exited' : 'running'} exitCode={0} duration={n * 140}
+        onStop={() => setStopped(true)} stopOnEscape />
+    </div>
+  );
+}
+```
+<!-- /example -->

package/dist/guidance/components/ThreadList/README.md

@@ -0,0 +1,110 @@
+# ThreadList
+
+Conversations with an assistant, beside the thread: new conversation, grouped by date, search, rename, delete, and for agents that run in the background, which ones are still working, which finished while you were away and which are waiting for you. It's built from `Sidebar`'s parts.
+
+**Elevation: a record of conversations, with live rows.**
+- **Rows** are destinations: flush at rest, lifting one level when pointed at; the current thread sits on the Sidebar's raised pill (`aria-current="page"`).
+- **Working** isn't pending (nothing you sent is in flight), so it never hovers: a plate with a steady accent lamp says "Working". No spinner.
+- **Needs you** ("Needs approval", "Has a question") is a caution plate with a lamp. A row can't lift into a card inside a nav without breaking the list, so the word carries it, and it's announced once.
+- **Finished, unread** is a dot and the title in 600. **Failed** and **stopped** are plates in words.
+- **Renaming** opens a field (a well) in the row. **Deleting** leaves a `RemovalReceipt` in the row's slot with Undo.
+- **New conversation** is secondary: the composer's Send keeps the view's one primary.
+
+**Accessibility.** A landmark (the Sidebar's `aria-label`, "Conversations") holding lists of links. Each row's name includes its state: "Q3 pricing comparison, Needs approval, 2 minutes ago". F2 renames the focused row (Enter saves, Escape cancels, focus returns to it); Delete deletes it; the row menu is named "More actions for Q3 pricing comparison". ⌘K / Ctrl+K focuses search when `searchable`. A background thread that starts needing you is announced politely once; finishing isn't announced.
+
+**Parts:** `ThreadList` (`searchable`, `onSearch`, `searchLabel`); `ThreadListGroup` (`label`); `ThreadListItem` (`href`, `title`, `updatedAt`, `status`: `'idle' | 'working' | 'needs-input' | 'failed' | 'stopped'`, `needs`: `'approval' | 'question'`, `unread`, `current`, `onSelect`, `onRename`, `onDelete`, `onUndoDelete`, `onDeleted`, `onArchive`); `ThreadListNew`. Helper: `groupByDate(threads, getDate, now?, locale?)` → Today, Yesterday, Previous 7 days, Previous 30 days, then months.
+
+**You provide:** the threads and their states, what selecting, renaming and deleting do. Keep a deleted thread until `onDeleted` (when its receipt closes), so Undo can bring it back.
+
+```tsx
+<Sidebar aria-label="Conversations">
+  <SidebarHeader><ThreadListNew onClick={newThread} /></SidebarHeader>
+  <SidebarContent>
+    <ThreadList searchable onSearch={setQuery}>
+      {groupByDate(threads, (t) => t.updatedAt).map((g) => (
+        <ThreadListGroup key={g.label} label={g.label}>
+          {g.threads.map((t) => <ThreadListItem key={t.id} href={`/c/${t.id}`} current={t.id === id} title={t.title} updatedAt={t.updatedAt}
+            status={t.status} unread={t.unread} onRename={(name) => rename(t.id, name)} onDelete={() => remove(t.id)} onUndoDelete={() => restore(t.id)} onDeleted={() => drop(t.id)} />)}
+        </ThreadListGroup>
+      ))}
+    </ThreadList>
+  </SidebarContent>
+</Sidebar>
+```
+
+- Do say every state in words; the lamp only repeats it.
+- Do keep deleted threads until the receipt closes.
+- Don't show a spinner or make a working row hover.
+
+<!-- example: generated from build/previews.txt by build/previews.mjs. Edit the preview, not this section. -->
+## Example
+
+`ThreadList` as first used in its preview:
+
+```tsx
+import { ThreadList, ThreadListGroup, ThreadListItem, groupByDate } from 'altitude-design';
+
+<ThreadList searchable onSearch={setQ}>
+  {groupByDate(shown, (t) => t.at, now).map((g) => (
+    <ThreadListGroup key={g.label} label={g.label}>
+      {g.threads.map((t) => (
+        <ThreadListItem key={t.id} href={'#/c/' + t.id} title={t.title} updatedAt={t.at} status={t.status} needs={t.needs} unread={t.unread} current={t.id === at}
+          onSelect={(e) => { e.preventDefault(); setAt(t.id); set(t.id, { unread: false }); }}
+          onRename={(title) => set(t.id, { title })} onDelete={() => {}} onUndoDelete={() => {}} onDeleted={() => setThreads((ts) => ts.filter((x) => x.id !== t.id))} />
+      ))}
+    </ThreadListGroup>
+  ))}
+</ThreadList>
+```
+
+The full preview, as rendered in Storybook and checked in CI (`tl`, `page` are the preview page's own layout classes, not Altitude's):
+
+```tsx
+import * as React from 'react';
+import { AppShell, Sidebar, SidebarContent, SidebarHeader, ThreadList, ThreadListGroup, ThreadListItem, ThreadListNew, groupByDate } from 'altitude-design';
+
+const now = Date.now(), min = 60000, hour = 3600000, day = 86400000;
+// Earlier threads hang off the start of today, not off now, so each stays in its group just after midnight.
+const today = new Date(now).setHours(0, 0, 0, 0);
+const seed = [
+  { id: 'a', title: 'Q3 pricing comparison', at: now - 2 * min, status: 'needs-input', needs: 'approval' },
+  { id: 'b', title: 'Refactor the billing module', at: Math.max(now - 9 * min, today), status: 'working' },
+  { id: 'c', title: 'Summarise incident #4821', at: Math.max(now - 40 * min, today), unread: true },
+  { id: 'd', title: 'Draft the release note', at: today - 9 * hour },
+  { id: 'e', title: 'Migrate the users table', at: today - 11 * hour, status: 'failed' },
+  { id: 'f', title: 'Onboarding email ideas', at: today - 3 * day - 12 * hour },
+  { id: 'g', title: 'Competitor research', at: today - 11 * day - 12 * hour, status: 'stopped' },
+];
+export default function App() {
+  const [threads, setThreads] = React.useState(seed);
+  const [at, setAt] = React.useState('b');
+  const [q, setQ] = React.useState('');
+  const shown = threads.filter((t) => t.title.toLowerCase().includes(q.toLowerCase()));
+  const set = (id, patch) => setThreads((ts) => ts.map((t) => (t.id === id ? { ...t, ...patch } : t)));
+  return (
+    <div className="tl">
+      <AppShell sidebar={
+        <Sidebar aria-label="Conversations">
+          <SidebarHeader><ThreadListNew onClick={() => { const id = String(Date.now()); setThreads((ts) => [{ id, title: 'New conversation', at: Date.now() }, ...ts]); setAt(id); }} /></SidebarHeader>
+          <SidebarContent>
+            <ThreadList searchable onSearch={setQ}>
+              {groupByDate(shown, (t) => t.at, now).map((g) => (
+                <ThreadListGroup key={g.label} label={g.label}>
+                  {g.threads.map((t) => (
+                    <ThreadListItem key={t.id} href={'#/c/' + t.id} title={t.title} updatedAt={t.at} status={t.status} needs={t.needs} unread={t.unread} current={t.id === at}
+                      onSelect={(e) => { e.preventDefault(); setAt(t.id); set(t.id, { unread: false }); }}
+                      onRename={(title) => set(t.id, { title })} onDelete={() => {}} onUndoDelete={() => {}} onDeleted={() => setThreads((ts) => ts.filter((x) => x.id !== t.id))} />
+                  ))}
+                </ThreadListGroup>
+              ))}
+            </ThreadList>
+          </SidebarContent>
+        </Sidebar>
+      }>
+        <div className="page">The conversation “{threads.find((t) => t.id === at)?.title}” is open here.</div>
+      </AppShell>
+    </div>
+  );
+}
+```
+<!-- /example -->

package/dist/guidance/components/TimeInput/README.md

@@ -0,0 +1,63 @@
+# TimeInput
+
+A time of day: when a scheduled report is sent, quiet hours, business hours, a maintenance window. It pairs with `DatePicker` when you need both.
+
+**Elevation.** It's an opening, built like `DatePicker`'s typed field: the same segments in the same well. It follows the DatePicker rule for completeness: **it fills only when every segment holds a value**. A partial time ("09:––") is still a hole with its back wall showing, and the floor rises flush once the whole time is there. A time outside `min` and `max` (or `invalid`) drops it to a trench on `critical-soft`. A time zone's short name ("GMT+1") sits after the time in `ink-muted`.
+
+**Typing.** Type digits and they move on by themselves once no further digit could fit ("9" in the hour moves to the minutes, while "1" waits for a second digit). Up and Down change a segment (minutes by `step`), Left and Right move between segments, Backspace clears, and ":" moves on. On a 12-hour clock, "a" or "p" sets AM or PM, and Up or Down flips it. The clock follows the locale unless `hourCycle` says otherwise.
+
+**Value.** Always "HH:mm" on a 24-hour clock ("15:45"), whatever is shown, or null until the time is complete. `timeZone` only labels the time; it doesn't convert it.
+
+**Accessibility.** Segmented [spinbuttons](https://www.w3.org/WAI/ARIA/apg/patterns/spinbutton/) ("Hour", "Minute", "AM/PM", each with its value or "Empty") in a `role="group"`, as in `DatePicker`. The time zone describes each segment. Under forced colours it's dashed while empty or partial and solid when complete. Under `contrast="more"` it gets the well's hard inner edge.
+
+**Props:** `value`, `defaultValue`, `onValueChange` (`"HH:mm" | null`); `step` (minutes, default 1); `hourCycle` (`'auto' | 'h12' | 'h23'`); `min`, `max` ("HH:mm"); `timeZone`; `locale`; `invalid`; `disabled`; `required`; `size`; `name` (submits the value with a form).
+
+**You provide:** a label (with `Field`), the allowed range, and the time zone when people in several zones see it.
+
+```tsx
+<Field label="Send the report at">
+  <TimeInput value="09:30" onValueChange={setTime} step={15} hourCycle="auto" timeZone="Europe/Berlin" />
+</Field>
+```
+
+- Do show the time zone whenever the time isn't in the viewer's own.
+- Do set `step` to the granularity you actually schedule at (15 minutes, not 1).
+- Don't use `<input type="time">`; it looks different in every browser and ignores the scheme.
+- Don't offer a long Select of times when people know the time they want.
+
+<!-- example: generated from build/previews.txt by build/previews.mjs. Edit the preview, not this section. -->
+## Example
+
+`TimeInput` as first used in its preview:
+
+```tsx
+import { TimeInput } from 'altitude-design';
+
+<TimeInput value={report} onValueChange={setReport} step={15} hourCycle="h12" locale="en-US" timeZone="Europe/Berlin" />
+```
+
+The full preview, as rendered in Storybook and checked in CI (`col`, `ti`, `cap` are the preview page's own layout classes, not Altitude's):
+
+```tsx
+import * as React from 'react';
+import { Field, TimeInput } from 'altitude-design';
+
+export default function App() {
+  const [report, setReport] = React.useState('09:30');
+  const [quiet, setQuiet] = React.useState(null);
+  const [open, setOpen] = React.useState('08:00');
+  return (
+    <div className="col">
+      <div className="ti">
+        <Field label="Send the report at" hint={report ? `Stored as ${report}` : 'Not set'}><TimeInput value={report} onValueChange={setReport} step={15} hourCycle="h12" locale="en-US" timeZone="Europe/Berlin" /></Field>
+        <Field label="Quiet hours start" hint="24-hour clock"><TimeInput value={quiet} onValueChange={setQuiet} hourCycle="h23" /></Field>
+        <Field label="Opens at" hint="Between 06:00 and 12:00" error={open && (open < '06:00' || open > '12:00') ? 'Choose a time between 06:00 and 12:00.' : undefined}>
+          <TimeInput value={open} onValueChange={setOpen} min="06:00" max="12:00" hourCycle="h23" />
+        </Field>
+      </div>
+      <p className="cap">Type digits (they move on by themselves), or use Up and Down; minutes step by 15 in the first field. "a" or "p" sets AM or PM. The field fills only once the whole time is there.</p>
+    </div>
+  );
+}
+```
+<!-- /example -->

package/dist/guidance/components/Timeline/README.md

@@ -0,0 +1,87 @@
+# Timeline
+
+Events in order: activity on a record ("Maya changed status to Done"), workspace activity, version history, webhook delivery attempts, an order's history, background agent runs.
+
+**Elevation: the ground is the record, literally.** The events stand on a ground line turned upright, the same 1px `ink-muted` rule that `Stepper`, the `Drilldown` staircase and a chart's baseline stand on. Each event is a flush entry stamped onto it, with its icon on a flush plate on the line. Past events are never raised cards: a raised card claims to be live.
+- **New events** arrive lifted and settle with the afterglow, at most four starting at once. "2 new events" is announced.
+- **An event you caused** (`status="pending"`) hovers ("Sending…") until it lands and joins the record. A failed one drops to a trench with "Couldn't send" and Retry.
+- **An event that links** (`href`) lifts when pointed at.
+- **Detail** (a `DiffView`, a payload) opens behind a Details disclosure as a raised card, as an `Accordion` lid does.
+
+With `groupBy="day"` (the default), each day starts with a heading ("Today", "Yesterday", "Monday", "March 4").
+
+**Accessibility.** A `section` named by `aria-label`, holding an ordered list. Each event is one sentence with its `<time>` (a `RelativeTime` with its exact time in a tooltip). The line and markers are hidden from assistive technology, and day headings are real headings (`headingLevel`, default 3). Details is a disclosure button. Under forced colours the line is `CanvasText`, a pending event is dotted, and a failed one has a thick dash. Under `contrast="more"` the line is 2px.
+
+**Props.** `Timeline`: `groupBy` (`'day' | 'none'`), `headingLevel`, `locale`, `aria-label`, and `TimelineItem` children (give each a key). `TimelineItem`: `time`, `icon`, `status` (`'pending' | 'committed' | 'failed'`), `onRetry`, `detail`, `href`, and the sentence as children.
+
+**You provide:** the events, each as a sentence (who did what to what), with its time.
+
+```tsx
+<Timeline aria-label="Activity">
+  {events.map((e) => (
+    <TimelineItem key={e.id} time={e.at} icon={iconFor(e)} status={e.status} detail={e.diff && <DiffView … />}>
+      <strong>{e.actor}</strong> changed status to <Badge>Done</Badge>
+    </TimelineItem>
+  ))}
+</Timeline>
+```
+
+- Do write each event as a sentence a screen reader can read on its own.
+- Do keep keys stable, so only new events glow.
+- Don't raise past events into cards.
+- Don't use it for steps still to come; that's a `Stepper`.
+
+<!-- example: generated from build/previews.txt by build/previews.mjs. Edit the preview, not this section. -->
+## Example
+
+`Timeline` as first used in its preview:
+
+```tsx
+import { Timeline, TimelineItem } from 'altitude-design';
+
+<Timeline aria-label="Activity">
+  {events.map((e) => <TimelineItem key={e.id} time={e.at} icon={<I d={icons[e.icon]} />} status={e.status} href={e.href} detail={e.detail}
+    onRetry={() => setEvents((xs) => xs.map((x) => (x.id === e.id ? { ...x, status: 'committed' } : x)))}>{e.text}</TimelineItem>)}
+</Timeline>
+```
+
+The full preview, as rendered in Storybook and checked in CI (`tl`, `col`, `row`, `cap` are the preview page's own layout classes, not Altitude's):
+
+```tsx
+import * as React from 'react';
+import { Badge, Button, Input, Timeline, TimelineItem } from 'altitude-design';
+
+// Anchored to the calendar day, so "Today" and "Yesterday" hold at any hour (just after midnight too).
+const ago = (m) => { const start = new Date(); start.setHours(0, 0, 0, 0); return new Date(Math.max(Date.now() - m * 60000, start.getTime() + 1000)); };
+const yesterdayAt = (h) => { const d = new Date(); d.setDate(d.getDate() - 1); d.setHours(h, 0, 0, 0); return d; };
+const I = ({ d }) => <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="1.75" strokeLinecap="round" strokeLinejoin="round"><path d={d} /></svg>;
+const icons = { status: 'M5 12.5l4.5 4.5L19 7.5', comment: 'M4 5h16v11H8l-4 4z', assign: 'M16 19v-1a4 4 0 0 0-8 0v1M12 11a3 3 0 1 0 0-6 3 3 0 0 0 0 6' };
+export default function App() {
+  const [events, setEvents] = React.useState([
+    { id: 'e3', at: ago(14), icon: 'status', text: <><strong>Maya</strong> changed status to <Badge tone="positive">Done</Badge></> },
+    { id: 'e2', at: ago(95), icon: 'assign', text: <><strong>Theo</strong> assigned this to <strong>Maya</strong></>, href: '#/people/maya' },
+    { id: 'e1', at: yesterdayAt(12), icon: 'comment', text: <><strong>Ada</strong> commented</>, detail: <p style={{ margin: 0 }}>“Can we ship this before the release freeze on Friday?”</p> },
+  ]);
+  const [text, setText] = React.useState('');
+  const send = (fail) => {
+    const id = 'n' + Date.now();
+    setEvents((xs) => [{ id, at: new Date(), icon: 'comment', status: 'pending', text: <><strong>You</strong> commented “{text || 'Looks good'}”</> }, ...xs]);
+    setText('');
+    setTimeout(() => setEvents((xs) => xs.map((x) => (x.id === id ? { ...x, status: fail ? 'failed' : 'committed' } : x))), 1200);
+  };
+  return (
+    <div className="tl">
+      <Timeline aria-label="Activity">
+        {events.map((e) => <TimelineItem key={e.id} time={e.at} icon={<I d={icons[e.icon]} />} status={e.status} href={e.href} detail={e.detail}
+          onRetry={() => setEvents((xs) => xs.map((x) => (x.id === e.id ? { ...x, status: 'committed' } : x)))}>{e.text}</TimelineItem>)}
+      </Timeline>
+      <div className="col">
+        <Input value={text} onChange={(ev) => setText(ev.target.value)} placeholder="Add a comment" aria-label="Comment" />
+        <div className="row"><Button variant="primary" onClick={() => send(false)}>Comment</Button><Button onClick={() => send(true)}>Comment (fails)</Button></div>
+        <p className="cap">Your comment hovers until it lands, then settles into the record; one that fails drops to a trench with Retry.</p>
+      </div>
+    </div>
+  );
+}
+```
+<!-- /example -->

package/dist/guidance/components/Toaster/README.md

@@ -0,0 +1,54 @@
+# Toaster
+
+Confirms what just happened, in a depth stack: the newest toast floats in front at level 4 and older ones sink behind it.
+
+Call `toast()` from anywhere; render `Toaster` once inside `AltitudeProvider`. A new toast rises 24px into the front while the others each step back: 10px up, 5% smaller, more transparent and one shadow level lower, with their text hidden. Hovering or focusing the stack fans it out to full height and pauses every timer. Dismissed toasts sink and fade. `critical` toasts use `role="alert"`.
+
+**On touch.** A tap on the stack fans it out and pauses the timers until a tap outside folds it, as hover does for a mouse. A horizontal swipe dismisses a toast.
+
+**You provide:** `toast({ title, description?, tone?, duration?, action?, announce? })` or just `toast('Changes saved')`. `duration` defaults to 5000ms; 0 keeps it until dismissed. Returns an id for `toast.dismiss(id)`. `announce: false` shows a toast without announcing it, for words a screen reader has already heard where they happened: `ItemGroup`'s Undo toast repeats what the receipt in the list already announced.
+
+- Do write the title as the outcome in past tense: "Domain verified".
+- Don't use toasts for errors the person must fix in place; show those in the form with Field.
+
+While a modal owns the document, toasts retain their visual position above the scrim, but their controls are inert and expiry timers pause with their remaining lifetime intact. Notification text is routed to a noninteractive live region inside the active modal, and the external live region is suppressed to avoid duplicate announcements. Timers and controls resume after final release. Essential modal errors belong inside that modal.
+
+When an item leaves a list, its result is shown first in the item's own slot ([RemovalReceipt](../RemovalReceipt/README.md)); once that slot has closed, a toast carries Undo, as in the [Actions in place recipe](../../visual/ActionsInPlace.md). A timed toast may supplement recovery, but must never be its only route: keep a durable Archived/Restore path after a brief Undo opportunity expires. Withdraw a toast's Undo (`toast.dismiss(id)`) as soon as a newer revision makes it invalid.
+
+<!-- example: generated from build/previews.txt by build/previews.mjs. Edit the preview, not this section. -->
+## Example
+
+`Toaster` as first used in its preview:
+
+```tsx
+import { Toaster } from 'altitude-design';
+
+<Toaster />
+```
+
+The full preview, as rendered in Storybook and checked in CI (`col`, `row`, `cap` are the preview page's own layout classes, not Altitude's):
+
+```tsx
+import * as React from 'react';
+import { Button, Toaster, toast } from 'altitude-design';
+
+const msgs = [
+  { title: 'Deployment queued', description: 'northwind-web · main@8dc01b2' },
+  { title: 'Domain verified', description: 'acme.dev now points here.', tone: 'positive' },
+  { title: 'Build failed', description: 'Missing DATABASE_URL.', tone: 'critical', action: { label: 'Retry', onClick: () => {} } },
+];
+export default function App() {
+  React.useEffect(() => { msgs.forEach((m, i) => setTimeout(() => toast({ ...m, duration: 60000 }), 300 + i * 450)); }, []);
+  return (
+    <div className="col">
+      <div className="row">
+        <Button onClick={() => toast({ title: 'Changes saved', tone: 'positive' })}>Toast</Button>
+        <Button variant="ghost" onClick={() => toast({ title: 'Running low on storage', description: '92% used', tone: 'caution' })}>Warning</Button>
+      </div>
+      <p className="cap" style={{ maxWidth: 300 }}>Hover or tap the stack to fan it out; timers pause while you read; swipe a toast away.</p>
+      <Toaster />
+    </div>
+  );
+}
+```
+<!-- /example -->