altitude-design 0.3.2 → 0.4.1

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

@@ -0,0 +1,107 @@
+# DiffView
+
+What changed between two versions: version history, audit-log detail ("Plan: Pro → Business"), config changes before a deploy, and edits an AI proposes to a document or record.
+
+**Elevation.** Both versions are the record, so it lies flush on the ground with a `line` rim, as `CodeBlock` does. It has no height of its own. **Never colour alone.**
+- **Additions** are `positive-soft`, with a `+` sign and "Added" in their name (`<ins>`).
+- **Removals** are `critical-soft`, struck through, with a `−` sign and "Removed" (`<del>`).
+- **Words that changed** inside a line take a stronger tint. A removal and the addition that replaces it are paired in order, within a block of changed lines.
+- **Long unchanged runs** fold behind a lid ("6 unchanged lines"), keeping `context` lines around each change. A single unchanged line is never folded.
+- **In `mode="properties"`**, each changed field shows its old value struck through beside the new.
+
+**Restoring a version is a consequential action**, not something the diff does: follow the consequential-action pattern (a confirmation, then a receipt).
+
+**Accessibility.** A `figure` named by its caption, with a summary first ("3 additions, 2 removals", "2 properties changed"). Previous change and Next change move focus from change to change, and so do the `n` and `p` keys while focus is inside. Signs are hidden; "Added" and "Removed" are read. Under forced colours the tints are dropped, and the signs and strike-through carry the meaning. Under `contrast="more"` each changed line gets a 2px edge in its tone.
+
+**Props:** `mode` (`'text' | 'properties'`); `before`, `after` (texts, or records); `fields` (`{ key, label, format? }[]`, for properties); `context` (default 3); `caption`; `hunks` (precomputed line operations for large inputs; `diffLines(before, after)` makes them).
+
+**Reviewing a proposed change.** With `review` (text mode), each change is a labelled group ("Change 3 of 7, lines 40 to 52") raised as a proposal, with Accept and Reject; the header counts "3 of 7 changes reviewed" and offers Accept all and Reject all; n and p (or ] and [) move between undecided changes. `decisions` is yours (by id, `change-1` in order; `diffChanges` lists them), as is applying them. Accepted lands flush with one afterglow; rejected is muted and collapses to "Rejected · show" after `dur-linger`. Decisions are announced ("Change 3 accepted. 4 left."). Property diffs aren't reviewable yet.
+
+**You provide:** the two versions and a caption that names them.
+
+```tsx
+<DiffView caption="Version 4 → 5" before={v4.body} after={v5.body} context={3} />
+<DiffView mode="properties" caption="Subscription changed" before={prev} after={next} fields={[{ key: 'plan', label: 'Plan' }]} />
+```
+
+- Do say which versions are compared in the caption.
+- 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

