@cssints/headless 0.17.0 → 0.18.0

package/README.md

@@ -65,7 +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, 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, 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.
 
 `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.
 
@@ -89,6 +90,41 @@ Membership, sizes and z-order are **not modelled** in `pointer.qnt` (its node se
 
 **Nested canvases** are two instances the host composes: a `#canvas` node holds a second `createCanvas`, and the inner viewport stops propagation of its own pointer, wheel and key events. The innermost canvas under the pointer owns the event, so a press or zoom inside it never starts an outer gesture or moves the outer camera. A nested canvas is a single tab stop in its parent.
 
+## Pan and zoom
+
+`createPanZoom` is one image fitted to a viewport: the scale, the offset and the prop objects for the viewport, the image and a live value. **There is no APG pattern for pan-zoom**, so there is no Quint spec and no ported scenarios: the contract is this module's own and `test/panzoom.browser.test.tsx` is its oracle. The case it replaces (kocharin-art-3's `Zoomable`: ~110 lines of pointer maths) had no keyboard path and no ARIA at all.
+
+**The accessible contract is three parts, and the pointer is a bonus:** a viewport that takes focus (`role=group`, `tabindex=0`, `aria-roledescription="zoomable image"`, `aria-describedby` the value), keyboard operations that stand in for every gesture (`+` / `=` / `-` zoom by `step`, arrows pan by 24 px, Shift ×4, `0` resets), and a polite live region (`role=status`, `aria-live=polite`, the current `"150%"`). `valueProps` deliberately carries no `hidden`: a `hidden` live region is not announced, so the host hides it visually.
+
+**Not `createCanvas`.** The canvas is a camera over an infinite world with nodes, culling, snap and a z-order; a picture is one image in a box. There is no world, no node set and no reason to carry the camera machine.
+
+```tsx
+const panzoom = createPanZoom({ min: 1, max: 4, step: 0.25 });
+
+<div {...panzoom.viewportProps} class="viewport">
+  <img {...panzoom.imageProps} src={src} alt={alt} />
+  <span {...panzoom.valueProps} class="visually-hidden">
+    {panzoom.value()}
+  </span>
+</div>;
+```
+
+**Gestures.** A drag pans, a second pointer pinches about its midpoint, a double click resets. Pinch is two pointers and the distance between them, not a platform gesture, so it works where `PointerEvent` does. **Wheel is zoom only with `ctrl` / `meta`** — the browser's own pinch arrives as `ctrl+wheel` — and a bare wheel is never `preventDefault`ed, so the page keeps scrolling; a swallowed wheel is the one thing that is never acceptable on a trackpad.
+
+**`bounds: "clamp"`** (the default) 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 smaller than its viewport cannot be held gap-free: give it a viewport of its own or `bounds: "free"`.
+
+Left to the host: the box (the viewport's size and `overflow: hidden`, `touch-action: none` if a touch drag should pan), the look (a transition on the transform, `transform-origin: 50% 50%` — the default this maths assumes), and the image itself. Not modelled: inertia, rotation, and a keyboard pan at scale `min` (the clamp means there is nothing to pan, so the arrows are inert).
+
+```tsx
+const panzoom = createPanZoom({
+  scale, // controlled: the host owns the scale
+  onScaleChange: setScale,
+  onPanChange: (offset) => save({ x: offset.x, y: offset.y }),
+});
+```
+
+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.
+
 ## 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.
@@ -382,6 +418,74 @@ const drawer = createDrawer({ side: "right", labelledby: "nav-title" });
 - **No drag-to-dismiss.** A drag is not a dialog interaction: it is a scroll snap the platform runs off the main thread, and it is the host's CSS (`scroll-snap-type: y mandatory`, snap markers, `scrollsnapchange`; see [docs/bottom-sheet.md](docs/bottom-sheet.md)). Re-implementing a native snap in pointer events would be the gesture duplication that research forbids, and the handle would drag on top of the snap that already moved the panel. So `handleProps` is decoration (`aria-hidden`, no pointer handlers) and the ways out are the backdrop, Escape, a close control the host puts in the panel, and the trigger. Swipe-to-dismiss, if it is ever wanted, is a separate decision with its own oracle.
 - **No `attach`.** The panel is edge-anchored: nothing is measured and no placement is computed, so focus and the Tab cycle find the panel through `contentProps.id` and the host only spreads attributes onto its own elements. Give the panel a name: pass `labelledby`, or set `aria-labelledby` / `aria-label` after the spread.
 
+## Hotkeys
+
+`createHotkeys` is a **platform utility, not a widget**: one registry for the chords every app hand-rolls (the docs app's `/` and Cmd/Ctrl+K, the CMS's Cmd/Ctrl+S). **No APG pattern exists for a keyboard registry**, so there is no role, no element, no styling and no Quint spec; `test/hotkeys.browser.test.tsx` is the oracle.
+
+```tsx
+const hotkeys = createHotkeys();
+
+onSettled(() => {
+  hotkeys.bind({
+    keys: "mod+k",
+    onTrigger: () => searchEl.focus(),
+  });
+  hotkeys.bind({
+    keys: "/",
+    when: () => !dialog().open,
+    onTrigger: () => searchEl.focus(),
+  });
+  hotkeys.bind({
+    keys: "mod+s",
+    scope: editorEl,
+    onTrigger: () => save(),
+  });
+  return () => hotkeys.dispose();
+});
+```
+
+- **One listener.** `bind` adds a chord to one `keydown` listener on the document in the capture phase (a `scope` only filters the event's target, it does not add a listener), and the last binding to go is the one that removes it; `dispose` unbinds everything and a later `bind` is a no-op. The unbind `bind` returns is idempotent.
+- **Modifiers match exactly.** `mod` is Cmd on macOS and Ctrl elsewhere (`isApple` injects the answer, so a test does not read the runner's OS); `ctrl`, `alt`, `shift` and `meta` are as written. A chord that does not declare Shift does not fire with Shift held. A shifted character implies Shift: `"?"` fires from Shift+/ even without `"shift+?"`, and `"/"` does not fire from it.
+- **A text field keeps its keys.** 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`, which is what Escape wants: it closes a dialog wherever the focus is.
+- **Last bound wins.** Only the most recently bound match fires, so a modal's `"/"` shadows the page's and unbinding it brings the page's back; a `when` that is false makes the next match fire instead, so the gate can close without unbinding.
+- **`preventDefault` is on** for a binding that fires (Cmd/Ctrl+S and Cmd/Ctrl+K would otherwise reach the browser); pass `false` to let the platform act too.
+
+Collisions with the browser's own chords: `preventDefault` reaches the page's default action, not the browser's. Cmd/Ctrl+S (Save Page), Cmd/Ctrl+K (the browser's search, in Chrome and Firefox), Cmd/Ctrl+P and `/` (Firefox's quick find) can be cancelled by a page, and a host that binds one is choosing to take it from the browser; Cmd/Ctrl+T, Cmd/Ctrl+W, Cmd/Ctrl+N, Cmd/Ctrl+L and F11 are reserved and cannot be intercepted, so a chord built on them never fires. `keys` takes any of them the same and says nothing.
+
+## Scrollspy
+
+`createScrollspy` is a table of contents whose current entry is the last heading to reach the top of the scrollport. **No APG pattern exists for a scrollspy** (the APG has no table-of-contents pattern), so there is no Quint spec and no ported scenarios: the contract is WAI-ARIA — `aria-current="location"` on the current link, exactly one link at a time, `role="list"` / `role="listitem"` for the list, and a named navigation landmark — plus HTML (`#id` targets). `test/scrollspy.browser.test.tsx` is its oracle.
+
+```tsx
+const toc = createScrollspy({
+  entries, // { id, label } in document order: the ids are the headings'
+  offset: 96, // a sticky header's height
+  onChange: (id) => track(id),
+});
+
+onSettled(() => toc.attach()); // returns the teardown
+
+<nav {...toc.navProps}>
+  <ul {...toc.listProps}>
+    <For each={entries}>
+      {(entry) => (
+        <li {...toc.itemProps(entry.id)}>
+          <a {...toc.linkProps(entry.id)}>{entry.label}</a>
+        </li>
+      )}
+    </For>
+  </ul>
+</nav>;
+```
+
+- **A scroll listener, not an `IntersectionObserver`.** "The last heading at or above the offset" is a total order over every heading, and an observer only reports what crossed its band: a band observer has to rebuild the order from its enter/leave state and misreports after a jump (an anchor click, a restored scroll position). The listener is passive, the measurements are reads only (no writes, so no layout thrash), and a docs page has a dozen headings — the same cost as the listener the page already keeps.
+- **`attach()`** adds that one listener to `root()` (the document by default; read once, so attach again after swapping containers), calls it once to sync a page opened mid-scroll, and returns the teardown. Headings are looked up by id on every scroll, so they may render after `attach`; an id with no element is skipped.
+- **`offset`** is px below the scrollport's top edge, not the viewport's, so an inner container plus a sticky header works: `offset` is the header's height inside that container.
+- **Before any scroll the first entry is current**, and it stays current while nothing has passed the line. `active()` is `undefined` only when there are no entries.
+- **Exactly one `aria-current="location"`**, on the link, never on the heading: the heading's own `id` is the target. Skin it with `a[aria-current="location"]`.
+- **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")}>`.
+
 ## Commands
 
 ```sh

package/dist/index.d.mts

@@ -1757,6 +1757,128 @@ export interface Pagination {
  * Target size is the skin's job: 24x24 CSS px at AA, 44x44 at AAA.
  */
 export declare const createPagination: (options: PaginationOptions) => Pagination;
+/** A point in the viewport's own coordinate space: `0, 0` is its top-left corner. */
+export interface PanZoomPoint {
+  readonly x: number;
+  readonly y: number;
+}
+export interface PanZoomOptions {
+  /** Smallest scale, and where `reset` returns to. Default 1. */
+  readonly min?: number | undefined;
+  /** Largest scale. Default 4. */
+  readonly max?: number | undefined;
+  /** The `+` / `-` / `zoomIn` / `zoomOut` increment. Default 0.25. */
+  readonly step?: number | undefined;
+  /** Starting scale when uncontrolled; ignored while `scale` is set. */
+  readonly defaultScale?: number | undefined;
+  /** Controlled: the host owns the scale and this is the only thing that changes it. */
+  readonly scale?: number | undefined;
+  /**
+   * A request to change the scale, called when the intent differs from the
+   * current value. Uncontrolled it is accepted; controlled the host may ignore it.
+   */
+  readonly onScaleChange?: (scale: number) => void;
+  /** The pan changed (a drag, a pinch, an arrow key, a zoom about a point, a reset). */
+  readonly onPanChange?: (offset: PanZoomPoint) => void;
+  /**
+   * `"clamp"` (default) keeps the scaled image covering the viewport: the offset
+   * never opens a gap. `"free"` lets it be dragged out of view.
+   */
+  readonly bounds?: "clamp" | "free" | undefined;
+  readonly labels?: {
+    readonly viewport?: string;
+  } | undefined;
+}
+export interface PanZoomViewportProps {
+  readonly tabindex: number;
+  readonly role: "group";
+  readonly "aria-roledescription": string;
+  readonly "aria-label": string;
+  readonly "aria-describedby": string;
+  readonly onKeyDown: (event: KeyboardEvent) => void;
+  readonly onWheel: (event: WheelEvent) => void;
+  readonly onPointerDown: (event: PointerEvent) => void;
+  readonly onPointerMove: (event: PointerEvent) => void;
+  readonly onPointerUp: (event: PointerEvent) => void;
+  readonly onPointerCancel: (event: PointerEvent) => void;
+  readonly onDblClick: (event: MouseEvent) => void;
+}
+/**
+ * Spread onto the image. `style` is a getter returning a fresh object, so Solid
+ * reads it inside the tracking scope; `draggable: false` keeps the native image
+ * drag from swallowing the pan gesture.
+ */
+export interface PanZoomImageProps {
+  readonly draggable: false;
+  readonly style: {
+    readonly transform: string;
+  };
+}
+/** The live value: the current percentage, in a polite status region (`aria-describedby` of the viewport). */
+export interface PanZoomValueProps {
+  readonly id: string;
+  readonly role: "status";
+  readonly "aria-live": "polite";
+  readonly "aria-atomic": "true";
+}
+export interface PanZoom {
+  readonly scale: Accessor<number>;
+  readonly offset: Accessor<PanZoomPoint>;
+  /** Back to `min` and centred. */
+  readonly reset: () => void;
+  readonly zoomIn: () => void;
+  readonly zoomOut: () => void;
+  /** A request; `origin` is the viewport point to keep still (its centre by default). */
+  readonly setScale: (scale: number, origin?: PanZoomPoint) => void;
+  readonly viewportProps: PanZoomViewportProps;
+  readonly imageProps: PanZoomImageProps;
+  readonly valueProps: PanZoomValueProps;
+  /** The human value of `valueProps`: `"150%"`. */
+  readonly value: Accessor<string>;
+}
+/**
+ * Pan and zoom for one image in a viewport: scale, offset and the prop objects
+ * for a focusable viewport, the transformed image and a live value.
+ *
+ * **There is no APG pattern for pan-zoom.** The accessible contract is the three
+ * parts this returns: a viewport that takes focus (`role=group`, `tabindex=0`,
+ * `aria-roledescription="zoomable image"`), keyboard operations that stand in
+ * for every pointer gesture (`+` / `=` / `-` zoom, arrows pan, `0` resets), and a
+ * polite live region (`aria-describedby` of the viewport) that carries the
+ * current scale. The pointer gestures are an addition for mouse and touch, never
+ * the only way in. That contract is this module's own: the case it replaces
+ * (kocharin-art-3's `Zoomable`, ~110 lines of pointer maths) had no keyboard path
+ * and no ARIA at all, and `createCanvas` is the wrong model here — an infinite
+ * canvas moves a camera over a world, while this is one image fitted to its
+ * viewport.
+ *
+ * Wheel is zoom-with-a-modifier only: `ctrl` / `meta` (the browser's own pinch
+ * arrives as `ctrl+wheel`) zooms about the cursor; a bare wheel is never
+ * `preventDefault`ed, so the page keeps scrolling. Trackpad gestures differ per
+ * platform and a swallowed wheel is the one thing that is never acceptable.
+ *
+ * Pointer: a drag pans, a second pointer pinches (about its midpoint), a double
+ * click resets. Capture is best-effort (a synthetic pointer cannot be captured).
+ *
+ * `bounds: "clamp"` bounds the offset by half the viewport's scaled overflow, so
+ * the image is expected to fill the viewport at `min` (the usual
+ * `width: 100%; height: 100%` / `object-fit: cover` box). A letterboxed image
+ * smaller than its viewport cannot be held gap-free; give it a viewport of its
+ * own or `bounds: "free"`.
+ *
+ * Request/commit (`rt1p`): uncontrolled by default (`defaultScale`); pass `scale`
+ * + `onScaleChange` to own the value. The offset has no controlled prop, so a
+ * hosting page that rejects a scale request also gets the offset resolved for the
+ * scale it refused — accept the request, or pass `bounds: "free"` and own the
+ * pan elsewhere.
+ *
+ * The host owns the box and the looks: size the viewport, put `touch-action:
+ * none` on it if a touch drag should pan, centre the image
+ * (`transform-origin: 50% 50%` is the default this maths assumes), and hide the
+ * live region visually rather than with `hidden` (a `hidden` live region is not
+ * announced).
+ */
+export declare const createPanZoom: (options?: PanZoomOptions) => PanZoom;
 export type PopoverPlacement = "bottom-start" | "bottom" | "bottom-end" | "top-start" | "top" | "top-end";
 /** A rect in one space, as `getBoundingClientRect` gives it. */
 export interface PopoverRect {
@@ -2027,6 +2149,53 @@ export declare const packSort: (column: number, dir: GridSortDirection) => numbe
  * snapshot); `rows`/`cols`/`page` are captured once.
  */
 export declare const createGrid: (options?: GridOptions) => Grid;
+/**
+ * Hotkeys: one registry for the chords every app hand-rolls (the docs app's `/`
+ * and Cmd/Ctrl+K, the CMS's Cmd/Ctrl+S), instead of a `keydown` listener per
+ * screen.
+ *
+ * This is a platform utility, not a widget: there is no APG pattern for a
+ * keyboard registry, so no role, no element, no styling, no Quint spec and no
+ * ported scenario. The oracle is `test/hotkeys.browser.test.tsx` in a real
+ * Chromium.
+ */
+export interface HotkeyBinding {
+  /**
+   * A chord: the modifiers `mod` (Cmd on macOS, Ctrl elsewhere), `ctrl`, `alt`,
+   * `shift`, `meta`, then exactly one key (`k`, `/`, `?`, `escape`, `enter`,
+   * `arrowup`), joined with `+`; `"mod+k"`, `"shift+?"`, `"/"`.
+   */
+  readonly keys: string;
+  readonly onTrigger: (event: KeyboardEvent) => void;
+  /** Gates a binding whose precondition is off: it falls through to the next one. */
+  readonly when?: (() => boolean) | undefined;
+  /** `event.preventDefault()` when the binding fires; default true. */
+  readonly preventDefault?: boolean | undefined;
+  /** Fire while the focus is in an input, a textarea or a contenteditable; default false. */
+  readonly allowInEditable?: boolean | undefined;
+  /** Only events from inside this element: one panel's `"mod+s"` over a page's. */
+  readonly scope?: HTMLElement | undefined;
+}
+export interface HotkeysOptions {
+  /** Whether `mod` is Cmd; injected so a test does not read the runner's OS. */
+  readonly isApple?: boolean | undefined;
+}
+export interface Hotkeys {
+  /** Registers `binding`; the returned unbind is idempotent. The last bound wins. */
+  readonly bind: (binding: HotkeyBinding) => () => void;
+  /** Unbinds all of them and removes the listener; a later `bind` is a no-op. */
+  readonly dispose: () => void;
+}
+/**
+ * One `keydown` listener in the capture phase, one list of chords. A chord
+ * fires when its modifiers match exactly, its `when` holds, its scope contains
+ * the event's target, and the focus is not in a text field (unless
+ * `allowInEditable`). The most recently bound match is the only one that fires,
+ * so a modal's `"/"` overrides the page's and unbinding it brings the page's
+ * back; `preventDefault` is on by default for the bindings whose chord the
+ * browser would otherwise act on (Cmd/Ctrl+S, Cmd/Ctrl+K).
+ */
+export declare const createHotkeys: (options?: HotkeysOptions) => Hotkeys;
 export interface LinkOptions {
   readonly href?: string | undefined;
   /** Render a native `<a href>` (the default when `href` is set). */
@@ -2601,6 +2770,76 @@ export interface ResizablePanels {
  * DOM is checked against it by the differential walk.
  */
 export declare const createResizablePanels: (options: ResizablePanelsOptions) => ResizablePanels;
+export interface ScrollspyEntry {
+  readonly id: string;
+  readonly label: string;
+}
+export interface ScrollspyOptions {
+  /** The table of contents, in document order. The heading elements carry these ids. */
+  readonly entries: ReadonlyArray<ScrollspyEntry>;
+  /**
+   * How far below the scrollport's top edge a heading counts as current, in px.
+   * A host with a sticky header passes its height. @default 0
+   */
+  readonly offset?: number | undefined;
+  /**
+   * The scroll container; the document by default. Read once, when `attach`
+   * runs, so a host that swaps containers attaches again.
+   */
+  readonly root?: (() => HTMLElement | undefined) | undefined;
+  /** The active id changed. */
+  readonly onChange?: ((id: string | undefined) => void) | undefined;
+}
+export interface ScrollspyNavProps {
+  /** The navigation landmark's name; the host overrides it after the spread to translate it. */
+  readonly "aria-label": string;
+}
+export interface ScrollspyListProps {
+  readonly role: "list";
+}
+export interface ScrollspyItemProps {
+  readonly role: "listitem";
+}
+export interface ScrollspyLinkProps {
+  readonly href: string;
+  readonly "aria-current": "location" | undefined;
+}
+export interface Scrollspy {
+  /** The current entry's id; `undefined` only when there are no entries. */
+  readonly active: Accessor<string | undefined>;
+  readonly navProps: ScrollspyNavProps;
+  readonly listProps: ScrollspyListProps;
+  readonly itemProps: (id: string) => ScrollspyItemProps;
+  readonly linkProps: (id: string) => ScrollspyLinkProps;
+  /**
+   * DOM wiring: one passive `scroll` listener on the root, which measures the
+   * headings. Call it once mounted and call the teardown it returns on cleanup.
+   */
+  readonly attach: () => () => void;
+}
+/**
+ * A scrollspy: a table of contents whose current entry is the last heading that
+ * has reached the top of the scrollport, marked `aria-current="location"` on
+ * its link (and nowhere else: exactly one link is current).
+ *
+ * **No APG pattern exists for a scrollspy**, so there is no Quint spec and no
+ * ported scenarios: the contract is WAI-ARIA (`aria-current="location"`, the
+ * `list` / `listitem` roles, the navigation landmark and its name) and HTML,
+ * and `test/scrollspy.browser.test.tsx` is its oracle.
+ *
+ * **A scroll listener, not an `IntersectionObserver`.** "The last heading at or
+ * above the offset" is a total order over every heading, while an observer only
+ * reports what crossed its band: a band observer has to rebuild the order from
+ * its enter/leave state, and it misreports after a jump (an anchor click, a
+ * restored scroll position). The listener is passive, the measurements are
+ * reads only (no writes, so no layout thrash), and a docs page has a dozen
+ * headings — the same cost as the listener the page already keeps.
+ *
+ * Smooth scrolling is the host's (`scroll-behavior: smooth`): the links are
+ * plain `#id` targets and nothing here moves the scrollport, so no
+ * `prefers-reduced-motion` branch is needed either.
+ */
+export declare const createScrollspy: (options: ScrollspyOptions) => Scrollspy;
 export type SliderOrientation = "horizontal" | "vertical";
 export type SliderDirection = "ltr" | "rtl";
 export interface SliderOptions {

package/dist/index.mjs

@@ -3266,6 +3266,304 @@ const createPagination = (options) => {
 		}
 	};
 };
+// src/panzoom.ts
+/** Arrow-key pan distance, in CSS px; Shift multiplies it. */
+const PAN_STEP = 24;
+const PAN_SHIFT = 4;
+/** A ctrl/meta wheel notch. */
+const WHEEL_FACTOR = 1.1;
+const axis = (value, limit) => Math.min(limit, Math.max(-limit, value));
+/**
+* Pan and zoom for one image in a viewport: scale, offset and the prop objects
+* for a focusable viewport, the transformed image and a live value.
+*
+* **There is no APG pattern for pan-zoom.** The accessible contract is the three
+* parts this returns: a viewport that takes focus (`role=group`, `tabindex=0`,
+* `aria-roledescription="zoomable image"`), keyboard operations that stand in
+* for every pointer gesture (`+` / `=` / `-` zoom, arrows pan, `0` resets), and a
+* polite live region (`aria-describedby` of the viewport) that carries the
+* current scale. The pointer gestures are an addition for mouse and touch, never
+* the only way in. That contract is this module's own: the case it replaces
+* (kocharin-art-3's `Zoomable`, ~110 lines of pointer maths) had no keyboard path
+* and no ARIA at all, and `createCanvas` is the wrong model here — an infinite
+* canvas moves a camera over a world, while this is one image fitted to its
+* viewport.
+*
+* Wheel is zoom-with-a-modifier only: `ctrl` / `meta` (the browser's own pinch
+* arrives as `ctrl+wheel`) zooms about the cursor; a bare wheel is never
+* `preventDefault`ed, so the page keeps scrolling. Trackpad gestures differ per
+* platform and a swallowed wheel is the one thing that is never acceptable.
+*
+* Pointer: a drag pans, a second pointer pinches (about its midpoint), a double
+* click resets. Capture is best-effort (a synthetic pointer cannot be captured).
+*
+* `bounds: "clamp"` bounds the offset by half the viewport's scaled overflow, so
+* the image is expected to fill the viewport at `min` (the usual
+* `width: 100%; height: 100%` / `object-fit: cover` box). A letterboxed image
+* smaller than its viewport cannot be held gap-free; give it a viewport of its
+* own or `bounds: "free"`.
+*
+* Request/commit (`rt1p`): uncontrolled by default (`defaultScale`); pass `scale`
+* + `onScaleChange` to own the value. The offset has no controlled prop, so a
+* hosting page that rejects a scale request also gets the offset resolved for the
+* scale it refused — accept the request, or pass `bounds: "free"` and own the
+* pan elsewhere.
+*
+* The host owns the box and the looks: size the viewport, put `touch-action:
+* none` on it if a touch drag should pan, centre the image
+* (`transform-origin: 50% 50%` is the default this maths assumes), and hide the
+* live region visually rather than with `hidden` (a `hidden` live region is not
+* announced).
+*/
+const createPanZoom = (options = {}) => {
+	const min = options.min ?? 1;
+	const max = options.max ?? 4;
+	const step = options.step ?? .25;
+	const bounds = () => options.bounds ?? "clamp";
+	const valueId = createUniqueId();
+	const clamp = (next) => Math.min(max, Math.max(min, next));
+	const [scale, requestScale] = createControllable({
+		value: () => options.scale,
+		initial: clamp(options.defaultScale ?? min),
+		onChange: () => options.onScaleChange
+	});
+	const [version, setVersion] = createSignal(0);
+	let last = {
+		x: 0,
+		y: 0
+	};
+	const offset = () => {
+		version();
+		return last;
+	};
+	const setOffset = (next) => {
+		last = next;
+		setVersion((count) => count + 1);
+	};
+	let box = {
+		left: 0,
+		top: 0,
+		width: 0,
+		height: 0
+	};
+	const measure = (event) => {
+		if (!(event.currentTarget instanceof Element)) return;
+		const rect = event.currentTarget.getBoundingClientRect();
+		box = {
+			left: rect.left,
+			top: rect.top,
+			width: rect.width,
+			height: rect.height
+		};
+	};
+	const limits = (at) => ({
+		x: Math.max(0, box.width * (at - 1) / 2),
+		y: Math.max(0, box.height * (at - 1) / 2)
+	});
+	const move = (next, at = scale()) => {
+		const allowed = limits(at);
+		const target = bounds() === "free" ? next : {
+			x: axis(next.x, allowed.x),
+			y: axis(next.y, allowed.y)
+		};
+		const previous = offset();
+		if (target.x === previous.x && target.y === previous.y) return;
+		setOffset(target);
+		options.onPanChange?.(target);
+	};
+	const setScale = (next, origin) => {
+		const before = scale();
+		const target = clamp(next);
+		if (target === before) return;
+		requestScale(target);
+		const at = origin ?? {
+			x: box.width / 2,
+			y: box.height / 2
+		};
+		const o = {
+			x: at.x - box.width / 2,
+			y: at.y - box.height / 2
+		};
+		const ratio = before > 0 ? target / before : 1;
+		const current = offset();
+		move({
+			x: o.x - (o.x - current.x) * ratio,
+			y: o.y - (o.y - current.y) * ratio
+		}, target);
+	};
+	const zoomIn = () => setScale(scale() + step);
+	const zoomOut = () => setScale(scale() - step);
+	const reset = () => {
+		requestScale(min);
+		move({
+			x: 0,
+			y: 0
+		}, min);
+	};
+	const pointers = /* @__PURE__ */ new Map();
+	let drag;
+	let pinch;
+	const distance = () => {
+		const [a, b] = [...pointers.values()];
+		return a === void 0 || b === void 0 ? 0 : Math.hypot(a.x - b.x, a.y - b.y);
+	};
+	const midpoint = () => {
+		const [a, b] = [...pointers.values()];
+		if (a === void 0 || b === void 0) return {
+			x: box.left + box.width / 2,
+			y: box.top + box.height / 2
+		};
+		return {
+			x: (a.x + b.x) / 2,
+			y: (a.y + b.y) / 2
+		};
+	};
+	const local = (point) => ({
+		x: point.x - box.left,
+		y: point.y - box.top
+	});
+	const pointerDown = (event) => {
+		measure(event);
+		if (event.button !== 0) return;
+		try {
+			if (event.currentTarget instanceof Element) event.currentTarget.setPointerCapture(event.pointerId);
+		} catch {}
+		const at = {
+			x: event.clientX,
+			y: event.clientY
+		};
+		pointers.set(event.pointerId, at);
+		drag = {
+			at,
+			from: offset()
+		};
+		if (pointers.size === 2) pinch = {
+			distance: distance(),
+			scale: scale()
+		};
+	};
+	const pointerMove = (event) => {
+		if (!pointers.has(event.pointerId)) return;
+		pointers.set(event.pointerId, {
+			x: event.clientX,
+			y: event.clientY
+		});
+		if (pointers.size === 2 && pinch !== void 0) {
+			if (pinch.distance > 0) setScale(pinch.scale * (distance() / pinch.distance), local(midpoint()));
+			return;
+		}
+		if (drag !== void 0) move({
+			x: drag.from.x + event.clientX - drag.at.x,
+			y: drag.from.y + event.clientY - drag.at.y
+		});
+	};
+	const pointerUp = (event) => {
+		pointers.delete(event.pointerId);
+		pinch = void 0;
+		const rest = [...pointers.values()][0];
+		drag = rest === void 0 ? void 0 : {
+			at: rest,
+			from: offset()
+		};
+	};
+	const wheel = (event) => {
+		if (!event.ctrlKey && !event.metaKey) return;
+		event.preventDefault();
+		measure(event);
+		const factor = event.deltaY < 0 ? WHEEL_FACTOR : 1 / WHEEL_FACTOR;
+		setScale(scale() * factor, {
+			x: event.clientX - box.left,
+			y: event.clientY - box.top
+		});
+	};
+	const keyDown = (event) => {
+		measure(event);
+		const by = PAN_STEP * (event.shiftKey ? PAN_SHIFT : 1);
+		const current = offset();
+		switch (event.key) {
+			case "+":
+			case "=":
+				zoomIn();
+				break;
+			case "-":
+			case "_":
+				zoomOut();
+				break;
+			case "0":
+				reset();
+				break;
+			case "ArrowLeft":
+				move({
+					x: current.x - by,
+					y: current.y
+				});
+				break;
+			case "ArrowRight":
+				move({
+					x: current.x + by,
+					y: current.y
+				});
+				break;
+			case "ArrowUp":
+				move({
+					x: current.x,
+					y: current.y - by
+				});
+				break;
+			case "ArrowDown":
+				move({
+					x: current.x,
+					y: current.y + by
+				});
+				break;
+			default: return;
+		}
+		event.preventDefault();
+	};
+	return {
+		scale,
+		offset,
+		reset,
+		zoomIn,
+		zoomOut,
+		setScale,
+		value: () => `${Math.round(scale() * 100)}%`,
+		viewportProps: {
+			tabindex: 0,
+			role: "group",
+			"aria-roledescription": "zoomable image",
+			get "aria-label"() {
+				return options.labels?.viewport ?? "Image";
+			},
+			get "aria-describedby"() {
+				return valueId;
+			},
+			onKeyDown: keyDown,
+			onWheel: wheel,
+			onPointerDown: pointerDown,
+			onPointerMove: pointerMove,
+			onPointerUp: pointerUp,
+			onPointerCancel: pointerUp,
+			onDblClick: (event) => {
+				measure(event);
+				reset();
+			}
+		},
+		imageProps: {
+			draggable: false,
+			get style() {
+				const at = offset();
+				return { transform: `translate(${at.x}px, ${at.y}px) scale(${scale()})` };
+			}
+		},
+		valueProps: {
+			id: valueId,
+			role: "status",
+			"aria-live": "polite",
+			"aria-atomic": "true"
+		}
+	};
+};
 // src/popover.ts
 const FLIPPED = {
 	"bottom-start": "top-start",
@@ -3833,6 +4131,109 @@ const createGrid = (options = {}) => {
 		}
 	};
 };
+// src/hotkeys.ts
+const MODIFIERS = /* @__PURE__ */ new Set([
+	"mod",
+	"ctrl",
+	"alt",
+	"shift",
+	"meta"
+]);
+const SHIFTED = /* @__PURE__ */ new Set("~!@#$%^&*()_+{}|:\"<>?");
+const detectsApple = () => typeof navigator !== "undefined" && /Mac|iPhone|iPad|iPod/.test(navigator.platform || navigator.userAgent);
+const parse = (keys, isApple) => {
+	const parts = keys.toLowerCase().split("+");
+	const key = parts.pop() ?? "";
+	if (key === "" || MODIFIERS.has(key)) throw new TypeError(`hotkeys: "${keys}" ends with no key`);
+	const chord = {
+		ctrl: false,
+		meta: false,
+		alt: false,
+		shift: SHIFTED.has(key),
+		key
+	};
+	for (const part of parts) switch (part) {
+		case "mod":
+			if (isApple) chord.meta = true;
+			else chord.ctrl = true;
+			break;
+		case "ctrl":
+			chord.ctrl = true;
+			break;
+		case "meta":
+			chord.meta = true;
+			break;
+		case "alt":
+			chord.alt = true;
+			break;
+		case "shift":
+			chord.shift = true;
+			break;
+		default: throw new TypeError(`hotkeys: "${part}" in "${keys}" is not a modifier`);
+	}
+	return chord;
+};
+const matches = (chord, event) => event.key.toLowerCase() === chord.key && event.ctrlKey === chord.ctrl && event.metaKey === chord.meta && event.altKey === chord.alt && event.shiftKey === chord.shift;
+const editable = (target) => target instanceof HTMLElement && (target.tagName === "INPUT" || target.tagName === "TEXTAREA" || target.isContentEditable);
+const inScope = (scope, target) => scope === void 0 || target instanceof Node && scope.contains(target);
+/**
+* One `keydown` listener in the capture phase, one list of chords. A chord
+* fires when its modifiers match exactly, its `when` holds, its scope contains
+* the event's target, and the focus is not in a text field (unless
+* `allowInEditable`). The most recently bound match is the only one that fires,
+* so a modal's `"/"` overrides the page's and unbinding it brings the page's
+* back; `preventDefault` is on by default for the bindings whose chord the
+* browser would otherwise act on (Cmd/Ctrl+S, Cmd/Ctrl+K).
+*/
+const createHotkeys = (options = {}) => {
+	const isApple = options.isApple ?? detectsApple();
+	const bindings = [];
+	let listening = false;
+	let disposed = false;
+	const onKeyDown = (event) => {
+		for (let i = bindings.length - 1; i >= 0; i--) {
+			const entry = bindings[i];
+			if (entry === void 0) continue;
+			const { chord, binding } = entry;
+			if (!matches(chord, event) || binding.when?.() === false) continue;
+			if (!inScope(binding.scope, event.target)) continue;
+			if (binding.allowInEditable !== true && editable(event.target)) continue;
+			if (binding.preventDefault !== false) event.preventDefault();
+			binding.onTrigger(event);
+			return;
+		}
+	};
+	const stop = () => {
+		if (!listening) return;
+		listening = false;
+		document.removeEventListener("keydown", onKeyDown, true);
+	};
+	return {
+		bind: (binding) => {
+			if (disposed) return () => {};
+			const entry = {
+				chord: parse(binding.keys, isApple),
+				binding
+			};
+			bindings.push(entry);
+			if (!listening) {
+				listening = true;
+				document.addEventListener("keydown", onKeyDown, true);
+			}
+			return () => {
+				const at = bindings.indexOf(entry);
+				if (at === -1) return;
+				bindings.splice(at, 1);
+				if (bindings.length === 0) stop();
+			};
+		},
+		dispose: () => {
+			disposed = true;
+			bindings.length = 0;
+			stop();
+		}
+	};
+};
 // src/link.ts
 /**
 * APG Link (https://www.w3.org/WAI/ARIA/apg/patterns/link/): a native `<a href>`
@@ -5449,6 +5850,69 @@ const createResizablePanels = (options) => {
 		separatorProps
 	};
 };
+// src/scrollspy.ts
+/**
+* A scrollspy: a table of contents whose current entry is the last heading that
+* has reached the top of the scrollport, marked `aria-current="location"` on
+* its link (and nowhere else: exactly one link is current).
+*
+* **No APG pattern exists for a scrollspy**, so there is no Quint spec and no
+* ported scenarios: the contract is WAI-ARIA (`aria-current="location"`, the
+* `list` / `listitem` roles, the navigation landmark and its name) and HTML,
+* and `test/scrollspy.browser.test.tsx` is its oracle.
+*
+* **A scroll listener, not an `IntersectionObserver`.** "The last heading at or
+* above the offset" is a total order over every heading, while an observer only
+* reports what crossed its band: a band observer has to rebuild the order from
+* its enter/leave state, and it misreports after a jump (an anchor click, a
+* restored scroll position). The listener is passive, the measurements are
+* reads only (no writes, so no layout thrash), and a docs page has a dozen
+* headings — the same cost as the listener the page already keeps.
+*
+* Smooth scrolling is the host's (`scroll-behavior: smooth`): the links are
+* plain `#id` targets and nothing here moves the scrollport, so no
+* `prefers-reduced-motion` branch is needed either.
+*/
+const createScrollspy = (options) => {
+	const offset = options.offset ?? 0;
+	const first = options.entries[0]?.id;
+	const [active, setActive] = createSignal(first);
+	const at = () => {
+		const container = options.root?.()?.getBoundingClientRect().top ?? 0;
+		let id = first;
+		for (const entry of options.entries) {
+			const element = document.getElementById(entry.id);
+			if (element === null) continue;
+			if (element.getBoundingClientRect().top - container <= offset) id = entry.id;
+		}
+		return id;
+	};
+	const commit = () => {
+		const next = at();
+		if (next === active()) return;
+		setActive(next);
+		options.onChange?.(next);
+	};
+	return {
+		active,
+		navProps: { "aria-label": "On this page" },
+		listProps: { role: "list" },
+		itemProps: () => ({ role: "listitem" }),
+		linkProps: (id) => ({
+			href: `#${id}`,
+			get "aria-current"() {
+				return id === active() ? "location" : void 0;
+			}
+		}),
+		attach: () => {
+			const target = options.root?.() ?? document;
+			const listener = () => commit();
+			target.addEventListener("scroll", listener, { passive: true });
+			commit();
+			return () => target.removeEventListener("scroll", listener);
+		}
+	};
+};
 // src/slider.ts
 const valueTextFor$1 = (value) => value <= 3 ? "low" : value <= 7 ? "medium" : "high";
 /**
@@ -8361,4 +8825,4 @@ const createRearrangeableListbox = (options) => {
 		})
 	};
 };
-export { ConfirmPendingError, DEFAULT_PREFS, DRAG_PX, GRID, NO_POS, SNAP_PX, TONE, TREEVIEW_NODES, TWEEN_TICKS, WORLD_BOUND, YES_POS, ZMAX, ZMIN, ZONE, cellPart, createAccordion, createAlert, createAlertDialog, createBreadcrumb, createButton, createCanvas, createCarousel, createCheckbox, createCheckboxGroup, createCombobox, createConfirm, createDialogModal, createDisclosure, createDrawer, createFeed, createField, createGrid, createLink, createListbox, createMenu, createMenubar, createMeter, createPagination, createPlayer, createPopover, createRadioGroup, createRearrangeableListbox, createResizablePanels, createSlider, createSliderMultiThumb, createSpinbutton, createStatus, createSwitch, createTable, createTabs, createTextArea, createTextInput, createTimeline, createToast, createToolbar, createTooltipGroup, createTreegrid, createTreeview, createWindowSplitter, gridCandidates, headerPart, packSelection, packSort, rowPart, treegridCellPart, treegridFocusTargetPart, treegridRowPart, withPrefs };
+export { ConfirmPendingError, DEFAULT_PREFS, DRAG_PX, GRID, NO_POS, SNAP_PX, TONE, TREEVIEW_NODES, TWEEN_TICKS, WORLD_BOUND, YES_POS, ZMAX, ZMIN, ZONE, cellPart, createAccordion, createAlert, createAlertDialog, createBreadcrumb, createButton, createCanvas, createCarousel, createCheckbox, createCheckboxGroup, createCombobox, createConfirm, createDialogModal, createDisclosure, createDrawer, createFeed, createField, createGrid, createHotkeys, createLink, createListbox, createMenu, createMenubar, createMeter, createPagination, createPanZoom, createPlayer, createPopover, createRadioGroup, createRearrangeableListbox, createResizablePanels, createScrollspy, createSlider, createSliderMultiThumb, createSpinbutton, createStatus, createSwitch, createTable, createTabs, createTextArea, createTextInput, createTimeline, createToast, createToolbar, createTooltipGroup, createTreegrid, createTreeview, createWindowSplitter, gridCandidates, headerPart, packSelection, packSort, rowPart, treegridCellPart, treegridFocusTargetPart, treegridRowPart, withPrefs };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cssints/headless",
-  "version": "0.17.0",
+  "version": "0.18.0",
   "description": "Headless APG widgets on Solid 2: state plus attribute objects, no elements, no styling, each conformance-checked against its Quint spec",
   "license": "MIT",
   "repository": {