@zeyos/zx 4.3.4 → 5.0.0

package/dist/types/components/menu-button/menu-button.d.ts

@@ -1,31 +1,6 @@
 import { Component } from '../../core/component.js';
-export type MenuItem = {
-    /**
-     * Item label.
-     */
-    label: string;
-    /**
-     * Kernel icon name.
-     */
-    icon?: string;
-    /**
-     * Value emitted on selection.
-     */
-    value?: unknown;
-    /**
-     * Whether selection is disabled.
-     */
-    disabled?: boolean;
-    /**
-     * Whether the action is dangerous.
-     */
-    danger?: boolean;
-    /**
-     * Selection callback.
-     */
-    onselect?: (value: unknown, item: MenuItem, menuButton: MenuButton) => void;
-};
-export type MenuButtonItem = MenuItem | '-';
+export type MenuItem = import('../../internal/menu-items.js').MenuItem;
+export type MenuButtonItem = import('../../internal/menu-items.js').MenuEntry;
 export type MenuButtonOptions = {
     /**
      * Trigger label.
@@ -63,16 +38,16 @@ export type MenuButtonOptions = {
      */
     onclose?: (event: CustomEvent<Record<string, never>>) => void;
 };
-/**
- * @typedef {Object} MenuItem
- * @property {string} label Item label.
- * @property {string} [icon] Kernel icon name.
- * @property {unknown} [value] Value emitted on selection.
- * @property {boolean} [disabled=false] Whether selection is disabled.
- * @property {boolean} [danger=false] Whether the action is dangerous.
- * @property {(value: unknown, item: MenuItem, menuButton: MenuButton) => void} [onselect] Selection callback.
- */
-/** @typedef {MenuItem|'-'} MenuButtonItem */
+export type MenuButtonOpenOptions = {
+    /**
+     * Where focus goes when this opening ends with a
+     * selection or Escape: `true` is the trigger, an element is that element (the trigger again if
+     * it has left the document), and `false` leaves focus alone.
+     */
+    returnFocus?: boolean | HTMLElement;
+};
+/** @typedef {import('../../internal/menu-items.js').MenuItem} MenuItem */
+/** @typedef {import('../../internal/menu-items.js').MenuEntry} MenuButtonItem */
 /**
  * @typedef {Object} MenuButtonOptions
  * @property {string} [label=''] Trigger label.
@@ -84,8 +59,18 @@ export type MenuButtonOptions = {
  * @property {(event: CustomEvent<Record<string, never>>) => void} [onopen] Open event listener.
  * @property {(event: CustomEvent<Record<string, never>>) => void} [onclose] Close event listener.
  */
+/**
+ * @typedef {Object} MenuButtonOpenOptions
+ * @property {boolean|HTMLElement} [returnFocus=true] Where focus goes when this opening ends with a
+ *   selection or Escape: `true` is the trigger, an element is that element (the trigger again if
+ *   it has left the document), and `false` leaves focus alone.
+ */
 /**
  * APG menu-button trigger backed by an anchored Dropdown.
+ *
+ * Choosing an item closes the menu and puts focus back on the trigger before the `select` event
+ * and the item's `onselect` run, so whatever they open — a dialog, a sheet — records the trigger
+ * as the place to return to, and focus they move themselves stays where they put it.
  * @fires MenuButton#select
  * @fires MenuButton#open
  * @fires MenuButton#close
@@ -115,9 +100,11 @@ export declare class MenuButton extends Component<MenuButtonOptions> {
     setItems(items: MenuButtonItem[]): this;
     /**
      * Opens the menu.
+     * @param {MenuButtonOpenOptions} [options={}] Where focus returns when this opening ends; ignored
+     *   while the menu is already open.
      * @returns {this}
      */
-    open(): this;
+    open(options?: MenuButtonOpenOptions): this;
     /**
      * Closes the menu.
      * @returns {this}
@@ -132,10 +119,18 @@ export declare class MenuButton extends Component<MenuButtonOptions> {
     getTrigger(): HTMLElement;
     /** Returns the owned menu panel. @returns {HTMLElement} */
     getPanel(): HTMLElement;
