altitude-design 0.4.0 → 0.4.2

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

@@ -78,3 +78,51 @@ A `Card`'s parts land together, and a `RevealGroup` takes one place in the atten
 - Don't use it for errors: a rejected promise throws to your nearest error boundary, where an `Alert` belongs.
 - Don't use `null` for "still loading"; it means there's nothing, and renders empty.
 - `Skeleton` with `loaded` is still the way for layouts of your own.
+
+<!-- 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 (`card`, `who`, `id`, `col`, `cap` are the preview page's own layout classes, not Altitude's):
+
+```tsx
+import * as React from 'react';
+import { Avatar, Badge, Card, CardContent, CardDescription, CardHeader, CardTitle } from 'altitude-design';
+
+const USER = { name: 'Mara Quist', role: 'Platform engineer, Lisbon', bio: 'Merged “Faster cold starts” into main. Cold starts are down 38% across all regions.' };
+// Stands in for useQuery or useSWR: undefined until the data arrives.
+function useLoaded(value, ms) {
+  const [data, setData] = React.useState(undefined);
+  React.useEffect(() => { const t = setTimeout(() => setData(value), ms); return () => clearTimeout(t); }, []);
+  return data;
+}
+function Member() {
+  const user = useLoaded(USER, 1200);
+  const status = useLoaded('On call', 1800);
+  return (
+    <Card className="card">
+      <CardHeader>
+        <div className="who">
+          <Avatar name={user?.name} size={44} status="active" />
+          <div className="id">
+            <CardTitle>{user?.name}</CardTitle>
+            <CardDescription skeleton={{ lines: 1, width: '70%' }}>{user?.role}</CardDescription>
+          </div>
+          <Badge tone="positive">{status}</Badge>
+        </div>
+      </CardHeader>
+      <CardContent skeleton={{ lines: 2 }}>{user?.bio}</CardContent>
+    </Card>
+  );
+}
+export default function App() {
+  const [round, setRound] = React.useState(0);
+  React.useEffect(() => { const t = setTimeout(() => setRound((r) => r + 1), 4400); return () => clearTimeout(t); }, [round]);
+  return (
+    <div className="col">
+      <Member key={round} />
+      <p className="cap">No skeleton code: while user is undefined, each part imprints itself at its own size, and rises out of it when the data arrives.</p>
+    </div>
+  );
+}
+```
+<!-- /example -->

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

@@ -20,3 +20,47 @@ Labels status or metadata. A badge is an **indicator plate**: part of the record
 - Do pair status colour with the word: "Outage", never a lamp alone.
 - Don't make badges clickable; if it filters or navigates, it's a ghost Button.
 - Don't use `count` for totals that aren't asking for attention; use a plate or plain text.
+
+<!-- example: generated from build/previews.txt by build/previews.mjs. Edit the preview, not this section. -->
+## Example
+
+`Badge` as first used in its preview:
+
+```tsx
+import { Badge } from 'altitude-design';
+
+<Badge lamp>Draft</Badge>
+```
+
+The full preview, as rendered in Storybook and checked in CI (`col`, `row`, `anchor`, `cap` are the preview page's own layout classes, not Altitude's):
+
+```tsx
+import * as React from 'react';
+import { Badge, Button } from 'altitude-design';
+
+export default function App() {
+  const [deploying, setDeploying] = React.useState(true);
+  const [n, setN] = React.useState(3);
+  React.useEffect(() => { const t = setInterval(() => { setDeploying((d) => !d); setN((x) => (x % 5) + 1); }, 2400); return () => clearInterval(t); }, []);
+  return (
+    <div className="col">
+      <div className="row">
+        <Badge lamp>Draft</Badge>
+        <Badge tone="accent">Beta</Badge>
+        <Badge tone="positive">Operational</Badge>
+        <Badge tone="caution">Degraded</Badge>
+        <Badge tone="critical">Outage</Badge>
+        <Badge tone={deploying ? 'accent' : 'positive'} lamp={deploying ? 'pulse' : true}>{deploying ? 'Deploying' : 'Live'}</Badge>
+      </div>
+      <div className="row">
+        <Badge tone="positive" variant="tinted">Operational</Badge>
+        <Badge tone="critical" variant="tinted">Outage</Badge>
+        <Badge variant="outline">v2.4.0</Badge>
+        <span className="anchor"><Button>Inbox</Button><Badge variant="count" tone="critical">{n}</Badge></span>
+      </div>
+      <p className="cap">Labels are stamped into the record; status wears a lamp that relights when it changes. A count is the one badge that floats, because it wants you.</p>
+    </div>
+  );
+}
+```
+<!-- /example -->

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

