altitude-design 0.4.0 → 0.4.2

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

@@ -32,3 +32,63 @@ Approve or reject an action an agent proposes, before anything happens: "Send 21
 - Do name the outcome on Approve.
 - Don't draw a proposal as pending.
 - Don't remove a rejected proposal; keep it in the record.
+
+<!-- example: generated from build/previews.txt by build/previews.mjs. Edit the preview, not this section. -->
+## Example
+
+`Confirmation` as first used in its preview:
+
+```tsx
+import { Confirmation } from 'altitude-design';
+
+<Confirmation state={state} title={title} consequence={consequence} escalate={escalate} approveLabel={approveLabel} rejectLabel={rejectLabel}
+runningLabel={runningLabel} doneLabel={doneLabel} failedLabel={failedLabel} resolvedBy="you" resolvedAt={at} scopes={scopes} resolvedScope={scope}
+onApprove={approve} onReject={() => { setState('rejected'); setAt(new Date()); }} onRetry={() => { setState('running'); setTimeout(() => { setState('done'); setAt(new Date()); }, 1000); }} />
+```
+
+The full preview, as rendered in Storybook and checked in CI (`col` is the preview page's own layout class, not Altitude's):
+
+```tsx
+import * as React from 'react';
+import { Confirmation, Field, Input, Select } from 'altitude-design';
+
+function Proposal({ escalate, title, consequence, approveLabel, rejectLabel, runningLabel, doneLabel, failedLabel, fails, scopes }) {
+  const [state, setState] = React.useState('requested');
+  const [scope, setScope] = React.useState();
+  const [at, setAt] = React.useState();
+  const approve = (s) => { setScope(s); setState('running'); setTimeout(() => { setState(fails ? 'failed' : 'done'); setAt(new Date()); }, 1400); };
+  return <Confirmation state={state} title={title} consequence={consequence} escalate={escalate} approveLabel={approveLabel} rejectLabel={rejectLabel}
+    runningLabel={runningLabel} doneLabel={doneLabel} failedLabel={failedLabel} resolvedBy="you" resolvedAt={at} scopes={scopes} resolvedScope={scope}
+    onApprove={approve} onReject={() => { setState('rejected'); setAt(new Date()); }} onRetry={() => { setState('running'); setTimeout(() => { setState('done'); setAt(new Date()); }, 1000); }} />;
+}
+// Edit what's proposed before approving: the consequence and the button follow the edited values.
+function EditableProposal() {
+  const original = { subject: 'October product update', segment: 'Pro customers', n: 214 };
+  const [v, setV] = React.useState(original);
+  const [state, setState] = React.useState('requested');
+  const [at, setAt] = React.useState();
+  const counts = { 'Pro customers': 214, 'All customers': 1180, 'Trial users': 96 };
+  const edited = v.subject !== original.subject || v.segment !== original.segment;
+  return <Confirmation state={state} title="Send campaign email" consequence={`${v.n} ${v.segment} will receive “${v.subject}”.`}
+    approveLabel={`Send ${v.n} emails`} rejectLabel="Don't send" runningLabel="Sending…" doneLabel="Sent" resolvedBy="you" resolvedAt={at} edited={edited}
+    edit={<>
+      <Field label="Subject"><Input value={v.subject} onChange={(e) => setV({ ...v, subject: e.target.value })} /></Field>
+      <Field label="Segment"><Select value={v.segment} onValueChange={(segment) => setV({ ...v, segment, n: counts[segment] })} items={Object.keys(counts).map((k) => ({ value: k, label: k }))} /></Field>
+    </>}
+    onEditCancel={() => setV(original)}
+    onApprove={() => { setState('running'); setTimeout(() => { setState('done'); setAt(new Date()); }, 1200); }} onReject={() => { setState('rejected'); setAt(new Date()); }} />;
+}
+export default function App() {
+  return (
+    <div className="col">
+      <Proposal title="Send campaign email" consequence="214 Pro customers will receive “October product update”." approveLabel="Send 214 emails" rejectLabel="Don't send" runningLabel="Sending…" doneLabel="Sent" failedLabel="Couldn't send" />
+      <Proposal title="Delete 3 stale branches" consequence="release/2.3, spike/maps and fix/old-auth will be deleted from the repository." approveLabel="Delete 3 branches" rejectLabel="Keep them" runningLabel="Deleting…" doneLabel="Deleted" escalate="hold" />
+      <Proposal title="Archive the Atlas workspace" consequence="12 people lose access; it can't be restored after 30 days." approveLabel="Archive workspace" rejectLabel="Don't archive" runningLabel="Archiving…" failedLabel="Couldn't archive" escalate="dialog" fails />
+      <Proposal title="Run npm test" consequence="Runs the test suite in this workspace." approveLabel="Run once" rejectLabel="Don't run" runningLabel="Running…" doneLabel="Ran"
+        scopes={[{ value: 'session', label: 'Allow npm test for this session' }, { value: 'always', label: 'Always allow npm test', description: 'Saved to this project’s settings' }]} />
+      <EditableProposal />
+    </div>
+  );
+}
+```
+<!-- /example -->

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

@@ -28,3 +28,54 @@ Actions on a thing (a file, a row, a board card, a tree node, a canvas object),
 - Do offer the same actions in a visible menu.
 - Don't nest menus; open a `Dialog` for a long choice.
 - Don't raise the thing while its menu is open; it's outlined.
