altitude-design 0.4.0 → 0.4.1

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

@@ -34,3 +34,32 @@ Collapsing a pane changes its size on `ease-glide`, not its level.
 - Do set a `minSize` that keeps a pane usable.
 - Don't use it for a task that sits on top of the page; that's a `Sheet`.
 - Don't raise a pane into a card.
+
+<!-- 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 (`rz`, `detail`, `cap` are the preview page's own layout classes, not Altitude's):
+
+```tsx
+import * as React from 'react';
+import { ResizableHandle, ResizablePanel, ResizablePanelGroup } from 'altitude-design';
+
+const threads = ['Invoice INV-0042 failed', 'Welcome to the beta', 'Your export is ready', 'Q4 planning notes', 'Security alert: new sign-in'];
+export default function App() {
+  const [open, setOpen] = React.useState(0);
+  return (
+    <div className="rz">
+      <ResizablePanelGroup direction="horizontal">
+        <ResizablePanel defaultSize={35} minSize={20} maxSize={60} collapsible aria-label="Conversations">
+          <ul>{threads.map((t, i) => <li key={t}><button aria-current={i === open || undefined} onClick={() => setOpen(i)}>{t}</button></li>)}</ul>
+        </ResizablePanel>
+        <ResizableHandle />
+        <ResizablePanel aria-label="Conversation">
+          <div className="detail"><h2>{threads[open]}</h2><p className="cap">Drag the grip, or focus it and use the arrow keys; Enter collapses the list. The panes stay on the ground; only the grip lifts, and floats while held.</p></div>
+        </ResizablePanel>
+      </ResizablePanelGroup>
+    </div>
+  );
+}
+```
+<!-- /example -->

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

