altitude-design 0.3.2 → 0.4.1

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

@@ -0,0 +1,193 @@
+# ItemGroup
+
+A list of records shown as slats (media, title, description, actions), changed in the list itself: edit a slat in place, add one at the end, reorder by picking one up, remove one with real recovery. Settings lists (API keys, webhooks, team members), option lists (a form builder's choices) and “add another” sections. It's the Files recipe from [Actions in place](../../visual/ActionsInPlace.md) as a component; the editor is [EditRegion](../EditRegion/README.md).
+
+```tsx
+<ItemGroup<Webhook>
+  aria-label="Webhooks"
+  items={webhooks}
+  getKey={(w) => w.id}
+  getLabel={(w) => w.name}
+  renderItem={(w, { editProps, removeProps }) => (
+    <Item>
+      <ItemMedia><WebhookIcon /></ItemMedia>
+      <ItemContent><ItemTitle>{w.name}</ItemTitle><ItemDescription>{w.url}</ItemDescription></ItemContent>
+      <ItemActions>
+        <Button size="sm" variant="ghost" {...editProps}>Edit</Button>
+        <Button size="sm" variant="ghost" {...removeProps}>Remove</Button>
+      </ItemActions>
+    </Item>
+  )}
+  renderEditor={(field) => <>
+    <Field label="Name" error={field.error('name')}><Input {...field('name')} /></Field>
+    <Field label="Endpoint URL" error={field.error('url')}><Input type="url" {...field('url')} /></Field>
+  </>}
+  onSave={(draft, { previousValue }) => api.updateWebhook(draft, previousValue.revision)}  // EditRegion's contract
+  onItemChange={(w) => setWebhooks((list) => list.map((x) => (x.id === w.id ? w : x)))}
+  newItem={() => ({ id: '', name: '', url: 'https://' })}
+  onCreate={(draft) => api.createWebhook(draft)}           // { ok: true, value } after items includes it
+  addLabel="Add webhook"
+  onReorder={(next) => api.reorder(next.map((w) => w.id))}  // shows grips
+  onRemove={(w) => api.archiveWebhook(w.id)}
+  removal={{ kind: 'recoverable', undo: (w) => api.restoreWebhook(w.id) }}
+  empty={<EmptyState size="sm" title="No webhooks yet" />}
+/>
+```
+
+`removal` has no default, on purpose: say whether removal is recoverable (it happens at once, and Undo calls your real inverse operation) or needs confirmation (`{ kind: 'confirm', title, description?, confirmLabel? }`: a stationary `Dialog` naming the record, Cancel focused). A danger button doesn't imply irreversibility.
+
+A recoverable removal leaves its result where the slat was, as a [RemovalReceipt](../RemovalReceipt/README.md): “Webhook is removed.” with Undo, at the slat's height, so nothing moves while it's read. After the hold the slot closes, and Undo moves to a toast that the group raises itself. Render a `Toaster` once in your app for it to appear. The toast is a supplement to Undo, not the only route back, so keep a durable recovery route of your own (Archived → Restore).
+
+## Elevation
+
+- **Slats** are the record: flush on the ground with `line` dividers, as Table rows, in a plain `ul`. Actions are visible ghost buttons, not hover-only.
+- **Editing**: one slat at a time lifts into its EditRegion, a static raised card holding the fields; its neighbours stay flush and readable. Opening another while one is open keeps the first and moves focus back to it.
+- **The add slat** is an opening: a dashed well (an `EmptyState`-style button) that deepens to a trench under the pointer or focus. Activating it rises into an empty editor in the same place; once added, the new slat settles with an afterglow and a fresh add slat is ready below.
+- **Reordering**: a slat picked up by its grip floats at level 3, tilted, shown where it will land; the slot it leaves opens as a well.
+- **Pending** removals and reorders hover at level 2 after `dur-grace`; known failures are a critical Alert, and the list is unchanged.
+- **Removed** (recoverable): once `onRemove` resolves, the slat's contents cross-fade (`dur-travel-2`) to its receipt in the same slot: a check, “<label> is removed.” in `ink-muted` on the ground, and Undo.
+  - **The hold.** The receipt holds for `dur-linger`, pausing while it's pointed at or focused and waiting while a mouse is still over the list. Then it lifts off and the gap glides shut (`dur-travel-3`, `ease-glide`). Removals due within 250ms of each other close together.
+  - **Undo during the hold.** The slat cross-fades back and settles with an afterglow; nothing moves.
+  - **Undo after the close** is in a toast (“<label> is removed.”, Undo). That Undo glides the slot open where it was, then the slat settles. The toast is withdrawn if the item comes back another way.
+- **Removed** (confirmed): the slat glides shut where it was instead of vanishing. There's no receipt, because there's nothing to undo.
+
+Forced colours: the add slat and slot dashed, the carried slat 2px, pending dotted, a receipt outlined in `CanvasText`. `contrast="more"`: the carried slat gets a 3px slab.
+
+## Keyboard and focus
+
+Tab reaches each slat's controls in order. Edit opens the editor and focuses its first field; Enter in a single-line field saves and Escape cancels (EditRegion's rules), and focus returns to that slat's Edit button. Add focuses the new editor; after it's added, focus goes to the fresh add slat, so several can be added in a row. Remove moves focus to the next slat's Remove, else the previous one's, else the add slat or the list. A receipt's Undo stays in the tab order while it's held (Shift+Tab reaches it), and the hold doesn't expire while focus is in it. After Undo, focus goes to the restored slat's Remove. Grips follow SortableList: Space picks up, ↑/↓ move, Space drops, Escape cancels, with positions announced assertively (“Position 2 of 5”). One polite status announces saved, added, removed (confirmed), restored and errors. A recoverable removal is announced by its receipt (“<label> is removed. Undo is available.”), not by the status as well, and the toast after the close isn't announced again. Under reduced motion the receipt still fades and holds, and the gap closes at once.
+
+## Props
+
+| Prop | |
+|---|---|
+| `items`, `getKey`, `getLabel`, `renderItem` | the slats; `renderItem` gets `edit`, `remove`, and `editProps`/`removeProps` to spread onto visible buttons (name, handler, focus repair) |
+| `renderEditor`, `onSave`, `onItemChange` | the editor's fields; EditRegion's save contract; publish the canonical record |
+| `newItem`, `onCreate`, `addLabel` | the add slat |
+| `onReorder` | grips; resolve after `items` is in the new order |
+| `onRemove`, `removal` | removal and its stated recovery policy |
+| `empty`, `aria-label`, `aria-labelledby` | |
+
+Parts: `Item`, `ItemMedia` (`variant` icon, image or avatar), `ItemContent`, `ItemTitle`, `ItemDescription`, `ItemActions`, `ItemSeparator`.
+
+## You provide
+
+The records, the writes and their concurrency guards, and the recovery policy and its inverse operation. Pointer reordering, multi-select and bulk actions aren't covered yet.
+
+## Do and don't
+
+- **Do** state the removal policy honestly; offer Undo only when you can really reverse it.
+- **Do** keep the editor short; past about five fields, open the record in a `Sheet`.
+- **Don't** hide Edit and Remove behind hover or a “…” menu when there are only one or two.
+
+## Demo and verification
+
+The `ItemGroup` section of `build/previews.txt` shows webhooks (edit, add, reorder, recoverable removal) and a form builder's answer options (empty state, confirmed removal). `node checks/item-group.mjs` (from `build/`; `ALT_FIXTURE_ROOT` selects React 19 fixtures) covers editing and focus return, one editor at a time, adding with field errors and several in a row, keyboard reordering with cancel, confirmed removal with Cancel focused, the empty state, and removal. For removal it checks:
+- the receipt in place with focus repair and a single announcement, and Undo during the hold, with every frame sampled to show nothing below moves;
+- the hold of `dur-linger`, then the gap gliding shut;
+- the toast's unannounced Undo gliding the slot back open;
+- the hold pausing on focus, several removals closing together, reduced motion, and a confirmed slat gliding shut.
+
+It also renders and 320/960px layouts in both schemes under reduced motion, forced colours and `contrast="more"`.
+**Narrow.** When the group is under 480px wide, `ItemActions` moves to its own row under the content, so the title keeps its width; `narrow="inline"` keeps the actions beside it. `ItemDescription truncate` (or a number of lines) clamps a long description.
+
+<!-- example: generated from build/previews.txt by build/previews.mjs. Edit the preview, not this section. -->
+## Example
+
+`ItemGroup` as first used in its preview:
+
+```tsx
+import { Button, Field, Input, Item, ItemActions, ItemContent, ItemDescription, ItemGroup, ItemMedia, ItemTitle } from 'altitude-design';
+
+<ItemGroup aria-labelledby="ig-hooks" items={hooks} getKey={h => h.id} getLabel={h => h.name}
+  renderItem={(h, { editProps, removeProps }) => <Item>
+    <ItemMedia><HookIcon /></ItemMedia>
+    <ItemContent><ItemTitle>{h.name}</ItemTitle><ItemDescription className="ig-url">{h.url}</ItemDescription></ItemContent>
+    <ItemActions><Button size="sm" variant="ghost" {...editProps}>Edit</Button><Button size="sm" variant="ghost" {...removeProps}>Remove</Button></ItemActions>
+  </Item>}
+  renderEditor={field => <>
+    <Field label="Name" required error={field.error('name')}><Input {...field('name')} /></Field>
+    <Field label="Endpoint URL" required error={field.error('url')}><Input {...field('url')} type="url" /></Field>
+  </>}
+  onSave={async (draft, { previousValue }) => {
+    const errors = validate(draft); if (Object.keys(errors).length) return { ok: false, error: 'Check the highlighted fields.', fieldErrors: errors };
+    await igWait(300); return { ok: true, value: { ...draft, name: draft.name.trim(), revision: previousValue.revision + 1 } };
+  }}
+  onItemChange={h => setHooks(list => list.map(x => x.id === h.id ? h : x))}
+  newItem={() => ({ id: '', name: '', url: 'https://', revision: 0 })}
+  onCreate={async draft => {
+    const errors = validate(draft); if (Object.keys(errors).length) return { ok: false, error: 'Check the highlighted fields.', fieldErrors: errors };
+    await igWait(300); const hook = { ...draft, id: 'n' + ++seq.current, name: draft.name.trim(), revision: 1 }; setHooks(list => [...list, hook]); return { ok: true, value: hook };
+  }}
+  addLabel="Add webhook"
+  onReorder={async next => { await igWait(200); setHooks(next); }}
+  onRemove={async h => { await igWait(200); trash.current.set(h.id, hooks.indexOf(h)); setHooks(list => list.filter(x => x.id !== h.id)); }}
+  removal={{ kind: 'recoverable', undo: h => setHooks(list => { const next = [...list]; next.splice(trash.current.get(h.id) ?? next.length, 0, h); return next; }) }} />
+```
+
+The full preview, as rendered in Storybook and checked in CI (`ig-demo`, `ig-url` are the preview page's own layout classes, not Altitude's):
+
+```tsx
+import * as React from 'react';
+import { Button, EmptyState, Field, Input, Item, ItemActions, ItemContent, ItemDescription, ItemGroup, ItemMedia, ItemTitle, Toaster } from 'altitude-design';
+
+const IG_HOOKS = [
+  { id: 'h1', name: 'Production', url: 'https://api.northwind.example/hooks/prod', revision: 1 },
+  { id: 'h2', name: 'Staging', url: 'https://staging.northwind.example/hooks', revision: 1 },
+  { id: 'h3', name: 'Billing events', url: 'https://billing.northwind.example/in', revision: 1 },
+];
+const igWait = ms => new Promise(resolve => setTimeout(resolve, ms));
+const HookIcon = () => <svg width="16" height="16" viewBox="0 0 16 16" fill="none" stroke="currentColor" strokeWidth="1.5" strokeLinecap="round"><path d="M6 4.5a2.5 2.5 0 1 1 3 2.4L7 11" /><path d="M4 12a2.5 2.5 0 1 1 2-4" /><path d="M12 12.5H8" /><circle cx="12" cy="12.5" r="1.5" /></svg>;
+export default function App() {
+  const [hooks, setHooks] = React.useState(IG_HOOKS);
+  const [options, setOptions] = React.useState([]);
+  const trash = React.useRef(new Map());
+  const seq = React.useRef(0);
+  const validate = draft => ({ ...(draft.name.trim() ? {} : { name: 'Enter a name.' }), ...(/^https:\/\/[^\s/]+\.[^\s]+$/.test(draft.url) ? {} : { url: 'Use an https:// address.' }) });
+  return <div className="ig-demo">
+    <section>
+      <h3 id="ig-hooks">Webhooks</h3>
+      <ItemGroup aria-labelledby="ig-hooks" items={hooks} getKey={h => h.id} getLabel={h => h.name}
+        renderItem={(h, { editProps, removeProps }) => <Item>
+          <ItemMedia><HookIcon /></ItemMedia>
+          <ItemContent><ItemTitle>{h.name}</ItemTitle><ItemDescription className="ig-url">{h.url}</ItemDescription></ItemContent>
+          <ItemActions><Button size="sm" variant="ghost" {...editProps}>Edit</Button><Button size="sm" variant="ghost" {...removeProps}>Remove</Button></ItemActions>
+        </Item>}
+        renderEditor={field => <>
+          <Field label="Name" required error={field.error('name')}><Input {...field('name')} /></Field>
+          <Field label="Endpoint URL" required error={field.error('url')}><Input {...field('url')} type="url" /></Field>
+        </>}
+        onSave={async (draft, { previousValue }) => {
+          const errors = validate(draft); if (Object.keys(errors).length) return { ok: false, error: 'Check the highlighted fields.', fieldErrors: errors };
+          await igWait(300); return { ok: true, value: { ...draft, name: draft.name.trim(), revision: previousValue.revision + 1 } };
+        }}
+        onItemChange={h => setHooks(list => list.map(x => x.id === h.id ? h : x))}
+        newItem={() => ({ id: '', name: '', url: 'https://', revision: 0 })}
+        onCreate={async draft => {
+          const errors = validate(draft); if (Object.keys(errors).length) return { ok: false, error: 'Check the highlighted fields.', fieldErrors: errors };
+          await igWait(300); const hook = { ...draft, id: 'n' + ++seq.current, name: draft.name.trim(), revision: 1 }; setHooks(list => [...list, hook]); return { ok: true, value: hook };
+        }}
+        addLabel="Add webhook"
+        onReorder={async next => { await igWait(200); setHooks(next); }}
+        onRemove={async h => { await igWait(200); trash.current.set(h.id, hooks.indexOf(h)); setHooks(list => list.filter(x => x.id !== h.id)); }}
+        removal={{ kind: 'recoverable', undo: h => setHooks(list => { const next = [...list]; next.splice(trash.current.get(h.id) ?? next.length, 0, h); return next; }) }} />
+      <Toaster />
+    </section>
+    <section>
+      <h3 id="ig-options">Answer options</h3>
+      <ItemGroup aria-labelledby="ig-options" items={options} getKey={o => o.id} getLabel={o => o.label}
+        renderItem={(o, { editProps, removeProps }) => <Item><ItemContent><ItemTitle>{o.label}</ItemTitle></ItemContent>
+          <ItemActions><Button size="sm" variant="ghost" {...editProps}>Edit</Button><Button size="sm" variant="ghost" {...removeProps}>Delete</Button></ItemActions></Item>}
+        renderEditor={field => <Field label="Option" required error={field.error('label')}><Input {...field('label')} /></Field>}
+        onItemChange={o => setOptions(list => list.map(x => x.id === o.id ? o : x))}
+        newItem={() => ({ id: '', label: '' })}
+        onCreate={draft => { if (!draft.label.trim()) return { ok: false, error: 'Enter an option.', fieldErrors: { label: 'Enter an option.' } }; const o = { id: 'o' + ++seq.current, label: draft.label.trim() }; setOptions(list => [...list, o]); return { ok: true, value: o }; }}
+        addLabel="Add option" onReorder={setOptions}
+        onRemove={o => setOptions(list => list.filter(x => x.id !== o.id))}
+        removal={{ kind: 'confirm', title: o => `Delete “${o.label}” permanently?`, description: () => 'Responses that chose it keep their answer, but it can’t be chosen again.', confirmLabel: 'Delete option' }}
+        empty={<EmptyState size="sm" title="No options yet" description="Add the answers people can choose from." />} />
+    </section>
+  </div>;
+}
+```
+<!-- /example -->

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

