altitude-design 0.4.0 → 0.4.2

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

@@ -35,3 +35,47 @@ formatNumber(4213, { format: 'compact' })                              // "4.2K"
 - Do use `formatNumber` for table columns and chart formatters, so a number reads the same everywhere.
 - Don't animate digits or count up to a new value.
 - Don't use it for a headline figure; that's a `Stat`.
+
+<!-- example: generated from build/previews.txt by build/previews.mjs. Edit the preview, not this section. -->
+## Example
+
+`FormattedNumber` as first used in its preview:
+
+```tsx
+import { FormattedNumber } from 'altitude-design';
+
+<FormattedNumber value={4900} format="currency" currency="EUR" locale="en-IE" />
+```
+
+The full preview, as rendered in Storybook and checked in CI (`fn`, `cap` are the preview page's own layout classes, not Altitude's):
+
+```tsx
+import * as React from 'react';
+import { Card, CardContent, CardDescription, CardHeader, CardTitle, FormattedNumber } from 'altitude-design';
+
+const usage = [4_212_000_000, 4_512_000_000, 5_030_000_000];
+export default function App() {
+  const [i, setI] = React.useState(0);
+  React.useEffect(() => { const t = setInterval(() => setI((n) => (n + 1) % usage.length), 2600); return () => clearInterval(t); }, []);
+  return (
+    <div className="fn">
+      <dl>
+        <dt>Plan</dt><dd><FormattedNumber value={4900} format="currency" currency="EUR" locale="en-IE" /> a month</dd>
+        <dt>Storage</dt><dd><FormattedNumber value={4_512_000_000} format="bytes" /></dd>
+        <dt>Latency</dt><dd><FormattedNumber value={128} format="duration" /> · <FormattedNumber value={95_000} format="duration" /></dd>
+        <dt>Error rate</dt><dd><FormattedNumber value={0.0123} format="percent" maximumFractionDigits={1} /></dd>
+        <dt>Requests</dt><dd><FormattedNumber value={4213} format="compact" /></dd>
+        <dt>Seats</dt><dd><FormattedNumber value={1250} /></dd>
+      </dl>
+      <Card>
+        <CardHeader><CardTitle>Usage</CardTitle><CardDescription>Refreshes as files are uploaded</CardDescription></CardHeader>
+        <CardContent>
+          <p>You've used <FormattedNumber value={usage[i]} format="bytes" /> of <FormattedNumber value={10_000_000_000} format="bytes" />.</p>
+          <p className="cap">A changed value cross-fades and settles with a tint. It never counts up. Point at "4.2K" or a byte size for its exact value.</p>
+        </CardContent>
+      </Card>
+    </div>
+  );
+}
+```
+<!-- /example -->

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

@@ -43,3 +43,74 @@ A value per cell across two dimensions: load by hour and weekday, error rate by
 - Do use `scale="diverging"` only when the midpoint means something (no change, a target).
 - Don't use a heatmap to compare a handful of values; that's `BarChart`.
 - Don't encode a second measure in cell size or a glow; it's one value per cell.
