altitude-design 0.3.2 → 0.4.1

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

@@ -0,0 +1,54 @@
+# CopyButton
+
+Copies a value and says so: API keys, install commands, invite links, IDs, webhook URLs.
+
+**Elevation.** It's a `Button` (ghost by default, or `secondary`), so it's live: it lifts one level when pointed at. **Copying is a press that confirms in words.** Once copied it stays pressed to the ground for `dur-linger` (2s), its icon cross-fades from copy to a check, and its words change to "Copied". Then it springs back. There's no rise and no afterglow, because nothing new arrived on the page. All its words share one cell, so saying "Copied" never changes its width.
+
+**When it fails.** The Clipboard API needs a secure context and permission. Where it isn't available, CopyButton falls back to selecting a hidden copy of the text and running the copy command. If that fails too, the button says "Couldn't copy" with an alert icon, and "Couldn't copy. Select the text and press ⌘C." (Ctrl+C off a Mac) is announced. `onError` gets the error.
+
+**Accessibility.** It's a plain [button](https://www.w3.org/WAI/ARIA/apg/patterns/button/): Enter or Space copies. The button keeps its name while it says "Copied": a polite status region announces the result instead, so focus never lands on a button whose name just changed. An icon-only CopyButton (no children) is square, named by `label`, and shows `label` in a `Tooltip`. Under forced colours a hovered button gets a 1px border.
+
+**Props:** `value` (a string, or a function returning one or a promise of one); `label` (default "Copy"); `copiedLabel` (default "Copied"); `failedLabel` (default "Couldn't copy"); `onCopy(value)`; `onError(error)`; every `Button` prop except `square`, `loading` and `leading`.
+
+**You provide:** the value, and a `label` that names what's copied ("Copy API key") when the button is icon-only.
+
+```tsx
+<CopyButton value={apiKey} label="Copy API key" />
+<CopyButton value={() => buildInviteUrl()} variant="secondary">Copy invite link</CopyButton>
+```
+
+- Do name what's copied ("Copy API key"), not just "Copy", when there are several on a page.
+- 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