@@ -0,0 +1,36 @@
+# Kbd
+
+Shows a keyboard key as a keycap: a tiny slab with a 2px wall that presses down when the person presses that key.
+
+Keys sit at level 1 in the mono family with `wall-1` under them. With `listen`, the cap drops to the ground (wall gone) while the matching key (a `KeyboardEvent.key`, case-insensitive) is held: a small confirmation that a shortcut registered.
+
+**On touch.** `hideOnTouch` hides a key cap on a touch-only device (no hover, a coarse pointer) until a key is pressed in the session, for a hint that only makes sense with a keyboard. It's off by default, because an app may be documenting its shortcuts on purpose; Altitude's own hints (menu shortcuts, CommandPalette's keys, InlineEdit's save hint) already do this. `useKeyboardLikely()` gives the same answer to your own components.
+
+**You provide:** the key's glyph as children (one `Kbd` per key: `<Kbd>⌘</Kbd><Kbd>K</Kbd>`), and `listen` when the shortcut is live on this page.
+
+<!-- example: generated from build/previews.txt by build/previews.mjs. Edit the preview, not this section. -->
+## Example
+
+`Kbd` as first used in its preview:
+
+```tsx
+import { Kbd } from 'altitude-design';
+
+<Kbd listen="Meta">⌘</Kbd>
+```
+
+The full preview, as rendered in Storybook and checked in CI (`col`, `row`, `body`, `cap` are the preview page's own layout classes, not Altitude's):
+
+```tsx
+import { Kbd } from 'altitude-design';
+
+export default function App() {
+  return (
+    <div className="col">
+      <div className="row"><span className="body">Open the command menu</span><span><Kbd listen="Meta">⌘</Kbd><Kbd listen="k">K</Kbd></span></div>
+      <p className="cap">Click into this card and press ⌘K, or hold K.</p>
+    </div>
+  );
+}
+```
+<!-- /example -->

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

