altitude-design 0.4.0 → 0.4.2

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

@@ -23,3 +23,38 @@ Pass `value` (or `defaultValue`) as `[low, high]` and the Slider has two thumbs,
 - **Names.** Give each thumb its own name (`['Minimum price', 'Maximum price']`), or one name for the pair: the thumbs are then "Price, minimum" and "Price, maximum", in a `role="group"` named "Price".
 
 - Do show the current value in text near the slider when it matters precisely; the bubble only shows while dragging or focused.
+
+<!-- example: generated from build/previews.txt by build/previews.mjs. Edit the preview, not this section. -->
+## Example
+
+`Slider` as first used in its preview:
+
+```tsx
+import { Slider } from 'altitude-design';
+
+<Slider value={v} onValueChange={setV} aria-label="Volume" format={(n) => n + '%'} />
+```
+
+The full preview, as rendered in Storybook and checked in CI (`col`, `wrap`, `cap`, `gap` are the preview page's own layout classes, not Altitude's):
+
+```tsx
+import * as React from 'react';
+import { Slider } from 'altitude-design';
+
+export default function App() {
+  const [v, setV] = React.useState(64);
+  const [price, setPrice] = React.useState([20, 80]);
+  return (
+    <div className="col wrap">
+      <Slider value={v} onValueChange={setV} aria-label="Volume" format={(n) => n + '%'} />
+      <Slider defaultValue={30} disabled aria-label="Disabled" />
+      <p className="cap">Volume {v}% — drag, or focus and use the arrow keys.</p>
+      <div className="gap" />
+      <Slider value={price} onValueChange={setPrice} min={0} max={200} step={5} minStepsBetween={2}
+        aria-label={['Minimum price', 'Maximum price']} format={(n) => '$' + n} />
+      <p className="cap">Price ${price[0]}–${price[1]} — drag either thumb, or the fill to move both.</p>
+    </div>
+  );
+}
+```
+<!-- /example -->

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

@@ -9,3 +9,37 @@ Pressing and dragging an item lifts it to level 3 (floating surface, `elev-3`),
 **You provide:** `items`, `getKey`, `onReorder` (receives the new array), `renderItem` (the row content; the row itself and its grip are drawn for you), `getLabel` for announcements, `aria-label`.
 
 - Do keep rows short and uniform; the slot is sized to the item being moved.
+
+<!-- example: generated from build/previews.txt by build/previews.mjs. Edit the preview, not this section. -->
+## Example
+
+`SortableList` as first used in its preview:
+
+```tsx
+import { Badge, SortableList } from 'altitude-design';
+
+<SortableList aria-label="Priorities" items={items} getKey={(i) => i.id} getLabel={(i) => i.t} onReorder={setItems}
+  renderItem={(i) => <div className="it">{i.t}<Badge tone={i.p === 'High' ? 'critical' : i.p === 'Med' ? 'caution' : 'neutral'}>{i.p}</Badge></div>} />
+```
+
+The full preview, as rendered in Storybook and checked in CI (`col`, `wrap`, `it`, `cap` are the preview page's own layout classes, not Altitude's):
+
+```tsx
+import * as React from 'react';
+import { Badge, SortableList } from 'altitude-design';
+
+export default function App() {
+  const [items, setItems] = React.useState([
+    { id: 'a', t: 'Write release notes', p: 'High' }, { id: 'b', t: 'Review pricing copy', p: 'Med' },
+    { id: 'c', t: 'Fix cold-start regression', p: 'High' }, { id: 'd', t: 'Update onboarding emails', p: 'Low' }, { id: 'e', t: 'Plan Q1 roadmap', p: 'Med' },
+  ]);
+  return (
+    <div className="col wrap">
+      <SortableList aria-label="Priorities" items={items} getKey={(i) => i.id} getLabel={(i) => i.t} onReorder={setItems}
+        renderItem={(i) => <div className="it">{i.t}<Badge tone={i.p === 'High' ? 'critical' : i.p === 'Med' ? 'caution' : 'neutral'}>{i.p}</Badge></div>} />
+      <p className="cap">Drag, or focus a row and press Space, then the arrow keys.</p>
+    </div>
+  );
+}
+```
+<!-- /example -->

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

