altitude-design 0.3.2 → 0.4.1

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

@@ -0,0 +1,92 @@
+# Stat
+
+The tile at the top of a dashboard: a label, a big number, how it changed and against what ("Active users · 12,480 · Up 8% vs last month: 11,556"). It's often the most-read thing on the page, and sometimes the right answer isn't a chart at all.
+
+**Why it's flush.** A number is the record. A stat has no level of its own: inside a `Card` it lies on the card, on its own it lies on the page. The label is `text-label` in `ink-muted`; the value is `text-title` in `ink`, weight 600, with tabular figures. `size="hero"` sets it in `text-display`, for the one number a view leads with (once per view, as the type scale says). A `trend` sits beside the value, usually a decorative [`Sparkline`](../Sparkline/README.md).
+
+**Up isn't always good.** Without `good`, the change is neutral: `ink-muted` text with an arrow ("↘ Down 12 ms"). Say which direction is good (`good="up"` for users, `good="down"` for an error rate) and the change becomes a `Badge` plate whose lamp is `positive` or `critical`. The word says the direction, the arrow shows it, and the colour says whether it's good, so no cue stands alone. No change reads "No change" and stays neutral.
+
+**Motion.** A changed value cross-fades (`dur-travel-2`) and the stat takes the afterglow (`settle`), within the attention budget. It never counts up: that delays the number for decoration. While the value loads (`undefined`, or a promise) it's an imprint of a number's width under a label already in place, and it lands like any `Await` content. In a `StatGroup` the values land together.
+
+**Accessibility.** Plain HTML: a `section` named by its label, so it reads "Active users, 12,480, Up 8%, vs last month: 11,556". Direction is always a word; the arrow is decorative. With `live`, a changed value is announced politely: "Active users, 12,792, up 10.7% vs last month." Under forced colours the change plate gets a 1px border and the arrow carries direction; under `contrast="more"` it's drawn as `Badge` is.
+
+**Props:** `label`; `value` (a number, a string, `null` for an em dash, `undefined` or a promise while it loads); `format`; `change` (`{ value, vs, previous, format }`: `value` is a fraction by default, so `0.08` reads "Up 8%"; with `format` it's in your units); `good` (`'up'` or `'down'`); `trend`; `help` (a caption of context); `size` (`'default'` or `'hero'`); `live`; `locale`. `StatGroup` lays a row of stats out to wrap (each at least 180px) and lands them together.
+
+**You provide:** the value and, if it changed, by how much and against what, in words. Put each stat in a `Card` on a dashboard; make the card `interactive` if the whole stat opens a report.
+
+```tsx
+<StatGroup aria-label="Last 30 days">
+  <Card><CardContent>
+    <Stat label="Active users" value={metrics?.active} good="up"
+      change={{ value: 0.08, vs: 'last month', previous: 11556 }}
+      trend={<Sparkline data={metrics?.daily} y="active" decorative />} />
+  </CardContent></Card>
+</StatGroup>
+```
+
+- Do say what the change is against ("vs last month"); a percentage alone has no anchor.
+- Do set `good` only when a direction really is good or bad; otherwise leave the change neutral.
+- Do lead a dashboard with stats, then the charts that explain them, then the table that is the record.
+- Don't use `size="hero"` more than once in a view.
+- Don't animate the number counting up, or colour the value itself: colour belongs to the change, and only with `good`.
+
+<!-- example: generated from build/previews.txt by build/previews.mjs. Edit the preview, not this section. -->
+## Example
+
+`Stat` as first used in its preview:
+
+```tsx
+import { Stat } from 'altitude-design';
+
+<Stat label="Monthly recurring revenue" size="hero" value={mrr} format={usd.format} good="up"
+  change={{ value: 0.042, vs: 'September', previous: 176800 }} help="Paid plans only, before refunds." />
+```
+
+The full preview, as rendered in Storybook and checked in CI (`st`, `st-bar` are the preview page's own layout classes, not Altitude's):
+
+```tsx
+import * as React from 'react';
+import { Button, Card, CardContent, Sparkline, Stat, StatGroup } from 'altitude-design';
+
+const stDays = (vals) => vals.map((v, i) => ({ day: `2026-10-${String(i + 1).padStart(2, '0')}`, v }));
+const active = stDays([11.2, 11.4, 11.3, 11.6, 11.5, 11.8, 11.9, 12.0, 11.9, 12.1, 12.2, 12.4, 12.3, 12.48].map((k) => k * 1000));
+const errors = stDays([0.8, 0.9, 0.8, 1.0, 1.1, 1.0, 1.2, 1.3, 1.2, 1.4, 1.5, 1.4, 1.6, 1.7]);
+const usd = new Intl.NumberFormat('en', { style: 'currency', currency: 'USD', maximumFractionDigits: 0 });
+export default function App() {
+  const [n, setN] = React.useState(0);
+  const [mrr, setMrr] = React.useState(undefined);
+  React.useEffect(() => { const t = setTimeout(() => setMrr(184200), 2400); return () => clearTimeout(t); }, []);
+  const users = 12480 + n * 312;
+  return (
+    <div className="st">
+      <Card>
+        <CardContent>
+          <Stat label="Monthly recurring revenue" size="hero" value={mrr} format={usd.format} good="up"
+            change={{ value: 0.042, vs: 'September', previous: 176800 }} help="Paid plans only, before refunds." />
+        </CardContent>
+      </Card>
+      <div className="st-bar">
+        <h3>Last 30 days</h3>
+        <Button variant="secondary" size="sm" onClick={() => setN((k) => k + 1)}>Refresh</Button>
+      </div>
+      <StatGroup aria-label="Last 30 days">
+        <Card><CardContent>
+          <Stat label="Active users" value={users} live good="up" change={{ value: users / 11556 - 1, vs: 'last month', previous: 11556 }}
+            trend={<Sparkline data={active} x="day" y="v" decorative width={72} />} />
+        </CardContent></Card>
+        <Card><CardContent>
+          <Stat label="Error rate" value={1.7 + n * 0.1} format={(v) => `${v.toFixed(1)}%`} good="down" change={{ value: 0.21 + n * 0.07, vs: 'last month' }}
+            trend={<Sparkline data={errors} x="day" y="v" tone="critical" decorative width={72} />} />
+        </CardContent></Card>
+        <Card><CardContent>
+          <Stat label="Median response" value={182 - n * 4} format={(v) => `${v} ms`} change={{ value: -12 - n * 4, vs: 'last week', format: (m) => `${m} ms` }} />
+        </CardContent></Card>
+        <Card><CardContent>
+          <Stat label="Refunds" value={null} help="No refunds this period." />
+        </CardContent></Card>
+      </StatGroup>
+    </div>
+  );
+}
+```
+<!-- /example -->

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

@@ -0,0 +1,90 @@
+# Stepper
+
+Shows where you are in a process of a few steps: done steps settle into the record, the current one stands raised, and steps to come are imprints.
+
+**Elevation.** A stepper is a staircase of plates standing on one ground line, in the same vocabulary as Drilldown's breadcrumb, and each step's height says which of the three things it is.
+
+- **Done: settled into the record.** A plate flush with the ground, its edges stamped like a Badge, wearing the Checkbox family's check: a raised white mark on the accent. Done steps are part of the record now, so they don't stand up.
+- **Current: live.** A raised slab with a wall (`wall-2`, as tall as the primary action), `surface-raised`, its number ringed in `accent-ink`. It has no sheen: sheen means "press me", and the current step does nothing when pressed; its wall is staircase height, as on the breadcrumb's current step.
+- **To come: not built yet.** Imprints pressed into the page (`surface-well`, a dark inner top edge), like Skeleton's.
+
+Connectors between steps are `accent` behind you and `line-control` ahead.
+
+**Advancing** is the record being written. The current step presses down into the ground (`ease-sink`) and its check is stamped in (as a Badge is re-stamped: down 3px, settling, while the tick draws); about 150ms later the next step rises out of its imprint (`dur-travel-3`, `ease-rise`), within the attention budget. Going back runs the other way: the current step sinks back into an imprint and the step you chose rises from the record. Every state uses the same six-layer shadow list, so each animates into the others. Reduced motion keeps the changes of level and drops the travel.
+
+**Keyboard and screen readers.** An `<ol>` (named "Progress" unless you pass `aria-label`) with `aria-current="step"` on the current step. Every step also says its state in words ("Step 2 of 5, completed"), and a polite live region announces the new step when it changes. With `onStepChange`, completed steps become buttons (`role="button"`, Enter or Space) that go back to that step; hovering one shows a ghost of the slab it would become. Steps ahead can't be jumped to. In forced colours the current step has a solid border and steps to come a dashed one.
+
+| Prop | Default | |
+|---|---|---|
+| `steps` | | `{ title, description?, id? }[]` |
+| `current` | | index of the step being worked on; `steps.length` means all done |
+| `onStepChange` | | makes completed steps buttons that go back |
+| `orientation` | `horizontal` | `vertical` stacks the plates, with descriptions under the titles |
+
+**Narrow.** `orientation="auto"` (recommended) lays the steps out in a row when they all fit on one line, and down the page when they don't, so a phone never shows connectors leading to the next line.
+
+**You provide:** `steps` with short titles (one or two words, sentence case), `current`, and the Back and Continue buttons that change it; `onStepChange` if people may revisit completed steps.
+
+- Do keep it to three to six steps; more than that is a list, not a staircase.
+- Don't use it for places people move between freely; that's Tabs, or Drilldown for a hierarchy.
+
+<!-- example: generated from build/previews.txt by build/previews.mjs. Edit the preview, not this section. -->
+## Example
+
+`Stepper` as first used in its preview:
+
+```tsx
+import { Stepper } from 'altitude-design';
+
+<Stepper
+  steps={steps}
+  current={at}
+  onStepChange={setAt}
+  orientation="auto"
+  aria-label="Workspace setup"
+/>
+```
+
+The full preview, as rendered in Storybook and checked in CI (`wrap`, `row`, `cap`, `pair` are the preview page's own layout classes, not Altitude's):
+
+```tsx
+import * as React from 'react';
+import { Button, Stepper } from 'altitude-design';
+
+const steps = [{ title: "Account" }, { title: "Workspace" }, { title: "Invite team" }, { title: "Billing" }, { title: "Launch" }];
+const setup = [
+  { title: "Connect repository", description: "github.com/acme/northwind" },
+  { title: "Configure build", description: "Framework, output directory, env" },
+  { title: "Deploy", description: "First production deployment" }
+];
+export default function App() {
+  const [at, setAt] = React.useState(2);
+  return <div className="wrap">
+  <Stepper
+    steps={steps}
+    current={at}
+    onStepChange={setAt}
+    orientation="auto"
+    aria-label="Workspace setup"
+  />
+  <div className="row">
+    <Button variant="ghost" disabled={at === 0} onClick={() => setAt(at - 1)}>
+      Back
+    </Button>
+    <Button variant="primary" disabled={at === steps.length} onClick={() => setAt(at + 1)}>
+      {at >= steps.length - 1 ? "Finish" : "Continue"}
+    </Button>
+    <span className="cap">
+      Continue presses the current step into the record and raises the next one; click a completed step to go back.
+    </span>
+  </div>
+  <div className="pair">
+    <Stepper steps={setup} current={1} orientation="vertical" aria-label="Deployment setup" />
+    <p className="cap">
+      Vertical: the same plates, stacked. Completed steps are flush and checked, the current one stands on its wall, and steps to come are imprints.
+    </p>
+  </div>
+</div>;
+}
+```
+<!-- /example -->

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

@@ -0,0 +1,87 @@
+# Suggestions
+
+Prompts to start from or follow up with. An empty conversation offers starting points ("Summarise last week's incidents"); a finished answer offers follow-ups ("Compare with Q2"). Choosing one either fills the composer to edit or sends it at once.
+
+**Elevation: things you press.**
+- **Each suggestion** is a small secondary `Button`: raised at level 1 with its wall, lifting to 2 when pointed at, pressed to the ground. Never level 2 at rest: the view's one primary is the composer's Send.
+- **Starters** sit in an `EmptyState` (its sunk opening) and are simply there.
+- **Follow-ups** sit under the answer, inside its `Message`, and cross-fade in over `dur-onset`; they don't rise, because they only became available.
+- **A send-mode suggestion** shows an arrow and is named "…, sends now".
+
+**Accessibility.** A labelled `group` of buttons; with more than four, the toolbar pattern with one tab stop and arrow keys. Enter or Space chooses. After choosing, focus goes to the composer, with the caret at the end when the text was filled in. Follow-ups aren't announced when they arrive; the answer was.
+
+**Props:** `Suggestions`: `aria-label` (required), `mode` (`'fill'` default, or `'send'`), `onChoose(value)`, `arrive` (default true inside a `Message`). `Suggestion`: `value` (filled or sent instead of the label), and button props.
+
+**You provide:** what choosing does. For `fill`, set the composer's value (`PromptInput value`); for `send`, send it.
+
+```tsx
+<Message from="assistant">
+  <MessageContent>…</MessageContent>
+  <Suggestions aria-label="Suggested follow-ups" mode="send" onChoose={send}>
+    <Suggestion>Compare with Q2</Suggestion>
+    <Suggestion value="List the three biggest risks, with owners">Biggest risks</Suggestion>
+  </Suggestions>
+</Message>
+```
+
+- Do keep them short, and few (three is plenty).
+- Do use `fill` when the person will likely want to adjust the prompt.
+- Don't make a suggestion the primary button, or animate follow-ups in with a rise.
+
+<!-- example: generated from build/previews.txt by build/previews.mjs. Edit the preview, not this section. -->
+## Example
+
+`Suggestions` as first used in its preview:
+
+```tsx
+import { Suggestion, Suggestions } from 'altitude-design';
+
+<Suggestions aria-label="Start with" onChoose={setDraft}>
+  <Suggestion>Summarise last week's incidents</Suggestion>
+  <Suggestion>Draft a release note</Suggestion>
+  <Suggestion value="Which of my open pull requests are blocked, and by whom?">What's blocked?</Suggestion>
+</Suggestions>
+```
+
+The full preview, as rendered in Storybook and checked in CI (`sg`, `col`, `lbl` are the preview page's own layout classes, not Altitude's):
+
+```tsx
+import * as React from 'react';
+import { EmptyState, Message, MessageContent, PromptInput, PromptInputSubmit, PromptInputTextarea, PromptInputToolbar, Suggestion, Suggestions } from 'altitude-design';
+
+export default function App() {
+  const [draft, setDraft] = React.useState('');
+  const [sent, setSent] = React.useState([]);
+  return (
+    <div className="sg">
+      <div className="col">
+        <p className="lbl">Starters in an empty conversation (fill the composer)</p>
+        <EmptyState title="Ask about this workspace" description="Pick a starting point, or write your own." size="sm">
+          <Suggestions aria-label="Start with" onChoose={setDraft}>
+            <Suggestion>Summarise last week's incidents</Suggestion>
+            <Suggestion>Draft a release note</Suggestion>
+            <Suggestion value="Which of my open pull requests are blocked, and by whom?">What's blocked?</Suggestion>
+          </Suggestions>
+        </EmptyState>
+        <PromptInput onSubmit={({ text }) => { setSent((s) => [...s, text]); setDraft(''); }} value={draft} onValueChange={setDraft}>
+          <PromptInputTextarea placeholder="Ask anything" />
+          <PromptInputToolbar><PromptInputSubmit /></PromptInputToolbar>
+        </PromptInput>
+      </div>
+      <div className="col">
+        <p className="lbl">Follow-ups under an answer (send at once)</p>
+        <Message from="assistant">
+          <MessageContent>Revenue grew 12% in Q3, led by the annual plan. Churn held at 2.1%.</MessageContent>
+          <Suggestions aria-label="Suggested follow-ups" mode="send" onChoose={(t) => setSent((s) => [...s, t])}>
+            <Suggestion>Compare with Q2</Suggestion>
+            <Suggestion>Make it shorter</Suggestion>
+            <Suggestion value="List the three biggest risks, with owners">Biggest risks</Suggestion>
+          </Suggestions>
+        </Message>
+        {sent.length > 0 && <p className="lbl">Sent: {sent[sent.length - 1]}</p>}
+      </div>
+    </div>
+  );
+}
+```
+<!-- /example -->

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

@@ -0,0 +1,48 @@
+# Surface
+
+The primitive every component is built from: a box placed on one rung of the elevation ladder.
+
+`level` picks the tint and shadow together (`surface-raised` + `elev-1` at level 1, `surface-well` + `well` at −1, and so on), so the two can never drift apart. `interactive` makes it climb one level on hover and focus and drop to ground while pressed.
+
+**You provide:** `level`, children, and padding and radius through `className`/`style` (the default radius is `radius-lg`). With `interactive` and `onClick`, a non-native surface receives button semantics, keyboard focus, Enter activation and Space activation on release. Consumer keyboard handlers can cancel that behavior with `preventDefault()`. Prefer `as="button"` for a single action (its default `type` is `button`) or `as="a" href="…"` for navigation; their native keyboard behavior is preserved. `disabled` or `aria-disabled` prevents activation, including native links without a click callback. Disabled links omit their destination and retain link semantics. Events from nested controls do not activate the containing surface. Keep interactive content outside a native button or link; use a separate named action when a card contains several controls.
+
+**Depth signals** (also on `Card`, and available to your own components through `useDepth`):
+
+| Prop | What it shows |
+|---|---|
+| `settle` | Afterglow. Pass any value; when it changes, the surface tints with `accent-soft`, lifts to `elev-2` and settles back over `dur-settle` (full for 1s, noticeable for ~4s). `true` settles once on mount, for newly added items. |
+| `status` | Commitment. `pending` hovers above the ground after `dur-grace` (so fast saves never flicker) and sets `aria-busy`; changing to `committed` lands with a settle; `failed` drops into a trench on `critical-soft`. Pair it with visible text ("Saving…", "Couldn't save"). |
+| `heldBy` | Possession. `{ name, presence: 1–3 }` lifts it to level 3, outlines it in that `presence-*` colour and shows the name. Use for collaborators editing or dragging it. |
+| `relevance` | Focus+context. `match` rises one level, `miss` sinks into a well in `ink-muted`. Use for filtering in place instead of removing items. |
+
+- Do use Surface for one-off panels, sidebars and app chrome so they share the ladder with the components.
+- Don't set `interactive` on something that doesn't act when clicked: a lift is a promise.
+- Don't stack more than three levels in one region; if you need a fourth, the layout probably wants a dialog or a page.
+
+<!-- example: generated from build/previews.txt by build/previews.mjs. Edit the preview, not this section. -->
+## Example
+
+`Surface` as first used in its preview:
+
+```tsx
+import { Surface } from 'altitude-design';
+
+<Surface level={-1} className="s"><b>level={'{-1}'}</b><span>A well. Holds things; never lifts.</span></Surface>
+```
+
+The full preview, as rendered in Storybook and checked in CI (`grid`, `s` are the preview page's own layout classes, not Altitude's):
+
+```tsx
+import { Surface } from 'altitude-design';
+
+export default function App() {
+  return (
+    <div className="grid" data-tells-ignore="LA4 the three surfaces side by side, to compare">
+      <Surface level={-1} className="s"><b>level={'{-1}'}</b><span>A well. Holds things; never lifts.</span></Surface>
+      <Surface level={1} className="s"><b>level={'{1}'}</b><span>Static grouping. Doesn't react to the pointer.</span></Surface>
+      <Surface level={1} interactive className="s" onClick={() => {}}><b>level={'{1}'} interactive</b><span>Hover: climbs to 2. Press: drops to ground.</span></Surface>
+    </div>
+  );
+}
+```
+<!-- /example -->

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

@@ -0,0 +1,38 @@
+# Switch
+
+Turns a setting on or off immediately: a raised thumb riding in a trench.
+
+The track is level −2 (`surface-trench`, `trench`). Turning it on pours the `accent` into the track behind the thumb (a clip-path that follows it), and the thumb travels on `ease-settle`. Pressing stretches the thumb before it moves. Hover lifts the thumb from level 1 to 2.
+
+**You provide:** `label` (or `aria-label`), and `checked`/`onCheckedChange` or `defaultChecked`. It renders `role="switch"`.
+
+- Do use it only for changes that apply instantly. If the change needs a Save, use a Checkbox.
+
+<!-- example: generated from build/previews.txt by build/previews.mjs. Edit the preview, not this section. -->
+## Example
+
+`Switch` as first used in its preview:
+
+```tsx
+import { Switch } from 'altitude-design';
+
+<Switch label="Sync across devices" defaultChecked />
+```
+
+The full preview, as rendered in Storybook and checked in CI (`col`, `cap` are the preview page's own layout classes, not Altitude's):
+
+```tsx
+import { Switch } from 'altitude-design';
+
+export default function App() {
+  return (
+    <div className="col">
+      <Switch label="Sync across devices" defaultChecked />
+      <Switch label="Email me when someone comments" />
+      <Switch label="Disabled" disabled />
+      <p className="cap">Hold the pointer down: the thumb stretches before it travels.</p>
+    </div>
+  );
+}
+```
+<!-- /example -->

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

@@ -0,0 +1,78 @@
+# SyncIndicator
+
+One honest answer to "is my work saved?", for autosaving editors, optimistic UIs and local-first apps: "Saved", "Saving…", "Offline · 3 changes waiting", "Couldn't sync", "1 conflict to resolve". Write-ups on local-first apps name showing unsynced edits as saved as the most common failure.
+
+**Elevation.** A status plate is a label, and labels never lift. It's a flush `Badge` plate whose lamp relights when the state changes: positive when saved (with "· 2 minutes ago"), pulsing while saving, caution when offline or in conflict, critical when a sync failed. A change of state cross-fades rather than rising, because "things that merely changed state cross-fade". The *items* it covers carry `status="pending"` and hover until they land, so the per-item and the global signals agree. With a `queue`, pressing the plate opens the waiting changes in a `Popover`. The plate then lifts when pointed at, because it acts.
+
+**When it fails.** `failed` shows Retry (`onRetry`). `conflict` shows Resolve (`onOpenConflicts`). The patterns around it (offline queues, conflicts, session expiry) are a framework pattern of their own.
+
+**Accessibility.** The words are a polite status region, said without chatter. "Saved" is said at most every `announceEvery` ms (default 5s), not "Saving… Saved" on every key. "Saving" isn't said. Going offline, failures and conflicts are said at once. With a queue, the plate is a button named by its state ("Offline · 2 changes waiting. Show changes"). Under forced colours the words and the lamp carry it. Under `contrast="more"` the plate gets a `line-control` edge. Under reduced motion the lamp doesn't pulse; the word says "Saving…".
+
+**Props:** `state` (`'saved' | 'saving' | 'offline' | 'failed' | 'conflict'`); `pending`; `conflicts`; `lastSyncedAt`; `onRetry`; `onOpenConflicts`; `queue`; `announceEvery`.
+
+**You provide:** the true state of your sync. Only say "Saved" once the server has acknowledged the change.
+
+```tsx
+<SyncIndicator state={sync.state} pending={sync.queue.length} lastSyncedAt={sync.at}
+  onRetry={sync.retry} onOpenConflicts={openConflicts}
+  queue={sync.queue.map((c) => <Surface key={c.id} status="pending">{c.label}</Surface>)} />
+```
+
+- Do show "Saved" only after the server confirms.
+- Do count what's waiting when offline.
+- Don't put a spinner beside it; the pulsing lamp and the word say it.
+- Don't raise the plate to get attention when a sync fails; the lamp and the words change.
+
+<!-- example: generated from build/previews.txt by build/previews.mjs. Edit the preview, not this section. -->
+## Example
+
+`SyncIndicator` as first used in its preview:
+
+```tsx
+import { Surface, SyncIndicator } from 'altitude-design';
+
+<SyncIndicator state={state} pending={waiting.length} lastSyncedAt={at} conflicts={1} onRetry={() => { setState('saving'); setTimeout(() => { setState('saved'); setAt(new Date()); }, 700); }}
+  onOpenConflicts={() => setState('saved')}
+  queue={waiting.length ? waiting.map((w, i) => <Surface key={i} status="pending" className="change">{w}</Surface>) : undefined} />
+```
+
+The full preview, as rendered in Storybook and checked in CI (`si`, `bar`, `change`, `col`, `cap` are the preview page's own layout classes, not Altitude's):
+
+```tsx
+import * as React from 'react';
+import { Button, Surface, Switch, SyncIndicator, Textarea } from 'altitude-design';
+
+export default function App() {
+  const [text, setText] = React.useState('Q4 goals: grow self-serve revenue 20% and halve time to first value.');
+  const [state, setState] = React.useState('saved');
+  const [at, setAt] = React.useState(() => new Date(Date.now() - 120000));
+  const [offline, setOffline] = React.useState(false);
+  const [waiting, setWaiting] = React.useState([]);
+  const timer = React.useRef();
+  const edit = (v) => {
+    setText(v);
+    if (offline) { setWaiting((w) => [...w.slice(-2), 'Edited the goals paragraph']); setState('offline'); return; }
+    setState('saving'); clearTimeout(timer.current);
+    timer.current = setTimeout(() => { setState('saved'); setAt(new Date()); }, 700);
+  };
+  return (
+    <div className="si">
+      <div>
+        <div className="bar"><span>Q4 planning</span>
+          <SyncIndicator state={state} pending={waiting.length} lastSyncedAt={at} conflicts={1} onRetry={() => { setState('saving'); setTimeout(() => { setState('saved'); setAt(new Date()); }, 700); }}
+            onOpenConflicts={() => setState('saved')}
+            queue={waiting.length ? waiting.map((w, i) => <Surface key={i} status="pending" className="change">{w}</Surface>) : undefined} />
+        </div>
+        <Textarea value={text} onChange={(e) => edit(e.target.value)} aria-label="Q4 goals" />
+      </div>
+      <div className="col">
+        <Switch label="Offline" checked={offline} onCheckedChange={(on) => { setOffline(on); if (!on) { setWaiting([]); setState('saving'); setTimeout(() => { setState('saved'); setAt(new Date()); }, 700); } }} />
+        <Button size="sm" onClick={() => setState('failed')}>Make a save fail</Button>
+        <Button size="sm" onClick={() => setState('conflict')}>Cause a conflict</Button>
+        <p className="cap">Type to save. Go offline and the plate counts what's waiting; press it to see those changes, each hovering until it lands.</p>
+      </div>
+    </div>
+  );
+}
+```
+<!-- /example -->

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

@@ -0,0 +1,138 @@
+# Table
+
+Rows and columns of records: the rows sit on the ground with `line` dividers, and only the ones that are selected, matching, in hand or under your pointer rise.
+
+**Elevation: the record.** A table is the plainest thing in Altitude: its rows are what has been settled, so they lie flush on the ground. Height is spent only on rows that mean something right now:
+
+- **Selected** rows are tinted `accent-soft` and raised one level (`elev-1`), with a checked Checkbox; the toolbar counts them with a count Badge, the one badge that floats, because the count wants your attention.
+- **Interactive** rows (ones that open something) lift one level on hover, a ghost lift; pressing drops them back to the ground. Rows that do nothing don't move at all.
+- **Filtering in place** raises matches one level and sinks misses into a well (`ink-muted`), so the rows keep their places and you can still see what didn't match (Signals: relevance).
+- **Carried** rows: when the order changes (a sort, a move), each row travels to its new place (`dur-travel-3`, `ease-glide`) instead of the table being reshuffled, so you can follow a row you were looking at.
+- **In hand**: a row picked up to reorder floats at level 3, slightly tilted, over a slot that opens as a well where it will land; its neighbours glide aside, as in SortableList.
+
+The header stays flush until rows scroll under it, then rises to `elev-2` (as in ScrollArea); where rows continue below, the bottom edge curves away (`lip-bottom`). Cells can't share one shadow, so each row's height is drawn as a single slab by its first cell, as wide as the table.
+
+**Semantics.** A plain `<table>` with `<th scope="col">`: it's a table, not a grid, because its cells aren't edited or navigated one by one. Sortable headers are buttons, and the `th` carries `aria-sort`. Selection lives in the row's Checkbox (no `aria-selected` on rows of a plain table). An interactive row's first cell is a real button, so the keyboard reaches it; clicking anywhere else on the row does the same. Move handles are buttons: Space picks a row up, ↑ and ↓ move it, Space drops it, Escape puts it back; each step is announced. Selection counts and sort changes are announced too. Forced colours rule raised rows solid and sunk rows dashed.
+
+**Two ways to build one.** The primitives mirror shadcn/ui: `Table` (with `maxHeight` for a scrolling body), `TableHeader`, `TableBody`, `TableFooter`, `TableRow` (`rowId`, `selected`, `interactive`, `relevance`, `settle`, `held`), `TableHead` (`align`, `sort`, `onSort`), `TableCell` (`align`) and `TableCaption`. `DataTable` builds the whole thing from data:
+
+| Prop | |
+|---|---|
+| `columns` | `{ key, header, cell?, sortValue?, align?, width? }[]`; `sortValue` makes a column sortable (ascending, descending, none) |
+| `rows`, `getRowId`, `getRowLabel` | the records, a stable id, and a name for screen readers |
+| `selectable`, `selected`/`onSelectedChange`, `actions` | a checkbox column; actions appear beside the count while rows are selected |
+| `onRowClick` | interactive rows |
+| `relevance` | `(row) => 'match' \| 'miss' \| undefined` for filtering in place |
+| `onReorder` | move handles; hidden while a sort is active |
+| `renderExpanded`, `expanded`/`defaultExpanded`/`onExpandedChange`, `expandMode` | a disclosure button per row opening a full-width detail row (`'single'` by default: one open at a time) |
+| `renderEditor`, `onSave`, `onRowChange` | an Edit button per row that opens the row's fields as an `EditRegion` in a full-width row beneath it (EditRegion's save contract; `onRowChange` publishes the canonical row) |
+| `toolbar`, `maxHeight`, `empty` | a filter field or button at the toolbar's end (at narrow widths the toolbar wraps onto more lines and a field in it shrinks, so nothing scrolls sideways); scroll height; text for no rows |
+
+**Loading.** While `DataTable`'s `rows` is undefined (your query hasn't returned) or a promise, the table keeps its real header over `skeleton.lines` rows of imprinted cells (default 5), so columns don't jump (see `Await`). An empty array is an empty table.
+
+**Opening a row.** Read-only detail (`renderExpanded`) is a reveal of the record, so it stays on the ground: a full-width row under the record, inset, with the disclosure chevron turned and `aria-expanded`/`aria-controls` on its button. Editing (`renderEditor` + `onSave`) is live, so it rises: the row and its region become one raised slab (`elev-1`) holding a static `EditRegion`, with the row's cells still visible above it so the record stays identified. The first field takes focus; Enter in a single-line field saves and Escape cancels, and focus returns to the row's Edit button. While a row is in edit, the other rows' Edit buttons, sorting and reordering wait, so the edited row isn't carried away mid-edit; once saved it settles with an afterglow and, if its sort position changed, is carried to its new place. It stays a table, not a grid: the region is one `td` spanning the row. Above about eight fields, open the record in a `Sheet` beside the table instead (`onRowClick`).
+
+**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.
+
+**You provide:** the data or the rows, short column headers in sentence case, numbers right-aligned (`align="end"`), and a `getRowLabel` that names each row the way people refer to it.
+
+- Do filter in place with `relevance` when position matters (a ranked list, a schedule); remove rows instead when it doesn't.
+- Don't make rows interactive unless clicking one does something; a lift that leads nowhere is a broken promise.
+- Don't nest tables or put a table inside a raised card's padding without a reason; the table is already the record.
+
+## Columns and density
+
+Wide record tables need a way to choose what shows. `columnsMenu` adds a **Columns** button to the toolbar (it says "· 3 hidden" when some are). It opens a `Popover` (level 3) holding a `SortableList` of `Checkbox`es (drag a column, or pick it up with Space and the arrows, to reorder it) and a density switch (a single-choice `ToggleGroup`: Comfortable or Compact). The first column in order can't be hidden: it names the row.
+
+- `columnVisibility`, `onColumnVisibilityChange`: `{ [key]: false }` hides a column.
+- `columnOrder`, `onColumnOrderChange`: keys in order; keys left out keep their place after the ones given.
+- `density`, `onDensityChange`: `'comfortable'` (default) or `'compact'`. Compact rows keep every target at least 24px tall ([WCAG 2.5.8](https://www.w3.org/WAI/WCAG22/Understanding/target-size-minimum)).
+
+Each has an uncontrolled `default…` form. Showing, hiding or reordering a column doesn't animate the table: it's a change of layout, not of the record. Each change is announced ("Owner column hidden", "Compact rows").
+
+## Paging from the server
+
+`pagination` puts paging in the table's footer, under a line:
+
+- **Pages:** `{ page, pageCount, pageSize, total, onPageChange, hrefFor?, noun? }` renders `Pagination` with its range summary ("9–16 of 214 invoices"). Leave out `pageCount` for cursor paging (Previous, Next, `hasNext`).
+- **Load more:** `{ mode: 'more', hasMore, onLoadMore, total?, noun? }` renders "6 of 46 events" and a Load more button. Loaded rows arrive with the afterglow (at most four begin at once), and "6 more loaded, 12 of 46" is announced.
+
+**While the next page loads** (`loading: true`), the current rows stay on the ground at half strength (the reading a refetching chart uses), the table is `aria-busy`, and the page thumb is held pressed. Your app loads the rows (`useAsyncCollection` keeps selection across pages with `selection: 'preserve'`). After a page change, focus stays on the pagination control.
+
+## Selecting past the page
+
+To bulk-act on a filtered set larger than a page ("Archive all 2,341 inactive users"), use the richer selection:
+
+```tsx
+<DataTable … selectable selection={selection} onSelectionChange={setSelection} matchingTotal={2341} noun="inactive users"
+  actions={(ids, sel) => <Button onClick={() => archive(sel)}>Archive</Button>} actionsPlacement="auto" />
+```
+
+- **A selection** is `{ kind: 'ids', ids }` or `{ kind: 'query', total, except }`. Actions get the loaded ids and the whole selection, so they can act on the *query*. It persists through filtering, sorting and paging, because it's yours.
+- **Once the header checkbox selects a page**, a flush `accent-soft` row offers "Select all 2,341 matching inactive users". A query selection is said in words ("All 2,341 matching, except 1"), and unchecking a row adds it to the exceptions.
+- **`actionsPlacement="floating"`**, or `auto` once the toolbar has scrolled away, docks the count and actions as **a bar floating at the bottom edge, level 3**: a selection is a set of records in your hand. It's a labelled region ("Selection"), and it rises into place.
+
+`selected` and `onSelectedChange` keep working for selections of loaded rows. Report each record's outcome of a long bulk action in place (`RemovalReceipt`'s reading) and in a toast.
+
+<!-- example: generated from build/previews.txt by build/previews.mjs. Edit the preview, not this section. -->
+## Example
+
+The full preview, as rendered in Storybook and checked in CI (`col`, `filter`, `cap` are the preview page's own layout classes, not Altitude's):
+
+```tsx
+import * as React from 'react';
+import { Badge, Button, DataTable, Input } from 'altitude-design';
+
+const data = [
+  { id: "nw", name: "Northwind", env: "Production", owner: "Mara Quist", updated: 2, req: 1240 },
+  { id: "bc", name: "Beacon", env: "Preview", owner: "Jon Reyes", updated: 5, req: 312 },
+  { id: "ci", name: "Cinder", env: "Production", owner: "Lena Park", updated: 26, req: 5906 },
+  { id: "dl", name: "Delta", env: "Staging", owner: "Sam Okafor", updated: 49, req: 88 },
+  { id: "em", name: "Ember", env: "Production", owner: "Ivy Chen", updated: 70, req: 2410 },
+  { id: "fb", name: "Fable", env: "Preview", owner: "Ada Obi", updated: 96, req: 19 },
+  { id: "gn", name: "Garnet", env: "Staging", owner: "Theo Marsh", updated: 120, req: 640 },
+  { id: "hb", name: "Harbor", env: "Production", owner: "Noa Levi", updated: 168, req: 3120 }
+];
+const tone = { Production: "positive", Preview: "accent", Staging: "neutral" };
+export default function App() {
+  const [rows, setRows] = React.useState(data);
+  const [q, setQ] = React.useState("");
+  const [opened, setOpened] = React.useState(null);
+  return <div className="col" style={{ gap: 8 }}>
+  <DataTable
+    aria-label="Projects"
+    rows={rows}
+    onReorder={setRows}
+    getRowId={(r) => r.id}
+    getRowLabel={(r) => r.name}
+    selectable={true}
+    defaultSelected={["bc", "ci"]}
+    maxHeight={300}
+    onRowClick={(r) => setOpened(r.name)}
+    relevance={(r) => q ? r.name.toLowerCase().includes(q.toLowerCase()) || r.owner.toLowerCase().includes(q.toLowerCase()) ? "match" : "miss" : void 0}
+    actions={() => <Button size="sm">Archive</Button>}
+    columnsMenu={true}
+    toolbar={<div className="filter">
+      <Input
+        size="sm"
+        placeholder="Filter in place"
+        value={q}
+        onChange={(e) => setQ(e.target.value)}
+        aria-label="Filter projects"
+      />
+    </div>}
+    columns={[
+        { key: "name", header: "Project", sortValue: (r) => r.name },
+        { key: "env", header: "Environment", cell: (r) => <Badge tone={tone[r.env]}>{r.env}</Badge>, sortValue: (r) => r.env },
+        { key: "owner", header: "Owner", sortValue: (r) => r.owner },
+        { key: "updated", header: "Updated", align: "end", sortValue: (r) => r.updated, cell: (r) => r.updated < 24 ? r.updated + "h ago" : Math.round(r.updated / 24) + "d ago" },
+        { key: "req", header: "Requests", align: "end", sortValue: (r) => r.req, cell: (r) => r.req.toLocaleString("en-US") }
+      ]}
+  />
+  <p className="cap">
+    {opened ? `Opened ${opened}.` : "Sort a column: rows travel to their places. Filter: matches rise, misses sink. Drag a handle, or focus it and press Space, then the arrow keys. Columns shows, hides and reorders columns, and sets the row density."}
+  </p>
+</div>;
+}
+```
+<!-- /example -->