@@ -0,0 +1,109 @@
+# LineChart
+
+Change over time: latency over a day, revenue over a year, one series or a few compared. It renders inside a [`ChartContainer`](../ChartContainer/README.md), which places x by time (ISO dates, timestamps) or by number.
+
+**Why it's flat.** Lines are the record, so they lie on the plot: 2px strokes in their series' colours, round joins and caps, no fill, no glow, no shadow. A missing value (`null`) is a gap in the line, never bridged: nothing was recorded there, as `Await` tells `null` from not-yet. `curve="monotone"` curves through the points without overshooting them (Fritsch–Carlson), so a curve never invents a peak or a dip the data doesn't have. The last point wears an 8px marker, and each line is named at its end in `ink` (up to four series), so the lines are their own legend; end labels are nudged at least 16px apart where lines converge.
+
+**The axis.** Unlike bars, a line's y axis doesn't have to include zero, but its range is always labelled. When zero isn't on it, the plot's foot is drawn as an ordinary gridline, not the ground line, so nothing reads as a baseline that isn't one.
+
+**Without colour.** Under forced colours and in print, and with `patterns` on the container, each line takes its slot's dash and every point its slot's marker (circle, square, triangle, diamond, ring, cross), in `CanvasText` when forced. With `contrast="more"` lines are 3px.
+
+**Motion.** When the data changes and the x values are the same, the line morphs on `ease-glide`; when they differ (a new range), the old chart and the new one cross-fade. A rescale comes first. There's no draw-on animation on first render ([Motion](../../visual/Motion.md), "Charts").
+
+**Accessibility.** Without a written `summary`, the generated one says which way each series went between its first and last values ("p95 rises from 168 ms at 14 Mar, 12:00 AM to 207 ms…"), and its lowest and highest points. The keyboard path along x and between series is #63, the readout #52, and the table view #64.
+
+**Props:** `data` and `x`; `curve` (`'linear'` or `'monotone'`); `y={{ format }}` to format the axis; `endLabels` to turn end labels on or off (default on for up to four series, and always under forced colours and in print). `status` and `boundary` (below); `band={{ low, high, series?, label? }}` for an uncertainty band. `linePath(points, curve)` is exported for your own marks: it draws the same path, gaps and all.
+
+**Selecting and drilling.** `selected` and `onSelect` make the marks a selection that cross-filters the rest of a dashboard, and `drill` opens a level down inside a `Drilldown`. Hover only promises what a click does. See [ChartContainer](../ChartContainer/README.md), "Marks you can select or drill into".
+
+**Filtering in place.** `relevance={(d) => 'match' | 'miss' | undefined}` recedes misses to 35% and keeps everything in place; `rescale` fits the axis to the matches. See [ChartContainer](../ChartContainer/README.md), "Filtering in place".
+
+**Not yet the record.** `status={(d) => d.day > today ? 'projected' : undefined}` dashes the line (5 4) from the last settled point on, and draws those points hollow: ringed in the series colour on the plot's own. It's one path clipped two ways, so a curve doesn't kink where the record ends. A 1px `line-control` rule named "Today" marks the boundary. Point names, the readout's heading and the table say "Projected" or "So far", and the generated summary reads its trend from the settled points only, then says what's projected. While patterns are on, a line that has its own dash keeps it, and the hollow points carry the difference.
+
+**A sliding window.** `window={{ minutes: 15 }}` (or `hours`, `days`, or `points` for the last N records) shows only the latest stretch, and the axis spans exactly that window, however sparse the data. In a `live` container, when the window moves on, x glides one step and the line rides along with it.
+
+**A chosen window.** `window={{ start, end }}` shows a fixed stretch of x, both ends included; a `DateRange` fits as it is. Put a `ChartBrush` inside the chart to pick it on an overview, with `onWindowChange` to hear where it moved.
+
+**Uncertainty is a band.** `band={{ low: 'p10', high: 'p90', label: 'Range 10th–90th percentile' }}` draws a flat fill of the series colour at 16% between the two keys, under the lines. It's never error bars, which readers misjudge (Correll & Gleicher 2014), and never a gradient. Its edges count toward the y axis. The readout adds a row for it ("499–787 Range 10th–90th percentile"), and so do point names and the table.
+
+**Banked to 45°.** `aspect="banked"` lets the data choose the chart's height: slopes read best when the segments average about 45° (Cleveland's banking), so the plot takes the width ÷ height that sets their mean absolute orientation there, held between 1 and 4 for the data area so a card is never a sliver or a tower. Steep, jagged data banks wide; a gentle trend banks tall. The width stays the card's. It's read from every shown series, and kept while values glide; only new x values, which cross-fade as a new chart, bank it afresh, and the height change itself never animates. Put it on the `LineChart` or on the container. In a grid of equal cards, keep a fixed `aspect`: banked neighbours would differ in height.
+
+**Focus.** `focus={['team']}` keeps those lines' colours and draws the rest in `data-context`, their end labels in `ink-muted`; the readout and the keyboard path list the focused lines first. See [ChartContainer](../ChartContainer/README.md), "Focus".
+
+**Against the record before.** `compare={{ data: lastWeek, label: 'Last week' }}` matches records by position (or `key` reads a field on each record) and draws the earlier period as a 1.5px solid `ink-muted` trace under the compared series (`series`, default the first), without points, named at its end in `ink-muted`. It's solid because dashes mean projected, and it follows the data, which a 1px straight reference line never does. The readout, point names, the table and the summary say the difference.
+
+**You provide:** a `ChartContainer` with a `config` naming each series, the `data` in x order, and usually a `summary`.
+
+```tsx
+<ChartContainer config={{ p50: { label: 'p50' }, p95: { label: 'p95' } }} aspect={2.5}>
+  <LineChart data={latency} x="minute" curve="monotone" y={{ format: (ms) => `${ms} ms` }} />
+</ChartContainer>
+```
+
+- Do keep it to four series or fewer; past that, use small multiples, or a legend and the readout.
+- Do leave missing values as `null`; don't fill them with zero or the last value.
+- Do use `monotone` for smooth measures, and `linear` when each point is a discrete count.
+- Don't fill the area under a line to make it look richer; that's `AreaChart`, for a total and its parts.
+- Don't put two measures of different scale on one plot; that's two charts.
+
+<!-- example: generated from build/previews.txt by build/previews.mjs. Edit the preview, not this section. -->
+## Example
+
+`LineChart` as first used in its preview:
+
+```tsx
+import { LineChart } from 'altitude-design';
+
+<LineChart data={latency} x="t" y={{ format: (ms) => `${ms} ms` }} />
+```
+
+The full preview, as rendered in Storybook and checked in CI (`lc` is the preview page's own layout class, not Altitude's):
+
+```tsx
+import { Card, CardContent, CardDescription, CardHeader, CardTitle, ChartContainer, LineChart } from 'altitude-design';
+
+const t0 = Date.UTC(2026, 2, 14, 0, 0);
+const latency = Array.from({ length: 49 }, (_, i) => ({ t: t0 + i * 30 * 60e3, p50: 92 + Math.round(18 * Math.sin(i / 6) + (i % 5)), p95: 168 + Math.round(30 * Math.sin(i / 6 + 0.6) + (i % 7) * 3) }));
+const revenue = ['2025-07-01', '2025-08-01', '2025-09-01', '2025-10-01', '2025-11-01', '2025-12-01', '2026-01-01', '2026-02-01', '2026-03-01', '2026-04-01', '2026-05-01', '2026-06-01']
+  .map((month, i) => ({ month, revenue: [61, 64, 63, 70, 74, 72, 79, 85, 83, 92, 98, 104][i] * 1000 }));
+const signups = Array.from({ length: 14 }, (_, i) => ({ day: `2026-04-${String(i + 1).padStart(2, '0')}`, signups: [42, 48, 51, null, null, 55, 61, 58, 63, null, 66, 70, 68, 74][i] }));
+const signupsBefore = [38, 41, 40, 44, 47, 45, 49, 52, 50, 53, 55, 54, 57, 58].map((signups) => ({ signups }));
+const plans = ['2026-01-01', '2026-02-01', '2026-03-01', '2026-04-01', '2026-05-01', '2026-06-01'].map((month, i) => ({ month, free: 40 + i * 2, team: 34 + i * 3, business: 30 + i * 2.6, enterprise: 12 + i }));
+const usd = new Intl.NumberFormat('en', { style: 'currency', currency: 'USD', notation: 'compact' });
+function Chart({ id, title, sub, children, ...props }) {
+  // With a takeaway the figure names itself: the title becomes the label over the takeaway, the heading.
+  if (props.takeaway) return (
+    <Card>
+      <CardContent style={{ paddingTop: 'var(--space-5)' }}><ChartContainer title={title} description={sub} aspect={1.9} {...props}>{children}</ChartContainer></CardContent>
+    </Card>
+  );
+  return (
+    <Card>
+      <CardHeader><CardTitle id={id}>{title}</CardTitle><CardDescription>{sub}</CardDescription></CardHeader>
+      <CardContent><ChartContainer aria-labelledby={id} aspect={1.9} {...props}>{children}</ChartContainer></CardContent>
+    </Card>
+  );
+}
+export default function App() {
+  return (
+    <div className="lc">
+      <Chart id="l1" title="Response time" sub='14 Mar, every 30 minutes; yLabels="inline"' yLabels="inline" config={{ p50: { label: 'p50' }, p95: { label: 'p95' } }}>
+        <LineChart data={latency} x="t" y={{ format: (ms) => `${ms} ms` }} />
+      </Chart>
+      <Chart id="l2" title="Monthly revenue" takeaway="Revenue rose 70% over the year" sub='curve="monotone": no overshoot' config={{ revenue: { label: 'Revenue', format: usd.format } }} summary="Revenue rose 70% over the year, with small dips in September, December and March.">
+        <LineChart data={revenue} x="month" curve="monotone" />
+      </Chart>
+      <Chart id="l3" title="Daily signups" sub="Gaps stay gaps; read against the two weeks before" config={{ signups: { label: 'Signups' } }}>
+        <LineChart data={signups} x="day" compare={{ data: signupsBefore, label: '2 weeks before' }} />
+      </Chart>
+      <Chart id="l4" title="Seats by plan" sub="Four series, focus on Team: the rest in data-context" config={{ free: { label: 'Free' }, team: { label: 'Team' }, business: { label: 'Business' }, enterprise: { label: 'Enterprise' } }}>
+        <LineChart data={plans} x="month" focus={['team']} />
+      </Chart>
+      <Chart id="l5" title="Monthly revenue, banked" sub='aspect="banked": the segments average 45°' aspect="banked" config={{ revenue: { label: 'Revenue', format: usd.format } }}>
+        <LineChart data={revenue} x="month" curve="monotone" />
+      </Chart>
+    </div>
+  );
+}
+```
+<!-- /example -->

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

