altitude-design 0.4.0 → 0.4.2

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

@@ -39,3 +39,77 @@ Reading a chart against something: an SLO target, a budget, a normal range, the
 - Do keep annotations to a few words; the plate is a label, not a note.
 - Don't dash a reference line; a dash means "projected".
 - Don't use a reference band for data. A range in the data is an uncertainty band (`LineChart`'s `band`).
+
+<!-- example: generated from build/previews.txt by build/previews.mjs. Edit the preview, not this section. -->
+## Example
+
+`ChartReference` as first used in its preview:
+
+```tsx
+import { ChartReference } from 'altitude-design';
+
+<ChartReference y={[0.995, 1]} label="Normal range" />
+```
+
+The full preview, as rendered in Storybook and checked in CI (`cr`, `row` are the preview page's own layout classes, not Altitude's):
+
+```tsx
+import * as React from 'react';
+import { BarChart, Button, Card, CardContent, CardDescription, CardHeader, CardTitle, ChartAnnotation, ChartContainer, ChartReference, LineChart } from 'altitude-design';
+
+const uptime = Array.from({ length: 30 }, (_, i) => ({ day: `2026-03-${String(i + 1).padStart(2, '0')}`, uptime: [0.9995, 0.9991, 0.9998, 0.9962, 0.9971, 0.9993, 0.9997, 0.9999, 0.9994, 0.9988, 0.9996, 0.9999, 0.9997, 0.9921, 0.9984, 0.9995, 0.9998, 0.9996, 0.9999, 0.9997, 0.9993, 0.9996, 0.9998, 0.9999, 0.9995, 0.9997, 0.9999, 0.9998, 0.9996, 0.9999][i] }));
+const pct = new Intl.NumberFormat('en', { style: 'percent', maximumFractionDigits: 2 });
+const usd = new Intl.NumberFormat('en', { style: 'currency', currency: 'USD', maximumFractionDigits: 0 });
+const weekA = ['Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat', 'Sun'].map((day, i) => ({ day, cost: [412, 455, 498, 430, 610, 220, 190][i] }));
+const weekB = weekA.map((d, i) => ({ ...d, cost: [520, 590, 640, 575, 780, 300, 260][i] }));
+const teams = [['Search', 92], ['Checkout', 81], ['Accounts', 74], ['Messaging', 66], ['Billing', 58]].map(([team, score]) => ({ team, score }));
+const deploys = Array.from({ length: 21 }, (_, i) => ({ day: `2026-04-${String(i + 1).padStart(2, '0')}`, latency: 180 + Math.round(30 * Math.sin(i / 3)) + (i > 9 ? -40 : 0) + (i === 14 ? 60 : 0) }));
+function Chart({ id, title, sub, children, ...props }) {
+  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() {
+  const [later, setLater] = React.useState(false);
+  const [picked, setPicked] = React.useState(null);
+  return (
+    <div className="cr" data-tells-ignore="LA4 a gallery of references in each chart, to compare">
+      <Chart id="r1" title="Uptime" sub="March, against the SLO" config={{ uptime: { label: 'Uptime', format: pct.format } }}>
+        <LineChart data={uptime} x="day">
+          <ChartReference y={[0.995, 1]} label="Normal range" />
+          <ChartReference y={0.999} label="Target 99.9%" />
+          <ChartReference y={0.99} label="Limit 99%" tone="critical" />
+          <ChartAnnotation x="2026-03-14" label="DNS outage" />
+        </LineChart>
+      </Chart>
+      <Card>
+        <CardHeader><CardTitle id="r2">Cloud spend</CardTitle><CardDescription>Against the daily budget; the median moves with the week</CardDescription></CardHeader>
+        <CardContent>
+          <ChartContainer aria-labelledby="r2" aspect={2.2} config={{ cost: { label: 'Cost', format: usd.format } }}>
+            <BarChart data={later ? weekB : weekA} x="day">
+              <ChartReference y={700} label="Budget $700" tone="caution" />
+              <ChartReference y="median" label="Median" />
+            </BarChart>
+          </ChartContainer>
+          <div className="row" style={{ marginTop: 12 }}><Button size="sm" onClick={() => setLater((v) => !v)}>{later ? 'Last week' : 'This week'}</Button></div>
+        </CardContent>
+      </Card>
+      <Chart id="r3" title="Accessibility score" sub="By team, against the bar of 75" config={{ score: { label: 'Score' } }}>
+        <BarChart data={teams} x="team" layout="horizontal"><ChartReference y={75} label="Bar 75" /></BarChart>
+      </Chart>
+      <Chart id="r4" title="p95 latency" sub={picked ? `Picked: ${picked}` : 'Events stack into rows where they would overlap'} config={{ latency: { label: 'p95', format: (v) => `${v} ms` } }}>
+        <LineChart data={deploys} x="day">
+          <ChartReference y="mean" label="Average" />
+          <ChartAnnotation x="2026-04-10" label="Cache rollout" onSelect={() => setPicked('Cache rollout')} />
+          <ChartAnnotation x="2026-04-11" label="v2 launch" onSelect={() => setPicked('v2 launch')} />
+          <ChartAnnotation x="2026-04-15" label="Incident 412" />
+        </LineChart>
+      </Chart>
+    </div>
+  );
+}
+```
+<!-- /example -->

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

