altitude-design 0.4.0 → 0.4.2

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

@@ -91,3 +91,103 @@ The `ItemGroup` section of `build/previews.txt` shows webhooks (edit, add, reord
 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

@@ -7,3 +7,30 @@ Keys sit at level 1 in the mono family with `wall-1` under them. With `listen`,
 **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

@@ -45,3 +45,65 @@ Change over time: latency over a day, revenue over a year, one series or a few c
 - 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

@@ -26,3 +26,44 @@ Navigation: a link in prose, "Learn more" after a hint, "View all invoices →"
 - 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

@@ -30,3 +30,84 @@ An answer's Markdown, set as Altitude prose, as it streams. Models answer in Mar
 - 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

@@ -27,3 +27,55 @@ Where a reading sits in a known range: storage used of a quota, seats used of a
 - 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 -->

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

@@ -26,3 +26,42 @@ An inbox of what happened: mentions, assignments, approvals waiting, failed jobs
 - Do keep an action on the item when it's waiting for someone ("Approve").
 - Don't raise or tint unread items.
 - Don't put momentary confirmations here; that's a toast.
+
+<!-- example: generated from build/previews.txt by build/previews.mjs. Edit the preview, not this section. -->
+## Example
+
+`NotificationCenter` as first used in its preview:
+
+```tsx
+import { NotificationCenter } from 'altitude-design';
+
+<NotificationCenter items={items} onMarkRead={markRead} onMarkAllRead={() => setItems((xs) => xs.map((x) => ({ ...x, read: true })))} preferencesHref="#/settings/notifications" />
+```
+
+The full preview, as rendered in Storybook and checked in CI (`col`, `nc`, `cap` are the preview page's own layout classes, not Altitude's):
+
+```tsx
+import * as React from 'react';
+import { Button, NotificationCenter } from 'altitude-design';
+
+const ago = (m) => new Date(Date.now() - m * 60000);
+export default function App() {
+  const [items, setItems] = React.useState([
+    { id: 'n1', title: 'Maya mentioned you in Q4 planning', body: '“@you can you take the pricing section?”', createdAt: ago(5), read: false, href: '#/docs/q4' },
+    { id: 'n2', title: 'Theo asked to approve an expense', body: '€1,240 · Conference travel', createdAt: ago(48), read: false, actions: <Button size="sm" variant="secondary">Approve</Button> },
+    { id: 'n3', title: 'Export of 812 invoices is ready', createdAt: ago(60 * 3), read: true, href: '#/exports/7' },
+    { id: 'n4', title: 'Nightly sync failed for Salesforce', body: 'The token expired. Reconnect to resume.', createdAt: ago(60 * 27), read: true, href: '#/integrations' },
+  ]);
+  const markRead = (ids) => setItems((xs) => xs.map((x) => (ids.includes(x.id) ? { ...x, read: true } : x)));
+  return (
+    <div className="col">
+      <div className="nc">
+        <Button size="sm" variant="secondary" onClick={() => setItems((xs) => [{ id: 'n' + Date.now(), title: 'Ada assigned you “Billing page”', createdAt: new Date(), read: false, href: '#/issues/212' }, ...xs])}>Simulate a new notification</Button>
+        <NotificationCenter items={items} onMarkRead={markRead} onMarkAllRead={() => setItems((xs) => xs.map((x) => ({ ...x, read: true })))} preferencesHref="#/settings/notifications" />
+      </div>
+      <p className="cap">Unread is a dot and a bolder title, never a height. A new notification arrives lifted and settles, and is announced even while the panel is closed.</p>
+    </div>
+  );
+}
+```
+<!-- /example -->

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

@@ -27,3 +27,40 @@ A number field: seats on a plan, rate limits, retention days, prices, quantities
 - Do put the unit in `format`, not in the label, so it's spoken with the value.
 - Don't use it for identifiers that happen to be digits (a ZIP code, a card number); that's an `Input`.
 - Don't use it to choose roughly within a range; that's a `Slider`.
+
+<!-- example: generated from build/previews.txt by build/previews.mjs. Edit the preview, not this section. -->
+## Example
+
+`NumberInput` as first used in its preview:
+
+```tsx
+import { NumberInput } from 'altitude-design';
+
+<NumberInput value={seats} onValueChange={setSeats} min={1} max={500} incrementLabel="Increase seats" decrementLabel="Decrease seats" />
+```
+
+The full preview, as rendered in Storybook and checked in CI (`col`, `ni`, `cap` are the preview page's own layout classes, not Altitude's):
+
+```tsx
+import * as React from 'react';
+import { Field, NumberInput } from 'altitude-design';
+
+export default function App() {
+  const [seats, setSeats] = React.useState(12);
+  const [days, setDays] = React.useState(30);
+  const [price, setPrice] = React.useState(1250.5);
+  const [rate, setRate] = React.useState(null);
+  return (
+    <div className="col">
+      <div className="ni">
+        <Field label="Seats" hint="1 to 500"><NumberInput value={seats} onValueChange={setSeats} min={1} max={500} incrementLabel="Increase seats" decrementLabel="Decrease seats" /></Field>
+        <Field label="Keep logs for"><NumberInput value={days} onValueChange={setDays} min={1} max={365} format={{ style: 'unit', unit: 'day', unitDisplay: 'long' }} /></Field>
+        <Field label="Preis pro Monat" hint="German: type 1.250,50"><NumberInput value={price} onValueChange={setPrice} min={0} step={0.5} locale="de-DE" format={{ style: 'currency', currency: 'EUR' }} /></Field>
+        <Field label="Sampling rate"><NumberInput value={rate} onValueChange={setRate} min={0} max={1} step={0.05} format={{ style: 'percent' }} placeholder="10" /></Field>
+      </div>
+      <p className="cap">Arrow keys step (Shift for ten); Home and End go to the limits; a stepper at its limit lies flat. Values clamp to their range when you leave the field.</p>
+    </div>
+  );
+}
+```
+<!-- /example -->

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

@@ -27,3 +27,48 @@ The block every page opens with: breadcrumb, title, a line of description, the p
 - Do keep the description to one line about what the page is for.
 - Don't put a PageHeader inside a `Card`; that's `CardHeader`.
 - Don't make the whole header a raised card. It lies on the ground, and only rises while content passes under it.
+
+<!-- example: generated from build/previews.txt by build/previews.mjs. Edit the preview, not this section. -->
+## Example
+
+`PageHeader` as first used in its preview:
+
+```tsx
+import { Breadcrumb, Button, PageHeader, PageHeaderDescription, PageHeaderTitle, Tabs, TabsList, TabsTrigger } from 'altitude-design';
+
+<PageHeader sticky
+  breadcrumb={<Breadcrumb items={[{ label: 'Settings', href: '#/settings' }, { label: 'Members' }]} />}
+  primary={<Button variant="primary">Invite members</Button>}
+  actions={<Button variant="secondary">Export list</Button>}
+  overflow={[{ label: 'Download audit log' }, { label: 'Members settings' }]}
+  tabs={<Tabs variant="segmented" value={tab} onValueChange={setTab}><TabsList aria-label="Members sections"><TabsTrigger value="members">Members</TabsTrigger><TabsTrigger value="invites">Invitations</TabsTrigger><TabsTrigger value="roles">Roles</TabsTrigger></TabsList></Tabs>}>
+  <PageHeaderTitle>Members</PageHeaderTitle>
+  <PageHeaderDescription>People who can see and edit this workspace.</PageHeaderDescription>
+</PageHeader>
+```
+
+The full preview, as rendered in Storybook and checked in CI (`ph`, `rows` are the preview page's own layout classes, not Altitude's):
+
+```tsx
+import * as React from 'react';
+import { Breadcrumb, Button, PageHeader, PageHeaderDescription, PageHeaderTitle, Tabs, TabsList, TabsTrigger } from 'altitude-design';
+
+export default function App() {
+  const [tab, setTab] = React.useState('members');
+  return (
+    <div className="ph">
+      <PageHeader sticky
+        breadcrumb={<Breadcrumb items={[{ label: 'Settings', href: '#/settings' }, { label: 'Members' }]} />}
+        primary={<Button variant="primary">Invite members</Button>}
+        actions={<Button variant="secondary">Export list</Button>}
+        overflow={[{ label: 'Download audit log' }, { label: 'Members settings' }]}
+        tabs={<Tabs variant="segmented" value={tab} onValueChange={setTab}><TabsList aria-label="Members sections"><TabsTrigger value="members">Members</TabsTrigger><TabsTrigger value="invites">Invitations</TabsTrigger><TabsTrigger value="roles">Roles</TabsTrigger></TabsList></Tabs>}>
+        <PageHeaderTitle>Members</PageHeaderTitle>
+        <PageHeaderDescription>People who can see and edit this workspace.</PageHeaderDescription>
+      </PageHeader>
+      <div className="rows">{Array.from({ length: 10 }, (_, i) => <div key={i} />)}</div>
+    </div>
+  );
+}
+```
+<!-- /example -->

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

@@ -23,3 +23,36 @@ Moves through pages of a collection the server pages: invoices, members, audit e
 - Do show the summary; "Page 3 of 11" says less than "41–60 of 214".
 - Don't page short lists; show them whole.
 - Don't use it for steps in a process; that's a `Stepper`.
+
+<!-- example: generated from build/previews.txt by build/previews.mjs. Edit the preview, not this section. -->
+## Example
+
+`Pagination` as first used in its preview:
+
+```tsx
+import { Pagination } from 'altitude-design';
+
+<Pagination page={page} pageCount={11} onPageChange={go} total={214} pageSize={20} noun="invoices" loading={loading} />
+```
+
+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 * as React from 'react';
+import { Pagination } from 'altitude-design';
+
+export default function App() {
+  const [page, setPage] = React.useState(3);
+  const [loading, setLoading] = React.useState(false);
+  const [cursor, setCursor] = React.useState(1);
+  const go = (p) => { setPage(p); setLoading(true); setTimeout(() => setLoading(false), 500); };
+  return (
+    <div className="col">
+      <Pagination page={page} pageCount={11} onPageChange={go} total={214} pageSize={20} noun="invoices" loading={loading} />
+      <Pagination page={cursor} onPageChange={setCursor} hasNext={cursor < 4} aria-label="Audit log pages" />
+      <p className="cap">The current page is a raised thumb in the trench; it's held pressed while the next page loads. Without a page count it's Previous, Next and "Page 3".</p>
+    </div>
+  );
+}
+```
+<!-- /example -->

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

@@ -32,3 +32,39 @@ A password field: signing in, signing up, a reset, "change password" in settings
 - Do say your rules before someone breaks them, as requirements.
 - Don't draw strength as a progress bar.
 - Don't show a strength meter when signing in; it's for creating a password.
+
+<!-- example: generated from build/previews.txt by build/previews.mjs. Edit the preview, not this section. -->
+## Example
+
+`PasswordInput` as first used in its preview:
+
+```tsx
+import { PasswordInput } from 'altitude-design';
+
+<PasswordInput defaultValue="correct horse" />
+```
+
+The full preview, as rendered in Storybook and checked in CI (`pw` is the preview page's own layout class, not Altitude's):
+
+```tsx
+import { Field, PasswordInput } from 'altitude-design';
+
+// A stand-in score: in an app this would be zxcvbn or your own rules.
+const score = (v) => Math.min(4, [v.length >= 8, v.length >= 12, /[A-Z]/.test(v) && /[a-z]/.test(v), /\d/.test(v), /[^\w\s]/.test(v)].filter(Boolean).length - (v.length < 8 ? 1 : 0));
+const common = ['password', 'password1', '12345678', 'qwerty123'];
+export default function App() {
+  return (
+    <div className="pw">
+      <Field label="Password"><PasswordInput defaultValue="correct horse" /></Field>
+      <Field label="New password">
+        <PasswordInput defaultValue="Glacier7" strength={score}
+          requirements={[
+            { label: 'At least 12 characters', test: (v) => v.length >= 12 },
+            { label: 'Not a common password', test: (v) => v.length > 0 && !common.includes(v.toLowerCase()) },
+          ]} />
+      </Field>
+    </div>
+  );
+}
+```
+<!-- /example -->