@@ -45,3 +45,65 @@ The y axis always includes zero, whatever the container's `zero` says: a truncat
 - Do use `stack="expand"` only when the shares matter more than the totals, and say so in the title.
 - Don't label every bar: label the one the chart is about, and leave the rest to the readout and the table.
 - Don't colour bars by their value or give them a gradient; for polarity, a diverging ramp on a separate chart says it better.
+
+<!-- example: generated from build/previews.txt by build/previews.mjs. Edit the preview, not this section. -->
+## Example
+
+`BarChart` as first used in its preview:
+
+```tsx
+import { BarChart } from 'altitude-design';
+
+<BarChart data={teams} x="team" sort="desc" labels="max" focus={(d) => d.team === 'Cedar' || d.team === 'Delta'} />
+```
+
+The full preview, as rendered in Storybook and checked in CI (`bc` is the preview page's own layout class, not Altitude's):
+
+```tsx
+import { BarChart, Card, CardContent, CardDescription, CardHeader, CardTitle, ChartContainer } from 'altitude-design';
+
+const teams = [{ team: 'Atlas', deploys: 42 }, { team: 'Birch', deploys: 35 }, { team: 'Cedar', deploys: 51 }, { team: 'Delta', deploys: 19 }, { team: 'Ember', deploys: 28 }];
+const months = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun'].map((month, i) => ({ month, api: 20 + ((i * 7) % 11), web: 14 + ((i * 5) % 9), jobs: 6 + ((i * 3) % 7) }));
+const net = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun'].map((month, i) => ({ month, change: [12, -8, 5, -15, 9, 18][i] }));
+const regions = [{ region: 'North America', seats: 1240, before: 1120 }, { region: 'Europe, Middle East and Africa', seats: 980, before: 1040 }, { region: 'Asia Pacific', seats: 610, before: 470 }, { region: 'Latin America', seats: 270, before: 240 }];
+const stack3 = { api: { label: 'API' }, web: { label: 'Web' }, jobs: { label: 'Jobs' } };
+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.45} {...props}>{children}</ChartContainer></CardContent>
+    </Card>
+  );
+  return (
+    <Card>
+      <CardHeader><CardTitle id={id}>{title}</CardTitle><CardDescription>{sub}</CardDescription></CardHeader>
+      <CardContent><ChartContainer aria-labelledby={id} aspect={1.45} {...props}>{children}</ChartContainer></CardContent>
+    </Card>
+  );
+}
+export default function App() {
+  return (
+    <div className="bc">
+      <Chart id="b1" title="Deploys by team" takeaway="Cedar deployed nearly three times as often as Delta" sub='One series, sorted, labels="max"' config={{ deploys: { label: 'Deploys' } }} summary="Cedar deployed most, 51 times; Delta least, 19.">
+        <BarChart data={teams} x="team" sort="desc" labels="max" focus={(d) => d.team === 'Cedar' || d.team === 'Delta'} />
+      </Chart>
+      <Chart id="b2" title="Requests by service" sub="Grouped: three series side by side" config={stack3}>
+        <BarChart data={months.slice(3)} x="month" />
+      </Chart>
+      <Chart id="b3" title="Requests, all services" sub='Stacked, labels="last", focus={["web"]}' config={stack3}>
+        <BarChart data={months} x="month" stack labels="last" focus={['web']} />
+      </Chart>
+      <Chart id="b4" title="Share of requests" sub='stack="expand": parts of 100%' config={stack3}>
+        <BarChart data={months} x="month" stack="expand" />
+      </Chart>
+      <Chart id="b5" title="Net new customers" sub="Negative bars hang below the ground line" config={{ change: { label: 'Net change', format: (v) => (v > 0 ? '+' : '') + v } }}>
+        <BarChart data={net} x="month" />
+      </Chart>
+      <Chart id="b6" title="Seats by region" sub='layout="horizontal", against last quarter' config={{ seats: { label: 'Seats', format: (v) => v.toLocaleString('en') } }}>
+        <BarChart data={regions} x="region" layout="horizontal" compare={{ key: 'before', label: 'Q2' }} labels="max" />
+      </Chart>
+    </div>
+  );
+}
+```
+<!-- /example -->

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

