cssints 0.18.0 → 0.20.0

package/docs/API.md

@@ -1465,6 +1465,42 @@ createTable(options: {
 
 Selection is over ids, so it survives the host's re-sort. `rowProps` carries `aria-selected` and a click that selects; `toggleRow` / `toggleAll` are the programmatic path, and the row's checkbox stops its click from reaching the row so the two controls never toggle the same row twice. `selectAllProps` and `rowCheckboxProps` are `undefined` unless `selection` is `"multiple"` (one control over one selection is meaningless), and the select-all is a `role="checkbox"` rather than a native `input` because the mixed state a screen reader must hear is `aria-checked="mixed"`, not the DOM-only `indeterminate` property. It toggles the rows the table renders: a windowed table toggles its window and keeps the rest of the selection. A table that renders all of its rows and columns carries no `aria-rowcount` / `aria-colcount` (the markup already says it); pass them, and every cell gets its `aria-colindex`, only when the host windows. `numeric` is a layout hint for the host's skin: HTML has no attribute for it.
 
+### Headless: `createTabs` (`@cssints/headless`)
+
+The APG tablist as state and attribute objects: roving tabindex, wrapping arrows, Home/End, automatic or manual activation, disabled tabs, and a selection that is a request (`value` + `onValueChange`) or uncontrolled (`defaultSelected`). `packages/apg-specs/specs/apg/tabs.qnt` is its model; `packages/headless/test/tabs.browser.test.tsx` replays it in Chromium.
+
+Its accessibility requirements are catalogued, gap by gap, in `packages/headless/docs/requirements/tabs.md` (the model is `packages/headless/docs/requirements/README.md`).
+
+Close and rename are an **extension** (bean `cssints-gdv2`, the docs playground's file tabs), off by default so the plain tabs are untouched. The primitive owns no list: it asks (`onClose`, `onRename`), the host removes or renames. `packages/headless/test/tabs-close.browser.test.tsx` is their oracle.
+
+```ts skip
+createTabs(options?: {
+  ...; // the plain tabs: items, value, defaultSelected, orientation, activation, disabled, focusablePanels, id, onValueChange
+  closable?: boolean; // false: closeProps and the Delete key; the host removes from onClose
+  renamable?: boolean; // false: a double click edits the label inline; the host renames from onRename
+  label?(index: number): string | undefined; // the tab's name: the buttons' labels and the rename draft
+  onClose?(index: number): void; // a request: the host removes the tab and may ignore it
+  onRename?(index: number, label: string): void; // a request with a non-empty label
+}): {
+  ...;
+  editing(): number | null; // the tab being renamed inline
+  focusAfterClose(index: number): number; // the tab to focus once the removal landed
+  closeProps(index): { "aria-label": string; tabindex: -1; onClick: () => void };
+  renameProps(index): {
+    onDblClick: () => void;
+    editing(): boolean;
+    begin(index: number): void;
+    commit(label: string): void;
+    cancel(): void;
+    inputProps: { type: "text"; value; "aria-label"; onInput; onKeyDown; onBlur };
+  };
+};
+```
+
+- **Close.** `closeProps(index)` is the tab's close button: `aria-label="Close <label>"` and `tabindex=-1`, because a tablist's tab stops are its tabs; the keyboard path is Delete on the focused tab. Focus after a close goes to the tab that slid into the closed one's place, or to the previous tab when the last one closed: `focusAfterClose(index)` names that index in the shortened list (call it before the host removes the tab). Closing the last remaining tab is refused, as the spec refuses an empty tablist; a closed tab that was selected asks for the tab that takes the focus.
+- **Rename.** A double click begins; the tab renders `inputProps` instead of its label. Enter commits, Escape reverts, blur commits, and a label that trims to nothing cancels. While editing, the input owns the keys: the tablist's roving does not move. `begin(index)` is the programmatic start, for a tab the host has just added (append it, then `focusTab(index)` and `begin(index)`).
+- **The host's list.** `items` is read from the option on every read, so the bounds, the roving tab stop and `firstEnabled` follow a host that shrinks its list. `label` is read lazily too, so a renamed tab renames its buttons with it.
+- The spec models a `deletable` flavour (Delete, focus to the next tab, the last refused) but neither a rename nor the callbacks, so the browser test, not the model, holds the extension.
 
 ### Headless: `createHotkeys` (`@cssints/headless`)
 
@@ -1488,7 +1524,6 @@ hotkeys.dispose(); // unbinds all and removes the document listener; a later bin
 
 There is one `keydown` listener on the document in the capture phase, added when the first binding is bound and removed when the last is unbound or on `dispose`. The most recently bound match is the only one that fires, so a modal's `/` shadows the page's and unbinding it brings the page's back; a binding whose `when` returns false falls through to the next match instead of blocking it. By default a binding does not fire while the focus is in an `input`, a `textarea` or a `contenteditable` (an inherited one included) unless it sets `allowInEditable`. An unknown modifier or a chord with no key throws a `TypeError` at `bind`.
 
-
 ### Headless: `createScrollspy` (`@cssints/headless`)
 
 A table of contents whose current entry is the last heading to reach the top of the scrollport, marked `aria-current="location"` on the link. **No APG pattern exists for a scrollspy**, so it has no Quint spec and no ported scenarios: the contract is WAI-ARIA (the `aria-current` value, `role="list"` / `role="listitem"`, a named navigation landmark) and HTML, and `packages/headless/test/scrollspy.browser.test.tsx` is its oracle.
@@ -1513,6 +1548,48 @@ createScrollspy(options: {
 
 f812d87e (headless: a data table with sortable headers and row selection)
 
+### Headless: `createCommandPalette` (`@cssints/headless`)
+
+The first **composition**, not a new primitive and not a new spec: `createDialogModal` + `createTextInput` + `createStatus` wired into a palette. Its oracle is `packages/headless/test/command-palette.browser.test.tsx`. A palette is a dialog, **not a combobox**: choosing a row runs a command, so the field is `input[type=text][role=searchbox]` (no `aria-autocomplete`, no `aria-haspopup`), the container is `role=dialog` and the list is a `role=listbox`.
+
+```ts skip
+createCommandPalette(options: {
+  commands: ReadonlyArray<{
+    id: string;
+    label: string;
+    group?: string | undefined; // the heading the host renders
+    keywords?: ReadonlyArray<string> | undefined; // also matched
+    run(): void | Promise<void>;
+  }>;
+  open?: boolean | undefined; // controlled: the host owns the open state
+  onOpenChange?(open: boolean): void;
+  hotkey?: string | undefined; // the chord attach() binds; "mod+k"
+  labels?: Partial<{
+    title: string; // "Command palette"
+    placeholder: string; // "Type a command"
+    empty: string; // "No commands found"
+    results(count: number): string; // "4 commands"
+  }> | undefined;
+}): {
+  open(): boolean;
+  openPalette(): void;
+  closePalette(): void;
+  query(): string;
+  setQuery(text: string): void;
+  active(): number; // index into results(); -1 = the field holds the highlight
+  setActive(index: number): void;
+  results(): ReadonlyArray<{ id: string; label: string; group: string | undefined }>;
+  labels: { title: string; placeholder: string; empty: string; results(count: number): string };
+  status(): string | undefined; // the count, in the polite region
+  // inputProps, listProps, optionProps(id), emptyProps, statusProps,
+  // dialogProps, backdropProps and titleProps: the attribute objects.
+  runActive(): void | Promise<void>;
+  attach(): () => void; // binds the hotkey on the document; returns the teardown
+};
+```
+
+Focus stays in the field and `aria-activedescendant` names the highlighted option: ↓ on the last and ↑ on the first return the highlight to the field, and ↓/↑ from there re-enter at the first/last row. Home/End move the caret while the field has text and are list keys only while it is empty. Enter runs the highlight, Escape closes through the dialog, Tab is not intercepted. Filtering is a plain case-insensitive substring match over `label` and `keywords` — no fuzzy scoring, because a palette is short and ranking (recents, scopes) is the host's policy. `results()` keeps host order; `group` is what the host groups by; `emptyProps.hidden` and `labels.empty` are the empty state; the count is written to `statusProps` once per query, not on every arrow. The query and highlight reset on close, focus returns to the element that had it, and `runActive()` closes before `run()` so a command may open its own UI. Host's: rendering, grouping and CSS; async commands and their errors; every visible string via `labels`; any close other than Escape or a command. The filterable menu and the date picker are later compositions on the same research.
+
 ### Headless: `createPanZoom` (`@cssints/headless`)
 
 **No APG pattern exists for pan-zoom**, so there is no Quint spec and no ported scenarios: `packages/headless/test/panzoom.browser.test.tsx`, a real Chromium viewport, is its oracle. The accessible contract is the three parts it returns: a focusable viewport (`role=group`, `tabindex=0`, `aria-roledescription="zoomable image"`, `aria-describedby` the value), keyboard operations that stand in for every gesture, and a polite live value. The pointer — drag to pan, two pointers to pinch, a double click to reset — is an addition, never the only way in. It is not `createCanvas`: that is a camera over an infinite world, this is one image fitted to a box.
@@ -1559,6 +1636,291 @@ Wheel zooms **only with `ctrl` / `meta`** held: the browser's pinch gesture arri
 
 The host owns the box and the look: the viewport's size and `overflow: hidden`, `touch-action: none` if a touch drag should pan, `transform-origin: 50% 50%` (the default this maths assumes), and any transition on the transform. Controlled is `scale` + `onScaleChange`; the offset has no controlled prop, so a host that ignores a scale request also gets the offset resolved for the scale it refused. Not modelled: inertia, rotation, and pinching on platforms without `PointerEvent` (the browser's own pinch is the `ctrl+wheel` path).
 
+### Headless: `createMenu` (`@cssints/headless`)
+
+The APG menu family (`createMenu` for the menu button and the checkable menus, `createMenubar` for the roving bar) as state and attribute objects. Its behaviour is `specs/apg/menu-button.qnt` and `menu-checkable.qnt`, and `packages/headless/test/menu-button.browser.test.tsx` replays the generated models, ported scenarios and seeded differential walks against it.
+
+```ts skip
+createMenu(options: {
+  items: ReadonlyArray<string | { label: string; kind?: "item" | "checkbox" | "radio"; checked?: boolean; disabled?: boolean }>;
+  variant?: "plain" | "checkbox-items" | "radio-items" | "mixed" | undefined; // "plain"
+  open?: boolean | undefined; // controlled: the host owns the open state
+  defaultOpen?: boolean; // uncontrolled starting state
+  onOpenChange?(open: boolean): void; // a request the host may ignore
+  value?: number | undefined; // controlled checked items, packed (checkboxItem0 * 5 + radioChoice, 1-based)
+  defaultValue?: number;
+  onCheckedValueChange?(value: number): void;
+  triggerMode?: "outside" | "held" | undefined; // where the focus sits while the menu is closed
+  disabled?: ReadonlyArray<number>; // focusable, never activated
+  id?: string | undefined;
+  onItemClick?(index: number): void;
+}): {
+  open(): boolean;
+  focusLevel(): 0 | 1 | 2; // 0 outside, 1 on the trigger, 2 on an item
+  focusIndex(): number;
+  openMenu(): void; // a request, like every intent
+  closeMenu(): void;
+  keyDown(key: string): void;
+  // …items, triggerProps, menuProps, itemProps(index), type(), setFocusItem()
+};
+```
+
+**The open state is a request/commit pair**, like every other controlled primitive: `open` (+ `onOpenChange`) makes the host own it, `defaultOpen` starts it. Every intent that opens or closes — the trigger's click and its keys, Escape, an item's activation, Tab, an outside click in a kit, the programmatic `openMenu` / `closeMenu` — is a request, so a host that holds `open` keeps the menu open and the focus where it was; `menu-button.qnt` reverts the whole transition of a rejected request, focus included. A write the host makes on its own is not a request: it takes the focus to the first item when it opens and to the trigger when it closes, and a write of the value it already has moves nothing (no widget can observe it).
+
+### Headless: `createCheckboxGroup` (`@cssints/headless`)
+
+The APG Checkbox pattern's tri-state group controller: exactly three child values, a controller whose `aria-checked` is derived from them (all / none / mixed) with the optional "remember the last mixed combination" cycle, checked against `specs/apg/checkbox-group.qnt`. Its name, description and error are `createField`'s contract on the `role="group"` element, which the model leaves out on purpose (its header omits labelling), so `packages/headless/test/checkbox-group.browser.test.tsx` is their oracle.
+
+```ts skip
+createCheckboxGroup(options: {
+  values: ReadonlyArray<T>; // exactly three
+  value?: ReadonlyArray<T> | undefined; // controlled checked subset
+  defaultValue?: ReadonlyArray<T>;
+  parent?: boolean; // the "all" controller is a focus stop
+  remember?: boolean; // the third activation restores the last mixed combination
+  id?: string | undefined; // base of `<id>-control` (the group element) and `<id>-error`
+  label?: string | undefined; // the group's name, as aria-label
+  labelledby?: string | undefined; // the id of the host's own label element; wins over `label`
+  describedby?: string | undefined; // host-owned description ids, after the error
+  invalid?: boolean | string | undefined; // like createField: a string is the flag and the message
+  error?: string | undefined; // the error shown; implies invalid, `invalid: false` silences it
+  onValueChange?(checked: ReadonlyArray<T>): void;
+}): {
+  invalid(): boolean;
+  error(): string | undefined; // only while invalid
+  describedIds(): readonly string[]; // the error id while shown, then describedby
+  groupProps: { id; role: "group"; "aria-label"; "aria-labelledby"; "aria-describedby"; "aria-invalid"; onKeyDown };
+  errorProps: { id; hidden; role }; // role "alert" while shown; render it always
+  // …children, parentChecked, checkedValues(), click(target), keySpace(), groupProps' onKeyDown
+};
+```
+
+The group is not a `<label for>` target: pass `labelledby` naming the host's own label element, or `label` without one. The error id is in `aria-describedby` only while the error is shown, `aria-invalid` only while the group is invalid, and the group element's own id is there for a controller that names it with `aria-controls`. The checked set is unchanged by all of this: the request/commit split and the spec stay as they were.
+
+### Headless: `createSlider` and `createSpinbutton` (`@cssints/headless`)
+
+The two number controls. Their behaviour is `packages/apg-specs/specs/apg/slider.qnt` and `spinbutton.qnt`, checked against the real DOM by the differential walk in `packages/headless/test/slider.browser.test.tsx` and `spinbutton.browser.test.tsx`. Options are plain and read lazily (a getter is fine); `value` + `onValueChange` make the widget controlled, `defaultValue` is the uncontrolled start.
+
+```ts skip
+createSlider(options?: {
+  min?: number; // 0
+  max?: number; // 10
+  step?: number; // 1
+  largeStep?: number; // 3: the jump of PageUp / PageDown
+  value?: number | undefined; // controlled; undefined = uncontrolled
+  defaultValue?: number; // 5, clamped into the range
+  orientation?: "horizontal" | "vertical"; // "horizontal"
+  direction?: "ltr" | "rtl"; // "ltr": under rtl the horizontal arrows flip
+  disabled?: boolean; // aria-disabled on the thumb; a key or rail press changes nothing
+  id?: string; // base of the thumb id
+  onValueChange?(value: number): void; // a request the host may ignore
+}): {
+  value(): number;
+  focused(): boolean;
+  setValue(value: number): void;
+  focus(): void;
+  blur(): void;
+  keyDown(key: string): boolean; // true when the key was consumed (preventDefault it)
+  pointerDown(position: number): void; // a rail press at a 0..1 fraction of the track
+  thumbProps: {
+    id;
+    role: "slider";
+    "aria-valuenow";
+    "aria-valuemin";
+    "aria-valuemax";
+    "aria-valuetext";
+    "aria-orientation";
+    "aria-disabled": "true" | undefined;
+    tabindex: 0;
+    onFocus;
+    onBlur;
+    onKeyDown;
+  };
+  trackProps: { onPointerDown };
+};
+```
+
+```ts skip
+createSpinbutton(options?: {
+  min?: number; // 1
+  max?: number; // 12
+  step?: number; // 1: the arrows and the buttons
+  largeStep?: number; // 3: PageUp / PageDown
+  value?: number | undefined; // controlled; undefined = uncontrolled
+  defaultValue?: number; // 5, clamped into the range
+  wrap?: boolean; // false: clamp at the bounds (true wraps)
+  disabled?: boolean; // aria-disabled and the native disabled; keys, typing and both steppers change nothing
+  id?: string; // base of the input and button ids
+  onValueChange?(value: number): void; // a request the host may ignore
+}): {
+  value(): number;
+  focused(): boolean;
+  editing(): boolean;
+  draft(): string;
+  displayed(): string; // the draft while editing, else the value
+  setValue(value: number): void;
+  focus(): void;
+  blur(): void; // commits a valid draft
+  keyDown(key: string): boolean;
+  typeInput(text: string): void; // replaces the draft; needs focus
+  commit(): void;
+  revert(): void;
+  increment(): void;
+  decrement(): void;
+  setWrap(wrap: boolean): void;
+  inputProps: {
+    id;
+    role: "spinbutton";
+    "aria-valuenow";
+    "aria-valuemin";
+    "aria-valuemax";
+    "aria-valuetext";
+    "aria-invalid": "true" | undefined;
+    "aria-disabled": "true" | undefined;
+    disabled: boolean; // this is an <input>: the native attribute is a form control's disabled
+    tabindex: 0;
+    value;
+    onFocus;
+    onBlur;
+    onKeyDown;
+    onInput;
+  };
+  incrementProps: { role: "button"; tabindex: -1; "aria-label"; "aria-disabled"; onMouseDown; onClick };
+  decrementProps: { role: "button"; tabindex: -1; "aria-label"; "aria-disabled"; onMouseDown; onClick };
+};
+```
+
+`disabled` is **a widget-level extension of the APG patterns**, and the specs say so: `slider.qnt` lists it under its deliberate omissions, and `spinbutton.qnt` models the steppers' at-bound state only (`DisabledOnlyAtBound`). Neither machine has a `disabled` var, so the DOM tests, not the model, hold the primitive to these rules:
+
+- a disabled slider **keeps the thumb as its tab stop** (`tabindex="0"`, the same choice `createButton` makes with `aria-disabled`) and announces `aria-disabled="true"` on the thumb; every key and every rail press is dropped before it becomes a request, so `onValueChange` never fires and `keyDown` returns `false` (nothing to preventDefault);
+- a disabled spinbutton's field announces `aria-disabled` **and carries the native `disabled`** (the field is an `<input>`, so the platform's own form-control rule applies); the spin keys, the typed draft (Enter and blur included) and both steppers change nothing, and **both** steppers announce `aria-disabled="true"` — the at-bound rule of the spec stays, and a disabled widget adds the other side;
+- both read the option on every attribute read, so a host may flip `disabled` on a mounted widget and the attributes and the guards follow in the same tick.
+
+### Headless: `createKnob` (`@cssints/headless`)
+
+A virtual knob after GarageBand's ([How Apple Designs a Virtual Knob](https://jherrm.github.io/knobs/)): spin around the centre, or slide vertically / horizontally, with one gesture locked per drag. **No APG pattern and no ARIA role exist for a dial**, so there is no Quint spec and no ported scenarios: `packages/headless/test/knob.browser.test.tsx` (real Chromium) is the oracle. The knob is a `role=slider` — the closest role WAI-ARIA has — with a polite live value; a numeric field must sit next to it, because a dial is never the only control. Options are plain and read lazily; `value` + `onValueChange` make the widget controlled.
+
+```ts skip
+createKnob(options?: {
+  min?: number; // 0
+  max?: number; // 100
+  step?: number; // 1
+  value?: number | undefined; // controlled; undefined = uncontrolled
+  defaultValue?: number; // the middle of the range, quantised to step
+  wrap?: boolean | undefined; // false: clamp at the bounds; true: continuous, past max wraps to min
+  gesture?: "spin" | "slide" | "both" | undefined; // "both": locked per drag from the first movement
+  labels?: { knob?: string | undefined } | undefined; // aria-label on the knob, "Knob" by default
+  format?: ((value: number) => string) | undefined; // aria-valuetext, String by default
+  id?: string | undefined; // base of the value region id
+  onValueChange?(value: number): void; // a request the host may ignore
+}): {
+  value(): number;
+  setValue(value: number): void; // a request
+  percentOf(value: number): number; // the rotation fraction, 0..1 (× 360 for degrees)
+  stepBy(delta: number): void; // a request
+  knobProps: {
+    role: "slider";
+    tabindex: 0;
+    "aria-valuemin";
+    "aria-valuemax";
+    "aria-valuenow";
+    "aria-valuetext";
+    "aria-label";
+    onKeyDown;
+    onPointerDown;
+    onPointerMove;
+    onPointerUp;
+    onPointerCancel;
+    onWheel;
+  };
+  valueProps: { id; role: "status"; "aria-live": "polite" };
+};
+```
+
+**Gestures.** The first movement past 6 px picks the mode once: movement that stays on one axis (the other under 35% of it) is a slide, anything else is a turn around the centre, and `gesture: "spin"` / `"slide"` disables the other. The direction is the reference's "which side you turn": a vertical slide down turns clockwise (up in value) on the right half and counter-clockwise on the left half; a horizontal slide uses the same left/right side (the reference picks top/bottom for that one). A spin's value per degree shrinks with the pointer's distance from the centre — farther is finer. `percentOf` maps the value to the fraction of a full turn for the skin; `wrap` makes the dial continuous instead of clamped.
+
+**Keyboard.** Arrows step, PageUp/PageDown move ten steps, Home/End jump to the bounds (no typing: the dial has no text entry). The wheel steps once per event and `preventDefault`s while the pointer is over the knob.
+
+### Headless: `createDropZone` (`@cssints/headless`)
+
+A file drop target. **There is no APG pattern and no Quint spec for a drop zone** — the contract is HTML's file input plus WAI-ARIA's live region — so `packages/headless/test/dropzone.browser.test.tsx` (real Chromium) is its oracle. It is the replacement for the bare `<input type="file">` fields of cms-admin's image field and kocharin's dashboard upload.
+
+```ts skip
+createDropZone(options: {
+  accept?: string | undefined; // the HTML accept grammar: ".png", "image/png", "image/*"
+  multiple?: boolean | undefined; // the input's multiple, and an accept of several files per drop
+  maxSize?: number | undefined; // bytes; a larger file is rejected with "size"
+  disabled?: boolean | undefined; // zone aria-disabled, native disabled input and button, drops ignored
+  onFiles(files: File[]): void; // the accepted files of one batch; not called when none passed
+  onReject?({ file, reason }: { file: File; reason: "type" | "size" }): void; // once per refused file
+  labels?: { zone?: string | undefined; browse?: string | undefined };
+}): {
+  dragging(): boolean; // a drag is over the zone; a child's dragleave does not clear it
+  message(): string | undefined; // "2 files, 1 rejected: too large"; undefined before the first batch
+  inputProps: {
+    id; // the id the browse button clicks
+    type: "file";
+    accept: string | undefined;
+    multiple: true | undefined;
+    disabled: true | undefined;
+    hidden: true;
+    onChange;
+  };
+  zoneProps: {
+    role: "group";
+    "aria-label": string | undefined;
+    "aria-disabled": "true" | undefined;
+    onDragEnter;
+    onDragOver;
+    onDragLeave;
+    onDrop;
+  };
+  browseProps: { type: "button"; disabled: true | undefined; "aria-disabled"; "aria-label"; onClick };
+  statusProps: { role: "status"; "aria-live": "polite"; "aria-atomic": "true" };
+};
+```
+
+Principles:
+
+- **The zone is never drag-only.** `browseProps` spreads onto a real `<button type="button">` that clicks the hidden input, so the picker is the keyboard path (Enter and Space are the platform's) and a pointer user can click too. The drop handlers add nothing the button cannot do.
+- **Validation happens once per file**, in the order type then size, with a reason the host can show: `onReject` gets the file and `"type" | "size"`, and `onFiles` gets the rest in one batch. A batch with nothing accepted calls `onFiles` not at all — not with an empty array.
+- **A folder or an empty `DataTransfer` is a no-op** (Chromium marks a dropped directory as a `file` item whose `webkitGetAsEntry().isDirectory` is true): no callback, no rejection, and `message()` keeps the previous sentence.
+- **`dragleave` counts.** A child's `dragleave` bubbles to the zone, so `dragging()` is a depth counter: it clears when the drag leaves the zone, or on a drop. It is the styling hook; the primitive writes no `data-dragging`.
+- **`message()` is a default sentence for the host's status region** ("2 files, 1 rejected: too large", `undefined` before the first batch): the primitive tracks the counts of the last batch, the host decides the words. Render `statusProps` once and keep it mounted, or a change of its text is not announced.
+- Picking through the input is the same path as a drop and clears `input.value` afterwards, so choosing the same file twice fires `change` again.
+
+### Headless: `createTimeline` (`@cssints/headless`)
+
+Two modes over one axis. Without `rows` it is the package's demo tree of five fixed spans (collapsing, a zoom window, checked against `specs/apg/timeline.qnt` by the differential walk in `packages/headless/test/timeline.browser.test.tsx`). With `rows` it is a trace waterfall: real span data laid out in percentages of the rows' own extent. The rows mode has **no APG pattern** to follow, so its contract is `packages/headless/test/timeline-rows.browser.test.tsx`.
+
+```ts skip
+createTimeline(options: {
+  rows: ReadonlyArray<{ id: string; label: string; start: number; end: number; depth?: number; status?: "ok" | "error" | "unset" }>; // in display order
+  axis?: { unit?: "ms" | "us" | "s" } | undefined; // "ms": the ruler's labels
+  selected?: string | undefined; // controlled; undefined = uncontrolled
+  onSelect?(id: string): void; // a request the host may ignore
+}): {
+  extent(): { start: number; end: number }; // min start, max end; { 0, 0 } when empty
+  depthOf(id: string): number; // 0 for a root span
+  listProps: { role: "list"; "aria-label": string };
+  rowProps(id: string): { role: "listitem"; "aria-level": number; "aria-current": "true" | undefined; "data-status"; tabindex; onClick; onKeyDown };
+  barProps(id: string): { "aria-hidden": "true"; style: { left; width; "--depth" } };
+  labelProps(id: string): { style: { "--depth" } };
+  rulerProps: { role: "presentation"; "aria-hidden": "true"; ticks: ReadonlyArray<{ value: number; left: number; label: string }> };
+  select(id: string): void;
+  selectedId(): string | undefined;
+};
+```
+
+`createTimeline()` with no `rows` keeps the tree API exactly as it was (`rows()`, `treeProps`, `rowProps`, zoom, collapse).
+
+- **Role.** A waterfall is neither a tree (nothing collapses in rows mode) nor a grid (nothing is edited), and `aria-selected` is not allowed on a `listitem`. So the rows are `role="list"` / `role="listitem"`, the depth is `aria-level` (`depth + 1`, which `listitem` supports) and the selected row is `aria-current="true"`, which any element may carry. The demo tree keeps `role="tree"` / `"treeitem"` because it does collapse.
+- **Geometry.** `extent()` is across every row, so a child span is a percentage of the whole trace: `barProps(id).style.left` / `.width` are percentages of it, and a zero-length span (`start === end`) still paints because every bar has a **0.5% width floor** — 2 px on a 400 px track, the floor the o11y dashboard used when it hand-rolled these rows. An empty extent (`{ 0, 0 }`) puts every bar at `left: 0%` with that floor rather than dividing by zero.
+- **Depth is `--depth`** on `barProps` and `labelProps`, not nested DOM: the host indents with `padding-inline-start: calc(var(--depth) * 0.75rem)`, and the bar keeps its track when the panel is narrow.
+- **Ruler.** `ticks` steps the extent by 1, 2 or 5 times a power of ten (about five ticks), each with `value` on the axis, `left` in percent and a `label` in the axis unit. The ruler element is decorative; the host renders ticks as its children.
+- **Selection.** A click selects and moves the tab stop; ArrowUp / ArrowDown / Home / End move a roving tab stop; Enter or Space selects the focused row. The host moves real DOM focus after an arrow key, as the demo fixture does; `selected` + `onSelect` make it controlled, `select(id)` is the programmatic request.
+- **`status` is `data-status`** on the row, a styling hook for the host's colour. The primitive never invents the label: the host's data holds it.
+
 ### Publishing a library (decided 2026-10-02, cssints-0l3f)
 
 A package written on cssints ships JavaScript that still has the attribute, and its `.d.ts`. The app that installs it evaluates the package with its own engine: one sheet, the app's browserslist and themes, and a token, a kernel or an `@property` of the package is made once however many modules use it. Nothing is declared: the engine recognises a file by `with { type: "cssints" }`, the same marker as in app code.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cssints",
-  "version": "0.18.0",
+  "version": "0.20.0",
   "description": "CSS in TypeScript: typed css.* calls compiled to atomic CSS at build time (a Vite plugin)",
   "license": "MIT",
   "repository": {
@@ -72,7 +72,7 @@
     }
   },
   "dependencies": {
-    "@cssints/css-grammar": "^0.18.0",
+    "@cssints/css-grammar": "^0.20.0",
     "culori": "^4.0.2",
     "effect": "4.0.6",
     "happy-dom": "^20.14.5",