@@ -36,3 +36,66 @@ Turn the readout off with `tooltip={false}` on the chart type or the container.
 - Do format the heading the way people say the x ("Week of Mon, April 6"), not as stored.
 - Don't put anything in it that can't be reached another way: it's a convenience over the summary, the keyboard path and the table.
 - Don't add buttons or links to it; it doesn't take the pointer, and it moves away as soon as the pointer does.
+
+<!-- example: generated from build/previews.txt by build/previews.mjs. Edit the preview, not this section. -->
+## Example
+
+`ChartTooltip` as first used in its preview:
+
+```tsx
+import { ChartTooltip, ChartTooltipContent } from 'altitude-design';
+
+<ChartTooltip content={<ChartTooltipContent indicator="dot" labelFormat={(w) => 'Week of ' + long.format(new Date(w + 'T00:00:00Z'))} />} />
+```
+
+The full preview, as rendered in Storybook and checked in CI (`ct` is the preview page's own layout class, not Altitude's):
+
+```tsx
+import * as React from 'react';
+import { BarChart, Card, CardContent, CardDescription, CardHeader, CardTitle, ChartContainer, ChartTooltip, ChartTooltipContent, LineChart, useChart } from 'altitude-design';
+
+// The readout is on for every chart; point at one (or press and hold on touch). Here it's opened with setActive,
+// the same call the keyboard path uses, so the preview shows it without a pointer.
+const weeks = ['2026-03-02', '2026-03-09', '2026-03-16', '2026-03-23', '2026-03-30', '2026-04-06', '2026-04-13'].map((week, i) => ({ week, opened: [31, 38, 35, 44, 41, 47, 52][i], closed: [28, 30, 36, 39, 43, 45, 49][i] }));
+const long = new Intl.DateTimeFormat('en', { weekday: 'short', day: 'numeric', month: 'long', timeZone: 'UTC' });
+function Open({ at }) {
+  const { setActive } = useChart();
+  React.useEffect(() => { setActive(at); }, []);
+  return null;
+}
+export default function App() {
+  const [pins, setPins] = React.useState(['2026-03-09', '2026-04-06']);
+  return (
+    <div className="ct" data-tells-ignore="LA4 a gallery of the readout in each chart, to compare">
+      <Card>
+        <CardHeader><CardTitle id="t1">Issues opened and closed</CardTitle><CardDescription>The default readout, open on 23 Mar</CardDescription></CardHeader>
+        <CardContent>
+          <ChartContainer aria-labelledby="t1" aspect={1.8} config={{ opened: { label: 'Opened' }, closed: { label: 'Closed' } }}>
+            <LineChart data={weeks} x="week" /><Open at={3} />
+          </ChartContainer>
+        </CardContent>
+      </Card>
+      <Card>
+        <CardHeader><CardTitle id="t2">Same data, your own content</CardTitle><CardDescription>indicator="dot" and a long date</CardDescription></CardHeader>
+        <CardContent>
+          <ChartContainer aria-labelledby="t2" aspect={1.8} config={{ opened: { label: 'Opened' }, closed: { label: 'Closed' } }}>
+            <BarChart data={weeks} x="week">
+              <ChartTooltip content={<ChartTooltipContent indicator="dot" labelFormat={(w) => 'Week of ' + long.format(new Date(w + 'T00:00:00Z'))} />} />
+            </BarChart>
+            <Open at={5} />
+          </ChartContainer>
+        </CardContent>
+      </Card>
+      <Card>
+        <CardHeader><CardTitle id="t3">Pinned readings</CardTitle><CardDescription>pinnable: click (or P) sets a reading down; two compare</CardDescription></CardHeader>
+        <CardContent>
+          <ChartContainer aria-labelledby="t3" aspect={1.8} config={{ opened: { label: 'Opened' } }}>
+            <LineChart data={weeks} x="week" pinnable pins={pins} onPinsChange={setPins} />
+          </ChartContainer>
+        </CardContent>
+      </Card>
+    </div>
+  );
+}
+```
+<!-- /example -->

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