@@ -0,0 +1,82 @@
+# DotPlot
+
+Values compared across categories where zero isn't part of the story: ten services' p95, all between 180 and 240 ms; scores by team with their spread; last quarter against this one. A `BarChart` must stand on zero, which squashes differences of a few percent into identical bars, and bars of averages carry a measured misreading: values inside the bar are judged likelier than values equally far outside it (Newman & Scholl, 2012), which dot plots reduce (Okan et al., 2018). Without this form people reach for bars and either squash the data or truncate the axis, which Altitude forbids.
+
+**Why it's flat.** The values are the record, so the dots lie on the plot as a `ScatterChart`'s do: at least 8px, a `data-*` fill (a marker shape per series when there's more than one), and a 2px ring of the plot's own colour so neighbours stay apart. Never raised, never shaded. The value is position, never height, on an axis that needn't include zero; with no zero there's no ground line, only the plot's foot, as on a `LineChart` that leaves zero off.
+
+**Rows.** Categories run down the side, as on a horizontal `BarChart`, with the same label budget. Each row has a 1px `line` guide from its label across the plot. `sort="desc"` orders the rows by value (the first series', or `to`'s), and re-sorted rows are carried to their places.
+
+**A spread.** `range={['p10', 'p90']}` draws a flat band of the series colour at 16% behind the dot, with round ends: an uncertainty band, as on a `LineChart`, never error bars, which readers misjudge (Correll & Gleicher, 2014). `rangeLabel` says what it is ("10th–90th percentile"). It joins the axis, the readout, each point's name ("Billing, p95, 236 ms. 10th–90th percentile 190 ms to 320 ms.") and a column of the table.
+
+**Before and after.** `from="q2" to="q3"` makes a dumbbell: the earlier dot hollow, the later filled, both in one colour because they're one entity at two times, joined by a 2px `ink-muted` link. The change is said in words, as `compare` says it: "Up 7.5% from Q2" in the later dot's name, a row in the readout, "Q2" and "vs Q2" columns in the table, and "Against Q2: 4 rose, 1 fell." in the summary.
+
+**Without colour.** Under forced colours the dots are `CanvasText` ringed in `Canvas` (a hollow dot is a `CanvasText` ring on `Canvas`), the spread `GrayText`, the link `CanvasText`. With `contrast="more"` the row guides are `line-control`, as gridlines are.
+
+**Motion.** The container's engine: a rescale first, then the dots, their spreads and their links glide to their new values on `ease-glide`; re-sorted rows are carried. Nothing grows in on first render. Under reduced motion values change in place.
+
+**Accessibility.** The keyboard path is one Tab stop: the summary, then the series, then the points down the rows. The generated summary names the range, the lowest and highest, and the widest spread. The readout, each point's name and the table view carry the spread and the change.
+
+**Props:** `data`, `x`; `sort`; `range`, `rangeLabel`, `rangeSeries`; `from` and `to`; `zero` (default false); `relevance` and `rescale`; `selected`, `onSelect`, `drill`; `focus`; `tooltip`; `empty`.
+
+**Selecting, drilling and filtering** work as on every chart: a mark that acts gets a 2px `ink` outline round its dots under the pointer or keyboard, never a lift; misses recede to 35% where they stand.
+
+**You provide:** a `ChartContainer` whose `config` names and formats the value (or `from` and `to`), the records, and usually a `summary` or a `takeaway` that says what the comparison means.
+
+```tsx
+<ChartContainer config={{ p95: { label: 'p95', format: (v) => `${v} ms` } }}>
+  <DotPlot data={services} x="service" range={['p10', 'p90']} rangeLabel="10th–90th percentile" sort="desc" />
+</ChartContainer>
+
+<ChartContainer config={{ q2: { label: 'Q2' }, q3: { label: 'Q3' } }}>
+  <DotPlot data={teams} x="team" from="q2" to="q3" sort="desc" />
+</ChartContainer>
+```
+
+- Do use it when the differences are a few percent of the values, or when each value is an average with a spread.
+- 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

@@ -0,0 +1,43 @@
+# Drilldown
+
+Navigates a hierarchy as a **stack**. Each place you go into is laid on top of the one before it; going back lifts sheets off the top.
+
+- Do use `Breadcrumb` for the same staircase in an app with routes; the two share one implementation.
+- **The breadcrumb is a staircase.** Every crumb is a step standing on the same ground line, so all their contact shadows line up; a deeper place is a *taller* step (its wall is 3px longer), not one floating higher. Face and wall share one hairline (`--alt-ring`), so the top edge of a white step always reads against a light page, and every step casts its contact shadow at the same ground line. The root is the lowest step and where you are now is the tallest. Every step except the current one is a button: it rises 1px when pointed at and presses down to the ground when clicked, and choosing it climbs back to that place. When you go deeper, the new step rises up out of the ground.
+- **The view sits on a pile.** One sheet shows beneath it for each level you've descended (up to three), the same language as `Pile`: depth you can see at rest.
+- **Transitions follow the stack.** Going deeper, the child is laid on top while the parent is pressed beneath it; going back, the top sheet lifts off and the parent comes up from under it. Focus moves to each new view.
+
+**You provide:** `root`, a tree of `{ id, title, description?, children?, content? }`. A node with children lists them; a leaf shows its `content`.
+
+- Use it for nested places people move through (workspace → project → environment → build).
+- 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

@@ -0,0 +1,71 @@
+# DropZone
+
+A receptacle that opens only when there's something to receive: flush at rest, sunk while a file is in flight, deeper under the pointer.
+
+At rest it's a dashed outline on the ground. As soon as files are dragged anywhere over the page it sinks into a well (armed), so every place that can take the file announces itself. Hovering it deepens it to a trench with an `accent-ink` rim and `accent-soft` fill (over). Dropped files settle in with an afterglow. Clicking, Enter or Space opens the file picker.
+
+**You provide:** `onFiles`, optional `accept` and `multiple`, the zone's content (an icon and "Drop files or browse"). `state` forces a visual state for documentation.
+
+- Don't leave drop zones armed when nothing is being dragged; an always-open well stops meaning anything.
+
+## The queue
+
+Pass `queue` and each file you're handling is a slat under the zone, named by its file and size:
+
+- **uploading** is a task, so a `Progress` fill rises out of its trench ("Uploading, 40%"), with Cancel;
+- **processing** is a write the server hasn't confirmed, so the slat **hovers as pending** ("Processing"), with Cancel;
+- **done** lands and settles with the afterglow ("Uploaded"), with Remove;
+- **failed** drops to a trench with its reason and **Retry**, and Remove.
+
+`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

@@ -0,0 +1,63 @@
+# DropdownMenu
+
+Lists actions for a trigger; one highlight glides between items, which arrive in quick sequence.
+
+The menu rises like a Popover. Items stagger in at 16ms each. A single `accent-soft` highlight (`critical-soft` on a destructive item) follows the pointer or arrow keys on `ease-settle` instead of each row blinking on and off. Arrow keys, Home and End move; Enter selects; Escape and Tab close and return focus.
+
+**On touch.** An item's `shortcut` is shown only where there's likely a keyboard: on a touch-only device it's hidden until a key is pressed in the session. The shortcut still works.
+
+**On a narrow screen.** It opens where its `side` and `align` put it, then shifts sideways to stay 8px inside the screen, and it's never wider than the screen less 16px.
+
+**As a sheet.** `presentation="auto"` (the default) opens the menu as a sheet at the bottom edge on a narrow touch screen (under 640px, with a coarse pointer), where the thumb is: full width less 8px, clear of the safe areas, a head with its `title` (default: the trigger's label) and Close, and 44px rows. It's still the menu, at level 3, with the same keyboard and roles. `"anchored"` or `"sheet"` forces one.
+
+**You provide:** `trigger` (usually a Button with a `ChevronDown` trailing icon) and `items`: actions (`label`, optional `icon`, `shortcut`, `onSelect`, `tone: 'critical'`, `disabled`), `{ type: 'separator' }` and `{ type: 'label', label }`.
+
+**Predicted items.** Mark items you expect the person to want with `predicted: true`. They appear at once; the others fade in over `dur-onset` (500ms). Nothing moves, so the menu stays learnable. In Findlater et al.'s studies this made selection faster than a static menu and than highlighting, but only when predictions were right about four times in five; misses cost a little time. Leave it off unless your predictions are that good.
+
+- 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 -->