cssints 0.19.0 → 0.20.0

package/docs/API.md

@@ -1469,6 +1469,8 @@ Selection is over ids, so it survives the host's re-sort. `rowProps` carries `ar
 
 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
@@ -1546,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.
@@ -1592,6 +1636,67 @@ 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.
@@ -1691,6 +1796,51 @@ createSpinbutton(options?: {
 - 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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cssints",
-  "version": "0.19.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.19.0",
+    "@cssints/css-grammar": "^0.20.0",
     "culori": "^4.0.2",
     "effect": "4.0.6",
     "happy-dom": "^20.14.5",