@@ -9,3 +9,38 @@ Toggles one independent option. A checkbox is built like the Switch and the Radi
 **You provide:** `label`, optional `description`, and `checked`/`onCheckedChange` (or `defaultChecked`). It's a real `<input type="checkbox">`, so it works in forms with `name` and `value`.
 
 - Use a Switch when the change takes effect immediately; a Checkbox is for choices submitted together.
+
+<!-- example: generated from build/previews.txt by build/previews.mjs. Edit the preview, not this section. -->
+## Example
+
+`Checkbox` as first used in its preview:
+
+```tsx
+import { Checkbox } from 'altitude-design';
+
+<Checkbox label="Select all" checked={a && b} indeterminate={a !== b} onCheckedChange={(c) => { setA(c); setB(c); }} />
+```
+
+The full preview, as rendered in Storybook and checked in CI (`col`, `family`, `cap` are the preview page's own layout classes, not Altitude's):
+
+```tsx
+import * as React from 'react';
+import { Checkbox, Switch } from 'altitude-design';
+
+export default function App() {
+  const [a, setA] = React.useState(true);
+  const [b, setB] = React.useState(false);
+  return (
+    <div className="col">
+      <Checkbox label="Select all" checked={a && b} indeterminate={a !== b} onCheckedChange={(c) => { setA(c); setB(c); }} />
+      <div className="col" style={{ paddingLeft: 34 }}>
+        <Checkbox label="Weekly digest" description="A summary every Monday morning." checked={a} onCheckedChange={setA} />
+        <Checkbox label="Product updates" checked={b} onCheckedChange={setB} />
+      </div>
+      <Checkbox label="Disabled" disabled defaultChecked />
+      <div className="family"><span className="cap">Same build as</span><Switch defaultChecked aria-label="Switch" /><Switch aria-label="Switch off" /></div>
+    </div>
+  );
+}
+```
+<!-- /example -->

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

@@ -69,3 +69,69 @@ The items, applying and persisting each op, and reversing ops for Undo.
 ## Demo and verification
 
 The `Checklist` section of `build/previews.txt` shows nested launch tasks (a fictional service refuses “TBD”) and a flat packing list with `sortDone`. `node checks/checklist.mjs` (from `build/`; `ALT_FIXTURE_ROOT` selects React 19 fixtures) covers Enter, split and merge at the caret, Backspace on an empty line, Tab and Shift+Tab, Escape then Tab, ↑/↓, Alt+↑, Ctrl+Enter, IME Enter, a refused edit with Retry, remove and Ctrl+Z, the add line, task-list paste, `sortDone`, 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
