altitude-design 0.4.0 → 0.4.2

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

@@ -26,3 +26,43 @@ Roles against permissions: "Admins can manage billing, Members can invite, Viewe
 - Do return a promise from `onChange` so a cell shows it's saving.
 - Don't draw inherited grants as disabled checkboxes.
 - Don't lift the active cell; it's a ring.
+
+<!-- example: generated from build/previews.txt by build/previews.mjs. Edit the preview, not this section. -->
+## Example
+
+`PermissionMatrix` as first used in its preview:
+
+```tsx
+import { PermissionMatrix } from 'altitude-design';
+
+<PermissionMatrix aria-label="Role permissions" roles={roles} permissions={perms} value={grants} inherited={inherited}
+  onChange={(role, perm, on) => new Promise((r) => setTimeout(() => { setGrants((g) => ({ ...g, [role]: { ...g[role], [perm]: on } })); r(); }, 600))} />
+```
+
+The full preview, as rendered in Storybook and checked in CI (`col`, `cap` are the preview page's own layout classes, not Altitude's):
+
+```tsx
+import * as React from 'react';
+import { PermissionMatrix } from 'altitude-design';
+
+const roles = [{ id: 'owner', name: 'Owner', locked: true }, { id: 'admin', name: 'Admin' }, { id: 'member', name: 'Member' }, { id: 'viewer', name: 'Viewer' }];
+const perms = [
+  { id: 'billing.view', name: 'View invoices', group: 'Billing' }, { id: 'billing.manage', name: 'Manage billing', group: 'Billing' },
+  { id: 'members.invite', name: 'Invite members', group: 'Members' }, { id: 'members.remove', name: 'Remove members', group: 'Members' },
+  { id: 'projects.create', name: 'Create projects', group: 'Projects' }, { id: 'projects.view', name: 'View projects', group: 'Projects' },
+];
+export default function App() {
+  const [grants, setGrants] = React.useState({ admin: { 'billing.view': true, 'billing.manage': true, 'members.invite': true, 'members.remove': true, 'projects.create': true },
+    member: { 'members.invite': true, 'projects.create': true }, viewer: {} });
+  // Everyone can view projects; admins inherit invoices from Billing admins in this example.
+  const inherited = (role, perm) => (perm === 'projects.view' ? { granted: true, from: 'Everyone' } : role === 'viewer' && perm.startsWith('billing') ? { granted: false, from: 'Guest policy' } : undefined);
+  return (
+    <div className="col">
+      <PermissionMatrix aria-label="Role permissions" roles={roles} permissions={perms} value={grants} inherited={inherited}
+        onChange={(role, perm, on) => new Promise((r) => setTimeout(() => { setGrants((g) => ({ ...g, [role]: { ...g[role], [perm]: on } })); r(); }, 600))} />
+      <p className="cap">Editable grants are checkboxes. Owner's and inherited grants are stamped into the record: they're decided, not unavailable. Arrow keys move; Space toggles.</p>
+    </div>
+  );
+}
+```
+<!-- /example -->

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

@@ -10,3 +10,45 @@ Shows a group of items as a stack. Its thickness says roughly how many; click it
 
 - Leave room below a pile, or near the bottom of the viewport the list may run off-screen.
 - Use piles for collections people triage: review queues, inboxes, stacks of drafts.