@@ -27,3 +27,61 @@ Top pages, top referrers, top customers by spend: a ranked list where each row i
 - Do fold a long tail into "Other" with `limit` rather than scrolling a hundred rows.
 - Don't colour bars by status or give each row its own colour: colour is identity, and these rows are one series.
 - Don't set the bars' lengths to share of total yourself; `share` says it in words, and the bars compare rows with each other.
+
+<!-- example: generated from build/previews.txt by build/previews.mjs. Edit the preview, not this section. -->
+## Example
+
+`BarList` as first used in its preview:
+
+```tsx
+import { BarList } from 'altitude-design';
+
+<BarList aria-labelledby="bl-pages" data={pages.map((p) => ({ ...p, href: '#' + p.name }))} limit={7} share noun="pages" />
+```
+
+The full preview, as rendered in Storybook and checked in CI (`bl`, `bl-tools` are the preview page's own layout classes, not Altitude's):
+
+```tsx
+import * as React from 'react';
+import { BarList, Button, Card, CardContent, CardDescription, CardHeader, CardTitle, Input } from 'altitude-design';
+
+const pages = [
+  { name: '/pricing', value: 4210 }, { name: '/', value: 3880 }, { name: '/docs/getting-started', value: 2410 }, { name: '/blog/height-is-the-interface-why-we-stopped-using-shadows-for-everything', value: 1630 },
+  { name: '/changelog', value: 1210 }, { name: '/docs/components/chart-container', value: 980 }, { name: '/careers', value: 610 },
+  ...Array.from({ length: 14 }, (_, i) => ({ name: `/docs/page-${i + 1}`, value: 420 - i * 25 })),
+];
+const referrers0 = [{ name: 'google.com', value: 5120 }, { name: 'github.com', value: 2310 }, { name: 'news.ycombinator.com', value: 1980 }, { name: 'x.com', value: 760 }, { name: 'Direct', value: 3400 }];
+const referrers1 = [{ name: 'google.com', value: 5240 }, { name: 'github.com', value: 2390 }, { name: 'news.ycombinator.com', value: 6120 }, { name: 'x.com', value: 1310 }, { name: 'Direct', value: 3460 }];
+export default function App() {
+  const [spike, setSpike] = React.useState(false);
+  const [q, setQ] = React.useState('');
+  const [later, setLater] = React.useState(undefined);
+  React.useEffect(() => { const t = setTimeout(() => setLater([{ name: 'Acme Corp', value: 48200 }, { name: 'Globex', value: 31900 }, { name: 'Initech', value: 22750 }, { name: 'Umbrella', value: 9400 }]), 2400); return () => clearTimeout(t); }, []);
+  const usd = new Intl.NumberFormat('en', { style: 'currency', currency: 'USD', maximumFractionDigits: 0 });
+  return (
+    <div className="bl">
+      <Card>
+        <CardHeader><CardTitle id="bl-pages">Top pages</CardTitle><CardDescription>Last 7 days · views</CardDescription></CardHeader>
+        <CardContent><BarList aria-labelledby="bl-pages" data={pages.map((p) => ({ ...p, href: '#' + p.name }))} limit={7} share noun="pages" /></CardContent>
+      </Card>
+      <div style={{ display: 'grid', gap: 16, alignContent: 'start' }}>
+        <Card>
+          <CardHeader><CardTitle id="bl-ref">Top referrers</CardTitle><CardDescription>Static rows: nothing lifts</CardDescription></CardHeader>
+          <CardContent>
+            <div className="bl-tools">
+              <Button size="sm" variant="secondary" onClick={() => setSpike((s) => !s)}>{spike ? 'Yesterday' : 'Today'}</Button>
+              <Input size="sm" placeholder="Filter" aria-label="Filter referrers" value={q} onChange={(e) => setQ(e.target.value)} />
+            </div>
+            <BarList aria-labelledby="bl-ref" data={spike ? referrers1 : referrers0} relevance={q ? (d) => (d.name.includes(q) ? 'match' : 'miss') : undefined} />
+          </CardContent>
+        </Card>
+        <Card>
+          <CardHeader><CardTitle id="bl-cust">Top customers</CardTitle><CardDescription>Spend this quarter</CardDescription></CardHeader>
+          <CardContent><BarList aria-labelledby="bl-cust" data={later} format={usd.format} limit={4} /></CardContent>
+        </Card>
+      </div>
+    </div>
+  );
+}
+```
+<!-- /example -->

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