-    /** Opens the menu and focuses its first enabled item. @returns {this} */
-    focusFirst(): this;
-    /** Opens the menu and focuses its last enabled item. @returns {this} */
-    focusLast(): this;
+    /**
+     * Opens the menu and focuses its first enabled item.
+     * @param {MenuButtonOpenOptions} [options={}] Passed to `open()`.
+     * @returns {this}
+     */
+    focusFirst(options?: MenuButtonOpenOptions): this;
+    /**
+     * Opens the menu and focuses its last enabled item.
+     * @param {MenuButtonOpenOptions} [options={}] Passed to `open()`.
+     * @returns {this}
+     */
+    focusLast(options?: MenuButtonOpenOptions): this;
     /**
      * Sets the visible trigger label.
      * @param {string} label Trigger label.

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.
-     */
-    update: (pct: number, text?: string) => void;
-    /**
-     * Completes and dismisses the progress message.
-     */
-    done: () => void;
-    /**
-     * Marks progress as failed and dismisses it later.
+     * Closes the message.
      */
-    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,4 +287,43 @@ 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.
+     * @param {string} fallback English default.
+     * @returns {string}
+     */
+    _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.
@@ -56,6 +56,15 @@ export type ModalOptions = {
 /**
  * Thin native-dialog overlay with lifecycle-safe content and dismissal behavior.
  * The constructor always creates and appends a new dialog; its target argument is ignored.
+ *
+ * Accessibility is the platform's wherever the platform has an answer. The root is a real
+ * `<dialog>` and `_show()` presents it with `showModal()`, so focus containment, the inertness of
+ * everything behind it, Escape, the top layer and the implicit `dialog` role all come from the
+ * browser — there is no hand-written focus trap here, and adding one on top of `:modal` would be
+ * two traps fighting over the same Tab key. What the platform leaves undone is the rest of this
+ * class's accessibility work: it stops initial focus at the panel instead of the first control,
+ * and it restores focus to the opener only for its own native presentation, not for the popover
+ * one a non-modal subclass uses.
  * @fires Modal#open
  * @fires Modal#close
  * @fires Modal#cancel
@@ -129,11 +138,33 @@ export declare class Modal extends Component<ModalOptions> {
      * @returns {boolean} Whether this event closed the current presentation.
      */
     _settleClose(closingPresentation: number | undefined): boolean;
+    /**
+     * Places initial focus inside the panel.
+     *
+     * `showModal()` focuses an `autofocus` control when the content declares one and otherwise stops
+     * at the dialog element, which leaves a reader one Tab short of the first control. This keeps
+     * that preference — so a `Dialog` footer button marked `autofocus` still wins — and then falls
+     * through to the first focusable descendant, with the panel itself as the last resort so focus
+     * is never left outside the overlay.
+     * @returns {void}
+     */
+    _focusInitial(): void;
     /**
      * Creates the owned native dialog.
      * @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}
@@ -165,3 +196,31 @@ export declare class Modal extends Component<ModalOptions> {
      */
     destroy(): void;
 }
+/**
+ * Fired after the modal enters the top layer.
+ * @event Modal#open
+ * @type {CustomEvent<Record<string, never>>}
+ */
+/**
+ * Fired after the native dialog closes.
+ * @event Modal#close
+ * @type {CustomEvent<{result: unknown}>}
+ */
+/**
+ * Fired when Escape requests cancellation. Preventing it keeps the modal open.
+ * @event Modal#cancel
+ * @type {CustomEvent<Record<string, never>>}
+ */
+/**
+ * Picks the control initial focus belongs on inside an overlay panel: an `autofocus` control when
+ * the content named one, the first focusable descendant otherwise, and null when the panel holds
+ * neither and must take focus itself.
+ *
+ * Candidates in a hidden, `aria-hidden` or `inert` subtree are skipped, because `focus()` on one
+ * is a silent no-op: a `Dialog` whose header close button is hidden by `closable: false`, or whose
+ * other registered views sit hidden in the same body, would otherwise "focus" nothing at all and
+ * leave the reader with no way into the overlay.
+ * @param {Element} root Overlay panel.
+ * @returns {HTMLElement|null}
+ */
+export declare function initialFocusTarget(root: Element): HTMLElement | null;

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