@@ -27,3 +27,61 @@ A trend the size of a word: the last 30 days of a metric in a `DataTable` cell,
 - Don't give it axes, a tooltip or a legend; when someone needs to read values, that's a `LineChart`.
 - Don't colour it with a status hue unless the series means good or bad, and say so in words beside it.
 - Don't compare sparklines in different rows as if they shared a scale: each is scaled to its own values.
+
+<!-- example: generated from build/previews.txt by build/previews.mjs. Edit the preview, not this section. -->
+## Example
+
+`Sparkline` as first used in its preview:
+
+```tsx
+import { Sparkline } from 'altitude-design';
+
+<Sparkline data={signups} x="day" y="signups" tone="data" width={120} aria-label="Signups, last 30 days" />
+```
+
+The full preview, as rendered in Storybook and checked in CI (`sp`, `row`, `big`, `note` are the preview page's own layout classes, not Altitude's):
+
+```tsx
+import * as React from 'react';
+import { Badge, DataTable, Sparkline } from 'altitude-design';
+
+const spDays = (vals) => vals.map((v, i) => ({ day: `2026-10-${String(i + 1).padStart(2, '0')}`, signups: v }));
+const signups = spDays([1200, 1180, 1230, 1260, 1210, 1290, 1310, 1280, 1300, 1350, 1330, 1290, 1340, 1370, 1360, 1320, 1380, 1400, 1390, 1360, 1410, 1430, 1390, 1420, 1450, 1410, 1380, 1420, 1440, 1400]);
+const teams = [
+  { id: 'core', name: 'Core', builds: [12, 14, 13, 15, 16, 18, 17, 19, 21, 20, 22, 24, 23, 25], errors: [0.4, 0.5, 0.4, 0.6, 0.5, 0.7, 0.9, 1.1, 1.0, 1.3, 1.5, 1.4, 1.8, 2.1] },
+  { id: 'web', name: 'Web', builds: [30, 28, 31, 27, 29, 26, 25, 27, 24, 23, 25, 22, 21, 20], errors: [1.2, 1.1, 1.3, 1.2, 1.1, 1.2, 1.0, 1.1, 1.2, 1.1, 1.0, 1.1, 1.2, 1.1] },
+  { id: 'data', name: 'Data', builds: [8, 9, null, null, 11, 10, 12, 14, 13, 15, 14, 16, 18, 17], errors: [2.0, 1.8, null, null, 1.6, 1.5, 1.6, 1.4, 1.3, 1.2, 1.3, 1.1, 1.0, 0.9] },
+];
+const latency = [182, 176, 190, 240, 178, 184, 171, 169, 175, 260, 181, 177, 174, 172, 179, 185, 176, 173];
+export default function App() {
+  const [slow, setSlow] = React.useState(undefined);
+  React.useEffect(() => { const t = setTimeout(() => setSlow([4, 6, 5, 8, 7, 9, 12, 11, 13, 12]), 2600); return () => clearTimeout(t); }, []);
+  return (
+    <div className="sp">
+      <section>
+        <h3>Beside a number</h3>
+        <div className="row"><span className="big">1,400</span><Sparkline data={signups} x="day" y="signups" tone="data" width={120} aria-label="Signups, last 30 days" /></div>
+        <p className="note">Signups, last 30 days. Up 17% from 1,200.</p>
+      </section>
+      <section>
+        <h3>In running text</h3>
+        <p>p95 latency <Sparkline data={latency} band={[160, 200]} format={(ms) => `${ms} ms`} aria-label="p95 latency, last 18 hours" /> spiked twice outside its normal range.</p>
+        <p>Deploys this week <Sparkline data={[3, 5, 2, 6, 4, 0, 1]} kind="bar" aria-label="Deploys per day" /> peaked on Thursday.</p>
+        <p className="note">Loading: <Sparkline data={slow} aria-label="Queue depth" /></p>
+      </section>
+      <section style={{ gridColumn: '1 / -1' }}>
+        <h3 id="sp-teams">In a table</h3>
+        <DataTable aria-labelledby="sp-teams" getRowId={(r) => r.id} rows={teams} columns={[
+          { key: 'name', header: 'Team' },
+          { key: 'builds', header: 'Builds per day', cell: (r) => <span className="row">{r.builds[r.builds.length - 1]}<Sparkline data={r.builds} decorative /></span> },
+          { key: 'errors', header: 'Error rate, 14 days', cell: (r) => {
+            const rising = r.errors[r.errors.length - 1] > r.errors[0] * 1.5;
+            return <span className="row">{r.errors[r.errors.length - 1]}%<Sparkline data={r.errors} tone={rising ? 'critical' : 'neutral'} format={(v) => `${v}%`} aria-label={`${r.name} error rate`} />{rising && <Badge tone="critical">Rising</Badge>}</span>;
+          } },
+        ]} />
+      </section>
+    </div>
+  );
+}
+```
+<!-- /example -->

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