@@ -29,3 +29,70 @@ Columns of cards you move between, a kanban: columns are receptacles that open w
 - Do keep buttons and links inside cards: pressing them doesn't pick the card up.
 - Do collapse finished columns rather than hiding them; the pile keeps their weight visible.
 - Don't use a board for a single list you reorder; that's SortableList.
+
+<!-- example: generated from build/previews.txt by build/previews.mjs. Edit the preview, not this section. -->
+## Example
+
+`Board` as first used in its preview:
+
+```tsx
+import { Board, BoardCard, BoardColumn, Field, Input } from 'altitude-design';
+
+<Board onMove={move} aria-label="Launch board">
+  {Object.keys(titles).map(k => <BoardColumn key={k} id={k} title={titles[k]} collapsible={k === "done"} defaultCollapsed={k === "done"} onCreate={k === "done" ? undefined : create(k)}>
+    {cols[k].map(c => <BoardCard key={c.id} id={c.id} label={c.t} heldBy={c.held} onRename={rename(k, c.id)}
+      {...(k === "review" ? { value: { title: c.t, meta: c.m }, onValueChange: update(k, c.id),
+        renderEditor: field => <><Field label="Title"><Input {...field("title")} size="sm" /></Field><Field label="Details"><Input {...field("meta")} size="sm" /></Field></>,
+        onSave: async draft => { await wait(200); return refuse(draft.title) || { ok: true, value: draft }; } } : {})}>
+      {c.t}<small>{c.m}</small>
+    </BoardCard>)}
+  </BoardColumn>)}
+</Board>
+```
+
+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 { Board, BoardCard, BoardColumn, Field, Input } from 'altitude-design';
+
+const start = {
+  todo: [{ id: "c1", t: "Write release notes", m: "Docs \xB7 Jon" }, { id: "c2", t: "Fix cold-start regression", m: "Runtime \xB7 Lena" }, { id: "c3", t: "Plan Q1 roadmap", m: "Planning \xB7 Ada" }],
+  doing: [{ id: "c4", t: "Pricing page copy", m: "Marketing \xB7 Mara", held: { name: "Mara", presence: 1 } }, { id: "c5", t: "Support macros", m: "Support \xB7 Ivy" }],
+  review: [{ id: "c6", t: "Brand voice", m: "Design \xB7 Ada" }],
+  done: Array.from({ length: 12 }, (_, i) => ({ id: "d" + i, t: "Shipped item " + (i + 1), m: "Done" }))
+};
+const titles = { todo: "To do", doing: "In progress", review: "Review", done: "Done" };
+export default function App() {
+  const [cols, setCols] = React.useState(start);
+  const [last, setLast] = React.useState(null);
+  const seq = React.useRef(0);
+  const move = ({ cardId, from, to }) => setCols((c) => {
+    const next = Object.fromEntries(Object.entries(c).map(([k, v]) => [k, v.slice()]));
+    const [card] = next[from.column].splice(from.index, 1);
+    next[to.column].splice(to.index, 0, card);
+    setLast(`${card.t} \u2192 ${titles[to.column]}`);
+    return next;
+  });
+  const wait = ms => new Promise(r => setTimeout(r, ms));
+  // The demo service refuses titles with “TBD” in them.
+  const refuse = t => /tbd/i.test(t) ? { ok: false, error: "Write the task, not \u201cTBD\u201d." } : null;
+  const create = k => async t => { await wait(250); const no = refuse(t); if (no) return no; const card = { id: "n" + ++seq.current, t, m: "New" }; setCols(c => ({ ...c, [k]: [...c[k], card] })); return { ok: true, value: { id: card.id } }; };
+  const rename = (k, id) => async t => { await wait(200); const no = refuse(t); if (no) return no; setCols(c => ({ ...c, [k]: c[k].map(x => x.id === id ? { ...x, t } : x) })); return { ok: true, value: t }; };
+  const update = (k, id) => v => setCols(c => ({ ...c, [k]: c[k].map(x => x.id === id ? { ...x, t: v.title, m: v.meta } : x) }));
+  return <div className="col" style={{ gap: 4 }}>
+    <Board onMove={move} aria-label="Launch board">
+      {Object.keys(titles).map(k => <BoardColumn key={k} id={k} title={titles[k]} collapsible={k === "done"} defaultCollapsed={k === "done"} onCreate={k === "done" ? undefined : create(k)}>
+        {cols[k].map(c => <BoardCard key={c.id} id={c.id} label={c.t} heldBy={c.held} onRename={rename(k, c.id)}
+          {...(k === "review" ? { value: { title: c.t, meta: c.m }, onValueChange: update(k, c.id),
+            renderEditor: field => <><Field label="Title"><Input {...field("title")} size="sm" /></Field><Field label="Details"><Input {...field("meta")} size="sm" /></Field></>,
+            onSave: async draft => { await wait(200); return refuse(draft.title) || { ok: true, value: draft }; } } : {})}>
+          {c.t}<small>{c.m}</small>
+        </BoardCard>)}
+      </BoardColumn>)}
+    </Board>
+    <p className="cap">{last ? `Moved: ${last}.` : "Drag a card, or focus one and press Space, then the arrow keys. F2 renames a card; each column adds cards at its foot. Done is collapsed into a pile and still takes cards."}</p>
+  </div>;
+}
+```
+<!-- /example -->

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

@@ -33,3 +33,34 @@ Where you are in an app with routes: Settings › Members › Jane Doe, or Proje
 - Do use it for location in a hierarchy, not for history ("back").
 - Don't add separators between steps.
 - Don't use it inside a `Drilldown`, which has its own.
+
+<!-- example: generated from build/previews.txt by build/previews.mjs. Edit the preview, not this section. -->
+## Example
+
+`Breadcrumb` as first used in its preview:
+
+```tsx
+import { Breadcrumb } from 'altitude-design';
+
+<Breadcrumb items={[{ label: 'Settings', href: '#/settings' }, { label: 'Members', href: '#/settings/members' }, { label: 'Jane Doe' }]} />
+```
+
+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 { Breadcrumb } from 'altitude-design';
+
+const RouterLink = React.forwardRef(({ to, ...rest }, ref) => <a ref={ref} href={'#' + to} {...rest} />);
+export default function App() {
+  return (
+    <div className="col">
+      <Breadcrumb items={[{ label: 'Settings', href: '#/settings' }, { label: 'Members', href: '#/settings/members' }, { label: 'Jane Doe' }]} />
+      <Breadcrumb maxItems={4} renderLink={(item, props) => <RouterLink to={item.href.slice(1)} {...props}>{item.label}</RouterLink>}
+        items={[{ label: 'Projects', href: '#/projects' }, { label: 'Atlas', href: '#/projects/atlas' }, { label: 'Q4 launch', href: '#/projects/atlas/q4' }, { label: 'Issues', href: '#/projects/atlas/q4/issues' }, { label: 'Billing page', href: '#/projects/atlas/q4/issues/212' }, { label: 'Comments' }]} />
+      <p className="cap">Each step you can go back to lifts when pointed at; the current page is the tallest step and doesn't press. A deep path keeps its first and last steps, with the middle behind "…".</p>
+    </div>
+  );
+}
+```
+<!-- /example -->

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

