@cssints/headless 0.15.0 → 0.17.0

package/README.md

@@ -65,7 +65,7 @@ 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, 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, 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.
 
@@ -189,6 +189,70 @@ const pages = createPagination({ page: 3, pageCount: 12, hrefFor: (page) => `/is
 - **`hrefFor` is what makes it work without JS**: with it every page is a real link; without it they are buttons and the host owns navigation.
 - **Target size is the skin's job**: 24x24 CSS px at AA, 44x44 at AAA.
 
+## Table
+
+`createTable` is sortable column headers and row selection on a **native `<table>`**: a `<caption>`, `<thead>`, `<tbody>`, `<th scope="col">` and `<td>` carry the semantics, so the primitive adds no `role` and no `aria-rowindex`, only what the elements cannot say themselves (`aria-sort` on the sorted column, `aria-selected` on a row, the mixed select-all state, and the totals a windowed table hides). It is a grid with a header row but **without the grid's navigation**: the cells keep their own focus, and `createGrid` stays the widget for roving cell focus. There is no spec of its own — it composes the two state models the package already has, `grid-sort.qnt` and `grid-selection.qnt` — so `test/table.browser.test.tsx` is its oracle.
+
+```tsx
+const table = createTable({
+  columns: [
+    { key: "title", abbr: "Title" },
+    { key: "status", sortable: false },
+    { key: "count", numeric: true },
+  ],
+  rows, // the host's ids, in the host's order: it sorts its data from the descriptor
+  selection: "multiple",
+  defaultSort: { key: "title", direction: "ascending" },
+  labels: { table: "Open issues", selectRow: (id) => `Select ${nameOf(id)}` },
+  onSortChange: (sort) => setSort(sort), // the host re-sorts its data and passes `rows` again
+});
+
+<table {...table.tableProps}>
+  <caption {...table.captionProps}>Open issues</caption>
+  <thead>
+    <tr>
+      {table.selectAllProps && (
+        <th>
+          <span {...table.selectAllProps} />
+        </th>
+      )}
+      {columns.map((column) => {
+        const sortButton = table.headerButtonProps(column.key); // undefined when not sortable
+        return (
+          <th {...table.headerCellProps(column.key)}>
+            {sortButton ? <button {...sortButton}>{column.key}</button> : column.key}
+          </th>
+        );
+      })}
+    </tr>
+  </thead>
+  <tbody>
+    {rows.map((id) => (
+      <tr {...table.rowProps(id)}>
+        {table.selectAllProps && (
+          <td>
+            <span {...table.rowCheckboxProps(id)} />
+          </td>
+        )}
+        {columns.map((column) => (
+          <td {...table.cellProps(id, column.key)}>{cellOf(id, column.key)}</td>
+        ))}
+      </tr>
+    ))}
+  </tbody>
+</table>;
+```
+
+- **Sorting is the host's data.** The primitive carries the descriptor (`sort()`) and announces it; it never reorders anything. The host maps the descriptor onto its own array and renders `rows` again.
+- **`aria-sort` is on the sorted column only.** A sortable header that is not sorted carries nothing (ARIA's default is "not sorted"), and a `sortable: false` column is fully inert: no `aria-sort`, and `headerButtonProps` is `undefined`, so the host renders no button and it is not a tab stop.
+- **The cycle is tri-state by default** (`ascending` -> `descending` -> unsorted), so a table can be put back in its own order; `sortCycle: "toggle"` gives `ascending` <-> `descending` and never returns to unsorted, which is what the APG grid example does. A new column always starts `ascending`, and only one column is ever sorted.
+- **Rows are ids, not a count.** The host sorts its data, so an id keeps naming the same row across a re-sort while an index would not; the primitive never learns the row's content.
+- **Selection** is `"none"` (the default), `"single"` or `"multiple"`, over ids: `selected()` is the list, `rowProps(id)` carries `aria-selected` and a click that selects, and `toggleRow` / `toggleAll` are the programmatic path. The row's checkbox stops its own click from reaching the row, so the two controls never toggle the same row twice.
+- **Select-all exists only for `"multiple"`** (`selectAllProps` and `rowCheckboxProps` are `undefined` otherwise: one control over one selection is meaningless). It is a `role="checkbox"`, not a native `input`: the mixed state of a native checkbox is a DOM property (`indeterminate`), and what a screen reader must hear is `aria-checked="mixed"`. It toggles the rows the table renders — a windowed table therefore toggles its window and keeps the rest of the selection.
+- **Windowed rows or columns** pass `rowCount` / `columnCount`: then `aria-rowcount` and `aria-colcount` are carried, and every cell gets its `aria-colindex`. A table that renders all of them carries neither (it would only repeat what the markup says).
+- **`numeric` is a layout hint** for the host's skin (right alignment, tabular figures): HTML has no attribute for it, so the primitive carries nothing.
+- Solid 2 arrives through delegated events; a host that reads the DOM right after a click waits a tick.
+
 ## Confirm
 
 `createConfirm` is a promise-based confirmation over `createDialogModal({ role: "alertdialog" })`. Like the field it is not checked against a spec (the dialog is; `test/confirm.browser.test.tsx` covers the promise around it, in Chromium).
@@ -296,6 +360,28 @@ onMount(() => {
 - **Not a menu.** No roving focus, no arrow keys between items: it is the base for `createMenu` in a popover, and for the filterable menu, which own their own item focus.
 - Absent on purpose: hover open (that is `createTooltipGroup`), submenus and item navigation (the menu), a scroll lock and `inert` (the modal dialog), and a vertical shift when neither side fits (the caller sees the requested placement).
 
+## Drawer
+
+`createDrawer` is the drawer / sheet shell: an edge-anchored panel over the Dialog (Modal) semantics, with the same focus, Escape, scroll-lock and backdrop behaviour as `createConfirm`. **No APG pattern exists for a drawer or a bottom sheet**, and [docs/bottom-sheet.md](docs/bottom-sheet.md) settled that the library composes rather than adding a sheet primitive: the semantics are Dialog (Modal), the position, the slide and the snap points are the host's native CSS, and this is the panel both were missing. `test/drawer.browser.test.tsx` is the oracle.
+
+```tsx
+const drawer = createDrawer({ side: "right", labelledby: "nav-title" });
+
+<button {...drawer.triggerProps}>Menu</button>;
+<div {...drawer.backdropProps} />;
+<div {...drawer.contentProps}>
+  <h2 id="nav-title">Site</h2>
+  <nav>{/* links */}</nav>
+</div>;
+```
+
+- **`side` is presentation only**, `"right"` (the default), `"left"` or `"bottom"`: a sheet is `{ side: "bottom" }`, a side rail is `{ side: "left" }`, and it is one API either way. The primitive lays out nothing; the host's CSS anchors the panel, and `handleProps` is the grab handle of a sheet.
+- **`modal` is the breakpoint switch.** It is read on every attribute read, so a host may flip it while the drawer is open (crossing the breakpoint) and `aria-modal`, the backdrop and the lock follow. `breakpoint` is a px number the primitive **does not read**: it has no viewport, so the host watches `matchMedia` and passes `side` and `modal`. A sheet below a breakpoint is modal; a side rail above it may not be.
+- **Modal** (the default): `aria-modal="true"`, a backdrop, focus into the panel's first focusable on open (else the panel, which is `tabindex="-1"`) and back to the trigger on close, Tab and Shift+Tab cycling inside, `overflow: hidden` on `document.documentElement` counted (as in `createConfirm`, and shared with it: a confirm over a drawer nests), and Escape read from the document in the capture phase, so it closes wherever the focus is. **Non-modal**: no `aria-modal`, no backdrop, no lock and no Tab trap, so the page keeps its scroll and its clicks; an outside `pointerdown` still dismisses it when `dismissable`, and Escape still closes it.
+- **The trigger toggles** (a hamburger), and Enter / Space open it. `dismissable: false` keeps the backdrop and an outside `pointerdown` from closing the drawer; Escape still closes it, because there is no way out otherwise.
+- **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.
+
 ## Commands
 
 ```sh

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`.
  */
@@ -2797,6 +2912,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 {

package/dist/index.mjs

@@ -54,7 +54,7 @@ const toggled = (a, index) => {
 	else next.add(index);
 	return next;
 };
-const sameSet = (a, b) => a.size === b.size && [...a].every((index) => b.has(index));
+const sameSet$1 = (a, b) => a.size === b.size && [...a].every((index) => b.has(index));
 /** The only member, or -1. */
 const sole = (a) => a.size === 1 ? [...a][0] ?? -1 : -1;
 const at = (values, index) => values[index] ?? 0;
@@ -477,7 +477,7 @@ const createCanvas = (options) => {
 		annSel: ann,
 		annText: prefs.announce ? messages().selection([...ann].sort((a, b) => a - b).map((i) => labelAt(s, i))) : ""
 	});
-	const announced = (s, sel) => sameSet(sel, s.annSel) ? {
+	const announced = (s, sel) => sameSet$1(sel, s.annSel) ? {
 		...s,
 		sel
 	} : announcing({
@@ -1296,7 +1296,7 @@ const createPlayer = (options) => {
 const HEADING_LEVELS = 6;
 const count = (expanded) => expanded.filter(Boolean).length;
 /** Re-establish the mode's constraints, exactly as the spec's `normExpanded`. */
-const normalize$1 = (expanded, multiple, collapsible) => {
+const normalize$2 = (expanded, multiple, collapsible) => {
 	if (!collapsible && count(expanded) === 0) return expanded.map((_, index) => index === 0);
 	if (multiple) return expanded;
 	const first = expanded.findIndex(Boolean);
@@ -1328,7 +1328,7 @@ const createAccordion = (options = {}) => {
 	const controlled = () => options.value !== void 0;
 	const [indices, request] = createControllable({
 		value: () => options.value,
-		initial: indicesOf(normalize$1(Array.from({ length: items }, (_, index) => (options.defaultValue ?? []).includes(index)), multiple(), collapsible())),
+		initial: indicesOf(normalize$2(Array.from({ length: items }, (_, index) => (options.defaultValue ?? []).includes(index)), multiple(), collapsible())),
 		onChange: () => options.onValueChange
 	});
 	const expanded = () => Array.from({ length: items }, (_, index) => indices().includes(index));
@@ -1361,11 +1361,11 @@ const createAccordion = (options = {}) => {
 		toggle,
 		setMultiple: (value) => {
 			setMultipleOverride(value);
-			if (!controlled()) commit(normalize$1(expanded(), value, collapsible()));
+			if (!controlled()) commit(normalize$2(expanded(), value, collapsible()));
 		},
 		setCollapsible: (value) => {
 			setCollapsibleOverride(value);
-			if (!controlled()) commit(normalize$1(expanded(), multiple(), value));
+			if (!controlled()) commit(normalize$2(expanded(), multiple(), value));
 		},
 		setHeadingLevel: (level) => {
 			setHeadingLevelSignal(Math.min(Math.max(level, 1), HEADING_LEVELS));
@@ -2584,28 +2584,85 @@ const createDialogModal = (options = {}) => {
 		}
 	};
 };
-// src/confirm.ts
-var ConfirmPendingError = class extends Error {
-	name = "ConfirmPendingError";
-	constructor() {
-		super("a confirmation is already pending");
+// src/overlay-shell.ts
+/**
+* The page-wide half of a modal overlay: one scroll lock, one stack of open
+* overlays, the tabbables of a panel and the Tab cycle over them. Shared by
+* `createConfirm` and `createDrawer` so that a confirm opened over a drawer (or
+* the reverse) takes Escape and Tab first, and the scroll lock outlives the
+* first of them to close.
+*/
+const TABBABLE = "a[href], button, input, select, textarea, [tabindex], [contenteditable]";
+/** The visible, tabbable elements of `root`, in document order. */
+const tabbables = (root) => Array.from(root.querySelectorAll(TABBABLE)).filter((element) => element.tabIndex >= 0 && !element.matches(":disabled") && element.getClientRects().length > 0);
+/** The first tabbable element of `root`, if any. */
+const firstFocusable$1 = (root) => tabbables(root)[0];
+/**
+* Wraps Tab / Shift+Tab inside `root` and pulls a focus that escaped back in
+* on the next Tab. With nothing tabbable the panel itself (which is
+* `tabindex="-1"`) keeps the focus.
+*/
+const cycleFocus = (event, root) => {
+	const items = tabbables(root);
+	const first = items[0];
+	const last = items.at(-1);
+	const active = document.activeElement;
+	const inside = root.contains(active);
+	if (first === void 0 || last === void 0) {
+		event.preventDefault();
+		root.focus();
+	} else if (event.shiftKey && (!inside || active === first || active === root)) {
+		event.preventDefault();
+		last.focus();
+	} else if (!event.shiftKey && (!inside || active === last)) {
+		event.preventDefault();
+		first.focus();
 	}
 };
-const openDialogs = [];
 let scrollLocks = 0;
 let scrollBefore = "";
+/**
+* `overflow: hidden` on the document element, counted: the first holder takes
+* it, the last to release restores what `overflow` was. The returned release is
+* idempotent.
+*/
 const lockScroll = () => {
 	const root = document.documentElement;
 	if (scrollLocks++ === 0) {
 		scrollBefore = root.style.overflow;
 		root.style.overflow = "hidden";
 	}
+	let released = false;
 	return () => {
+		if (released) return;
+		released = true;
 		if (--scrollLocks === 0) root.style.overflow = scrollBefore;
 	};
 };
-const TABBABLE = "a[href], button, input, select, textarea, [tabindex], [contenteditable]";
-const tabbables = (root) => Array.from(root.querySelectorAll(TABBABLE)).filter((element) => element.tabIndex >= 0 && !element.matches(":disabled") && element.getClientRects().length > 0);
+const openOverlays = [];
+/**
+* Joins the open overlays; the last one to claim takes Escape and Tab. Returns
+* the release (idempotent), which may be called in any order.
+*/
+const claimOverlay = (self) => {
+	openOverlays.push(self);
+	let claimed = true;
+	return () => {
+		if (!claimed) return;
+		claimed = false;
+		const at = openOverlays.indexOf(self);
+		if (at !== -1) openOverlays.splice(at, 1);
+	};
+};
+/** Whether `self` is the overlay that takes Escape and Tab (the one opened last). */
+const isTopOverlay = (self) => openOverlays.at(-1) === self;
+// src/confirm.ts
+var ConfirmPendingError = class extends Error {
+	name = "ConfirmPendingError";
+	constructor() {
+		super("a confirmation is already pending");
+	}
+};
 /**
 * A promise-based confirmation over `createDialogModal({ role: "alertdialog" })`
 * (APG Alert Dialog: https://www.w3.org/WAI/ARIA/apg/patterns/alertdialog/).
@@ -2627,7 +2684,9 @@ const tabbables = (root) => Array.from(root.querySelectorAll(TABBABLE)).filter((
 * 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
@@ -2661,7 +2720,7 @@ const createConfirm = (options = {}) => {
 	});
 	const self = Symbol(base);
 	const onDocumentKeyDown = (event) => {
-		if (openDialogs.at(-1) !== self) return;
+		if (!isTopOverlay(self)) return;
 		if (event.key === "Escape") {
 			event.preventDefault();
 			event.stopPropagation();
@@ -2670,31 +2729,17 @@ const createConfirm = (options = {}) => {
 		}
 		const root = document.getElementById(dialog.dialogProps.id);
 		if (event.key !== "Tab" || root === null) return;
-		const items = tabbables(root);
-		const first = items[0];
-		const last = items.at(-1);
-		const active = document.activeElement;
-		const inside = root.contains(active);
-		if (first === void 0 || last === void 0) {
-			event.preventDefault();
-			root.focus();
-		} else if (event.shiftKey && (!inside || active === first || active === root)) {
-			event.preventDefault();
-			last.focus();
-		} else if (!event.shiftKey && (!inside || active === last)) {
-			event.preventDefault();
-			first.focus();
-		}
+		cycleFocus(event, root);
 	};
 	createEffect(() => dialog.open(), (isOpen) => {
 		if (!isOpen) return;
 		document.getElementById(cancelId)?.focus();
 		const unlock = lockScroll();
-		openDialogs.push(self);
+		const release = claimOverlay(self);
 		document.addEventListener("keydown", onDocumentKeyDown, true);
 		return () => {
 			document.removeEventListener("keydown", onDocumentKeyDown, true);
-			openDialogs.splice(openDialogs.indexOf(self), 1);
+			release();
 			unlock();
 		};
 	});
@@ -2752,6 +2797,148 @@ const createConfirm = (options = {}) => {
 		}
 	};
 };
+// src/drawer.ts
+/**
+* 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.
+*/
+const createDrawer = (options = {}) => {
+	const base = options.id ?? createUniqueId();
+	const triggerId = `${base}-trigger`;
+	const contentId = `${base}-content`;
+	const backdropId = `${base}-backdrop`;
+	const self = Symbol(base);
+	let wasOpen = false;
+	const isModal = () => options.modal ?? true;
+	const dismissable = () => options.dismissable ?? true;
+	const content = () => document.getElementById(contentId);
+	const trigger = () => document.getElementById(triggerId);
+	const [open, requestOpen] = createControllable({
+		value: () => options.open,
+		initial: options.defaultOpen ?? false,
+		onChange: () => options.onOpenChange
+	});
+	const onDocumentKeyDown = (event) => {
+		if (!isTopOverlay(self) || !open()) return;
+		if (event.key === "Escape") {
+			event.preventDefault();
+			event.stopPropagation();
+			requestOpen(false);
+			return;
+		}
+		if (event.key !== "Tab" || !isModal()) return;
+		const panel = content();
+		if (panel !== null) cycleFocus(event, panel);
+	};
+	createEffect(() => open(), (isOpen) => {
+		if (isOpen) {
+			wasOpen = true;
+			const panel = content();
+			if (panel !== null) (firstFocusable$1(panel) ?? panel).focus();
+			const release = claimOverlay(self);
+			document.addEventListener("keydown", onDocumentKeyDown, true);
+			return () => {
+				document.removeEventListener("keydown", onDocumentKeyDown, true);
+				release();
+			};
+		}
+		if (wasOpen) {
+			wasOpen = false;
+			const back = trigger();
+			if (back !== null && back.isConnected) back.focus();
+		}
+	});
+	createEffect(() => open() && isModal(), (locked) => {
+		if (locked) return lockScroll();
+	});
+	const onPointerDown = (event) => {
+		if (!open() || !dismissable()) return;
+		const target = event.target;
+		if (!(target instanceof Node)) return;
+		if (content()?.contains(target) === true || trigger()?.contains(target) === true) return;
+		requestOpen(false);
+	};
+	document.addEventListener("pointerdown", onPointerDown, true);
+	onCleanup(() => document.removeEventListener("pointerdown", onPointerDown, true));
+	return {
+		open,
+		side: () => options.side ?? "right",
+		triggerProps: {
+			id: triggerId,
+			"aria-haspopup": "dialog",
+			get "aria-expanded"() {
+				return open() ? "true" : "false";
+			},
+			"aria-controls": contentId,
+			onClick: () => requestOpen(!open()),
+			onKeyDown: (event) => {
+				if (event.key === "Enter" || event.key === " ") {
+					event.preventDefault();
+					requestOpen(true);
+				}
+			}
+		},
+		backdropProps: {
+			id: backdropId,
+			get hidden() {
+				return !open() || !isModal();
+			},
+			onClick: () => {
+				if (dismissable()) requestOpen(false);
+			}
+		},
+		contentProps: {
+			id: contentId,
+			role: "dialog",
+			get "aria-modal"() {
+				return isModal() && open() ? "true" : void 0;
+			},
+			"aria-labelledby": options.labelledby,
+			tabindex: -1,
+			get hidden() {
+				return !open();
+			},
+			onKeyDown: (event) => {
+				if (event.key === "Escape" && open()) {
+					event.preventDefault();
+					requestOpen(false);
+				}
+			}
+		},
+		handleProps: { "aria-hidden": "true" }
+	};
+};
 // src/feed.ts
 /**
 * APG Feed (https://www.w3.org/WAI/ARIA/apg/patterns/feed/): state plus prop
@@ -5822,6 +6009,171 @@ const createSwitch = (options = {}) => {
 		}
 	};
 };
+// src/table.ts
+const normalize$1 = (ids) => [...new Set(ids)];
+const sameSet = (a, b) => a.length === b.length && a.every((id) => b.includes(id));
+const sameSort = (a, b) => a === null || b === null ? a === b : a.key === b.key && a.direction === b.direction;
+const isToggleKey = (event) => event.key === " " || event.key === "Spacebar" || event.key === "Enter";
+/**
+* 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.
+*/
+const createTable = (options) => {
+	const base = options.id ?? createUniqueId();
+	const selectionMode = () => options.selection ?? "none";
+	const selectable = () => selectionMode() !== "none";
+	const columnOf = (key) => options.columns.find((column) => column.key === key);
+	const isSortable = (key) => columnOf(key)?.sortable !== false;
+	const [rawSort, requestSort] = createControllable({
+		value: () => options.sort,
+		initial: options.defaultSort ?? null,
+		onChange: () => (next) => options.onSortChange?.(next ?? void 0),
+		same: sameSort
+	});
+	const sort = () => rawSort() ?? void 0;
+	const [rawSelected, requestSelection] = createControllable({
+		value: () => options.selected,
+		initial: normalize$1(options.defaultSelected ?? []),
+		onChange: () => options.onSelectionChange,
+		same: sameSet
+	});
+	const selected = () => normalize$1(rawSelected());
+	const isSelected = (id) => selected().includes(id);
+	const nextSort = (key) => {
+		const current = rawSort();
+		if (current === null || current.key !== key) return {
+			key,
+			direction: "ascending"
+		};
+		if (current.direction === "ascending") return {
+			key,
+			direction: "descending"
+		};
+		return (options.sortCycle ?? "tri-state") === "toggle" ? {
+			key,
+			direction: "ascending"
+		} : null;
+	};
+	const toggleRow = (id) => {
+		const mode = selectionMode();
+		if (mode === "none") return;
+		const current = selected();
+		const has = current.includes(id);
+		requestSelection(mode === "single" ? has ? [] : [id] : has ? current.filter((value) => value !== id) : [...current, id]);
+	};
+	const rows = () => options.rows;
+	const allSelected = () => {
+		const every = rows();
+		return every.length > 0 && every.every(isSelected);
+	};
+	const someSelected = () => rows().some(isSelected);
+	const toggleAll = () => {
+		if (selectionMode() !== "multiple") return;
+		const current = selected();
+		if (allSelected()) {
+			requestSelection(current.filter((id) => !rows().includes(id)));
+			return;
+		}
+		requestSelection(normalize$1([...current, ...rows()]));
+	};
+	const keyedToggle = (toggle) => (event) => {
+		if (!isToggleKey(event)) return;
+		event.preventDefault();
+		toggle();
+	};
+	const selectAll = () => {
+		if (selectionMode() !== "multiple") return;
+		return {
+			role: "checkbox",
+			get "aria-checked"() {
+				return allSelected() ? "true" : someSelected() ? "mixed" : "false";
+			},
+			get "aria-label"() {
+				return options.labels?.selectAll ?? "Select all rows";
+			},
+			tabindex: 0,
+			onClick: () => {
+				toggleAll();
+			},
+			onKeyDown: keyedToggle(toggleAll)
+		};
+	};
+	const rowCheckbox = (id) => {
+		if (!selectable()) return;
+		return {
+			role: "checkbox",
+			get "aria-checked"() {
+				return isSelected(id) ? "true" : "false";
+			},
+			get "aria-label"() {
+				return options.labels?.selectRow?.(id) ?? `Select row ${id}`;
+			},
+			tabindex: 0,
+			onClick: (event) => {
+				event.stopPropagation();
+				toggleRow(id);
+			},
+			onKeyDown: keyedToggle(() => toggleRow(id))
+		};
+	};
+	return {
+		selectionMode,
+		sort,
+		selected,
+		isSelected,
+		tableProps: {
+			get "aria-label"() {
+				return options.labels?.table;
+			},
+			get "aria-rowcount"() {
+				return options.rowCount;
+			},
+			get "aria-colcount"() {
+				return options.columnCount;
+			}
+		},
+		captionProps: { id: `${base}-caption` },
+		headerCellProps: (key) => ({
+			scope: "col",
+			get "aria-sort"() {
+				const current = rawSort();
+				return current !== null && current.key === key && isSortable(key) ? current.direction : void 0;
+			},
+			get abbr() {
+				return columnOf(key)?.abbr;
+			}
+		}),
+		headerButtonProps: (key) => {
+			if (!isSortable(key)) return;
+			return {
+				type: "button",
+				onClick: () => {
+					requestSort(nextSort(key));
+				}
+			};
+		},
+		rowProps: (id) => ({
+			get "aria-selected"() {
+				if (!selectable()) return;
+				return isSelected(id) ? "true" : "false";
+			},
+			get onClick() {
+				return selectable() ? () => toggleRow(id) : void 0;
+			}
+		}),
+		cellProps: (_rowId, key) => ({ get "aria-colindex"() {
+			if (options.columnCount === void 0) return;
+			const index = options.columns.findIndex((column) => column.key === key);
+			return index < 0 ? void 0 : index + 1;
+		} }),
+		get selectAllProps() {
+			return selectAll();
+		},
+		rowCheckboxProps: (id) => rowCheckbox(id),
+		toggleAll,
+		toggleRow
+	};
+};
 // src/textbox.ts
 const control = (field, options) => ({
 	...field.controlProps,
@@ -8009,4 +8361,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, createFeed, createField, createGrid, createLink, createListbox, createMenu, createMenubar, createMeter, createPagination, createPlayer, createPopover, createRadioGroup, createRearrangeableListbox, createResizablePanels, createSlider, createSliderMultiThumb, createSpinbutton, createStatus, createSwitch, 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, 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 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cssints/headless",
-  "version": "0.15.0",
+  "version": "0.17.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": {