+
+<!-- example: generated from build/previews.txt by build/previews.mjs. Edit the preview, not this section. -->
+## Example
+
+`Pile` as first used in its preview:
+
+```tsx
+import { Pile } from 'altitude-design';
+
+<Pile count={1} className="p"><div className="face"><b>Drafts</b><span>1 document</span></div></Pile>
+```
+
+The full preview, as rendered in Storybook and checked in CI (`col`, `piles`, `p`, `face`, `wide`, `doc`, `cap` are the preview page's own layout classes, not Altitude's):
+
+```tsx
+import * as React from 'react';
+import { Pile } from 'altitude-design';
+
+const docs = [
+  ['Pricing page copy', 'Three tiers, annual toggle, FAQ.', 'Mara · 2h'], ['Onboarding emails', 'Five-step drip for new workspaces.', 'Jon · yesterday'],
+  ['Q4 launch plan', 'Milestones, owners and risks.', 'Lena · Mon'], ['Release notes 2.4', 'Faster cold starts, new regions.', 'Sam · Mon'],
+  ['Support macros', 'Twelve canned replies, reviewed.', 'Ivy · last week'], ['Brand voice', 'How we sound, with examples.', 'Ada · last week'],
+  ['Security review', 'Findings from the October audit.', 'Theo · Oct 2'],
+];
+export default function App() {
+  const [picked, setPicked] = React.useState(null);
+  return (
+    <div className="col">
+      <div className="piles">
+        <Pile count={1} className="p"><div className="face"><b>Drafts</b><span>1 document</span></div></Pile>
+        <Pile count={3} interactive className="p"><div className="face"><b>Approved</b><span>3 documents</span></div></Pile>
+        <Pile items={docs} className="p wide" onSelect={(d) => setPicked(d[0])} defaultOpen maxHeight={300}
+          renderItem={([t, d, m]) => <div className="doc"><b>{t}</b><span>{d}</span><small>{m}</small></div>}>
+          <div className="face"><b>In review</b><span>{docs.length} documents · click to fan out</span></div>
+        </Pile>
+      </div>
+      <p className="cap">{picked ? `Opened “${picked}”.` : 'One sheet for 2–3 items, two for 4–9, three for 10+; the badge carries the number. Click a pile with items and they fan out over the page below it.'}</p>
+    </div>
+  );
+}
+```
+<!-- /example -->

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

@@ -23,3 +23,40 @@ Choose a plan (Free, Pro, Business) in sign-up, upgrade and downgrade flows, wit
 - Do say why a plan can't be chosen.
 - Don't lift or glow a recommended plan.
 - Don't animate prices counting up when the period changes.
+
+<!-- example: generated from build/previews.txt by build/previews.mjs. Edit the preview, not this section. -->
+## Example
+
+`PlanPicker` as first used in its preview:
+
+```tsx
+import { PlanPicker } from 'altitude-design';
+
+<PlanPicker plans={plans} value={plan} onValueChange={setPlan} current="free" recommended="pro" period={period} onPeriodChange={setPeriod} locale="en-IE" aria-label="Choose a plan" />
+```
+
+The full preview, as rendered in Storybook and checked in CI (`col`, `row` are the preview page's own layout classes, not Altitude's):
+
+```tsx
+import * as React from 'react';
+import { Button, PlanPicker } from 'altitude-design';
+
+const plans = [
+  { id: 'free', name: 'Free', price: 0, currency: 'EUR', unit: 'per seat', features: ['3 projects', 'Community support'] },
+  { id: 'pro', name: 'Pro', price: { month: 2400, year: 2000 }, currency: 'EUR', unit: 'per seat', features: ['Unlimited projects', 'SAML SSO', 'Audit log'] },
+  { id: 'business', name: 'Business', price: { month: 4800, year: 4000 }, currency: 'EUR', unit: 'per seat', features: ['Everything in Pro', 'Custom roles', '99.9% uptime SLA'] },
+  { id: 'enterprise', name: 'Enterprise', price: null, unavailable: 'Contact sales for more than 500 seats.' },
+];
+export default function App() {
+  const [plan, setPlan] = React.useState('free');
+  const [period, setPeriod] = React.useState('year');
+  const name = plans.find((p) => p.id === plan).name;
+  return (
+    <div className="col">
+      <PlanPicker plans={plans} value={plan} onValueChange={setPlan} current="free" recommended="pro" period={period} onPeriodChange={setPeriod} locale="en-IE" aria-label="Choose a plan" />
+      <div className="row"><Button variant="primary" disabled={plan === 'free'}>{plan === 'free' ? 'You\'re on Free' : `Continue to ${name}`}</Button></div>
+    </div>
+  );
+}
+```
+<!-- /example -->

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