@@ -24,3 +24,42 @@ One action with its alternatives: "Save changes ▾" (Save as draft, Save and cl
 - Do mark a destructive alternative with `tone: 'critical'`.
 - Don't hide the default inside the menu, or offer only one alternative (use two buttons).
 - Don't nest a SplitButton in a `Toolbar`; its tools are ghosts.
+
+<!-- example: generated from build/previews.txt by build/previews.mjs. Edit the preview, not this section. -->
+## Example
+
+`SplitButton` as first used in its preview:
+
+```tsx
+import { SplitButton } from 'altitude-design';
+
+<SplitButton label="Save changes" menuLabel="More save options" onClick={() => setSaid('Saved.')}
+  items={[{ label: 'Save as draft', onSelect: () => setSaid('Saved as a draft.') }, { label: 'Save and close', onSelect: () => setSaid('Saved and closed.') }]} />
+```
+
+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 { SplitButton } from 'altitude-design';
+
+export default function App() {
+  const [said, setSaid] = React.useState('');
+  const [deploying, setDeploying] = React.useState(false);
+  const deploy = (where) => { setSaid(`Deploying to ${where}…`); setDeploying(true); setTimeout(() => { setDeploying(false); setSaid(`Deployed to ${where}.`); }, 1600); };
+  return (
+    <div className="col">
+      <div className="row">
+        <SplitButton label="Save changes" menuLabel="More save options" onClick={() => setSaid('Saved.')}
+          items={[{ label: 'Save as draft', onSelect: () => setSaid('Saved as a draft.') }, { label: 'Save and close', onSelect: () => setSaid('Saved and closed.') }]} />
+        <SplitButton variant="secondary" label="Merge" menuLabel="More merge options" onClick={() => setSaid('Merged.')}
+          items={[{ label: 'Squash and merge', onSelect: () => setSaid('Squashed and merged.') }, { label: 'Rebase and merge', onSelect: () => setSaid('Rebased and merged.') }]} />
+        <SplitButton variant="secondary" label="Deploy" menuLabel="More deploy options" loading={deploying} onClick={() => deploy('staging')}
+          items={[{ label: 'Deploy to staging', onSelect: () => deploy('staging') }, { label: 'Deploy to production', onSelect: () => deploy('production'), tone: 'critical' }]} />
+      </div>
+      <p className="cap" role="status">{said || 'Each face lifts on its own. Alt+Down on an action opens its menu. While Deploy is loading, its chevron still works.'}</p>
+    </div>
+  );
+}
+```
+<!-- /example -->

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

@@ -29,3 +29,64 @@ The tile at the top of a dashboard: a label, a big number, how it changed and ag
 - Do lead a dashboard with stats, then the charts that explain them, then the table that is the record.
 - Don't use `size="hero"` more than once in a view.
 - Don't animate the number counting up, or colour the value itself: colour belongs to the change, and only with `good`.
+
+<!-- example: generated from build/previews.txt by build/previews.mjs. Edit the preview, not this section. -->
+## Example
+
+`Stat` as first used in its preview:
+
+```tsx
+import { Stat } from 'altitude-design';
+
+<Stat label="Monthly recurring revenue" size="hero" value={mrr} format={usd.format} good="up"
+  change={{ value: 0.042, vs: 'September', previous: 176800 }} help="Paid plans only, before refunds." />
+```
+
+The full preview, as rendered in Storybook and checked in CI (`st`, `st-bar` are the preview page's own layout classes, not Altitude's):
+
+```tsx
+import * as React from 'react';
+import { Button, Card, CardContent, Sparkline, Stat, StatGroup } from 'altitude-design';
+
+const stDays = (vals) => vals.map((v, i) => ({ day: `2026-10-${String(i + 1).padStart(2, '0')}`, v }));
+const active = stDays([11.2, 11.4, 11.3, 11.6, 11.5, 11.8, 11.9, 12.0, 11.9, 12.1, 12.2, 12.4, 12.3, 12.48].map((k) => k * 1000));
+const errors = stDays([0.8, 0.9, 0.8, 1.0, 1.1, 1.0, 1.2, 1.3, 1.2, 1.4, 1.5, 1.4, 1.6, 1.7]);
+const usd = new Intl.NumberFormat('en', { style: 'currency', currency: 'USD', maximumFractionDigits: 0 });
+export default function App() {
+  const [n, setN] = React.useState(0);
+  const [mrr, setMrr] = React.useState(undefined);
+  React.useEffect(() => { const t = setTimeout(() => setMrr(184200), 2400); return () => clearTimeout(t); }, []);
+  const users = 12480 + n * 312;
+  return (
+    <div className="st">
+      <Card>
+        <CardContent>
+          <Stat label="Monthly recurring revenue" size="hero" value={mrr} format={usd.format} good="up"
+            change={{ value: 0.042, vs: 'September', previous: 176800 }} help="Paid plans only, before refunds." />
+        </CardContent>
+      </Card>
+      <div className="st-bar">
+        <h3>Last 30 days</h3>
+        <Button variant="secondary" size="sm" onClick={() => setN((k) => k + 1)}>Refresh</Button>
+      </div>
+      <StatGroup aria-label="Last 30 days">
+        <Card><CardContent>
+          <Stat label="Active users" value={users} live good="up" change={{ value: users / 11556 - 1, vs: 'last month', previous: 11556 }}
+            trend={<Sparkline data={active} x="day" y="v" decorative width={72} />} />
+        </CardContent></Card>
+        <Card><CardContent>
+          <Stat label="Error rate" value={1.7 + n * 0.1} format={(v) => `${v.toFixed(1)}%`} good="down" change={{ value: 0.21 + n * 0.07, vs: 'last month' }}
+            trend={<Sparkline data={errors} x="day" y="v" tone="critical" decorative width={72} />} />
+        </CardContent></Card>
+        <Card><CardContent>
+          <Stat label="Median response" value={182 - n * 4} format={(v) => `${v} ms`} change={{ value: -12 - n * 4, vs: 'last week', format: (m) => `${m} ms` }} />
+        </CardContent></Card>
+        <Card><CardContent>
+          <Stat label="Refunds" value={null} help="No refunds this period." />
+        </CardContent></Card>
+      </StatGroup>
+    </div>
+  );
+}
+```
+<!-- /example -->

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

@@ -27,3 +27,64 @@ Connectors between steps are `accent` behind you and `line-control` ahead.
 
 - Do keep it to three to six steps; more than that is a list, not a staircase.
 - Don't use it for places people move between freely; that's Tabs, or Drilldown for a hierarchy.
+
+<!-- example: generated from build/previews.txt by build/previews.mjs. Edit the preview, not this section. -->
+## Example
+
+`Stepper` as first used in its preview:
+
+```tsx
+import { Stepper } from 'altitude-design';
+
+<Stepper
+  steps={steps}
+  current={at}
+  onStepChange={setAt}
+  orientation="auto"
+  aria-label="Workspace setup"
+/>
+```
+
+The full preview, as rendered in Storybook and checked in CI (`wrap`, `row`, `cap`, `pair` are the preview page's own layout classes, not Altitude's):
+
+```tsx
+import * as React from 'react';
+import { Button, Stepper } from 'altitude-design';
+
+const steps = [{ title: "Account" }, { title: "Workspace" }, { title: "Invite team" }, { title: "Billing" }, { title: "Launch" }];
+const setup = [
+  { title: "Connect repository", description: "github.com/acme/northwind" },
+  { title: "Configure build", description: "Framework, output directory, env" },
+  { title: "Deploy", description: "First production deployment" }
+];
+export default function App() {
+  const [at, setAt] = React.useState(2);
+  return <div className="wrap">
+  <Stepper
+    steps={steps}
+    current={at}
+    onStepChange={setAt}
+    orientation="auto"
+    aria-label="Workspace setup"
+  />
+  <div className="row">
+    <Button variant="ghost" disabled={at === 0} onClick={() => setAt(at - 1)}>
+      Back
+    </Button>
+    <Button variant="primary" disabled={at === steps.length} onClick={() => setAt(at + 1)}>
+      {at >= steps.length - 1 ? "Finish" : "Continue"}
+    </Button>
+    <span className="cap">
+      Continue presses the current step into the record and raises the next one; click a completed step to go back.
+    </span>
+  </div>
+  <div className="pair">
+    <Stepper steps={setup} current={1} orientation="vertical" aria-label="Deployment setup" />
+    <p className="cap">
+      Vertical: the same plates, stacked. Completed steps are flush and checked, the current one stands on its wall, and steps to come are imprints.
+    </p>
+  </div>
+</div>;
+}
+```
+<!-- /example -->

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

@@ -27,3 +27,61 @@ Prompts to start from or follow up with. An empty conversation offers starting p
 - Do keep them short, and few (three is plenty).
 - Do use `fill` when the person will likely want to adjust the prompt.
 - Don't make a suggestion the primary button, or animate follow-ups in with a rise.
+
+<!-- example: generated from build/previews.txt by build/previews.mjs. Edit the preview, not this section. -->
+## Example
+
+`Suggestions` as first used in its preview:
+
+```tsx
+import { Suggestion, Suggestions } from 'altitude-design';
+
+<Suggestions aria-label="Start with" onChoose={setDraft}>
+  <Suggestion>Summarise last week's incidents</Suggestion>
+  <Suggestion>Draft a release note</Suggestion>
+  <Suggestion value="Which of my open pull requests are blocked, and by whom?">What's blocked?</Suggestion>
+</Suggestions>
+```
+
+The full preview, as rendered in Storybook and checked in CI (`sg`, `col`, `lbl` are the preview page's own layout classes, not Altitude's):
+
+```tsx
+import * as React from 'react';
+import { EmptyState, Message, MessageContent, PromptInput, PromptInputSubmit, PromptInputTextarea, PromptInputToolbar, Suggestion, Suggestions } from 'altitude-design';
+
+export default function App() {
+  const [draft, setDraft] = React.useState('');
+  const [sent, setSent] = React.useState([]);
+  return (
+    <div className="sg">
+      <div className="col">
+        <p className="lbl">Starters in an empty conversation (fill the composer)</p>
+        <EmptyState title="Ask about this workspace" description="Pick a starting point, or write your own." size="sm">
+          <Suggestions aria-label="Start with" onChoose={setDraft}>
+            <Suggestion>Summarise last week's incidents</Suggestion>
+            <Suggestion>Draft a release note</Suggestion>
+            <Suggestion value="Which of my open pull requests are blocked, and by whom?">What's blocked?</Suggestion>
+          </Suggestions>
+        </EmptyState>
+        <PromptInput onSubmit={({ text }) => { setSent((s) => [...s, text]); setDraft(''); }} value={draft} onValueChange={setDraft}>
+          <PromptInputTextarea placeholder="Ask anything" />
+          <PromptInputToolbar><PromptInputSubmit /></PromptInputToolbar>
+        </PromptInput>
+      </div>
+      <div className="col">
+        <p className="lbl">Follow-ups under an answer (send at once)</p>
+        <Message from="assistant">
+          <MessageContent>Revenue grew 12% in Q3, led by the annual plan. Churn held at 2.1%.</MessageContent>
+          <Suggestions aria-label="Suggested follow-ups" mode="send" onChoose={(t) => setSent((s) => [...s, t])}>
+            <Suggestion>Compare with Q2</Suggestion>
+            <Suggestion>Make it shorter</Suggestion>
+            <Suggestion value="List the three biggest risks, with owners">Biggest risks</Suggestion>
+          </Suggestions>
+        </Message>
+        {sent.length > 0 && <p className="lbl">Sent: {sent[sent.length - 1]}</p>}
+      </div>
+    </div>
+  );
+}
+```
+<!-- /example -->

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

@@ -18,3 +18,31 @@ The primitive every component is built from: a box placed on one rung of the ele
 - Do use Surface for one-off panels, sidebars and app chrome so they share the ladder with the components.
 - Don't set `interactive` on something that doesn't act when clicked: a lift is a promise.
 - Don't stack more than three levels in one region; if you need a fourth, the layout probably wants a dialog or a page.
+
+<!-- example: generated from build/previews.txt by build/previews.mjs. Edit the preview, not this section. -->
+## Example
+
+`Surface` as first used in its preview:
+
+```tsx
+import { Surface } from 'altitude-design';
+
+<Surface level={-1} className="s"><b>level={'{-1}'}</b><span>A well. Holds things; never lifts.</span></Surface>
+```
+
+The full preview, as rendered in Storybook and checked in CI (`grid`, `s` are the preview page's own layout classes, not Altitude's):
+
+```tsx
+import { Surface } from 'altitude-design';
+
+export default function App() {
+  return (
+    <div className="grid" data-tells-ignore="LA4 the three surfaces side by side, to compare">
+      <Surface level={-1} className="s"><b>level={'{-1}'}</b><span>A well. Holds things; never lifts.</span></Surface>
+      <Surface level={1} className="s"><b>level={'{1}'}</b><span>Static grouping. Doesn't react to the pointer.</span></Surface>
+      <Surface level={1} interactive className="s" onClick={() => {}}><b>level={'{1}'} interactive</b><span>Hover: climbs to 2. Press: drops to ground.</span></Surface>
+    </div>
+  );
+}
+```
+<!-- /example -->

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

@@ -7,3 +7,32 @@ The track is level −2 (`surface-trench`, `trench`). Turning it on pours the `a
 **You provide:** `label` (or `aria-label`), and `checked`/`onCheckedChange` or `defaultChecked`. It renders `role="switch"`.
 
 - Do use it only for changes that apply instantly. If the change needs a Save, use a Checkbox.
+
+<!-- example: generated from build/previews.txt by build/previews.mjs. Edit the preview, not this section. -->
+## Example
+
+`Switch` as first used in its preview:
+
+```tsx
+import { Switch } from 'altitude-design';
+
+<Switch label="Sync across devices" defaultChecked />
+```
+
+The full preview, as rendered in Storybook and checked in CI (`col`, `cap` are the preview page's own layout classes, not Altitude's):
+
+```tsx
+import { Switch } from 'altitude-design';
+
+export default function App() {
+  return (
+    <div className="col">
+      <Switch label="Sync across devices" defaultChecked />
+      <Switch label="Email me when someone comments" />
+      <Switch label="Disabled" disabled />
+      <p className="cap">Hold the pointer down: the thumb stretches before it travels.</p>
+    </div>
+  );
+}
+```
+<!-- /example -->

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

@@ -22,3 +22,57 @@ One honest answer to "is my work saved?", for autosaving editors, optimistic UIs
 - Do count what's waiting when offline.
 - Don't put a spinner beside it; the pulsing lamp and the word say it.
 - Don't raise the plate to get attention when a sync fails; the lamp and the words change.
+
+<!-- example: generated from build/previews.txt by build/previews.mjs. Edit the preview, not this section. -->
+## Example
+
+`SyncIndicator` as first used in its preview:
+
+```tsx
+import { Surface, SyncIndicator } from 'altitude-design';
+
+<SyncIndicator state={state} pending={waiting.length} lastSyncedAt={at} conflicts={1} onRetry={() => { setState('saving'); setTimeout(() => { setState('saved'); setAt(new Date()); }, 700); }}
+  onOpenConflicts={() => setState('saved')}
+  queue={waiting.length ? waiting.map((w, i) => <Surface key={i} status="pending" className="change">{w}</Surface>) : undefined} />
+```
+
+The full preview, as rendered in Storybook and checked in CI (`si`, `bar`, `change`, `col`, `cap` are the preview page's own layout classes, not Altitude's):
+
+```tsx
+import * as React from 'react';
+import { Button, Surface, Switch, SyncIndicator, Textarea } from 'altitude-design';
+
+export default function App() {
+  const [text, setText] = React.useState('Q4 goals: grow self-serve revenue 20% and halve time to first value.');
+  const [state, setState] = React.useState('saved');
+  const [at, setAt] = React.useState(() => new Date(Date.now() - 120000));
+  const [offline, setOffline] = React.useState(false);
+  const [waiting, setWaiting] = React.useState([]);
+  const timer = React.useRef();
+  const edit = (v) => {
+    setText(v);
+    if (offline) { setWaiting((w) => [...w.slice(-2), 'Edited the goals paragraph']); setState('offline'); return; }
+    setState('saving'); clearTimeout(timer.current);
+    timer.current = setTimeout(() => { setState('saved'); setAt(new Date()); }, 700);
+  };
+  return (
+    <div className="si">
+      <div>
+        <div className="bar"><span>Q4 planning</span>
+          <SyncIndicator state={state} pending={waiting.length} lastSyncedAt={at} conflicts={1} onRetry={() => { setState('saving'); setTimeout(() => { setState('saved'); setAt(new Date()); }, 700); }}
+            onOpenConflicts={() => setState('saved')}
+            queue={waiting.length ? waiting.map((w, i) => <Surface key={i} status="pending" className="change">{w}</Surface>) : undefined} />
+        </div>
+        <Textarea value={text} onChange={(e) => edit(e.target.value)} aria-label="Q4 goals" />
+      </div>
+      <div className="col">
+        <Switch label="Offline" checked={offline} onCheckedChange={(on) => { setOffline(on); if (!on) { setWaiting([]); setState('saving'); setTimeout(() => { setState('saved'); setAt(new Date()); }, 700); } }} />
+        <Button size="sm" onClick={() => setState('failed')}>Make a save fail</Button>
+        <Button size="sm" onClick={() => setState('conflict')}>Cause a conflict</Button>
+        <p className="cap">Type to save. Go offline and the plate counts what's waiting; press it to see those changes, each hovering until it lands.</p>
+      </div>
+    </div>
+  );
+}
+```
+<!-- /example -->

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

@@ -74,3 +74,65 @@ To bulk-act on a filtered set larger than a page ("Archive all 2,341 inactive us
 
 `selected` and `onSelectedChange` keep working for selections of loaded rows. Report each record's outcome of a long bulk action in place (`RemovalReceipt`'s reading) and in a toast.
 
+<!-- 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 (`col`, `filter`, `cap` are the preview page's own layout classes, not Altitude's):
+
+```tsx
+import * as React from 'react';
+import { Badge, Button, DataTable, Input } from 'altitude-design';
+
+const data = [
+  { id: "nw", name: "Northwind", env: "Production", owner: "Mara Quist", updated: 2, req: 1240 },
+  { id: "bc", name: "Beacon", env: "Preview", owner: "Jon Reyes", updated: 5, req: 312 },
+  { id: "ci", name: "Cinder", env: "Production", owner: "Lena Park", updated: 26, req: 5906 },
+  { id: "dl", name: "Delta", env: "Staging", owner: "Sam Okafor", updated: 49, req: 88 },
+  { id: "em", name: "Ember", env: "Production", owner: "Ivy Chen", updated: 70, req: 2410 },
+  { id: "fb", name: "Fable", env: "Preview", owner: "Ada Obi", updated: 96, req: 19 },
+  { id: "gn", name: "Garnet", env: "Staging", owner: "Theo Marsh", updated: 120, req: 640 },
+  { id: "hb", name: "Harbor", env: "Production", owner: "Noa Levi", updated: 168, req: 3120 }
+];
+const tone = { Production: "positive", Preview: "accent", Staging: "neutral" };
+export default function App() {
+  const [rows, setRows] = React.useState(data);
+  const [q, setQ] = React.useState("");
+  const [opened, setOpened] = React.useState(null);
+  return <div className="col" style={{ gap: 8 }}>
+  <DataTable
+    aria-label="Projects"
+    rows={rows}
+    onReorder={setRows}
+    getRowId={(r) => r.id}
+    getRowLabel={(r) => r.name}
+    selectable={true}
+    defaultSelected={["bc", "ci"]}
+    maxHeight={300}
+    onRowClick={(r) => setOpened(r.name)}
+    relevance={(r) => q ? r.name.toLowerCase().includes(q.toLowerCase()) || r.owner.toLowerCase().includes(q.toLowerCase()) ? "match" : "miss" : void 0}
+    actions={() => <Button size="sm">Archive</Button>}
+    columnsMenu={true}
+    toolbar={<div className="filter">
+      <Input
+        size="sm"
+        placeholder="Filter in place"
+        value={q}
+        onChange={(e) => setQ(e.target.value)}
+        aria-label="Filter projects"
+      />
+    </div>}
+    columns={[
+        { key: "name", header: "Project", sortValue: (r) => r.name },
+        { key: "env", header: "Environment", cell: (r) => <Badge tone={tone[r.env]}>{r.env}</Badge>, sortValue: (r) => r.env },
+        { key: "owner", header: "Owner", sortValue: (r) => r.owner },
+        { key: "updated", header: "Updated", align: "end", sortValue: (r) => r.updated, cell: (r) => r.updated < 24 ? r.updated + "h ago" : Math.round(r.updated / 24) + "d ago" },
+        { key: "req", header: "Requests", align: "end", sortValue: (r) => r.req, cell: (r) => r.req.toLocaleString("en-US") }
+      ]}
+  />
+  <p className="cap">
+    {opened ? `Opened ${opened}.` : "Sort a column: rows travel to their places. Filter: matches rise, misses sink. Drag a handle, or focus it and press Space, then the arrow keys. Columns shows, hides and reorders columns, and sets the row density."}
+  </p>
+</div>;
+}
+```
+<!-- /example -->

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

@@ -16,3 +16,58 @@ Arrow keys, Home and End move between tabs in both.
 - Don't use tabs for sequential steps; they imply the views are peers.
 
 `TabsContent` takes `forceMount` to keep an unchosen panel mounted (inert, hidden from assistive technology, `data-state="inactive"`), for views that hold state or cross-fade, as a chart's Chart | Table views do.
+
+<!-- example: generated from build/previews.txt by build/previews.mjs. Edit the preview, not this section. -->
+## Example
+
+`Tabs` as first used in its preview:
+
+```tsx
+import { Tabs, TabsContent, TabsList, TabsTrigger } from 'altitude-design';
+
+<Tabs defaultValue="overview">
+  <TabsList aria-label="Project">
+    <TabsTrigger value="overview">Overview</TabsTrigger>
+    <TabsTrigger value="activity">Activity</TabsTrigger>
+    <TabsTrigger value="settings">Settings</TabsTrigger>
+    <TabsTrigger value="members">Members</TabsTrigger>
+  </TabsList>
+  <TabsContent value="overview"><p className="body">Three deployments this week. Everything is healthy.</p></TabsContent>
+  <TabsContent value="activity"><p className="body">Mara merged “Faster cold starts” 2 hours ago.</p></TabsContent>
+  <TabsContent value="settings"><p className="body">Region, domains and environment variables.</p></TabsContent>
+  <TabsContent value="members"><p className="body">Six people have access to this project.</p></TabsContent>
+</Tabs>
+```
+
+The full preview, as rendered in Storybook and checked in CI (`stack`, `body` are the preview page's own layout classes, not Altitude's):
+
+```tsx
+import { Tabs, TabsContent, TabsList, TabsTrigger } from 'altitude-design';
+
+export default function App() {
+  return (
+    <div className="stack">
+      <Tabs defaultValue="overview">
+        <TabsList aria-label="Project">
+          <TabsTrigger value="overview">Overview</TabsTrigger>
+          <TabsTrigger value="activity">Activity</TabsTrigger>
+          <TabsTrigger value="settings">Settings</TabsTrigger>
+          <TabsTrigger value="members">Members</TabsTrigger>
+        </TabsList>
+        <TabsContent value="overview"><p className="body">Three deployments this week. Everything is healthy.</p></TabsContent>
+        <TabsContent value="activity"><p className="body">Mara merged “Faster cold starts” 2 hours ago.</p></TabsContent>
+        <TabsContent value="settings"><p className="body">Region, domains and environment variables.</p></TabsContent>
+        <TabsContent value="members"><p className="body">Six people have access to this project.</p></TabsContent>
+      </Tabs>
+      <Tabs defaultValue="week" variant="segmented">
+        <TabsList aria-label="Range">
+          <TabsTrigger value="day">Day</TabsTrigger>
+          <TabsTrigger value="week">Week</TabsTrigger>
+          <TabsTrigger value="month">Month</TabsTrigger>
+        </TabsList>
+      </Tabs>
+    </div>
+  );
+}
+```
+<!-- /example -->