+
+<!-- example: generated from build/previews.txt by build/previews.mjs. Edit the preview, not this section. -->
+## Example
+
+`ContextMenu` as first used in its preview:
+
+```tsx
+import { Button, ContextMenu, DropdownMenu, Icons } from 'altitude-design';
+
+<ContextMenu key={f} items={() => actions(f)}>
+  <div className="file" role="listitem" tabIndex={0}>
+    <span className="name">{f}</span><span className="meta">Edited 2 days ago</span>
+    <DropdownMenu align="end" items={actions(f)} trigger={<Button variant="ghost" size="sm" square aria-label={`Actions for ${f}`}><Icons.More /></Button>} />
+  </div>
+</ContextMenu>
+```
+
+The full preview, as rendered in Storybook and checked in CI (`col`, `cm2`, `file`, `name`, `meta`, `cap` are the preview page's own layout classes, not Altitude's):
+
+```tsx
+import * as React from 'react';
+import { Button, ContextMenu, DropdownMenu, Icons } from 'altitude-design';
+
+export default function App() {
+  const [files, setFiles] = React.useState(['Q3 board deck.pdf', 'Invoices 2026.xlsx', 'Brand guidelines.fig']);
+  const [said, setSaid] = React.useState('');
+  const actions = (f) => [
+    { label: 'Open', onSelect: () => setSaid(`Opened ${f}.`) },
+    { label: 'Rename', onSelect: () => setSaid(`Renaming ${f}…`) },
+    { label: 'Duplicate', onSelect: () => setSaid(`Duplicated ${f}.`) },
+    { type: 'separator' },
+    { label: 'Delete file', tone: 'critical', onSelect: () => { setFiles((xs) => xs.filter((x) => x !== f)); setSaid(`Deleted ${f}.`); } },
+  ];
+  return (
+    <div className="col">
+      <div className="cm2" role="list" aria-label="Files">
+        {files.map((f) => (
+          <ContextMenu key={f} items={() => actions(f)}>
+            <div className="file" role="listitem" tabIndex={0}>
+              <span className="name">{f}</span><span className="meta">Edited 2 days ago</span>
+              <DropdownMenu align="end" items={actions(f)} trigger={<Button variant="ghost" size="sm" square aria-label={`Actions for ${f}`}><Icons.More /></Button>} />
+            </div>
+          </ContextMenu>
+        ))}
+      </div>
+      <p className="cap" role="status">{said || 'Right-click a file (or long-press, or focus it and press Shift+F10). The same actions are behind each row\'s ⋯ button, because a context menu is never the only way.'}</p>
+    </div>
+  );
+}
+```
+<!-- /example -->

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

@@ -43,3 +43,127 @@ The thread between a person and an assistant: their messages, the assistant's an
 - Do keep earlier versions when regenerating.
 - Don't fade in text word by word or glow a streaming answer.
 - Don't make a streaming answer hover; it isn't a pending write.
