@cssints/headless 0.15.0 → 0.18.0

package/dist/index.d.mts

@@ -1374,7 +1374,9 @@ export declare class ConfirmPendingError extends Error {
  * Nesting: confirms from different `createConfirm` calls may be open together;
  * only the last one opened gets Escape and Tab (and Escape does not reach a
  * dialog it sits in), and the scroll lock is counted: the first takes it, the
- * last to close restores what `overflow` was. One confirm still has one request.
+ * last to close restores what `overflow` was. `createDrawer` claims the same
+ * page-wide stack and lock, so a confirm over a drawer (or the reverse) nests
+ * the same way. One confirm still has one request.
  *
  * One request at a time: a second `confirm()` while one is pending is rejected,
  * not queued. Queued, a double click on "Delete" would ask twice and a stale
@@ -1382,6 +1384,119 @@ export declare class ConfirmPendingError extends Error {
  * answered `false` when the owner is disposed.
  */
 export declare const createConfirm: (options?: ConfirmOptions) => Confirm;
+/** The edge a drawer occupies. `side()` reads the option at call time. */
+export type DrawerSide = "left" | "right" | "bottom";
+export interface DrawerOptions {
+  /** Base for the generated trigger / content / backdrop ids. */
+  readonly id?: string | undefined;
+  /** Controlled: the host owns the open state and this is the only thing that changes it. */
+  readonly open?: boolean | undefined;
+  /** Uncontrolled starting state; ignored while `open` is set. */
+  readonly defaultOpen?: boolean | undefined;
+  /**
+   * The edge the panel is anchored to. @default "right"
+   *
+   * Presentation only: a `bottom` panel is a sheet, `left` / `right` is a side
+   * rail, and the same drawer is one API either way.
+   */
+  readonly side?: DrawerSide | undefined;
+  /**
+   * Whether the panel is modal: `aria-modal`, the Tab cycle, the scroll lock and
+   * the backdrop. @default true
+   *
+   * This is the switch a breakpoint flips: below it a panel is a sheet and
+   * modal, above it a side rail may not be. It is read on every attribute read,
+   * so the host may change it while the drawer is open (crossing the
+   * breakpoint) and the backdrop, `aria-modal` and the lock follow.
+   */
+  readonly modal?: boolean | undefined;
+  /**
+   * The width in px at which the host switches `side` and `modal` (a sheet
+   * below it, a dialog above). **Not read here**: the primitive has no viewport
+   * to measure and no `matchMedia`, so it only documents the pattern, and the
+   * host watches the breakpoint and passes `modal` / `side`. A host that wants
+   * the sheet drag behaviour composes CSS scroll snap around this, as
+   * [docs/bottom-sheet.md](../docs/bottom-sheet.md) lays out.
+   */
+  readonly breakpoint?: number | undefined;
+  /** A backdrop click or an outside `pointerdown` closes the drawer. @default true */
+  readonly dismissable?: boolean | undefined;
+  /** Id of the element naming the panel (`aria-labelledby`); a dialog without a name is unusable. */
+  readonly labelledby?: string | undefined;
+  /** A request to change the open state, called when the intent differs. */
+  readonly onOpenChange?: ((open: boolean) => void) | undefined;
+}
+export interface DrawerTriggerProps {
+  readonly id: string;
+  readonly "aria-haspopup": "dialog";
+  readonly "aria-expanded": "true" | "false";
+  readonly "aria-controls": string;
+  readonly onClick: () => void;
+  readonly onKeyDown: (event: KeyboardEvent) => void;
+}
+export interface DrawerBackdropProps {
+  readonly id: string;
+  /** Always hidden when the drawer is closed or not modal: a non-modal drawer keeps the page clickable. */
+  readonly hidden: boolean;
+  readonly onClick: () => void;
+}
+export interface DrawerContentProps {
+  readonly id: string;
+  readonly role: "dialog";
+  readonly "aria-modal": "true" | undefined;
+  readonly "aria-labelledby": string | undefined;
+  readonly tabindex: -1;
+  readonly hidden: boolean;
+  readonly onKeyDown: (event: KeyboardEvent) => void;
+}
+/** A bottom sheet's grab handle. Decorative: there is no drag, so it says nothing. */
+export interface DrawerHandleProps {
+  readonly "aria-hidden": "true";
+}
+export interface Drawer {
+  readonly open: Accessor<boolean>;
+  readonly side: Accessor<DrawerSide>;
+  readonly triggerProps: DrawerTriggerProps;
+  readonly backdropProps: DrawerBackdropProps;
+  readonly contentProps: DrawerContentProps;
+  readonly handleProps: DrawerHandleProps;
+}
+/**
+ * The shell for a drawer / bottom sheet: an edge-anchored panel over the
+ * Dialog (Modal) semantics (https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/),
+ * with the same shell as `createConfirm` — focus into the panel on open and back
+ * to the trigger on close, Tab cycling while modal, Escape read from the
+ * document (so it closes wherever focus is), a counted scroll lock and an
+ * outside dismissal.
+ *
+ * **Compose, do not add a sheet primitive.** [docs/bottom-sheet.md](../docs/bottom-sheet.md)
+ * settled it: the semantics are Dialog (Modal), the position, the slide and the
+ * snap points are the host's CSS (native scroll snap), and the panel that both
+ * need is this shell. `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 }`.
+ *
+ * **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 belongs to the host's
+ * scroll-snap CSS (see bottom-sheet.md: `scroll-snap-type: y mandatory`, snap
+ * markers, `scrollsnapchange`). Mirroring a native snap in JS would be the
+ * gesture re-implementation that the platform research forbids, and a pointer
+ * gesture would exist on top of the snap that already moved the panel. So the
+ * handle is decoration (`aria-hidden`, no pointer handlers): the ways out are
+ * the backdrop, Escape, the close control the host puts in the panel, and the
+ * trigger. Swipe-to-dismiss is a separate decision with its own oracle.
+ *
+ * The panel is edge-anchored, so there is **no `attach`**: nothing is measured
+ * and no placement is computed. Focus and Tab find the panel through
+ * `contentProps.id`, like `createConfirm` does, so the host only spreads
+ * attributes onto its own elements.
+ *
+ * Not checked against a Quint spec: the dialog is, and this is its shell, so
+ * `test/drawer.browser.test.tsx` is the oracle. A pointerdown outside the panel
+ * closes it when `dismissable` (that is the backdrop click too, and the only
+ * dismissal a non-modal drawer has); closing returns focus to the trigger.
+ */
+export declare const createDrawer: (options?: DrawerOptions) => Drawer;
 /**
  * Options are read lazily (getters); pass a component's `props`.
  */
@@ -1642,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 {
@@ -1912,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). */
@@ -2486,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 {
@@ -2797,6 +3151,182 @@ export interface Switch {
  * pass `value` + `onValueChange` to own the state.
  */
 export declare const createSwitch: (options?: SwitchOptions) => Switch;
+/**
+ * A data table on Solid 2: sortable column headers and row selection, as state
+ * plus getter-backed attribute objects; no elements, no styling.
+ *
+ * **The host renders a native `<table>`**: `<caption>`, `<thead>`, `<tbody>`,
+ * `<th scope="col">` and `<td>` carry the semantics, so the primitive adds no
+ * `role` and no `aria-rowindex` — only what a native table cannot say itself
+ * (which column is sorted, whether a row is selected, the mixed select-all
+ * state, and the totals a windowed table hides).
+ *
+ * **Sorting is the host's data.** The primitive carries the sort descriptor and
+ * announces it (`aria-sort`); it never sorts. The host maps `sort()` onto its
+ * own array before rendering `rows`.
+ *
+ * Composes the two state models the package already has — `grid-sort.qnt` and
+ * `grid-selection.qnt` — without their navigation: a table is a grid with a
+ * `th[scope]` header row, and the cells keep their own focus.
+ *
+ * Request/commit (map ticket `rt1p`): the sort and the selection are
+ * uncontrolled by default (`defaultSort` / `defaultSelected`) and can be owned
+ * by the host with `sort` + `onSortChange` / `selected` + `onSelectionChange`.
+ * `null` as `sort` is "no column sorted" (in a controlled host); `undefined` is
+ * "uncontrolled". `toggleRow`, `toggleAll` and the header button are requests:
+ * a controlled host may ignore them.
+ */
+export type TableSortDirection = "ascending" | "descending";
+export type TableSelectionMode = "none" | "single" | "multiple";
+/**
+ * `"tri-state"`: ascending -> descending -> unsorted, so a table can be put back
+ * in its own order (the bean's requirement). `"toggle"`: ascending <-> descending,
+ * never unsorted, which is what the APG grid example (and `grid-sort.qnt`) does.
+ */
+export type TableSortCycle = "tri-state" | "toggle";
+export interface TableSort {
+  readonly key: string;
+  readonly direction: TableSortDirection;
+}
+export interface TableColumn {
+  /** Identity of the column: what `cellProps` and `headerCellProps` are asked for. */
+  readonly key: string;
+  /** Defaults to `true`; `false` makes the header inert (no sort button, no `aria-sort`). */
+  readonly sortable?: boolean | undefined;
+  /**
+   * A layout hint for the host's skin (right-aligned, tabular figures). HTML has
+   * no attribute for it, so the primitive carries nothing.
+   */
+  readonly numeric?: boolean | undefined;
+  /** The `abbr` of the header cell: the short form a screen reader uses. */
+  readonly abbr?: string | undefined;
+}
+export interface TableLabels {
+  /** The table's accessible name; a host that renders a `<caption>` leaves it out. */
+  readonly table?: string | undefined;
+  /** Defaults to "Select all rows". */
+  readonly selectAll?: string | undefined;
+  /** Defaults to `Select row <id>`. */
+  readonly selectRow?: ((id: string) => string) | undefined;
+}
+export interface TableOptions {
+  readonly columns: ReadonlyArray<TableColumn>;
+  /**
+   * The row ids the host renders, in render order. Ids, not a count: the sort
+   * reorders the host's data and a selection must survive that, while an index
+   * would then name a different row. The row's visible content stays the host's.
+   */
+  readonly rows: ReadonlyArray<string>;
+  readonly selection?: TableSelectionMode | undefined;
+  readonly sortCycle?: TableSortCycle | undefined;
+  /** Controlled: the host owns the sort and this is the only thing that changes it; `null` is "unsorted". */
+  readonly sort?: TableSort | null | undefined;
+  /** Uncontrolled starting sort; ignored while `sort` is set. */
+  readonly defaultSort?: TableSort | undefined;
+  /** A request to re-sort (`undefined` = unsorted); uncontrolled it is accepted. */
+  readonly onSortChange?: ((sort: TableSort | undefined) => void) | undefined;
+  /** Controlled: the host owns the selected row ids and this is the only thing that changes them. */
+  readonly selected?: ReadonlyArray<string> | undefined;
+  /** Uncontrolled starting selection; ignored while `selected` is set. */
+  readonly defaultSelected?: ReadonlyArray<string> | undefined;
+  /** A request to change the selection; uncontrolled it is accepted. */
+  readonly onSelectionChange?: ((selected: ReadonlyArray<string>) => void) | undefined;
+  /**
+   * The total row count when the host renders a window of `rows`
+   * (`aria-rowcount`); absent on a table that renders all of them.
+   */
+  readonly rowCount?: number | undefined;
+  /**
+   * The total column count when the host renders a window of `columns`
+   * (`aria-colcount` and `aria-colindex`); absent on a table that renders all.
+   */
+  readonly columnCount?: number | undefined;
+  readonly labels?: TableLabels | undefined;
+  /** Base for generated ids. */
+  readonly id?: string | undefined;
+}
+/** Spread onto `<table>`; the host renders the table, the head and the body. */
+export interface TableProps {
+  /** `labels.table`; leave it out when the host renders a caption. */
+  readonly "aria-label": string | undefined;
+  /** Only while the host windows its rows. */
+  readonly "aria-rowcount": number | undefined;
+  /** Only while the host windows its columns. */
+  readonly "aria-colcount": number | undefined;
+}
+/** Spread onto `<caption>`. */
+export interface TableCaptionProps {
+  readonly id: string;
+}
+/** Spread onto `<th scope="col">` in the header row. */
+export interface TableHeaderCellProps {
+  readonly scope: "col";
+  /** The sorted column only; an unsorted one carries nothing (ARIA's default). */
+  readonly "aria-sort": TableSortDirection | undefined;
+  readonly abbr: string | undefined;
+}
+/** Spread onto the `<button type="button">` inside a sortable `<th>`. */
+export interface TableHeaderButtonProps {
+  readonly type: "button";
+  readonly onClick: () => void;
+}
+/** Spread onto `<tr>` in the body. */
+export interface TableRowProps {
+  readonly "aria-selected": "true" | "false" | undefined;
+  /** Selects the row; `undefined` when nothing is selectable. */
+  readonly onClick: (() => void) | undefined;
+}
+/** Spread onto a `<td>`; `aria-colindex` only while the host windows its columns. */
+export interface TableCellProps {
+  readonly "aria-colindex": number | undefined;
+}
+/**
+ * Spread onto the select-all control: a `role=checkbox` element (not a native
+ * `input`, which spells the mixed state as a DOM property, not an attribute).
+ */
+export interface TableSelectAllProps {
+  readonly role: "checkbox";
+  readonly "aria-checked": "true" | "false" | "mixed";
+  readonly "aria-label": string;
+  readonly tabindex: 0;
+  readonly onClick: () => void;
+  readonly onKeyDown: (event: KeyboardEvent) => void;
+}
+/** Spread onto a row's selection control. */
+export interface TableRowCheckboxProps {
+  readonly role: "checkbox";
+  readonly "aria-checked": "true" | "false";
+  readonly "aria-label": string;
+  readonly tabindex: 0;
+  /** Selects the row and stops there: the control sits inside the row, whose click would select again. */
+  readonly onClick: (event: MouseEvent) => void;
+  readonly onKeyDown: (event: KeyboardEvent) => void;
+}
+export interface Table {
+  readonly selectionMode: Accessor<TableSelectionMode>;
+  /** The sort descriptor, or `undefined` when nothing is sorted. */
+  readonly sort: Accessor<TableSort | undefined>;
+  readonly selected: Accessor<ReadonlyArray<string>>;
+  readonly isSelected: (id: string) => boolean;
+  readonly tableProps: TableProps;
+  readonly captionProps: TableCaptionProps;
+  readonly headerCellProps: (key: string) => TableHeaderCellProps;
+  /** `undefined` for a column that is not sortable — render no button there. */
+  readonly headerButtonProps: (key: string) => TableHeaderButtonProps | undefined;
+  readonly rowProps: (id: string) => TableRowProps;
+  readonly cellProps: (rowId: string, key: string) => TableCellProps;
+  /** `undefined` unless `selection` is `"multiple"`: one control over one selection is meaningless. */
+  readonly selectAllProps: TableSelectAllProps | undefined;
+  /** `undefined` while `selection` is `"none"`. */
+  readonly rowCheckboxProps: (id: string) => TableRowCheckboxProps | undefined;
+  readonly toggleAll: () => void;
+  readonly toggleRow: (id: string) => void;
+}
+/**
+ * Every option is read when an attribute is read, so pass props/getters, never a
+ * destructured snapshot. `id` is captured once: it is the base of the caption id.
+ */
+export declare const createTable: (options: TableOptions) => Table;
 /** The HTML `autocomplete` tokens worth naming; the attribute also takes an arbitrary token. */
 export type AutoCompleteToken = "off" | "on" | "name" | "given-name" | "family-name" | "username" | "email" | "tel" | "url" | "organization" | "street-address" | "postal-code" | "current-password" | "new-password" | "one-time-code" | "nickname";
 export interface TextInputOptions extends FieldOptions {