@@ -80,33 +80,30 @@ export type NavigationBarOptions = {
      */
     actions?: NavigationAction[];
     /**
-     * Change callback.
-     */
-    onchange?: (event: CustomEvent<{
-        name: string;
-    }>) => void;
-};
-export type NavigationRecord = {
-    /**
-     * Normalized item definition.
+     * Whether items collapse into the overflow menu at all.
+     * `false` keeps every item in the bar at every width and never shows the More button.
      */
-    definition: NavigationItem;
+    overflow?: boolean;
     /**
-     * Rendered link or button.
+     * Container inline size at or below which
+     * items collapse, as a `px` or `rem` length (a number is read as `px`); `false` disables
+     * collapsing exactly as `overflow: false` does. The default is the threshold the stylesheet's
+     * own container query carries, and a bar that keeps it collapses in CSS without measuring
+     * itself; any other value is watched with a `ResizeObserver`.
      */
-    item: HTMLElement;
+    overflowBelow?: string | number | false;
     /**
-     * Badge element.
+     * How many items, counted from the start, never collapse. The
+     * default collapses all of them, which is right for a top app bar and wrong for a phone bottom
+     * bar — `minVisible: 4` is what makes that bar usable.
      */
-    badge: HTMLElement;
+    minVisible?: number;
     /**
-     * Optional tab panel.
-     */
-    panel: HTMLElement | null;
-    /**
-     * Whether panel content has been mounted.
+     * Change callback.
      */
-    built: boolean;
+    onchange?: (event: CustomEvent<{
+        name: string;
+    }>) => void;
 };
 /** @typedef {Node|Component|(() => Node|Component)} NavigationPanelContent */
 /**
@@ -136,8 +133,46 @@ export type NavigationRecord = {
  * @property {NavigationItem[]} [items=[]] Navigation items.
  * @property {string|null} [active=null] Initially active item, or the first enabled item.
  * @property {NavigationAction[]} [actions=[]] Right-aligned action elements or descriptors.
+ * @property {boolean} [overflow=true] Whether items collapse into the overflow menu at all.
+ *   `false` keeps every item in the bar at every width and never shows the More button.
+ * @property {string|number|false} [overflowBelow='44rem'] Container inline size at or below which
+ *   items collapse, as a `px` or `rem` length (a number is read as `px`); `false` disables
+ *   collapsing exactly as `overflow: false` does. The default is the threshold the stylesheet's
+ *   own container query carries, and a bar that keeps it collapses in CSS without measuring
+ *   itself; any other value is watched with a `ResizeObserver`.
+ * @property {number} [minVisible=0] How many items, counted from the start, never collapse. The
+ *   default collapses all of them, which is right for a top app bar and wrong for a phone bottom
+ *   bar — `minVisible: 4` is what makes that bar usable.
  * @property {(event: CustomEvent<{name: string}>) => void} [onchange] Change callback.
  */
+/**
+ * The container width `navigation-bar.css` collapses at. A bar that keeps this exact threshold is
+ * served by the stylesheet's container query, so it needs no measurement and no script at all;
+ * anything else has to be watched. Keep it in step with the `@container` rule.
+ */
+export declare const OVERFLOW_BELOW = "44rem";
+export type NavigationRecord = {
+    /**
+     * Normalized item definition.
+     */
+    definition: NavigationItem;
+    /**
+     * Rendered link or button.
+     */
+    item: HTMLElement;
+    /**
+     * Badge element.
+     */
+    badge: HTMLElement;
+    /**
+     * Optional tab panel.
+     */
+    panel: HTMLElement | null;
+    /**
+     * Whether panel content has been mounted.
+     */
+    built: boolean;
+};
 /**
  * @typedef {Object} NavigationRecord
  * @property {NavigationItem} definition Normalized item definition.
@@ -163,6 +198,8 @@ export declare class NavigationBar extends Component<NavigationBarOptions> {
     _items: NavigationRecord[];
     _activeName: string;
     _tabMode: boolean;
+    _observer: ResizeObserver;
+    _frame: number;
     static cssName: string;
     /** @type {Readonly<NavigationBarOptions>} */
     static defaults: Readonly<NavigationBarOptions>;