+
+<!-- example: generated from build/previews.txt by build/previews.mjs. Edit the preview, not this section. -->
+## Example
+
+`Heatmap` as first used in its preview:
+
+```tsx
+import { Heatmap } from 'altitude-design';
+
+<Heatmap variant="calendar" data={commits} date="day" value="count" bins={[0, 1, 4, 10]} />
+```
+
+The full preview, as rendered in Storybook and checked in CI (`hm`, `wide` are the preview page's own layout classes, not Altitude's):
+
+```tsx
+import * as React from 'react';
+import { Card, CardContent, CardDescription, CardHeader, CardTitle, ChartContainer, Heatmap } from 'altitude-design';
+
+const days = ['Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat', 'Sun'];
+// Requests per hour: a working-day hump, quieter weekends, and a Tuesday-afternoon peak.
+const load = days.flatMap((weekday, w) => Array.from({ length: 24 }, (_, hour) => {
+  const day = Math.max(0, Math.sin(((hour - 6) / 15) * Math.PI));
+  const base = (w < 5 ? 300 : 110) * day + 20 + ((hour * 7 + w * 13) % 17);
+  return { weekday, hour, requests: Math.round(base + (w === 1 && hour >= 13 && hour <= 15 ? 160 : 0)) };
+}));
+// Commits per day for a year, with quiet weekends, a holiday gap and a few busy weeks.
+const start = Date.UTC(2025, 9, 27);
+const commits = Array.from({ length: 365 }, (_, i) => {
+  const t = start + i * 864e5, wd = new Date(t).getUTCDay(), r = (i * 37 + 11) % 23;
+  const busy = (i > 120 && i < 140) || (i > 300 && i < 312);
+  const n = wd === 0 || wd === 6 ? (r < 18 ? 0 : r - 17) : i > 56 && i < 68 ? 0 : busy ? 6 + (r % 9) : r < 5 ? 0 : Math.round(r / 3);
+  return { day: new Date(t).toISOString().slice(0, 10), count: n };
+});
+const services = ['Checkout', 'Search', 'Accounts', 'Media', 'Payments'];
+const regions = ['US', 'EU', 'APAC', 'LATAM'];
+// Error rate against last week, in points: below zero is better.
+const change = services.flatMap((service, s) => regions.map((region, r) => ({ service, region, delta: s === 3 && r === 3 ? null : Math.round((Math.sin(s * 2.1 + r * 1.3) * 1.6 + (s === 4 && r === 1 ? 1.8 : 0)) * 10) / 10 })));
+const pts = (v) => (v > 0 ? '+' : v < 0 ? '−' : '') + Math.abs(v).toFixed(1) + ' pts';
+export default function App() {
+  const [cell, setCell] = React.useState(null);
+  return (
+    <div className="hm">
+      <Card className="wide">
+        <CardHeader><CardTitle id="h1">Commits</CardTitle><CardDescription>A year, a cell per day: zero is the lightest step, and each step says its range</CardDescription></CardHeader>
+        <CardContent>
+          <ChartContainer aria-labelledby="h1" config={{ count: { label: 'Commits' } }}>
+            <Heatmap variant="calendar" data={commits} date="day" value="count" bins={[0, 1, 4, 10]} />
+          </ChartContainer>
+        </CardContent>
+      </Card>
+      <Card>
+        <CardHeader><CardTitle id="h2">Requests by hour</CardTitle><CardDescription>Load by weekday and hour, with the table view</CardDescription></CardHeader>
+        <CardContent>
+          <ChartContainer aria-labelledby="h2" views config={{ requests: { label: 'Requests' } }} xLabel="Weekday">
+            <Heatmap data={load} x="hour" y="weekday" value="requests" xFormat={(h) => String(h).padStart(2, '0')} />
+          </ChartContainer>
+        </CardContent>
+      </Card>
+      <Card>
+        <CardHeader><CardTitle id="h3">Error rate against last week</CardTitle><CardDescription>{cell ? `${cell.service} in ${cell.region}: select it again to clear` : 'scale="diverging": better below zero. Select a cell'}</CardDescription></CardHeader>
+        <CardContent>
+          <ChartContainer aria-labelledby="h3" config={{ delta: { label: 'Change', format: pts } }}>
+            <Heatmap data={change} x="region" y="service" value="delta" scale="diverging" selected={cell} onSelect={setCell} />
+          </ChartContainer>
+        </CardContent>
+      </Card>
+    </div>
+  );
+}
+```
+<!-- /example -->

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

@@ -14,3 +14,35 @@ This is a design friction: a small, deliberate obstacle in front of an action th
 
 - Use it for destructive or irreversible actions where the person already knows what will happen.
 - Don't use it when the consequence needs explaining; that's a `Dialog`.
