@zeyos/zx 4.4.0 → 5.0.0

package/dist/types/components/message/message.d.ts

@@ -1,18 +1,48 @@
 import { Component } from '../../core/component.js';
 export type MessageKind = 'info' | 'success' | 'warning' | 'error';
+export type MessageAction = {
+    /**
+     * Button text: a verb naming what happens ("Undo", "Approve", "Retry").
+     */
+    label: string;
+    /**
+     * Runs when the button is activated, by pointer
+     * or keyboard; the message closes right after it.
+     */
+    onclick?: (event: MouseEvent) => void;
+    /**
+     * Button kind; the default is the
+     * secondary button.
+     */
+    kind?: 'default' | 'primary' | 'danger' | 'ghost';
+};
 export type MessageShowOptions = {
     /**
      * Message intent (`danger` aliases `error`).
      */
     kind?: MessageKind | 'danger';
     /**
-     * Auto-dismiss delay in milliseconds; zero persists.
+     * Auto-dismiss delay in milliseconds; zero persists. A message
+     * with an `action` stays at least 8000ms.
      */
     timeout?: number;
     /**
      * Whether to render a close button.
      */
     closable?: boolean;
+    /**
+     * A command button inside the message. The message
+     * never times out while the pointer is over it or focus is inside it.
+     */
+    action?: MessageAction | null;
+    /**
+     * Visual shown in place of the
+     * kind icon, such as an Avatar's element. It is decorative — the message text must say what it
+     * shows.
+     */
+    leading?: Node | {
+        toElement: () => Node | null;
+    } | null;
     /**
      * Element whose nearest Zx theme scope owns a floating toast.
      */
@@ -37,28 +67,32 @@ export type MessageOptions = {
     maxVisible?: number;
 };
 export type MessageHandle = {
-    close: () => void;
-};
-export type ProgressHandle = {
     /**
-     * Updates progress and optional text.
+     * Closes the message.
      */
-    update: (pct: number, text?: string) => void;
-    /**
-     * Completes and dismisses the progress message.
-     */
-    done: () => void;
-    /**
-     * Marks progress as failed and dismisses it later.
-     */
-    fail: (text?: string) => void;
+    close: () => void;
 };
 /** @typedef {'info'|'success'|'warning'|'error'} MessageKind */
+/**
+ * The one command a message may carry, drawn as a small button beside its text.
+ * @typedef {Object} MessageAction
+ * @property {string} label Button text: a verb naming what happens ("Undo", "Approve", "Retry").
+ * @property {(event: MouseEvent) => void} [onclick] Runs when the button is activated, by pointer
+ *   or keyboard; the message closes right after it.
+ * @property {'default'|'primary'|'danger'|'ghost'} [kind='default'] Button kind; the default is the
+ *   secondary button.
+ */
 /**
  * @typedef {Object} MessageShowOptions
  * @property {MessageKind|'danger'} [kind='info'] Message intent (`danger` aliases `error`).
- * @property {number} [timeout=4000] Auto-dismiss delay in milliseconds; zero persists.
+ * @property {number} [timeout=4000] Auto-dismiss delay in milliseconds; zero persists. A message
+ *   with an `action` stays at least 8000ms.
  * @property {boolean} [closable=true] Whether to render a close button.
+ * @property {MessageAction|null} [action=null] A command button inside the message. The message
+ *   never times out while the pointer is over it or focus is inside it.
+ * @property {Node|{toElement: () => Node|null}|null} [leading=null] Visual shown in place of the
+ *   kind icon, such as an Avatar's element. It is decorative — the message text must say what it
+ *   shows.
  * @property {Element|string|null} [scope=null] Element whose nearest Zx theme scope owns a floating toast.
  */
 /**
@@ -68,7 +102,28 @@ export type ProgressHandle = {
  * @property {boolean} [closable=true] Default close-button visibility.
  * @property {number} [maxVisible=5] Maximum number of visible messages.
  */
-/** @typedef {{close: () => void}} MessageHandle */
+/**
+ * Returned by every `show()`: closes that message early. Closing one that already closed, or one
+ * still waiting in the queue, is safe.
+ * @typedef {Object} MessageHandle
+ * @property {() => void} close Closes the message.
+ */
+/** The shortest time a message that carries an action stays, in milliseconds. */
+export declare const MESSAGE_ACTION_MIN_TIMEOUT = 8000;
+export type ProgressHandle = {
+    /**
+     * Updates progress and optional text.
+     */
+    update: (pct: number, text?: string) => void;
+    /**
+     * Completes and dismisses the progress message.
+     */
+    done: () => void;
+    /**
+     * Marks progress as failed and dismisses it later.
+     */
+    fail: (text?: string) => void;
+};
 /**
  * @typedef {Object} ProgressHandle
  * @property {(pct: number, text?: string) => void} update Updates progress and optional text.
@@ -129,6 +184,8 @@ export declare class Message extends Component<MessageOptions> {
         children: Node[];
     };
     _entries: Set<any>;
+    /** @type {Element|null} The overlay host this instance is the floating region of; null when inline. */
+    _floatingHost: Element | null;
     _queue: MessageQueue<any>;
     _cleaned: boolean;
     static cssName: string;
@@ -187,13 +244,24 @@ export declare class Message extends Component<MessageOptions> {
     static progress(text: string, options?: {
         scope?: Element | string | null;
     }): ProgressHandle;
+    /**
+     * Removes a floating region at once, toasts and all, without waiting for them to time out.
+     *
+     * A region already removes itself when its last toast closes, and one whose host has left the
+     * document is replaced on the next toast, so this is only for a host being torn down while
+     * toasts are still showing — an application view unmounting its themed shell, say.
+     * @param {Element|string} scope Element or selector whose nearest Zx theme scope owns the region,
+     *   as passed to `show()`.
+     * @returns {boolean} Whether there was a region to remove.
+     */
+    static disposeRegion(scope: Element | string): boolean;
     /** @returns {void} */
     destroy(): void;
     /** @param {string} text @returns {ProgressHandle} */
     _progress(text: string): ProgressHandle;
     /**
      * @param {string|Node} msg
-     * @param {{kind: MessageKind, timeout: number, closable: boolean}} settings
+     * @param {{kind: MessageKind, timeout: number, closable: boolean, action?: MessageAction|null, leading?: Node|null}} settings
      * @param {{pct: number, text: string}|null} [progress=null]
      * @returns {any}
      */
@@ -201,6 +269,8 @@ export declare class Message extends Component<MessageOptions> {
         kind: MessageKind;
         timeout: number;
         closable: boolean;
+        action?: MessageAction | null;
+        leading?: Node | null;
     }, progress?: {
         pct: number;
         text: string;
@@ -217,6 +287,17 @@ export declare class Message extends Component<MessageOptions> {
     _close(entry: any): void;
     /** @param {any} entry @returns {void} */
     _finish(entry: any): void;
+    /**
+     * Takes a floating region out of the document once its last toast has gone, so an emptied host
+     * is not left holding a region nobody uses. Inline areas stay: their element is the caller's.
+     * @returns {void}
+     */
+    _releaseIfEmpty(): void;
+    /**
+     * Destroys a floating region and removes its element.
+     * @returns {void}
+     */
+    _disposeFloating(): void;
     /**
      * Resolves a message through the host translator, falling back to the built-in English text.
      * @param {string} key Message key.
@@ -225,3 +306,24 @@ export declare class Message extends Component<MessageOptions> {
      */
     _message(key: string, fallback: string): string;
 }
+/**
+ * Settles how long a message stays. A message that carries an action stays at least
+ * `MESSAGE_ACTION_MIN_TIMEOUT`, so there is time to reach it; zero still means it stays until
+ * closed, and anything that is not a finite number falls back to the 4000ms default.
+ * @param {unknown} timeout Requested auto-dismiss delay in milliseconds.
+ * @param {boolean} [hasAction=false] Whether the message carries an action.
+ * @returns {number}
+ */
+export declare function messageTimeout(timeout: unknown, hasAction?: boolean): number;
+/**
+ * Copies a message action into the shape the message renders, or returns null when there is
+ * nothing to render: no object, or no label. An unknown `kind` reads as the default, secondary
+ * button, and a missing `onclick` leaves a button that only closes the message.
+ * @param {unknown} value Action descriptor.
+ * @returns {{label: string, kind: 'default'|'primary'|'danger'|'ghost', onclick: ((event: MouseEvent) => void)|null}|null}
+ */
+export declare function normalizeMessageAction(value: unknown): {
+    label: string;
+    kind: 'default' | 'primary' | 'danger' | 'ghost';
+    onclick: ((event: MouseEvent) => void) | null;
+} | null;

package/dist/types/components/modal/modal.d.ts

@@ -23,7 +23,7 @@ export type ModalOptions = {
      */
     destroyOnClose?: boolean;
     /**
-     * Element whose nearest Zx theme scope owns the overlay; defaults to the opener.
+     * Element whose nearest Zx theme scope owns the overlay; defaults to the opener. Resolved on every open, so a scope connected after construction still owns it.
      */
     scope?: Element | string | null;
     /**
@@ -48,7 +48,7 @@ export type ModalOptions = {
  * @property {boolean} [closable=true] Whether Escape may close the modal.
  * @property {boolean} [lightDismiss=false] Whether a backdrop click closes the modal.
  * @property {boolean} [destroyOnClose=false] Whether to destroy the modal after it closes.
- * @property {Element|string|null} [scope=null] Element whose nearest Zx theme scope owns the overlay; defaults to the opener.
+ * @property {Element|string|null} [scope=null] Element whose nearest Zx theme scope owns the overlay; defaults to the opener. Resolved on every open, so a scope connected after construction still owns it.
  * @property {(event: CustomEvent<Record<string, never>>) => void} [onopen] Open event listener.
  * @property {(event: CustomEvent<{result: unknown}>) => void} [onclose] Close event listener.
  * @property {(event: CustomEvent<Record<string, never>>) => void} [oncancel] Cancel event listener.
@@ -154,6 +154,17 @@ export declare class Modal extends Component<ModalOptions> {
      * @returns {HTMLDialogElement}
      */
     render(): HTMLDialogElement;
+    /**
+     * Gives a freshly rendered dialog its first home.
+     *
+     * A `scope` that is not in the document yet cannot say which theme it belongs to, and the
+     * `<body>` that `mountTarget()` would answer is outside it. The dialog then stays detached and
+     * `open()` places it, by which time the scope is in place. Called from `render()`, so it may
+     * read `this.options` but no instance state.
+     * @param {HTMLDialogElement} dialog The rendered dialog.
+     * @returns {void}
+     */
+    _mountInitial(dialog: HTMLDialogElement): void;
     /**
      * Opens the modal in the browser top layer.
      * @returns {this}

package/dist/types/components/select/color.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Accepts an item colour for an inline custom property: a CSS colour literal (`#0b7285`, `rgb(…)`,
+ * `oklch(…)`, a named colour) or a reference to a design token (`var(--zx-color-tone-blue-fg)`),
+ * so an item can follow the theme rather than fix one colour for light and dark alike. Anything
+ * else — other functions, declarations, a `var()` with a fallback — is refused.
+ *
+ * Shared by `Select.entity()` and `TagPicker`, the two components that take a colour per item.
+ *
+ * @param {unknown} value Candidate colour.
+ * @returns {string|null} The trimmed colour, or null when the value is not one.
+ */
+export declare function itemColor(value: unknown): string | null;

package/dist/types/components/select/glyphs.d.ts

@@ -0,0 +1,124 @@
+export type StatusIndicator = 'dotted' | 'ring' | 'progress' | 'review' | 'ready' | 'waiting' | 'done' | 'canceled' | 'duplicate';
+export type StatusTone = 'muted' | 'neutral' | 'warning' | 'info' | 'accent' | 'success' | 'danger';
+export type StatusId = 'backlog' | 'todo' | 'in-progress' | 'in-review' | 'review' | 'ready' | 'waiting' | 'done' | 'canceled' | 'cancelled' | 'duplicate';
+export type StatusIconOptions = {
+    /**
+     * Shape, overriding the status's own.
+     */
+    indicator?: StatusIndicator;
+    /**
+     * Colour, overriding the status's own.
+     */
+    tone?: StatusTone;
+    /**
+     * Accessible name. Without one the glyph is decorative
+     * (`aria-hidden`) and must sit beside text, or inside a control with a tooltip, that says the
+     * status.
+     */
+    label?: string | null;
+};
+export type PriorityIconOptions = {
+    /**
+     * Accessible name. Without one the glyph is decorative
+     * (`aria-hidden`) and must sit beside text, or inside a control with a tooltip, that says the
+     * priority.
+     */
+    label?: string | null;
+};
+/**
+ * The shapes a workflow-status glyph can take. Each status reads by shape first and colour
+ * second, so the set stays legible to readers who do not see the colour.
+ * @typedef {'dotted'|'ring'|'progress'|'review'|'ready'|'waiting'|'done'|'canceled'|'duplicate'} StatusIndicator
+ */
+/** @typedef {'muted'|'neutral'|'warning'|'info'|'accent'|'success'|'danger'} StatusTone */
+/**
+ * The built-in workflow statuses. `review` and `cancelled` are accepted as spellings of
+ * `in-review` and `canceled`.
+ * @typedef {'backlog'|'todo'|'in-progress'|'in-review'|'review'|'ready'|'waiting'|'done'|'canceled'|'cancelled'|'duplicate'} StatusId
+ */
+/**
+ * @typedef {Object} StatusIconOptions
+ * @property {StatusIndicator} [indicator] Shape, overriding the status's own.
+ * @property {StatusTone} [tone] Colour, overriding the status's own.
+ * @property {string|null} [label=null] Accessible name. Without one the glyph is decorative
+ *   (`aria-hidden`) and must sit beside text, or inside a control with a tooltip, that says the
+ *   status.
+ */
+/**
+ * @typedef {Object} PriorityIconOptions
+ * @property {string|null} [label=null] Accessible name. Without one the glyph is decorative
+ *   (`aria-hidden`) and must sit beside text, or inside a control with a tooltip, that says the
+ *   priority.
+ */
+/** Every shape `statusIcon()` draws. */
+export declare const STATUS_INDICATORS: readonly string[];
+/** Every colour a status glyph takes, from the semantic set. */
+export declare const STATUS_TONES: readonly string[];
+/**
+ * The built-in statuses in workflow order, as `[id, message key, English name, indicator, tone]`.
+ * `Select.status()` lists them; `statusIcon()` draws them.
+ */
+export declare const DEFAULT_STATUSES: readonly string[][];
+/** The top priority level, the one coloured level: a danger square with an exclamation mark. */
+export declare const PRIORITY_URGENT = 4;
+/**
+ * Resolves the shape and colour of a status glyph.
+ *
+ * A status is a built-in id (or one of its other spellings), or a status item of the kind
+ * `Select.status({items})` takes, whose own `indicator` and `tone` win over the built-in status
+ * its `ID` names. Options win over both. An unknown shape falls back to the empty ring and an
+ * unknown colour to muted, as `Select.status()` does with a custom item.
+ * @param {StatusId|string|{ID?: unknown, id?: unknown, indicator?: unknown, tone?: unknown}|null|undefined} status
+ * @param {StatusIconOptions} [options={}] Overrides.
+ * @returns {{indicator: StatusIndicator, tone: StatusTone}}
+ */
+export declare function resolveStatusGlyph(status: StatusId | string | {
+    ID?: unknown;
+    id?: unknown;
+    indicator?: unknown;
+    tone?: unknown;
+} | null | undefined, options?: StatusIconOptions): {
+    indicator: StatusIndicator;
+    tone: StatusTone;
+};
+/**
+ * Maps a status id to its built-in spelling: trimmed, lower-cased, and `review` / `cancelled`
+ * read as `in-review` / `canceled`.
+ * @param {unknown} id Status id.
+ * @returns {string}
+ */
+export declare function normalizeStatusId(id: unknown): string;
+/**
+ * Settles a priority level: an integer from 0 (lowest) to 4 (highest), or `null` for no priority.
+ * Out-of-range numbers clamp; anything that is not a number reads as 0.
+ * @param {unknown} level Priority level.
+ * @returns {number|null}
+ */
+export declare function normalizePriorityLevel(level: unknown): number | null;
+/**
+ * Draws the workflow-status glyph `Select.status()` shows, for a list row, a board column, a
+ * filter chip, or a heading — so every place a status appears reads as the picker that changes it.
+ *
+ * Built-in statuses: `backlog` (dotted ring), `todo` (empty ring), `in-progress` (ring with a
+ * centre dot), `in-review` (half filled; also `review`), `ready` (a third filled), `waiting` (two
+ * thirds filled), `done` (filled, with a check), `canceled` (filled, with a cross; also
+ * `cancelled`), and `duplicate` (ring with a slash). Colour only repeats what the shape says.
+ * @param {StatusId|string|{ID?: unknown, indicator?: unknown, tone?: unknown}} status Built-in id,
+ *   or a status item with its own `indicator` and `tone`.
+ * @param {StatusIconOptions} [options={}] Shape, colour, and accessible-name overrides.
+ * @returns {HTMLSpanElement} A `.zx-status-icon` element, decorative unless `label` is given.
+ */
+export declare function statusIcon(status: StatusId | string | {
+    ID?: unknown;
+    indicator?: unknown;
+    tone?: unknown;
+}, options?: StatusIconOptions): HTMLSpanElement;
+/**
+ * Draws the priority glyph `Select.priority()` shows. Levels 0–3 are four signal bars in muted
+ * ink, filled up to the level; level 4, the highest, is a filled danger square whose "!" the
+ * stylesheet draws, so it never joins the text beside it; no priority (`null`) is a row of dashes.
+ * @param {number|null} level Priority level, 0 (lowest) to 4 (highest), or `null` for none.
+ * @param {PriorityIconOptions} [options={}] Accessible-name option.
+ * @returns {HTMLSpanElement} A `.zx-priority-icon` element, decorative unless `label` is given.
+ */
+export declare function priorityIcon(level: number | null, options?: PriorityIconOptions): HTMLSpanElement;

package/dist/types/components/select/select.d.ts

@@ -147,7 +147,9 @@ export type EntitySelectOptions = {
      */
     iconKey?: string | ((item: SelectItem) => unknown);
     /**
-     * Optional icon colour reader.
+     * Optional icon colour reader: a CSS
+     * colour or a token reference such as `var(--zx-color-tone-blue-fg)`. Without one the glyph is a
+     * neutral tile in muted ink.
      */
     colorKey?: string | ((item: SelectItem) => unknown);
     /**
@@ -214,6 +216,7 @@ export declare class Select extends Component<SelectOptions> {
     _createdRoot: boolean;
     _root: HTMLElement;
     _snapshot: import("../../core/dom.js").TargetSnapshot;
+    _pointerModality: boolean;
     _handleTypeahead: (event: KeyboardEvent | string) => void;
     static cssName: string;
     /** @type {SelectOptions} */
@@ -267,9 +270,14 @@ export declare class Select extends Component<SelectOptions> {
     /** Moves focus to the combobox input. @returns {this} */
     focus(): this;
     /**
-     * Creates the five-level priority preset.
+     * Creates the five-level priority preset: values 0 (lowest) to 4 (highest), each drawn as grey
+     * signal bars filled to its level, except the highest, which is the one coloured level — a
+     * danger square with an exclamation mark. A "No priority" row (value null, a row of dashes)
+     * heads the list and labels the empty control; `clearable: false` removes it.
      * @param {Element|string|null} target Component target.
-     * @param {SelectOptions} [options={}] Select overrides other than fixed items and renderer.
+     * @param {SelectOptions} [options={}] Select overrides other than items and renderers.
+     *   `clearable` defaults to true here; `noneLabel` and `placeholder` default to the
+     *   `priority.none` message ("No priority").
      * @returns {Select}
      */
     static priority(target: Element | string | null, options?: SelectOptions): Select;

package/dist/types/components/stat-tile/stat-tile.d.ts

@@ -31,6 +31,10 @@ export type StatTileNameParts = {
      * The formatted value.
      */
     value?: string;
+    /**
+     * The context line under the value, e.g. `'of 13,184'`.
+     */
+    caption?: string;
     /**
      * The change, already worded for speech (`'up 2'`, not `'+2'`).
      */
@@ -58,6 +62,11 @@ export type StatTileOptions = {
      * ISO 4217 code used by `format: 'currency'`.
      */
     currency?: string | null;
+    /**
+     * A muted context line under the value — what the number is out
+     * of or measured in, e.g. `'of 13,184'` or `'open tickets'`. Part of the accessible name.
+     */
+    caption?: string;
     /**
      * BCP 47 tag for every formatter; defaults to the active language.
      */
@@ -87,12 +96,13 @@ export type StatTileOptions = {
      */
     trend?: number[];
     /**
-     * Icon name from `icons.js`, shown beside the label.
+     * Icon name from `icons.js`, shown muted beside the label —
+     * a glyph, not a coloured chip.
      */
     icon?: string | null;
     /**
-     * Semantic intent. It tints the icon and the sparkline
-     * and never the value, which stays at full text contrast whatever intent a record carries.
+     * Semantic intent. It tints the sparkline and never the
+     * value, which stays at full text contrast whatever intent a record carries.
      */
     kind?: StatTileKind;
     /**
@@ -245,10 +255,11 @@ export declare function statTileTag(options?: {
     onclick?: unknown;
 }): 'a' | 'button' | 'div';
 /**
- * Composes the tile's accessible name: label, then value, then how it changed.
+ * Composes the tile's accessible name: label, then value with its caption, then how it changed.
  *
  * The sparkline is decoration and contributes nothing, and the delta arrives already worded —
- * `'up 2'` rather than `'+2'` — because a screen reader should not have to interpret a glyph.
+ * `'up 2'` rather than `'+2'` — because a screen reader should not have to interpret a glyph. The
+ * caption is read with the value it qualifies (`'2,184 of 13,184'`), not as a separate clause.
  *
  * @param {StatTileNameParts} [parts={}] The pieces, already formatted and translated.
  * @returns {string} The name, with empty pieces dropped rather than left as stray punctuation.

package/dist/types/components/tabbox/tabbox.d.ts

@@ -53,6 +53,12 @@ export type TabboxOptions = {
      * Keep inactive panel elements mounted.
      */
     keepAlive?: boolean;
+    /**
+     * Accessible name of the tab list — what the tabs switch between
+     * ("Record sections"). A tab list needs one whenever the page has more than one, and screen
+     * readers announce it on entry.
+     */
+    label?: string;
     /**
      * Change callback.
      */
@@ -107,6 +113,9 @@ export type TabRecord = {
  *   the active tab across a full-width rule; `segmented` renders a compact group that reads as one
  *   control, for a toolbar or card header.
  * @property {boolean} [keepAlive=true] Keep inactive panel elements mounted.
+ * @property {string} [label] Accessible name of the tab list — what the tabs switch between
+ *   ("Record sections"). A tab list needs one whenever the page has more than one, and screen
+ *   readers announce it on entry.
  * @property {(event: CustomEvent<{name: string, previous: string|null}>) => void} [onchange] Change callback.
  * @property {(event: CustomEvent<{name: string}>) => void} [onclose] Close callback, fired when the
  *   user dismisses a closable tab.

package/dist/types/components/table/table.d.ts

@@ -3,6 +3,7 @@ export type TableRow = Record<string, any>;
 export type TableSortDirection = 'asc' | 'desc';
 export type TableSelectionMode = false | 'single' | 'multi';
 export type TableEditMode = false | 'cell' | 'row';
+export type TableVariant = 'default' | 'plain';
 export type TableEditorType = 'text' | 'number' | 'select' | 'date' | 'checkbox' | 'textarea' | 'custom';
 export type TableColumnType = 'text' | 'number' | 'currency' | 'percent' | 'unit';
 export type TableEditorOption = {
@@ -76,9 +77,16 @@ export type TableColumn = {
      */
     id: string;
     /**
-     * Visible header label.
+     * Visible header label. An empty label leaves the header blank — an
+     * icon or actions column — and the header is then named by `ariaLabel`, or by the id.
      */
     label: string;
+    /**
+     * Accessible name of the column header, and the name the column
+     * chooser and the cell editors use. Needed when `label` is empty or terse (`'#'`); include the
+     * visible label's words in it when there is one.
+     */
+    ariaLabel?: string;
     /**
      * Whether the header changes the active sort.
      */
@@ -249,6 +257,12 @@ export type TableOptions = {
      * Whether alternate rows use the zebra background.
      */
     zebra?: boolean;
+    /**
+     * Frame treatment. `'default'` draws the table's own
+     * bordered box; `'plain'` is for a table inside a card or panel that already draws one — no outer
+     * frame, no header band, no zebra, hairline row dividers. Reflected as `data-variant` on the root.
+     */
+    variant?: TableVariant;
     /**
      * Inline editing mode. `'cell'` edits one cell, `'row'`
      * opens every editable cell of the row together and commits them as a unit. Editing is completely
@@ -1392,12 +1406,43 @@ export declare function firstValidationError(values: Record<string, unknown>, co
     columnId: string;
     message: string;
 } | null;
+/**
+ * Resolves the `variant` option to one the stylesheet knows; anything else is the default frame.
+ * @param {unknown} value Requested variant.
+ * @returns {TableVariant}
+ */
+export declare function normalizeTableVariant(value: unknown): TableVariant;
 /**
  * Validates and shallow-clones table columns so stable-id APIs never mutate caller descriptors.
  * @param {unknown} columns Column descriptors.
  * @returns {TableColumn[]} Normalized descriptors.
  */
 export declare function normalizeTableColumns(columns: unknown): TableColumn[];
+/**
+ * The name a column goes by wherever it is named rather than shown: its `ariaLabel`, else its
+ * visible label, else its id. The column chooser lists columns by it and cell editors are labelled
+ * with it, so a column with a blank header still has a name in both.
+ * @param {Partial<TableColumn>|null|undefined} column Column descriptor.
+ * @returns {string} Non-empty name, unless the column has no id either.
+ */
+export declare function tableColumnName(column: Partial<TableColumn> | null | undefined): string;
+/**
+ * The accessible name a column header needs on top of its content, or null when its visible label
+ * already names it. That is the `ariaLabel` when one is given, and the column id when the label is
+ * blank — an icon or actions column — so no header is announced as an empty column.
+ * @param {Partial<TableColumn>|null|undefined} column Column descriptor.
+ * @returns {string|null} Name to set as `aria-label`, or null.
+ */
+export declare function tableHeaderName(column: Partial<TableColumn> | null | undefined): string | null;
+/**
+ * Whether opening an editor of this type selects its content, so the first keystroke replaces the
+ * value instead of being appended to it. True for the single-line text, number, and date editors;
+ * a textarea keeps its caret, and a select, checkbox, or custom editor keeps its own focus
+ * behaviour.
+ * @param {TableEditorType|string} type Resolved editor type.
+ * @returns {boolean}
+ */
+export declare function editorSelectsOnEntry(type: TableEditorType | string): boolean;
 /**
  * Reconciles saved or partial column IDs with every current column.
  * @param {TableColumn[]} columns Current columns.

package/dist/types/components/tag-picker/tag-picker.d.ts

@@ -24,9 +24,17 @@ export type TagPickerOptions = {
      */
     iconKey?: TagValueReader;
     /**
-     * Optional item colour property or reader.
+     * Optional item colour property or reader: a CSS colour
+     * or a token reference such as `var(--zx-color-tone-blue-fg)`.
      */
     colorKey?: TagValueReader;
+    /**
+     * Optional item tone property or reader: a categorical
+     * tone name from the Badge palette (`blue`, `teal`, `green`, `amber`, `orange`, `red`, `pink`,
+     * `violet`, `slate`). A toned tag takes the palette's fill and ink, as a Badge with that `tone`
+     * does; a tone wins over a colour, and unknown names are ignored.
+     */
+    toneKey?: TagValueReader;
     /**
      * Fields searched by local filtering.
      */
@@ -68,7 +76,8 @@ export type TagPickerOptions = {
      */
     disabled?: boolean;
     /**
-     * Whether tags may be added or removed.
+     * When true the picker shows only its tags — no input, chevron, or
+     * remove buttons.
      */
     readonly?: boolean;
     /**
@@ -142,7 +151,12 @@ export type TagPickerOptions = {
  * @property {TagValueReader} [valueKey='ID'] Item ID property or reader.
  * @property {TagLabelReader} [labelKey='name'] Item label property or reader.
  * @property {TagValueReader} [iconKey='icon'] Optional item icon property or reader.
- * @property {TagValueReader} [colorKey='color'] Optional item colour property or reader.
+ * @property {TagValueReader} [colorKey='color'] Optional item colour property or reader: a CSS colour
+ * or a token reference such as `var(--zx-color-tone-blue-fg)`.
+ * @property {TagValueReader} [toneKey='tone'] Optional item tone property or reader: a categorical
+ * tone name from the Badge palette (`blue`, `teal`, `green`, `amber`, `orange`, `red`, `pink`,
+ * `violet`, `slate`). A toned tag takes the palette's fill and ink, as a Badge with that `tone`
+ * does; a tone wins over a colour, and unknown names are ignored.
  * @property {Array<TagValueReader>|null} [searchKeys=null] Fields searched by local filtering.
  * @property {'local'|((query: string) => Promise<TagItem[]>|TagItem[])} [filter='local'] Filtering mode.
  * @property {number} [minQuery=0] Minimum async query length.
@@ -153,7 +167,8 @@ export type TagPickerOptions = {
  * @property {string} [placeholder=''] Empty-state input text.
  * @property {number} [listHeight=260] Maximum list height in pixels.
  * @property {boolean} [disabled=false] Whether interaction is disabled.
- * @property {boolean} [readonly=false] Whether tags may be added or removed.
+ * @property {boolean} [readonly=false] When true the picker shows only its tags — no input, chevron, or
+ * remove buttons.
  * @property {((item: TagItem) => Node|string)|null} [renderItem=null] Option renderer.
  * @property {((item: TagItem) => Node|string)|null} [renderTag=null] Tag-label renderer.
  * @property {Record<string, string>|Record<string, Record<string, string>>} [msg] Localized messages.
@@ -373,6 +388,8 @@ export declare class TagPicker extends Component<TagPickerOptions> {
     _iconOf(item: unknown): Node | null;
     /** @param {unknown} item @returns {string|null} */
     _colorOf(item: unknown): string | null;
+    /** @param {unknown} item @returns {string|null} */
+    _toneOf(item: unknown): string | null;
     /** @param {unknown} item @param {unknown} reader @returns {unknown} */
     _readItem(item: unknown, reader: unknown): unknown;
     /** @returns {void} */

package/dist/types/components/tree/tree.d.ts

@@ -381,3 +381,16 @@ export declare class TreeView extends Component<TreeOptions> {
     /** Restores an enhanced target to the markup it had before the takeover. @returns {void} */
     destroy(): void;
 }
+/**
+ * Whether a key press is one the type-ahead consumes: a single printable character, not a space
+ * (Space selects), with no Ctrl, Meta, or Alt (those are shortcuts). Shift is allowed, since it
+ * only changes the letter's case.
+ * @param {{key?: string, ctrlKey?: boolean, metaKey?: boolean, altKey?: boolean}} event Key event.
+ * @returns {boolean}
+ */
+export declare function isTreeTypeaheadKey(event: {
+    key?: string;
+    ctrlKey?: boolean;
+    metaKey?: boolean;
+    altKey?: boolean;
+}): boolean;