altitude-design 0.3.2 → 0.4.1

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

@@ -0,0 +1,138 @@
+# PromptInput
+
+Where a person writes to an assistant or agent: a textarea that grows, attachments as chips, optional tools or a model picker, Send, and Stop while a response is generating.
+
+**Elevation: an opening.** The whole composer is the `Input` well. Empty, its back wall shows and it deepens as the pointer nears; once it holds text its floor rises flush (Completeness and Anticipation, as `Textarea`).
+- **Send is the level-2 primary.** With nothing to send (no text, or a file still uploading) it's flush and faint, but stays focusable (`aria-disabled`).
+- **While generating, Send becomes Stop in the same slot and size**, held as the live action. Its icon cross-fades without travel, so nothing moves.
+- **Attachments are `Tag` plates** above the text. One being uploaded (your `onAttach` returned a promise) hovers as pending, "Uploading". A rejection removes it and says so.
+- **Dragging a file over** drops the well to a trench, "Drop to attach", as `DropZone` does. It opens only while something could be dropped.
+
+**Keyboard.** Enter sends. Shift+Enter adds a line. **Enter during IME composition never sends**, because it confirms the composition (Japanese, Chinese, Korean input). Escape stops generating. ⌘U or Ctrl+U attaches. Pasting a file attaches it. After sending, focus stays in the composer.
+
+**Accessibility.** Plain HTML: a `<form>` with a labelled `<textarea>` ("Message" unless you name it) and buttons named "Send message", "Stop generating" and "Attach files". Sending isn't announced, because the conversation announces the response. Stopping is ("Generating stopped"), and so are attachments added and removed. Under forced colours the empty well is dashed and a drop target dashed thick. Under reduced motion the composer grows without gliding.
+
+**Parts:** `PromptInput` (`onSubmit({ text, files })`, `status` (`'ready' | 'submitted' | 'streaming' | 'error'`), `onStop`, `value`, `onValueChange`, `onAttach`, `accept`); `PromptInputAttachments`; `PromptInputTextarea` (`placeholder`, `maxHeight`); `PromptInputToolbar`; `PromptInputAttach`; `PromptInputSubmit`.
+
+**Queueing.** With `onQueue`, Enter while the agent works queues the message instead of doing nothing: the button stays Stop, the composer empties and keeps focus, and "Message queued. It will be sent when the assistant finishes." is announced. Show the queue with `ConversationQueue`, and send the first one when the turn ends.
+
+**Context and commands.** With `mentionable(query)`, typing @ opens a list of matches above the composer, grouped by kind (Files, Records, People), ranked as you return them; a promise shows "Searching…". Choosing one puts "@label" in the text and a plate in the composer's context row; Backspace right after it removes it whole, and its plate's remove button does the same. With `commands`, / at the start of an empty composer lists them (best match first). `onSubmit` gets `mentions` and `command` separately; the command is taken out of `text`. The text is a combobox (arrows, Enter or Tab to choose); while generating, the first Escape closes the list and only a second one stops. IME composition never opens or drives it.
+
+**Dictation.** `PromptInputDictate` (in the toolbar) is a microphone toggle; your app supplies the speech recognition (the Web Speech API or a server transcriber) and passes `status`, `interim` and `final`. Listening is latched like a Toggle that's on (a shallow well with accent-soft poured in) with "Listening" and a steady lamp: no pulse, no waveform. Interim words are a ghost under the text in `ink-faint`, like a suggestion, never in the value; `final` words go in at the caret. ⌘D / Ctrl+D toggles from the text; Escape stops listening before it stops generating. "Listening" and "Stopped listening" are announced; interim words aren't. Blocked or unavailable stays focusable and says why.
+
+**You provide:** sending, stopping, uploading, and the `status` of the response. Leave out `accept` and there are no attachments.
+
+```tsx
+<PromptInput onSubmit={(msg) => send(msg)} status={status} onStop={stop} accept="image/*,.pdf">
+  <PromptInputAttachments />
+  <PromptInputTextarea placeholder="Ask about this workspace" />
+  <PromptInputToolbar>
+    <PromptInputAttach />
+    <Select size="sm" aria-label="Model" items={models} />
+    <PromptInputSubmit />
+  </PromptInputToolbar>
+</PromptInput>
+```
+
+- Do keep Stop where Send was.
+- Do return a promise from `onAttach` so an upload shows it's in flight.
+- Don't send on Enter during IME composition (it's handled; don't override `onKeyDown` to send).
+- Don't announce "Message sent".
+
+<!-- example: generated from build/previews.txt by build/previews.mjs. Edit the preview, not this section. -->
+## Example
+
+`PromptInput` as first used in its preview:
+
+```tsx
+import { PromptInput, PromptInputSubmit, PromptInputTextarea, PromptInputToolbar } from 'altitude-design';
+
+<PromptInput onSubmit={({ text, mentions, command }) => setSent(`${command ? `/${command} · ` : ''}${text}${mentions ? ` · context: ${mentions.map((m) => m.label).join(', ')}` : ''}`)}
+  mentionable={(q) => new Promise((r) => setTimeout(() => r(context.filter((c) => c.label.toLowerCase().includes(q.toLowerCase()))), 250))}
+  commands={[{ name: 'review', description: 'Review the current changes' }, { name: 'compact', description: 'Summarise the conversation so far' }, { name: 'clear', description: 'Start a new conversation' }]}>
+  <PromptInputTextarea placeholder="@ to add context, / for commands" />
+  <PromptInputToolbar><PromptInputSubmit /></PromptInputToolbar>
+</PromptInput>
+```
+
+The full preview, as rendered in Storybook and checked in CI (`col`, `cap`, `pi` are the preview page's own layout classes, not Altitude's):
+
+```tsx
+import * as React from 'react';
+import { PromptInput, PromptInputAttach, PromptInputAttachments, PromptInputDictate, PromptInputSubmit, PromptInputTextarea, PromptInputToolbar, Select } from 'altitude-design';
+
+const context = [
+  { id: 'f1', label: 'pricing.ts', kind: 'file', description: 'src/pricing.ts' },
+  { id: 'f2', label: 'plans.test.ts', kind: 'file', description: 'src/plans.test.ts' },
+  { id: 'r1', label: 'Q3 report', kind: 'record', description: 'Shared by Maya, 2 days ago' },
+  { id: 'p1', label: 'Maya Chen', kind: 'person', description: 'Billing team' },
+];
+function Pointed() {
+  const [sent, setSent] = React.useState('');
+  return (
+    <div className="col">
+      <PromptInput onSubmit={({ text, mentions, command }) => setSent(`${command ? `/${command} · ` : ''}${text}${mentions ? ` · context: ${mentions.map((m) => m.label).join(', ')}` : ''}`)}
+        mentionable={(q) => new Promise((r) => setTimeout(() => r(context.filter((c) => c.label.toLowerCase().includes(q.toLowerCase()))), 250))}
+        commands={[{ name: 'review', description: 'Review the current changes' }, { name: 'compact', description: 'Summarise the conversation so far' }, { name: 'clear', description: 'Start a new conversation' }]}>
+        <PromptInputTextarea placeholder="@ to add context, / for commands" />
+        <PromptInputToolbar><PromptInputSubmit /></PromptInputToolbar>
+      </PromptInput>
+      <p className="cap">{sent ? `Sent: ${sent}` : 'Type @ to point at a file, record or person, or / at the start for a command.'}</p>
+    </div>
+  );
+}
+// Dictation: here a scripted transcriber stands in for the app's speech recognition.
+function Dictated() {
+  const [status, setStatus] = React.useState('idle');
+  const [interim, setInterim] = React.useState('');
+  const [final, setFinal] = React.useState();
+  const timers = React.useRef([]);
+  const start = () => {
+    setStatus('listening');
+    const words = 'Summarise the open risks and who owns each one'.split(' ');
+    words.forEach((_, k) => timers.current.push(setTimeout(() => setInterim(words.slice(0, k + 1).join(' ')), 180 * (k + 1))));
+    timers.current.push(setTimeout(() => { setFinal({ id: Date.now(), text: words.join(' ') + '.' }); setInterim(''); setStatus('idle'); }, 180 * words.length + 400));
+  };
+  const stop = () => { timers.current.forEach(clearTimeout); timers.current = []; setInterim(''); setStatus('idle'); };
+  return (
+    <div className="col">
+      <PromptInput onSubmit={() => {}}>
+        <PromptInputTextarea placeholder="Type, or press the microphone and speak" />
+        <PromptInputToolbar>
+          <PromptInputDictate status={status} interim={interim} final={final} onStart={start} onStop={stop} />
+          <PromptInputDictate status="denied" label="Dictate (blocked example)" />
+          <PromptInputSubmit />
+        </PromptInputToolbar>
+      </PromptInput>
+    </div>
+  );
+}
+export default function App() {
+  const [status, setStatus] = React.useState('ready');
+  const [last, setLast] = React.useState('');
+  const timer = React.useRef();
+  const send = ({ text, files }) => {
+    setLast(`Sent “${text}”${files.length ? ` with ${files.length} file${files.length > 1 ? 's' : ''}` : ''}.`);
+    setStatus('submitted');
+    timer.current = setTimeout(() => { setStatus('streaming'); timer.current = setTimeout(() => setStatus('ready'), 2500); }, 600);
+  };
+  return (
+    <div className="col pi">
+      <PromptInput onSubmit={send} status={status} onStop={() => { clearTimeout(timer.current); setStatus('ready'); }} accept="image/*,.pdf,.csv"
+        onAttach={() => new Promise((r) => setTimeout(r, 900))}>
+        <PromptInputAttachments />
+        <PromptInputTextarea placeholder="Ask about this workspace" />
+        <PromptInputToolbar>
+          <PromptInputAttach />
+          <Select size="sm" aria-label="Model" defaultValue="opus" items={[{ value: 'opus', label: 'Opus 5.5' }, { value: 'sonnet', label: 'Sonnet 5.5' }, { value: 'haiku', label: 'Haiku 5.5' }]} />
+          <PromptInputSubmit />
+        </PromptInputToolbar>
+      </PromptInput>
+      <p className="cap">{status === 'ready' ? (last || 'Enter sends, Shift+Enter adds a line. Paste or drop a file to attach it.') : status === 'submitted' ? 'Sending…' : 'Generating… Escape or Stop ends it.'}</p>
+      <Pointed />
+      <Dictated />
+    </div>
+  );
+}
+```
+<!-- /example -->

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