@@ -0,0 +1,157 @@
+# DataGrid
+
+A table whose cells you edit one by one, with spreadsheet keys: arrows to move, type to replace, Enter or F2 to edit, Enter and Tab to save and move on, Escape to back out, a block pasted from a spreadsheet. For bulk entry and correction (prices, stock, schedules, mappings), where opening a form per row is the slowest path.
+
+**Use `DataTable` instead** when cells aren't edited one by one: its rows are records you select, sort, filter and open, and it's a table, not a grid. DataGrid changes the semantics (`role="grid"`, one Tab stop, roving cell focus), so it's a sibling, not a mode.
+
+```tsx
+<DataGrid<Product>
+  aria-label="Inventory"
+  rows={products}
+  getRowId={(p) => p.id}
+  getRowLabel={(p) => p.name}
+  columns={[
+    { key: 'name', header: 'Name', editable: true, validate: (v) => v.trim() ? undefined : 'Enter a name.' },
+    { key: 'sku', header: 'SKU' },                                                   // read-only
+    { key: 'stock', header: 'Stock', align: 'end', editable: true, parse: Number, validate: (n) => n >= 0 ? undefined : 'Use 0 or more.' },
+    { key: 'status', header: 'Status', editable: true, cell: (p) => <Badge>{p.status}</Badge>,
+      editor: (control) => <Select {...control} items={statuses} defaultOpen /> },
+  ]}
+  onCellSave={async ({ rowId, key, draft }) => { const r = await api.patch(rowId, { [key]: draft }); if (r.ok) setProducts(r.all); return r; }}
+  onCellsSave={async (changes) => { const r = await api.batchPatch(changes); if (r.ok) setProducts(r.all); return r; }}
+  onUndo={(last) => revert(last)}
+/>
+```
+
+Writes follow the `InlineEdit` contract: resolve `{ ok: true }` after `rows` carries the canonical value, or `{ ok: false, error }`. `onCellsSave` takes a paste or a cleared range as one batch; without it, each cell goes through `onCellSave`. `onUndo` receives the last committed change (or batch); there's no client-side snapshot.
+
+Data that arrived from elsewhere (an import, a sync) may already break a column's `validate`. `showInvalid` checks every cell at rest: an invalid value lies in a trench on critical-soft with an alert mark, and its problem is the cell's description, so the work left is visible at a glance and each cell says what's wrong. Fixing the value through `onCellSave` lifts it out.
+
+## Elevation
+
+- **Cells** are the record, flush in Table's rows. The **active cell** is a 2px `accent-ink` ring, not a height; a **range** is an `accent-soft` tint with `aria-selected`, because choosing a target isn't live content.
+- **Editable columns** carry a pencil in the header and “editable” in its name. Cells don't lift on hover: a click selects; Enter, F2, typing or a double-click edits.
+- **The cell being edited** opens into a well clipped to the cell, with the held rim. An **invalid** value deepens to a trench on `critical-soft`, with its message beside the cell (`role="alert"`, wired by `aria-describedby`).
+- **Saving** shows a small raised plate in the cell after `dur-grace`, with `aria-busy`. A **failed** cell drops to a trench with a critical mark, keeps its old value, and reopening it restores the rejected draft. A **landed** value settles; a pasted range settles as one change.
+- **A custom editor** (a Select) floats its list at level 3 from inside the cell, and commits on choosing.
+
+Forced colours: the active cell Highlight outline, the range Highlight, the editing cell dashed (thicker when invalid), pending dotted, failed dashed. `contrast="more"`: the editing well gets the solid inner top edge.
+
+## Keyboard
+
+The APG grid, with spreadsheet editing:
+
+| Mode | Key | |
+|---|---|---|
+| Navigation | arrows | one cell (mirrored in RTL); Shift extends a range |
+| | Home / End, Ctrl+Home / Ctrl+End | row ends; grid corners |
+| | PageUp / PageDown | ten rows |
+| | Enter, F2, or a character | edit (a character replaces the value) |
+| | Delete / Backspace | clear the cell or range, as one change that can be refused |
+| | Ctrl/Cmd+C, Ctrl/Cmd+V | copy the range as tab-separated text; paste a block from the active cell |
+| | Ctrl/Cmd+Z | `onUndo` with the last change |
+| Editing | Enter / Shift+Enter | save and move down / up |
+| | Tab / Shift+Tab | save and move right / left |
+| | Escape | discard the draft |
+
+Clicking another cell saves the open one and moves there, as in a spreadsheet; moving focus out of the grid keeps the draft open and marks it “Not saved yet”, rather than saving or discarding it. Nothing acts during IME composition. Announcements are batched: “Saved”, “4 cells saved”, “1 cell couldn't be saved: Price must be at least 0”, “3 by 4 cells selected”.
+
+## Props
+
+| Prop | |
+|---|---|
+| `rows`, `getRowId`, `getRowLabel` | the data; the row label names each cell's editor (“Price, Desk lamp”) |
+| `columns` | `{ key, header, label?, align?, editable?, parse?, format?, validate?, cell?, editor?, width? }` |
+| `onCellSave`, `onCellsSave`, `onUndo` | the writes and their reversal |
+| `maxHeight`, `aria-label`, `aria-labelledby` | |
+
+## You provide
+
+The rows, the writes and their concurrency guards, and undo. Virtualisation, a fill handle and row creation aren't covered yet.
+
+## Do and don't
+
+- **Do** validate in the column, so a bad value never leaves the cell.
+- **Do** give every row a label people would say, for the cell names.
+- **Don't** use it for records people mostly read, select or open: that's `DataTable`.
+
+## Demo and verification
+
+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