+
+<!-- example: generated from build/previews.txt by build/previews.mjs. Edit the preview, not this section. -->
+## Example
+
+`Conversation` as first used in its preview:
+
+```tsx
+import { Conversation, ConversationCheckpoint, ConversationContent, ConversationScrollButton, Message, MessageActions, MessageAttachments, MessageContent } from 'altitude-design';
+
+<Conversation aria-label="Assistant">
+  <ConversationContent>
+    {msgs.map((m) => m.kind === 'checkpoint' ? (
+      <ConversationCheckpoint key={m.id} label={m.label} at={m.at} onRestore={() => restore(m.id)} onReturn={giveBack}
+        consequence="The messages after this will be set aside. You can return to them." />
+    ) : (
+      <Message key={m.id} from={m.from} status={m.status} edited={m.v > 0} onRetry={m.status === 'stopped' ? () => { setStatus('streaming'); stream(m.id); } : undefined}>
+        {m.files && <MessageAttachments items={m.files} />}
+        <MessageContent>{m.text}</MessageContent>
+        {m.from === 'assistant' ? <MessageActions onCopy onRegenerate={() => {}} onFeedback={() => {}} />
+          : <MessageActions onEdit={(t) => edit(m.id, t)} versions={m.versions && { index: m.v + 1, total: m.versions.length, onChange: (k) => showVersion(m.id, k - 1) }} />}
+      </Message>
+    ))}
+  </ConversationContent>
+  <ConversationScrollButton />
+</Conversation>
+```
+
+The full preview, as rendered in Storybook and checked in CI (`cv` is the preview page's own layout class, not Altitude's):
+
+```tsx
+import * as React from 'react';
+import { Conversation, ConversationCheckpoint, ConversationContent, ConversationQueue, ConversationScrollButton, Message, MessageActions, MessageAttachments, MessageContent, PromptInput, PromptInputSubmit, PromptInputTextarea, PromptInputToolbar } from 'altitude-design';
+
+const answer = 'Last week the team shipped 14 changes. Two risks are open: the billing migration is two days behind, and the EU data residency review needs a decision from legal by Friday.';
+export default function App() {
+  const [msgs, setMsgs] = React.useState([
+    { id: 1, from: 'user', text: 'What changed in the Atlas workspace this month?', files: [
+      { name: 'atlas-usage.png', type: 'image/svg+xml', url: "data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='120' height='64'%3E%3Crect width='120' height='64' fill='%23e8edf5'/%3E%3Cpath d='M8 52 L32 36 L56 42 L80 20 L112 12' stroke='%233b6fd8' stroke-width='3' fill='none'/%3E%3C/svg%3E", onOpen: () => {} },
+      { name: 'Atlas changelog.pdf', type: 'application/pdf', size: 482113, href: '#changelog' },
+    ] },
+    { id: 'cp1', kind: 'checkpoint', label: 'Before the Atlas summary', at: '2026-10-30T14:14:00' },
+    { id: 2, from: 'assistant', text: 'Atlas moved to the new permission model on 3 October, and its storage limit was raised to 2 TB. Three people joined: Maya, Theo and Ada.', status: 'complete' },
+  ]);
+  const [status, setStatus] = React.useState('ready');
+  const timer = React.useRef();
+  // Messages written while the assistant works wait in the queue; the first is sent when the turn ends.
+  const [queued, setQueued] = React.useState([]);
+  const queuedRef = React.useRef(queued); queuedRef.current = queued;
+  const sendRef = React.useRef();
+  const stream = (id) => {
+    let n = 0;
+    const tick = () => {
+      n += 6;
+      setMsgs((ms) => ms.map((m) => (m.id === id ? { ...m, text: answer.slice(0, n), status: n >= answer.length ? 'complete' : 'streaming' } : m)));
+      if (n < answer.length) timer.current = setTimeout(tick, 60);
+      else {
+        setStatus('ready');
+        const next = queuedRef.current[0];
+        if (next) { setQueued((q) => q.slice(1)); setTimeout(() => sendRef.current({ text: next.text }), 0); }
+      }
+    };
+    tick();
+  };
+  const enqueue = ({ text }) => setQueued((q) => [...q, { id: String(Date.now()), text }]);
+  const send = ({ text }) => {
+    const id = Date.now();
+    setMsgs((ms) => [...ms, { id: id - 1, from: 'user', text }, { id, from: 'assistant', text: '', status: 'streaming' }]);
+    setStatus('streaming');
+    stream(id);
+  };
+  // Editing a sent message starts a branch from it; the earlier exchange is kept as version 1.
+  const edit = (id, text) => {
+    const i = msgs.findIndex((m) => m.id === id), m = msgs[i];
+    const versions = (m.versions ?? [{ text: m.text, files: m.files }]).map((v, k) => (k === (m.v ?? 0) ? { ...v, rest: msgs.slice(i + 1) } : v));
+    const aid = Date.now();
+    setMsgs([...msgs.slice(0, i), { ...m, text, files: undefined, versions: [...versions, { text }], v: versions.length }, { id: aid, from: 'assistant', text: '', status: 'streaming' }]);
+    setStatus('streaming');
+    stream(aid);
+  };
+  const showVersion = (id, k) => {
+    const i = msgs.findIndex((m) => m.id === id), m = msgs[i];
+    const versions = m.versions.map((v, j) => (j === m.v ? { ...v, rest: msgs.slice(i + 1) } : v));
+    setMsgs([...msgs.slice(0, i), { ...m, text: versions[k].text, files: versions[k].files, versions, v: k }, ...(versions[k].rest ?? [])]);
+  };
+  const sendNow = (id) => {
+    const q = queued.find((x) => x.id === id);
+    setQueued((qs) => qs.filter((x) => x.id !== id));
+    stop();
+    setTimeout(() => sendRef.current({ text: q.text }), 0);
+  };
+  // Restoring a checkpoint sets the turns after it aside; returning brings them back.
+  const aside = React.useRef([]);
+  const restore = (id) => new Promise((done) => setTimeout(() => { setMsgs((ms) => { const i = ms.findIndex((m) => m.id === id); aside.current = ms.slice(i + 1); return ms.slice(0, i + 1); }); done(); }, 900));
+  const giveBack = () => { setMsgs((ms) => [...ms, ...aside.current]); aside.current = []; };
+  const stop = () => { clearTimeout(timer.current); setStatus('ready'); setMsgs((ms) => ms.map((m) => (m.status === 'streaming' ? { ...m, status: 'stopped' } : m))); };
+  sendRef.current = send;
+  return (
+    <div className="cv">
+      <Conversation aria-label="Assistant">
+        <ConversationContent>
+          {msgs.map((m) => m.kind === 'checkpoint' ? (
+            <ConversationCheckpoint key={m.id} label={m.label} at={m.at} onRestore={() => restore(m.id)} onReturn={giveBack}
+              consequence="The messages after this will be set aside. You can return to them." />
+          ) : (
+            <Message key={m.id} from={m.from} status={m.status} edited={m.v > 0} onRetry={m.status === 'stopped' ? () => { setStatus('streaming'); stream(m.id); } : undefined}>
+              {m.files && <MessageAttachments items={m.files} />}
+              <MessageContent>{m.text}</MessageContent>
+              {m.from === 'assistant' ? <MessageActions onCopy onRegenerate={() => {}} onFeedback={() => {}} />
+                : <MessageActions onEdit={(t) => edit(m.id, t)} versions={m.versions && { index: m.v + 1, total: m.versions.length, onChange: (k) => showVersion(m.id, k - 1) }} />}
+            </Message>
+          ))}
+        </ConversationContent>
+        <ConversationScrollButton />
+      </Conversation>
+      <ConversationQueue items={queued} onSendNow={sendNow} onEdit={(id, text) => setQueued((qs) => qs.map((q) => (q.id === id ? { ...q, text } : q)))} onRemove={(id) => setQueued((qs) => qs.filter((q) => q.id !== id))} />
+      <PromptInput onSubmit={send} status={status} onStop={stop} onQueue={enqueue}>
+        <PromptInputTextarea placeholder="Ask about this workspace" />
+        <PromptInputToolbar><PromptInputSubmit /></PromptInputToolbar>
+      </PromptInput>
+    </div>
+  );
+}
+```
+<!-- /example -->

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

@@ -21,3 +21,34 @@ Copies a value and says so: API keys, install commands, invite links, IDs, webho
 - Do put it next to the value it copies, so people can see what they got.
 - Don't confirm a copy with a toast; the button says it where you're looking.
 - Don't make a primary CopyButton: copying is rarely the main thing on a page.
