@zeyos/zx 4.4.0 → 5.2.0

package/dist/types/components/module-bar/module-bar.d.ts

@@ -0,0 +1,395 @@
+import { AppRailPresenter } from '../../internal/app-rail.js';
+import { Dropdown } from '../dropdown/dropdown.js';
+import { Tooltip } from '../tooltip/tooltip.js';
+export type AppNavItem = import('../../internal/app-rail.js').AppNavItem;
+export type AppNavSelectDetail = import('../../internal/app-rail.js').AppNavSelectDetail;
+export type ModuleTone = import('../app-icon/app-icon.js').AppIconTone;
+export type ModuleItem = {
+    /**
+     * Stable module identifier.
+     */
+    id: string | number;
+    /**
+     * Module name: the tile's accessible name, tooltip, and catalogue label.
+     */
+    label: string;
+    /**
+     * Icon name, node, component, or factory.
+     */
+    icon?: string | Node | {
+        toElement: () => Node | null;
+    } | ((context: Record<string, any>, item: AppNavItem) => Node | null);
+    /**
+     * Identity colour from the theme's categorical tones.
+     */
+    tone?: ModuleTone;
+    /**
+     * Identity colour as any CSS colour; takes precedence over `tone`.
+     */
+    color?: string;
+    /**
+     * Count or status badge.
+     */
+    badge?: string | number;
+    /**
+     * Shown on the bar, in this order when a number. When no
+     * module sets it, every module is on the bar; otherwise unpinned modules are in "All modules" only.
+     */
+    pinned?: boolean | number;
+    /**
+     * Group heading in the "All modules" catalogue.
+     */
+    group?: string;
+    /**
+     * Secondary text, shown as the catalogue entry's title.
+     */
+    description?: string;
+    /**
+     * Emitted value; defaults to `id`.
+     */
+    value?: unknown;
+    /**
+     * Native navigation target for a module without a menu.
+     */
+    href?: string;
+    /**
+     * Native link browsing context.
+     */
+    target?: string;
+    /**
+     * Application-owned non-link action.
+     */
+    invoke?: () => void;
+    /**
+     * Whether activation is unavailable.
+     */
+    disabled?: boolean;
+    /**
+     * The module's menu. With `menus: 'flyout'` it opens beside
+     * the tile; it never renders inline.
+     */
+    children?: AppNavItem[];
+};
+export type ModuleBarOptions = {
+    /**
+     * Modules, in bar order.
+     */
+    items?: ModuleItem[];
+    /**
+     * Active destination id: a module, or any item in a module's menu.
+     */
+    active?: string | number | null;
+    /**
+     * Bar flow.
+     */
+    orientation?: 'vertical' | 'horizontal';
+    /**
+     * Workspace edge the bar occupies.
+     */
+    side?: 'left' | 'right' | 'top' | 'bottom';
+    /**
+     * Tile treatment: the glyph in the module
+     * colour on a tint of it, the solid identity tile, or monochrome glyphs.
+     */
+    appearance?: 'tint' | 'solid' | 'plain';
+    /**
+     * Whether a vertical bar prints each
+     * module's name: under its tile (a narrow strip), beside it (a full navigation column, with the
+     * count at the end of the row), or not at all — the name then stays the accessible name and the
+     * tooltip. Horizontal bars never print names.
+     */
+    labels?: 'hidden' | 'below' | 'beside';
+    /**
+     * How a module's children are presented: in a flyout,
+     * or by an adjacent panel the application owns, in which case activating the module emits `select`.
+     */
+    menus?: 'flyout' | 'none';
+    /**
+     * With `menus: 'none'`, the module whose menu the
+     * adjacent panel shows.
+     */
+    expanded?: string | number | null;
+    /**
+     * With `menus: 'none'`, the id of that panel.
+     */
+    controls?: string | null;
+    /**
+     * The "All modules" button: shown when a
+     * module does not fit or is unpinned, always, or never (the bar then scrolls).
+     */
+    allModules?: 'auto' | 'always' | 'never';
+    /**
+     * Leading content, such as a product mark.
+     */
+    header?: Node | string | number | {
+        toElement: () => Node | null;
+    } | null;
+    /**
+     * Trailing content, such as an account menu.
+     */
+    footer?: Node | string | number | {
+        toElement: () => Node | null;
+    } | null;
+    /**
+     * Navigation accessible label. Omitted resolves `moduleBar.label`, English `Modules`.
+     */
+    label?: string | null;
+    /**
+     * Flyout hover-open delay in milliseconds.
+     */
+    openDelay?: number;
+    /**
+     * Flyout pointer and focus crossing grace in milliseconds.
+     */
+    closeDelay?: number;
+    /**
+     * Optional host icon renderer.
+     */
+    renderIcon?: (item: AppNavItem, context: Record<string, any>) => Node | null;
+    /**
+     * Preventable activation listener.
+     */
+    onselect?: (event: CustomEvent<AppNavSelectDetail>) => void;
+    /**
+     * Flyout-state listener.
+     */
+    onflyoutchange?: (event: CustomEvent<{
+        item: AppNavItem;
+        id: string | number;
+        open: boolean;
+    }>) => void;
+    /**
+     * Overflow listener.
+     */
+    onoverflowchange?: (event: CustomEvent<{
+        visible: Array<string | number>;
+        overflow: Array<string | number>;
+    }>) => void;
+    /**
+     * "All modules" catalogue open-state listener.
+     */
+    onallmodules?: (event: CustomEvent<{
+        open: boolean;
+    }>) => void;
+};
+/**
+ * The module level of an application: one colour-coded tile per module in a vertical strip or a
+ * horizontal bar. A module with a menu opens it in a flyout, or leaves it to an adjacent panel
+ * (`menus: 'none'`, which is how `AppSidebar` composes the bar). Modules that do not fit, or are
+ * not pinned, are one step away in the "All modules" catalogue. The bar is one Tab stop: arrow
+ * keys, Home, End, and type-ahead move between tiles.
+ * @fires ModuleBar#select
+ * @fires ModuleBar#flyoutchange
+ * @fires ModuleBar#overflowchange
+ * @fires ModuleBar#allmodules
+ * @extends {AppRailPresenter}
+ */
+export declare class ModuleBar extends AppRailPresenter {
+    _sections: Map<any, any>;
+    _appearance: any;
+    _menus: string;
+    _expandedId: any;
+    _labels: any;
+    _promoted: string | number;
+    _catalogue: Dropdown;
+    _silenceCatalogue: boolean;
+    _catalogueTooltip: Tooltip;
+    _observer: ResizeObserver;
+    _partition: {
+        visible: any[];
+        overflow: any[];
+    } | {
+        visible: (string | number)[];
+        overflow: (string | number)[];
+    };
+    _rovingId: string;
+    _typeahead: any;
+    static cssName: string;
+    static partBlock: string;
+    /** @type {Readonly<ModuleBarOptions>} */
+    static defaults: Readonly<ModuleBarOptions>;
+    /**
+     * Creates or enhances a module bar.
+     * @param {Element|string|null} [target=null] Bar target; a `<nav>` is created when null.
+     * @param {ModuleBarOptions} [options={}] Bar options.
+     */
+    constructor(target?: Element | string | null, options?: ModuleBarOptions);
+    /** @returns {HTMLElement} */
+    render(): HTMLElement;
+    /** Replaces the modules and rebuilds the bar. @param {ModuleItem[]} items @returns {this} */
+    setItems(items: ModuleItem[]): this;
+    /** Returns a copy of the normalized modules. @returns {ModuleItem[]} */
+    getItems(): ModuleItem[];
+    /**
+     * Marks the active destination — a module, or anything in a module's menu — without routing.
+     * The module holding it becomes current and stays on the bar.
+     * @param {string|number|null} id Destination id.
+     * @returns {this}
+     */
+    setActive(id: string | number | null): this;
+    /** Opens a module's menu flyout. @param {string|number} id Module id. @param {{focus?: boolean}} [options={}] Focus its first item. @returns {this} */
+    openFlyout(id: string | number, options?: {
+        focus?: boolean;
+    }): this;
+    /** Closes a module's menu flyout. @param {string|number} id Module id. @returns {this} */
+    closeFlyout(id: string | number): this;
+    /** Closes every menu flyout. @returns {this} */
+    closeAllFlyouts(): this;
+    /** Reports whether a module's menu flyout is open. @param {string|number} id Module id. @returns {boolean} */
+    isFlyoutOpen(id: string | number): boolean;
+    /**
+     * With `menus: 'none'`, names the module whose menu the adjacent panel now shows.
+     * @param {string|number|null} id Module id, or null when the panel shows none.
+     * @returns {this}
+     */
+    setExpanded(id: string | number | null): this;
+    /**
+     * Updates one badge in place — on the tile, in a flyout, and in the catalogue — without
+     * rebuilding the bar. `null` removes it.
+     * @param {string|number} id Module or menu item id.
+     * @param {string|number|null} badge New badge.
+     * @returns {this}
+     */
+    setBadge(id: string | number, badge: string | number | null): this;
+    /**
+     * Changes flow or edge, keeping items, the active destination, and the expanded module.
+     * @param {{orientation?: 'vertical'|'horizontal', side?: 'left'|'right'|'top'|'bottom'}} layout
+     * @returns {this}
+     */
+    setLayout(layout?: {
+        orientation?: 'vertical' | 'horizontal';
+        side?: 'left' | 'right' | 'top' | 'bottom';
+    }): this;
+    /**
+     * Changes whether module names are printed — the expanded and collapsed states of a vertical
+     * navigation column — keeping items, the active destination, and the expanded module.
+     * @param {'hidden'|'below'|'beside'} labels
+     * @returns {this}
+     */
+    setLabels(labels: 'hidden' | 'below' | 'beside'): this;
+    /** Opens the "All modules" catalogue and focuses its filter or first entry. @returns {this} */
+    openAllModules(): this;
+    /** Closes the "All modules" catalogue. @returns {this} */
+    closeAllModules(): this;
+    /** Reports whether the "All modules" catalogue is open. @returns {boolean} */
+    isAllModulesOpen(): boolean;
+    /** Focuses the bar's Tab stop: the current module, else the first tile. @returns {this} */
+    focus(): this;
+    /** Destroys flyouts, tooltips, and the catalogue, and restores or removes the root. @returns {void} */
+    destroy(): void;
+    /** @param {Node|null} node @returns {boolean} @private */
+    private _containsNode;
+    /** @returns {void} */
+    _clearArtifacts(): void;
+    /** @param {AppNavItem} item @returns {boolean} */
+    _flyoutsFor(item: AppNavItem): boolean;
+    /** @returns {boolean} */
+    _tooltipFor(): boolean;
+    /** @param {AppNavItem} item @returns {HTMLElement} */
+    _renderControl(item: AppNavItem): HTMLElement;
+    /** @returns {void} */
+    _afterRebuild(): void;
+    /** @returns {void} */
+    _syncActive(): void;
+    /**
+     * Shows the tiles that fit, in bar order, and moves the rest behind "All modules". Everything is
+     * shown first so a bar sized by its content measures as not overflowing and never shrinks itself.
+     * @returns {void}
+     */
+    _layout(): void;
+    /** @param {AppNavItem} item @param {'bar'|'catalogue'} location @returns {HTMLElement} */
+    _renderTile(item: AppNavItem, location: 'bar' | 'catalogue'): HTMLElement;
+    /** @param {HTMLElement} control @param {AppNavItem} item @returns {void} */
+    _applyTileBadge(control: HTMLElement, item: AppNavItem): void;
+    /** Builds the "All modules" button and its catalogue for this render. @returns {void} */
+    _buildCatalogue(): void;
+    /**
+     * Leave exactly one visible catalogue entry in the Tab order: `preferred`, else the current stop,
+     * else the current module, else the first entry the filter shows.
+     * @param {HTMLElement} [preferred]
+     * @returns {void}
+     */
+    _syncCatalogueStop(preferred?: HTMLElement): void;
+    /** @param {AppNavItem} item @returns {HTMLElement} */
+    _catalogueControl(item: AppNavItem): HTMLElement;
+    /** @param {MouseEvent|Event} event @returns {void} */
+    _onCatalogueClick(event: MouseEvent | Event): void;
+    /** @param {KeyboardEvent} event @returns {void} */
+    _onCatalogueKeydown(event: KeyboardEvent): void;
+    /** @param {string} query @returns {void} */
+    _filterCatalogue(query: string): void;
+    /** @returns {void} */
+    _focusCatalogue(): void;
+    /** @param {KeyboardEvent} event @returns {void} */
+    _onRailKeydown(event: KeyboardEvent): void;
+    /** @param {string} key @param {HTMLElement[]} controls @param {number} index @returns {HTMLElement|null} */
+    _typeaheadTarget(key: string, controls: HTMLElement[], index: number): HTMLElement | null;
+    /** @returns {HTMLElement[]} Every module tile, shown or not. */
+    _tiles(): HTMLElement[];
+    /** @returns {HTMLElement[]} The tiles and button the arrow keys move between, in bar order. */
+    _rovingControls(): HTMLElement[];
+    /** @returns {HTMLElement|null} */
+    _rovingStop(): HTMLElement | null;
+    /** @param {HTMLElement} control @returns {void} */
+    _setRovingStop(control: HTMLElement): void;
+    /** @returns {void} */
+    _syncRoving(): void;
+    /** @returns {void} */
+    _syncExpanded(): void;
+    /** @returns {HTMLElement[]} */
+    _catalogueEntries(): HTMLElement[];
+    /** @param {string} id @returns {HTMLElement|null} */
+    _catalogueEntry(id: string): HTMLElement | null;
+    /** @returns {string} */
+    _labelText(): string;
+}
+/**
+ * Splits modules into those the bar shows and those only "All modules" offers.
+ *
+ * Bar order is pinned modules first — by their pinned number, then as listed — and the rest as
+ * listed. When any module is pinned, unpinned modules go to the catalogue. When the bar cannot
+ * hold every candidate, one slot goes to the "All modules" button. Modules named in `keep` (the
+ * current module, the module an adjacent panel shows) stay on the bar whatever their pin or
+ * position, displacing the last module that is not kept.
+ * @param {ModuleItem[]} items Modules.
+ * @param {number} [capacity=Infinity] Slots the bar has room for, the button included.
+ * @param {Array<string|number|null|undefined>|string|number|null} [keep=[]] Module ids that must stay visible.
+ * @param {boolean} [reserve=false] Keep a slot for the button even when every module fits.
+ * @returns {{visible: ModuleItem[], overflow: ModuleItem[], more: boolean}}
+ */
+export declare function partitionModules(items: ModuleItem[], capacity?: number, keep?: Array<string | number | null | undefined> | string | number | null, reserve?: boolean): {
+    visible: ModuleItem[];
+    overflow: ModuleItem[];
+    more: boolean;
+};
+/**
+ * Resolves a module's identity colour: a valid CSS `color` wins, then a known `tone`.
+ * @param {{tone?: unknown, color?: unknown}} item Module.
+ * @returns {{tone: ModuleTone|null, color: string|null}}
+ */
+export declare function resolveModuleColor(item: {
+    tone?: unknown;
+    color?: unknown;
+}): {
+    tone: ModuleTone | null;
+    color: string | null;
+};
+/**
+ * Modules are one level: a section contributes its modules, and remembers itself as their heading.
+ * @param {AppNavItem[]} items Normalized items.
+ * @param {Map<string, string>} [sections] Filled with each sectioned module's heading.
+ * @param {string|null} [heading=null] The section being lifted.
+ * @returns {AppNavItem[]}
+ */
+export declare function liftSections(items: AppNavItem[], sections?: Map<string, string>, heading?: string | null): AppNavItem[];
+/**
+ * The top-level module that is, or contains, an id.
+ * @param {AppNavItem[]} items Modules.
+ * @param {string|number|null|undefined} id Destination id.
+ * @returns {AppNavItem|null}
+ */
+export declare function moduleOf(items: AppNavItem[], id: string | number | null | undefined): AppNavItem | null;
+/** Fired when a module without a menu, a menu item, or (with `menus: 'none'`) any module is activated. @event ModuleBar#select @type {CustomEvent<AppNavSelectDetail>} */
+/** Fired when a module's flyout opens or closes. @event ModuleBar#flyoutchange @type {CustomEvent<{item: AppNavItem, id: string|number, open: boolean}>} */
+/** Fired when the modules on the bar change because of space, pins, or the current module. @event ModuleBar#overflowchange @type {CustomEvent<{visible: Array<string|number>, overflow: Array<string|number>}>} */
+/** Fired when the "All modules" catalogue opens or closes. @event ModuleBar#allmodules @type {CustomEvent<{open: boolean}>} */

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