+
+<!-- example: generated from build/previews.txt by build/previews.mjs. Edit the preview, not this section. -->
+## Example
+
+`HoldButton` as first used in its preview:
+
+```tsx
+import { HoldButton } from 'altitude-design';
+
+<HoldButton onConfirm={() => {}} holdingLabel="Keep holding…" doneLabel="Project deleted">Hold to delete</HoldButton>
+```
+
+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 { HoldButton } from 'altitude-design';
+
+export default function App() {
+  const [n, setN] = React.useState(0);
+  return (
+    <div className="col">
+      <div className="row">
+        <HoldButton onConfirm={() => {}} holdingLabel="Keep holding…" doneLabel="Project deleted">Hold to delete</HoldButton>
+        <HoldButton variant="primary" duration={700} repeatable onConfirm={() => setN(n + 1)} doneLabel="Published">Hold to publish</HoldButton>
+      </div>
+      <p className="cap">Press and hold (or hold Space). The button sinks below the ground as the fuse burns; let go early and it springs back. Once done it lies flat and can't be pressed again, unless it's <code>repeatable</code> (published {n}×).</p>
+    </div>
+  );
+}
+```
+<!-- /example -->

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

@@ -16,3 +16,56 @@ A richer preview of what a link or a face points to: who someone is, what a proj
 
 - Do keep it to a glance: if people need to act on it, it's a Popover (click to open) or a page.
 - Don't put the only copy of anything in it, and don't put a form in it.
+
+<!-- example: generated from build/previews.txt by build/previews.mjs. Edit the preview, not this section. -->
+## Example
+
+`HoverCard` as first used in its preview:
+
+```tsx
+import { HoverCard } from 'altitude-design';
+
+<HoverCard defaultOpen={true} trigger={<a href="#mara">Mara Quist</a>}>
+  <Card p={people.mara} />
+</HoverCard>
+```
+
+The full preview, as rendered in Storybook and checked in CI (`who`, `bio`, `stats`, `col`, `para`, `cap` are the preview page's own layout classes, not Altitude's):
+
+```tsx
+import { Avatar, HoverCard } from 'altitude-design';
+
+const people = {
+  mara: { name: "Mara Quist", role: "Platform \xB7 Lisbon", bio: "Owns deploys and the edge runtime. Usually reviews within the hour.", s: [42, 6, 3] },
+  jon: { name: "Jon Reyes", role: "Docs \xB7 Lima", bio: "Writes the release notes and keeps the changelog honest.", s: [18, 2, 5] }
+};
+const Card = ({ p }) => <>
+  <div className="who">
+    <Avatar name={p.name} size={40} status="active" />
+    <div><b>{p.name}</b><span>{p.role}</span></div>
+  </div>
+  <p className="bio">{p.bio}</p>
+  <div className="stats">
+    <span><b>{p.s[0]}</b>{" merged"}</span>
+    <span><b>{p.s[1]}</b>{" open"}</span>
+    <span><b>{p.s[2]}</b>{" projects"}</span>
+  </div>
+</>;
+export default function App() {
+  return <div className="col" style={{ gap: 18 }}>
+  <p className="para">
+    {"Merged by "}
+    <HoverCard defaultOpen={true} trigger={<a href="#mara">Mara Quist</a>}>
+      <Card p={people.mara} />
+    </HoverCard>
+    {" two hours ago, after review from "}
+    <HoverCard trigger={<a href="#jon">Jon Reyes</a>}><Card p={people.jon} /></HoverCard>
+    .
+  </p>
+  <p className="cap" style={{ marginTop: 160 }}>
+    Rest the pointer on a name; once one card has shown, the other opens at once. Focus a link with Tab to open it from the keyboard; Escape closes it.
+  </p>
+</div>;
+}
+```
+<!-- /example -->

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

@@ -22,3 +22,35 @@ Numbered source markers in a grounded answer ("…renews monthly [2]"), with a p
 - Do include the excerpt the answer relied on.
 - Do mark sources you couldn't verify.
 - Don't render citations as bare numbers or superscripts with no name.
+
+<!-- example: generated from build/previews.txt by build/previews.mjs. Edit the preview, not this section. -->
+## Example
+
+`InlineCitation` as first used in its preview:
+
+```tsx
+import { InlineCitation } from 'altitude-design';
+
+<InlineCitation index={1} source={sources[0]} />
+```
+
+The full preview, as rendered in Storybook and checked in CI (`ic` is the preview page's own layout class, not Altitude's):
+
+```tsx
+import { InlineCitation, Sources } from 'altitude-design';
+
+const sources = [
+  { title: 'Billing FAQ', url: 'https://help.example.com/billing/faq', excerpt: 'Annual plans can be refunded in full within 30 days of purchase.' },
+  { title: 'Plans and pricing', url: 'https://example.com/pricing', excerpt: 'Monthly plans renew on the same day each month.' },
+  { title: 'Forum post: “Refunds after 30 days?”', url: 'https://community.example.com/t/4821', unverified: true },
+];
+export default function App() {
+  return (
+    <div className="ic">
+      <p>Annual plans can be refunded in full within 30 days<InlineCitation index={1} source={sources[0]} />. Monthly plans renew on the same day each month<InlineCitation index={2} source={sources[1]} />, and some customers report partial refunds after that<InlineCitation index={3} source={sources[2]} />.</p>
+      <Sources items={sources} />
+    </div>
+  );
+}
+```
+<!-- /example -->

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

@@ -130,4 +130,250 @@ Optional labels are `editLabel` (default `Edit ${label}`), `saveLabel` (“Save
 
 The canonical `InlineEdit` section in `build/previews.txt` renders a task title (in its heading font), a multiline description, the task's status (Select, on choose, with a rejected “Blocked”), assignee (Combobox, on choose) and estimate (a numeric Input), an independent filename table cell with this component, and “Ways to open”: a pencil and two fields on hover, with seams. A collapsed documentation harness selects deterministic fixtures before mounting, resets records and counters, delays validation, applies external updates, removes the filename consumer during work and opens a dialog comparison using the same validation and persistence adapter. Fixture controls and operation logs stay outside the product scene.
 
-Run `node checks/inline-edit.mjs` from `build/` after generating preview fixtures. `ALT_FIXTURE_ROOT=test/react19` selects the React 19 source fixtures. The checks cover editing in place (the value's text doesn't move, the control takes its font, the pencil and the field move nothing on hover, the caret lands where clicked, the seam, the announcement that clears itself), multiline (newline on Enter, Ctrl/Cmd+Enter, IME, Escape, caret at the end, growth to `maxRows`, line breaks in read mode), custom editors (focus, Escape layering, on-choose saves and rejections, unchanged choices, numeric validation), lifecycle races, retained input, uncertainty reconciliation, conflict latching, keyboard/IME, focus, disabled behavior and the four-scheme responsive/accessibility matrix. Automated checks do not replace the human screen-reader, touch, magnification or formative comparisons recorded in [Actions in place validation](https://github.com/richlaconte/altitude/blob/v0.4.0/project/ActionsInPlaceValidation.md).
+Run `node checks/inline-edit.mjs` from `build/` after generating preview fixtures. `ALT_FIXTURE_ROOT=test/react19` selects the React 19 source fixtures. The checks cover editing in place (the value's text doesn't move, the control takes its font, the pencil and the field move nothing on hover, the caret lands where clicked, the seam, the announcement that clears itself), multiline (newline on Enter, Ctrl/Cmd+Enter, IME, Escape, caret at the end, growth to `maxRows`, line breaks in read mode), custom editors (focus, Escape layering, on-choose saves and rejections, unchanged choices, numeric validation), lifecycle races, retained input, uncertainty reconciliation, conflict latching, keyboard/IME, focus, disabled behavior and the four-scheme responsive/accessibility matrix. Automated checks do not replace the human screen-reader, touch, magnification or formative comparisons recorded in [Actions in place validation](https://github.com/richlaconte/altitude/blob/v0.4.2/project/ActionsInPlaceValidation.md).
+
+<!-- example: generated from build/previews.txt by build/previews.mjs. Edit the preview, not this section. -->
+## Example
+
+`InlineEdit` as first used in its preview:
+
+```tsx
+import { InlineEdit } from 'altitude-design';
+
+<InlineEdit label="Description" value={task.description} onValueChange={publish('description')} onSave={save('description')}
+  multiline rows={3} maxRows={8} maxLength={500} />
+```
+
+The full preview, as rendered in Storybook and checked in CI (`inline-demo-description`, `inline-demo-prop-label`, `inline-demo-props`, `inline-demo-prop`, `inline-demo-scene`, `inline-demo-task`, `inline-demo-meta`, `inline-demo-harness`, `inline-demo-controls`, `inline-demo-log`, `inline-demo` are the preview page's own layout classes, not Altitude's):
+
+```tsx
+import * as React from 'react';
+import { Badge, Button, Combobox, Dialog, Field, InlineEdit, Input, Select, Table, TableBody, TableCell, TableHead, TableHeader, TableRow } from 'altitude-design';
+
+const INLINE_RECORDS = Object.freeze([
+  Object.freeze({ id: 'task-launch', name: 'Prepare launch checklist', revision: 1 }),
+  Object.freeze({ id: 'file-brand', name: 'Brand guidelines.pdf', revision: 1 }),
+  Object.freeze({ id: 'file-brand-draft', name: 'Brand guidelines draft.pdf', revision: 1 }),
+  Object.freeze({ id: 'file-launch', name: 'Launch checklist.md', revision: 1 }),
+]);
+const INLINE_FIXTURES = ['success-100', 'success-1200', 'fail-once', 'conflict', 'interrupted-after-save'];
+const inlineWait = ms => new Promise(resolve => setTimeout(resolve, ms));
+const INLINE_STATUSES = [{ value: 'todo', label: 'To do' }, { value: 'progress', label: 'In progress' }, { value: 'review', label: 'In review' }, { value: 'blocked', label: 'Blocked' }];
+const INLINE_TONES = { todo: 'neutral', progress: 'accent', review: 'caution', blocked: 'critical' };
+const INLINE_PEOPLE = [{ value: 'mara', label: 'Mara Quist' }, { value: 'ines', label: 'Inés Ortega' }, { value: 'tobi', label: 'Tobi Adeyemi' }, { value: 'wen', label: 'Li Wen' }];
+const inlineLabel = (list, value) => list.find(option => option.value === value)?.label ?? 'Not set';
+
+// Task properties: the same session with a different editor. Status and assignee save on choose; the estimate waits for Save.
+function InlineTaskProperties() {
+  const [task, setTask] = React.useState({ status: 'progress', assignee: 'mara', estimate: 3, description: 'Collect sign-off from design, support and legal.\nShare the final list in #launch by Thursday.' });
+  const publish = key => value => setTask(task => ({ ...task, [key]: value }));
+  const save = key => async draft => {
+    await inlineWait(300);
+    if (key === 'status' && draft === 'blocked') return { ok: false, error: 'Only the project lead can block a task. Choose another status.' };
+    return { ok: true, value: draft };
+  };
+  return <>
+    <div className="inline-demo-description"><span className="inline-demo-prop-label" aria-hidden="true">Description</span>
+      <InlineEdit label="Description" value={task.description} onValueChange={publish('description')} onSave={save('description')}
+        multiline rows={3} maxRows={8} maxLength={500} /></div>
+    <div className="inline-demo-props">
+    <div className="inline-demo-prop"><span className="inline-demo-prop-label" aria-hidden="true">Status</span>
+      <InlineEdit label="Status" value={task.status} onValueChange={publish('status')} onSave={save('status')} commit="on-choose"
+        renderValue={status => <Badge tone={INLINE_TONES[status]}>{inlineLabel(INLINE_STATUSES, status)}</Badge>}
+        editor={control => <Select {...control} items={INLINE_STATUSES} size="sm" />} /></div>
+    <div className="inline-demo-prop"><span className="inline-demo-prop-label" aria-hidden="true">Assignee</span>
+      <InlineEdit label="Assignee" value={task.assignee} onValueChange={publish('assignee')} onSave={save('assignee')} commit="on-choose"
+        renderValue={person => inlineLabel(INLINE_PEOPLE, person)}
+        editor={control => <Combobox {...control} items={INLINE_PEOPLE} size="sm" placeholder="Type a name" />} /></div>
+    <div className="inline-demo-prop"><span className="inline-demo-prop-label" aria-hidden="true">Estimate</span>
+      <InlineEdit label="Estimate" value={task.estimate} onValueChange={publish('estimate')} onSave={save('estimate')} required
+        validate={points => Number.isInteger(points) && points >= 0 && points <= 40 ? undefined : 'Use a whole number from 0 to 40.'}
+        renderValue={points => `${points} point${points === 1 ? '' : 's'}`}
+        editor={({ value, onValueChange, ...control }) => <Input {...control} type="number" inputMode="numeric" min={0} max={40} size="sm"
+          value={value ?? ''} onChange={event => onValueChange(event.target.value === '' ? null : Number(event.target.value))} />} /></div>
+    </div>
+  </>;
+}
+
+function InlineExample({ fixture, slowValidation, epoch }) {
+  const server = React.useRef(null);
+  if (!server.current) server.current = new Map(INLINE_RECORDS.map(record => [record.id, { ...record }]));
+  const [records, setRecords] = React.useState(() => INLINE_RECORDS.map(record => ({ ...record })));
+  const [log, setLog] = React.useState([]);
+  const [visible, setVisible] = React.useState(true);
+  const [outsideCount, setOutsideCount] = React.useState(0);
+  const [baseline, setBaseline] = React.useState(false);
+  const sequence = React.useRef(0), failUsed = React.useRef(false), accepted = React.useRef(new Map());
+  const alive = React.useRef(true);
+  React.useEffect(() => { alive.current = true; return () => { alive.current = false; }; }, []);
+  const record = id => records.find(record => record.id === id);
+  const trace = event => { if (alive.current) setLog(log => [...log, event]); };
+  const reconcile = id => { if (alive.current) setRecords(records => records.map(record => record.id === id ? { ...server.current.get(id) } : record)); };
+  const publish = id => canonicalValue => {
+    trace({ event: 'published', id, value: canonicalValue });
+    setRecords(records => records.map(record => record.id === id ? { ...server.current.get(id), name: canonicalValue } : record));
+  };
+  const validate = id => async draft => {
+    if (slowValidation) await inlineWait(1200);
+    if (!draft.trim()) return 'Enter a name.';
+    if ([...server.current.values()].some(record => record.id !== id && record.name === draft.trim())) return 'A file already has this name. Choose another.';
+  };
+  const save = id => async (draft, { previousValue }) => {
+    const expectedRevision = record(id).revision;
+    const operationId = `rename-${epoch}-${++sequence.current}`;
+    trace({ event: 'requested', id, expectedRevision, operationId, draft });
+    const commit = () => {
+      if (accepted.current.has(operationId)) return accepted.current.get(operationId);
+      const current = server.current.get(id);
+      if (current.revision !== expectedRevision || current.name !== previousValue) {
+        reconcile(id); trace({ event: 'rejected-stale', id, operationId });
+        return { ok: false, error: 'The saved name changed. Review the current name.' };
+      }
+      const next = { ...current, name: draft.trim(), revision: current.revision + 1 };
+      server.current.set(id, next);
+      const result = { ok: true, value: next.name };
+      accepted.current.set(operationId, result);
+      trace({ event: 'committed', id, revision: next.revision, operationId, value: next.name });
+      return result;
+    };
+    if (fixture === 'interrupted-after-save') {
+      await inlineWait(100); const result = commit();
+      await inlineWait(1100);
+      // Simulate a lost acknowledgement, then query/retry the same operation ID.
+      // A known committed result is returned as success; no second mutation occurs.
+      trace({ event: 'reconciled', id, operationId, revision: server.current.get(id).revision });
+      return accepted.current.get(operationId) || result;
+    }
+    if (fixture === 'conflict') {
+      await inlineWait(100);
+      const current = server.current.get(id);
+      server.current.set(id, { ...current, name: id === 'task-launch' ? 'Prepare updated launch checklist' : 'Brand guidelines revised.pdf', revision: current.revision + 1 });
+      reconcile(id); trace({ event: 'external-update', id, revision: current.revision + 1 });
+      await inlineWait(1100); return commit();
+    }
+    if (fixture === 'fail-once' && !failUsed.current) {
+      failUsed.current = true; await inlineWait(1200);
+      trace({ event: 'rejected', id, operationId });
+      return { ok: false, error: 'We couldn’t save this name. Your text is still here. Try again.' };
+    }
+    await inlineWait(fixture === 'success-1200' ? 1200 : 100);
+    return commit();
+  };
+  const file = record('file-brand');
+  const externalUpdate = () => {
+    const current = server.current.get('file-brand');
+    server.current.set('file-brand', { ...current, name: 'Brand guidelines updated.pdf', revision: current.revision + 1 });
+    trace({ event: 'external-update', id: 'file-brand', revision: current.revision + 1 }); reconcile('file-brand');
+  };
+  return <>
+    <div className="inline-demo-scene" data-inline-scene="">
+      <section className="inline-demo-task" aria-labelledby="inline-task-title">
+        <h2 id="inline-task-title">Launch preparation</h2>
+        <InlineEdit label="Task title" editLabel="Edit task title" value={record('task-launch').name} onValueChange={publish('task-launch')} onSave={save('task-launch')} validate={validate('task-launch')} required maxLength={100} />
+        <p className="inline-demo-meta">Due Friday · Product team</p>
+        <InlineTaskProperties />
+      </section>
+      <section aria-labelledby="inline-files-title">
+        <h2 id="inline-files-title">Files</h2>
+        <Table>
+          <TableHeader><TableRow><TableHead>File name</TableHead><TableHead>Size</TableHead></TableRow></TableHeader>
+          <TableBody>
+            {visible && <TableRow><TableCell>
+              <InlineEdit label="File name" editLabel="Rename file" value={file.name} onValueChange={publish('file-brand')} onSave={save('file-brand')} validate={validate('file-brand')} required maxLength={100} />
+            </TableCell><TableCell>2.4 MB</TableCell></TableRow>}
+            <TableRow><TableCell>{record('file-brand-draft').name}<p className="inline-demo-meta">Draft · Updated yesterday</p></TableCell><TableCell>1.8 MB</TableCell></TableRow>
+            <TableRow><TableCell>{record('file-launch').name}</TableCell><TableCell>8 KB</TableCell></TableRow>
+          </TableBody>
+        </Table>
+        <Button variant="ghost" onClick={() => setOutsideCount(count => count + 1)}>Show file details</Button>
+        {outsideCount > 0 && <p className="inline-demo-meta">Three fictional files · Details opened {outsideCount} time{outsideCount === 1 ? '' : 's'}.</p>}
+      </section>
+      <InlineWaysToOpen />
+    </div>
+    <details className="inline-demo-harness">
+      <summary>Comparison and fixture controls</summary>
+      <p>These controls belong to the documentation harness. The dialog comparison uses the same filename, validation and save adapter. Reset before each trial.</p>
+      <div className="inline-demo-controls">
+        <Button onClick={externalUpdate}>Apply external filename update</Button>
+        <Button onClick={() => { if (!visible) reconcile('file-brand'); setVisible(visible => !visible); }}>{visible ? 'Remove filename editor' : 'Show filename editor'}</Button>
+        <Button onClick={() => setBaseline(true)}>Open dialog rename baseline</Button>
+      </div>
+      <output className="inline-demo-log" data-inline-log="" aria-label="Fixture operation log">{JSON.stringify(log, null, 2)}</output>
+    </details>
+    <InlineDialogBaseline open={baseline} onOpenChange={setBaseline} value={file.name} validate={validate('file-brand')} onSave={save('file-brand')} onValueChange={publish('file-brand')} />
+  </>;
+}
+
+function InlineDialogBaseline({ open, onOpenChange, value, validate, onSave, onValueChange }) {
+  const [draft, setDraft] = React.useState(value), [error, setError] = React.useState(''), [busy, setBusy] = React.useState('');
+  const baseline = React.useRef(value), generation = React.useRef(0), guard = React.useRef(false), latest = React.useRef(value);
+  latest.current = value;
+  React.useEffect(() => {
+    generation.current++; guard.current = false; setBusy(''); setError('');
+    if (open) { baseline.current = value; setDraft(value); }
+    return () => { generation.current++; };
+  }, [open]);
+  const submit = async () => {
+    if (guard.current) return;
+    if (latest.current !== baseline.current) { setError('The saved value changed. Close and reopen to review it.'); return; }
+    if (draft === baseline.current) { onOpenChange(false); return; }
+    guard.current = true; const token = generation.current; setError(''); setBusy('Checking value');
+    const error = draft.length > 100 ? 'Use 100 characters or fewer.' : await validate(draft);
+    if (token !== generation.current) return;
+    if (error) { guard.current = false; setBusy(''); setError(error); return; }
+    setBusy('Saving changes');
+    const result = await onSave(draft, { previousValue: baseline.current });
+    if (token !== generation.current) return;
+    guard.current = false; setBusy('');
+    if (latest.current !== baseline.current) { setError('The value changed while saving. Your save may have completed. Check the current record.'); return; }
+    if (!result.ok) { setError(result.error); return; }
+    onValueChange(result.value); onOpenChange(false);
+  };
+  return <Dialog open={open} onOpenChange={onOpenChange} title="Rename file" description="Change the name of this file." dismissible={busy !== 'Saving changes'} footer={<>
+    <Button variant="ghost" disabled={busy === 'Saving changes'} onClick={() => onOpenChange(false)}>Cancel</Button>
+    <Button variant="primary" loading={busy === 'Saving changes'} disabled={busy === 'Checking value'} onClick={submit}>Save changes</Button>
+  </>}>
+    <Field label="File name" error={error} required><Input value={draft} maxLength={100} readOnly={!!busy} onChange={event => { setDraft(event.target.value); setError(''); }} onKeyDown={event => {
+      if (event.nativeEvent.isComposing || event.nativeEvent.keyCode === 229) return;
+      if (event.key === 'Enter') { event.preventDefault(); submit(); }
+    }} /></Field>
+    <p role="status">{busy}</p>
+  </Dialog>;
+}
+
+// The value as its own button: a pencil on hover, or the field itself on hover. The seam says so at rest.
+function InlineWaysToOpen() {
+  const [values, setValues] = React.useState({ project: 'Northwind launch', meeting: 'Quarterly planning review', owner: '' });
+  const set = key => next => setValues(all => ({ ...all, [key]: next }));
+  const save = draft => ({ ok: true, value: draft.trim() });
+  return <section aria-labelledby="inline-ways-title">
+    <h2 id="inline-ways-title">Ways to open</h2>
+    <div className="inline-demo-props">
+      <div className="inline-demo-prop"><span className="inline-demo-prop-label">Pencil on hover, with a seam</span>
+        <InlineEdit label="Project name" trigger="pencil" hint="seam" value={values.project} onValueChange={set('project')} onSave={save} required /></div>
+      <div className="inline-demo-prop"><span className="inline-demo-prop-label">Field on hover, with a seam</span>
+        <InlineEdit label="Meeting title" trigger="field" hint="seam" value={values.meeting} onValueChange={set('meeting')} onSave={save} required /></div>
+      <div className="inline-demo-prop"><span className="inline-demo-prop-label">Field on hover, empty</span>
+        <InlineEdit label="Owner" trigger="field" hint="seam" emptyLabel="Add an owner" value={values.owner} onValueChange={set('owner')} onSave={save} /></div>
+    </div>
+  </section>;
+}
+
+export default function App() {
+  const [fixture, setFixture] = React.useState('success-100'), [slow, setSlow] = React.useState(false);
+  const [mounted, setMounted] = React.useState({ fixture: 'success-100', slow: false, epoch: 0 });
+  return <div className="inline-demo">
+    <InlineExample key={mounted.epoch} fixture={mounted.fixture} slowValidation={mounted.slow} epoch={mounted.epoch} />
+    <details className="inline-demo-harness">
+      <summary>Choose the next fixture</summary>
+      <p>Select before mounting. Reset restores the same fictional records, revisions and request counters.</p>
+      <div className="inline-demo-controls">
+        <label>Rename fixture<select value={fixture} onChange={event => setFixture(event.target.value)}>{INLINE_FIXTURES.map(name => <option key={name}>{name}</option>)}</select></label>
+        <label><input type="checkbox" checked={slow} onChange={event => setSlow(event.target.checked)} />Delay validation by 1,200 ms</label>
+        <Button onClick={() => setMounted({ fixture, slow, epoch: mounted.epoch + 1 })}>Reset example</Button>
+      </div>
+    </details>
+  </div>;
+}
+```
+<!-- /example -->

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

@@ -25,3 +25,39 @@ The shadow list is always four layers (wall, occlusion, lip, halo; the halo is u
 - Don't add an accent focus ring or glow to fields, or a rim on click. Keyboard focus on buttons and choice controls is the `accent-ink` ring; on a field the lit floor is the focus, plus the dark rim when you arrived by keyboard.
 - Don't put a suggestion in the value: pass it as `suggestion`, so people can tell what they wrote from what was proposed.
 - Don't place inputs on `surface-well` backgrounds: a well inside a well disappears. Put forms on ground or raised surfaces.
+
+<!-- example: generated from build/previews.txt by build/previews.mjs. Edit the preview, not this section. -->
+## Example
+
+`Input` as first used in its preview:
+
+```tsx
+import { Input } from 'altitude-design';
+
+<Input type="email" placeholder="name@company.com" value={email} onChange={(e) => setEmail(e.target.value)} />
+```
+
+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, Input, Kbd, Textarea } from 'altitude-design';
+
+export default function App() {
+  const [note, setNote] = React.useState('Ship the cold-start fix behind a flag first.');
+  const [email, setEmail] = React.useState('');
+  return (
+    <div className="col">
+      <div className="grid">
+        <Field label="Email address"><Input type="email" placeholder="name@company.com" value={email} onChange={(e) => setEmail(e.target.value)} /></Field>
+        <Field label="Billing email"><Input type="email" defaultValue="mara@northwind.dev" /></Field>
+        <Field label="Search projects"><Input type="search" placeholder="Project name" leading={<svg width="16" height="16" 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>} trailing={<Kbd>/</Kbd>} /></Field>
+        <Field label="Invite by email" error="Enter an email address, like name@company.com."><Input type="email" defaultValue="not-an-email" /></Field>
+        <div style={{ gridColumn: '1 / -1' }}><Field label="Note"><Textarea value={note} onChange={(e) => setNote(e.target.value)} maxLength={80} placeholder="Leave a note for your team…" /></Field></div>
+      </div>
+      <p className="cap">An empty field shows its inside wall below the top edge, and deepens as your pointer comes near. Type and the floor rises flush with the page. Invalid drops it to trench depth.</p>
+    </div>
+  );
+}
+```
+<!-- /example -->

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