+
+`Checklist` as first used in its preview:
+
+```tsx
+import { Checklist } from 'altitude-design';
+
+<Checklist aria-labelledby="cl-launch" nested {...props} {...launch} />
+```
+
+The full preview, as rendered in Storybook and checked in CI (`cl-demo` is the preview page's own layout class, not Altitude's):
+
+```tsx
+import * as React from 'react';
+import { Checklist } from 'altitude-design';
+
+// A tiny store that applies the Checklist's ops to nested items, and reverses them for Undo.
+const clStrip = (list, id) => { let found = null; const out = list.filter(x => { if (x.id === id) { found = x; return false; } return true; }).map(x => { if (found || !x.children) return x; const [kids, hit] = clStrip(x.children, id); if (hit) found = hit; return hit ? { ...x, children: kids } : x; }); return [out, found]; };
+const clInsert = (list, parentId, index, node) => parentId === null ? [...list.slice(0, index), node, ...list.slice(index)]
+  : list.map(x => x.id === parentId ? { ...x, children: [...(x.children || []).slice(0, index), node, ...(x.children || []).slice(index)] } : x.children ? { ...x, children: clInsert(x.children, parentId, index, node) } : x);
+const clUpdate = (list, id, patch) => list.map(x => x.id === id ? { ...x, ...patch } : x.children ? { ...x, children: clUpdate(x.children, id, patch) } : x);
+const clApply = (list, op) => {
+  if (op.type === 'add') return clInsert(list, op.parentId, op.index, { id: op.id, text: op.text, done: op.done });
+  if (op.type === 'edit') return clUpdate(list, op.id, { text: op.text });
+  if (op.type === 'toggle') return clUpdate(list, op.id, { done: op.done });
+  const [rest, node] = clStrip(list, op.id);
+  if (op.type === 'remove') return rest;
+  return clInsert(rest, op.parentId, op.index, node);
+};
+function useChecklist(seed, refuse) {
+  const [items, setItems] = React.useState(seed);
+  const removedNodes = React.useRef(new Map());
+  const onChange = op => {
+    if (refuse && refuse(op)) return { ok: false, error: refuse(op) };
+    if (op.type === 'remove') removedNodes.current.set(op.id, clStrip(items, op.id)[1]);
+    setItems(list => clApply(list, op));
+  };
+  const onUndo = op => setItems(list => {
+    if (op.type === 'add') return clStrip(list, op.id)[0];
+    if (op.type === 'remove') return clInsert(list, op.parentId, op.index, removedNodes.current.get(op.id));
+    const [rest, node] = clStrip(list, op.id); return clInsert(rest, op.from.parentId, op.from.index, node);
+  });
+  return { items, onChange, onUndo };
+}
+const CL_LAUNCH = [
+  { id: 'venue', text: 'Book the venue', done: true },
+  { id: 'invites', text: 'Send invitations', done: false, children: [
+    { id: 'list', text: 'Confirm the guest list', done: true }, { id: 'design', text: 'Design the card', done: false } ] },
+  { id: 'catering', text: 'Choose catering', done: false },
+];
+const CL_PACK = [{ id: 'p1', text: 'Passport', done: false }, { id: 'p2', text: 'Charger', done: true }, { id: 'p3', text: 'Rain jacket', done: false }];
+export default function App() {
+  const launch = useChecklist(CL_LAUNCH, op => op.type === 'edit' && /tbd/i.test(op.text) ? 'Write the task, not “TBD”.' : undefined);
+  const pack = useChecklist(CL_PACK);
+  const props = { getKey: t => t.id, getText: t => t.text, isDone: t => t.done, getChildren: t => t.children };
+  return <div className="cl-demo">
+    <section><h3 id="cl-launch">Launch tasks</h3><p>Nested: Tab and Shift+Tab indent and outdent. Backspace on an empty line removes it; Ctrl+Z (⌘Z) brings it back. Writing “TBD” is refused.</p>
+      <Checklist aria-labelledby="cl-launch" nested {...props} {...launch} /></section>
+    <section><h3 id="cl-pack">Packing</h3><p>Flat, done items last.</p>
+      <Checklist aria-labelledby="cl-pack" sortDone {...props} {...pack} placeholder="Add something to pack" /></section>
+  </div>;
+}
+```
+<!-- /example -->

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

@@ -26,3 +26,47 @@ Code to read and copy: install commands, API examples in several languages, webh
 - Do use tabs for the same thing in several forms, not for different things.
 - Don't raise a code block into a card or give it a shadow.
 - Don't colour code with the chart palette.
