altitude-design 0.3.2 → 0.4.1

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

@@ -0,0 +1,85 @@
+# Toggle and ToggleGroup
+
+Buttons that stay on: bold and italic in a formatting bar, a list/board/calendar view switch, "Show archived", thumbs up or down on an AI answer.
+
+**Elevation: on is a choice, not a held press.** Pressing a button returns it to the ground, and loading holds it there, so an "on" button drawn at ground level would look like it's loading. A toggle that's on is a choice, so it's built like the Switch: its face is cut into a shallow well (`well`) with `accent-soft` poured in and its label in `accent-ink`. Off is the slab it started as: a ghost (ground) or `secondary` (level 1). Turning on sinks on `ease-sink`, and turning off rises on `ease-rise`. Pointing at an on toggle previews off (feedforward): the well lightens toward the raised face it would become. This is the one exception to "never style a button as sunk" (see [Elevation](../../visual/Elevation.md), "Rules").
+
+**ToggleGroup.**
+- `type="single"` is one choice: segmented `Tabs` without panels, built with the same classes. The options sit in a well and one raised pill glides between them. It's a radio group, so arrow keys move and choose.
+- `type="multiple"` is a row of Toggles, each with `aria-pressed`. Arrow keys move and Space toggles.
+
+Either way the group is **one tab stop**, and returning to it lands on the item you left. Inside a `Toolbar`, a ToggleGroup leaves the arrow keys to the toolbar, so the whole bar is one tab stop.
+
+**Accessibility.** A Toggle is a [toggle button](https://www.w3.org/WAI/ARIA/apg/patterns/button/): its state is `aria-pressed`, and **its name never changes with state** (no "Bold" → "Unbold"). Icon-only toggles need an `aria-label`. A single-choice group is a [radio group](https://www.w3.org/WAI/ARIA/apg/patterns/radio/) with `aria-checked`. Under forced colours an on toggle is a dashed border with a `Highlight` fill, and an off `secondary` toggle has a 1px border. Under `contrast="more"` the on well gets the well's hard inner edge. Under reduced motion nothing travels: the pill appears in place and the fill still changes.
+
+**Props.** `Toggle`: `pressed`, `defaultPressed`, `onPressedChange`, `variant` (`'ghost' | 'secondary'`), and the `Button` props (`size`, `square`, `loading`, …). `ToggleGroup`: `type` (`'single' | 'multiple'`), `value`, `defaultValue`, `onValueChange`, `variant` and `size` (for `multiple`), `orientation`, `disabled`, `aria-label`. `ToggleGroupItem`: `value`.
+
+**You provide:** a label that names the thing being toggled ("Bold", "Show archived"), not the action, and an `aria-label` on each group.
+
+```tsx
+<Toggle aria-label="Bold" pressed={bold} onPressedChange={setBold} square><BoldIcon /></Toggle>
+
+<ToggleGroup type="single" value={view} onValueChange={setView} aria-label="View">
+  <ToggleGroupItem value="list">List</ToggleGroupItem>
+  <ToggleGroupItem value="board">Board</ToggleGroupItem>
+</ToggleGroup>
+
+<ToggleGroup type="multiple" value={marks} onValueChange={setMarks} aria-label="Text style" />
+```
+
+- Do use a Toggle for a tool or a view that stays on; use a `Switch` for a setting that's saved.
+- 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

@@ -0,0 +1,106 @@
+# Toolbar
+
+A row of small actions with one tab stop: a formatting bar, a table's tools, a comment composer, a canvas's tools.
+
+**Elevation.** The bar is settled: it lies on the ground, with a `line` rim when `bordered`. Its tools are live: ghost buttons that lift one level when pointed at and press to the ground. Latched tools (bold, a quote block) are `Toggle`s, so on is a well with the accent poured in. Groups are parted by decorative `Separator`s.
+
+**One tab stop.** Tab reaches the bar once, Left and Right (Up and Down when vertical) move between tools, Home and End jump, and returning to the bar lands on the tool you left. A `ToggleGroup` inside a Toolbar leaves the arrow keys to the bar, so a 12-tool bar costs one Tab, not twelve.
+
+**Overflow.** `overflow="wrap"` (default) wraps tools onto another row. `overflow="menu"` hides the tools that don't fit, from the end, and offers them in a "More tools" menu (`DropdownMenu`, level 3). There, toggles keep their state as checkable items (`menuitemcheckbox`). A separator never ends the visible row. Tools moving into the menu don't animate.
+
+**Accessibility.** The [toolbar pattern](https://www.w3.org/WAI/ARIA/apg/patterns/toolbar/): `role="toolbar"` with an `aria-label` (required) and `aria-orientation`. Icon-only tools need an `aria-label`: a development warning names any tool without one. Under forced colours a hovered or focused tool gets a 1px border and a latched one is dashed (the Toggle's fallback).
+
+**Parts.**
+- `Toolbar`: `aria-label`, `orientation` (`'horizontal' | 'vertical'`), `overflow` (`'wrap' | 'menu'`), `bordered`.
+- `ToolbarGroup`: tools that belong together (`role="group"`; give it an `aria-label` if the group has a name).
+- `ToolbarSeparator`: a decorative line between groups.
+- `ToolbarButton`: a ghost `Button`.
+- `ToolbarToggle`: a ghost `Toggle`.
+- A `ToggleGroup` works inside it as it is.
+
+**You provide:** a label for the bar and for every icon-only tool, and the actions.
+
+```tsx
+<Toolbar aria-label="Formatting" overflow="menu">
+  <ToolbarGroup>
+    <ToolbarToggle aria-label="Bold" pressed={b} onPressedChange={setB} square><Bold /></ToolbarToggle>
+    <ToolbarToggle aria-label="Italic" pressed={i} onPressedChange={setI} square><Italic /></ToolbarToggle>
+  </ToolbarGroup>
+  <ToolbarSeparator />
+  <ToolbarButton aria-label="Insert link" onClick={link} square><Link2 /></ToolbarButton>
+</Toolbar>
+```
+
+- Do put the tools used most first: overflow takes them from the end.
+- 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

@@ -0,0 +1,41 @@
+# Tooltip
+
+Names an icon-only control or adds a short hint; it floats at level 3 above its anchor.
+
+It opens after `delay` (450ms) on hover or immediately on keyboard focus, rising 4px from the anchor while its shadow grows from `elev-1` to `elev-3` (`dur-travel-3`). After one tooltip closes, neighbours open instantly for 400ms, so moving along a toolbar doesn't make you wait twice. Escape closes it.
+
+**On a narrow screen.** It opens where its `side` and `align` put it, then shifts sideways to stay 8px inside the screen, and it's never wider than the screen less 16px.
+
+**You provide:** `content` (a few words, optionally a shortcut), one focusable child, optionally `side="bottom"`.
+
+- 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

@@ -0,0 +1,73 @@
+# Tour
+
+A few steps pointing at parts of the interface, for onboarding or a feature launch: "Projects moved here", "New: filter by owner". Keep it short and skippable.
+
+**Elevation: a note in the air, not a summit.**
+- **One step at a time floats at level 3**, a `Popover`-built card beside its target, with "Step 2 of 4", a heading, the body, progress dots, Skip tour, Back and Next (Done on the last step).
+- **The target takes a 2px `accent-ink` ring**, as `DataGrid`'s active cell does. It's a ring, not a lift, because the target may not be something you press.
+- **It never dims the page.** Dimming means the page is receding, which is the summit's privilege (level 5, and only one thing sits there). Tours that dim with a cut-out spotlight block the very thing they point at.
+- **It isn't modal**: the target stays usable.
+
+**Motion.** Each step rises at its target on `ease-rise`. Moving on lifts the step off and the next one rises at its own target, so nothing flies across the screen. Under reduced motion the steps cross-fade.
+
+**Accessibility.** A non-modal [dialog](https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/) (`role="dialog"`, `aria-modal="false"`) named by the step's heading. The target is `aria-describedby` the step's body while it shows. Focus moves to the step when it opens. Tab reaches the target and back. Escape ends the tour. When the tour ends, focus returns to where it was. A target that's off screen is scrolled into view. Under forced colours the card has a 2px border and the ring is `Highlight`. Under `contrast="more"` the card gets a hard slab.
+
+**Props:** `steps` (`{ target, title, body? }[]`, where `target` is a selector or an element); `open`, `defaultOpen`, `onOpenChange`; `onFinish(how)` (`'done'` or `'skipped'`); `onStepChange`.
+
+**You provide:** the steps, when to start it, and remembering it's been seen (in `onFinish`).
+
+```tsx
+<Tour open={!seen} onOpenChange={…} onFinish={markSeen} steps={[
+  { target: '#nav-projects', title: 'Projects moved here', body: 'All your projects are now in the sidebar.' },
+  { target: '[data-tour=filter-owner]', title: 'Filter by owner', body: 'Type a name to see only their projects.' },
+]} />
+```
+
+- Do keep a tour to a few steps, and always let people skip it.
+- 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

@@ -0,0 +1,129 @@
+# Trace
+
+The steps an agent takes (searching, calling tools, reasoning, waiting for approval), so people can see what it did, what it's doing, what it plans, and where it failed.
+
+**Elevation: a process, drawn as a vertical `Stepper`.** Stepper's rule, verbatim: "done steps are flush in the record with a stamped check, the current one stands raised on its wall, steps to come are imprints."
+- **Done:** flush, stamped check, "Done · 820ms".
+- **Running:** raised on its wall, "Running", `aria-current="step"`. **No spinner:** loading in Altitude is a held press or an imprint, never a spinner. The mark holds a small steady lamp.
+- **Planned:** an imprint, "Planned". If the agent can't know its plan, leave planned steps out: steps then appear as they start, with the afterglow (at most four at once).
+- **Failed:** drops to a trench with a `critical` rim, the reason, and Retry.
+- **Waiting for approval:** raised like a running step, holding a `Confirmation`, the "Proposed" reading.
+- **Detail** sits under its step behind `Accordion` lids: `TraceToolCall` (the tool's name; input and output in `CodeBlock`s) and `TraceReasoning` ("Thought for 2.1s", closed by default).
+
+**Accessibility.** An ordered list (as `Stepper`), each step's state in words. Step changes are announced politely and throttled ("Done: Read 3 articles"), because an agent can finish several steps a second. Failures and approval requests are announced at once. Under forced colours a failed step is dashed thick.
+
+**Parts:** `Trace` (`aria-label`); `TraceStep` (`title`, `status` (`'planned' | 'running' | 'done' | 'failed' | 'awaiting-approval'`), `duration` (ms), `error`, `onRetry`); `TraceToolCall` (`name`, `input`, `output`, `defaultOpen`); `TraceReasoning` (`duration`).
+
+**Subagents.** A `Trace` inside a `TraceStep` is a nested run: a nested list behind a lid that says how it's going ("6 steps · 1 running"), open while something in it is running, waiting or failed, closed when it's all done. `TraceParallel label="Subagents"` groups steps that run at once, with a bracket and "3 in parallel · 2 of 3 done · 1 failed"; several can be raised at once, each because it's in play. `status="auto"` derives a parent from its children: running while any run, failed once the rest stop, done only when all are. Nested steps announce through the outer Trace with their run's name.
+
+**Reasoning as it streams.** `TraceReasoning status="streaming"` says "Thinking…" on its lid; opened, the text follows its end as it arrives, behind a dashed rule (not the record yet), until the person scrolls up. Complete, it's "Thought for 12s"; `status="redacted"` says "Reasoning hidden by the provider" with nothing to open. No shimmer, pulsing dots or ticking counter.
+
+**You provide:** the steps and their status from your agent's events.
+
+```tsx
+<Trace aria-label="Agent run">
+  {run.steps.map((s) => (
+    <TraceStep key={s.id} title={s.title} status={s.status} duration={s.ms}
+      onRetry={s.status === 'failed' ? () => retry(s.id) : undefined}>
+      {s.tool && <TraceToolCall name={s.tool.name} input={s.tool.input} output={s.tool.output} />}
+    </TraceStep>
+  ))}
+</Trace>
+```
+
+- Do say why a step failed.
+- 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 -->

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

@@ -0,0 +1,171 @@
+# Tree
+
+A hierarchy you see all at once and change in place: rename a node (F2), add a sibling or a child, carry a node to a new place (Space, or drag), collapse and expand, remove. Page trees, file explorers, nested categories, outlines.
+
+Use `Drilldown` instead when people work one level at a time and don't need the siblings of ancestors in view (settings, a mobile hierarchy); use `Accordion` for one level of disclosure.
+
+```tsx
+const tree = React.useRef<TreeHandle>(null);
+
+<Tree<Page>
+  ref={tree}
+  aria-label="Pages"
+  items={pages}
+  getKey={(p) => p.id}
+  getLabel={(p) => p.title}
+  getChildren={(p) => p.children}
+  hasChildren={(p) => p.kind === 'folder'}
+  expanded={expanded} onExpandedChange={setExpanded}
+  selected={selected} onSelectedChange={setSelected}
+  renderItem={(p) => <><PageIcon />{p.title}</>}
+  onRename={async (p, title) => { const r = await api.rename(p.id, title, p.revision); if (r.ok) setPages(r.pages); return r; }}
+  onMove={async ({ id, to }) => { const r = await api.move(id, to.parentId, to.index); if (r.ok) setPages(r.pages); return r; }}
+  canDrop={({ to }) => to.parentId === null || isFolder(to.parentId)}
+  onCreate={async ({ parentId, index, name }) => { const r = await api.create(parentId, index, name); if (r.ok) setPages(r.pages); return r.ok ? { ok: true, value: r.page } : r; }}
+  onRemove={(p) => archiveWithUndo(p)}
+/>
+<Button onClick={() => tree.current?.startCreate(null)}>New page</Button>
+```
+
+The tree is controlled by `items`. Each write follows the `InlineEdit` contract: return `{ ok: true }` (for a create, `{ ok: true, value }` with the new item) after `items` reflects the change, or `{ ok: false, error }` for a known failure. A throw or malformed result shows a generic retry message. One write runs at a time.
+
+## Elevation
+
+- **Nodes** are the record: flush rows on the ground, indented `space-4` per level, like `Table` rows. A node lifts one level on hover; the **selected** node is tinted `accent-soft` and raised one level.
+- **Expanding** is disclosure of existing records, so it's a chevron turn (`ease-settle`), not a rise. A node whose children are loading shows an imprint row (`loadChildren`).
+- **Renaming** sinks the label into a well (InlineEdit's field); an invalid or rejected name drops to a trench on `critical-soft`. A **pending** write hovers at level 2 after `dur-grace`; a **failed** one drops to a trench with a critical rim.
+- **Carried** (keyboard): the node floats at level 3, tilted, and is shown where it will land. **Carried** (pointer): a floating copy follows the pointer with the count of what it carries; the top or bottom quarter of a row shows a **slot**, a thin well at the target's depth; the middle of a row opens that node into a **trench with an accent rim** (a critical rim when `canDrop` refuses it). Hovering a closed node for 600ms opens it (spring-loaded).
+- **A new node** is named in a well at its insertion point; once added it settles with an afterglow.
+
+Without height: `aria-level`, `aria-setsize`, `aria-posinset`, `aria-expanded`, `aria-selected` and `aria-busy` on every node (a carried node is announced through the live region, since `aria-pressed` isn't allowed on a tree item); moves are announced with their depth (“Moved Logo into Brand, position 1 of 3”). Forced colours: selected 1px Highlight, carried 2px, slots dashed, drop-into 3px dashed, pending dotted, failed thick dashed. `contrast="more"`: the carried node gets a 3px slab.
+
+## Keyboard
+
+The APG tree view, plus editing:
+
+| Key | |
+|---|---|
+| ↑ / ↓ | previous / next visible node |
+| → / ← | expand, or go to the first child / collapse, or go to the parent (mirrored in RTL) |
+| Home / End | first / last visible node |
+| letters | type-ahead by label |
+| `*` | expand every sibling |
+| Enter | `onAction`, or select |
+| F2 | rename (Enter saves, Escape cancels; IME composition is left alone) |
+| Ctrl/Cmd+Enter, Ctrl/Cmd+Shift+Enter | add a sibling after / a child inside |
+| Space | pick up (announced): ↑/↓ move between slots, → into the node above, ← out of the parent, Space or Enter drop, Escape cancel. Without `onMove`, Space selects |
+| Alt+↑ / Alt+↓ | move one step without picking up |
+| Delete | `onRemove`; focus moves to the next node, else the previous |
+
+Only one node is in the Tab sequence. `TreeHandle.startCreate(parentId, index?)` and `startRename(id)` give pointer users the same actions from a toolbar.
+
+## Props
+
+| Prop | |
+|---|---|
+| `items`, `getKey`, `getLabel`, `getChildren`, `hasChildren`, `loadChildren` | the nested data; `hasChildren` shows a chevron before children are loaded; `loadChildren` is called on the first expand |
+| `expanded`, `defaultExpanded`, `onExpandedChange` | open nodes, by key |
+| `selectionMode`, `selected`, `defaultSelected`, `onSelectedChange` | `'single'` (default) or `'none'` |
+| `onAction`, `renderItem` | Enter's action; draw a node's label |
+| `onRename`, `onMove`, `canDrop`, `onCreate`, `onRemove` | the writes, as above. `TreeTarget.index` is the place among the children once the node has left its old one |
+
+## You provide
+
+The data, the writes and their concurrency guards, and the removal policy (recovery or confirmation, as in Actions in place). Multi-node carrying isn't supported.
+
+## Do and don't
+
+- **Do** give pointer users a visible “New” and “Rename” (through `TreeHandle`); the keyboard shortcuts aren't discoverable on their own.
+- **Do** use `canDrop` to keep pages out of pages that can't hold them.
+- **Don't** use a tree for a flat list, or for more than a few levels people need to see at once.
+
+## Demo and verification
+
+The `Tree` section of `build/previews.txt` is a page tree with a toolbar; the demo service rejects names over 40 characters and moves out of Archive. `node checks/tree.mjs` (from `build/`; `ALT_FIXTURE_ROOT` selects React 19 fixtures) covers the APG keys and RTL, rename (cancel, rejection, save), create (sibling and child), keyboard carry (up, down, indent, outdent, cancel, drop, a rejected move, `canDrop`), Alt+↓, Delete with focus repair, pointer carry into a closed node (spring-loaded) and onto a slot, and 320/960px layouts in both schemes under reduced motion, forced colours and `contrast="more"`.
+**On touch.** With `onMove`, a swipe on a row scrolls; a press-and-hold picks it up, then a drag moves it.
+
+<!-- example: generated from build/previews.txt by build/previews.mjs. Edit the preview, not this section. -->
+## Example
+
+`Tree` as first used in its preview:
+
+```tsx
+import { Tree } from 'altitude-design';
+
+<Tree ref={tree} aria-label="Pages" items={pages} getKey={p => p.id} getLabel={p => p.title} getChildren={p => p.children} hasChildren={p => !!p.children}
+  expanded={expanded} onExpandedChange={setExpanded} selected={selected} onSelectedChange={setSelected}
+  renderItem={p => <><span className="tree-demo-icon" aria-hidden="true">{p.children ? <FolderIcon /> : <PageIcon />}</span>{p.title}</>}
+  onRename={async (page, title) => { await treeWait(250); if (title.length > 40) return { ok: false, error: 'Use 40 characters or fewer.' }; setPages(list => treeRename(list, page.id, title.trim())); return { ok: true }; }}
+  canDrop={({ to }) => to.parentId === null || !!treeFind(pages, to.parentId).page.children}
+  onMove={async ({ id, to }) => {
+    await treeWait(250);
+    // The demo service refuses to move anything out of Archive.
+    if (treeFind(pages, id).parent === 'archive' && to.parentId !== 'archive') return { ok: false, error: 'Archived pages can’t be moved out of Archive.' };
+    setPages(list => { const page = treeFind(list, id).page; return treeInsert(treeRemove(list, id), to.parentId, to.index, page); });
+    return { ok: true };
+  }}
+  onCreate={async ({ parentId, index, name }) => { await treeWait(250); const page = { id: 'new-' + ++seq.current, title: name }; setPages(list => treeInsert(list, parentId, index, page)); return { ok: true, value: page }; }}
+  onRemove={page => setPages(list => treeRemove(list, page.id))} />
+```
+
+The full preview, as rendered in Storybook and checked in CI (`tree-demo`, `tree-demo-tools`, `tree-demo-icon`, `tree-demo-panel` are the preview page's own layout classes, not Altitude's):
+
+```tsx
+import * as React from 'react';
+import { Button, Tree } from 'altitude-design';
+
+const TREE_SEED = [
+  { id: 'brand', title: 'Brand', children: [
+    { id: 'logo', title: 'Logo usage' }, { id: 'colour', title: 'Colour' }, { id: 'type', title: 'Typography' } ] },
+  { id: 'product', title: 'Product', children: [
+    { id: 'roadmap', title: 'Roadmap' },
+    { id: 'specs', title: 'Specs', children: [{ id: 'search', title: 'Search' }, { id: 'billing', title: 'Billing' }] } ] },
+  { id: 'archive', title: 'Archive', children: [] },
+  { id: 'handbook', title: 'Team handbook' },
+];
+const treeWait = ms => new Promise(resolve => setTimeout(resolve, ms));
+// Pure helpers over the nested pages: find, remove, insert.
+const treeFind = (list, id, parent = null) => { for (const [i, p] of list.entries()) { if (p.id === id) return { page: p, parent, index: i }; const hit = p.children && treeFind(p.children, id, p.id); if (hit) return hit; } return null; };
+const treeRemove = (list, id) => list.filter(p => p.id !== id).map(p => p.children ? { ...p, children: treeRemove(p.children, id) } : p);
+const treeInsert = (list, parentId, index, page) => parentId === null ? [...list.slice(0, index), page, ...list.slice(index)]
+  : list.map(p => p.id === parentId ? { ...p, children: [...(p.children || []).slice(0, index), page, ...(p.children || []).slice(index)] } : p.children ? { ...p, children: treeInsert(p.children, parentId, index, page) } : p);
+const treeRename = (list, id, title) => list.map(p => p.id === id ? { ...p, title } : p.children ? { ...p, children: treeRename(p.children, id, title) } : p);
+const FolderIcon = () => <svg width="16" height="16" viewBox="0 0 16 16" fill="none" stroke="currentColor" strokeWidth="1.4"><path d="M2 4.5h4l1.5 1.5H14v6.5H2z" /></svg>;
+const PageIcon = () => <svg width="16" height="16" viewBox="0 0 16 16" fill="none" stroke="currentColor" strokeWidth="1.4"><path d="M4 2h5l3 3v9H4z" /><path d="M9 2v3h3" /></svg>;
+
+export default function App() {
+  const [pages, setPages] = React.useState(TREE_SEED);
+  const [expanded, setExpanded] = React.useState(['brand', 'product']);
+  const [selected, setSelected] = React.useState('roadmap');
+  const tree = React.useRef(null);
+  const seq = React.useRef(0);
+  const current = selected && treeFind(pages, selected);
+  return <div className="tree-demo">
+    <div>
+      <div className="tree-demo-tools">
+        <Button size="sm" variant="ghost" onClick={() => tree.current.startCreate(current && current.page.children ? current.page.id : current ? current.parent : null)}>New page</Button>
+        <Button size="sm" variant="ghost" disabled={!current} onClick={() => tree.current.startRename(selected)}>Rename</Button>
+      </div>
+      <Tree ref={tree} aria-label="Pages" items={pages} getKey={p => p.id} getLabel={p => p.title} getChildren={p => p.children} hasChildren={p => !!p.children}
+        expanded={expanded} onExpandedChange={setExpanded} selected={selected} onSelectedChange={setSelected}
+        renderItem={p => <><span className="tree-demo-icon" aria-hidden="true">{p.children ? <FolderIcon /> : <PageIcon />}</span>{p.title}</>}
+        onRename={async (page, title) => { await treeWait(250); if (title.length > 40) return { ok: false, error: 'Use 40 characters or fewer.' }; setPages(list => treeRename(list, page.id, title.trim())); return { ok: true }; }}
+        canDrop={({ to }) => to.parentId === null || !!treeFind(pages, to.parentId).page.children}
+        onMove={async ({ id, to }) => {
+          await treeWait(250);
+          // The demo service refuses to move anything out of Archive.
+          if (treeFind(pages, id).parent === 'archive' && to.parentId !== 'archive') return { ok: false, error: 'Archived pages can’t be moved out of Archive.' };
+          setPages(list => { const page = treeFind(list, id).page; return treeInsert(treeRemove(list, id), to.parentId, to.index, page); });
+          return { ok: true };
+        }}
+        onCreate={async ({ parentId, index, name }) => { await treeWait(250); const page = { id: 'new-' + ++seq.current, title: name }; setPages(list => treeInsert(list, parentId, index, page)); return { ok: true, value: page }; }}
+        onRemove={page => setPages(list => treeRemove(list, page.id))} />
+    </div>
+    <div className="tree-demo-panel" aria-live="polite">
+      <h3>{current ? current.page.title : 'No page selected'}</h3>
+      <p>F2 renames. Ctrl+Enter adds a page after, Ctrl+Shift+Enter one inside. Space picks a page up: arrows move it, → puts it inside the page above, Space drops. Or drag it onto a folder.</p>
+    </div>
+  </div>;
+}
+```
+<!-- /example -->