+
+<!-- example: generated from build/previews.txt by build/previews.mjs. Edit the preview, not this section. -->
+## Example
+
+`CopyButton` as first used in its preview:
+
+```tsx
+import { CopyButton } from 'altitude-design';
+
+<CopyButton size="sm" value="sk_live_51Hc8x2Lw9Qe7TfR4mNpZa" label="Copy API key" />
+```
+
+The full preview, as rendered in Storybook and checked in CI (`cb`, `key`, `row`, `cap` are the preview page's own layout classes, not Altitude's):
+
+```tsx
+import { CopyButton } from 'altitude-design';
+
+export default function App() {
+  return (
+    <div className="cb">
+      <div className="key"><code>sk_live_51Hc8x2Lw9Qe7TfR4mNpZa</code><CopyButton size="sm" value="sk_live_51Hc8x2Lw9Qe7TfR4mNpZa" label="Copy API key" /></div>
+      <div className="row">
+        <CopyButton variant="secondary" value={() => 'https://app.example.com/invite/7Fq2'}>Copy invite link</CopyButton>
+        <CopyButton value={() => Promise.reject(new Error('denied'))}>Copy install command</CopyButton>
+      </div>
+      <p className="cap">Copied: pressed to the ground with a check and "Copied" for two seconds, announced politely; the button keeps its name and its width. The last one fails on purpose, to show what a failure says.</p>
+    </div>
+  );
+}
+```
+<!-- /example -->

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

@@ -80,3 +80,78 @@ The rows, the writes and their concurrency guards, and undo. Virtualisation, a f
 The `DataGrid` section of `build/previews.txt` is an inventory grid: the fictional service locks the Desk lamp's price, prices must be 0 or more, and Status uses a Select. `node checks/data-grid.mjs` (from `build/`; `ALT_FIXTURE_ROOT` selects React 19 fixtures) covers the grid keys, type-to-replace, Enter, Tab, F2, Escape, validation, IME Enter, click-to-commit, a refused save and its retry draft, read-only cells, ranges, copy, clearing a range, undo, a paste with one invalid cell, the Select column, and 320/960px layouts in both schemes under reduced motion, forced colours and `contrast="more"`.
 **On a phone.** Under 480px of the frame's width, columns keep at least 6rem (or their `minWidth`) and the table scrolls inside its frame, fading the edge with more columns, instead of squeezing cells. `sticky: true` keeps a column in view over a flush 1px edge. Wide, nothing changes.
 
+<!-- example: generated from build/previews.txt by build/previews.mjs. Edit the preview, not this section. -->
+## Example
+
+`DataGrid` as first used in its preview:
+
+```tsx
+import { Badge, DataGrid, Select } from 'altitude-design';
+
+<DataGrid aria-label="Inventory" rows={rows} getRowId={r => r.id} getRowLabel={r => r.name}
+  columns={[
+    { key: 'name', header: 'Name', editable: true, validate: v => String(v).trim() ? undefined : 'Enter a name.' },
+    { key: 'sku', header: 'SKU' },
+    { key: 'price', header: 'Price', align: 'end', editable: true, parse: t => t.trim() === '' ? '' : Number(t), format: dgMoney,
+      validate: v => v === '' || !Number.isFinite(v) || v < 0 ? 'Use a price of 0 or more.' : undefined, cell: r => `$${r.price}` },
+    { key: 'stock', header: 'Stock', align: 'end', editable: true, parse: t => t.trim() === '' ? 0 : Number(t), format: dgMoney,
+      validate: v => Number.isInteger(v) && v >= 0 ? undefined : 'Use a whole number, 0 or more.' },
+    { key: 'status', header: 'Status', editable: true, format: v => DG_STATUS.find(s => s.value === v)?.label ?? '',
+      cell: r => <Badge tone={r.status === 'active' ? 'positive' : r.status === 'paused' ? 'caution' : 'neutral'}>{DG_STATUS.find(s => s.value === r.status).label}</Badge>,
+      editor: control => <Select {...control} items={DG_STATUS} size="sm" defaultOpen /> },
+  ]}
+  onCellSave={async change => {
+    await dgWait(250);
+    // The demo service locks the lamp's price during a sale.
+    if (change.rowId === 'p1' && change.key === 'price') return { ok: false, error: 'The Desk lamp price is locked during the sale.' };
+    apply([change]); return { ok: true };
+  }}
+  onCellsSave={async changes => { await dgWait(300); apply(changes); return { ok: true }; }}
+  onUndo={last => apply(last.map(c => ({ ...c, draft: c.previousValue })))} />
+```
+
+The full preview, as rendered in Storybook and checked in CI (`dg-demo` is the preview page's own layout class, not Altitude's):
+
+```tsx
+import * as React from 'react';
+import { Badge, DataGrid, Select } from 'altitude-design';
+
+const DG_STATUS = [{ value: 'active', label: 'Active' }, { value: 'paused', label: 'Paused' }, { value: 'retired', label: 'Retired' }];
+const DG_SEED = [
+  { id: 'p1', name: 'Desk lamp', sku: 'LMP-204', price: 49, stock: 120, status: 'active' },
+  { id: 'p2', name: 'Monitor arm', sku: 'ARM-310', price: 89, stock: 34, status: 'active' },
+  { id: 'p3', name: 'Cable tray', sku: 'TRY-118', price: 24, stock: 0, status: 'paused' },
+  { id: 'p4', name: 'Footrest', sku: 'FTR-052', price: 39, stock: 58, status: 'active' },
+  { id: 'p5', name: 'Laptop stand', sku: 'STD-077', price: 59, stock: 12, status: 'retired' },
+];
+const dgWait = ms => new Promise(resolve => setTimeout(resolve, ms));
+const dgMoney = v => v === '' || v === null || v === undefined ? '' : String(v);
+export default function App() {
+  const [rows, setRows] = React.useState(DG_SEED);
+  const apply = changes => setRows(list => list.map(row => changes.reduce((r, c) => c.rowId === r.id ? { ...r, [c.key]: c.draft } : r, row)));
+  return <div className="dg-demo">
+    <DataGrid aria-label="Inventory" rows={rows} getRowId={r => r.id} getRowLabel={r => r.name}
+      columns={[
+        { key: 'name', header: 'Name', editable: true, validate: v => String(v).trim() ? undefined : 'Enter a name.' },
+        { key: 'sku', header: 'SKU' },
+        { key: 'price', header: 'Price', align: 'end', editable: true, parse: t => t.trim() === '' ? '' : Number(t), format: dgMoney,
+          validate: v => v === '' || !Number.isFinite(v) || v < 0 ? 'Use a price of 0 or more.' : undefined, cell: r => `$${r.price}` },
+        { key: 'stock', header: 'Stock', align: 'end', editable: true, parse: t => t.trim() === '' ? 0 : Number(t), format: dgMoney,
+          validate: v => Number.isInteger(v) && v >= 0 ? undefined : 'Use a whole number, 0 or more.' },
+        { key: 'status', header: 'Status', editable: true, format: v => DG_STATUS.find(s => s.value === v)?.label ?? '',
+          cell: r => <Badge tone={r.status === 'active' ? 'positive' : r.status === 'paused' ? 'caution' : 'neutral'}>{DG_STATUS.find(s => s.value === r.status).label}</Badge>,
+          editor: control => <Select {...control} items={DG_STATUS} size="sm" defaultOpen /> },
+      ]}
+      onCellSave={async change => {
+        await dgWait(250);
+        // The demo service locks the lamp's price during a sale.
+        if (change.rowId === 'p1' && change.key === 'price') return { ok: false, error: 'The Desk lamp price is locked during the sale.' };
+        apply([change]); return { ok: true };
+      }}
+      onCellsSave={async changes => { await dgWait(300); apply(changes); return { ok: true }; }}
+      onUndo={last => apply(last.map(c => ({ ...c, draft: c.previousValue })))} />
+    <p>Arrows move, type to replace, Enter or F2 to edit, Tab and Enter save and move. Shift+arrows select; copy and paste a block from a spreadsheet. Ctrl+Z undoes.</p>
+  </div>;
+}
+```
+<!-- /example -->

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