+
+<!-- example: generated from build/previews.txt by build/previews.mjs. Edit the preview, not this section. -->
+## Example
+
+`CodeBlock` as first used in its preview:
+
+```tsx
+import { CodeBlock } from 'altitude-design';
+
+<CodeBlock title="Install" tabs={[{ label: 'npm', language: 'sh', code: 'npm install altitude-design' }, { label: 'pnpm', language: 'sh', code: 'pnpm add altitude-design' }, { label: 'yarn', language: 'sh', code: 'yarn add altitude-design' }]} />
+```
+
+The full preview, as rendered in Storybook and checked in CI (`cbk` is the preview page's own layout class, not Altitude's):
+
+```tsx
+import * as React from 'react';
+import { CodeBlock } from 'altitude-design';
+
+const payload = `{
+  "id": "evt_1Q8xZ2",
+  "type": "invoice.paid",
+  "created": 1793304000,
+  "data": {
+    "invoice": "INV-0042",
+    "amount": 4900,
+    "currency": "eur"
+  }
+}`;
+// A stand-in highlighter, to show the syntax prop: comments in ink-muted, keywords in accent-ink.
+const tiny = (code) => code.split(/(\/\/.*$|\b(?:const|await|import|from)\b)/m).map((part, i) => part.startsWith('//') ? <span key={i} className="tok-comment">{part}</span> : /^(const|await|import|from)$/.test(part) ? <span key={i} className="tok-keyword">{part}</span> : part);
+export default function App() {
+  const [streamed, setStreamed] = React.useState('');
+  const full = "import { Altitude } from 'altitude-design';\n// Verify the signature before trusting the event\nconst event = await verify(request, secret);";
+  React.useEffect(() => { let i = 0; const t = setInterval(() => { i = Math.min(full.length, i + 3); setStreamed(full.slice(0, i)); if (i >= full.length) clearInterval(t); }, 60); return () => clearInterval(t); }, []);
+  return (
+    <div className="cbk">
+      <CodeBlock title="Install" tabs={[{ label: 'npm', language: 'sh', code: 'npm install altitude-design' }, { label: 'pnpm', language: 'sh', code: 'pnpm add altitude-design' }, { label: 'yarn', language: 'sh', code: 'yarn add altitude-design' }]} />
+      <CodeBlock title="invoice.paid" language="json" code={payload} highlight={[3, 7]} lineNumbers maxHeight={220} />
+      <CodeBlock title="webhook.ts" language="ts" code={streamed} syntax={tiny} streaming={streamed.length < full.length} />
+    </div>
+  );
+}
+```
+<!-- /example -->

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

@@ -28,3 +28,42 @@ A brand colour for a white-label portal, a label or tag colour, a calendar colou
 - Do turn on `checkContrast` wherever the colour will carry text (an accent, a button).
 - Don't offer a free colour where a palette will do; custom colours make labels hard to tell apart.
 - Don't use the `data-*` chart palette as label colours; it means series.
+
+<!-- example: generated from build/previews.txt by build/previews.mjs. Edit the preview, not this section. -->
+## Example
+
+`ColorPicker` as first used in its preview:
+
+```tsx
+import { ColorPicker } from 'altitude-design';
+
+<ColorPicker label="Brand colour" value={color} onValueChange={setColor} swatches={brand} allowCustom checkContrast />
+```
+
+The full preview, as rendered in Storybook and checked in CI (`cpk`, `col`, `demo`, `cap` are the preview page's own layout classes, not Altitude's):
+
+```tsx
+import * as React from 'react';
+import { AltitudeProvider, Button, ColorPicker } from 'altitude-design';
+
+const brand = [
+  { value: '#0f8a6b', name: 'Teal' }, { value: '#2f5fd0', name: 'Blue' }, { value: '#7d3c6f', name: 'Plum' },
+  { value: '#c23a6b', name: 'Rose' }, { value: '#c8571f', name: 'Ember' }, { value: '#d9a521', name: 'Ochre' },
+];
+const labels = [{ value: '#66738a', name: 'Slate' }, { value: '#2f8f4e', name: 'Green' }, { value: '#c9372c', name: 'Red' }, { value: '#16869e', name: 'Cyan' }];
+export default function App() {
+  const [color, setColor] = React.useState('#0f8a6b');
+  const [tag, setTag] = React.useState('#2f8f4e');
+  return (
+    <div className="cpk">
+      <ColorPicker label="Brand colour" value={color} onValueChange={setColor} swatches={brand} allowCustom checkContrast />
+      <div className="col">
+        <ColorPicker label="Label colour" value={tag} onValueChange={setTag} swatches={labels} />
+        <div className="demo"><span className="cap">Preview:</span><AltitudeProvider accent={color}><Button variant="primary">Upgrade plan</Button></AltitudeProvider></div>
+        <p className="cap">The check says, for white text and for dark text, whether it reaches 4.5:1 on the colour. Arrow keys move the mark between swatches; Custom… opens a full picker.</p>
+      </div>
+    </div>
+  );
+}
+```
+<!-- /example -->

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