@@ -216,8 +253,21 @@ export declare class NavigationBar extends Component<NavigationBarOptions> {
     _ensurePanel(record: NavigationRecord): void;
     /** @param {KeyboardEvent} event @returns {void} */
     _onTabKeydown(event: KeyboardEvent): void;
-    /** @returns {void} */
+    /**
+     * Republishes the overflow state: which items may collapse, which mode the stylesheet should
+     * apply, and what the More menu contains. With the default `minVisible: 0` every item collapses
+     * and the menu lists them all, which is what it has always done.
+     * @returns {void}
+     */
     _syncOverflow(): void;
+    /**
+     * Watches the bar's own inline size when `overflowBelow` names a threshold the stylesheet cannot
+     * express. A bar on the default threshold installs nothing: its container query has already
+     * decided before the first frame of script, which is why the default path stays exactly as it
+     * was.
+     * @returns {void}
+     */
+    _observeWidth(): void;
     /** @param {NavigationRecord} record @returns {void} */
     _focusTab(record: NavigationRecord): void;
     /** @returns {NavigationRecord[]} */
@@ -227,3 +277,37 @@ export declare class NavigationBar extends Component<NavigationBarOptions> {
     /** @param {string} name @returns {NavigationRecord} */
     _require(name: string): NavigationRecord;
 }
+/**
+ * Fired after the active item changes.
+ * @event NavigationBar#change
+ * @type {CustomEvent<{name: string}>}
+ */
+/**
+ * Resolves the container inline size at or below which items collapse into the overflow menu.
+ *
+ * Two options can switch collapsing off, because they answer two different questions: `overflow`
+ * is whether the bar has an overflow menu at all, and `overflowBelow` is where it starts using it.
+ * Either being `false` means the same thing to the stylesheet — nothing ever collapses — so both
+ * resolve to `null` here and the caller has one state to handle rather than two.
+ * @param {NavigationBarOptions} [options={}] Navigation options, whole or partial.
+ * @returns {string|null} A `px` or `rem` length, or `null` when nothing ever collapses.
+ */
+export declare function resolveOverflowBelow(options?: NavigationBarOptions): string | null;
+/**
+ * How many items, counted from the start, stay in the bar when it collapses.
+ *
+ * Clamping to the item count is the whole arithmetic: `minVisible: 4` on a three-item bar keeps
+ * three, so the overflow menu is empty rather than holding a phantom fourth entry, and the bar
+ * hides its More button instead of opening onto nothing.
+ * @param {NavigationBarOptions} [options={}] Navigation options, whole or partial.
+ * @param {number} [count=0] How many items the bar currently has.
+ * @returns {number} A count between 0 and `count`.
+ */
+export declare function resolveMinVisible(options?: NavigationBarOptions, count?: number): number;
+/**
+ * Converts an overflow threshold to pixels, so a measured width can be compared with it.
+ * @param {string|number} length A `px` or `rem` length, or a number of pixels.
+ * @param {number} [rootFontSize=16] Computed root font size; anything unusable falls back to 16.
+ * @returns {number} The threshold in pixels.
+ */
+export declare function lengthToPixels(length: string | number, rootFontSize?: number): number;

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

@@ -191,4 +191,11 @@ export declare class Panel extends Component<PanelOptions> {
      * @returns {Element[]}
      */
     _buildButtons(list: PanelButton[], label: string): Element[];
+    /**
+     * Resolves a message through the host translator, falling back to the built-in English text.
+     * @param {string} key Message key.
+     * @param {string} fallback English default.
+     * @returns {string}
+     */
+    _message(key: string, fallback: string): string;
 }

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

@@ -95,4 +95,11 @@ export declare class Search extends Component<SearchOptions> {
     _scheduleInput(): void;
     /** @returns {void} */
     _syncClear(): void;
+    /**
+     * Resolves a message through the host translator, falling back to the built-in English text.
+     * @param {string} key Message key.
+     * @param {string} fallback English default.
+     * @returns {string}
+     */
+    _message(key: string, fallback: string): string;
 }

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;