altitude-design 0.4.0 → 0.4.2

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

@@ -28,3 +28,80 @@ What changed between two versions: version history, audit-log detail ("Plan: Pro
 - Do keep a little context around changes, so they can be read.
 - Don't show a diff in red and green alone.
 - Don't restore from inside the diff without a confirmation.
+
+<!-- example: generated from build/previews.txt by build/previews.mjs. Edit the preview, not this section. -->
+## Example
+
+`DiffView` as first used in its preview:
+
+```tsx
+import { DiffView, diffChanges, diffLines } from 'altitude-design';
+
+<DiffView caption="src/pricing.ts · proposed by the assistant" before={pricingBefore} after={pricingAfter} review decisions={decisions}
+onDecide={(id, d) => setDecisions({ ...decisions, [id]: d })}
+onDecideAll={(d) => setDecisions(Object.fromEntries(diffChanges(diffLines(pricingBefore, pricingAfter)).map((c) => [c.id, decisions[c.id] ?? d])))} />
+```
+
+The full preview, as rendered in Storybook and checked in CI (`dv` is the preview page's own layout class, not Altitude's):
+
+```tsx
+import * as React from 'react';
+import { DiffView, diffChanges, diffLines } from 'altitude-design';
+
+const v4 = `# Deploy settings
+region: eu-central-1
+replicas: 2
+memory: 512Mi
+timeout: 30s
+retries: 3
+logging: info
+metrics: enabled
+tracing: disabled
+cache: 5m
+health: /healthz
+owner: platform-team`;
+const v5 = `# Deploy settings
+region: eu-central-1
+replicas: 4
+memory: 1Gi
+timeout: 30s
+retries: 3
+logging: info
+metrics: enabled
+tracing: disabled
+cache: 5m
+health: /healthz
+owner: platform-team
+alerts: on-call`;
+const pricingBefore = `export const plans = {
+  starter: { monthly: 9, seats: 1 },
+  pro: { monthly: 29, seats: 5 },
+  business: { monthly: 99, seats: 25 },
+};
+export const trialDays = 14;
+export const currency = 'USD';`;
+const pricingAfter = `export const plans = {
+  starter: { monthly: 9, seats: 1 },
+  pro: { monthly: 32, seats: 5 },
+  business: { monthly: 99, seats: 25, sso: true },
+};
+export const trialDays = 30;
+export const currency = 'USD';`;
+function Review() {
+  const [decisions, setDecisions] = React.useState({ 'change-2': 'accept' });
+  return <DiffView caption="src/pricing.ts · proposed by the assistant" before={pricingBefore} after={pricingAfter} review decisions={decisions}
+    onDecide={(id, d) => setDecisions({ ...decisions, [id]: d })}
+    onDecideAll={(d) => setDecisions(Object.fromEntries(diffChanges(diffLines(pricingBefore, pricingAfter)).map((c) => [c.id, decisions[c.id] ?? d])))} />;
+}
+export default function App() {
+  return (
+    <div className="dv">
+      <DiffView caption="deploy.yaml · version 4 → 5" before={v4} after={v5} context={1} />
+      <DiffView mode="properties" caption="Subscription changed by Maya" before={{ plan: 'Pro', seats: 12, billing: 'Monthly' }} after={{ plan: 'Business', seats: 25, billing: 'Monthly' }}
+        fields={[{ key: 'plan', label: 'Plan' }, { key: 'seats', label: 'Seats' }, { key: 'billing', label: 'Billing' }]} />
+      <Review />
+    </div>
+  );
+}
+```
+<!-- /example -->

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

@@ -36,3 +36,47 @@ Values compared across categories where zero isn't part of the story: ten servic
 - Do sort the rows unless their order means something.
 - Don't use it for change over time; that's a `LineChart`, which implies continuity.
 - Don't set `zero` just to have it: if zero matters, a `BarChart` is usually the better form.
+
+<!-- example: generated from build/previews.txt by build/previews.mjs. Edit the preview, not this section. -->
+## Example
+
+`DotPlot` as first used in its preview:
+
+```tsx
+import { DotPlot } from 'altitude-design';
+
+<DotPlot data={services} x="service" range={['p10', 'p90']} rangeLabel="10th–90th percentile" sort="desc" />
+```
+
+The full preview, as rendered in Storybook and checked in CI (`dp` is the preview page's own layout class, not Altitude's):
+
+```tsx
+import { Card, CardContent, CardDescription, CardHeader, CardTitle, ChartContainer, DotPlot } from 'altitude-design';
+
+const services = [['Checkout', 212, 180, 240], ['Search', 188, 170, 205], ['Billing', 236, 190, 320], ['Accounts', 199, 182, 214], ['Media', 228, 196, 268], ['Auth', 184, 176, 193], ['Exports', 221, 187, 262], ['Email', 193, 179, 209]]
+  .map(([service, p95, p10, p90]) => ({ service, p95, p10, p90 }));
+const teams = [['Atlas', 71, 78], ['Birch', 64, 62], ['Cedar', 80, 86], ['Delta', 58, 69], ['Ember', 75, 77]].map(([team, q2, q3]) => ({ team, q2, q3 }));
+export default function App() {
+  return (
+    <div className="dp">
+      <Card>
+        <CardHeader><CardTitle id="d1">p95 latency by service</CardTitle><CardDescription>All between 180 and 240 ms; the band is the 10th–90th percentile</CardDescription></CardHeader>
+        <CardContent>
+          <ChartContainer aria-labelledby="d1" aspect={1.5} config={{ p95: { label: 'p95', format: (v) => `${v} ms` } }}>
+            <DotPlot data={services} x="service" range={['p10', 'p90']} rangeLabel="10th–90th percentile" sort="desc" />
+          </ChartContainer>
+        </CardContent>
+      </Card>
+      <Card>
+        <CardHeader><CardTitle id="d2">Accessibility score, Q2 to Q3</CardTitle><CardDescription>A dumbbell: the hollow dot is Q2, the filled one Q3</CardDescription></CardHeader>
+        <CardContent>
+          <ChartContainer aria-labelledby="d2" aspect={1.5} config={{ q2: { label: 'Q2' }, q3: { label: 'Q3' } }}>
+            <DotPlot data={teams} x="team" from="q2" to="q3" sort="desc" />
+          </ChartContainer>
+        </CardContent>
+      </Card>
+    </div>
+  );
+}
+```
+<!-- /example -->

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

@@ -13,3 +13,31 @@ Navigates a hierarchy as a **stack**. Each place you go into is laid on top of t
 - Don't use it for steps in a process; a stack implies you can always lift back out.
 
 **Charts that drill.** A node with both `content` and `children` shows its content, and the content opens the children itself: a chart's `drill={(d) => childId}`, or `useDrilldown().open(id)` from your own component. After a step, focus moves to the new view's own first stop when it names one (`data-drill-focus`, as a chart's summary does), otherwise to the view.
+
+<!-- example: generated from build/previews.txt by build/previews.mjs. Edit the preview, not this section. -->
+## Example
+
+`Drilldown` as first used in its preview:
+
+```tsx
+import { Drilldown } from 'altitude-design';
+
+<Drilldown root={tree} />
+```
+
+The full preview, as rendered in Storybook and checked in CI (`wrap` is the preview page's own layout class, not Altitude's):
+
+```tsx
+import { Drilldown } from 'altitude-design';
+
+const tree = { id: 'ws', title: 'Workspace', children: [
+  { id: 'nw', title: 'Northwind', description: 'Marketing site', children: [
+    { id: 'prod', title: 'Production', description: 'acme.dev', children: [
+      { id: 'b42', title: 'Build #42', description: 'main@8dc01b2 · 2h ago', content: 'Deployed by Mara. 14 routes, 2.1 MB, healthy.' },
+      { id: 'b41', title: 'Build #41', description: 'main@51ac9e0 · yesterday', content: 'Rolled back after a cold-start regression.' } ] },
+    { id: 'prev', title: 'Preview', description: '3 branches', content: 'Preview deployments for open pull requests.' } ] },
+  { id: 'bc', title: 'Beacon', description: 'Internal dashboard', content: 'No deployments yet.' },
+  { id: 'st', title: 'Settings', description: 'Members, billing, domains', content: 'Workspace settings.' } ] };
+export default function App() { return <div className="wrap"><Drilldown root={tree} /></div>; }
+```
+<!-- /example -->

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

@@ -19,3 +19,53 @@ Pass `queue` and each file you're handling is a slat under the zone, named by it
 
 `UploadItem` is `{ id, name, size?, state, progress?, error? }`. `onRetry`, `onCancel` and `onRemove` get the id, and their buttons name the file ("Retry upload of report.pdf"). Progress is announced at 25, 50, 75 and 100%, and on processing, finishing and failing, never continuously. Afterglows start at most four at once.
 
+<!-- example: generated from build/previews.txt by build/previews.mjs. Edit the preview, not this section. -->
+## Example
+
+`DropZone` as first used in its preview:
+
+```tsx
+import { DropZone } from 'altitude-design';
+
+<DropZone state="idle"><Body /></DropZone>
+```
+
+The full preview, as rendered in Storybook and checked in CI (`three`, `lab` are the preview page's own layout classes, not Altitude's):
+
+```tsx
+import * as React from 'react';
+import { DropZone } from 'altitude-design';
+
+const Body = () => <><svg width="22" height="22" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="1.75" strokeLinecap="round" strokeLinejoin="round"><path d="M12 16V4M7 9l5-5 5 5M5 20h14" /></svg><span>Drop files or <u>browse</u></span></>;
+export default function App() {
+  return (
+    <div className="three">
+      <div><div className="lab">idle · flush</div><DropZone state="idle"><Body /></DropZone></div>
+      <div><div className="lab">armed · a file is in flight</div><DropZone state="armed"><Body /></DropZone></div>
+      <div><div className="lab">over · ready to receive</div><DropZone state="over"><Body /></DropZone></div>
+      <div style={{ gridColumn: '1 / -1' }}><Queue /></div>
+    </div>
+  );
+}
+// A stand-in uploader: files upload in steps, then the server processes them; one fails until retried.
+const start = [
+  { id: 'a', name: 'Q3 board deck.pdf', size: 2400000, state: 'uploading', progress: 0 },
+  { id: 'b', name: 'Customer list.csv', size: 480000, state: 'uploading', progress: 0 },
+  { id: 'c', name: 'Brand guidelines.pdf', size: 18200000, state: 'uploading', progress: 0, fails: true },
+];
+function Queue() {
+  const [items, setItems] = React.useState(start);
+  React.useEffect(() => {
+    const t = setInterval(() => setItems((xs) => xs.map((x) => {
+      if (x.state === 'uploading') { const p = Math.min(100, x.progress + (x.id === 'b' ? 34 : 13)); if (x.fails && p > 40) return { ...x, state: 'failed', error: 'The connection dropped' }; return p >= 100 ? { ...x, state: 'processing', progress: 100 } : { ...x, progress: p }; }
+      if (x.state === 'processing') return Math.random() < 0.35 ? { ...x, state: 'done' } : x;
+      return x;
+    })), 450);
+    return () => clearInterval(t);
+  }, []);
+  return <DropZone multiple queue={items} onFiles={(fs) => setItems((xs) => [...xs, ...fs.map((f, i) => ({ id: f.name + Date.now() + i, name: f.name, size: f.size, state: 'uploading', progress: 0 }))])}
+    onRetry={(id) => setItems((xs) => xs.map((x) => (x.id === id ? { ...x, state: 'uploading', progress: 40, fails: false, error: undefined } : x)))}
+    onCancel={(id) => setItems((xs) => xs.filter((x) => x.id !== id))} onRemove={(id) => setItems((xs) => xs.filter((x) => x.id !== id))}><Body /></DropZone>;
+}
+```
+<!-- /example -->

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

@@ -17,3 +17,47 @@ The menu rises like a Popover. Items stagger in at 16ms each. A single `accent-s
 - Do use `ContextMenu` for the same menu opened where something is right-clicked; the two share one implementation.
 - Do use `checked` for an item that turns something on or off: it becomes a `menuitemcheckbox` with a check, and every item keeps a slot for the check so labels line up.
 - Do put destructive actions last, after a separator, in `critical`.
+
+<!-- example: generated from build/previews.txt by build/previews.mjs. Edit the preview, not this section. -->
+## Example
+
+`DropdownMenu` as first used in its preview:
+
+```tsx
+import { Button, DropdownMenu, Icons } from 'altitude-design';
+
+<DropdownMenu defaultOpen items={items} trigger={<Button trailing={<Icons.ChevronDown />}>Actions</Button>} />
+```
+
+The full preview, as rendered in Storybook and checked in CI (`pair` is the preview page's own layout class, not Altitude's):
+
+```tsx
+import { Button, DropdownMenu, Icons } from 'altitude-design';
+
+const items = [
+  { type: 'label', label: 'Project' },
+  { label: 'Rename', shortcut: 'R' },
+  { label: 'Duplicate', shortcut: '⌘D' },
+  { label: 'Move to…' },
+  { label: 'Archive', disabled: true },
+  { type: 'separator' },
+  { label: 'Delete project', tone: 'critical', shortcut: '⌫' },
+];
+const predicted = [
+  { label: 'Copy link', shortcut: '⌘L', predicted: true },
+  { label: 'Share…', predicted: true },
+  { label: 'Rename', shortcut: 'R' },
+  { label: 'Duplicate', shortcut: '⌘D' },
+  { label: 'Export as PDF' },
+  { label: 'Version history' },
+];
+export default function App() {
+  return (
+    <div className="pair">
+      <DropdownMenu defaultOpen items={items} trigger={<Button trailing={<Icons.ChevronDown />}>Actions</Button>} />
+      <DropdownMenu items={predicted} trigger={<Button trailing={<Icons.ChevronDown />}>Predicted</Button>} />
+    </div>
+  );
+}
+```
+<!-- /example -->

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

@@ -102,3 +102,162 @@ The record, the write (with a server-side revision or equivalent concurrency gua
 ## Demo and verification
 
 The `EditRegion` section of `build/previews.txt` lists three people with access; each row is an in-place EditRegion over a fictional people service with revisions. Below it, trip details are label–value rows with reserved values. A collapsed harness picks a save fixture (`success`, `slow`, `fail-once`, `conflict-during-save`) and applies an outside update. `node checks/edit-region.mjs` (from `build/`, after rendering previews; `ALT_FIXTURE_ROOT` selects React 19 fixtures) covers editing in place (fields hold their place on every frame while the editor grows, the record below is pushed through the glide, lifting never moves the record, each field opens at its value's x, reserved values open exactly where they were, the padded afterglow, the announcement that clears itself), opening and focus, unchanged saves, one write per save, `changed`, validation and error focus, Escape with an open Select, IME Enter, failure and retry, pending lock, both conflict paths, focus return, and a 320/960px layout in both schemes under reduced motion, forced colours and `contrast="more"`.
+
+<!-- example: generated from build/previews.txt by build/previews.mjs. Edit the preview, not this section. -->
+## Example
+
+`EditRegion` as first used in its preview:
+
+```tsx
+import { EditRegion, EditRegionForm, EditRegionValue, EditRegionView, Field, Input, Select, Switch } from 'altitude-design';
+
+<EditRegion layout="in-place" label={person.name} editLabel={`Edit ${person.name}`} value={erFields(person)} validate={validate}
+  onValueChange={canonical => setPeople(people => people.map(p => p.id === person.id ? { ...server.current.get(person.id), ...canonical } : p))}
+  onSave={save(person)}>
+  <EditRegionView>
+    <span className="er-name"><EditRegionValue field="name">{person.name}</EditRegionValue></span>
+    <span className="er-meta"><EditRegionValue field="email">{person.email}</EditRegionValue> · <EditRegionValue field="role">{ER_ROLES.find(r => r.value === person.role).label}</EditRegionValue>{person.notify ? <> · <EditRegionValue field="notify">Gets updates</EditRegionValue></> : ''}</span>
+  </EditRegionView>
+  <EditRegionForm>
+    {field => <>
+      <div className="er-name-edit"><Field label="Name" required error={field.error('name')}><Input {...field('name')} autoComplete="off" /></Field></div>
+      <div className="er-meta-edit">
+        <Field label="Email" required error={field.error('email')}><Input {...field('email')} type="email" autoComplete="off" /></Field>
+        <Field label="Role"><Select {...field.value('role')} items={ER_ROLES} /></Field>
+        <Switch {...field.checked('notify')} label="Gets updates" />
+      </div>
+    </>}
+  </EditRegionForm>
+</EditRegion>
+```
+
+The full preview, as rendered in Storybook and checked in CI (`er-list`, `er-name`, `er-meta`, `er-name-edit`, `er-meta-edit`, `er-harness`, `er-harness-controls`, `er-log`, `er-sheet`, `er-sheet-head`, `er-sheet-grid`, `er-demo` are the preview page's own layout classes, not Altitude's):
+
+```tsx
+import * as React from 'react';
+import { Button, EditRegion, EditRegionForm, EditRegionTrigger, EditRegionValue, EditRegionView, Field, Input, Select, Switch } from 'altitude-design';
+
+const ER_ROLES = [{ value: 'owner', label: 'Owner' }, { value: 'editor', label: 'Editor' }, { value: 'viewer', label: 'Viewer' }];
+const ER_PEOPLE = Object.freeze([
+  Object.freeze({ id: 'p-mara', name: 'Mara Quist', email: 'mara@northwind.example', role: 'owner', notify: true, revision: 1 }),
+  Object.freeze({ id: 'p-ines', name: 'Inés Ortega', email: 'ines@northwind.example', role: 'editor', notify: false, revision: 1 }),
+  Object.freeze({ id: 'p-tobi', name: 'Tobi Adeyemi', email: 'tobi@northwind.example', role: 'viewer', notify: true, revision: 1 }),
+]);
+const ER_FIXTURES = ['success', 'slow', 'fail-once', 'conflict-during-save'];
+const erWait = ms => new Promise(resolve => setTimeout(resolve, ms));
+const erFields = ({ revision, id, ...fields }) => fields;
+
+// A fictional people service with revisions: a stale write is rejected, an accepted one returns the canonical record.
+function EditRegionExample({ fixture }) {
+  const server = React.useRef(new Map(ER_PEOPLE.map(p => [p.id, { ...p }])));
+  const [people, setPeople] = React.useState(() => ER_PEOPLE.map(p => ({ ...p })));
+  const [log, setLog] = React.useState([]);
+  const failed = React.useRef(false);
+  const trace = event => setLog(log => [...log, event]);
+  const reconcile = id => setPeople(people => people.map(p => p.id === id ? { ...server.current.get(id) } : p));
+  const externalUpdate = () => {
+    const current = server.current.get('p-mara');
+    server.current.set('p-mara', { ...current, email: 'm.quist@northwind.example', revision: current.revision + 1 });
+    trace({ event: 'external-update', id: 'p-mara', revision: current.revision + 1 }); reconcile('p-mara');
+  };
+  const save = person => async (draft, { changed }) => {
+    trace({ event: 'requested', id: person.id, expectedRevision: person.revision, changed });
+    await erWait(fixture === 'slow' ? 1400 : 250);
+    if (fixture === 'fail-once' && !failed.current) { failed.current = true; trace({ event: 'rejected', id: person.id }); return { ok: false, error: 'We couldn’t reach the people service. Your changes are still here. Try again.' }; }
+    if (fixture === 'conflict-during-save') { externalUpdate(); await erWait(300); }
+    const current = server.current.get(person.id);
+    if (current.revision !== person.revision) { trace({ event: 'rejected-stale', id: person.id }); return { ok: false, error: 'Someone else changed this person. Review the current details.' }; }
+    if ([...server.current.values()].some(p => p.id !== person.id && p.email === draft.email.trim())) return { ok: false, error: 'Check the highlighted field.', fieldErrors: { email: 'Someone else already uses this email.' } };
+    const next = { ...current, ...draft, name: draft.name.trim(), email: draft.email.trim(), revision: current.revision + 1 };
+    server.current.set(person.id, next);
+    trace({ event: 'committed', id: person.id, revision: next.revision, changed });
+    return { ok: true, value: erFields(next) };
+  };
+  const validate = draft => {
+    const errors = {};
+    if (!draft.name.trim()) errors.name = 'Enter a name.';
+    if (!/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(draft.email.trim())) errors.email = 'Enter an email address, like name@example.com.';
+    return Object.keys(errors).length ? errors : undefined;
+  };
+  return <>
+    <section aria-labelledby="er-title">
+      <h2 id="er-title">People with access</h2>
+      <ul className="er-list">
+        {people.map(person => <li key={person.id}>
+          <EditRegion layout="in-place" label={person.name} editLabel={`Edit ${person.name}`} value={erFields(person)} validate={validate}
+            onValueChange={canonical => setPeople(people => people.map(p => p.id === person.id ? { ...server.current.get(person.id), ...canonical } : p))}
+            onSave={save(person)}>
+            <EditRegionView>
+              <span className="er-name"><EditRegionValue field="name">{person.name}</EditRegionValue></span>
+              <span className="er-meta"><EditRegionValue field="email">{person.email}</EditRegionValue> · <EditRegionValue field="role">{ER_ROLES.find(r => r.value === person.role).label}</EditRegionValue>{person.notify ? <> · <EditRegionValue field="notify">Gets updates</EditRegionValue></> : ''}</span>
+            </EditRegionView>
+            <EditRegionForm>
+              {field => <>
+                <div className="er-name-edit"><Field label="Name" required error={field.error('name')}><Input {...field('name')} autoComplete="off" /></Field></div>
+                <div className="er-meta-edit">
+                  <Field label="Email" required error={field.error('email')}><Input {...field('email')} type="email" autoComplete="off" /></Field>
+                  <Field label="Role"><Select {...field.value('role')} items={ER_ROLES} /></Field>
+                  <Switch {...field.checked('notify')} label="Gets updates" />
+                </div>
+              </>}
+            </EditRegionForm>
+          </EditRegion>
+        </li>)}
+      </ul>
+    </section>
+    <TripSheet />
+    <details className="er-harness">
+      <summary>Fixture controls</summary>
+      <p>Documentation harness only: change Mara's record on the “server” while it's being edited.</p>
+      <div className="er-harness-controls"><Button onClick={externalUpdate}>Apply external update to Mara</Button></div>
+      <output className="er-log" data-er-log="" aria-label="Fixture operation log">{JSON.stringify(log, null, 2)}</output>
+    </details>
+  </>;
+}
+
+// Labelled rows whose values already have their controls' height (EditRegionValue reserve): Edit all moves nothing.
+const ER_SEATS = [{ value: 'aisle', label: 'Aisle' }, { value: 'window', label: 'Window' }, { value: 'any', label: 'No preference' }];
+function TripSheet() {
+  const [trip, setTrip] = React.useState({ traveller: 'Mara Quist', email: 'mara@northwind.example', phone: '', seat: 'aisle' });
+  const validate = draft => /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(draft.email.trim()) ? undefined : { email: 'Enter an email address, like name@example.com.' };
+  const rows = [['traveller', 'Traveller'], ['email', 'Email'], ['phone', 'Phone'], ['seat', 'Seat']];
+  return <section className="er-sheet" aria-labelledby="er-sheet-title">
+    <EditRegion layout="in-place" label="Trip details" editLabel="Edit all trip details" value={trip} validate={validate} onValueChange={setTrip}
+      onSave={async draft => { await erWait(250); return { ok: true, value: { ...draft, traveller: draft.traveller.trim(), email: draft.email.trim(), phone: draft.phone.trim() } }; }}>
+      <EditRegionView trigger={false}>
+        <div className="er-sheet-head"><h2 id="er-sheet-title">Trip details</h2><EditRegionTrigger>Edit all</EditRegionTrigger></div>
+        <dl className="er-sheet-grid">{rows.map(([key, label]) => <React.Fragment key={key}><dt>{label}</dt><dd>
+          <EditRegionValue field={key} reserve>{key === 'seat' ? ER_SEATS.find(s => s.value === trip.seat).label : trip[key] || <span className="er-meta">Not set</span>}</EditRegionValue>
+        </dd></React.Fragment>)}</dl>
+      </EditRegionView>
+      <EditRegionForm>
+        {field => <>
+          <div className="er-sheet-head"><h2>Trip details</h2></div>
+          <dl className="er-sheet-grid">
+            <dt>Traveller</dt><dd><Field label="Traveller" required error={field.error('traveller')}><Input {...field('traveller')} autoComplete="off" /></Field></dd>
+            <dt>Email</dt><dd><Field label="Email" required error={field.error('email')}><Input {...field('email')} type="email" autoComplete="off" /></Field></dd>
+            <dt>Phone</dt><dd><Field label="Phone"><Input {...field('phone')} type="tel" placeholder="Add a phone number" autoComplete="off" /></Field></dd>
+            <dt>Seat</dt><dd><Field label="Seat"><Select {...field.value('seat')} items={ER_SEATS} /></Field></dd>
+          </dl>
+        </>}
+      </EditRegionForm>
+    </EditRegion>
+  </section>;
+}
+
+export default function App() {
+  const [fixture, setFixture] = React.useState('success');
+  const [mounted, setMounted] = React.useState({ fixture: 'success', epoch: 0 });
+  return <div className="er-demo">
+    <EditRegionExample key={mounted.epoch} fixture={mounted.fixture} />
+    <details className="er-harness">
+      <summary>Choose the next fixture</summary>
+      <div className="er-harness-controls">
+        <label>Save fixture<select value={fixture} onChange={event => setFixture(event.target.value)}>{ER_FIXTURES.map(name => <option key={name}>{name}</option>)}</select></label>
+        <Button onClick={() => setMounted({ fixture, epoch: mounted.epoch + 1 })}>Reset example</Button>
+      </div>
+    </details>
+  </div>;
+}
+```
+<!-- /example -->

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

@@ -15,3 +15,52 @@ What a list, board, search or page shows when it has nothing to show: a statemen
 - Do give it one primary action at most; a second one is `secondary`, quieter.
 - Don't use it for an error that stopped content loading: that's a problem to fix, an `Alert`.
 - Don't raise it into a card, or make it the only thing on a page that's still loading: show a `Skeleton` until you know it's empty.
+
+<!-- example: generated from build/previews.txt by build/previews.mjs. Edit the preview, not this section. -->
+## Example
+
+`EmptyState` as first used in its preview:
+
+```tsx
+import { Button, EmptyState } from 'altitude-design';
+
+<EmptyState icon={<Gift />} title="No gift ideas yet" headingLevel={2}
+  description="Ideas you save stay private to you until you share them."
+  action={<Button variant="primary">Add idea</Button>}
+  secondary={<Button variant="ghost">Import a list</Button>} />
+```
+
+The full preview, as rendered in Storybook and checked in CI (`two`, `lab`, `side`, `cap` are the preview page's own layout classes, not Altitude's):
+
+```tsx
+import * as React from 'react';
+import { Button, EmptyState } from 'altitude-design';
+
+const Gift = () => <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="1.75" strokeLinecap="round" strokeLinejoin="round"><rect x="3" y="8" width="18" height="4" rx="1" /><path d="M12 8v13M19 12v7a2 2 0 0 1-2 2H7a2 2 0 0 1-2-2v-7M7.5 8a2.5 2.5 0 0 1 0-5C10 3 12 8 12 8s2-5 4.5-5a2.5 2.5 0 0 1 0 5" /></svg>;
+const Search = () => <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="1.75" strokeLinecap="round"><circle cx="11" cy="11" r="7" /><path d="M20 20l-3.5-3.5" /></svg>;
+const Bell = () => <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="1.75" strokeLinecap="round" strokeLinejoin="round"><path d="M6 8a6 6 0 0 1 12 0c0 7 3 9 3 9H3s3-2 3-9M10.3 21a1.94 1.94 0 0 0 3.4 0" /></svg>;
+export default function App() {
+  const [q, setQ] = React.useState('lamp');
+  return (
+    <div className="two">
+      <div><div className="lab">md · a page with nothing yet</div>
+        <EmptyState icon={<Gift />} title="No gift ideas yet" headingLevel={2}
+          description="Ideas you save stay private to you until you share them."
+          action={<Button variant="primary">Add idea</Button>}
+          secondary={<Button variant="ghost">Import a list</Button>} />
+      </div>
+      <div className="side">
+        <div><div className="lab">sm · a widget</div>
+          <EmptyState size="sm" icon={<Bell />} title="You're all caught up" description="New mentions and replies appear here." />
+        </div>
+        <div><div className="lab">sm · after a search</div>
+          {q ? <EmptyState size="sm" icon={<Search />} title={`No ideas match \u201C${q}\u201D`} announce="No matching ideas"
+            description="Try another word, or clear the search." action={<Button size="sm" onClick={() => setQ('')}>Clear search</Button>} />
+            : <p className="cap">Search cleared.</p>}
+        </div>
+      </div>
+    </div>
+  );
+}
+```
+<!-- /example -->

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

@@ -26,3 +26,42 @@ Pressing it opens a `Popover` (level 3): "Available on Business", what the plan
 - Do say what the plan adds, not just its name.
 - Don't use `disabled` for a feature that needs another plan.
 - Don't hide the upgrade from people who can't buy it; tell them who can.
+
+<!-- example: generated from build/previews.txt by build/previews.mjs. Edit the preview, not this section. -->
+## Example
+
+`FeatureGate` as first used in its preview:
+
+```tsx
+import { Button, FeatureGate } from 'altitude-design';
+
+<FeatureGate requires="Business" description="Export any view to CSV, and schedule exports by email." onUpgrade={() => setSaid('Opening plans…')} compareHref="#/billing/plans">
+  <Button variant="secondary">Export to CSV</Button>
+</FeatureGate>
+```
+
+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, FeatureGate } from 'altitude-design';
+
+export default function App() {
+  const [said, setSaid] = React.useState('');
+  return (
+    <div className="col">
+      <div className="row">
+        <Button variant="secondary">Export view</Button>
+        <FeatureGate requires="Business" description="Export any view to CSV, and schedule exports by email." onUpgrade={() => setSaid('Opening plans…')} compareHref="#/billing/plans">
+          <Button variant="secondary">Export to CSV</Button>
+        </FeatureGate>
+        <FeatureGate requires="Enterprise" description="Sign in with your identity provider (Okta, Azure AD, Google)." canUpgrade={false}>
+          <Button variant="ghost">SAML SSO</Button>
+        </FeatureGate>
+      </div>
+      <p className="cap" role="status">{said || 'Locked features keep their ink, lift when pointed at and are reachable by keyboard; pressing one explains the plan. Without permission to upgrade, it says to ask an admin.'}</p>
+    </div>
+  );
+}
+```
+<!-- /example -->

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

@@ -8,3 +8,39 @@ Pairs one control with its label, an optional hint and an error message that eme
 
 - Do write the error as the fix: "Use at least 5 characters", not "Invalid input".
 - Don't show an error before the person has finished with the field; validate on blur or submit.
+
+<!-- example: generated from build/previews.txt by build/previews.mjs. Edit the preview, not this section. -->
+## Example
+
+`Field` as first used in its preview:
+
+```tsx
+import { Field, Input } from 'altitude-design';
+
+<Field label="Workspace name" hint="Shown to everyone you invite.">
+  <Input defaultValue="Northwind Studio" />
+</Field>
+```
+
+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 { Field, Input } from 'altitude-design';
+
+export default function App() {
+  const [v, setV] = React.useState('acme');
+  const err = v.length < 5 ? 'Use at least 5 characters.' : null;
+  return (
+    <div className="grid">
+      <Field label="Workspace name" hint="Shown to everyone you invite.">
+        <Input defaultValue="Northwind Studio" />
+      </Field>
+      <Field label="URL slug" required error={err}>
+        <Input value={v} onChange={(e) => setV(e.target.value)} />
+      </Field>
+    </div>
+  );
+}
+```
+<!-- /example -->

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

@@ -67,3 +67,66 @@ Automation rules, segments and advanced search need nested logic: "Plan is Pro *
 
 A group is drawn as **a flush bracket on the ground**: a 1px `line-control` rule around its own conditions, with its own all/any switch (shown even with one condition) and its own Add filter. Groups are part of the record of the query, not live surfaces. Depth is capped at one level of groups so it never becomes a code editor, and groups follow the top level's conditions. "+ Add group" starts an "any of" group, and removing a group's last condition removes the group. `filterSentence(fields, tree)` reads the whole expression in words, and it's announced as it changes. `value: Filter[]` keeps working as before.
 
+<!-- example: generated from build/previews.txt by build/previews.mjs. Edit the preview, not this section. -->
+## Example
+
+`FilterBar` as first used in its preview:
+
+```tsx
+import { FilterBar } from 'altitude-design';
+
+<FilterBar aria-label="Filter issues" fields={FB_FIELDS} value={filters} onValueChange={setFilters} match={match} onMatchChange={setMatch} resultCount={count} />
+```
+
+The full preview, as rendered in Storybook and checked in CI (`fb-demo` is the preview page's own layout class, not Altitude's):
+
+```tsx
+import * as React from 'react';
+import { DataTable, FilterBar } from 'altitude-design';
+
+const FB_STATUSES = [{ value: 'todo', label: 'To do' }, { value: 'progress', label: 'In progress' }, { value: 'review', label: 'In review' }, { value: 'done', label: 'Done' }];
+const FB_PEOPLE = [{ value: 'mara', label: 'Mara Quist' }, { value: 'ines', label: 'Inés Ortega' }, { value: 'tobi', label: 'Tobi Adeyemi' }, { value: 'wen', label: 'Li Wen' }];
+const FB_FIELDS = [
+  { key: 'status', label: 'Status', type: 'enum', options: FB_STATUSES },
+  { key: 'assignee', label: 'Assignee', type: 'enum', options: FB_PEOPLE, searchable: true },
+  { key: 'updated', label: 'Updated', type: 'date' },
+  { key: 'title', label: 'Title', type: 'text' },
+  { key: 'points', label: 'Points', type: 'number' },
+];
+const FB_ROWS = [
+  { id: 'a', title: 'Search results page', status: 'review', assignee: 'mara', updated: '2026-10-21', points: 5 },
+  { id: 'b', title: 'Billing address form', status: 'progress', assignee: 'ines', updated: '2026-10-12', points: 3 },
+  { id: 'c', title: 'Search filters', status: 'todo', assignee: 'tobi', updated: '2026-09-30', points: 8 },
+  { id: 'd', title: 'Invoice emails', status: 'done', assignee: 'wen', updated: '2026-10-02', points: 2 },
+  { id: 'e', title: 'Onboarding checklist', status: 'review', assignee: 'ines', updated: '2026-10-19', points: 3 },
+];
+const fbTest = (row, f) => {
+  if (f.value === undefined || f.value === '') return true;
+  const v = row[f.field];
+  switch (f.operator) {
+    case 'is': return v === f.value; case 'is not': return v !== f.value;
+    case 'contains': return v.toLowerCase().includes(String(f.value).toLowerCase()); case 'does not contain': return !v.toLowerCase().includes(String(f.value).toLowerCase());
+    case '=': return v === f.value; case '>': return v > f.value; case '<': return v < f.value;
+    case 'before': return v < f.value; case 'after': return v > f.value; case 'between': return v >= f.value.start && v <= f.value.end;
+  }
+  return true;
+};
+export default function App() {
+  const [filters, setFilters] = React.useState([{ id: 'f1', field: 'status', operator: 'is', value: 'review' }]);
+  const [match, setMatch] = React.useState('all');
+  const matches = row => match === 'all' ? filters.every(f => fbTest(row, f)) : filters.some(f => fbTest(row, f));
+  const count = FB_ROWS.filter(matches).length;
+  return <div className="fb-demo">
+    <FilterBar aria-label="Filter issues" fields={FB_FIELDS} value={filters} onValueChange={setFilters} match={match} onMatchChange={setMatch} resultCount={count} />
+    <DataTable aria-label="Issues" rows={FB_ROWS} getRowId={r => r.id} relevance={r => filters.length ? (matches(r) ? 'match' : 'miss') : undefined}
+      columns={[
+        { key: 'title', header: 'Title' },
+        { key: 'status', header: 'Status', cell: r => FB_STATUSES.find(s => s.value === r.status).label },
+        { key: 'assignee', header: 'Assignee', cell: r => FB_PEOPLE.find(p => p.value === r.assignee).label },
+        { key: 'updated', header: 'Updated' },
+        { key: 'points', header: 'Points', align: 'end' },
+      ]} />
+  </div>;
+}
+```
+<!-- /example -->