cssints 0.15.0 → 0.18.0

package/docs/API.md

@@ -1377,6 +1377,188 @@ createPopover(options?: {
 
 `attach` is the DOM contract: on open it measures and places the content (and again on resize, scroll and a `ResizeObserver`), focuses the content's first focusable element (else the content, which is `tabindex="-1"`), and on close returns the focus to the trigger unless the close came from an outside `pointerdown` — that one leaves the focus where the page put it. The page behind stays interactive: there is no `inert`, no scroll lock and no Tab cycle, and the content is not a menu (no roving focus: `createMenu` in a popover owns its items). The rects and the viewport passed to `position` must share a space; `attach` measures in client space and writes page space for `position: absolute`.
 
+### Headless: `createDrawer` (`@cssints/headless`)
+
+The drawer / sheet shell: an edge-anchored panel over Dialog (Modal), with the focus, Escape, scroll-lock and backdrop behaviour of `createConfirm`. **No APG pattern exists for a drawer or a bottom sheet**; [packages/headless/docs/bottom-sheet.md](../packages/headless/docs/bottom-sheet.md) settles that the library composes instead of adding a sheet primitive (the semantics are Dialog, the position and the snap points are native CSS), and this is the shell that decision left to exist. Its oracle is `packages/headless/test/drawer.browser.test.tsx`.
+
+```ts skip
+createDrawer(options?: {
+  id?: string | undefined;
+  open?: boolean | undefined; // controlled: the host owns the state
+  defaultOpen?: boolean | undefined;
+  side?: "left" | "right" | "bottom" | undefined; // "right"; presentation only
+  modal?: boolean | undefined; // true; read at every attribute read (the breakpoint switch)
+  breakpoint?: number | undefined; // px; documented only: the host watches it and passes side / modal
+  dismissable?: boolean | undefined; // true; a backdrop click or an outside pointerdown
+  labelledby?: string | undefined; // the panel needs a name
+  onOpenChange?(open: boolean): void;
+}): {
+  open(): boolean;
+  side(): "left" | "right" | "bottom";
+  triggerProps: {
+    id;
+    "aria-haspopup": "dialog";
+    "aria-expanded": "true" | "false";
+    "aria-controls": string;
+    onClick(): void; // toggles
+    onKeyDown(event: KeyboardEvent): void; // Enter / Space open
+  };
+  backdropProps: { id; hidden: boolean; onClick(): void }; // always hidden when closed or not modal
+  contentProps: {
+    id;
+    role: "dialog";
+    "aria-modal": "true" | undefined; // by modal, and undefined while closed
+    "aria-labelledby": string | undefined;
+    tabindex: -1;
+    hidden: boolean;
+    onKeyDown(event: KeyboardEvent): void; // Escape closes
+  };
+  handleProps: { "aria-hidden": "true" }; // a bottom sheet's grab handle; decorative
+};
+```
+
+`side` and `modal` are the whole presentation API: a sheet is `{ side: "bottom", modal: true }`, a side rail is `{ side: "right" }`, and a non-modal rail is `{ side: "right", modal: false }`. `modal` is read at attribute-read time, so a host that watches the breakpoint may flip it while the drawer is open and the backdrop, `aria-modal` and the lock follow; `breakpoint` itself is not read, because the primitive has no viewport and the host owns the `matchMedia`.
+
+A modal drawer is `aria-modal="true"` with a backdrop, focus moves to the panel's first focusable on open (else the panel, `tabindex="-1"`) and back to the trigger on close, Tab and Shift+Tab cycle inside it, `overflow: hidden` is set on `document.documentElement` (counted, and shared with `createConfirm`, so a confirm over a drawer nests), and Escape is read from the document in the capture phase, so it closes wherever the focus is. A non-modal drawer keeps the page's scroll, focus and clicks: no `aria-modal`, no backdrop, no lock, no Tab trap; an outside `pointerdown` still dismisses it when `dismissable`, and Escape still closes it. `dismissable: false` pins the drawer against the backdrop and the outside pointerdown only.
+
+**No drag-to-dismiss and no `attach`.** A drag would be a JS re-implementation of the native scroll snap the host writes (see bottom-sheet.md), so `handleProps` is decoration with no pointer handlers, and the ways out are the backdrop, Escape, a close control in the panel and the trigger. The panel is edge-anchored, so nothing is measured: focus and the Tab cycle find it through `contentProps.id`.
+
+### Headless: `createTable` (`@cssints/headless`)
+
+A data table on a **native `<table>`**: sortable column headers and row selection, as state and attribute objects. It has no spec of its own; it composes the two state models the package already has (`grid-sort.qnt`, `grid-selection.qnt`) without the grid's navigation, so `packages/headless/test/table.browser.test.tsx` is its oracle. The host renders `<table>`, `<caption>`, `<thead>`, `<tbody>`, `<th scope="col">` and `<td>`: the primitive adds no `role`, only what the elements cannot say themselves.
+
+```ts skip
+createTable(options: {
+  columns: ReadonlyArray<{ key: string; sortable?: boolean; numeric?: boolean; abbr?: string | undefined }>; // sortable defaults true
+  rows: ReadonlyArray<string>; // row ids in render order; the host sorts its own data
+  selection?: "none" | "single" | "multiple" | undefined; // "none"
+  sortCycle?: "tri-state" | "toggle" | undefined; // "tri-state": ascending -> descending -> unsorted
+  sort?: TableSort | null | undefined; // controlled; null = unsorted, undefined = uncontrolled
+  defaultSort?: TableSort | undefined;
+  onSortChange?(sort: TableSort | undefined): void;
+  selected?: ReadonlyArray<string> | undefined; // controlled
+  defaultSelected?: ReadonlyArray<string> | undefined;
+  onSelectionChange?(selected: ReadonlyArray<string>): void;
+  rowCount?: number | undefined; // only when the host windows its rows
+  columnCount?: number | undefined; // only when it windows its columns
+  labels?: { table?: string | undefined; selectAll?: string | undefined; selectRow?: ((id: string) => string) | undefined } | undefined;
+  id?: string | undefined;
+}): {
+  selectionMode(): "none" | "single" | "multiple";
+  sort(): TableSort | undefined;
+  selected(): ReadonlyArray<string>;
+  isSelected(id: string): boolean;
+  tableProps: { "aria-label"; "aria-rowcount"; "aria-colcount" }; // the counts only while windowed
+  captionProps: { id };
+  headerCellProps(key: string): { scope: "col"; "aria-sort": "ascending" | "descending" | undefined; abbr };
+  headerButtonProps(key: string): { type: "button"; onClick } | undefined; // undefined when not sortable
+  rowProps(id: string): { "aria-selected"; onClick };
+  cellProps(rowId: string, key: string): { "aria-colindex" }; // only while windowed
+  selectAllProps: { role: "checkbox"; "aria-checked": "true" | "false" | "mixed"; "aria-label"; tabindex: 0; onClick; onKeyDown } | undefined;
+  rowCheckboxProps(id: string): { role: "checkbox"; "aria-checked"; "aria-label"; tabindex: 0; onClick; onKeyDown } | undefined;
+  toggleAll(): void;
+  toggleRow(id: string): void;
+};
+```
+
+`aria-sort` is carried by the sorted column only; a sortable header that is not sorted has none (ARIA's "not sorted" default), and a `sortable: false` column gets no button from `headerButtonProps` at all, so it is not a tab stop. The header button cycles `ascending` -> `descending` -> unsorted by default (so the table can be put back in its own order) and `ascending` <-> `descending` with `sortCycle: "toggle"` (what the APG grid example does); a new column always starts `ascending`, and only one is sorted. Sorting is the host's data: the primitive carries the descriptor and announces it, it never reorders a row.
+
+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: `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.15.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.15.0",
+    "@cssints/css-grammar": "^0.18.0",
     "culori": "^4.0.2",
     "effect": "4.0.6",
     "happy-dom": "^20.14.5",