@@ -0,0 +1,116 @@
+# DatePicker
+
+Choose a date in a field, by typing it or by picking it from a month calendar. `DateRangePicker` chooses a span of two dates; `Calendar` is the month grid laid on the page on its own.
+
+```tsx
+<Field label="Due date">
+  <DatePicker value={due} onValueChange={setDue} min={today} isUnavailable={(d) => holidays.has(d)} />
+</Field>
+
+<Field label="Trip"><DateRangePicker value={{ start, end }} onValueChange={setTrip} /></Field>
+<DateRangePicker value={range} onValueChange={setRange} presets={[datePresets.today(), datePresets.lastDays(7), datePresets.lastDays(30), datePresets.thisQuarter()]} defaultPreset="last-30-days" />
+
+<Calendar value={day} onValueChange={setDay} aria-label="Delivery day" />
+```
+
+Values are ISO calendar dates, `'YYYY-MM-DD'` strings: no time, no time zone, serialisable, and comparable with `<`. That keeps the bundle free of a date library and avoids `Date`'s time-zone traps (midnight UTC is the previous evening in the Americas). Convert at your edges.
+
+## Elevation
+
+- **The field** is an opening built like `Select`: day, month and year are typed segments in the locale's order. A partial date isn't a value (as a Combobox query isn't), so the floor stays a well; it rises flush only once the field holds a whole, real, allowed date. An impossible or disallowed date drops the field to trench depth with a message (“Enter a real date.”, “Enter a date on or after 26 Oct 2026.”).
+- **The calendar** floats at level 3 (`surface-floating`, `elev-3`) and grows from the field's edge, as a `Popover`.
+- **Days** are flush (ground). At this density a trench per day would be noise, so the RadioGroup's rule is kept by its other half: the chosen day carries the one raised accent mark (`accent` with the sheen, `elev-1`), and choosing another day in the same month carries the mark there (`ease-settle`, `dur-travel-2`). Hovering a day shows a faint ghost of the mark: feedforward.
+- **Today** has an `accent-ink` dot and says “today” in its name. **Unavailable** days are `ink-faint` and say “unavailable”.
+- **A span** (DateRangePicker) is the Slider's build: a sunk `accent-soft` track across the days, between two raised ends. While the end is being chosen, the track previews from the start to the day under the pointer or focus.
+- **Presets** (DateRangePicker `presets`) are a column of rows beside the calendar in the same level-3 panel (above it on narrow screens), built like `Select`'s options: one gliding `accent-soft` highlight, and the chosen row wears the tick at its end. A chosen preset fills the field with its name in `ink` and its dates in `ink-muted` (“Last 30 days · 28 Sept – 27 Oct”), settling with the same brief afterglow as a Select value.
+- **A month change** is lateral, not a change of level, so the grid cross-fades (`dur-travel-1`).
+- **`Calendar`** lies on the page at level 0, with no panel.
+
+Without height: segments are spinbuttons with values; chosen days are `aria-selected` with “start date”/“end date” in a range; the field is `aria-invalid` with its message wired by `aria-describedby`, along with the format (“Format: DD/MM/YYYY”). Forced colours: an empty field is dashed, the panel has a 2px border, the chosen day is Highlight, the span is dashed and today is underlined. `contrast="more"`: the chosen mark gets a 2px ink slab.
+
+## Keyboard
+
+The APG date picker dialog, with React Aria's segmented field:
+
+- **Field**: Tab moves between segments; digits fill a segment and move on once no further digit could fit; ↑/↓ step it; Backspace clears it; ←/→ move between segments (mirrored in RTL); a separator key (`/`, `.`, `-`) moves on. Alt+↓ opens the calendar. The calendar button is “Choose date”.
+- **Grid**: ←/→ a day (mirrored in RTL), ↑/↓ a week, Home/End the week's start and end (by the locale's first day), PageUp/PageDown a month, Shift+PageUp/PageDown a year; Enter or Space chooses, closes and returns focus to the calendar button; Escape closes without a change. Only one day is in the Tab sequence. The month heading is a polite live region.
+- **Presets**: opening the panel focuses the preset list, its own Tab stop before the calendar; ↑/↓ move between rows, Home/End jump, Enter or Space chooses and closes. In the field a chosen preset is one button named in full (“Last 30 days, 28 September 2026 to 27 October 2026”); typing a digit, Backspace or F2 on it turns it back into the date segments to type a custom range. Typing dates or picking days makes the range custom, and the preset is cleared.
+- **Range**: the first choice is the start, the second the end (they swap if the end is earlier); the panel says which it's asking for. A span can't cross an unavailable day.
+
+## Props
+
+| Prop | |
+|---|---|
+| `value`, `defaultValue`, `onValueChange` | `ISODate \| null` (DatePicker), `{ start, end }` (DateRangePicker). `onValueChange` gets a complete, real, allowed date, or `null` when the field is cleared or holds one that isn't allowed |
+| `min`, `max`, `isUnavailable` | limits for choosing and typing |
+| `locale`, `weekStartsOn` | segment order and names (default: the browser's); first day of the week, 0 Sunday … 6 Saturday (default: the locale's, from `Intl.Locale` week info) |
+| `presets` | DateRangePicker: named spans offered beside the calendar. Build them with `datePresets` (`today()`, `yesterday()`, `lastDays(n)` with today included, `thisMonth()`, `lastMonth()`, `thisQuarter()`, `lastQuarter()`, `thisYear()`), or pass `{ key?, label, range }` where `range` is `{ start, end }` or a function of today. A preset whose span falls outside `min`/`max` is disabled |
+| `preset`, `defaultPreset`, `onPresetChange` | the chosen preset's key (`null` when custom), controlled or not. Without a `defaultValue`, `defaultPreset` sets the starting range |
+| `today` | an `ISODate`; relative presets resolve against it, and a chosen one re-resolves when it changes (“Last 7 days” moves with the date). Default: the local date |
+| `id`, `name`, `disabled`, `required`, `invalid`, `size`, `defaultOpen` | as `Select`; `name` submits through a hidden input (`name-start` and `name-end` for a range) |
+
+`Calendar`: `value`, `defaultValue`, `onValueChange`, `min`, `max`, `isUnavailable`, `locale`, `weekStartsOn`, `aria-label`.
+
+## You provide
+
+The value and the rules (limits, unavailable days). Time of day isn't covered (that's a separate `DateTimePicker`).
+
+## Do and don't
+
+- **Do** let people type: a birthday or a date years away is faster typed than paged to.
+- **Do** give a dashboard's range presets: hardly anyone wants to page a calendar for “the last 30 days”. Lead with the few your readers use.
+- **Do** say why a day is unavailable in the field's hint when it isn't obvious.
+- **Don't** convert to `Date` at midnight local time and back; keep ISO dates until you need a moment in time.
+
+## 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