@@ -138,9 +138,23 @@ export type PaginationChangeDetail = PaginationState;
 /** @typedef {PaginationState} PaginationChangeDetail */
 /**
  * The pager for a server-backed list. It owns no data: it reports which slice the user asked for
- * and lets the application fetch it, which is exactly the shape `zeyosTable()` expects —
- * `offset`/`pageSize` for `load()` in `pages` mode, or one `change` per `loadMore()` in
- * `loadmore` mode.
+ * — `page`, `pageSize`, and the zero-based row `offset = (page - 1) * pageSize` — and lets the
+ * application fetch it.
+ *
+ * The pager is one-based and defaults to 25 rows per page. The ZeyOS bindings are zero-based,
+ * default to 50 rows, and append pages above zero unless told to replace, so connecting the two
+ * takes a small mapping rather than a direct hand-off:
+ *
+ * ```js
+ * const binding = zeyosTable(client, 'contacts', { pageSize: 25 });
+ * const pager = new Pagination(host, { pageSize: binding.pageSize });
+ * pager.on('change', async ({ detail }) => {
+ *   const result = await binding.load({ page: detail.page - 1, pageSize: detail.pageSize, replace: true });
+ *   pager.setTotal(result.count ?? 0);
+ * });
+ * ```
+ *
+ * In `loadmore` mode each `change` stands for one `binding.loadMore()`, which appends.
  *
  * `page` is clamped into `[1, pages]` after every state change, so shrinking `total` under the
  * user's feet can never leave the pager pointing past the end of the data.

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} */
@@ -224,6 +227,12 @@ export declare class Select extends Component<SelectOptions> {
     get value(): unknown;
     /** @param {unknown} id Selected item ID. */
     set value(id: unknown);
+    /**
+     * Returns the selected item ID, or null: the same as reading `value`, under the `get()`/`set()`
+     * pair the other value components share.
+     * @returns {unknown}
+     */
+    get(): unknown;
     /** Selected item, or null. @returns {SelectItem|null} */
     get selected(): SelectItem | null;
     /**
@@ -267,9 +276,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/sheet/sheet.d.ts

@@ -172,6 +172,8 @@ export type SheetOptions = {
 export declare class Sheet extends Dialog {
     #private;
     _dock: any;
+    /** @type {Element|null} The element focus was on when the current `open()` began. */
+    _openedFrom: Element | null;
     static cssName: string;
     /** @type {Readonly<SheetOptions>} */
     static defaults: Readonly<SheetOptions>;
@@ -229,6 +231,19 @@ export declare class Sheet extends Dialog {
      * @returns {void}
      */
     _rehost(): void;
+    /**
+     * Describes the presentation for the overlay stack. A docked sheet is part of the layout and
+     * stays off it.
+     *
+     * Escape and outside-click are free for a modal dialog and absent for a non-modal one — the
+     * browser only wires `cancel` for `showModal()`, and there is no `::backdrop` to click — so a
+     * floating non-modal sheet takes both from the stack. That is what makes it aware of what it
+     * opened: Escape reaches it only once no popup above it takes the key, and a press inside a menu
+     * anchored in the sheet counts as inside the sheet, wherever the menu's panel lives.
+     * @returns {import('../../core/overlay-stack.js').OverlayEntryOptions|null}
+     * @protected
+     */
+    protected _overlayEntry(): import('../../core/overlay-stack.js').OverlayEntryOptions | null;
     /**
      * Opens the sheet, trapping focus first where the modality asks for it.
      * @returns {this}