@@ -25,3 +25,41 @@ const record = useEditRecord({ initialValue: settings, validate, validationMode:
 - Do keep the draft when a save fails.
 - Don't use it beside an `EditRegion`, which has its own Save.
 - Don't show it on the first keystroke.
+
+<!-- example: generated from build/previews.txt by build/previews.mjs. Edit the preview, not this section. -->
+## Example
+
+`SaveBar` as first used in its preview:
+
+```tsx
+import { SaveBar } from 'altitude-design';
+
+<SaveBar record={record} />
+```
+
+The full preview, as rendered in Storybook and checked in CI (`col`, `sb`, `cap` are the preview page's own layout classes, not Altitude's):
+
+```tsx
+import * as React from 'react';
+import { Field, Input, SaveBar, Switch, useEditRecord } from 'altitude-design';
+
+export default function App() {
+  const [failNext, setFailNext] = React.useState(false);
+  const fail = React.useRef(false); fail.current = failNext;
+  const record = useEditRecord({
+    initialValue: { name: 'Acme Inc.', domain: 'acme.dev', seats: '25', region: 'Frankfurt' }, validationMode: 'submit',
+    validate: (d) => (d.name.trim() ? {} : { name: 'Enter a workspace name' }),
+    save: (draft) => new Promise((r) => setTimeout(() => r(fail.current ? { ok: false, error: "We couldn't reach the server." } : { ok: true, value: draft }), 900)),
+  });
+  const f = (key, label) => <Field label={label} error={record.errors[key]}><Input value={record.draft[key]} onChange={(e) => record.setDraft({ ...record.draft, [key]: e.target.value })} /></Field>;
+  return (
+    <div className="col">
+      <div className="sb">{f('name', 'Workspace name')}{f('domain', 'Domain')}{f('seats', 'Seats')}{f('region', 'Region')}</div>
+      <Switch label="Make the next save fail" checked={failNext} onCheckedChange={setFailNext} />
+      <p className="cap">Change a field: once the change settles, the bar rises from the bottom edge. ⌘S or Save hovers while saving and lowers away when saved; a failed save drops into a trench and keeps your changes.</p>
+      <SaveBar record={record} />
+    </div>
+  );
+}
+```
+<!-- /example -->

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

@@ -22,3 +22,61 @@ const views = useSavedViews({ views: saved, onSave, onCreate });
 - Do keep the default view ("All deals") unfiltered.
 - Don't save a view on every change; a draft is saved when someone says so.
 - Don't use segmented tabs; the views own the table beneath them, so they're folder tabs.
+
+<!-- example: generated from build/previews.txt by build/previews.mjs. Edit the preview, not this section. -->
+## Example
+
+`SavedViews` as first used in its preview:
+
+```tsx
+import { DataTable, FilterBar, FormattedNumber, SavedViews } from 'altitude-design';
+
+<SavedViews views={views} aria-label="Deal views">
+  <FilterBar fields={fields} {...views.filterBarProps} aria-label="Filter deals" />
+  <DataTable aria-label="Deals" rows={deals} getRowId={(r) => r.id} {...views.tableProps} columnsMenu density="compact"
+    relevance={(r) => (value.some((f) => f.value !== undefined) ? (matches(r, value, match) ? 'match' : 'miss') : undefined)}
+    columns={[{ key: 'name', header: 'Deal', sortValue: (r) => r.name }, { key: 'stage', header: 'Stage', sortValue: (r) => r.stage }, { key: 'owner', header: 'Owner', sortValue: (r) => r.owner },
+      { key: 'value', header: 'Value', align: 'end', sortValue: (r) => r.value, cell: (r) => <FormattedNumber value={r.value} format="currency" currency="USD" minorUnits={false} maximumFractionDigits={0} /> }]} />
+</SavedViews>
+```
+
+The full preview, as rendered in Storybook and checked in CI:
+
+```tsx
+import * as React from 'react';
+import { DataTable, FilterBar, FormattedNumber, SavedViews, useSavedViews } from 'altitude-design';
+
+const deals = [
+  { id: 'd1', name: 'Northwind renewal', stage: 'Negotiation', owner: 'Maya', value: 48000 },
+  { id: 'd2', name: 'Globex expansion', stage: 'Proposal', owner: 'Theo', value: 120000 },
+  { id: 'd3', name: 'Initech pilot', stage: 'Discovery', owner: 'Maya', value: 9000 },
+  { id: 'd4', name: 'Umbrella security', stage: 'Negotiation', owner: 'Ada', value: 76000 },
+  { id: 'd5', name: 'Hooli seats', stage: 'Closed won', owner: 'Theo', value: 31000 },
+];
+const fields = [
+  { key: 'stage', label: 'Stage', type: 'enum', options: ['Discovery', 'Proposal', 'Negotiation', 'Closed won'].map((x) => ({ value: x, label: x })) },
+  { key: 'owner', label: 'Owner', type: 'enum', options: ['Maya', 'Theo', 'Ada'].map((x) => ({ value: x, label: x })) },
+];
+const matches = (r, filters, match) => { const t = filters.filter((f) => f.value !== undefined).map((f) => (f.operator === 'is' ? r[f.field] === f.value : r[f.field] !== f.value)); return !t.length || (match === 'any' ? t.some(Boolean) : t.every(Boolean)); };
+export default function App() {
+  const [saved, setSaved] = React.useState([
+    { id: 'all', name: 'All deals', sort: { key: 'value', direction: 'descending' } },
+    { id: 'mine', name: 'My open deals', filters: [{ id: 'f1', field: 'owner', operator: 'is', value: 'Maya' }, { id: 'f2', field: 'stage', operator: 'is not', value: 'Closed won' }] },
+    { id: 'late', name: 'In negotiation', filters: [{ id: 'f3', field: 'stage', operator: 'is', value: 'Negotiation' }], columnVisibility: { owner: false } },
+  ]);
+  const views = useSavedViews({ views: saved,
+    onSave: (v) => setSaved((xs) => xs.map((x) => (x.id === v.id ? v : x))),
+    onCreate: (v) => setSaved((xs) => [...xs, { ...v, id: 'v' + xs.length }]) });
+  const { value, match } = views.filterBarProps;
+  return (
+    <SavedViews views={views} aria-label="Deal views">
+      <FilterBar fields={fields} {...views.filterBarProps} aria-label="Filter deals" />
+      <DataTable aria-label="Deals" rows={deals} getRowId={(r) => r.id} {...views.tableProps} columnsMenu density="compact"
+        relevance={(r) => (value.some((f) => f.value !== undefined) ? (matches(r, value, match) ? 'match' : 'miss') : undefined)}
+        columns={[{ key: 'name', header: 'Deal', sortValue: (r) => r.name }, { key: 'stage', header: 'Stage', sortValue: (r) => r.stage }, { key: 'owner', header: 'Owner', sortValue: (r) => r.owner },
+          { key: 'value', header: 'Value', align: 'end', sortValue: (r) => r.value, cell: (r) => <FormattedNumber value={r.value} format="currency" currency="USD" minorUnits={false} maximumFractionDigits={0} /> }]} />
+    </SavedViews>
+  );
+}
+```
+<!-- /example -->

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

@@ -39,3 +39,66 @@ Two measures per record, to see whether they move together and to spot the ones
 - Do say what a correlation means in the `summary`; don't let a trend line stand in for a cause.
 - Don't use more than three groups; split into small multiples.
 - Don't size dots by a third measure; it's two measures per record, read by position.
+
+<!-- example: generated from build/previews.txt by build/previews.mjs. Edit the preview, not this section. -->
+## Example
+
+`ScatterChart` as first used in its preview:
+
+```tsx
+import { ChartLegend, ChartLegendContent, ScatterChart } from 'altitude-design';
+
+<ScatterChart data={endpoints} x="kb" y="ms" group="service" id="name" name="name" label={(d) => (d.ms > 250 && d.kb < 300 ? d.name : null)} trend>
+  <ChartLegend content={<ChartLegendContent toggle label="Services" />} />
+</ScatterChart>
+```
+
+The full preview, as rendered in Storybook and checked in CI (`sc`, `sc-foot` are the preview page's own layout classes, not Altitude's):
+
+```tsx
+import * as React from 'react';
+import { Button, Card, CardContent, CardDescription, CardHeader, CardTitle, ChartContainer, ChartLegend, ChartLegendContent, ScatterChart } from 'altitude-design';
+
+const svc = ['Checkout', 'Search', 'Media'];
+// p95 latency against payload per endpoint: latency climbs with payload, Media's big payloads most of all.
+const endpoints = Array.from({ length: 30 }, (_, i) => {
+  const service = svc[i % 3], kb = Math.round(8 + ((i * 53) % 97) * (service === 'Media' ? 4.1 : 2.2));
+  const ms = Math.round(70 + kb * (service === 'Media' ? 0.62 : 0.48) + ((i * 37) % 41) - 20 + (i === 13 ? 190 : 0));
+  return { name: `${service} ${['list', 'get', 'create', 'update', 'search', 'export', 'upload', 'sync', 'batch', 'stream'][Math.floor(i / 3)]}`, service, kb, ms };
+});
+const kb = (v) => `${Math.round(v)} KB`, ms = (v) => `${Math.round(v)} ms`;
+const usd = new Intl.NumberFormat('en', { style: 'currency', currency: 'USD', notation: 'compact' });
+const month = (m) => Array.from({ length: 16 }, (_, i) => {
+  const seats = 20 + ((i * 29) % 140) + m * (i % 4) * 6;
+  return { id: 'c' + i, name: ['Acme', 'Globex', 'Initech', 'Umbrella', 'Hooli', 'Vandelay', 'Stark', 'Wayne', 'Wonka', 'Tyrell', 'Cyberdyne', 'Soylent', 'Aperture', 'Massive', 'Oscorp', 'Gringotts'][i], seats, spend: Math.round(seats * (38 + ((i * 17) % 23)) + m * 300) };
+});
+export default function App() {
+  const [m, setM] = React.useState(0);
+  const [picked, setPicked] = React.useState(null);
+  const customers = React.useMemo(() => month(m), [m]);
+  return (
+    <div className="sc">
+      <Card>
+        <CardHeader><CardTitle id="sc1">Latency against payload</CardTitle><CardDescription>p95 per endpoint, by service, with the trend</CardDescription></CardHeader>
+        <CardContent>
+          <ChartContainer aria-labelledby="sc1" aspect={1.5} config={{ kb: { label: 'Payload', format: kb }, ms: { label: 'p95', format: ms } }}>
+            <ScatterChart data={endpoints} x="kb" y="ms" group="service" id="name" name="name" label={(d) => (d.ms > 250 && d.kb < 300 ? d.name : null)} trend>
+              <ChartLegend content={<ChartLegendContent toggle label="Services" />} />
+            </ScatterChart>
+          </ChartContainer>
+        </CardContent>
+      </Card>
+      <Card>
+        <CardHeader><CardTitle id="sc2">Spend against seats</CardTitle><CardDescription>{picked ? `${picked.name} selected: the rest recede` : 'Per customer. Select one; dots glide by id when the month changes'}</CardDescription></CardHeader>
+        <CardContent>
+          <ChartContainer aria-labelledby="sc2" aspect={1.5} views config={{ seats: { label: 'Seats' }, spend: { label: 'Spend', format: usd.format } }}>
+            <ScatterChart data={customers} x="seats" y="spend" id="id" name="name" selected={picked ? picked.id : null} onSelect={setPicked} />
+          </ChartContainer>
+          <div className="sc-foot"><Button size="sm" variant="secondary" onClick={() => setM((n) => (n + 1) % 3)}>Next month</Button><span>Month {m + 1} of 3</span></div>
+        </CardContent>
+      </Card>
+    </div>
+  );
+}
+```
+<!-- /example -->

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

@@ -74,3 +74,69 @@ The events and their writes (with concurrency guards), time zones, and the detai
 The `Schedule` section of `build/previews.txt` is a room-booking work week (26–30 Oct 2026): the service refuses Wednesday mornings, rooms close at 17:00 on Friday, and Ana holds the Retro. `node checks/schedule.mjs` (from `build/`; `ALT_FIXTURE_ROOT` selects React 19 fixtures) covers the grid keys and names, creating, carrying, resizing and cancelling without a pointer, a refused move with Retry, unavailable time, a collaborator's hold, rename, remove, the next week, pointer carry, drawing and the resize handle, and 320/960px layouts in both schemes under reduced motion, forced colours and `contrast="more"`.
 **Narrow and on touch.** Under 480px of its own width the schedule shows one day at a time (`narrowView="day"`, the default; `false` keeps the week), paged by the header's previous and next. Under a coarse pointer an hour is 96px unless you set `hourHeight`, so a 15-minute slot is 24px tall, and a tap opens an event.
 
+<!-- example: generated from build/previews.txt by build/previews.mjs. Edit the preview, not this section. -->
+## Example
+
+`Schedule` as first used in its preview:
+
+```tsx
+import { Schedule } from 'altitude-design';
+
+<Schedule aria-label="Room bookings" view="workweek" date={date} onDateChange={setDate} now="2026-10-27T10:20"
+  events={events} getKey={e => e.id} getStart={e => e.start} getEnd={e => e.end} getLabel={e => e.title}
+  dayStart="08:00" dayEnd="18:00"
+  renderEvent={e => <><strong>{e.title}</strong><small className="sch-room">{e.start.slice(11)}–{e.end.slice(11)} · {e.room}</small></>}
+  heldBy={e => e.id === 'e6' ? { name: 'Ana', presence: 2 } : null}
+  // Rooms close at 17:00 on Fridays.
+  isUnavailable={({ start, end }) => start.slice(0, 10) === '2026-10-30' && end.slice(11) > '17:00'}
+  onChange={async ({ id, start, end }) => {
+    await schWait(300);
+    // The demo service refuses Wednesday mornings: the rooms are being cleaned.
+    if (start.slice(0, 10) === '2026-10-28' && start.slice(11) < '12:00') return { ok: false, error: 'Both rooms are being cleaned on Wednesday morning.' };
+    setEvents(list => list.map(e => e.id === id ? { ...e, start, end } : e)); return { ok: true };
+  }}
+  onCreate={async ({ start, end, title }) => { await schWait(300); const event = { id: 'n' + ++seq.current, title, start, end, room: 'Room A' }; setEvents(list => [...list, event]); return { ok: true, value: event }; }}
+  onRename={async (e, title) => { await schWait(200); setEvents(list => list.map(x => x.id === e.id ? { ...x, title } : x)); return { ok: true }; }}
+  onRemove={e => setEvents(list => list.filter(x => x.id !== e.id))} />
+```
+
+The full preview, as rendered in Storybook and checked in CI (`sch-demo`, `sch-room` are the preview page's own layout classes, not Altitude's):
+
+```tsx
+import * as React from 'react';
+import { Schedule } from 'altitude-design';
+
+const SCH_SEED = [
+  { id: 'e1', title: 'Standup', start: '2026-10-26T09:00', end: '2026-10-26T09:30', room: 'Room A' },
+  { id: 'e2', title: 'Design review', start: '2026-10-27T10:00', end: '2026-10-27T11:00', room: 'Room B' },
+  { id: 'e3', title: 'Customer call', start: '2026-10-27T10:30', end: '2026-10-27T11:15', room: 'Room A' },
+  { id: 'e4', title: 'Planning', start: '2026-10-28T13:00', end: '2026-10-28T14:30', room: 'Room B' },
+  { id: 'e5', title: 'Interview', start: '2026-10-29T15:00', end: '2026-10-29T16:00', room: 'Room A' },
+  { id: 'e6', title: 'Retro', start: '2026-10-30T11:00', end: '2026-10-30T12:00', room: 'Room B' },
+];
+const schWait = ms => new Promise(resolve => setTimeout(resolve, ms));
+export default function App() {
+  const [date, setDate] = React.useState('2026-10-26');
+  const [events, setEvents] = React.useState(SCH_SEED);
+  const seq = React.useRef(0);
+  return <div className="sch-demo">
+    <Schedule aria-label="Room bookings" view="workweek" date={date} onDateChange={setDate} now="2026-10-27T10:20"
+      events={events} getKey={e => e.id} getStart={e => e.start} getEnd={e => e.end} getLabel={e => e.title}
+      dayStart="08:00" dayEnd="18:00"
+      renderEvent={e => <><strong>{e.title}</strong><small className="sch-room">{e.start.slice(11)}–{e.end.slice(11)} · {e.room}</small></>}
+      heldBy={e => e.id === 'e6' ? { name: 'Ana', presence: 2 } : null}
+      // Rooms close at 17:00 on Fridays.
+      isUnavailable={({ start, end }) => start.slice(0, 10) === '2026-10-30' && end.slice(11) > '17:00'}
+      onChange={async ({ id, start, end }) => {
+        await schWait(300);
+        // The demo service refuses Wednesday mornings: the rooms are being cleaned.
+        if (start.slice(0, 10) === '2026-10-28' && start.slice(11) < '12:00') return { ok: false, error: 'Both rooms are being cleaned on Wednesday morning.' };
+        setEvents(list => list.map(e => e.id === id ? { ...e, start, end } : e)); return { ok: true };
+      }}
+      onCreate={async ({ start, end, title }) => { await schWait(300); const event = { id: 'n' + ++seq.current, title, start, end, room: 'Room A' }; setEvents(list => [...list, event]); return { ok: true, value: event }; }}
+      onRename={async (e, title) => { await schWait(200); setEvents(list => list.map(x => x.id === e.id ? { ...x, title } : x)); return { ok: true }; }}
+      onRemove={e => setEvents(list => list.filter(x => x.id !== e.id))} />
+  </div>;
+}
+```
+<!-- /example -->

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

@@ -5,3 +5,31 @@ A scrolling region whose edges show where content continues, so it never looks f
 When content continues above or below, that edge gets an inner lip (`lip-top`, `lip-bottom`), as if the content curves away under the rim. With a `header`, the header sits flush at the top and rises to `elev-2` as soon as content scrolls beneath it, then settles back when you return to the top. Both counter the illusion of completeness: people stop scrolling when a region looks complete.
 
 **You provide:** children, `maxHeight` (px or any CSS length), an optional `header`, and an `aria-label` (the body is keyboard-focusable so it can be scrolled with arrow keys).
+
+<!-- example: generated from build/previews.txt by build/previews.mjs. Edit the preview, not this section. -->
+## Example
+
+`ScrollArea` as first used in its preview:
+
+```tsx
+import { ScrollArea } from 'altitude-design';
+
+<ScrollArea maxHeight={240} aria-label="Invoices">{rows.map(([a, b]) => <div className="item" key={a}>{a}<span>{b}</span></div>)}</ScrollArea>
+```
+
+The full preview, as rendered in Storybook and checked in CI (`pair`, `item`, `head` are the preview page's own layout classes, not Altitude's):
+
+```tsx
+import { ScrollArea } from 'altitude-design';
+
+const rows = Array.from({ length: 18 }, (_, i) => ['Invoice #' + (2041 + i), '$' + (120 + i * 37) + '.00']);
+export default function App() {
+  return (
+    <div className="pair">
+      <ScrollArea maxHeight={240} aria-label="Invoices">{rows.map(([a, b]) => <div className="item" key={a}>{a}<span>{b}</span></div>)}</ScrollArea>
+      <ScrollArea maxHeight={196} header={<div className="head">Invoices · October</div>} aria-label="Invoices with header">{rows.map(([a, b]) => <div className="item" key={a}>{a}<span>{b}</span></div>)}</ScrollArea>
+    </div>
+  );
+}
+```
+<!-- /example -->

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

@@ -26,3 +26,49 @@ A key or token: an API key, a webhook signing secret, a personal access token. I
 - Do leave out `onReveal` for secrets you don't store in a retrievable form.
 - Don't show a stored secret in full by default.
 - Don't put revoke one click away; it's held.
+
+<!-- example: generated from build/previews.txt by build/previews.mjs. Edit the preview, not this section. -->
+## Example
+
+`SecretField` as first used in its preview:
+
+```tsx
+import { SecretField } from 'altitude-design';
+
+<SecretField label="Secret key" value="ak_live_EXAMPLE0000demo4f2a" once onAcknowledge={() => setSaved(true)} />
+```
+
+The full preview, as rendered in Storybook and checked in CI (`sf`, `col`, `cap` are the preview page's own layout classes, not Altitude's):
+
+```tsx
+import * as React from 'react';
+import { Button, Card, CardContent, CardDescription, CardFooter, CardHeader, CardTitle, SecretField } from 'altitude-design';
+
+export default function App() {
+  const [saved, setSaved] = React.useState(false);
+  const [said, setSaid] = React.useState('');
+  return (
+    <div className="sf">
+      <Card>
+        <CardHeader><CardTitle>API key created</CardTitle><CardDescription>Production · created just now</CardDescription></CardHeader>
+        <CardContent>
+          <SecretField label="Secret key" value="ak_live_EXAMPLE0000demo4f2a" once onAcknowledge={() => setSaved(true)} />
+        </CardContent>
+        <CardFooter><Button variant="primary" disabled={!saved}>Done</Button></CardFooter>
+      </Card>
+      <Card>
+        <CardHeader><CardTitle>Webhook signing secret</CardTitle><CardDescription>Used to verify deliveries to /hooks/billing</CardDescription></CardHeader>
+        <CardContent>
+          <div className="col">
+            <SecretField label="Signing secret" noun="secret" prefix="whk_" maskedTail="9d1c"
+              onReveal={() => new Promise((r) => setTimeout(() => r('whk_EXAMPLE0000demo9d1c'), 400))}
+              onRotate={() => setSaid('A new secret would be created; the old one keeps working for 24 hours.')} onRevoke={() => setSaid('Secret revoked.')} />
+            <p className="cap" role="status">{said}</p>
+          </div>
+        </CardContent>
+      </Card>
+    </div>
+  );
+}
+```
+<!-- /example -->

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

@@ -25,3 +25,73 @@ Chooses one value from a list: an opening you fill by choosing, with the list ri
 - Do use a RadioGroup instead when there are five options or fewer: people can see and compare them without opening anything.
 - Do give a non-string `label` a `textValue`, so typeahead can find it.
 - Don't use it for actions; that's a DropdownMenu.
+
+<!-- example: generated from build/previews.txt by build/previews.mjs. Edit the preview, not this section. -->
+## Example
+
+`Select` as first used in its preview:
+
+```tsx
+import { Select } from 'altitude-design';
+
+<Select items={regions} placeholder="Choose a region" name="region" />
+```
+
+The full preview, as rendered in Storybook and checked in CI (`col`, `grid`, `cap` are the preview page's own layout classes, not Altitude's):
+
+```tsx
+import * as React from 'react';
+import { Field, Select, SelectItem } from 'altitude-design';
+
+const regions = [
+  { value: "iad", label: "Virginia", description: "us-east-1" },
+  { value: "fra", label: "Frankfurt", description: "eu-central-2" },
+  { value: "sin", label: "Singapore", description: "ap-southeast-1" },
+  { value: "gru", label: "S\xE3o Paulo", description: "sa-east-1" },
+  { value: "syd", label: "Sydney", description: "Opens in March", disabled: true }
+];
+export default function App() {
+  const [plan, setPlan] = React.useState("team");
+  const [tz, setTz] = React.useState("");
+  return <div className="col">
+  <div className="grid">
+    <Field label="Region" hint="Where your deployments run.">
+      <Select items={regions} placeholder="Choose a region" name="region" />
+    </Field>
+    <Field label="Plan">
+      <Select value={plan} onValueChange={setPlan}>
+        <SelectItem value="solo">Solo</SelectItem>
+        <SelectItem value="team">Team</SelectItem>
+        <SelectItem value="org">Organization</SelectItem>
+      </Select>
+    </Field>
+    <Field label="Timezone" required={true} error={tz ? null : "Choose a timezone."}>
+      <Select
+        value={tz}
+        onValueChange={setTz}
+        placeholder="Choose a timezone"
+        items={[{ value: "utc", label: "UTC" }, { value: "lis", label: "Europe/Lisbon" }, { value: "nyc", label: "America/New_York" }]}
+      />
+    </Field>
+    <Field label="Runtime">
+      <Select
+        defaultValue="node"
+        defaultOpen={true}
+        items={[{ value: "node", label: "Node.js 22" }, { value: "bun", label: "Bun 1.2" }, { value: "deno", label: "Deno 2" }, { value: "edge", label: "Edge (V8 isolates)" }]}
+      />
+    </Field>
+    <Field label="Owner">
+      <Select
+        disabled={true}
+        defaultValue="mara"
+        items={[{ value: "mara", label: "Mara Quist" }]}
+      />
+    </Field>
+  </div>
+  <p className="cap" style={{ marginTop: 150 }}>
+    Empty fields are holes with their back wall showing; choosing raises the floor flush. Type a letter on a focused field to jump to it.
+  </p>
+</div>;
+}
+```
+<!-- /example -->

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

@@ -24,3 +24,47 @@ A divider: between sections in a card, groups in a toolbar, items in a sidebar,
 - Do make a separator between groups of toolbar buttons `decorative`.
 - Don't use it to fake a table's row lines; `Table` and `ItemGroup` draw their own (`ItemSeparator`).
 - Don't give it a colour, a thickness or a shadow.
+
+<!-- example: generated from build/previews.txt by build/previews.mjs. Edit the preview, not this section. -->
+## Example
+
+`Separator` as first used in its preview:
+
+```tsx
+import { Separator } from 'altitude-design';
+
+<Separator />
+```
+
+The full preview, as rendered in Storybook and checked in CI (`sp`, `cap`, `col`, `bar`, `signin` are the preview page's own layout classes, not Altitude's):
+
+```tsx
+import { Button, Card, CardContent, CardDescription, CardHeader, CardTitle, Input, Separator } from 'altitude-design';
+
+export default function App() {
+  return (
+    <div className="sp">
+      <Card>
+        <CardHeader><CardTitle>Workspace</CardTitle><CardDescription>Name, URL and region</CardDescription></CardHeader>
+        <Separator />
+        <CardContent><p className="cap">Sections in a card are parted by a horizontal separator: role="separator", 1px of line.</p></CardContent>
+      </Card>
+      <div className="col">
+        <div className="bar">
+          <Button size="sm" variant="ghost">Bold</Button>
+          <Button size="sm" variant="ghost">Italic</Button>
+          <Separator orientation="vertical" decorative />
+          <Button size="sm" variant="ghost">Link</Button>
+        </div>
+        <div className="signin">
+          <Button variant="secondary">Continue with SSO</Button>
+          <Separator label="or" />
+          <Input placeholder="Email address" aria-label="Email address" />
+        </div>
+        <p className="cap">A vertical one between groups of buttons is decorative. "or" is read as a word; its lines are drawn.</p>
+      </div>
+    </div>
+  );
+}
+```
+<!-- /example -->

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

@@ -30,3 +30,97 @@ A large panel laid over the page at level 4, anchored to an edge, for a task tha
 A modal Sheet shares document-scoped isolation, scroll ownership and eligible-focus containment with Dialog. Its locks remain through exit. Opening a Dialog from a Sheet suspends the Sheet, then resumes its focus and existing background policy after the Dialog closes. A Sheet requested beneath a summit cannot take its focus or `aria-modal` ownership. A stationary Dialog also removes the lower Sheet's scrim blur until it closes.
 
 `modal={false}` keeps the page interactive and scrollable: no scrim, recession or focus trap. Closing that Sheet does not restore focus over a newer modal.
+
+<!-- example: generated from build/previews.txt by build/previews.mjs. Edit the preview, not this section. -->
+## Example
+
+`Sheet` as first used in its preview:
+
+```tsx
+import { Button, Input, Sheet, SheetDescription, SheetFooter, SheetHeader, SheetTitle } from 'altitude-design';
+
+<Sheet side="bottom" size="sm" trigger={<Button>Share</Button>}>
+  <SheetHeader>
+    <SheetTitle>Share Northwind</SheetTitle>
+    <SheetDescription>
+      Anyone with the link can view the latest deployment.
+    </SheetDescription>
+  </SheetHeader>
+  <Input
+    defaultValue="https://acme.dev/n/8dc01b2"
+    readOnly={true}
+    aria-label="Share link"
+  />
+  <SheetFooter><Button variant="primary">Copy link</Button></SheetFooter>
+</Sheet>
+```
+
+The full preview, as rendered in Storybook and checked in CI (`page`, `row`, `grid`, `form` are the preview page's own layout classes, not Altitude's):
+
+```tsx
+import * as React from 'react';
+import { Button, Card, Checkbox, Field, Input, Sheet, SheetDescription, SheetFooter, SheetHeader, SheetTitle, Switch, Textarea } from 'altitude-design';
+
+export default function App() {
+  const [edit, setEdit] = React.useState(true);
+  return <div className="page">
+  <div className="row">
+    <Button variant="primary" onClick={() => setEdit(true)}>Edit project</Button>
+    <Sheet side="bottom" size="sm" trigger={<Button>Share</Button>}>
+      <SheetHeader>
+        <SheetTitle>Share Northwind</SheetTitle>
+        <SheetDescription>
+          Anyone with the link can view the latest deployment.
+        </SheetDescription>
+      </SheetHeader>
+      <Input
+        defaultValue="https://acme.dev/n/8dc01b2"
+        readOnly={true}
+        aria-label="Share link"
+      />
+      <SheetFooter><Button variant="primary">Copy link</Button></SheetFooter>
+    </Sheet>
+    <Sheet
+      side="left"
+      size="sm"
+      modal={false}
+      trigger={<Button variant="ghost">Filters</Button>}
+    >
+      <SheetHeader>
+        <SheetTitle>Filters</SheetTitle>
+        <SheetDescription>The page stays usable while this is open.</SheetDescription>
+      </SheetHeader>
+      <Checkbox label="Production" defaultChecked={true} />
+      <Checkbox label="Preview" />
+      <Checkbox label="Failed builds only" />
+    </Sheet>
+  </div>
+  <div className="grid" data-tells-ignore="LA4 placeholder page behind the overlay">
+    <Card />
+    <Card />
+    <Card />
+    <Card />
+    <Card />
+    <Card />
+  </div>
+  <Sheet open={edit} onOpenChange={setEdit}>
+    <SheetHeader>
+      <SheetTitle>Edit project</SheetTitle>
+      <SheetDescription>Changes apply to every environment.</SheetDescription>
+    </SheetHeader>
+    <div className="form">
+      <Field label="Project name"><Input defaultValue="Northwind" /></Field>
+      <Field label="Description" hint="Shown on the project's card.">
+        <Textarea placeholder="What is this project for?" />
+      </Field>
+      <Switch label="Deploy previews for every branch" defaultChecked={true} />
+    </div>
+    <SheetFooter>
+      <Button variant="ghost" onClick={() => setEdit(false)}>Cancel</Button>
+      <Button variant="primary" onClick={() => setEdit(false)}>Save changes</Button>
+    </SheetFooter>
+  </Sheet>
+</div>;
+}
+```
+<!-- /example -->

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

@@ -12,3 +12,39 @@ Imprints are wells (`surface-well`, inset shadow) because they're openings waiti
 - Don't show imprints for loads under about 300ms; show nothing.
 
 Under `AltitudeProvider loading="breath"` (experimental) a Skeleton breathes in depth instead of being swept by light, on the same page clock as every other imprint, and its content fills past the ground when `loaded` turns true. See `Await`.
+
+<!-- example: generated from build/previews.txt by build/previews.mjs. Edit the preview, not this section. -->
+## Example
+
+`Skeleton` as first used in its preview:
+
+```tsx
+import { Avatar, Skeleton } from 'altitude-design';
+
+<Skeleton loaded={loaded} shape="circle" width={44}><Avatar name="Mara Quist" size={44} status="active" /></Skeleton>
+```
+
+The full preview, as rendered in Storybook and checked in CI (`col`, `card`, `lines`, `txt`, `cap` are the preview page's own layout classes, not Altitude's):
+
+```tsx
+import * as React from 'react';
+import { Avatar, Skeleton, Surface } from 'altitude-design';
+
+export default function App() {
+  const [loaded, setLoaded] = React.useState(false);
+  React.useEffect(() => { const t = setInterval(() => setLoaded((l) => !l), 2600); return () => clearInterval(t); }, []);
+  return (
+    <div className="col">
+      <Surface level={1} className="card">
+        <Skeleton loaded={loaded} shape="circle" width={44}><Avatar name="Mara Quist" size={44} status="active" /></Skeleton>
+        <div className="lines">
+          <Skeleton loaded={loaded} width="45%" height={14}><b style={{ font: '600 14px/20px var(--font-sans)' }}>Mara Quist</b></Skeleton>
+          <Skeleton loaded={loaded} shape="text" lines={2}><p className="txt">Merged “Faster cold starts” into main. Cold starts are down 38% across all regions.</p></Skeleton>
+        </div>
+      </Surface>
+      <p className="cap">While it loads, the layout is pressed into the page; when content lands it rises out of its imprint, four at a time at most.</p>
+    </div>
+  );
+}
+```
+<!-- /example -->