@@ -65,3 +65,52 @@ The value and the rules (limits, unavailable days). Time of day isn't covered (t
 ## Demo and verification
 
 The `DatePicker` section of `build/previews.txt` shows a due date (from today, weekends unavailable, en-GB, open), a trip range and an en-US date. `node checks/date-picker.mjs` (from `build/`; `ALT_FIXTURE_ROOT` selects React 19 fixtures) covers the APG grid keys, RTL arrows, unavailable days, Escape, focus return, segment typing and stepping, impossible dates, Alt+↓, the range flow with its preview, and 320/960px layouts in both schemes under reduced motion, forced colours and `contrast="more"`.
+
+<!-- example: generated from build/previews.txt by build/previews.mjs. Edit the preview, not this section. -->
+## Example
+
+`DatePicker` as first used in its preview:
+
+```tsx
+import { DatePicker } from 'altitude-design';
+
+<DatePicker value={due} onValueChange={setDue} min={DP_TODAY} isUnavailable={weekend} locale="en-GB" defaultOpen />
+```
+
+The full preview, as rendered in Storybook and checked in CI (`dp-demo`, `dp-wide` are the preview page's own layout classes, not Altitude's):
+
+```tsx
+import * as React from 'react';
+import { Button, DatePicker, DateRangePicker, Field, datePresets } from 'altitude-design';
+
+const DP_TODAY = (() => { const t = new Date(); return `${t.getFullYear()}-${String(t.getMonth() + 1).padStart(2, '0')}-${String(t.getDate()).padStart(2, '0')}`; })();
+const dpShift = (iso, days) => { const [y, m, d] = iso.split('-').map(Number); const t = new Date(Date.UTC(y, m - 1, d + days)); return t.toISOString().slice(0, 10); };
+export default function App() {
+  const [due, setDue] = React.useState(dpShift(DP_TODAY, 3));
+  const [trip, setTrip] = React.useState({ start: dpShift(DP_TODAY, 9), end: dpShift(DP_TODAY, 13) });
+  const [start, setStart] = React.useState(null);
+  const [dpToday, setDpToday] = React.useState('2026-10-27');
+  const [period, setPeriod] = React.useState({ start: '2026-09-28', end: '2026-10-27' });
+  const [preset, setPreset] = React.useState('last-30-days');
+  const weekend = iso => { const [y, m, d] = iso.split('-').map(Number); const w = new Date(Date.UTC(y, m - 1, d)).getUTCDay(); return w === 0 || w === 6; };
+  return <div className="dp-demo">
+    <Field label="Due date" hint="Weekends aren’t available.">
+      <DatePicker value={due} onValueChange={setDue} min={DP_TODAY} isUnavailable={weekend} locale="en-GB" defaultOpen />
+    </Field>
+    <div>
+      <Field label="Trip"><DateRangePicker value={trip} onValueChange={setTrip} min={DP_TODAY} locale="en-GB" /></Field>
+      <div style={{ height: 24 }} />
+      <Field label="Start date (US format)"><DatePicker value={start} onValueChange={setStart} locale="en-US" /></Field>
+    </div>
+    <div className="dp-wide">
+      <Field label="Reporting period" hint={`Presets resolve against today (${dpToday}); they stay relative when it changes.`}>
+        <DateRangePicker value={period} onValueChange={setPeriod} preset={preset} onPresetChange={setPreset} today={dpToday} locale="en-GB"
+          presets={[datePresets.today(), datePresets.lastDays(7), datePresets.lastDays(30), datePresets.thisMonth(), datePresets.thisQuarter(), datePresets.lastQuarter(),
+            { key: 'launch', label: 'Since launch', range: { start: '2026-03-04', end: dpToday } }]} />
+      </Field>
+      <div style={{ marginTop: 8 }}><Button size="sm" variant="ghost" onClick={() => setDpToday((t) => dpShift(t, 1))}>Next day</Button></div>
+    </div>
+  </div>;
+}
+```
+<!-- /example -->

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