@@ -0,0 +1,137 @@
+# PropertyList
+
+One record's properties as label–value pairs, each editable where it sits: an issue's sidebar (status, assignee, priority, estimate), a customer's details, a settings summary, a “Check your answers” page. It's GOV.UK's summary list and Ant Design's Descriptions, with Linear-style editing: each editable value is an [InlineEdit](../InlineEdit/README.md) with any control, and “Edit all” is one [EditRegion](../EditRegion/README.md).
+
+```tsx
+<PropertyList aria-label="Issue details" shortcuts>
+  <PropertyListItem label="Status" value={issue.status} shortcut="s"
+    renderValue={(s) => <Badge tone={toneFor(s)}>{labelFor(s)}</Badge>}
+    editor={(control) => <Select {...control} items={statuses} />} commit="on-choose"
+    onSave={(draft) => api.patch(issue.id, { status: draft }, issue.revision)}
+    onValueChange={(status) => setIssue({ ...issue, status })} />
+  <PropertyListItem label="Priority" value={issue.priority} emptyLabel="Add priority" … />
+  <PropertyListItem label="Created" value={formatDate(issue.createdAt)} />      {/* read-only: no onSave */}
+</PropertyList>
+```
+
+`onSave` makes an item editable, with InlineEdit's whole contract (`editor`, `commit`, `validate`, `required`, `isEqual`, retained input on failure, conflict latching). Without it the value is read-only text.
+
+## Elevation
+
+- **Properties** are the record, on the ground: a `dl`, labels `ink-muted` above (`layout="stacked"`, a sidebar) or beside (`layout="inline"`, a summary, with `line` rules) their values.
+- **An editable value** is one plate, the InlineEdit trigger, that lifts one level (`elev-1`) when pointed at, because clicking it opens its editor. Read-only values never lift, so editability shows without a pencil per row (hover is a promise).
+- **An unset value** is a small opening: a dashed well, the empty field's treatment at plate size, naming what to add (“Add priority”), so a half-filled record reads at a glance. Setting it fills it.
+- **Editing** opens InlineEdit's well in the value's place, under its own text, so the value doesn't move; with `commit="on-choose"` the picker's list rises from it and there's no Save. Pending, failed and accepted are InlineEdit's.
+- **Edit all** (`editAll`) lifts the whole list into one raised `EditRegion`, for records with cross-field rules (a last day on or after the first).
+- **A proposed change** (an item's `proposed`: an agent read an email and suggests "Stage: Qualified → Proposal", or a teammate's suggested edit) is status that asks for action, so that field is **raised one level** (as `Confirmation`). It shows the current value struck through beside the proposed one (`DiffView`'s property change), "Proposed by Assistant", and Reject and Accept. **Nothing touches the record until it's accepted.** Accepting saves through `onSave`, hovering as pending ("Saving…") and settling with the afterglow (staggered for Accept all, at most four at once). A failed save drops to a trench with the reason and Retry. A raised summary above the list counts the proposals ("3 proposed changes by Assistant") with Accept all and Reject all.
+
+Each editable value is a button named by the label, the value and the verb (“Status: In review. Change status”), as GOV.UK's visually hidden “Change name” guidance asks, so it makes sense out of context. Each change is announced (“Status set to Done”). Proposals are a labelled group (“3 proposed changes”); each Accept and Reject names its field (“Accept new amount”), the old and new values are read as “Current” and “Proposed”, and outcomes are announced (“New amount saved”, “Rejected the new stage”). Forced colours: unset values dashed, the hover plate outlined. `contrast="more"`: the hover plate gets the level-1 ink slab.
+
+## Keyboard
+
+Tab moves through the editable values; Enter or Space opens one, and the editor behaves as InlineEdit (Escape cancels, focus returns to the value). With `shortcuts` on the list, an item's `shortcut` key opens it while focus is in the list and not in a field (`s` for status, as Linear does), and the value announces it with `aria-keyshortcuts`. Shortcuts are off by default: WCAG 2.1.4 asks that single-key shortcuts can be turned off or remapped, so offer a setting before turning them on.
+
+## Props
+
+| | |
+|---|---|
+| `PropertyList` | `layout` (`'stacked'` or `'inline'`), `shortcuts`, `editAll` (`{ value, onValueChange, onSave, validate?, renderEditor, label? }`), `proposedBy`, `aria-label`/`aria-labelledby` |
+| `PropertyListItem` | `label`, `value`, `renderValue`, `emptyLabel`; editable with `onSave`, `onValueChange`, `editor`, `commit`, `validate`, `required`, `isEqual`, `shortcut`; `proposed` and `onProposalResolved(accepted, value)` (clear `proposed` there) |
+
+InlineEdit gains `trigger="value"` (read mode as one value plate), `emptyLabel` and `shortcut` for this; they're available on their own too.
+
+## You provide
+
+The record and each property's write, and for Edit all the whole-record write and its cross-field rules.
+
+## Do and don't
+
+- **Do** use `emptyLabel` to name what's missing (“Add due date”), not just “Not set”.
+- **Do** keep Edit all for records with rules across fields; otherwise edit each property where it sits.
+- **Don't** turn on shortcuts without a way to turn them off.
+
+## Demo and verification
+
+The `PropertyList` section of `build/previews.txt` shows an issue sidebar (status, assignee, priority unset, estimate, created) with shortcuts on, and a “Check your answers” summary with an unset phone number and Edit all. `node checks/property-list.mjs` (from `build/`; `ALT_FIXTURE_ROOT` selects React 19 fixtures) covers the `dl` structure, value buttons and their names, read-only text, unset openings, on-choose saves and announcements, filling an unset value, validation and Escape, shortcuts, Edit all with a cross-field rule and focus return, and 320/960px layouts in both schemes under reduced motion, forced colours and `contrast="more"`.
+**Narrow.** Under 480px of its own width, an inline list stacks each label over its value, and a proposed change stacks its values, who proposed it and its Reject and Accept.
+
+<!-- example: generated from build/previews.txt by build/previews.mjs. Edit the preview, not this section. -->
+## Example
+
+`PropertyList` as first used in its preview:
+
+```tsx
+import { Badge, Combobox, Input, PropertyList, PropertyListItem, Select } from 'altitude-design';
+
+<PropertyList aria-labelledby="pl-issue" shortcuts>
+  <PropertyListItem label="Status" value={issue.status} shortcut="s" commit="on-choose" onSave={save('status')} onValueChange={set('status')}
+    renderValue={s => <Badge tone={PL_TONE[s]}>{plLabel(PL_STATUS, s)}</Badge>} editor={c => <Select {...c} items={PL_STATUS} size="sm" />} />
+  <PropertyListItem label="Assignee" value={issue.assignee} shortcut="a" commit="on-choose" onSave={save('assignee')} onValueChange={set('assignee')}
+    renderValue={p => plLabel(PL_PEOPLE, p)} editor={c => <Combobox {...c} items={PL_PEOPLE} size="sm" />} />
+  <PropertyListItem label="Priority" value={issue.priority} emptyLabel="Add priority" commit="on-choose" onSave={save('priority')} onValueChange={set('priority')}
+    renderValue={p => plLabel(PL_PRIORITY, p)} editor={c => <Select {...c} items={PL_PRIORITY} size="sm" />} />
+  <PropertyListItem label="Estimate" value={issue.estimate} onSave={save('estimate')} onValueChange={set('estimate')} required
+    validate={n => Number.isInteger(n) && n >= 0 ? undefined : 'Use a whole number, 0 or more.'} renderValue={n => `${n} points`}
+    editor={({ value, onValueChange, ...c }) => <Input {...c} type="number" size="sm" value={value ?? ''} onChange={e => onValueChange(e.target.value === '' ? null : Number(e.target.value))} />} />
+  <PropertyListItem label="Created" value={issue.created} />
+</PropertyList>
+```
+
+The full preview, as rendered in Storybook and checked in CI (`pl-demo`, `pl-side` are the preview page's own layout classes, not Altitude's):
+
+```tsx
+import * as React from 'react';
+import { Badge, Combobox, Field, Input, PropertyList, PropertyListItem, Select } from 'altitude-design';
+
+const PL_STATUS = [{ value: 'todo', label: 'To do' }, { value: 'progress', label: 'In progress' }, { value: 'review', label: 'In review' }, { value: 'done', label: 'Done' }];
+const PL_TONE = { todo: 'neutral', progress: 'accent', review: 'caution', done: 'positive' };
+const PL_PEOPLE = [{ value: 'mara', label: 'Mara Quist' }, { value: 'ines', label: 'Inés Ortega' }, { value: 'tobi', label: 'Tobi Adeyemi' }];
+const PL_PRIORITY = [{ value: 'low', label: 'Low' }, { value: 'medium', label: 'Medium' }, { value: 'high', label: 'High' }];
+const plWait = ms => new Promise(resolve => setTimeout(resolve, ms));
+const plLabel = (list, v) => list.find(o => o.value === v)?.label;
+export default function App() {
+  const [issue, setIssue] = React.useState({ status: 'review', assignee: 'mara', priority: '', estimate: 3, created: '21 Oct 2026' });
+  const [trip, setTrip] = React.useState({ name: 'Mara Quist', email: 'mara@northwind.example', start: '2026-11-02', end: '2026-11-06', phone: '' });
+  const set = key => v => setIssue(i => ({ ...i, [key]: v }));
+  const save = key => async draft => { await plWait(250); if (key === 'status' && draft === 'done' && !issue.assignee) return { ok: false, error: 'Assign someone before marking it done.' }; return { ok: true, value: draft }; };
+  const tripSet = key => v => setTrip(t => ({ ...t, [key]: v }));
+  const tripSave = async draft => { await plWait(200); return { ok: true, value: draft }; };
+  return <div className="pl-demo">
+    <section className="pl-side">
+      <h3 id="pl-issue">Issue details</h3>
+      <PropertyList aria-labelledby="pl-issue" shortcuts>
+        <PropertyListItem label="Status" value={issue.status} shortcut="s" commit="on-choose" onSave={save('status')} onValueChange={set('status')}
+          renderValue={s => <Badge tone={PL_TONE[s]}>{plLabel(PL_STATUS, s)}</Badge>} editor={c => <Select {...c} items={PL_STATUS} size="sm" />} />
+        <PropertyListItem label="Assignee" value={issue.assignee} shortcut="a" commit="on-choose" onSave={save('assignee')} onValueChange={set('assignee')}
+          renderValue={p => plLabel(PL_PEOPLE, p)} editor={c => <Combobox {...c} items={PL_PEOPLE} size="sm" />} />
+        <PropertyListItem label="Priority" value={issue.priority} emptyLabel="Add priority" commit="on-choose" onSave={save('priority')} onValueChange={set('priority')}
+          renderValue={p => plLabel(PL_PRIORITY, p)} editor={c => <Select {...c} items={PL_PRIORITY} size="sm" />} />
+        <PropertyListItem label="Estimate" value={issue.estimate} onSave={save('estimate')} onValueChange={set('estimate')} required
+          validate={n => Number.isInteger(n) && n >= 0 ? undefined : 'Use a whole number, 0 or more.'} renderValue={n => `${n} points`}
+          editor={({ value, onValueChange, ...c }) => <Input {...c} type="number" size="sm" value={value ?? ''} onChange={e => onValueChange(e.target.value === '' ? null : Number(e.target.value))} />} />
+        <PropertyListItem label="Created" value={issue.created} />
+      </PropertyList>
+    </section>
+    <section>
+      <h3 id="pl-trip">Check your answers</h3>
+      <PropertyList aria-labelledby="pl-trip" layout="inline"
+        editAll={{ label: 'trip details', value: trip, onValueChange: setTrip,
+          validate: d => d.end < d.start ? { end: 'The last day must be on or after the first.' } : undefined,
+          onSave: async d => { await plWait(250); return { ok: true, value: d }; },
+          renderEditor: field => <>
+            <Field label="Name" error={field.error('name')}><Input {...field('name')} /></Field>
+            <Field label="Email" error={field.error('email')}><Input {...field('email')} type="email" /></Field>
+            <Field label="First day" error={field.error('start')}><Input {...field('start')} type="date" /></Field>
+            <Field label="Last day" error={field.error('end')}><Input {...field('end')} type="date" /></Field>
+            <Field label="Phone"><Input {...field('phone')} type="tel" /></Field>
+          </> }}>
+        <PropertyListItem label="Name" value={trip.name} onSave={tripSave} onValueChange={tripSet('name')} required />
+        <PropertyListItem label="Email" value={trip.email} onSave={tripSave} onValueChange={tripSet('email')} required />
+        <PropertyListItem label="Dates" value={`${trip.start} to ${trip.end}`} />
+        <PropertyListItem label="Phone" value={trip.phone} emptyLabel="Add phone number" onSave={tripSave} onValueChange={tripSet('phone')} />
+      </PropertyList>
+    </section>
+  </div>;
+}
+```
+<!-- /example -->

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

@@ -0,0 +1,81 @@
+# Question
+
+An agent asks the person something before it carries on: "Which environment should I deploy to?", "Keep the old column or drop it?". The person picks one or several options, or writes their own answer, and the run continues. This is the elicitation half of human-in-the-loop (MCP elicitation, Claude Code's AskUserQuestion); `Confirmation` is the approval half.
+
+**Elevation: status that asks, until it's answered.**
+- **Asking** is `Confirmation`'s requested card: raised at level 1 ("The assistant is asking", the question as its title). Nothing has been dispatched, so it's raised, not pending. It arrives with the afterglow.
+- **Options** are trenches: a radio group for one, checkboxes for several, with descriptions. **Your own answer** is a field (a well).
+- **Answer** is the one primary; **Skip** (`skipLabel`) is a ghost button.
+- **Answered**, it presses to the ground as one muted line in the record: "Which layout…? · You chose: Compact · 3 minutes ago". **Expired** says "No longer needed".
+
+**Accessibility.** A section labelled by its question, holding a radio group (arrows) or a group of checkboxes; not a dialog. There's no default answer and nothing is focused for you; the composer keeps focus. Asked, it's announced assertively once ("The assistant is asking: …"), because the run is waiting on it; answered, politely ("Answered: Staging"). Enter in your own answer doesn't submit.
+
+**Props:** `Question`: `title`, `state` (`'asking' | 'answered' | 'expired'`), `multiple`, `allowOther`, `otherLabel`, `answerLabel`, `skipLabel`, `onSkip`, `onAnswer({ values, other })`, `answer`, `answeredAt`, `requestedBy`, `name` (its key in a set). `QuestionOption`: `value`, `label`, `description`. `QuestionSet`: `state`, `onAnswer(answers by name)`, `answerLabel`, `skipLabel`, `onSkip`: several questions answered by one button.
+
+**You provide:** the options, what answering does, and the answer to show once it's answered.
+
+```tsx
+<Question title="Which environment should I deploy to?" state={q.state} answer={q.answer} allowOther
+  answerLabel="Deploy" skipLabel="Let the assistant decide" onAnswer={(a) => respond(q.id, a)} onSkip={() => skip(q.id)}>
+  <QuestionOption value="staging" label="Staging" description="Resets nightly. Safe to try things." />
+  <QuestionOption value="production" label="Production" description="Customers will see it immediately." />
+</Question>
+```
+
+- Do describe what each option means for the run.
+- Do offer a way to let the assistant decide when a default exists.
+- Don't preselect an option or move focus to the question.
+
+<!-- example: generated from build/previews.txt by build/previews.mjs. Edit the preview, not this section. -->
+## Example
+
+`Question` as first used in its preview:
+
+```tsx
+import { Question, QuestionOption } from 'altitude-design';
+
+<Question title="Which environment should I deploy to?" state={q.state} answer={q.answer} answeredAt={q.at} allowOther
+  answerLabel="Deploy" skipLabel="Let the assistant decide" onSkip={() => setQ({ state: 'expired' })}
+  onAnswer={(answer) => setQ({ state: 'answered', answer, at: Date.now() })}>
+  <QuestionOption value="staging" label="Staging" description="Resets nightly. Safe to try things." />
+  <QuestionOption value="production" label="Production" description="Customers will see it immediately." />
+</Question>
+```
+
+The full preview, as rendered in Storybook and checked in CI (`qs` is the preview page's own layout class, not Altitude's):
+
+```tsx
+import * as React from 'react';
+import { Question, QuestionOption, QuestionSet } from 'altitude-design';
+
+export default function App() {
+  const [q, setQ] = React.useState({ state: 'asking' });
+  const [set, setSet] = React.useState({ state: 'asking' });
+  return (
+    <div className="qs">
+      <Question title="Which environment should I deploy to?" state={q.state} answer={q.answer} answeredAt={q.at} allowOther
+        answerLabel="Deploy" skipLabel="Let the assistant decide" onSkip={() => setQ({ state: 'expired' })}
+        onAnswer={(answer) => setQ({ state: 'answered', answer, at: Date.now() })}>
+        <QuestionOption value="staging" label="Staging" description="Resets nightly. Safe to try things." />
+        <QuestionOption value="production" label="Production" description="Customers will see it immediately." />
+      </Question>
+      <QuestionSet state={set.state} onAnswer={(answers) => setSet({ state: 'answered', answers })}>
+        <Question name="column" title="Keep the old status column, or drop it?" answer={set.answers?.column}>
+          <QuestionOption value="keep" label="Keep it" description="Writes go to both columns until you remove it." />
+          <QuestionOption value="drop" label="Drop it" description="The migration removes it after copying." />
+        </Question>
+        <Question name="notify" title="Who should hear about it?" multiple answer={set.answers?.notify}>
+          <QuestionOption value="eng" label="#eng-billing" />
+          <QuestionOption value="support" label="#support" />
+          <QuestionOption value="owner" label="The account owner" />
+        </Question>
+      </QuestionSet>
+      <Question title="Which layout should I use for the invoice?" state="answered" answer={{ values: ['compact'] }} answeredAt={Date.now() - 3 * 60000}>
+        <QuestionOption value="compact" label="Compact" />
+        <QuestionOption value="detailed" label="Detailed" />
+      </Question>
+    </div>
+  );
+}
+```
+<!-- /example -->

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

@@ -0,0 +1,47 @@
+# RadioGroup
+
+Chooses exactly one option. A radio group is built like the Switch with more positions: **one switch, several positions, one thumb**.
+
+Each option is a round trench, the same as the switch track. The group owns a single raised thumb; choosing an option slides it to that track on `ease-settle`, and the accent pours into the track from under the thumb as it arrives while the old one drains. Because there's only one thumb, the choice can't be in two places, and its movement shows where it came from. Hovering an unchosen option shows a faint ghost of the thumb where it would land (feedforward); hovering the chosen option lifts the thumb; pressing it stretches the thumb, like a switch. Arrow keys move the choice, as native radios do, and the thumb follows.
+
+**You provide:** `Radio` children with `value`, `label` and optional `description`; `value`/`onValueChange` or `defaultValue`; an `aria-label` for the group if there's no visible heading; `orientation="horizontal"` for two or three short options.
+
+- Default to a sensible choice; a group with no thumb is rarely what you want.
+- Don't use radios for more than about six options; use a menu.
+
+<!-- example: generated from build/previews.txt by build/previews.mjs. Edit the preview, not this section. -->
+## Example
+
+`RadioGroup` as first used in its preview:
+
+```tsx
+import { Radio, RadioGroup } from 'altitude-design';
+
+<RadioGroup defaultValue="team" aria-label="Plan">
+  <Radio value="solo" label="Solo" description="One seat, unlimited projects." />
+  <Radio value="team" label="Team" description="Up to 20 seats and shared libraries." />
+  <Radio value="org" label="Organization" disabled description="Talk to us." />
+</RadioGroup>
+```
+
+The full preview, as rendered in Storybook and checked in CI (`pair` is the preview page's own layout class, not Altitude's):
+
+```tsx
+import { Radio, RadioGroup } from 'altitude-design';
+
+export default function App() {
+  return (
+    <div className="pair">
+      <RadioGroup defaultValue="team" aria-label="Plan">
+        <Radio value="solo" label="Solo" description="One seat, unlimited projects." />
+        <Radio value="team" label="Team" description="Up to 20 seats and shared libraries." />
+        <Radio value="org" label="Organization" disabled description="Talk to us." />
+      </RadioGroup>
+      <RadioGroup defaultValue="m" orientation="horizontal" aria-label="Size">
+        <Radio value="s" label="Small" /><Radio value="m" label="Medium" /><Radio value="l" label="Large" />
+      </RadioGroup>
+    </div>
+  );
+}
+```
+<!-- /example -->

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

@@ -0,0 +1,73 @@
+# RelativeTime
+
+A moment shown as "3 minutes ago", for activity feeds, audit logs, comments and "last edited". `formatRelativeTime()` gives the same words as a string.
+
+**Elevation.** A timestamp is part of the record, so it's plain text on the ground. **Ticking forward is not a change to the record:** "3 minutes ago" becoming "4 minutes ago" swaps the words with no transition and no afterglow. When the moment itself changes (the record was edited again), that is a change, and the time takes the same ground-level tint as a changed `FormattedNumber`, decaying over `dur-settle`.
+
+**Refreshing.** Every RelativeTime on the page shares one timer (every 15 seconds). It stops while the page is hidden and catches up as soon as the page is visible again. Words come from `Intl.RelativeTimeFormat` with `numeric: "auto"`, so you get "now", "yesterday" and "last month", pluralised for the locale.
+
+**Formats.** `relative` (default) always says how long ago or until. `auto` is relative within `threshold` (an ISO 8601 duration such as `"P7D"` or `"PT12H"`, or milliseconds; default 7 days), then a date ("Mar 4", or "Mar 4, 2025" in another year). `tense="past"` never says "in 2 minutes", even when a client's clock runs ahead, and `tense="future"` never says "ago".
+
+**Accessibility.** It renders a `<time dateTime="…ISO…">`. With `tooltip` (on by default) it's focusable, and the exact date, time and zone ("Wednesday, October 29, 2026 at 3:04:12 PM EDT") is shown in a `Tooltip` on hover and focus and attached with `aria-describedby`. With `tooltip={false}` the exact time is its `title`. Ticking is never a live region. Under forced colours a new moment's tint is a `Highlight` outline.
+
+**Props:** `date` (a `Date`, ISO string or epoch ms); `format` (`'relative' | 'auto'`); `threshold`; `tense` (`'auto' | 'past' | 'future'`); `locale`; `tooltip` (default true).
+
+**You provide:** the moment, and whether old moments should become dates (`format="auto"`).
+
+```tsx
+<RelativeTime date={event.createdAt} />                    // "3 minutes ago"
+<RelativeTime date={due} format="auto" threshold="P7D" />   // relative within 7 days, then "Mar 4"
+<RelativeTime date={d} locale="fr" tense="past" />          // "il y a 3 minutes"
+```
+
+- Do use `format="auto"` in logs and feeds that reach back further than a week.
+- Do keep the tooltip on wherever the exact time matters (audit logs, billing).
+- Don't put a RelativeTime in a live region, or announce it ticking.
+- Don't format times by hand with string concatenation.
+
+<!-- example: generated from build/previews.txt by build/previews.mjs. Edit the preview, not this section. -->
+## Example
+
+`RelativeTime` as first used in its preview:
+
+```tsx
+import { RelativeTime } from 'altitude-design';
+
+<RelativeTime date={when} format="auto" />
+```
+
+The full preview, as rendered in Storybook and checked in CI (`rt`, `col`, `row`, `cap` are the preview page's own layout classes, not Altitude's):
+
+```tsx
+import * as React from 'react';
+import { Button, Card, CardContent, CardDescription, CardHeader, CardTitle, RelativeTime } from 'altitude-design';
+
+const ago = (ms) => new Date(Date.now() - ms);
+const events = [
+  ['Deploy #482 finished', ago(20_000)],
+  ['Maya invited Theo', ago(3 * 60_000)],
+  ['Invoice INV-0042 paid', ago(5 * 3_600_000)],
+  ['API key rotated', ago(26 * 3_600_000)],
+  ['Workspace created', ago(40 * 86_400_000)],
+];
+export default function App() {
+  const [edited, setEdited] = React.useState(() => ago(12 * 60_000));
+  return (
+    <div className="rt">
+      <ul aria-label="Activity">
+        {events.map(([what, when]) => <li key={what}><span>{what}</span><RelativeTime date={when} format="auto" /></li>)}
+      </ul>
+      <Card>
+        <CardHeader><CardTitle>Q3 board deck</CardTitle><CardDescription>Last edited <RelativeTime date={edited} /></CardDescription></CardHeader>
+        <CardContent>
+          <div className="col">
+            <div className="row"><Button size="sm" onClick={() => setEdited(new Date())}>Edit again</Button></div>
+            <p className="cap">Time passing changes the words with nothing else. A new moment (an edit) settles with a tint. Point at or tab to a time for its exact date, time and zone. Past a week, the feed shows a date.</p>
+          </div>
+        </CardContent>
+      </Card>
+    </div>
+  );
+}
+```
+<!-- /example -->

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

@@ -0,0 +1,111 @@
+# RemovalReceipt
+
+The slot of an item that can leave its list: a file archived, a webhook removed, an invitation revoked. When the item goes, its result shows in its own slot, at the height it had, so nothing on the page moves while it's read. The slot holds, lifts its receipt off, and only then glides the gap closed. Use it instead of removing the row at once and adding an Alert below the list, which reshapes the page twice and puts the feedback away from where the person acted.
+
+**Left in place, then closed.** With `removed`, the item's content cross-fades (`dur-travel-2`) to the receipt: a check (or, with `tone="critical"`, an alert icon), your `title`, and your `action`. While `pending`, the write isn't confirmed: the receipt shows a spinner in place of the check, the slot hovers as pending only after `dur-grace` (a fast write never flickers), and the hold hasn't started. Once confirmed, the receipt holds for `dur-linger` (2000ms), then lifts off as an Alert does (8px, in 70% of `dur-travel-3`, `ease-sink`), and the gap glides shut (`dur-travel-3`, `ease-glide`). The rows below are pushed by the height, not animated on their own. `onClosed` is called once the gap has closed: drop the item from your list there.
+
+**The hold waits for the person.** It pauses while the receipt is pointed at or focused, and while a modal owns the document. When it's due and a mouse is still over the list (the slot's parent), it waits for the pointer to leave, up to `dur-settle`, so the next row doesn't slide under a pointer reaching for it. Touch has no hover, so on touch it closes when the hold ends. Receipts due within 250ms of each other close together, as one change.
+
+**Why it's on the ground.** The receipt is a trace of what happened to the record, not a live surface, so it doesn't rise for attention: muted ink on the ground. Only its exit lifts off. Pending uses the shared pending signal (`surface-lifted`, `elev-2`, breathing over `dur-hover`). An item brought back from elsewhere (`arrive`) glides its slot open and settles with an afterglow; an item restored while its receipt is still held (`removed` back to false) returns in place with an afterglow.
+
+**Accessibility.** The receipt's text is a polite live region (`role="status"`) present from the slot's first render, so the result is announced when it appears. Put Undo in `action` and name it fully (`aria-label="Undo archive of Brand guidelines.pdf"`). Before the slot closes, focus inside it moves to the first focusable control of the next slot, else the previous one, else `focusFallback()`. Under reduced motion the receipt still fades and holds, nothing travels, and the gap closes at once. Under forced colours the receipt is outlined in `CanvasText`.
+
+**Props:** `removed`; `pending`; `title`; `action`; `tone` (`neutral` | `critical`); `icon`; `hold` (ms, default `dur-linger`); `onClosed`; `focusFallback`; `arrive`; `settle`; `as` (`div` | `li` | `section` | `article`, default `div`). Other props go to the slot's element, and the item's own content (`children`) keeps the slot's layout (its wrapper is `display: contents`).
+
+**You provide:** the item, whether it's removed and whether that's confirmed, the words and the actions, and what happens next. Undo has to call your real inverse operation. After the slot closes, offer Undo in a `toast` if you like, but keep a durable recovery route (Archived → Restore), and withdraw a toast's Undo (`toast.dismiss(id)`) once a newer revision makes it invalid. See [Actions in place](../../visual/ActionsInPlace.md) for the full recipe: pending, failure, conflict, late receipts and focus.
+
+```tsx
+<ul>
+  {files.map((file) => (
+    <RemovalReceipt as="li" key={file.id} removed={!!receipts[file.id]} pending={receipts[file.id]?.pending}
+      title={`${file.name} archived.`}
+      action={<Button size="sm" aria-label={`Undo archive of ${file.name}`} onClick={() => restore(file)}>Undo</Button>}
+      onClosed={() => { dropReceipt(file.id); toast({ title: `${file.name} archived.`, action: { label: 'Undo', onClick: () => restore(file) } }); }}>
+      <FileRow file={file} onArchive={() => archive(file)} />
+    </RemovalReceipt>
+  ))}
+</ul>
+```
+
+- Do keep the item in its slot until its removal is confirmed; show a failure in the restored row, not somewhere else.
+- Do put Undo where the removing action was, so a second click under the pointer reverses rather than navigates.
+- Don't hold the receipt for longer to "make sure": the person can stop it by pointing at it or focusing it.
+- Don't use it for a line removed while typing (an empty `Checklist` line); nothing was lost, and the hold would sit in the way. Checklist glides the line shut instead.
+- Don't use it for permanent deletion without saying so: a deletion's receipt has no Undo.
+
+<!-- example: generated from build/previews.txt by build/previews.mjs. Edit the preview, not this section. -->
+## Example
+
+`RemovalReceipt` as first used in its preview:
+
+```tsx
+import { Button, RemovalReceipt, toast } from 'altitude-design';
+
+<RemovalReceipt as="li" key={hook.id} removed={!!receipt} pending={receipt?.pending} arrive={back === hook.id}
+  title={receipt?.undoing ? `Restoring ${hook.name}…` : receipt?.pending ? `Removing ${hook.name}…` : `${hook.name} removed.`}
+  action={receipt && (!receipt.pending || receipt.undoing) &&
+    <Button size="sm" loading={!!receipt.undoing} aria-label={`Undo removing ${hook.name}`} onClick={() => undo(hook)}>Undo</Button>}
+  onClosed={() => {
+    put(hook.id, null); setHooks((list) => list.filter((h) => h.id !== hook.id));
+    toast({ title: `${hook.name} removed.`, action: { label: 'Undo', onClick: () => restore(hook) } });
+  }}>
+  <div className="rr-body"><div className="rr-name">{hook.name}</div><div className="rr-url">{hook.url}</div></div>
+  <Button size="sm" variant="ghost" aria-label={`Remove ${hook.name}`} onClick={() => remove(hook)}>Remove</Button>
+</RemovalReceipt>
+```
+
+The full preview, as rendered in Storybook and checked in CI (`rr`, `rr-hint`, `rr-body`, `rr-name`, `rr-url`, `rr-empty` are the preview page's own layout classes, not Altitude's):
+
+```tsx
+import * as React from 'react';
+import { Button, RemovalReceipt, Toaster, toast } from 'altitude-design';
+
+const HOOKS = [
+  { id: 'h1', name: 'Deploy notifications', url: 'https://hooks.example.com/deploys' },
+  { id: 'h2', name: 'Billing events', url: 'https://hooks.example.com/billing' },
+  { id: 'h3', name: 'New sign-ups', url: 'https://hooks.example.com/signups' },
+  { id: 'h4', name: 'Error alerts', url: 'https://hooks.example.com/errors' },
+];
+// A fictional service: removing and restoring a webhook each take 400ms.
+const later = (value) => new Promise((resolve) => setTimeout(() => resolve(value), 400));
+export default function App() {
+  const [hooks, setHooks] = React.useState(HOOKS);
+  const [receipts, setReceipts] = React.useState({});
+  const [back, setBack] = React.useState(null);
+  const put = (id, value) => setReceipts((r) => { const next = { ...r }; if (value) next[id] = value; else delete next[id]; return next; });
+  const remove = async (hook) => { put(hook.id, { pending: true }); await later(); put(hook.id, { pending: false }); };
+  const undo = async (hook) => { put(hook.id, { pending: true, undoing: true }); await later(); put(hook.id, null); };
+  const restore = async (hook) => {
+    await later();
+    setHooks((list) => HOOKS.filter((h) => h.id === hook.id || list.some((x) => x.id === h.id)));
+    setBack(hook.id);
+  };
+  return (
+    <section className="rr" aria-labelledby="rr-title">
+      <h3 id="rr-title">Webhooks</h3>
+      <p className="rr-hint">Remove one: its result stays in its place, then the list closes up. Point at the result to keep it.</p>
+      <ul>
+        {hooks.map((hook) => {
+          const receipt = receipts[hook.id];
+          return (
+            <RemovalReceipt as="li" key={hook.id} removed={!!receipt} pending={receipt?.pending} arrive={back === hook.id}
+              title={receipt?.undoing ? `Restoring ${hook.name}…` : receipt?.pending ? `Removing ${hook.name}…` : `${hook.name} removed.`}
+              action={receipt && (!receipt.pending || receipt.undoing) &&
+                <Button size="sm" loading={!!receipt.undoing} aria-label={`Undo removing ${hook.name}`} onClick={() => undo(hook)}>Undo</Button>}
+              onClosed={() => {
+                put(hook.id, null); setHooks((list) => list.filter((h) => h.id !== hook.id));
+                toast({ title: `${hook.name} removed.`, action: { label: 'Undo', onClick: () => restore(hook) } });
+              }}>
+              <div className="rr-body"><div className="rr-name">{hook.name}</div><div className="rr-url">{hook.url}</div></div>
+              <Button size="sm" variant="ghost" aria-label={`Remove ${hook.name}`} onClick={() => remove(hook)}>Remove</Button>
+            </RemovalReceipt>
+          );
+        })}
+      </ul>
+      {!hooks.length && <p className="rr-empty">No webhooks.</p>}
+      <Toaster />
+    </section>
+  );
+}
+```
+<!-- /example -->