cssints 0.18.0 → 0.19.0

package/docs/API.md

@@ -1465,6 +1465,40 @@ 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.
+
+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 +1522,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.
@@ -1559,6 +1592,185 @@ 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: `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: `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.19.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.19.0",
     "culori": "^4.0.2",
     "effect": "4.0.6",
     "happy-dom": "^20.14.5",