@cssints/headless 0.19.0 → 0.20.0

package/dist/index.d.mts

@@ -1030,6 +1030,94 @@ export interface Checkbox {
  * pass `value` + `onValueChange` to own the state.
  */
 export declare const createCheckbox: (options?: CheckboxOptions) => Checkbox;
+export interface FieldOptions {
+  /** Base of every id the field makes (`<id>-control`, `-label`, `-hint`, `-error`). */
+  readonly id?: string | undefined;
+  readonly required?: boolean | undefined;
+  /**
+   * `true` marks the control invalid; a string does too and is the error message
+   * (unless `error` is set). `false` forces valid: an `error` is then not shown,
+   * so a host can pass `touched() && failed()` and keep the message ready.
+   * Left out, the field is invalid exactly when it has an error message.
+   */
+  readonly invalid?: boolean | string | undefined;
+  /** Help text; absent (or empty) means the hint element is hidden and not referenced. */
+  readonly hint?: string | undefined;
+  /** The error message; absent (or empty) means no error element. */
+  readonly error?: string | undefined;
+  /**
+   * Ids of elements the host owns, appended to `aria-describedby` after the
+   * field's own hint and error: a form-level error that belongs to several
+   * controls ("the passwords do not match" names both). One id or a list;
+   * empty strings are dropped, and the attribute is absent when nothing is left.
+   * The host keeps that element rendered, and decides whether it is hidden.
+   */
+  readonly describedby?: string | readonly string[] | undefined;
+}
+/** Spread onto the form control (`input`, `textarea`, `select`, or a custom widget). */
+export interface FieldControlProps {
+  readonly id: string;
+  /** The ids of the hint and the error that are shown, hint first, then the host's `describedby`; absent when there are none. */
+  readonly "aria-describedby": string | undefined;
+  readonly "aria-invalid": "true" | undefined;
+  /** For a control that is not native (a native one has `required`). */
+  readonly "aria-required": "true" | undefined;
+  readonly required: true | undefined;
+}
+export interface FieldLabelProps {
+  readonly id: string;
+  readonly for: string;
+}
+/** Spread onto the hint and the error element; render both, always. */
+export interface FieldMessageProps {
+  readonly id: string;
+  readonly hidden: boolean;
+}
+/** The error element also announces itself: `role="alert"` while it is shown. */
+export interface FieldErrorProps extends FieldMessageProps {
+  readonly role: "alert" | undefined;
+}
+export interface Field {
+  readonly invalid: () => boolean;
+  /** The hint, or `undefined` when there is none. */
+  readonly hint: () => string | undefined;
+  /** The error shown: `undefined` unless the field is invalid and has a message. */
+  readonly error: () => string | undefined;
+  /**
+   * The ids `aria-describedby` lists now: hint, then error (never an id that is
+   * hidden), then the host's `describedby`.
+   */
+  readonly describedIds: () => readonly string[];
+  readonly controlProps: FieldControlProps;
+  readonly labelProps: FieldLabelProps;
+  readonly hintProps: FieldMessageProps;
+  readonly errorProps: FieldErrorProps;
+}
+/**
+ * The ARIA contract of a form field: a label, a control, a hint and an error.
+ * There is no APG pattern for it (APG has no "form field"; the nearest is the
+ * label and description rules of the accessible name computation), so the
+ * contract comes from WAI-ARIA 1.2 (`aria-describedby`, `aria-invalid`,
+ * `aria-required`) and HTML (`label[for]`, `required`), and from the
+ * majority of Base UI Field, react-aria TextField and ariakit FormControl,
+ * which list the description and the error message together. It is not checked
+ * against a Quint spec; `test/field.browser.test.tsx` is its oracle.
+ *
+ * Decisions: the error does not replace the hint, both are listed, hint first
+ * (the hint is what tells the user how to fix the error); an error implies
+ * invalid and `invalid: false` overrides it; a hidden message is never
+ * referenced, so `aria-describedby` has no dangling id. The error element is
+ * `role="alert"` only while it is shown (a hidden element announces nothing, and
+ * one that appears is announced); the hint is never an alert.
+ *
+ * `describedby` lists host-owned ids after the field's own: one refusal that
+ * belongs to two controls is one form-level element (with its own `role`), named
+ * by both. The field cannot know whether that element is shown: the host
+ * passes the id only while it is.
+ *
+ * Options are read when an attribute is read: pass getters, never destructure.
+ */
+export declare const createField: (options?: FieldOptions) => Field;
 export type CheckboxGroupFocus = "none" | "parent" | "c0" | "c1" | "c2";
 export type ParentChecked = "true" | "false" | "mixed";
 export interface CheckboxGroupOptions<T = unknown> {
@@ -1043,6 +1131,22 @@ export interface CheckboxGroupOptions<T = unknown> {
   readonly parent?: boolean;
   /** Remember the last mixed combination for the controller's third activation. */
   readonly remember?: boolean;
+  /** Base of the group's ids (`<id>-control`, `-error`); a unique one when absent. */
+  readonly id?: string;
+  /** The group's name, as `aria-label`: a `role="group"` needs one. */
+  readonly label?: string | undefined;
+  /** The id of the element that names the group (`aria-labelledby`); wins over `label`. */
+  readonly labelledby?: string | undefined;
+  /** Ids of elements the host owns that describe the group, after the group's own error id. */
+  readonly describedby?: string | undefined;
+  /**
+   * `true` marks the group invalid; a string does too and is the error message
+   * (unless `error` is set). `false` forces valid. Left out, the group is invalid
+   * exactly when it has an error message. Same contract as `createField`.
+   */
+  readonly invalid?: boolean | string | undefined;
+  /** The error message; absent (or empty) means no error element. */
+  readonly error?: string | undefined;
   /**
    * A request to change the checked subset, called when the intent differs from
    * the current value. Uncontrolled it is accepted; controlled the host may
@@ -1070,9 +1174,18 @@ export interface CheckboxGroupChildProps {
   readonly onFocus: () => void;
 }
 export interface CheckboxGroupProps {
+  /** The group element: a host's label can name it, and a controller can `aria-controls` it. */
+  readonly id: string;
   readonly role: "group";
+  readonly "aria-label": string | undefined;
+  readonly "aria-labelledby": string | undefined;
+  /** The error id while one is shown, then the host's `describedby`. */
+  readonly "aria-describedby": string | undefined;
+  readonly "aria-invalid": "true" | undefined;
   readonly onKeyDown: (event: KeyboardEvent) => void;
 }
+/** The error element: render it always, it is `hidden` while there is no error. */
+export type CheckboxGroupErrorProps = FieldErrorProps;
 export interface CheckboxGroup<T = unknown> {
   readonly children: Accessor<ReadonlyArray<boolean>>;
   readonly memory: Accessor<ReadonlyArray<boolean>>;
@@ -1080,6 +1193,14 @@ export interface CheckboxGroup<T = unknown> {
   readonly focused: Accessor<CheckboxGroupFocus>;
   readonly parentChecked: Accessor<ParentChecked>;
   readonly checkedValues: () => ReadonlyArray<T>;
+  /** The error shown: `undefined` unless the group is invalid and has a message. */
+  readonly error: () => string | undefined;
+  readonly invalid: () => boolean;
+  /**
+   * The ids `aria-describedby` lists now: the error (never while it is hidden),
+   * then the host's `describedby`.
+   */
+  readonly describedIds: () => readonly string[];
   readonly click: (target: CheckboxGroupFocus) => void;
   readonly keySpace: () => void;
   readonly keyTab: () => void;
@@ -1088,6 +1209,7 @@ export interface CheckboxGroup<T = unknown> {
   readonly setRemember: (value: boolean) => void;
   readonly setChildren: (children: ReadonlyArray<boolean>) => void;
   readonly groupProps: CheckboxGroupProps;
+  readonly errorProps: CheckboxGroupErrorProps;
   readonly parentProps: CheckboxGroupParentProps;
   readonly childProps: (index: 0 | 1 | 2) => CheckboxGroupChildProps;
 }
@@ -1103,7 +1225,17 @@ export interface CheckboxGroup<T = unknown> {
  * pass `value` + `onValueChange` to own the checked subset. The checked set is
  * packed internally so it rides the scalar `createControllable`.
  *
- * Behaviour is checked against `specs/apg/checkbox-group.qnt` by the bridge.
+ * The name, the description and the error are `createField`'s contract on the
+ * `role="group"` element (`aria-label` / `aria-labelledby`, `aria-describedby`,
+ * `aria-invalid`, an error element that is `role="alert"` while it is shown), so
+ * a group reads like the fields around it. The group is not a `<label for>`
+ * target: a host names a visible label element's id with `labelledby`, or passes
+ * `label` without one.
+ *
+ * Behaviour is checked against `specs/apg/checkbox-group.qnt` by the bridge. That
+ * model leaves labelling out on purpose ("shift+Tab, accessible names,
+ * fieldset/legend or role=group labelling" in its header), so the field contract
+ * is checked by plain assertions in `test/checkbox-group.browser.test.tsx`.
  */
 export declare const createCheckboxGroup: <T = unknown>(options: CheckboxGroupOptions<T>) => CheckboxGroup<T>;
 /**
@@ -1294,6 +1426,215 @@ export interface DialogModal {
  * are requests the host may ignore.
  */
 export declare const createDialogModal: (options?: DialogModalOptions) => DialogModal;
+export interface StatusOptions {
+  /** Rendered on `statusProps`; generated when absent. */
+  readonly id?: string | undefined;
+}
+/** Spread onto the `role=status` live region. Render it once, always. */
+export interface StatusProps {
+  readonly id: string;
+  readonly role: "status";
+  readonly "aria-live": "polite";
+  readonly "aria-atomic": "true";
+}
+export interface Status {
+  /** The text currently shown, or `undefined` before the first `show`. */
+  readonly message: Accessor<string | undefined>;
+  /** Writes the message, replacing the previous one; nothing is queued. */
+  readonly show: (text: string) => void;
+  readonly clear: () => void;
+  readonly statusProps: StatusProps;
+}
+/**
+ * APG Alert's polite sibling: one `role=status` live region whose text the host
+ * replaces ("Link copied", "Saved"). It is not a queue: a second message shows
+ * in place of the first, so a burst reads as the last state, not as N alerts.
+ * The region is rendered once and stays mounted, which is what makes a change
+ * of its text announced.
+ *
+ * A status is never for errors: an error that needs attention now is
+ * `createAlert` (`role=alert`, assertive), and a message with a title, a
+ * description and a timeout is `createToast`.
+ */
+export declare const createStatus: (options?: StatusOptions) => Status;
+/** 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 {
+  readonly type?: "text" | "email" | "tel" | "url" | "search" | "password" | undefined;
+  /** The HTML token list: the browser's own autofill is the accessible path. */
+  readonly autoComplete?: AutoCompleteToken | undefined;
+  readonly spellCheck?: boolean | undefined;
+  readonly autoCapitalize?: "none" | "sentences" | "words" | "characters" | undefined;
+  readonly inputMode?: "none" | "text" | "tel" | "url" | "email" | "numeric" | "decimal" | "search" | undefined;
+  readonly maxLength?: number | undefined;
+  readonly readOnly?: boolean | undefined;
+  readonly disabled?: boolean | undefined;
+  readonly name?: string | undefined;
+  readonly dir?: "ltr" | "rtl" | "auto" | undefined;
+  readonly placeholder?: string | undefined;
+  /** Change and input both land here; the host decides what a keystroke means. */
+  readonly onValueChange?: ((value: string) => void) | undefined;
+}
+export interface TextAreaOptions extends TextInputOptions {
+  readonly rows?: number | undefined;
+  readonly wrap?: "soft" | "hard" | "off" | undefined;
+  readonly resize?: "none" | "vertical" | "horizontal" | "both" | undefined;
+}
+export interface TextControlProps {
+  readonly id: string;
+  readonly "aria-describedby": string | undefined;
+  readonly "aria-invalid": "true" | undefined;
+  readonly "aria-required": "true" | undefined;
+  readonly required: true | undefined;
+  readonly type: TextInputOptions["type"];
+  readonly autoComplete: AutoCompleteToken | undefined;
+  readonly spellcheck: "true" | "false" | undefined;
+  readonly autocapitalize: TextInputOptions["autoCapitalize"];
+  readonly inputmode: TextInputOptions["inputMode"];
+  readonly maxlength: number | undefined;
+  readonly readOnly: true | undefined;
+  readonly disabled: true | undefined;
+  readonly name: string | undefined;
+  readonly dir: "ltr" | "rtl" | "auto" | undefined;
+  readonly placeholder: string | undefined;
+  readonly onInput: (event: {
+    currentTarget: {
+      value: string;
+    };
+  }) => void;
+}
+export interface TextAreaControlProps extends TextControlProps {
+  readonly rows: number | undefined;
+  readonly wrap: TextAreaOptions["wrap"];
+  readonly style: {
+    readonly resize: "none" | "vertical" | "horizontal" | "both";
+  } | undefined;
+}
+/** The field and the control, one object: every prop the element needs. */
+export interface TextInput extends Field {
+  readonly controlProps: TextControlProps;
+}
+export interface TextArea extends Field {
+  readonly controlProps: TextAreaControlProps;
+}
+/**
+ * A text input with the field contract attached: label, hint, error (announced),
+ * `aria-describedby` and `aria-invalid` come from `createField`; this adds the
+ * props a host forgets — autofill tokens, spellcheck, inputmode, maxlength, the
+ * disabled/readOnly pair. Platform: native (`input` is its own APG-equivalent;
+ * no primitive re-implements text editing, which is why there is no key
+ * handling here).
+ *
+ * Both `required` and `aria-required` are emitted: the native attribute is what
+ * the browser enforces, the ARIA one is what a custom widget reading the same
+ * props needs. A host that validates itself passes `noValidate` on the form
+ * rather than dropping the attribute.
+ */
+export declare const createTextInput: (options?: TextInputOptions) => TextInput;
+/**
+ * The same contract for a textarea, plus rows, wrap and resize. `resize` is a
+ * style because CSS has no attribute for it; `none` is the value a layout that
+ * owns its own height wants.
+ */
+export declare const createTextArea: (options?: TextAreaOptions) => TextArea;
+/** One command the host offers; `group` only picks the heading the host renders. */
+export interface PaletteCommand {
+  readonly id: string;
+  readonly label: string;
+  readonly group?: string | undefined;
+  readonly keywords?: ReadonlyArray<string> | undefined;
+  readonly run: () => void | Promise<void>;
+}
+/** A command that survived the filter, in host order. */
+export interface PaletteResult {
+  readonly id: string;
+  readonly label: string;
+  readonly group: string | undefined;
+}
+/** Every string the host puts on screen; override what you translate. */
+export interface CommandPaletteLabels {
+  /** The dialog's name; `titleProps` heads it and the listbox is named by it. */
+  readonly title: string;
+  readonly placeholder: string;
+  readonly empty: string;
+  /** The result count the polite region announces, once per query. */
+  readonly results: (count: number) => string;
+}
+export interface CommandPaletteOptions {
+  readonly commands: ReadonlyArray<PaletteCommand>;
+  /** Controlled: the host owns the open state and this is the only thing that changes it. */
+  readonly open?: boolean | undefined;
+  /** A request to change the open state, called when the intent differs. */
+  readonly onOpenChange?: ((open: boolean) => void) | undefined;
+  /** The `createHotkeys` chord `attach` binds; `"mod+k"` by default. */
+  readonly hotkey?: string | undefined;
+  readonly labels?: Partial<CommandPaletteLabels> | undefined;
+}
+export interface CommandPalette {
+  readonly open: Accessor<boolean>;
+  readonly openPalette: () => void;
+  readonly closePalette: () => void;
+  readonly query: Accessor<string>;
+  readonly setQuery: (text: string) => void;
+  /** Index into `results()`; `-1` = the search field holds the highlight. */
+  readonly active: Accessor<number>;
+  readonly setActive: (index: number) => void;
+  readonly results: Accessor<ReadonlyArray<PaletteResult>>;
+  readonly labels: CommandPaletteLabels;
+  /** The live region's text; render it inside `statusProps`. */
+  readonly status: Accessor<string | undefined>;
+  readonly inputProps: TextControlProps & {
+    readonly role: "searchbox";
+    readonly value: string;
+    readonly "aria-controls": string;
+    readonly "aria-activedescendant": string | undefined;
+    readonly onKeyDown: (event: KeyboardEvent) => void;
+  };
+  readonly listProps: {
+    readonly id: string;
+    readonly role: "listbox";
+    readonly "aria-labelledby": string;
+    /** A pointer click keeps the focus in the search field. */
+    readonly onMouseDown: (event: MouseEvent) => void;
+  };
+  readonly optionProps: (id: string) => {
+    readonly id: string;
+    readonly role: "option";
+    readonly "aria-selected": "true" | "false";
+    readonly tabindex: -1;
+    readonly onClick: () => void;
+    readonly onMouseEnter: () => void;
+  };
+  readonly emptyProps: {
+    readonly hidden: boolean;
+  };
+  readonly statusProps: StatusProps;
+  readonly dialogProps: DialogContentProps;
+  readonly backdropProps: DialogBackdropProps;
+  readonly titleProps: {
+    readonly id: string;
+  };
+  /** Runs the active command and closes the palette; a no-op with no highlight. */
+  readonly runActive: () => void | Promise<void>;
+  /** Binds the hotkey on the document; call once and call the teardown on cleanup. */
+  readonly attach: () => () => void;
+}
+/**
+ * A command palette: `createDialogModal` (a modal dialog, announced as one),
+ * `createTextInput` (a `searchbox`, not a combobox — choosing runs a command,
+ * it does not complete the field) and one filtered list. Focus stays in the
+ * field; `aria-activedescendant` names the highlighted option, and ↓ on the
+ * last / ↑ on the first return the highlight to the field. Home/End are menu
+ * keys only while the field is empty, so the caret keeps them while typing.
+ * Filtering is a plain case-insensitive substring match on the label and the
+ * keywords, no fuzzy scoring: a palette is short and stable, and ranking
+ * (recency, scopes) is a policy the host owns.
+ *
+ * The host's: rendering and grouping (the `group` field, headings, the CSS),
+ * async commands (a rejected `run` is the host's to report), and any close
+ * other than Escape / a command. `runActive` closes before it runs.
+ */
+export declare const createCommandPalette: (options: CommandPaletteOptions) => CommandPalette;
 export interface ConfirmOptions {
   readonly id?: string | undefined;
   /** Called with `true` when a request opens the dialog and `false` when it settles. */
@@ -1684,94 +2025,6 @@ export interface Feed {
  * request; `loadStart` / `loadFail` are adapter lifecycle events.
  */
 export declare const createFeed: (options?: FeedOptions) => Feed;
-export interface FieldOptions {
-  /** Base of every id the field makes (`<id>-control`, `-label`, `-hint`, `-error`). */
-  readonly id?: string | undefined;
-  readonly required?: boolean | undefined;
-  /**
-   * `true` marks the control invalid; a string does too and is the error message
-   * (unless `error` is set). `false` forces valid: an `error` is then not shown,
-   * so a host can pass `touched() && failed()` and keep the message ready.
-   * Left out, the field is invalid exactly when it has an error message.
-   */
-  readonly invalid?: boolean | string | undefined;
-  /** Help text; absent (or empty) means the hint element is hidden and not referenced. */
-  readonly hint?: string | undefined;
-  /** The error message; absent (or empty) means no error element. */
-  readonly error?: string | undefined;
-  /**
-   * Ids of elements the host owns, appended to `aria-describedby` after the
-   * field's own hint and error: a form-level error that belongs to several
-   * controls ("the passwords do not match" names both). One id or a list;
-   * empty strings are dropped, and the attribute is absent when nothing is left.
-   * The host keeps that element rendered, and decides whether it is hidden.
-   */
-  readonly describedby?: string | readonly string[] | undefined;
-}
-/** Spread onto the form control (`input`, `textarea`, `select`, or a custom widget). */
-export interface FieldControlProps {
-  readonly id: string;
-  /** The ids of the hint and the error that are shown, hint first, then the host's `describedby`; absent when there are none. */
-  readonly "aria-describedby": string | undefined;
-  readonly "aria-invalid": "true" | undefined;
-  /** For a control that is not native (a native one has `required`). */
-  readonly "aria-required": "true" | undefined;
-  readonly required: true | undefined;
-}
-export interface FieldLabelProps {
-  readonly id: string;
-  readonly for: string;
-}
-/** Spread onto the hint and the error element; render both, always. */
-export interface FieldMessageProps {
-  readonly id: string;
-  readonly hidden: boolean;
-}
-/** The error element also announces itself: `role="alert"` while it is shown. */
-export interface FieldErrorProps extends FieldMessageProps {
-  readonly role: "alert" | undefined;
-}
-export interface Field {
-  readonly invalid: () => boolean;
-  /** The hint, or `undefined` when there is none. */
-  readonly hint: () => string | undefined;
-  /** The error shown: `undefined` unless the field is invalid and has a message. */
-  readonly error: () => string | undefined;
-  /**
-   * The ids `aria-describedby` lists now: hint, then error (never an id that is
-   * hidden), then the host's `describedby`.
-   */
-  readonly describedIds: () => readonly string[];
-  readonly controlProps: FieldControlProps;
-  readonly labelProps: FieldLabelProps;
-  readonly hintProps: FieldMessageProps;
-  readonly errorProps: FieldErrorProps;
-}
-/**
- * The ARIA contract of a form field: a label, a control, a hint and an error.
- * There is no APG pattern for it (APG has no "form field"; the nearest is the
- * label and description rules of the accessible name computation), so the
- * contract comes from WAI-ARIA 1.2 (`aria-describedby`, `aria-invalid`,
- * `aria-required`) and HTML (`label[for]`, `required`), and from the
- * majority of Base UI Field, react-aria TextField and ariakit FormControl,
- * which list the description and the error message together. It is not checked
- * against a Quint spec; `test/field.browser.test.tsx` is its oracle.
- *
- * Decisions: the error does not replace the hint, both are listed, hint first
- * (the hint is what tells the user how to fix the error); an error implies
- * invalid and `invalid: false` overrides it; a hidden message is never
- * referenced, so `aria-describedby` has no dangling id. The error element is
- * `role="alert"` only while it is shown (a hidden element announces nothing, and
- * one that appears is announced); the hint is never an alert.
- *
- * `describedby` lists host-owned ids after the field's own: one refusal that
- * belongs to two controls is one form-level element (with its own `role`), named
- * by both. The field cannot know whether that element is shown: the host
- * passes the id only while it is.
- *
- * Options are read when an attribute is read: pass getters, never destructure.
- */
-export declare const createField: (options?: FieldOptions) => Field;
 export interface PaginationLabels {
   /** The navigation landmark's name; defaults to "Pagination". */
   readonly nav?: string | undefined;
@@ -2296,6 +2549,107 @@ export interface Hotkeys {
  * browser would otherwise act on (Cmd/Ctrl+S, Cmd/Ctrl+K).
  */
 export declare const createHotkeys: (options?: HotkeysOptions) => Hotkeys;
+/** How a drag turns the knob: the angle around the centre, a straight slide, or whichever the drag starts as. */
+export type KnobGesture = "spin" | "slide" | "both";
+export interface KnobLabels {
+  /** The knob's accessible name (`aria-label`); "Knob" by default. */
+  readonly knob?: string | undefined;
+}
+export interface KnobOptions {
+  readonly min?: number | undefined;
+  readonly max?: number | undefined;
+  readonly step?: number | undefined;
+  /** Controlled: the host owns the value and this is the only thing that changes it. */
+  readonly value?: number | undefined;
+  /** Starting value when uncontrolled (the middle of the range by default). */
+  readonly defaultValue?: number | undefined;
+  /**
+   * `false` (default): clamp at `min` / `max`. `true`: a continuous dial — the
+   * value wraps around (past `max` comes back at `min`), so a full turn of the
+   * skin is a full cycle.
+   */
+  readonly wrap?: boolean | undefined;
+  /** Which drag turns the knob; "both" (default) locks per drag from the first movement. */
+  readonly gesture?: KnobGesture | undefined;
+  readonly labels?: KnobLabels | undefined;
+  /** The spoken value (`aria-valuetext`); `String` by default. */
+  readonly format?: ((value: number) => string) | undefined;
+  /** Base for the generated value region id. */
+  readonly id?: string | undefined;
+  /**
+   * A request to change the value, called when the intent differs from the
+   * current value. Uncontrolled it is accepted; controlled the host may ignore it.
+   */
+  readonly onValueChange?: ((value: number) => void) | undefined;
+}
+/** Spread onto the knob element, the focusable control. */
+export interface KnobProps {
+  readonly role: "slider";
+  readonly tabindex: number;
+  readonly "aria-valuemin": string;
+  readonly "aria-valuemax": string;
+  readonly "aria-valuenow": string;
+  readonly "aria-valuetext": string;
+  readonly "aria-label": string;
+  readonly onKeyDown: (event: KeyboardEvent) => void;
+  readonly onPointerDown: (event: PointerEvent) => void;
+  readonly onPointerMove: (event: PointerEvent) => void;
+  readonly onPointerUp: (event: PointerEvent) => void;
+  readonly onPointerCancel: (event: PointerEvent) => void;
+  readonly onWheel: (event: WheelEvent) => void;
+}
+/** Spread onto the live value; render it once, always (hide it visually, never with `hidden`). */
+export interface KnobValueProps {
+  readonly id: string;
+  readonly role: "status";
+  readonly "aria-live": "polite";
+}
+export interface Knob {
+  readonly value: Accessor<number>;
+  /** A request, like a key or a drag; `setValue` never bypasses a controlled `value`. */
+  readonly setValue: (value: number) => void;
+  /**
+   * The fraction of a full turn the skin rotates by for `value`, 0..1 (multiply
+   * by 360 for degrees). Clamped to 0..1, or the wrapped fraction when `wrap`.
+   */
+  readonly percentOf: (value: number) => number;
+  /** A request to move by `delta` value units (a key, a wheel, a host button). */
+  readonly stepBy: (delta: number) => void;
+  readonly knobProps: KnobProps;
+  readonly valueProps: KnobValueProps;
+}
+/**
+ * A virtual knob after GarageBand's (https://jherrm.github.io/knobs/): one
+ * control turned three ways — spun around its centre, or slid vertically or
+ * horizontally, one gesture locked per drag. Plain Solid signals, no elements,
+ * no styling. **No ARIA role exists for a dial**, so the knob is a `role=slider`
+ * with `aria-valuenow` / `aria-valuetext`; the value the host renders in
+ * `valueProps` is the live announcement (`role=status`), and a numeric field
+ * must sit next to the dial, because a dial is never the only control.
+ *
+ * Request/commit (map ticket `rt1p`): uncontrolled by default (`defaultValue`);
+ * pass `value` + `onValueChange` to own the value. A key, a wheel, a drag and
+ * `setValue`/`stepBy` are requests the host may ignore.
+ *
+ * Gestures (`gesture`, default "both"), decided once on the first meaningful
+ * movement so a drag never switches modes:
+ * - a movement that stays on one axis (the other axis under `SLIDE_VARIANCE` of
+ *   it) locks a slide — the reference's "slide in a straight line";
+ * - any other movement is a turn around the centre: the angle the pointer
+ *   covers is the value, and the farther from the centre the finer it is;
+ * - `gesture: "spin"` / `"slide"` disable the other.
+ *
+ * A vertical slide turns the knob the way the grabbed side would turn a real
+ * one: down on the right half is clockwise (up in value), down on the left half
+ * counter-clockwise. A horizontal slide uses the same left/right side (the
+ * reference picks top/bottom for this one; one rule for both is simpler to
+ * learn). `wrap` makes the dial continuous instead of clamped.
+ *
+ * ponytail: no momentum/inertia and no `disabled` — the reference has a
+ * deceleration tail, and no host here has asked for one; add inertia in the
+ * host's rAF loop if a look needs it.
+ */
+export declare const createKnob: (options?: KnobOptions) => Knob;
 export interface LinkOptions {
   readonly href?: string | undefined;
   /** Render a native `<a href>` (the default when `href` is set). */
@@ -2451,8 +2805,12 @@ export declare const createListbox: (options: ListboxOptions) => Listbox;
  * dismiss and Esc; `focusgroup` gives the menubar's roving tabindex. The
  * library owns the menu keys, typeahead, submenus and checkable state.
  *
- * ponytail: uncontrolled; add a `value`/`onValueChange` host pair when a
- * consumer owns open/checked state.
+ * Request/commit (map ticket `rt1p`): the open state, and the checked items of
+ * the checkable variants, are controllable. Uncontrolled by default
+ * (`defaultOpen` / `defaultValue`); pass `open` / `value` (+ `onOpenChange` /
+ * `onCheckedValueChange`) to own them. Every opening and closing intent — the
+ * trigger's click and keys, Escape, an item's activation, Tab, and the
+ * programmatic `openMenu` / `closeMenu` — is a request the host may ignore.
  */
 export type MenuItemKind = "item" | "checkbox" | "radio";
 export interface MenuItemInput {
@@ -2465,6 +2823,9 @@ export type MenuVariant = "plain" | "checkbox-items" | "radio-items" | "mixed";
 export interface MenuOptions {
   readonly items: ReadonlyArray<string | MenuItemInput>;
   readonly variant?: MenuVariant;
+  /** Controlled: the host owns the open state and this is the only thing that opens or closes it. */
+  readonly open?: boolean | undefined;
+  /** Uncontrolled starting state; ignored while `open` is set. */
   readonly defaultOpen?: boolean;
   /**
    * `outside` (menu button): focus can sit outside the widget, so keys are
@@ -2480,7 +2841,7 @@ export interface MenuOptions {
    * Controlled: the host owns the checked items. Packed as
    * `checkboxItem0 * 5 + radioChoice` (1-based), matching `menu-checkable.qnt`'s
    * `checked(wrap, choice)`; pass `undefined` for uncontrolled. The open state
-   * stays uncontrolled.
+   * has its own `open` pair.
    */
   readonly value?: number | undefined;
   /** The uncontrolled packed checked state at mount. */
@@ -2490,6 +2851,10 @@ export interface MenuOptions {
   /** Item indices disabled (focusable, not activatable). */
   readonly disabled?: ReadonlyArray<number>;
   readonly id?: string;
+  /**
+   * A request to change the open state, called when the intent differs from the
+   * current one. Uncontrolled it is accepted; controlled the host may ignore it.
+   */
   readonly onOpenChange?: (open: boolean) => void;
   readonly onItemClick?: (index: number) => void;
   readonly onCheckedChange?: (checked: boolean, index: number) => void;
@@ -3190,37 +3555,6 @@ export interface Spinbutton {
  * APG text.
  */
 export declare const createSpinbutton: (options?: SpinbuttonOptions) => Spinbutton;
-export interface StatusOptions {
-  /** Rendered on `statusProps`; generated when absent. */
-  readonly id?: string | undefined;
-}
-/** Spread onto the `role=status` live region. Render it once, always. */
-export interface StatusProps {
-  readonly id: string;
-  readonly role: "status";
-  readonly "aria-live": "polite";
-  readonly "aria-atomic": "true";
-}
-export interface Status {
-  /** The text currently shown, or `undefined` before the first `show`. */
-  readonly message: Accessor<string | undefined>;
-  /** Writes the message, replacing the previous one; nothing is queued. */
-  readonly show: (text: string) => void;
-  readonly clear: () => void;
-  readonly statusProps: StatusProps;
-}
-/**
- * APG Alert's polite sibling: one `role=status` live region whose text the host
- * replaces ("Link copied", "Saved"). It is not a queue: a second message shows
- * in place of the first, so a burst reads as the last state, not as N alerts.
- * The region is rendered once and stays mounted, which is what makes a change
- * of its text announced.
- *
- * A status is never for errors: an error that needs attention now is
- * `createAlert` (`role=alert`, assertive), and a message with a title, a
- * description and a timeout is `createToast`.
- */
-export declare const createStatus: (options?: StatusOptions) => Status;
 export interface SwitchOptions {
   /** Controlled: the host owns the state and this is the only thing that changes it. */
   readonly value?: boolean | undefined;
@@ -3451,86 +3785,6 @@ export interface Table {
  * 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 {
-  readonly type?: "text" | "email" | "tel" | "url" | "search" | "password" | undefined;
-  /** The HTML token list: the browser's own autofill is the accessible path. */
-  readonly autoComplete?: AutoCompleteToken | undefined;
-  readonly spellCheck?: boolean | undefined;
-  readonly autoCapitalize?: "none" | "sentences" | "words" | "characters" | undefined;
-  readonly inputMode?: "none" | "text" | "tel" | "url" | "email" | "numeric" | "decimal" | "search" | undefined;
-  readonly maxLength?: number | undefined;
-  readonly readOnly?: boolean | undefined;
-  readonly disabled?: boolean | undefined;
-  readonly name?: string | undefined;
-  readonly dir?: "ltr" | "rtl" | "auto" | undefined;
-  readonly placeholder?: string | undefined;
-  /** Change and input both land here; the host decides what a keystroke means. */
-  readonly onValueChange?: ((value: string) => void) | undefined;
-}
-export interface TextAreaOptions extends TextInputOptions {
-  readonly rows?: number | undefined;
-  readonly wrap?: "soft" | "hard" | "off" | undefined;
-  readonly resize?: "none" | "vertical" | "horizontal" | "both" | undefined;
-}
-export interface TextControlProps {
-  readonly id: string;
-  readonly "aria-describedby": string | undefined;
-  readonly "aria-invalid": "true" | undefined;
-  readonly "aria-required": "true" | undefined;
-  readonly required: true | undefined;
-  readonly type: TextInputOptions["type"];
-  readonly autoComplete: AutoCompleteToken | undefined;
-  readonly spellcheck: "true" | "false" | undefined;
-  readonly autocapitalize: TextInputOptions["autoCapitalize"];
-  readonly inputmode: TextInputOptions["inputMode"];
-  readonly maxlength: number | undefined;
-  readonly readOnly: true | undefined;
-  readonly disabled: true | undefined;
-  readonly name: string | undefined;
-  readonly dir: "ltr" | "rtl" | "auto" | undefined;
-  readonly placeholder: string | undefined;
-  readonly onInput: (event: {
-    currentTarget: {
-      value: string;
-    };
-  }) => void;
-}
-export interface TextAreaControlProps extends TextControlProps {
-  readonly rows: number | undefined;
-  readonly wrap: TextAreaOptions["wrap"];
-  readonly style: {
-    readonly resize: "none" | "vertical" | "horizontal" | "both";
-  } | undefined;
-}
-/** The field and the control, one object: every prop the element needs. */
-export interface TextInput extends Field {
-  readonly controlProps: TextControlProps;
-}
-export interface TextArea extends Field {
-  readonly controlProps: TextAreaControlProps;
-}
-/**
- * A text input with the field contract attached: label, hint, error (announced),
- * `aria-describedby` and `aria-invalid` come from `createField`; this adds the
- * props a host forgets — autofill tokens, spellcheck, inputmode, maxlength, the
- * disabled/readOnly pair. Platform: native (`input` is its own APG-equivalent;
- * no primitive re-implements text editing, which is why there is no key
- * handling here).
- *
- * Both `required` and `aria-required` are emitted: the native attribute is what
- * the browser enforces, the ARIA one is what a custom widget reading the same
- * props needs. A host that validates itself passes `noValidate` on the form
- * rather than dropping the attribute.
- */
-export declare const createTextInput: (options?: TextInputOptions) => TextInput;
-/**
- * The same contract for a textarea, plus rows, wrap and resize. `resize` is a
- * style because CSS has no attribute for it; `none` is the value a layout that
- * owns its own height wants.
- */
-export declare const createTextArea: (options?: TextAreaOptions) => TextArea;
 export type TabsOrientation = "horizontal" | "vertical";
 export type TabsActivation = "automatic" | "manual";
 /**