altitude-design 0.4.0 → 0.4.2

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

@@ -64,3 +64,53 @@ The set, its policy (what's allowed, the limit, normalizing), and any persistenc
 ## 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

@@ -25,3 +25,45 @@ A command's output as it runs, with how it ended. Coding agents run `npm test`,
 - 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

@@ -35,3 +35,76 @@ Conversations with an assistant, beside the thread: new conversation, grouped by
 - 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

@@ -24,3 +24,40 @@ A time of day: when a scheduled report is sent, quiet hours, business hours, a m
 - 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

@@ -30,3 +30,58 @@ With `groupBy="day"` (the default), each day starts with a heading ("Today", "Ye
 - 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

@@ -14,3 +14,41 @@ Call `toast()` from anywhere; render `Toaster` once inside `AltitudeProvider`. A
 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 -->

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

@@ -31,3 +31,55 @@ Either way the group is **one tab stop**, and returning to it lands on the item
 - Do use `type="single"` for mutually exclusive views; use `Tabs` when each option has its own panel.
 - Don't change a toggle's label when it turns on.
 - Don't use a Toggle for an action that happens once; that's a `Button`.
+
+<!-- example: generated from build/previews.txt by build/previews.mjs. Edit the preview, not this section. -->
+## Example
+
+`Toggle` as first used in its preview:
+
+```tsx
+import { Toggle } from 'altitude-design';
+
+<Toggle variant="secondary" pressed={archived} onPressedChange={setArchived}>Show archived</Toggle>
+```
+
+The full preview, as rendered in Storybook and checked in CI (`tg`, `bar`, `cap` are the preview page's own layout classes, not Altitude's):
+
+```tsx
+import * as React from 'react';
+import { Toggle, ToggleGroup, ToggleGroupItem } from 'altitude-design';
+
+const Thumb = ({ down }) => <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="1.75" strokeLinecap="round" strokeLinejoin="round" aria-hidden="true" style={down ? { transform: 'scaleY(-1)' } : undefined}><path d="M7 10v11H4V10zM7 10l4-7a2 2 0 0 1 3 2l-1 5h6a2 2 0 0 1 2 2.3l-1.5 7A2 2 0 0 1 17.5 21H7" /></svg>;
+export default function App() {
+  const [view, setView] = React.useState('board');
+  const [marks, setMarks] = React.useState(['bold']);
+  const [archived, setArchived] = React.useState(false);
+  const [vote, setVote] = React.useState('');
+  return (
+    <div className="tg">
+      <div className="bar">
+        <ToggleGroup type="multiple" value={marks} onValueChange={setMarks} aria-label="Text style">
+          <ToggleGroupItem value="bold" aria-label="Bold" square><b>B</b></ToggleGroupItem>
+          <ToggleGroupItem value="italic" aria-label="Italic" square><i>I</i></ToggleGroupItem>
+          <ToggleGroupItem value="underline" aria-label="Underline" square><u>U</u></ToggleGroupItem>
+        </ToggleGroup>
+        <ToggleGroup type="single" value={view} onValueChange={setView} aria-label="View">
+          <ToggleGroupItem value="list">List</ToggleGroupItem>
+          <ToggleGroupItem value="board">Board</ToggleGroupItem>
+          <ToggleGroupItem value="calendar">Calendar</ToggleGroupItem>
+        </ToggleGroup>
+        <Toggle variant="secondary" pressed={archived} onPressedChange={setArchived}>Show archived</Toggle>
+      </div>
+      <div className="bar">
+        <span className="cap">Was this answer helpful?</span>
+        <ToggleGroup type="single" value={vote} onValueChange={setVote} aria-label="Rate this answer">
+          <ToggleGroupItem value="up" aria-label="Helpful"><Thumb /></ToggleGroupItem>
+          <ToggleGroupItem value="down" aria-label="Not helpful"><Thumb down /></ToggleGroupItem>
+        </ToggleGroup>
+      </div>
+      <p className="cap">On is a choice, built like the Switch: the face sinks into a well with the accent poured in. Pointing at an on toggle previews off. One choice (View) is segmented Tabs without panels. Each group is one tab stop; arrows move inside it.</p>
+    </div>
+  );
+}
+```
+<!-- /example -->

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

@@ -35,3 +35,72 @@ A row of small actions with one tab stop: a formatting bar, a table's tools, a c
 - Do use a Toolbar for a set of small, related tools; a page's main actions are separate `Button`s.
 - Don't put text fields inside a Toolbar: arrow keys would stop moving the caret.
 - Don't give tools a raised (`secondary` or `primary`) variant; in a toolbar they're ghosts.
+
+<!-- example: generated from build/previews.txt by build/previews.mjs. Edit the preview, not this section. -->
+## Example
+
+`Toolbar` as first used in its preview:
+
+```tsx
+import { ToggleGroup, ToggleGroupItem, Toolbar, ToolbarButton, ToolbarGroup, ToolbarSeparator, ToolbarToggle } from 'altitude-design';
+
+<Toolbar aria-label="Formatting" overflow="menu" bordered className={className}>
+  <ToggleGroup type="multiple" value={marks} onValueChange={setMarks} aria-label="Text style">
+    <ToggleGroupItem value="bold" aria-label="Bold" square><b>B</b></ToggleGroupItem>
+    <ToggleGroupItem value="italic" aria-label="Italic" square><i>I</i></ToggleGroupItem>
+    <ToggleGroupItem value="underline" aria-label="Underline" square><u>U</u></ToggleGroupItem>
+  </ToggleGroup>
+  <ToolbarSeparator />
+  <ToolbarGroup aria-label="Blocks">
+    <ToolbarButton aria-label="Bulleted list" square><I d={list} /></ToolbarButton>
+    <ToolbarToggle aria-label="Quote" square pressed={quoted} onPressedChange={setQuoted}><I d={quote} /></ToolbarToggle>
+    <ToolbarButton aria-label="Code" square><I d={code} /></ToolbarButton>
+  </ToolbarGroup>
+  <ToolbarSeparator />
+  <ToolbarButton aria-label="Insert link" square><I d={link} /></ToolbarButton>
+</Toolbar>
+```
+
+The full preview, as rendered in Storybook and checked in CI (`tb`, `narrow`, `cap` are the preview page's own layout classes, not Altitude's):
+
+```tsx
+import * as React from 'react';
+import { ToggleGroup, ToggleGroupItem, Toolbar, ToolbarButton, ToolbarGroup, ToolbarSeparator, ToolbarToggle } from 'altitude-design';
+
+const I = ({ d }) => <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="1.75" strokeLinecap="round" strokeLinejoin="round" aria-hidden="true"><path d={d} /></svg>;
+const link = 'M10 14a4 4 0 0 0 6 0l3-3a4 4 0 0 0-6-6l-1 1M14 10a4 4 0 0 0-6 0l-3 3a4 4 0 0 0 6 6l1-1';
+const list = 'M9 6h11M9 12h11M9 18h11M4 6h.01M4 12h.01M4 18h.01';
+const quote = 'M7 7h4v6H5V9zM15 7h4v6h-6V9zM9 13l-2 4M17 13l-2 4';
+const code = 'M8 8l-4 4 4 4M16 8l4 4-4 4';
+function Bar({ className }) {
+  const [marks, setMarks] = React.useState(['bold']);
+  const [quoted, setQuoted] = React.useState(false);
+  return (
+    <Toolbar aria-label="Formatting" overflow="menu" bordered className={className}>
+      <ToggleGroup type="multiple" value={marks} onValueChange={setMarks} aria-label="Text style">
+        <ToggleGroupItem value="bold" aria-label="Bold" square><b>B</b></ToggleGroupItem>
+        <ToggleGroupItem value="italic" aria-label="Italic" square><i>I</i></ToggleGroupItem>
+        <ToggleGroupItem value="underline" aria-label="Underline" square><u>U</u></ToggleGroupItem>
+      </ToggleGroup>
+      <ToolbarSeparator />
+      <ToolbarGroup aria-label="Blocks">
+        <ToolbarButton aria-label="Bulleted list" square><I d={list} /></ToolbarButton>
+        <ToolbarToggle aria-label="Quote" square pressed={quoted} onPressedChange={setQuoted}><I d={quote} /></ToolbarToggle>
+        <ToolbarButton aria-label="Code" square><I d={code} /></ToolbarButton>
+      </ToolbarGroup>
+      <ToolbarSeparator />
+      <ToolbarButton aria-label="Insert link" square><I d={link} /></ToolbarButton>
+    </Toolbar>
+  );
+}
+export default function App() {
+  return (
+    <div className="tb">
+      <Bar />
+      <Bar className="narrow" />
+      <p className="cap">One tab stop for the whole bar; arrows move between tools. The narrow bar moves what doesn't fit into "More tools", where Quote stays a checkable item.</p>
+    </div>
+  );
+}
+```
+<!-- /example -->

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

@@ -10,3 +10,32 @@ It opens after `delay` (450ms) on hover or immediately on keyboard focus, rising
 
 - Do use `side="right"` for a rail of icons (a collapsed `Sidebar`), where a tooltip above would cover the next icon.
 - Don't put anything interactive in a tooltip, and don't hide essential information in one.
+
+<!-- example: generated from build/previews.txt by build/previews.mjs. Edit the preview, not this section. -->
+## Example
+
+`Tooltip` as first used in its preview:
+
+```tsx
+import { Button, Tooltip } from 'altitude-design';
+
+<Tooltip content="Bold  ⌘B" defaultOpen><Button square variant="ghost" aria-label="Bold"><b>B</b></Button></Tooltip>
+```
+
+The full preview, as rendered in Storybook and checked in CI (`row`, `cap` are the preview page's own layout classes, not Altitude's):
+
+```tsx
+import { Button, Tooltip } from 'altitude-design';
+
+export default function App() {
+  return (
+    <div className="row">
+      <Tooltip content="Bold  ⌘B" defaultOpen><Button square variant="ghost" aria-label="Bold"><b>B</b></Button></Tooltip>
+      <Tooltip content="Italic  ⌘I"><Button square variant="ghost" aria-label="Italic"><i style={{ fontFamily: 'serif', fontSize: 17 }}>I</i></Button></Tooltip>
+      <Tooltip content="Underline  ⌘U"><Button square variant="ghost" aria-label="Underline"><u>U</u></Button></Tooltip>
+      <span className="cap" style={{ marginLeft: 12 }}>Hover one, then slide to the next: no second delay.</span>
+    </div>
+  );
+}
+```
+<!-- /example -->

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

@@ -27,3 +27,47 @@ A few steps pointing at parts of the interface, for onboarding or a feature laun
 - Do remember when it's been finished or skipped.
 - Don't dim the page or block the target.
 - Don't use a tour to explain an interface that should explain itself.
+
+<!-- example: generated from build/previews.txt by build/previews.mjs. Edit the preview, not this section. -->
+## Example
+
+`Tour` as first used in its preview:
+
+```tsx
+import { Tour } from 'altitude-design';
+
+<Tour open={open} onOpenChange={setOpen} onFinish={(how) => setSaid(how === 'done' ? 'Tour finished.' : 'Tour skipped.')} steps={[
+  { target: '#tour-projects', title: 'Projects moved here', body: 'All your projects now live in one place.' },
+  { target: '[data-tour="owner"]', title: 'Filter by owner', body: 'Type a name to see only their projects.' },
+  { target: '[data-tour="new"]', title: 'Start something new', body: 'Projects can start from a template.' },
+]} />
+```
+
+The full preview, as rendered in Storybook and checked in CI (`tr`, `bar`, `row`, `cap` are the preview page's own layout classes, not Altitude's):
+
+```tsx
+import * as React from 'react';
+import { Button, Input, Tour } from 'altitude-design';
+
+export default function App() {
+  const [open, setOpen] = React.useState(false);
+  const [said, setSaid] = React.useState('');
+  return (
+    <div className="tr">
+      <div className="bar">
+        <Button variant="ghost" id="tour-projects">Projects</Button>
+        <Input size="sm" placeholder="Filter by owner" aria-label="Filter by owner" data-tour="owner" style={{ maxWidth: 220 }} />
+        <span style={{ marginLeft: 'auto' }}><Button variant="primary" data-tour="new">New project</Button></span>
+      </div>
+      <div className="row"><Button onClick={() => setOpen(true)}>Take the tour</Button></div>
+      <p className="cap">{said || 'The tour points at one thing at a time with a ring. The page isn\'t dimmed and stays usable: try typing in the filter while it\'s on that step.'}</p>
+      <Tour open={open} onOpenChange={setOpen} onFinish={(how) => setSaid(how === 'done' ? 'Tour finished.' : 'Tour skipped.')} steps={[
+        { target: '#tour-projects', title: 'Projects moved here', body: 'All your projects now live in one place.' },
+        { target: '[data-tour="owner"]', title: 'Filter by owner', body: 'Type a name to see only their projects.' },
+        { target: '[data-tour="new"]', title: 'Start something new', body: 'Projects can start from a template.' },
+      ]} />
+    </div>
+  );
+}
+```
+<!-- /example -->

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

@@ -35,3 +35,95 @@ The steps an agent takes (searching, calling tools, reasoning, waiting for appro
 - Do put an approval request in the step that's waiting.
 - Don't draw spinners or nested cards.
 - Don't invent planned steps the agent hasn't planned.
+
+<!-- example: generated from build/previews.txt by build/previews.mjs. Edit the preview, not this section. -->
+## Example
+
+`Trace` as first used in its preview:
+
+```tsx
+import { Confirmation, Trace, TraceReasoning, TraceStep, TraceToolCall } from 'altitude-design';
+
+<Trace aria-label="Agent run: answer refund question">
+  {plan.map((s, i) => (
+    <TraceStep key={s.id} title={s.title} status={status(i)} duration={i < at ? s.ms : undefined}
+      error={failed && i === at ? 'The billing service timed out.' : undefined} onRetry={failed && i === at ? () => { setRetried(true); setFailed(false); } : undefined}>
+      {s.tool && <TraceToolCall name={s.tool.name} input={s.tool.input} output={i < at ? s.tool.output ?? { plan: 'annual', startedDaysAgo: 20 } : undefined} />}
+      {s.reasoning && i < at && <TraceReasoning duration={s.ms}>{s.reasoning}</TraceReasoning>}
+      {s.approval && <Confirmation state={approval} title="Send reply to Jamie Lee" consequence="Jamie will get an email confirming a full refund of €240." approveLabel="Send reply" rejectLabel="Don't send" runningLabel="Sending…" doneLabel="Sent"
+        onApprove={() => { setApproval('running'); setTimeout(() => setApproval('done'), 1000); }} onReject={() => setApproval('rejected')} />}
+    </TraceStep>
+  ))}
+</Trace>
+```
+
+The full preview, as rendered in Storybook and checked in CI (`col`, `tc` are the preview page's own layout classes, not Altitude's):
+
+```tsx
+import * as React from 'react';
+import { Confirmation, Trace, TraceParallel, TraceReasoning, TraceStep, TraceToolCall } from 'altitude-design';
+
+const plan = [
+  { id: 's1', title: 'Search the help centre', ms: 820, tool: { name: 'search_documents', input: { query: 'refund policy annual plans', limit: 5 }, output: { results: 3 } } },
+  { id: 's2', title: 'Read 3 articles', ms: 1400 },
+  { id: 's3', title: 'Check the customer’s plan', ms: 600, fails: true, tool: { name: 'get_subscription', input: { customer: 'cus_EXAMPLE42' } } },
+  { id: 's4', title: 'Draft a reply', ms: 2100, reasoning: 'The customer is 20 days into an annual plan, so the 30-day full refund applies. No proration needed.' },
+  { id: 's5', title: 'Send the reply', approval: true },
+];
+export default function App() {
+  const [at, setAt] = React.useState(0);
+  const [failed, setFailed] = React.useState(false);
+  const [retried, setRetried] = React.useState(false);
+  const [approval, setApproval] = React.useState('requested');
+  React.useEffect(() => {
+    if (failed || at >= plan.length - 1) return;
+    const step = plan[at];
+    const t = setTimeout(() => { if (step.fails && !retried) setFailed(true); else setAt(at + 1); }, step.ms);
+    return () => clearTimeout(t);
+  }, [at, failed, retried]);
+  const status = (i) => (i < at ? 'done' : i > at ? 'planned' : failed ? 'failed' : plan[i].approval ? (approval === 'done' ? 'done' : 'awaiting-approval') : 'running');
+  return (
+    <div className="col tc">
+      <Trace aria-label="Agent run: answer refund question">
+        {plan.map((s, i) => (
+          <TraceStep key={s.id} title={s.title} status={status(i)} duration={i < at ? s.ms : undefined}
+            error={failed && i === at ? 'The billing service timed out.' : undefined} onRetry={failed && i === at ? () => { setRetried(true); setFailed(false); } : undefined}>
+            {s.tool && <TraceToolCall name={s.tool.name} input={s.tool.input} output={i < at ? s.tool.output ?? { plan: 'annual', startedDaysAgo: 20 } : undefined} />}
+            {s.reasoning && i < at && <TraceReasoning duration={s.ms}>{s.reasoning}</TraceReasoning>}
+            {s.approval && <Confirmation state={approval} title="Send reply to Jamie Lee" consequence="Jamie will get an email confirming a full refund of €240." approveLabel="Send reply" rejectLabel="Don't send" runningLabel="Sending…" doneLabel="Sent"
+              onApprove={() => { setApproval('running'); setTimeout(() => setApproval('done'), 1000); }} onReject={() => setApproval('rejected')} />}
+          </TraceStep>
+        ))}
+      </Trace>
+      <Trace aria-label="Agent run: compare billing providers">
+        <TraceStep title="Plan the comparison" status="done" duration={900} />
+        <TraceStep title="Research pricing pages" status="auto">
+          <TraceParallel label="Subagents">
+            <TraceStep title="Stripe" status="auto">
+              <Trace aria-label="Stripe subagent">
+                <TraceStep title="Open the pricing page" status="done" duration={1200} />
+                <TraceStep title="Extract the fees" status="done" duration={3400} />
+              </Trace>
+            </TraceStep>
+            <TraceStep title="Paddle" status="auto">
+              <Trace aria-label="Paddle subagent">
+                <TraceStep title="Open the pricing page" status="done" duration={1500} />
+                <TraceStep title="Extract the fees" status="running" />
+              </Trace>
+            </TraceStep>
+            <TraceStep title="Lemon Squeezy" status="failed" error="The pricing page returned 403." onRetry={() => {}} />
+          </TraceParallel>
+        </TraceStep>
+        <TraceStep title="Weigh the fees" status="running">
+          <TraceReasoning status="streaming">{'Stripe charges 2.9% + 30¢ per card payment. Paddle is a merchant of record, so its 5% + 50¢ includes sales tax handling, which'}</TraceReasoning>
+        </TraceStep>
+        <TraceStep title="Check the provider's notes" status="done" duration={2400}>
+          <TraceReasoning status="redacted" />
+        </TraceStep>
+        <TraceStep title="Write the comparison" status="planned" />
+      </Trace>
+    </div>
+  );
+}
+```
+<!-- /example -->