@@ -15,3 +15,44 @@ The wall is the face colour darkened, so it reads in every scheme and with any c
 
 - Don't put two primary buttons in one view. Promote one, demote the other to secondary.
 - Leave room below a row of buttons: the wall extends up to 5px under the face.
+
+<!-- example: generated from build/previews.txt by build/previews.mjs. Edit the preview, not this section. -->
+## Example
+
+`Button` as first used in its preview:
+
+```tsx
+import { Button } from 'altitude-design';
+
+<Button variant="primary">Publish changes</Button>
+```
+
+The full preview, as rendered in Storybook and checked in CI (`col`, `row`, `cap` are the preview page's own layout classes, not Altitude's):
+
+```tsx
+import * as React from 'react';
+import { Button, Icons } from 'altitude-design';
+
+export default function App() {
+  const [busy, setBusy] = React.useState(false);
+  return (
+    <div className="col">
+      <div className="row">
+        <Button variant="primary">Publish changes</Button>
+        <Button>Preview</Button>
+        <Button variant="ghost">Cancel</Button>
+        <Button variant="danger">Delete project</Button>
+      </div>
+      <div className="row">
+        <Button variant="primary" size="sm">Small</Button>
+        <Button variant="primary" size="lg">Large</Button>
+        <Button square aria-label="Close"><Icons.X /></Button>
+        <Button variant="primary" loading={busy} onClick={() => { setBusy(true); setTimeout(() => setBusy(false), 1600); }}>Save</Button>
+        <Button disabled>Disabled</Button>
+      </div>
+      <p className="cap">Primary rests at level 2, secondary at 1, ghost at 0. Hover climbs one level; pressing returns to the ground. Click Save: a loading button stays pressed.</p>
+    </div>
+  );
+}
+```
+<!-- /example -->

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