@@ -27,3 +27,178 @@ This fragment shows presentation only. Use the executable [confirmation recipe](
 - Name the action in the confirm button, such as “Delete permanently”. For irreversible actions, initially focus Cancel.
 - Keep essential errors and progress inside the dialog. Background toast actions are temporarily inert; notification text is routed into its live region.
 - Keep one summit. A Dialog may temporarily suspend a modal Sheet. Competing Dialog/CommandPalette requests are rejected, warn in development, and require `open=false` before a fresh attempt. They never queue. A palette command may close the palette and open a Dialog in the same callback.
+
+<!-- example: generated from build/previews.txt by build/previews.mjs. Edit the preview, not this section. -->
+## Example
+
+`Dialog` as first used in its preview:
+
+```tsx
+import { Alert, Button, Dialog } from 'altitude-design';
+
+<Dialog open={open} onOpenChange={setOpen} background={background} size="sm" title="Delete this file permanently?"
+  description={`“${target?.name || ''}” will be removed. You won’t be able to restore it.`} focusSelector="[data-cancel]" returnFocus={() => heading.current}
+  footer={<><Button data-cancel variant="ghost" onClick={() => setOpen(false)}>{busy ? 'Close' : 'Cancel'}</Button>
+    <Button data-confirm variant="danger" disabled={busy || operation?.state === 'conflict'} onClick={confirm}>{busy ? operation?.state === 'checking' ? 'Checking deletion…' : 'Deleting…' : failed ? 'Try deleting again' : 'Delete permanently'}</Button></>}>
+  <p className="body dialog-target">{target?.name}<br /><span className="cap">{target?.folder}</span></p>
+  {busy && <p role="status">Deletion is in progress. Closing this dialog won’t cancel it.</p>}
+  {failed && <Alert tone="critical" title="File not deleted">{operation.message}{operation.state === 'conflict' && <p>Latest file: {operation.current?.name || 'No longer available'}</p>}</Alert>}
+</Dialog>
+```
+
+The full preview, as rendered in Storybook and checked in CI (`dialog-demo`, `cap`, `body`, `dialog-file`, `dialog-target`, `row` are the preview page's own layout classes, not Altitude's):
+
+```tsx
+import * as React from 'react';
+import { Alert, AltitudeProvider, Button, CommandPalette, Dialog, Input, Sheet, SheetHeader, SheetTitle, Toaster, toast, useAltitude } from 'altitude-design';
+
+const dialogFiles = [
+  { id: 'file-brand', name: 'Brand guidelines.pdf', folder: 'Brand', revision: 1 },
+  { id: 'file-brand-draft', name: 'Brand guidelines draft.pdf', folder: 'Brand', revision: 1 },
+  { id: 'file-launch', name: 'Launch checklist.md', folder: 'Launch', revision: 1 },
+];
+function ModalFrameFixture() {
+  const [open, setOpen] = React.useState(false), [sheet, setSheet] = React.useState(false);
+  React.useEffect(() => { window.altitudeModalFrameFixture = { setOpen, setSheet }; return () => { delete window.altitudeModalFrameFixture; }; }, []);
+  return <AltitudeProvider><p>Independent document fixture</p><Button data-frame-trigger onClick={() => setOpen(true)}>Open frame palette</Button>
+    <CommandPalette open={open} onOpenChange={setOpen} items={[{ items: [{ label: 'Frame command' }] }]} />
+    <Sheet open={sheet} onOpenChange={setSheet}><SheetHeader><SheetTitle>Frame sheet</SheetTitle></SheetHeader><Input aria-label="Frame input" /></Sheet>
+  </AltitudeProvider>;
+}
+export default function App() {
+  const altitude = useAltitude();
+  const releaseLegacy = React.useRef(null);
+  const [rows, setRows] = React.useState(dialogFiles);
+  const server = React.useRef(dialogFiles.map(file => ({ ...file })));
+  const heading = React.useRef(null);
+  const [target, setTarget] = React.useState(null);
+  const [open, setOpen] = React.useState(false);
+  const opened = React.useRef(false); opened.current = open;
+  const [background, setBackground] = React.useState('stationary');
+  const [fixture, setFixture] = React.useState(new URLSearchParams(window.location.search).get('fixture') || 'success-100');
+  const [operation, setOperation] = React.useState(null);
+  const [outcome, setOutcome] = React.useState('');
+  const [present, setPresent] = React.useState(true);
+  const session = React.useRef(0), sequence = React.useRef(0), pending = React.useRef(new Set());
+  const failUsed = React.useRef(false), accepted = React.useRef([]);
+  const invocation = React.useRef(null), mounted = React.useRef(false), epoch = React.useRef(0);
+  const [frame, setFrame] = React.useState(false);
+  const frameRoot = React.useRef(null);
+  const [mode, setMode] = React.useState('');
+  const [sheet, setSheet] = React.useState(false), [nonmodal, setNonmodal] = React.useState(false);
+  const [palette, setPalette] = React.useState(false), [competing, setCompeting] = React.useState(false);
+  const [controls, setControls] = React.useState(true), [inserted, setInserted] = React.useState(false);
+  const [nestedPresent, setNestedPresent] = React.useState(true);
+  const [nested, setNested] = React.useState(false), [toastActions, setToastActions] = React.useState(0);
+  const latest = React.useRef({});
+  React.useEffect(() => { mounted.current = true; return () => { mounted.current = false; epoch.current++; }; }, []);
+  const begin = (file, invoker) => {
+    if (pending.current.has(file.id)) { setOutcome(`Deletion is already in progress for “${file.name}”.`); return; }
+    session.current++; invocation.current = invoker || document.activeElement;
+    setTarget({ ...file, session: session.current }); setOperation(null); setOpen(true); setPresent(true);
+  };
+  const finish = (captured, id, result, ownEpoch) => {
+    pending.current.delete(captured.id);
+    if (!mounted.current || ownEpoch !== epoch.current) return;
+    const matching = session.current === captured.session;
+    if (result === 'success') {
+      const restoreRemoved = !opened.current && document.activeElement === invocation.current && matching;
+      setRows(server.current.map(file => ({ ...file })));
+      setOutcome(`Deleted “${captured.name}”.`);
+      if (matching) { setOperation({ id, session: captured.session, state: 'done' }); setOpen(false); }
+      if (restoreRemoved) requestAnimationFrame(() => heading.current?.focus({ preventScroll: true }));
+    } else {
+      const message = result === 'conflict' ? 'This file changed. Close this dialog and review the latest file before deleting.' : 'The file was not deleted. Try again.';
+      if (matching && opened.current) setOperation({ id, session: captured.session, state: result, message, current: server.current.find(file => file.id === captured.id) });
+      else setOutcome(`“${captured.name}”: ${message}`);
+    }
+  };
+  const confirm = async () => {
+    if (!target || pending.current.has(target.id)) return;
+    const captured = { ...target }, id = `delete-${++sequence.current}`, ownEpoch = epoch.current, behavior = fixture;
+    pending.current.add(captured.id); setOperation({ id, session: captured.session, state: 'pending' });
+    const request = { id: captured.id, expectedRevision: captured.revision, operationId: id, outcome: 'pending' };
+    accepted.current.push(request);
+    const reject = behavior === 'fail-once' && !failUsed.current;
+    if (reject) failUsed.current = true;
+    if (behavior === 'unmount') setTimeout(() => { if (epoch.current === ownEpoch && mounted.current) { setPresent(false); setOpen(false); } }, 50);
+    if (behavior === 'interrupted-after-save') {
+      await new Promise(resolve => setTimeout(resolve, 100));
+      if (ownEpoch !== epoch.current) return;
+      const record = server.current.find(file => file.id === captured.id);
+      if (record?.revision === captured.revision) server.current = server.current.filter(file => file.id !== captured.id);
+      await new Promise(resolve => setTimeout(resolve, 1100));
+    } else await new Promise(resolve => setTimeout(resolve, behavior === 'success-1200' || reject || behavior === 'conflict' ? 1200 : 100));
+    if (ownEpoch !== epoch.current) return;
+    if (behavior === 'conflict') { server.current = server.current.map(file => file.id === captured.id ? { ...file, name: 'Brand guidelines revised.pdf', revision: file.revision + 1 } : file); setRows(server.current); }
+    const current = server.current.find(file => file.id === captured.id);
+    let result = !current || current.revision !== captured.revision ? 'conflict' : reject || behavior === 'interrupted-before-save' ? 'failure' : 'success';
+    if (result === 'success') server.current = server.current.filter(file => file.id !== captured.id);
+    if (behavior.startsWith('interrupted')) {
+      if (mounted.current && session.current === captured.session && opened.current) setOperation({ id, session: captured.session, state: 'checking' });
+      await new Promise(resolve => setTimeout(resolve, 200));
+      result = server.current.some(file => file.id === captured.id) ? 'failure' : 'success';
+    }
+    request.outcome = result;
+    finish(captured, id, result, ownEpoch);
+  };
+  const reset = () => {
+    epoch.current++; sequence.current = 0; failUsed.current = false; accepted.current = []; pending.current.clear(); server.current = dialogFiles.map(file => ({ ...file }));
+    setRows(server.current); setOpen(false); setOutcome(''); setOperation(null); setPresent(true); setMode(''); setSheet(false); setNonmodal(false); setPalette(false); setCompeting(false); setNested(false);
+  };
+  latest.current = { legacyVote: () => { releaseLegacy.current = altitude.pushLayer(); }, legacyRelease: () => releaseLegacy.current?.(), begin, reset, setFrame, setMode, setSheet, setNonmodal, setPalette, setCompeting, setNested, setNestedPresent, setControls, setInserted, setPresent, setBackground, setFixture,
+    close: () => setOpen(false), confirm, openFirst: () => begin(server.current[0]),
+    changeTarget: () => { server.current = server.current.map(file => file.id === target?.id ? { ...file, name: file.name.replace('.pdf', ' revised.pdf'), revision: file.revision + 1 } : file); setRows(server.current); },
+    notify: () => toast({ title: 'Background update', duration: 1200, action: { label: 'Undo background change', onClick: () => setToastActions(n => n + 1) } }),
+    snapshot: () => ({ rows, operation, requests: sequence.current, accepted: accepted.current, toastActions, session: session.current, open }) };
+  React.useEffect(() => {
+    window.altitudeModalFixture = new Proxy({}, { get: (_, key) => latest.current[key] });
+    return () => { delete window.altitudeModalFixture; };
+  }, []);
+  const busy = operation?.session === target?.session && ['pending', 'checking'].includes(operation?.state);
+  const failed = operation?.session === target?.session && ['failure', 'conflict'].includes(operation?.state);
+  return <div className="dialog-demo">
+    <header><p className="cap">Files / Archived</p><h1 ref={heading} tabIndex={-1}>Archived files</h1></header>
+    <p className="body">Archived files can be restored. Permanently deleted files cannot.</p>
+    <section aria-label="Archived files">{rows.map(file => <div className="dialog-file" key={file.id}>
+      <div><strong>{file.name}</strong><p className="cap">{file.folder}</p></div>
+      <Button data-file={file.id} onClick={event => begin(file, event.currentTarget)}>Delete permanently</Button>
+    </div>)}</section>
+    <p role="status" data-outcome>{outcome}</p>
+    {present && <Dialog open={open} onOpenChange={setOpen} background={background} size="sm" title="Delete this file permanently?"
+      description={`“${target?.name || ''}” will be removed. You won’t be able to restore it.`} focusSelector="[data-cancel]" returnFocus={() => heading.current}
+      footer={<><Button data-cancel variant="ghost" onClick={() => setOpen(false)}>{busy ? 'Close' : 'Cancel'}</Button>
+        <Button data-confirm variant="danger" disabled={busy || operation?.state === 'conflict'} onClick={confirm}>{busy ? operation?.state === 'checking' ? 'Checking deletion…' : 'Deleting…' : failed ? 'Try deleting again' : 'Delete permanently'}</Button></>}>
+      <p className="body dialog-target">{target?.name}<br /><span className="cap">{target?.folder}</span></p>
+      {busy && <p role="status">Deletion is in progress. Closing this dialog won’t cancel it.</p>}
+      {failed && <Alert tone="critical" title="File not deleted">{operation.message}{operation.state === 'conflict' && <p>Latest file: {operation.current?.name || 'No longer available'}</p>}</Alert>}
+    </Dialog>}
+    <details><summary>Demo controls</summary>
+      <div className="row"><label>Background <select aria-label="Dialog background" value={background} onChange={event => setBackground(event.target.value)}><option value="stationary">Stationary</option><option value="recede">Default recession</option></select></label>
+      <label>Service fixture <select aria-label="Service fixture" value={fixture} onChange={event => setFixture(event.target.value)}><option value="success-100">Success · 100 ms</option><option value="success-1200">Slow success · 1,200 ms</option><option value="fail-once">Fail once, then retry</option><option value="conflict">Record changes before save</option><option value="interrupted-after-save">Connection interrupted after save</option><option value="interrupted-before-save">Connection interrupted before save</option><option value="unmount">Unmount presentation during write</option></select></label>
+      <Button onClick={reset}>Reset fixtures</Button></div>
+      <div className="row"><Button onClick={() => { setControls(true); setMode('title'); }}>Read a structured dialog</Button><Button onClick={() => setMode('field')}>Edit in a dialog</Button><Button onClick={() => setMode('panel')}>Panel-only dialog</Button><Button onClick={() => setSheet(true)}>Open modal sheet</Button><Button onClick={() => setNonmodal(true)}>Open nonmodal sheet</Button><Button onClick={() => setPalette(true)}>Open command palette</Button><Button onClick={() => setNested(true)}>Open nested-provider dialog</Button></div>
+      <p className="cap">Requests: {sequence.current}. Accepted operation log: <output data-operation-log>{JSON.stringify(accepted.current)}</output></p>
+      <p className="cap">Deterministic fictional data. Pending close, failure, conflict, unmount and ownership cases are exercised by the canonical regression harness. <a href="https://github.com/richlaconte/altitude/blob/main/build/previews.txt">Example source</a> · <a href="../../ActionsInPlace.md">Actions in place recipe</a></p>
+    <button data-background-control onClick={() => setOutcome('Background action')}>Background control</button>
+    {inserted && <button data-late-background>New background control</button>}
+      {frame && <iframe srcDoc="<!doctype html><html><head></head><body></body></html>" title="Independent document" style={{ width: '100%', height: 360 }} onLoad={event => {
+        const doc = event.currentTarget.contentDocument;
+        for (const style of document.querySelectorAll('style')) doc.head.append(style.cloneNode(true));
+        frameRoot.current = ReactDOM.createRoot(doc.body); frameRoot.current.render(<ModalFrameFixture />);
+      }} />}
+    </details>
+    <Dialog open={!!mode} onOpenChange={value => { if (!value) setMode(''); }} title="Modal focus fixture" initialFocus={mode === 'title' ? 'title' : mode === 'panel' ? false : 'first-field'} dismissible={mode !== 'panel'} background={background}
+      footer={mode !== 'panel' && controls ? <><button data-first>First control</button><button data-last>Last control</button></> : null}>
+      {mode === 'field' && controls && <Input aria-label="Fixture field" />}<button hidden>Hidden control</button><button disabled>Disabled control</button>
+    </Dialog>
+    <Dialog open={competing} onOpenChange={setCompeting} title="Competing summit" />
+    <Sheet open={sheet} onOpenChange={setSheet}><SheetHeader><SheetTitle>File details</SheetTitle></SheetHeader><Button data-sheet-dialog onClick={() => setMode('title')}>Read details in dialog</Button></Sheet>
+    <Sheet open={nonmodal} onOpenChange={setNonmodal} modal={false}><SheetHeader><SheetTitle>File filters</SheetTitle></SheetHeader><Button data-nonmodal-close onClick={() => setNonmodal(false)}>Close filters</Button></Sheet>
+    <CommandPalette open={palette} onOpenChange={setPalette} items={[{ items: [{ label: 'Read file details', onSelect: () => setMode('title') }] }]} />
+    {nestedPresent && <AltitudeProvider scheme="nightfall" recede={false}><div data-nested-background hidden>Nested workspace</div><Dialog open={nested} onOpenChange={setNested} title="Nested dialog" initialFocus="title" /></AltitudeProvider>}
+    <Toaster />
+  </div>;
+}
+```
+<!-- /example -->