@cssints/headless 0.17.0 → 0.19.0

package/dist/index.d.mts

@@ -1497,6 +1497,106 @@ export interface Drawer {
  * dismissal a non-modal drawer has); closing returns focus to the trigger.
  */
 export declare const createDrawer: (options?: DrawerOptions) => Drawer;
+/** Why a file was refused: the `accept` grammar, or `maxSize`. */
+export type DropZoneRejectReason = "type" | "size";
+export interface DropZoneReject {
+  readonly file: File;
+  readonly reason: DropZoneRejectReason;
+}
+export interface DropZoneLabels {
+  /** The zone's accessible name (`aria-label` on the `role=group` zone). */
+  readonly zone?: string | undefined;
+  /** The browse button's accessible name; render it visibly, or use it for an icon-only button. */
+  readonly browse?: string | undefined;
+}
+export interface DropZoneOptions {
+  /** The HTML `accept` grammar: extensions (`.png`) and MIME types, wildcards included (`image/*`). */
+  readonly accept?: string | undefined;
+  readonly multiple?: boolean | undefined;
+  /** Bytes; a larger file is rejected with `"size"`. */
+  readonly maxSize?: number | undefined;
+  readonly disabled?: boolean | undefined;
+  /** The files that passed, one call per batch; not called when the batch has none. */
+  readonly onFiles: (files: File[]) => void;
+  /** Each refused file, once, with the reason the host shows. */
+  readonly onReject?: ((reject: DropZoneReject) => void) | undefined;
+  readonly labels?: DropZoneLabels | undefined;
+}
+/** Spread onto the hidden `<input type=file>`; render it, always. */
+export interface DropZoneInputProps {
+  /** The id the browse button clicks; generated. */
+  readonly id: string;
+  readonly type: "file";
+  readonly accept: string | undefined;
+  readonly multiple: true | undefined;
+  readonly disabled: true | undefined;
+  readonly hidden: true;
+  readonly onChange: (event: {
+    currentTarget: HTMLInputElement;
+  }) => void;
+}
+/** Spread onto the drop target (any element). `dragging()` is the styling hook. */
+export interface DropZoneZoneProps {
+  readonly role: "group";
+  readonly "aria-label": string | undefined;
+  readonly "aria-disabled": "true" | undefined;
+  readonly onDragEnter: (event: DragEvent) => void;
+  readonly onDragOver: (event: DragEvent) => void;
+  readonly onDragLeave: (event: DragEvent) => void;
+  readonly onDrop: (event: DragEvent) => void;
+}
+/** Spread onto a real `<button type="button">`: Enter and Space are the platform's. */
+export interface DropZoneBrowseProps {
+  readonly type: "button";
+  readonly disabled: true | undefined;
+  readonly "aria-disabled": "true" | undefined;
+  readonly "aria-label": string | undefined;
+  readonly onClick: () => void;
+}
+/** Spread onto the live region; render it once, always. */
+export interface DropZoneStatusProps {
+  readonly role: "status";
+  readonly "aria-live": "polite";
+  readonly "aria-atomic": "true";
+}
+export interface DropZone {
+  /** A drag is over the zone; `dragleave` on a child does not clear it. */
+  readonly dragging: Accessor<boolean>;
+  /**
+   * A default sentence for the last batch ("2 files, 1 rejected: too large"),
+   * or `undefined` before one arrived. The host may write its own words from
+   * the same counts.
+   */
+  readonly message: Accessor<string | undefined>;
+  readonly inputProps: DropZoneInputProps;
+  readonly zoneProps: DropZoneZoneProps;
+  readonly browseProps: DropZoneBrowseProps;
+  readonly statusProps: DropZoneStatusProps;
+}
+/**
+ * A file drop zone. There is no APG pattern and no Quint spec for one: the
+ * contract is HTML's file input plus WAI-ARIA's live region, and
+ * `test/dropzone.browser.test.tsx` is its oracle.
+ *
+ * Decisions:
+ * - **The zone is never drag-only.** `browseProps` spreads onto a real
+ *   `<button type="button">` that clicks the hidden input, so the picker is the
+ *   keyboard path (Enter and Space are the platform's) and a pointer user can
+ *   click as well as drag. The drop handlers add nothing the button cannot do.
+ * - **Validation happens once per file**, in the order type then size, and a
+ *   refused file reaches `onReject` with the reason the host shows. `accept` is
+ *   the HTML grammar (`.` extension, MIME type, `*`); `maxSize` is bytes.
+ * - **Dropping a folder or a `DataTransfer` with no files is a no-op**: no
+ *   `onFiles`, no `onReject`, no message, and the previous announcement stays.
+ * - **`dragleave` counts.** A child's `dragleave` bubbles to the zone, so the
+ *   state is a depth counter: it clears only when the drag leaves the zone
+ *   itself, or on a drop.
+ * - **The zone is `role=group`** so `labels.zone` is exposed; `dragging()` is
+ *   the only drag state a skin reads (no `data-dragging`).
+ * - `disabled` marks the zone `aria-disabled`, disables the input natively and
+ *   the browse button, and drops every drag before it becomes a batch.
+ */
+export declare const createDropZone: (options: DropZoneOptions) => DropZone;
 /**
  * Options are read lazily (getters); pass a component's `props`.
  */