@@ -12,3 +12,41 @@ Cards take the same depth signals as `Surface`: `settle`, `status`, `heldBy` and
 
 - Do make the entire card the target when it navigates somewhere (a project tile).
 - Don't make a card interactive *and* put buttons inside it: nested targets break the press metaphor. Keep the card static and let its buttons lift.
+
+<!-- example: generated from build/previews.txt by build/previews.mjs. Edit the preview, not this section. -->
+## Example
+
+`Card` as first used in its preview:
+
+```tsx
+import { Card, CardContent, CardDescription, CardHeader, CardTitle } from 'altitude-design';
+
+<Card>
+  <CardHeader><CardTitle>Usage this month</CardTitle><CardDescription>Static: a grouping surface, it never lifts.</CardDescription></CardHeader>
+  <CardContent>18,240 requests · 62% of plan</CardContent>
+</Card>
+```
+
+The full preview, as rendered in Storybook and checked in CI (`grid` is the preview page's own layout class, not Altitude's):
+
+```tsx
+import * as React from 'react';
+import { Card, CardContent, CardDescription, CardHeader, CardTitle } from 'altitude-design';
+
+export default function App() {
+  const [n, setN] = React.useState(0);
+  return (
+    <div className="grid">
+      <Card>
+        <CardHeader><CardTitle>Usage this month</CardTitle><CardDescription>Static: a grouping surface, it never lifts.</CardDescription></CardHeader>
+        <CardContent>18,240 requests · 62% of plan</CardContent>
+      </Card>
+      <Card interactive onClick={() => setN(n + 1)}>
+        <CardHeader><CardTitle>Open project</CardTitle><CardDescription>Interactive: the whole card is the target, so it lifts and presses.</CardDescription></CardHeader>
+        <CardContent>{n ? `Opened ${n}×` : 'Click or press Enter'}</CardContent>
+      </Card>
+    </div>
+  );
+}
+```
+<!-- /example -->

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