@@ -14,3 +14,38 @@ An editable Select: type to narrow a long list, then choose. What you type is a
 
 - Do use it when the list is long enough that scrolling is slower than typing (people, countries, repositories).
 - Don't use it for free text that may not be in the list; it only accepts listed values.
+
+<!-- example: generated from build/previews.txt by build/previews.mjs. Edit the preview, not this section. -->
+## Example
+
+`Combobox` as first used in its preview:
+
+```tsx
+import { Combobox } from 'altitude-design';
+
+<Combobox items={people} value={who} onValueChange={setWho} placeholder="Search people" />
+```
+
+The full preview, as rendered in Storybook and checked in CI (`col`, `grid` are the preview page's own layout classes, not Altitude's):
+
+```tsx
+import * as React from 'react';
+import { Combobox, Field } from 'altitude-design';
+
+const people = ["Ada Obi", "Eli Ward", "Ivy Chen", "Jon Reyes", "Kai Ito", "Lena Park", "Mara Quist", "Noa Levi", "Rui Costa", "Sam Okafor", "Theo Marsh"].map((n) => ({ value: n.toLowerCase().replace(" ", "-"), label: n }));
+const countries = ["Brazil", "Canada", "Germany", "Japan", "Peru", "Portugal", "Singapore", "Spain"].map((c) => ({ value: c.toLowerCase(), label: c }));
+export default function App() {
+  const [who, setWho] = React.useState("");
+  return <div className="col">
+  <div className="grid">
+    <Field label="Assignee" hint={who ? "Assigned." : "Start typing a name."}>
+      <Combobox items={people} value={who} onValueChange={setWho} placeholder="Search people" />
+    </Field>
+    <Field label="Country">
+      <Combobox items={countries} defaultValue="portugal" defaultOpen={true} />
+    </Field>
+  </div>
+</div>;
+}
+```
+<!-- /example -->

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

@@ -25,3 +25,180 @@ Finds and runs anything in the product from one field: the summit, at level 5, o
 - Don't render two palettes, and don't open a Sheet from one: one summit, and a level-4 sheet can't sit on it.
 
 The palette and Dialog share one summit per document, including across providers. Its shortcut cannot take an occupied summit. A simultaneous controlled request is rejected with a development warning; set it to `false` before trying again. Rejected requests do not queue. A selected command can close the palette and open a Dialog synchronously: callback ordering is unchanged, the exiting palette retires, and scroll/isolation ownership transfers without unlocking the page. Only the active modal has `aria-modal`; composition Enter and Escape remain with the input method.
