@zeyos/zx 4.3.0 → 4.4.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,8 @@ 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 */
+/** @typedef {import('../../internal/menu-items.js').MenuItem} MenuItem */
+/** @typedef {import('../../internal/menu-items.js').MenuEntry} MenuButtonItem */
 /**
  * @typedef {Object} MenuButtonOptions
  * @property {string} [label=''] Trigger label.

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

@@ -217,4 +217,11 @@ export declare class Message extends Component<MessageOptions> {
     _close(entry: any): void;
     /** @param {any} entry @returns {void} */
     _finish(entry: any): 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/modal/modal.d.ts

@@ -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,6 +138,17 @@ 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}
@@ -165,3 +185,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/select.d.ts

@@ -68,6 +68,10 @@ export type SelectOptions = {
      * Empty control text.
      */
     placeholder?: string;
+    /**
+     * Accessible combobox name; falls back to the placeholder.
+     */
+    label?: string;
     /**
      * Whether selection may be cleared.
      */

package/dist/types/components/sort-control/sort-control.d.ts

@@ -0,0 +1,105 @@
+import { Component } from '../../core/component.js';
+import { Select } from '../select/select.js';
+export type SortField = {
+    id: string;
+    label: string;
+};
+export type SortValue = {
+    id: string;
+    dir: 'asc' | 'desc';
+};
+export type SortControlOptions = {
+    /**
+     * Available sort fields, in display order.
+     */
+    fields?: SortField[];
+    /**
+     * Initial sort; null chooses the first field ascending.
+     */
+    value?: SortValue | null;
+    /**
+     * Accessible field label and direction-name prefix.
+     */
+    label?: string;
+    /**
+     * Current/next direction labels, defaulting to Ascending/Descending.
+     */
+    labels?: {
+        asc?: string;
+        desc?: string;
+    };
+    /**
+     * Whether interaction is disabled.
+     */
+    disabled?: boolean;
+    /**
+     * Atomic field/direction change.
+     */
+    onchange?: (event: CustomEvent<{
+        value: SortValue;
+    }>) => void;
+};
+/** @typedef {{id:string,label:string}} SortField */
+/** @typedef {{id:string,dir:'asc'|'desc'}} SortValue */
+/**
+ * @typedef {Object} SortControlOptions
+ * @property {SortField[]} [fields=[]] Available sort fields, in display order.
+ * @property {SortValue|null} [value=null] Initial sort; null chooses the first field ascending.
+ * @property {string} [label='Sort by'] Accessible field label and direction-name prefix.
+ * @property {{asc?:string,desc?:string}} [labels={}] Current/next direction labels, defaulting to Ascending/Descending.
+ * @property {boolean} [disabled=false] Whether interaction is disabled.
+ * @property {(event:CustomEvent<{value:SortValue}>)=>void} [onchange] Atomic field/direction change.
+ */
+/**
+ * A searchable field selector with an adjacent direction toggle and one shared sort value.
+ * @fires SortControl#change
+ * @extends {Component<SortControlOptions>}
+ */
+export declare class SortControl extends Component<SortControlOptions> {
+    _createdRoot: boolean;
+    _snapshot: import("../../core/dom.js").TargetSnapshot;
+    _value: SortValue;
+    _disabled: boolean;
+    _direction: HTMLButtonElement;
+    _select: Select;
+    static cssName: string;
+    /** @type {SortControlOptions} */
+    static defaults: SortControlOptions;
+    /** @returns {HTMLElement} */
+    render(): HTMLElement;
+    /** Returns a defensive copy of the current sort. @returns {SortValue|null} */
+    getValue(): SortValue | null;
+    /**
+     * Replaces the field and direction atomically; rejects unavailable fields and directions.
+     * @param {SortValue|null} value Sort state, or null for the first field ascending.
+     * @param {{silent?:boolean}} [options={}] Suppress change when silent.
+     * @returns {this}
+     */
+    setValue(value: SortValue | null, { silent }?: {
+        silent?: boolean;
+    }): this;
+    /** Enables both controls when fields are available. @returns {this} */
+    enable(): this;
+    /** Disables both controls and closes the option panel. @returns {this} */
+    disable(): this;
+    /** Updates the icon and accessible current/next direction text. @private @returns {void} */
+    private _syncDirection;
+    /** Focuses the searchable control. @returns {this} */
+    focus(): this;
+    /** Releases the owned Select and restores an enhanced target. @returns {void} */
+    destroy(): void;
+}
+/**
+ * Validates a sort against available fields without retaining caller-owned state.
+ * @param {SortValue|null} value Requested sort.
+ * @param {SortField[]} fields Available fields.
+ * @returns {SortValue|null} Normalized sort, or null for an empty catalogue.
+ */
+export declare function normalizeSortValue(value: SortValue | null, fields: SortField[]): SortValue | null;
+/**
+ * Builds one searchable record per field without retaining caller-owned objects.
+ * @param {SortField[]} fields Available fields.
+ * @returns {SortField[]} Choice records.
+ */
+export declare function sortChoices(fields: SortField[]): SortField[];
+/** @event SortControl#change @type {CustomEvent<{value:SortValue}>} */