@cssints/headless 0.19.0 → 0.20.0

package/README.md

@@ -65,8 +65,8 @@ A primitive that has a seam honours an optional `prefs` entry (a `Partial<Prefs>
 - **menu / menubar** — `typeaheadDelayMs` (the typeahead buffer timeout).
 - **tooltip** — `tooltipShowDelayMs` / `tooltipHideDelayMs`, exposed as `showDelayMs()` / `hideDelayMs()` for the host to wire its `setTimeout` from (the spec keeps timers as events).
 
-Everything else **ignores** prefs: accordion, alert, alertdialog, breadcrumb, button, carousel, checkbox, checkbox-group, combobox, confirm, dialog-modal, disclosure, feed, field, grid, link, listbox, meter, player, popover, radio, resizable-panels, scrollspy, slider, slider-multithumb, spinbutton, switch, table, tabs, timeline, toolbar, treegrid, treeview, windowsplitter — they expose no timing / motion / live-region / camera seam. `listbox` / `treeview` / `timeline` typeahead timeouts are host-driven via their reset methods, so they take no delay here either.
-Everything else **ignores** prefs: accordion, alert, alertdialog, breadcrumb, button, carousel, checkbox, checkbox-group, combobox, confirm, dialog-modal, disclosure, feed, field, grid, link, listbox, meter, panzoom, player, popover, radio, resizable-panels, slider, slider-multithumb, spinbutton, switch, table, tabs, timeline, toolbar, treegrid, treeview, windowsplitter — they expose no timing / motion / live-region / camera seam. `listbox` / `treeview` / `timeline` typeahead timeouts are host-driven via their reset methods, so they take no delay here either.
+Everything else **ignores** prefs: accordion, alert, alertdialog, breadcrumb, button, carousel, checkbox, checkbox-group, combobox, command-palette, confirm, dialog-modal, disclosure, feed, field, grid, link, listbox, meter, player, popover, radio, resizable-panels, scrollspy, slider, slider-multithumb, spinbutton, switch, table, tabs, timeline, toolbar, treegrid, treeview, windowsplitter — they expose no timing / motion / live-region / camera seam. `listbox` / `treeview` / `timeline` typeahead timeouts are host-driven via their reset methods, so they take no delay here either.
+Everything else **ignores** prefs: accordion, alert, alertdialog, breadcrumb, button, carousel, checkbox, checkbox-group, combobox, command-palette, confirm, dialog-modal, disclosure, feed, field, grid, link, listbox, meter, panzoom, player, popover, radio, resizable-panels, slider, slider-multithumb, spinbutton, switch, table, tabs, timeline, toolbar, treegrid, treeview, windowsplitter — they expose no timing / motion / live-region / camera seam. `listbox` / `treeview` / `timeline` typeahead timeouts are host-driven via their reset methods, so they take no delay here either.
 
 `motionDurationMs` is **not consumed**: canvas tweens are tick-driven, not millisecond-driven, and the look layer owns durations. It stays in `Prefs` only so a host's preference record fits the type.
 
@@ -125,6 +125,30 @@ const panzoom = createPanZoom({
 
 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.
 
+## Knob
+
+`createKnob` is a virtual knob after GarageBand's ([How Apple Designs a Virtual Knob](https://jherrm.github.io/knobs/)): one focusable control you spin around its centre or slide vertically / horizontally, with **one gesture locked per drag**. **There is no APG pattern and no ARIA role for a dial**, so it is a `role=slider` with `aria-valuenow` / `aria-valuetext`, and `test/knob.browser.test.tsx` (real Chromium) is its oracle — there is no Quint spec.
+
+```tsx
+const knob = createKnob({ labels: { knob: "Volume" }, format: (value) => `${value}%` });
+const turn = () => knob.percentOf(knob.value());
+
+<div {...knob.knobProps} class="knob">
+  <span class="indicator" style={{ transform: `rotate(${turn() * 360}deg)` }} />
+</div>
+<span {...knob.valueProps} class="visually-hidden">
+  {knob.value()}
+</span>;
+```
+
+`percentOf` is the fraction of a full turn the skin rotates by; the look is the host's. `valueProps` must be rendered (hide it visually, never with `hidden`): it is the live announcement.
+
+**A dial is never the only control.** The keyboard contract stands in for every gesture — arrows step, PageUp/PageDown by ten steps, Home/End to the bounds — but a numeric field (`createSpinbutton`) still belongs next to it: a slider role is operable but does not make a range easy to discover or type.
+
+**Gestures** (`gesture`, default `"both"`). A pointerdown records the centre, the start angle and the side. On the first movement past 6 px the drag picks a mode once and keeps it for the rest of the drag: movement that stays on one axis (the other under 35% of it) is a slide, anything else is a turn around the centre. The reference's direction rule holds: down on the right half turns clockwise (up in value), down on the left half counter-clockwise, and a horizontal slide uses the same left/right side. A spin's value per degree shrinks as the pointer moves away from the centre — the same angle is a longer arc, so farther is finer. `gesture: "spin"` / `"slide"` disables the other. The wheel steps once per event and `preventDefault`s, so hovering the dial stops the page from scrolling.
+
+**`wrap`** makes the dial continuous: past `max` comes back at `min`, so a full turn is a full cycle instead of the clamped end of the range. `setValue` / `stepBy` are requests like a key, so a controlled `value` still owns the result.
+
 ## Resizable panels
 
 `createResizablePanels` is a group of N panes and N-1 separators: react-resizable-panels' layout on the APG window splitter's keyboard. Its behaviour is `packages/apg-specs/specs/patterns/resizable-panels.qnt` — not an APG pattern, so it lives under `patterns/` — and the DOM is checked against it by the differential walk. The spec is the three-pane instance (10/80 bounds, 10% steps, pane 0 collapsible at 0); the primitive takes N panes and any bounds.
@@ -359,6 +383,8 @@ const timeline = createTimeline({
 
 `createTabs` is the APG tablist: roving tabindex, wrapping arrows, Home/End, automatic or manual activation, disabled tabs, and a selection that is a request (`value` + `onValueChange`) or uncontrolled (`defaultSelected`). The plain widget is checked against `specs/apg/tabs.qnt` by the scenario bridge and the differential walk in `test/tabs.browser.test.tsx`.
 
+Its accessibility requirements — one row per requirement, each naming the Quint invariant, browser test or manual AT row that holds it, and the gaps still open — are `docs/requirements/tabs.md`, written on the model in `docs/requirements/README.md`: a behaviour goes to the spec and its walk, a DOM attribute or a layout value to a browser test, and what a screen reader says to the assistive-technology table.
+
 The docs playground's file tabs add and close files and rename them, so `createTabs` also takes `closable` and `renamable` — both off by default, so the plain widget is unchanged. **The primitive never takes the list:** it asks (`onClose`, `onRename`), the host removes or renames. `label(index)` is the tab's name: it names the close and rename buttons and seeds the rename draft, and it is read lazily.
 
 ```tsx
@@ -597,6 +623,57 @@ onSettled(() => toc.attach()); // returns the teardown
 - **Smooth scrolling is the host's.** The links are plain `#id` targets, the primitive never moves the scrollport, so `scroll-behavior: smooth` (and any `prefers-reduced-motion` override) belongs to the page's CSS; there is no scroll helper to reduce.
 - **"On this page" is English.** Spread `navProps` first and override it after: `<nav {...toc.navProps} aria-label={t("onThisPage")}>`.
 
+## Command palette
+
+The first **composition** on the primitives — no new widget, no new spec: `createCommandPalette` is `createDialogModal` (a modal dialog) + `createTextInput` (the field) + `createStatus` (the count), wired into the shape [docs/research/compositions-2026-10.md](docs/research/compositions-2026-10.md) settles.
+
+```tsx
+const palette = createCommandPalette({
+  commands, // ReadonlyArray<{ id, label, group?, keywords?, run(): void | Promise<void> }>
+  hotkey: "mod+k", // what attach() binds; this is the default
+  labels: { title: t("palette"), placeholder: t("search"), empty: t("empty") },
+});
+
+onSettled(() => palette.attach()); // one document hotkey; returns the teardown
+
+const groups = () => [...new Set(palette.results().map((result) => result.group ?? ""))];
+
+<button
+  aria-haspopup="dialog"
+  aria-expanded={palette.open()}
+  onClick={() => palette.openPalette()}
+>
+  Commands
+</button>
+<div {...palette.backdropProps} />
+<div {...palette.dialogProps}>
+  <h2 {...palette.titleProps}>{palette.labels.title}</h2>
+  <input {...palette.inputProps} />
+  <div {...palette.listProps}>
+    <For each={groups()}>
+      {(group) => (
+        <section>
+          <h3>{group}</h3>
+          <For each={palette.results().filter((result) => result.group === group)}>
+            {(result) => <div {...palette.optionProps(result.id)}>{result.label}</div>}
+          </For>
+        </section>
+      )}
+    </For>
+  </div>
+  <p {...palette.emptyProps}>{palette.labels.empty}</p>
+  <div {...palette.statusProps}>{palette.status()}</div>
+</div>;
+```
+
+- **A dialog, not a combobox.** Choosing a row runs a command; it does not complete the field. So the field is `input[type=text][role=searchbox]` with no `aria-autocomplete` and no `aria-haspopup`, the container is `role=dialog` (a trigger says `aria-haspopup="dialog"`), and the list is a `role=listbox` named by the title. Nothing is changed by typing.
+- **Focus stays in the field.** `aria-activedescendant` names the highlighted option; ↓ past the last and ↑ before the first put the highlight back on the field (the attribute is absent), and ↓/↑ from there re-enter the list at the first/last row. Home/End move the caret while the field has text and are list keys (first/last) only while it is empty. Enter runs the highlighted command; Escape closes through the dialog; Tab is not intercepted, so the dialog's own focus policy applies.
+- **Filtering is a plain case-insensitive substring match** on `label` and `keywords`. No fuzzy scoring: a palette holds tens of commands, and ranking (recents, scopes, weighted keywords) is a policy the host owns — a typo hiding a command is worse than an extra row. `results()` keeps host order.
+- **Groups, empty state, one announcement.** `result.group` (or `undefined`) is what the host groups by; it renders the headings and the CSS. `emptyProps.hidden` is false when nothing matches, and `labels.empty` is the text to show. The count lands in one polite region (`statusProps`, `status()`), written once per query change — moving the highlight does not re-announce it.
+- **Reset on close**: the query and highlight are cleared on close, so the next open starts at the full list (unlike a combobox, which keeps its value). Focus returns to the element that had it when the palette opened.
+- **The host's**: rendering, grouping and CSS; async commands (`run` may return a promise, and moving the highlight to the next command is the host's call); closing on anything but Escape or a command; every visible string through `labels`; and the dialog's title element, which carries `titleProps` (`aria-labelledby` points at it).
+- **Not in this PR**: the filterable menu (`filter: true` on `createMenu`, with the IME guard and the arrow loop to the field) and the date picker are later compositions on the same research; this one is the palette only.
+
 ## Commands
 
 ```sh