@@ -10,3 +10,39 @@ It grows from the trigger's edge (`transform-origin` on that side), rising 6px f
 
 - Do use it for small forms and pickers that belong to one control.
 - Don't use it for a decision that blocks the page; that's a Dialog.
+
+<!-- example: generated from build/previews.txt by build/previews.mjs. Edit the preview, not this section. -->
+## Example
+
+`Popover` as first used in its preview:
+
+```tsx
+import { Button, Field, Input, Popover } from 'altitude-design';
+
+<Popover defaultOpen aria-label="Share" trigger={<Button>Share</Button>}>
+  <div className="col" style={{ width: 280, gap: 12 }}>
+    <b style={{ font: '600 14px/20px var(--font-sans)' }}>Invite to project</b>
+    <Field label="Email address"><Input size="sm" type="email" placeholder="name@company.com" /></Field>
+    <div className="row" style={{ justifyContent: 'flex-end', gap: 8 }}><Button size="sm" variant="primary">Send invite</Button></div>
+  </div>
+</Popover>
+```
+
+The full preview, as rendered in Storybook and checked in CI (`col`, `row` are the preview page's own layout classes, not Altitude's):
+
+```tsx
+import { Button, Field, Input, Popover } from 'altitude-design';
+
+export default function App() {
+  return (
+    <Popover defaultOpen aria-label="Share" trigger={<Button>Share</Button>}>
+      <div className="col" style={{ width: 280, gap: 12 }}>
+        <b style={{ font: '600 14px/20px var(--font-sans)' }}>Invite to project</b>
+        <Field label="Email address"><Input size="sm" type="email" placeholder="name@company.com" /></Field>
+        <div className="row" style={{ justifyContent: 'flex-end', gap: 8 }}><Button size="sm" variant="primary">Send invite</Button></div>
+      </div>
+    </Popover>
+  );
+}
+```
+<!-- /example -->

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

@@ -8,3 +8,34 @@ Determinate progress glides between values on `ease-glide` (`dur-travel-3`). Wit
 
 - Do switch from indeterminate to determinate as soon as you know the total.
 - Don't use it for a reading such as storage used of a quota: that's the record, not a task, so it's a [`Meter`](../Meter/README.md).
+
+<!-- example: generated from build/previews.txt by build/previews.mjs. Edit the preview, not this section. -->
+## Example
+
+`Progress` as first used in its preview:
+
+```tsx
+import { Progress } from 'altitude-design';
+
+<Progress value={v} aria-label="Upload" />
+```
+
+The full preview, as rendered in Storybook and checked in CI (`col`, `wrap`, `cap` are the preview page's own layout classes, not Altitude's):
+
+```tsx
+import * as React from 'react';
+import { Progress } from 'altitude-design';
+
+export default function App() {
+  const [v, setV] = React.useState(20);
+  React.useEffect(() => { const t = setInterval(() => setV((x) => (x >= 100 ? 8 : x + 23)), 1100); return () => clearInterval(t); }, []);
+  return (
+    <div className="col wrap">
+      <Progress value={v} aria-label="Upload" />
+      <Progress aria-label="Loading" />
+      <p className="cap">Determinate glides between values; indeterminate travels.</p>
+    </div>
+  );
+}
+```
+<!-- /example -->

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

@@ -38,3 +38,101 @@ Where a person writes to an assistant or agent: a textarea that grows, attachmen
 - 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

@@ -55,3 +55,83 @@ The record and each property's write, and for Edit all the whole-record write an
 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

@@ -25,3 +25,57 @@ An agent asks the person something before it carries on: "Which environment shou
 - 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

@@ -8,3 +8,40 @@ Each option is a round trench, the same as the switch track. The group owns a si
 
 - 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

@@ -24,3 +24,50 @@ A moment shown as "3 minutes ago", for activity feeds, audit logs, comments and
 - 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

@@ -32,3 +32,80 @@ The slot of an item that can leave its list: a file archived, a webhook removed,
 - 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 -->