@@ -1757,6 +1857,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 +2249,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 +2870,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 {
@@ -2615,6 +2954,11 @@ export interface SliderOptions {
   readonly defaultValue?: number;
   readonly orientation?: SliderOrientation;
   readonly direction?: SliderDirection;
+  /**
+   * aria-disabled: the thumb stays the tab stop (the APG pattern's focus
+   * contract) but a key or a rail press changes nothing.
+   */
+  readonly disabled?: boolean;
   /** Base for the generated thumb id. */
   readonly id?: string;
   /**
@@ -2631,6 +2975,7 @@ export interface SliderThumbProps {
   readonly "aria-valuemax": string;
   readonly "aria-valuetext": string;
   readonly "aria-orientation": SliderOrientation;
+  readonly "aria-disabled": "true" | undefined;
   readonly tabindex: number;
   readonly onFocus: () => void;
   readonly onBlur: () => void;
@@ -2668,6 +3013,11 @@ export interface Slider {
  * pass `value` + `onValueChange` to own the value. A key or rail press is a
  * request the host may ignore.
  *
+ * `disabled` is a widget-level extension of the pattern (the spec lists it
+ * under its deliberate omissions): the thumb keeps its tab stop and announces
+ * `aria-disabled`, and every key and rail press is dropped before it becomes a
+ * request.
+ *
  * ponytail: dragging (pointer capture/move) is not modelled — the spec
  * deliberately only fixes a discrete rail press.
  */
@@ -2752,6 +3102,11 @@ export interface SpinbuttonOptions {
   readonly defaultValue?: number;
   /** Wrap around at the bounds instead of clamping. */
   readonly wrap?: boolean;
+  /**
+   * aria-disabled plus the native `disabled` on the text field: keys, typing
+   * and both steppers change nothing, and both steppers announce `aria-disabled`.
+   */
+  readonly disabled?: boolean;
   /** Base for the generated input / button ids. */
   readonly id?: string;
   /**
@@ -2768,6 +3123,8 @@ export interface SpinbuttonInputProps {
   readonly "aria-valuemax": string;
   readonly "aria-valuetext": string;
   readonly "aria-invalid": "true" | undefined;
+  readonly "aria-disabled": "true" | undefined;
+  readonly disabled: boolean;
   readonly tabindex: number;
   readonly value: string;
   readonly onFocus: () => void;
@@ -2823,6 +3180,12 @@ export interface Spinbutton {
  * stepper buttons, Enter and blur are requests the host may ignore; typing and
  * Escape change no committed value.
  *
+ * `disabled` is a widget-level extension of the pattern (the spec models the
+ * steppers' bound only, and lists this under its deliberate omissions): the
+ * field announces `aria-disabled` and carries the native `disabled`, every key,
+ * typed draft and both steppers are dropped before they become a request, and
+ * neither stepper offers itself.
+ *
  * ponytail: commit/revert on Enter/blur/Escape is the common convention, not
  * APG text.
  */
@@ -3194,6 +3557,26 @@ export interface TabsOptions {
    * current value. Uncontrolled it is accepted; controlled the host may ignore it.
    */
   readonly onValueChange?: (index: number) => void;
+  /**
+   * Close buttons and the Delete key (default false): the host renders
+   * `closeProps` and removes the tab from `onClose`. The last tab is never
+   * asked to close.
+   */
+  readonly closable?: boolean | undefined;
+  /**
+   * Inline rename (default false): a double click on a tab starts it, Enter /
+   * blur commit and Escape reverts; the host renames from `onRename`.
+   */
+  readonly renamable?: boolean | undefined;
+  /**
+   * A tab's label: the close / rename button names and the starting draft of a
+   * rename, read lazily (a getter is fine) so a rename follows.
+   */
+  readonly label?: ((index: number) => string | undefined) | undefined;
+  /** A request to remove a tab; the primitive does not own the list. */
+  readonly onClose?: ((index: number) => void) | undefined;
+  /** A request to rename a tab with a non-empty label. */
+  readonly onRename?: ((index: number, label: string) => void) | undefined;
 }
 /** Spread onto the element with `role=tab` (a native `<button>`). */
 export interface TabProps {
@@ -3221,21 +3604,63 @@ export interface TabpanelProps {
   readonly tabindex: 0 | undefined;
   readonly hidden: boolean;
 }
+/**
+ * Spread onto the tab's close button. `tabindex=-1` keeps it out of the
+ * tablist's tab order (a tablist's stops are its tabs); the Delete key is the
+ * keyboard path.
+ */
+export interface TabCloseProps {
+  readonly "aria-label": string;
+  readonly tabindex: -1;
+  readonly onClick: () => void;
+}
+/** Spread onto the inline `<input>` a renaming tab renders instead of its label. */
+export interface TabRenameInputProps {
+  readonly type: "text";
+  readonly value: string;
+  readonly "aria-label": string;
+  readonly onInput: (event: InputEvent) => void;
+  readonly onKeyDown: (event: KeyboardEvent) => void;
+  readonly onBlur: () => void;
+}
+/** The rename part of one tab: put `onDblClick` on the tab, `inputProps` in it. */
+export interface TabRenameProps {
+  readonly onDblClick: () => void;
+  /** Whether this tab is the one being renamed. */
+  readonly editing: Accessor<boolean>;
+  /** Start renaming `index` (e.g. a tab the host has just added). */
+  readonly begin: (index: number) => void;
+  /** Commit `label` to the tab being edited; an empty label cancels. */
+  readonly commit: (label: string) => void;
+  readonly cancel: () => void;
+  readonly inputProps: TabRenameInputProps;
+}
 export interface Tabs {
+  /** The tab count; read from `items` on every read, so a host that shrinks its list stays in step. */
   readonly items: number;
   readonly selected: Accessor<number>;
   /** Tab holding (or last holding) DOM focus; -1 when focus is outside. */
   readonly focused: Accessor<number>;
+  /** The tab being renamed inline, `null` when none. */
+  readonly editing: Accessor<number | null>;
   /** Programmatic selection request; ignores disabled tabs. */
   readonly select: (index: number) => void;
   /** Programmatic selection request (may point at a disabled tab, like base-ui). */
   readonly setSelected: (index: number) => void;
   /** Programmatic focus (does not select). */
   readonly focusTab: (index: number) => void;
+  /**
+   * The tab that takes focus once `onClose(index)`'s removal lands: the tab
+   * that slid into `index`, or the previous one when the last tab closed. Call
+   * it before the host removes the tab.
+   */
+  readonly focusAfterClose: (index: number) => number;
   readonly keyDown: (key: string) => void;
   readonly tablistProps: TablistProps;
   readonly tabProps: (index: number) => TabProps;
   readonly tabpanelProps: (index: number) => TabpanelProps;
+  readonly closeProps: (index: number) => TabCloseProps;
+  readonly renameProps: (index: number) => TabRenameProps;
 }
 /**
  * APG Tabs (https://www.w3.org/WAI/ARIA/apg/patterns/tabs/): state plus prop
@@ -3250,6 +3675,14 @@ export interface Tabs {
  * Request/commit (map ticket `rt1p`): uncontrolled by default
  * (`defaultSelected`); pass `value` + `onValueChange` to own the selection.
  * Programmatic methods (`select`, `setSelected`, `keyDown`) are requests too.
+ *
+ * Close and rename are an **extension** (bean `cssints-gdv2`): the APG spec
+ * models a `deletable` flavour but neither a callback nor a rename, and this
+ * primitive owns no list. `closable` / `renamable` turn on the props; `onClose`
+ * / `onRename` ask the host, which removes or renames. Focus after a close goes
+ * to the tab that slid into the closed one's place, or to the previous tab when
+ * the last one closed; closing the last remaining tab is refused, as the spec
+ * refuses an empty tablist.
  */
 export declare const createTabs: (options?: TabsOptions) => Tabs;
 /**
@@ -3267,10 +3700,16 @@ export declare const createTabs: (options?: TabsOptions) => Tabs;
  * may ignore. The zoom window (`viewStart`/`viewEnd`) is not the controlled
  * value and stays uncontrolled.
  *
- * ponytail: the fixed 5-span tree is a demo fixture; a real consumer owns the
- * span list (layout is theirs). Roving tabindex only — a consumer must call
- * `focus()` on the row whose `tabindex` is 0 after arrow navigation (the tests'
- * fixture does this with an effect).
+ * The fixed 5-span tree is the demo fixture (the differential walk's oracle).
+ * A real consumer passes `rows`: span data on one shared axis, laid out by
+ * `barProps` as percentages of the rows' extent. No roles are borrowed from
+ * APG: a trace waterfall is a list of spans in time, so the rows mode is
+ * `role="list"` / `role="listitem"` (with `aria-level` for the depth) and the
+ * current row is `aria-current="true"`, which every element may carry.
+ *
+ * Roving tabindex only — a consumer must call `focus()` on the row whose
+ * `tabindex` is 0 after arrow navigation (the tests' fixture does this with an
+ * effect; the rows mode's span rows are reached by tabbing to the current one).
  */
 /** One span row: a fraction of the parent span on a shared 0..1 axis. */
 export interface TimelineRow {
@@ -3353,12 +3792,90 @@ export interface Timeline {
   readonly rowProps: (id: number) => TimelineRowProps;
   readonly rulerProps: TimelineRulerProps;
 }
-/**
- * Headless span timeline on Solid 2. The exported accessors are signals; the
- * prop objects are getter-backed, so spreading them keeps every attribute
- * reactive.
- */
-export declare const createTimeline: (options?: TimelineOptions) => Timeline;
+/** One span of a real trace: a point on a shared axis, labelled, at a depth. */
+export interface TimelineSpan {
+  readonly id: string;
+  readonly label: string;
+  /** Offset on the axis, in the axis' unit; `end` is the same axis, not a duration. */
+  readonly start: number;
+  readonly end: number;
+  /** Nesting level, 0 for a root span. */
+  readonly depth?: number;
+  readonly status?: "ok" | "error" | "unset";
+}
+export interface TimelineAxis {
+  /** The unit the numbers are in; the ruler labels its ticks with it. */
+  readonly unit?: "ms" | "us" | "s";
+}
+/** The rows mode: real span data, read lazily like every other option. */
+export interface TimelineRowsOptions {
+  readonly rows: ReadonlyArray<TimelineSpan>;
+  readonly axis?: TimelineAxis | undefined;
+  /** Controlled: the host owns the selection. */
+  readonly selected?: string | undefined;
+  /** A request to change the selection the host may ignore. */
+  readonly onSelect?: ((id: string) => void) | undefined;
+}
+export interface TimelineTick {
+  readonly value: number;
+  readonly left: number;
+  readonly label: string;
+}
+export interface TimelineListProps {
+  readonly role: "list";
+  readonly "aria-label": string;
+}
+export interface TimelineSpanRowProps {
+  readonly role: "listitem";
+  /** `depth + 1`: the nesting a flat list cannot show in the DOM. */
+  readonly "aria-level": number;
+  readonly "aria-current": "true" | undefined;
+  /** A styling hook: the status the span ended with. */
+  readonly "data-status": "ok" | "error" | "unset";
+  readonly tabindex: number;
+  readonly onClick: () => void;
+  readonly onKeyDown: (event: KeyboardEvent) => void;
+}
+export interface TimelineBarProps {
+  readonly "aria-hidden": "true";
+  /** `left` / `width` are percentages of the extent; `--depth` is the row's depth. */
+  readonly style: {
+    readonly left: string;
+    readonly width: string;
+    readonly "--depth": string;
+  };
+}
+export interface TimelineLabelProps {
+  /** `--depth`, so the host indents the label (`padding-inline-start: calc(var(--depth) * 1rem)`) instead of nesting it. */
+  readonly style: {
+    readonly "--depth": string;
+  };
+}
+export interface TimelineRulerRowsProps {
+  readonly role: "presentation";
+  readonly "aria-hidden": "true";
+  /** Ticks of a nice step across the extent; render them as children. */
+  readonly ticks: ReadonlyArray<TimelineTick>;
+}
+export interface TimelineRows {
+  /** `{ start, end }` across the rows; `{ 0, 0 }` when there are none. */
+  readonly extent: () => {
+    readonly start: number;
+    readonly end: number;
+  };
+  readonly depthOf: (id: string) => number;
+  readonly listProps: TimelineListProps;
+  readonly rowProps: (id: string) => TimelineSpanRowProps;
+  readonly barProps: (id: string) => TimelineBarProps;
+  readonly labelProps: (id: string) => TimelineLabelProps;
+  readonly rulerProps: TimelineRulerRowsProps;
+  /** Programmatic selection request; a controlled host may ignore it. */
+  readonly select: (id: string) => void;
+  readonly selectedId: Accessor<string | undefined>;
+}
+/** The demo five-span tree (`rows` absent) or real span data (`rows` given). */
+export declare function createTimeline(options: TimelineRowsOptions): TimelineRows;
+export declare function createTimeline(options?: TimelineOptions): Timeline;
 /** A toast's urgency; `error` is the only tone that announces assertively. */
 export type ToastTone = "info" | "success" | "error";
 export interface ToastOptions {