@@ -0,0 +1,69 @@
+# Link
+
+Navigation: a link in prose, "Learn more" after a hint, "View all invoices →" at the end of a card, an external link to docs.
+
+**Elevation.** A link is text in the record, so it lies on the ground and **never lifts**. Lifting a word would break its line, and height means "press it", which is what a `Button` is for. It's `accent-ink` with an underline, so it's never told apart by colour alone. Hover thickens the underline from 1px to 2px over `dur-travel-1`. Focus is the 2px `accent-ink` ring at a 2px offset. A standalone link ("View all invoices →") is still ground.
+
+**Link or button?** A link goes somewhere (it has an `href`). A button does something. Don't use a ghost `Button` for navigation: it has the wrong semantics, and it lifts on hover like a slab.
+
+**External links.** `external` opens a new tab with `rel="noopener noreferrer"`, ends with an external-link icon, and adds "(opens in a new tab)" for screen readers.
+
+**Router links.** `asChild` puts the styles and behaviour on your own element (a router's `Link`) instead of rendering an `<a>`.
+
+**Accessibility.** It's a plain `<a href>`, so Enter follows it. Under forced colours it's `LinkText`. Under `contrast="more"` the underline is always 2px. `visited` turns a followed link's underline `ink-muted` (off by default; it helps in long lists of documents).
+
+**Props:** `href` and every anchor attribute; `external`; `asChild`; `visited`.
+
+**You provide:** where it goes, and link text that says where (not "click here").
+
+```tsx
+<Link href="/docs/webhooks">Read about webhooks</Link>
+<Link href="https://status.example.com" external>Status page</Link>
+<Link asChild><NextLink href="/billing">Manage billing</NextLink></Link>
+```
+
+- Do write link text that makes sense on its own ("Read about webhooks", not "here").
+- Do use `external` for anything that leaves your app.
+- Don't use a link for an action (Save, Delete); that's a `Button`.
+- Don't colour a link yourself, or take its underline away inside prose.
+
+<!-- example: generated from build/previews.txt by build/previews.mjs. Edit the preview, not this section. -->
+## Example
+
+`Link` as first used in its preview:
+
+```tsx
+import { Link } from 'altitude-design';
+
+<Link href="#webhooks">Read about webhooks</Link>
+```
+
+The full preview, as rendered in Storybook and checked in CI (`lk`, `col`, `cap` are the preview page's own layout classes, not Altitude's):
+
+```tsx
+import * as React from 'react';
+import { Card, CardContent, CardDescription, CardHeader, CardTitle, Link } from 'altitude-design';
+
+// A router's link, to show asChild: Link styles it and it keeps its own behaviour.
+const RouterLink = React.forwardRef(({ to, ...rest }, ref) => <a ref={ref} href={'#' + to} {...rest} />);
+export default function App() {
+  return (
+    <div className="lk">
+      <div className="col">
+        <p>Webhooks send a signed POST for each event. <Link href="#webhooks">Read about webhooks</Link> before you add an endpoint, or check the <Link href="https://status.example.com" external>status page</Link> if deliveries stop.</p>
+        <p className="cap">In prose, the underline thickens on hover. Nothing lifts, so the line of text stays put.</p>
+      </div>
+      <Card>
+        <CardHeader><CardTitle>Invoices</CardTitle><CardDescription>Your last three invoices</CardDescription></CardHeader>
+        <CardContent>
+          <div className="col">
+            <span>INV-0042 · €49.00 · Paid</span>
+            <Link asChild><RouterLink to="/billing/invoices">View all invoices →</RouterLink></Link>
+          </div>
+        </CardContent>
+      </Card>
+    </div>
+  );
+}
+```
+<!-- /example -->

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

@@ -0,0 +1,113 @@
+# Markdown
+
+An answer's Markdown, set as Altitude prose, as it streams. Models answer in Markdown; `Markdown` renders it in the system's type and hands the parts Altitude already has to their components: fenced code to `CodeBlock`, links to `Link`, `[n]` markers to `InlineCitation`, tables to `Table`'s flush rows, `---` to `Separator`.
+
+**Elevation: the record's typography, adding no height.**
+- **Paragraphs, lists and headings** are on the ground. A `#` heading is the heading style (never the title, which belongs to the page), weight 600; `##` and below step down.
+- **Inline code** has a 1px `line` rim and no fill. **Fenced code** is a `CodeBlock` titled with its language.
+- **Tables** are `Table`'s flush rows with `line` dividers, in a frame that scrolls sideways when the table is wider than the message.
+- **Blockquotes** have a 2px `line` rule at their start. **Task items** have a read-only stamped check.
+- **A citation** is the one part that lifts, by one, when pointed at.
+- **An image** waits in a sunk imprint at a 16:9 size and rises out of it when it loads; if it fails, its alt text shows.
+- **While streaming** an open fence is a streaming `CodeBlock` (dashed rule, "Writing…", `aria-busy`), a table shows nothing until its delimiter row arrives and never a half-received row, and an unclosed `**`, backtick or link shows its words without the markers. The answer as a whole is still carried by `Message status="streaming"`.
+
+**Accessibility.** Plain HTML: headings offset by `headingLevel` (default 3, so `#` is `h3` under the conversation's), lists, `table` with a header row, `blockquote`, `pre`/`code`, `a`. A table is in a focusable region named after its first columns, so it can be scrolled by keyboard. Markdown announces nothing; `Conversation` announces an answer once it completes. Off-site links say "(opens in a new tab)".
+
+**Safety.** Raw HTML in the source is shown as text unless `allowHtml`. URLs pass through `transformUrl`, which by default refuses `javascript:`, `vbscript:`, `file:` and `data:` (except images); a refused link keeps its words.
+
+**Props:** `children` (the source), `streaming`, `citations`, `idPrefix`, `syntax`, `headingLevel`, `components` (`a`, `img`, `code`, `pre`, `table`, `blockquote`), `allowHtml`, `transformUrl`. Also exported: `parseMarkdown`, `safeUrl`.
+
+**You provide:** the text, `streaming` while it arrives, and the sources its `[n]` markers refer to. It covers CommonMark plus GFM tables, task lists, strikethrough and bare links, with no dependencies; footnotes, math and reference-style links aren't parsed. For those, render with your own parser and pass its parts through `components`.
+
+```tsx
+<Message from="assistant" status={m.status}>
+  <MessageContent>
+    <Markdown streaming={m.status === 'streaming'} citations={m.sources} syntax={highlight}>{m.text}</Markdown>
+  </MessageContent>
+</Message>
+```
+
+- Do pass `streaming` while the answer arrives, so half-received constructs don't flash as raw text.
+- Do give each answer its own `idPrefix` when several cite sources on one page.
+- Don't turn on `allowHtml` for model output or anything else you don't control.
+
+<!-- example: generated from build/previews.txt by build/previews.mjs. Edit the preview, not this section. -->
+## Example
+
+`Markdown` as first used in its preview:
+
+```tsx
+import { Markdown } from 'altitude-design';
+
+<Markdown citations={sources}>{done}</Markdown>
+```
+
+The full preview, as rendered in Storybook and checked in CI (`md-demo`, `lbl`, `col` are the preview page's own layout classes, not Altitude's):
+
+```tsx
+import { Markdown } from 'altitude-design';
+
+const sources = [
+  { title: 'Billing FAQ', url: 'https://help.example.com/billing/faq', excerpt: 'Annual plans can be refunded in full within 30 days of purchase.' },
+  { title: 'Plans and pricing', url: 'https://example.com/pricing' },
+];
+const done = [
+  '# Refunds on annual plans',
+  '',
+  'Annual plans are refunded **in full** within 30 days [1]; after that, the unused months are credited as *account balance*, not cash [2].',
+  '',
+  '## What to check first',
+  '',
+  '- [x] The plan was bought less than 30 days ago',
+  '- [ ] No seats were added since',
+  '- [ ] The invoice is `paid`, not ~~pending~~',
+  '',
+  '| Plan | Window | Refund |',
+  '| --- | :---: | ---: |',
+  '| Monthly | none | $0 |',
+  '| Annual | 30 days | 100% |',
+  '',
+  '> Credits never expire, but they can\'t be moved to another workspace.',
+  '',
+  'Issue it from the console:',
+  '',
+  '```sh',
+  'altitude billing refund INV-0042 --full',
+  '```',
+  '',
+  'See [the billing guide](https://help.example.com/billing) for partial refunds.',
+].join('\n');
+const streaming = [
+  '## Steps',
+  '',
+  '1. Find the invoice',
+  '2. Check the **refund window',
+  '',
+  '| Invoice | Amount | Status |',
+  '| --- | ---: | --- |',
+  '| INV-0042 | $480 | paid |',
+  '| INV-0043 | $1',
+].join('\n') + '';
+const streamingCode = ['Run this:', '', '```ts', 'const refund = await billing.refund({', "  invoice: 'INV-0042',"].join('\n');
+export default function App() {
+  return (
+    <div className="md-demo">
+      <div>
+        <p className="lbl">Complete</p>
+        <Markdown citations={sources}>{done}</Markdown>
+      </div>
+      <div className="col">
+        <div>
+          <p className="lbl">Mid-stream: an unclosed bold and a half-received row</p>
+          <Markdown streaming>{streaming}</Markdown>
+        </div>
+        <div>
+          <p className="lbl">Mid-stream: an open fence</p>
+          <Markdown streaming>{streamingCode}</Markdown>
+        </div>
+      </div>
+    </div>
+  );
+}
+```
+<!-- /example -->

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

@@ -0,0 +1,81 @@
+# Meter
+
+Where a reading sits in a known range: storage used of a quota, seats used of a plan, CPU, a score. It isn't a task's progress: a meter doesn't move toward done, and being near the top can be bad. With `segments` it shows parts of a whole (storage by type), the honest replacement for a donut chart.
+
+**Why it's flush, not a trench.** `Progress` and `Meter` look alike and mean different things (see [Charts](../../visual/Charts.md)). `Progress` is a task under way, which is live, so its fill rises out of a trench. A meter's reading is the record, so it lies on the ground: a flush track of `line` with the reading drawn across it as flat ink (`data-1`), with no shadow, wall or sheen.
+
+**Thresholds.** `high` is where the reading is near its limit and `critical` where it's over (by default, anything above `max`). Each threshold inside the range is a 1px `ink-muted` notch standing at the track's rim. Past `high` the fill turns `caution`, and past the limit `critical`, and the meter says so in words ("Near limit", "Over limit") on a `Badge` whose lamp relights when the state changes. Thresholds assume that higher is worse, as for quotas and load. For a score where lower is worse, leave them off and say the state in your own words.
+
+**Segments.** Each part is a flat `data-*` fill in config order (`data-1`, `data-2`, …), parted from the one before by a 2px cut in the surface's own colour, with a legend of each part's value beneath. The segments add up to the reading, and thresholds still apply to the total.
+
+**Motion.** The fill glides to a new reading on `ease-glide` over `dur-travel-3`, as Progress does, and its colour cross-fades when it crosses a threshold. Under reduced motion it changes in place. While the reading loads (`value` undefined) the track is an imprint and lands like `Await` content.
+
+**Accessibility.** The [APG meter pattern](https://www.w3.org/WAI/ARIA/apg/patterns/meter/): `role="meter"` named by its label, with `aria-valuemin`, `aria-valuemax` and `aria-valuenow` (kept within the range when the reading is over it) and an `aria-valuetext` in words: "Storage, 62 GB of 100 GB", "11,800 of 10,000, over limit", "62 GB of 100 GB, Media 38 GB, Documents 14 GB…". Under forced colours the track is outlined, the fill is `Highlight`, the notches are `CanvasText`, and the state is in the words. Under `contrast="more"` the track gets a 1px `ink` edge and the notches are `ink`.
+
+**Props:** `label`; `value`; `min` (default 0); `max` (default 100); `high`; `critical`; `segments` (`{ key, label, value, color? }[]`); `format`; `states` (`{ high, critical }` words); `hideValue`; `locale`.
+
+**You provide:** the reading and its range, the thresholds that matter, and a `format` that names the unit.
+
+```tsx
+<Meter label="Storage" value={62} max={100} high={80} format={(n) => `${n} GB`} />
+<Meter label="Storage by type" max={100} format={(n) => `${n} GB`}
+  segments={[{ key: 'media', label: 'Media', value: 38 }, { key: 'docs', label: 'Documents', value: 14 }, { key: 'other', label: 'Other', value: 10 }]} />
+```
+
+- Do use `Progress` for a task moving toward done, and `Meter` for a reading.
+- Do name the unit in `format` ("62 GB of 100 GB"), not only a percentage.
+- Do use segments for parts of a whole instead of a pie or donut.
+- Don't give it more than six segments; fold the rest into "Other".
+- Don't colour a reading caution or critical yourself; set `high` and `critical`, so the words come with the colour.
+
+<!-- example: generated from build/previews.txt by build/previews.mjs. Edit the preview, not this section. -->
+## Example
+
+`Meter` as first used in its preview:
+
+```tsx
+import { Meter } from 'altitude-design';
+
+<Meter label="Storage" value={used} max={100} high={80} format={gb} />
+```
+
+The full preview, as rendered in Storybook and checked in CI (`mt`, `stack`, `row` are the preview page's own layout classes, not Altitude's):
+
+```tsx
+import * as React from 'react';
+import { Button, Card, CardContent, CardDescription, CardHeader, CardTitle, Meter } from 'altitude-design';
+
+const gb = (n) => `${n} GB`;
+export default function App() {
+  const [used, setUsed] = React.useState(62);
+  const [cpu, setCpu] = React.useState(undefined);
+  React.useEffect(() => { const t = setTimeout(() => setCpu(37), 2400); return () => clearTimeout(t); }, []);
+  return (
+    <div className="mt">
+      <Card>
+        <CardHeader><CardTitle>Plan usage</CardTitle><CardDescription>Thresholds at 80% and the limit</CardDescription></CardHeader>
+        <CardContent className="stack">
+          <Meter label="Storage" value={used} max={100} high={80} format={gb} />
+          <Meter label="Seats" value={24} max={25} high={20} format={(n) => `${n}`} />
+          <Meter label="API calls today" value={11800} max={10000} high={8000} format={(n) => n.toLocaleString('en')} />
+          <Meter label="CPU" value={cpu} format={(n) => `${n}%`} />
+          <div className="row">
+            <Button size="sm" variant="secondary" onClick={() => setUsed((u) => Math.max(0, u - 15))}>Free 15 GB</Button>
+            <Button size="sm" variant="secondary" onClick={() => setUsed((u) => u + 15)}>Use 15 GB</Button>
+          </div>
+        </CardContent>
+      </Card>
+      <Card>
+        <CardHeader><CardTitle>Storage by type</CardTitle><CardDescription>Parts of a whole, instead of a donut</CardDescription></CardHeader>
+        <CardContent className="stack">
+          <Meter label="Storage" max={100} format={gb}
+            segments={[{ key: 'media', label: 'Media', value: 38 }, { key: 'docs', label: 'Documents', value: 14 }, { key: 'mail', label: 'Mail', value: 6 }, { key: 'other', label: 'Other', value: 4 }]} />
+          <Meter label="Team seats" max={50} high={45} format={(n) => `${n}`}
+            segments={[{ key: 'admin', label: 'Admins', value: 4 }, { key: 'members', label: 'Members', value: 31 }, { key: 'guests', label: 'Guests', value: 12 }]} />
+        </CardContent>
+      </Card>
+    </div>
+  );
+}
+```
+<!-- /example -->