@@ -28,3 +28,49 @@ A one-time code: two-factor sign-in, email verification, device approval. Four t
 - Do say where the code went and how to get a new one.
 - Don't split the code into several inputs; autofill and paste break.
 - Don't clear the code on a rejection without saying why; leave it so it can be corrected.
+
+<!-- example: generated from build/previews.txt by build/previews.mjs. Edit the preview, not this section. -->
+## Example
+
+`InputOTP` as first used in its preview:
+
+```tsx
+import { InputOTP, InputOTPGroup, InputOTPSeparator, InputOTPSlot } from 'altitude-design';
+
+<InputOTP maxLength={6} value={code} verifying={state === 'verifying'}
+  onChange={(c) => { setCode(c); if (state === 'wrong') setState('idle'); }} onComplete={verify}>
+  <InputOTPGroup>{[0, 1, 2].map((i) => <InputOTPSlot key={i} index={i} />)}</InputOTPGroup>
+  <InputOTPSeparator />
+  <InputOTPGroup>{[3, 4, 5].map((i) => <InputOTPSlot key={i} index={i} />)}</InputOTPGroup>
+</InputOTP>
+```
+
+The full preview, as rendered in Storybook and checked in CI (`col` is the preview page's own layout class, not Altitude's):
+
+```tsx
+import * as React from 'react';
+import { Field, InputOTP, InputOTPGroup, InputOTPSeparator, InputOTPSlot } from 'altitude-design';
+
+export default function App() {
+  const [code, setCode] = React.useState('');
+  const [state, setState] = React.useState('idle');
+  const verify = (c) => { setState('verifying'); setTimeout(() => setState(c === '123456' ? 'ok' : 'wrong'), 900); };
+  const hint = state === 'verifying' ? 'Checking code…' : state === 'ok' ? 'Verified.' : 'We sent it to j•••@acme.com. Try 123456, or any other code to see a rejection.';
+  return (
+    <div className="col">
+      <Field label="Verification code" hint={hint} error={state === 'wrong' ? 'That code didn\'t work. Check the latest email and try again.' : undefined}>
+        <InputOTP maxLength={6} value={code} verifying={state === 'verifying'}
+          onChange={(c) => { setCode(c); if (state === 'wrong') setState('idle'); }} onComplete={verify}>
+          <InputOTPGroup>{[0, 1, 2].map((i) => <InputOTPSlot key={i} index={i} />)}</InputOTPGroup>
+          <InputOTPSeparator />
+          <InputOTPGroup>{[3, 4, 5].map((i) => <InputOTPSlot key={i} index={i} />)}</InputOTPGroup>
+        </InputOTP>
+      </Field>
+      <Field label="Backup code" hint="8 letters or digits.">
+        <InputOTP maxLength={8} pattern="alphanumeric" defaultValue="K7Q2" />
+      </Field>
+    </div>
+  );
+}
+```
+<!-- /example -->