@@ -39,3 +39,60 @@ const [range, setRange] = React.useState({ start: '2026-03-01', end: '2026-04-30
 - Do give the window a typed twin (a `DateRangePicker`) when exact dates matter; dragging is for finding, typing for stating.
 - Don't use a brush for a few dozen records: the chart can show them all.
 - Don't put a brush on a chart of categories; it windows records in their order, which only means something over time.
+
+<!-- example: generated from build/previews.txt by build/previews.mjs. Edit the preview, not this section. -->
+## Example
+
+`ChartBrush` as first used in its preview:
+
+```tsx
+import { ChartBrush } from 'altitude-design';
+
+<ChartBrush />
+```
+
+The full preview, as rendered in Storybook and checked in CI (`cb`, `col`, `pick` are the preview page's own layout classes, not Altitude's):
+
+```tsx
+import * as React from 'react';
+import { AreaChart, BarChart, Card, CardContent, CardDescription, CardHeader, CardTitle, ChartBrush, ChartContainer, DateRangePicker, Field } from 'altitude-design';
+
+// A year of daily active users, with a dip in August and a launch in late September.
+const cbYear = Array.from({ length: 365 }, (_, i) => {
+  const day = new Date(Date.UTC(2026, 0, 1 + i)).toISOString().slice(0, 10);
+  const trend = 4200 + i * 9, week = [0.82, 1, 1.04, 1.05, 1.03, 0.97, 0.78][i % 7];
+  const summer = i > 212 && i < 243 ? 0.8 : 1, launch = i > 265 ? 1.18 : 1;
+  return { day, active: Math.round((trend + 260 * Math.sin(i / 9)) * week * summer * launch) };
+});
+const cbWeeks = Array.from({ length: 52 }, (_, i) => ({ week: new Date(Date.UTC(2026, 0, 5 + i * 7)).toISOString().slice(0, 10), signups: Math.round(310 + i * 6 + 90 * Math.sin(i / 3) + (i > 37 ? 160 : 0)) }));
+const cbK = new Intl.NumberFormat('en', { notation: 'compact', maximumFractionDigits: 1 });
+export default function App() {
+  const [range, setRange] = React.useState({ start: '2026-03-01', end: '2026-04-30' });
+  return (
+    <div className="cb">
+      <Card>
+        <CardHeader><CardTitle id="cb1">Daily active users</CardTitle><CardDescription>Drag the lens to pan, a grip to resize, or press the overview to centre it there. The picker is the same state, typed.</CardDescription></CardHeader>
+        <CardContent className="col">
+          <Field label="Window" className="pick"><DateRangePicker value={range} onValueChange={setRange} min="2026-01-01" max="2026-12-31" locale="en-GB" /></Field>
+          <ChartContainer aria-labelledby="cb1" config={{ active: { label: 'Active users', format: cbK.format } }} aspect={3.4} locale="en-GB">
+            <AreaChart data={cbYear} x="day" window={range} onWindowChange={setRange}>
+              <ChartBrush />
+            </AreaChart>
+          </ChartContainer>
+        </CardContent>
+      </Card>
+      <Card>
+        <CardHeader><CardTitle id="cb2">Weekly sign-ups</CardTitle><CardDescription>Bars over time with a brush that keeps its own window</CardDescription></CardHeader>
+        <CardContent>
+          <ChartContainer aria-labelledby="cb2" config={{ signups: { label: 'Sign-ups' } }} aspect={4} locale="en-GB">
+            <BarChart data={cbWeeks} x="week">
+              <ChartBrush />
+            </BarChart>
+          </ChartContainer>
+        </CardContent>
+      </Card>
+    </div>
+  );
+}
+```
+<!-- /example -->

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

@@ -150,3 +150,80 @@ function Target({ value }) {
 - Don't give marks a shadow, a wall, a sheen, a gradient or a lift.
 - Don't colour text with a series colour; labels and ticks wear `ink` and `ink-muted`.
 - Don't draw more than about 2,000 marks: SVG gets slow. Aggregate, or use a canvas library with Altitude's theme (#77).
+
+<!-- example: generated from build/previews.txt by build/previews.mjs. Edit the preview, not this section. -->
+## Example
+
+`ChartContainer` as first used in its preview:
+
+```tsx
+import { ChartContainer } from 'altitude-design';
+
+<ChartContainer aria-labelledby="rc" data={months} x="month" aspect={1.7} summary="Revenue rose 44% while costs held flat."
+  config={{ revenue: { label: 'Revenue', format: usd.format }, costs: { label: 'Costs', format: usd.format } }}>
+  <Lines />
+</ChartContainer>
+```
+
+The full preview, as rendered in Storybook and checked in CI (`charts` is the preview page's own layout class, not Altitude's):
+
+```tsx
+import { Card, CardContent, CardDescription, CardHeader, CardTitle, ChartContainer, ChartMarker, useChart } from 'altitude-design';
+
+// Until the chart types land, these marks are drawn by hand with useChart(): the same scales the types will use.
+const usd = new Intl.NumberFormat('en', { style: 'currency', currency: 'USD', notation: 'compact' });
+const months = [
+  { month: '2026-01-01', revenue: 8200, costs: 5100 }, { month: '2026-02-01', revenue: 8900, costs: 5000 },
+  { month: '2026-03-01', revenue: 9400, costs: 5300 }, { month: '2026-04-01', revenue: 9100, costs: 5200 },
+  { month: '2026-05-01', revenue: 10600, costs: 5400 }, { month: '2026-06-01', revenue: 11800, costs: 5300 },
+];
+const regions = [
+  { region: 'North', q2: 42, q3: 51 }, { region: 'South', q2: 35, q3: 31 }, { region: 'East', q2: 28, q3: 37 }, { region: 'West', q2: 19, q3: 24 },
+];
+// encode() draws a series by its slot: colour, and a dash, marker or hatch whenever patterns are on (forced colours, print).
+function Lines() {
+  const { series, data, xOf, y, encode, patterns, strokeWidth } = useChart();
+  return series.map((s) => {
+    const e = encode(s.key);
+    return <g key={s.key}>
+      <polyline fill="none" stroke={e.stroke} strokeDasharray={e.dash} strokeWidth={strokeWidth} strokeLinejoin="round" strokeLinecap="round"
+        points={data.map((d) => `${xOf(d)},${y(d[s.key])}`).join(' ')} />
+      {patterns && data.map((d, i) => <ChartMarker key={i} shape={e.marker} x={xOf(d)} y={y(d[s.key])} color={e.stroke} />)}
+    </g>;
+  });
+}
+function Bars() {
+  const { series, data, x, y, xKey, ground, alpha, encode, gap } = useChart();
+  const w = (x.bandwidth - gap * (series.length - 1)) / series.length;
+  return data.map((d) => series.map((s, i) => {
+    const v = d[s.key], top = Math.min(y(v), ground), e = encode(s.key);
+    return <rect key={d[xKey] + s.key} x={x(d[xKey]) + i * (w + gap)} y={top} width={w} height={Math.abs(y(v) - ground)}
+      fill={e.fill} stroke={e.edge} strokeWidth={e.edge ? 1 : undefined} opacity={alpha(d, s.key)} />;
+  }));
+}
+export default function App() {
+  return (
+    <div className="charts">
+      <Card>
+        <CardHeader><CardTitle id="rc">Revenue and costs</CardTitle><CardDescription>Jan to Jun 2026</CardDescription></CardHeader>
+        <CardContent>
+          <ChartContainer aria-labelledby="rc" data={months} x="month" aspect={1.7} summary="Revenue rose 44% while costs held flat."
+            config={{ revenue: { label: 'Revenue', format: usd.format }, costs: { label: 'Costs', format: usd.format } }}>
+            <Lines />
+          </ChartContainer>
+        </CardContent>
+      </Card>
+      <Card>
+        <CardHeader><CardTitle id="dr">Deals closed by region</CardTitle><CardDescription>Q2 and Q3</CardDescription></CardHeader>
+        <CardContent>
+          <ChartContainer aria-labelledby="dr" data={regions} x="region" aspect={1.7}
+            config={{ q2: { label: 'Q2' }, q3: { label: 'Q3' } }}>
+            <Bars />
+          </ChartContainer>
+        </CardContent>
+      </Card>
+    </div>
+  );
+}
+```
+<!-- /example -->

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

@@ -33,3 +33,46 @@ Names each series, and optionally lets people hide and show series. Every chart
 - Do use `toggle` when people need to compare a few series out of many; otherwise a static legend is quieter.
 - Don't let colour be the only link between a key and its series: under forced colours the keys show each series' pattern.
 - Don't put the legend somewhere the chart's readout or summary can't be read alongside it.
+
+<!-- example: generated from build/previews.txt by build/previews.mjs. Edit the preview, not this section. -->
+## Example
+
+`ChartLegend` as first used in its preview:
+
+```tsx
+import { ChartLegend, ChartLegendContent } from 'altitude-design';
+
+<ChartLegend content={<ChartLegendContent />} />
+```
+
+The full preview, as rendered in Storybook and checked in CI (`cl` is the preview page's own layout class, not Altitude's):
+
+```tsx
+import { BarChart, Card, CardContent, CardDescription, CardHeader, CardTitle, ChartContainer, ChartLegend, ChartLegendContent, LineChart } from 'altitude-design';
+
+const months = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun'].map((month, i) => ({ month, api: 20 + ((i * 7) % 11), web: 14 + ((i * 5) % 9), jobs: 6 + ((i * 3) % 7) }));
+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 }));
+export default function App() {
+  return (
+    <div className="cl">
+      <Card>
+        <CardHeader><CardTitle id="g1">Requests, all services</CardTitle><CardDescription>A legend that only labels</CardDescription></CardHeader>
+        <CardContent>
+          <ChartContainer aria-labelledby="g1" aspect={1.8} config={{ api: { label: 'API' }, web: { label: 'Web' }, jobs: { label: 'Jobs' } }}>
+            <BarChart data={months} x="month" stack><ChartLegend content={<ChartLegendContent />} /></BarChart>
+          </ChartContainer>
+        </CardContent>
+      </Card>
+      <Card>
+        <CardHeader><CardTitle id="g2">Seats by plan</CardTitle><CardDescription>toggle: each key is a switch; Enterprise starts hidden</CardDescription></CardHeader>
+        <CardContent>
+          <ChartContainer aria-labelledby="g2" aspect={1.8} config={{ free: { label: 'Free' }, team: { label: 'Team' }, business: { label: 'Business' }, enterprise: { label: 'Enterprise' } }}>
+            <LineChart data={plans} x="month"><ChartLegend content={<ChartLegendContent toggle defaultHidden={['enterprise']} />} /></LineChart>
+          </ChartContainer>
+        </CardContent>
+      </Card>
+    </div>
+  );
+}
+```
+<!-- /example -->