+
+<!-- example: generated from build/previews.txt by build/previews.mjs. Edit the preview, not this section. -->
+## Example
+
+`CommandPalette` as first used in its preview:
+
+```tsx
+import { CommandPalette } from 'altitude-design';
+
+<CommandPalette
+  open={open}
+  onOpenChange={onOpenChange}
+  query={text}
+  onQueryChange={setText}
+  items={groups}
+  onSelect={(item) => setLast(item.label)}
+/>
+```
+
+The full preview, as rendered in Storybook and checked in CI (`app`, `bar`, `find`, `grid`, `cap` are the preview page's own layout classes, not Altitude's):
+
+```tsx
+import * as React from 'react';
+import { Badge, Card, CommandPalette, Input, Kbd } from 'altitude-design';
+
+const I = {
+  up: <svg
+  width="16"
+  height="16"
+  viewBox="0 0 24 24"
+  fill="none"
+  stroke="currentColor"
+  strokeWidth="1.75"
+  strokeLinecap="round"
+  strokeLinejoin="round"
+>
+  <path d="M7 17L17 7M9 7h8v8" />
+</svg>,
+  folder: <svg
+  width="16"
+  height="16"
+  viewBox="0 0 24 24"
+  fill="none"
+  stroke="currentColor"
+  strokeWidth="1.75"
+  strokeLinejoin="round"
+>
+  <path d="M3 7a2 2 0 0 1 2-2h4l2 2h8a2 2 0 0 1 2 2v8a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2z" />
+</svg>,
+  plus: <svg
+  width="16"
+  height="16"
+  viewBox="0 0 24 24"
+  fill="none"
+  stroke="currentColor"
+  strokeWidth="1.75"
+  strokeLinecap="round"
+>
+  <path d="M12 5v14M5 12h14" />
+</svg>,
+  user: <svg
+  width="16"
+  height="16"
+  viewBox="0 0 24 24"
+  fill="none"
+  stroke="currentColor"
+  strokeWidth="1.75"
+  strokeLinecap="round"
+>
+  <circle cx="12" cy="8" r="4" />
+  <path d="M4 20c1.5-4 4.5-6 8-6s6.5 2 8 6" />
+</svg>,
+  key: <svg
+  width="16"
+  height="16"
+  viewBox="0 0 24 24"
+  fill="none"
+  stroke="currentColor"
+  strokeWidth="1.75"
+  strokeLinecap="round"
+  strokeLinejoin="round"
+>
+  <circle cx="8" cy="15" r="4" />
+  <path d="M11 12l9-9M17 6l3 3" />
+</svg>,
+  trash: <svg
+  width="16"
+  height="16"
+  viewBox="0 0 24 24"
+  fill="none"
+  stroke="currentColor"
+  strokeWidth="1.75"
+  strokeLinecap="round"
+  strokeLinejoin="round"
+>
+  <path d="M4 7h16M9 7V4h6v3M6 7l1 13h10l1-13" />
+</svg>
+};
+const groups = [
+  { label: "Recent", predicted: true, items: [
+    { label: "Deploy to production", icon: I.up, shortcut: ["\u2318", "D"], keywords: ["ship", "release"] },
+    { label: "Open Northwind", icon: I.folder, description: "Marketing site" }
+  ] },
+  { label: "Actions", items: [
+    { label: "New project", icon: I.plus, shortcut: ["\u2318", "N"] },
+    { label: "Invite people", icon: I.user, keywords: ["team", "member"] },
+    { label: "Deploy preview", icon: I.up, description: "main@8dc01b2" },
+    { label: "Delete project\u2026", icon: I.trash, tone: "critical" }
+  ] },
+  { label: "Projects", items: [
+    { label: "Northwind", icon: I.folder, description: "acme.dev" },
+    { label: "Beacon", icon: I.folder, description: "Internal dashboard" },
+    { label: "Cinder", icon: I.folder, description: "API gateway" }
+  ] },
+  { label: "Settings", items: [
+    { label: "Environment variables", icon: I.key, keywords: ["env", "secrets", "dependencies"] },
+    { label: "Billing", icon: I.key, disabled: true }
+  ] }
+];
+const searchIcon = <svg
+  width="16"
+  height="16"
+  viewBox="0 0 24 24"
+  fill="none"
+  stroke="currentColor"
+  strokeWidth="1.75"
+  strokeLinecap="round"
+  aria-hidden="true"
+>
+  <circle cx="11" cy="11" r="7" />
+  <path d="M20 20l-3.5-3.5" />
+</svg>;
+export default function App() {
+  const [open, setOpen] = React.useState(true);
+  const [text, setText] = React.useState("");
+  const [last, setLast] = React.useState(null);
+  const onOpenChange = (v) => {
+    setOpen(v);
+    if (!v) setText("");
+  };
+  return <div className="app">
+  <div className="bar">
+    <b>Northwind</b>
+    <Badge tone="positive">Operational</Badge>
+    <Input
+      className="find"
+      aria-label="Search or run a command"
+      placeholder="Search or run a command"
+      value={text}
+      leading={searchIcon}
+      trailing={<span aria-hidden="true"><Kbd>⌘</Kbd><Kbd>K</Kbd></span>}
+      onChange={(e) => {
+    setText(e.target.value);
+    if (e.target.value) setOpen(true);
+  }}
+    />
+  </div>
+  <div className="grid" data-tells-ignore="LA4 placeholder page behind the overlay">
+    <Card />
+    <Card />
+    <Card />
+  </div>
+  <p className="cap">
+    {last ? `Chose \u201C${last}\u201D.` : "Type \u201Cdep\u201D: the best match moves to the top and the rows that stay travel there. Close it and type in the search field: the palette opens with what you typed."}
+  </p>
+  <CommandPalette
+    open={open}
+    onOpenChange={onOpenChange}
+    query={text}
+    onQueryChange={setText}
+    items={groups}
+    onSelect={(item) => setLast(item.label)}
+  />
+</div>;
+}
+```
+<!-- /example -->

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

