cssints 0.17.0 → 0.18.0

package/docs/API.md

@@ -1465,7 +1465,100 @@ 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.
 
- f812d87e (headless: a data table with sortable headers and row selection)
+
+### Headless: `createHotkeys` (`@cssints/headless`)
+
+One registry for the chords every app hand-rolls (`/` focuses search, Cmd/Ctrl+K opens it, Cmd/Ctrl+S saves). **A platform utility rather than a widget**: no APG pattern exists for a keyboard registry, so it has no role, no element, no styling, no Quint spec and no ported scenarios; `packages/headless/test/hotkeys.browser.test.tsx` is its oracle.
+
+```ts skip
+const hotkeys = createHotkeys({ isApple: false }); // isApple is injectable; default reads the platform
+const unbind = hotkeys.bind({
+  keys: "mod+k", // mod = Cmd on macOS, Ctrl elsewhere; then ctrl / alt / shift / meta, then one key
+  onTrigger: (event) => search.focus(),
+  when: () => dialog.open === false, // gates it: false makes the next matching binding fire
+  preventDefault: true, // default; false lets the browser act too
+  allowInEditable: false, // default; true fires with the focus in an input / textarea / contenteditable
+  scope: panel, // only events from inside this element; it adds no listener
+});
+unbind(); // idempotent
+hotkeys.dispose(); // unbinds all and removes the document listener; a later bind is a no-op
+```
+
+`keys` is a chord string: optional modifiers `mod`, `ctrl`, `alt`, `shift`, `meta`, then exactly one key (`k`, `/`, `?`, `escape`, `enter`, `arrowup`), joined with `+`. `mod` is resolved at `createHotkeys` time, once. A shifted character implies Shift (`"?"` fires from Shift+/, `"/"` does not), and the other modifiers must match the event exactly, so a chord without `shift` does not fire while Shift is held.
+
+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.
+
+```ts skip
+createScrollspy(options: {
+  entries: ReadonlyArray<{ id: string; label: string }>; // document order; the ids are the headings'
+  offset?: number | undefined; // px below the scrollport's top edge where a heading counts as current; 0
+  root?: (() => HTMLElement | undefined) | undefined; // the scroll container; the document by default
+  onChange?(id: string | undefined): void;
+}): {
+  active(): string | undefined; // the last heading at or above the offset, else the first entry
+  navProps: { "aria-label": string }; // "On this page"; override after the spread to translate
+  listProps: { role: "list" };
+  itemProps(id: string): { role: "listitem" };
+  linkProps(id: string): { href: string; "aria-current": "location" | undefined }; // exactly one link is current
+  attach(): () => void; // one passive scroll listener; returns the teardown
+};
+```
+
+`attach()` adds **one passive `scroll` listener** to `root()`, which measures each heading's `getBoundingClientRect`, syncs once (a page opened mid-scroll starts correct), and returns the teardown. Not an `IntersectionObserver`: "the last heading at or above the offset" is a total order over all headings, while an observer reports only what crossed a band, so it has to rebuild that order from enter/leave state and misreports after a jump. Smooth scrolling is the host's (`scroll-behavior: smooth`, and any `prefers-reduced-motion` override): the links are plain `#id` targets and the primitive never moves the scrollport. The first entry is current before any scroll and while nothing has passed the line.
+
+f812d87e (headless: a data table with sortable headers and row selection)
+
+### 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.
+
+```ts skip
+createPanZoom(options?: {
+  min?: number | undefined; // 1, and where reset returns
+  max?: number | undefined; // 4
+  step?: number | undefined; // the + / - increment, 0.25
+  defaultScale?: number | undefined;
+  scale?: number | undefined; // controlled: the host owns the scale
+  onScaleChange?(scale: number): void;
+  onPanChange?(offset: { x: number; y: number }): void;
+  bounds?: "clamp" | "free" | undefined; // "clamp": the image never leaves a gap
+  labels?: { viewport?: string | undefined } | undefined; // the viewport's name, "Image"
+}): {
+  scale(): number;
+  offset(): { x: number; y: number };
+  reset(): void; // back to min and centred
+  zoomIn(): void;
+  zoomOut(): void;
+  setScale(scale: number, origin?: { x: number; y: number }): void; // origin in the viewport's own space, its centre by default
+  viewportProps: {
+    tabindex: 0;
+    role: "group";
+    "aria-roledescription": "zoomable image";
+    "aria-label";
+    "aria-describedby";
+    onKeyDown; // + / = / - zoom, arrows pan by 24 px (Shift x4), 0 resets
+    onWheel; // ctrl / meta only: the browser's pinch, zoomed about the cursor
+    onPointerDown;
+    onPointerMove;
+    onPointerUp;
+    onPointerCancel;
+    onDblClick;
+  };
+  imageProps: { draggable: false; style: { transform: string } }; // translate(..) scale(..)
+  valueProps: { id; role: "status"; "aria-live": "polite"; "aria-atomic": "true" };
+  value(): string; // "150%"
+};
+```
+
+Wheel zooms **only with `ctrl` / `meta`** held: the browser's pinch gesture arrives that way, and a bare wheel is left to the page so trackpad scrolling still works — a swallowed wheel is never acceptable. Arrows pan the image with the arrow (like a drag), and with `bounds: "clamp"` they are inert at `min`, where there is nothing to reveal. The clamp bounds the offset by half the viewport's scaled overflow, so the image is expected to fill the viewport at `min` (`width: 100%; height: 100%` / `object-fit: cover`); a letterboxed image cannot be held gap-free, and `bounds: "free"` lets it be dragged out of view instead. `valueProps` carries no `hidden` — a `hidden` live region is not announced — so the host hides it visually.
+
+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).
+
 ### 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.17.0",
+  "version": "0.18.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.17.0",
+    "@cssints/css-grammar": "^0.18.0",
     "culori": "^4.0.2",
     "effect": "4.0.6",
     "happy-dom": "^20.14.5",