@zeyos/zx 5.0.0 → 5.2.0

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

@@ -184,8 +184,14 @@ 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. */
+    /** @type {Element|null} The theme scope this instance is the floating region of; null when inline. */
     _floatingHost: Element | null;
+    /** @type {Element|null} Where the floating region was last put: its scope, or the topmost modal. */
+    _placedIn: Element | null;
+    /** @type {import('../../core/overlay-stack.js').OverlayHandle|null} The region's toast entry. */
+    _overlay: import('../../core/overlay-stack.js').OverlayHandle | null;
+    /** @type {(() => void)|null} Stops following the overlay stack. */
+    _unfollow: (() => void) | null;
     _queue: MessageQueue<any>;
     _cleaned: boolean;
     static cssName: string;
@@ -293,6 +299,13 @@ export declare class Message extends Component<MessageOptions> {
      * @returns {void}
      */
     _releaseIfEmpty(): void;
+    /**
+     * Puts a floating region where it can be seen and used: inside the topmost open modal dialog
+     * while one is open — outside it, `showModal()` would leave every toast unclickable — and in its
+     * own theme scope otherwise. Re-showing it after a move puts it back on top of the top layer.
+     * @returns {void}
+     */
+    _rehome(): void;
     /**
      * Destroys a floating region and removes its element.
      * @returns {void}

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

@@ -110,6 +110,36 @@ export declare class Modal extends Component<ModalOptions> {
      * @returns {void}
      */
     _present(): void;
+    /**
+     * Describes the current presentation for the overlay stack, or returns null to stay off it.
+     *
+     * The kind is read from the platform like `aria-modal` is: a `showModal()` dialog is `modal`,
+     * and its Escape and backdrop stay the browser's; anything else is `non-modal`, and a subclass
+     * presenting that way adds the Escape and outside-press handling it wants.
+     * @returns {import('../../core/overlay-stack.js').OverlayEntryOptions|null}
+     * @protected
+     */
+    protected _overlayEntry(): import('../../core/overlay-stack.js').OverlayEntryOptions | null;
+    /**
+     * Re-registers the current presentation on the overlay stack: called after every presentation,
+     * including a subclass's change of address that bypasses `open()`.
+     * @returns {void}
+     * @protected
+     */
+    protected _syncOverlay(): void;
+    /**
+     * Takes the overlay off the stack. Safe to call repeatedly.
+     * @returns {void}
+     * @protected
+     */
+    protected _releaseOverlay(): void;
+    /**
+     * Whether a node is inside this overlay or anything opened from it, as the overlay stack sees it.
+     * @param {Node|null|undefined} node Candidate.
+     * @returns {boolean}
+     * @protected
+     */
+    protected _overlayContains(node: Node | null | undefined): boolean;
     /**
      * Hides the current presentation and records which generation its queued close event belongs to.
      * @param {string} [result=''] Native string return value.

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/select.d.ts

@@ -227,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;
     /**

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}