@@ -0,0 +1,204 @@
+# Dialog
+
+Asks for a decision or a focused task at level 5, the summit. The page waits while the dialog is open and through its exit.
+
+By default the app scales back 1.5% and desaturates, the scrim fades in with a 3px blur, and the dialog rises 16px from 96% scale while its shadow grows from `elev-1` to `elev-5` (`dur-travel-5`). It closes faster than it opened, sinking. `background="stationary"` keeps the background in place and removes backdrop blur, including a modal Sheet underneath. Dimming and the dialog's own elevation and motion stay the same. `AltitudeProvider recede={false}` suppresses stage recession for either mode; the default scrim still blurs.
+
+**Where focus lands.** A form starts at its first eligible field by default. A readable structured surface can use `initialFocus="title"`; Tab then reaches the first control and Shift+Tab the last. `focusSelector` selects a different initial target. `initialFocus={false}` focuses the panel as a safe containment fallback until the application moves focus inside. Hidden, disabled, inert and negative-tabindex controls are excluded from Tab traversal. Composition Escape does not dismiss.
+
+**Where focus returns.** Closing retains native background isolation, scroll locking and focus containment through the exit. The captured invoker receives focus afterward when it remains available. If an action removes it, supply a lazy `returnFocus={() => headingRef.current}`; the returned element must be connected, visible, non-inert and in the same document. A static heading needs `tabIndex={-1}`. The surviving provider stage is the final neutral fallback. An older close does not take focus from a newer modal or a valid application completion destination.
+
+**On a phone.** It sizes to the visible viewport, not the largest one: with the on-screen keyboard open it shrinks to the part you can see, so its footer and the focused field stay in reach.
+
+**You provide:** `title`, `description`, optional body, `footer`, `open`/`onOpenChange` or a `trigger`, and `size`. `dismissible={false}` disables Escape, scrim dismissal and the close affordance. `background` defaults to `'recede'`. `returnFocus` is optional for unchanged invokers.
+
+```tsx
+const listHeading = React.useRef<HTMLHeadingElement>(null);
+<Dialog open={open} onOpenChange={setOpen} size="sm"
+  background="stationary" title="Delete this file permanently?"
+  description={`“${target.name}” will be removed. You won’t be able to restore it.`}
+  focusSelector="[data-cancel]" returnFocus={() => listHeading.current}
+  footer={<><Button data-cancel variant="ghost" onClick={() => setOpen(false)}>Cancel</Button>
+    <Button variant="danger" onClick={confirmDelete}>Delete permanently</Button></>} />
+```
+
+This fragment shows presentation only. Use the executable [confirmation recipe](../../visual/ActionsInPlace.md) for target/revision capture, duplicate suppression, retained errors, pending Close, uncertain outcomes and session-safe completion. The application owns dispatched work; closing a Dialog never implies that a write was cancelled.
+
+- 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 -->