@@ -28,3 +28,54 @@ Comments on a task, a document, a design or a deal: write with @mentions, post,
 - Do keep a resolved thread in place, stamped.
 - Don't announce typing.
 - Don't post on Enter alone; people write several lines.
+
+<!-- example: generated from build/previews.txt by build/previews.mjs. Edit the preview, not this section. -->
+## Example
+
+`CommentThread` as first used in its preview:
+
+```tsx
+import { CommentThread } from 'altitude-design';
+
+<CommentThread comments={comments} resolved={resolved ? { by: 'You' } : false} onPost={post}
+  onResolve={() => setResolved(true)} onReopen={() => setResolved(false)}
+  onRetry={(id) => setComments((xs) => xs.map((x) => (x.id === id ? { ...x, status: undefined } : x)))}
+  onDelete={(id) => setComments((xs) => xs.map((x) => (x.id === id ? { ...x, deleted: true } : x)))}
+  onUndoDelete={(id) => setComments((xs) => xs.map((x) => (x.id === id ? { ...x, deleted: false } : x)))}
+  mentionable={(q) => people.filter((p) => p.name.toLowerCase().includes(q.toLowerCase()))} typing={resolved ? [] : ['Ada Obi']} />
+```
+
+The full preview, as rendered in Storybook and checked in CI (`col`, `ct` are the preview page's own layout classes, not Altitude's):
+
+```tsx
+import * as React from 'react';
+import { CommentThread, Switch } from 'altitude-design';
+
+const people = [{ id: 'maya', name: 'Maya Chen' }, { id: 'theo', name: 'Theo Marsh' }, { id: 'ada', name: 'Ada Obi' }];
+const ago = (m) => new Date(Date.now() - m * 60000);
+export default function App() {
+  const [comments, setComments] = React.useState([
+    { id: 'c1', author: { name: 'Theo Marsh' }, body: 'Can we ship this before the release freeze on Friday?', createdAt: ago(90) },
+    { id: 'c2', author: { name: 'Maya Chen' }, body: '@Theo Marsh yes, if QA signs off by Thursday.', mentions: ['Theo Marsh'], createdAt: ago(40) },
+  ]);
+  const [resolved, setResolved] = React.useState(false);
+  const [failNext, setFailNext] = React.useState(false);
+  const post = (body, mentions) => {
+    const id = 'n' + Date.now(), fail = failNext;
+    setComments((xs) => [...xs, { id, author: { name: 'You' }, body, mentions: mentions.map((m) => m.name), createdAt: new Date(), status: 'pending', mine: true }]);
+    setTimeout(() => setComments((xs) => xs.map((x) => (x.id === id ? { ...x, status: fail ? 'failed' : undefined } : x))), 900);
+  };
+  return (
+    <div className="col ct">
+      <CommentThread comments={comments} resolved={resolved ? { by: 'You' } : false} onPost={post}
+        onResolve={() => setResolved(true)} onReopen={() => setResolved(false)}
+        onRetry={(id) => setComments((xs) => xs.map((x) => (x.id === id ? { ...x, status: undefined } : x)))}
+        onDelete={(id) => setComments((xs) => xs.map((x) => (x.id === id ? { ...x, deleted: true } : x)))}
+        onUndoDelete={(id) => setComments((xs) => xs.map((x) => (x.id === id ? { ...x, deleted: false } : x)))}
+        mentionable={(q) => people.filter((p) => p.name.toLowerCase().includes(q.toLowerCase()))} typing={resolved ? [] : ['Ada Obi']} />
+      <Switch label="Make the next post fail" checked={failNext} onCheckedChange={setFailNext} />
+    </div>
+  );
+}
+```
+<!-- /example -->