@zeyos/zx 2.1.0 → 2.2.1

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

@@ -0,0 +1,212 @@
+import { Component } from '../../core/component.js';
+export type MessageKind = 'info' | 'success' | 'warning' | 'error';
+export type MessageShowOptions = {
+    /**
+     * Message intent (`danger` aliases `error`).
+     */
+    kind?: MessageKind | 'danger';
+    /**
+     * Auto-dismiss delay in milliseconds; zero persists.
+     */
+    timeout?: number;
+    /**
+     * Whether to render a close button.
+     */
+    closable?: boolean;
+};
+export type MessageOptions = {
+    /**
+     * Default message intent.
+     */
+    kind?: MessageKind | 'danger';
+    /**
+     * Default auto-dismiss delay.
+     */
+    timeout?: number;
+    /**
+     * Default close-button visibility.
+     */
+    closable?: boolean;
+    /**
+     * Maximum number of visible messages.
+     */
+    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.
+     */
+    fail: (text?: string) => void;
+};
+/** @typedef {'info'|'success'|'warning'|'error'} MessageKind */
+/**
+ * @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 {boolean} [closable=true] Whether to render a close button.
+ */
+/**
+ * @typedef {Object} MessageOptions
+ * @property {MessageKind|'danger'} [kind='info'] Default message intent.
+ * @property {number} [timeout=4000] Default auto-dismiss delay.
+ * @property {boolean} [closable=true] Default close-button visibility.
+ * @property {number} [maxVisible=5] Maximum number of visible messages.
+ */
+/** @typedef {{close: () => void}} MessageHandle */
+/**
+ * @typedef {Object} ProgressHandle
+ * @property {(pct: number, text?: string) => void} update Updates progress and optional text.
+ * @property {() => void} done Completes and dismisses the progress message.
+ * @property {(text?: string) => void} fail Marks progress as failed and dismisses it later.
+ */
+/**
+ * Small FIFO admission queue used by message regions.
+ * @template T
+ */
+export declare class MessageQueue<T> {
+    #private;
+    /**
+     * @param {number} [limit=5] Maximum active item count.
+     * @param {(item: T) => void} [onActivate=()=>{}] Called when an item becomes active.
+     */
+    constructor(limit?: number, onActivate?: (item: T) => void);
+    /**
+     * Adds an item, activating it immediately when capacity allows.
+     * @param {T} item Item to add.
+     * @returns {'active'|'pending'} Initial queue location.
+     */
+    enqueue(item: T): 'active' | 'pending';
+    /**
+     * Removes an item and promotes the oldest pending item when needed.
+     * @param {T} item Item to remove.
+     * @returns {'active'|'pending'|null} Previous location, or null when absent.
+     */
+    remove(item: T): 'active' | 'pending' | null;
+    /**
+     * Reports whether an item is active.
+     * @param {T} item Item to inspect.
+     * @returns {boolean}
+     */
+    isActive(item: T): boolean;
+    /**
+     * Removes every item without activation callbacks.
+     * @returns {{active: T[], pending: T[]}} Removed items.
+     */
+    clear(): {
+        active: T[];
+        pending: T[];
+    };
+    /** @returns {number} */
+    get activeCount(): number;
+    /** @returns {number} */
+    get pendingCount(): number;
+}
+/**
+ * Inline message area and static toast service.
+ * @extends {Component<MessageOptions>}
+ */
+export declare class Message extends Component<MessageOptions> {
+    #private;
+    _createdRoot: boolean;
+    _original: {
+        attributes: [string, string][];
+        children: Node[];
+    };
+    _entries: Set<any>;
+    _queue: MessageQueue<any>;
+    _cleaned: boolean;
+    static cssName: string;
+    /** @type {Readonly<MessageOptions>} */
+    static defaults: Readonly<MessageOptions>;
+    /** @returns {HTMLElement} */
+    render(): HTMLElement;
+    /**
+     * Shows a message in this inline region.
+     * @param {string|Node} msg Text or DOM content.
+     * @param {MessageShowOptions} [options={}] Display options.
+     * @returns {MessageHandle}
+     */
+    show(msg: string | Node, options?: MessageShowOptions): MessageHandle;
+    /**
+     * Shows a floating informational toast.
+     * @param {string|Node} msg Text or DOM content.
+     * @param {MessageShowOptions} [options={}] Display options.
+     * @returns {MessageHandle}
+     */
+    static info(msg: string | Node, options?: MessageShowOptions): MessageHandle;
+    /**
+     * Shows a floating success toast.
+     * @param {string|Node} msg Text or DOM content.
+     * @param {MessageShowOptions} [options={}] Display options.
+     * @returns {MessageHandle}
+     */
+    static success(msg: string | Node, options?: MessageShowOptions): MessageHandle;
+    /**
+     * Shows a floating warning toast.
+     * @param {string|Node} msg Text or DOM content.
+     * @param {MessageShowOptions} [options={}] Display options.
+     * @returns {MessageHandle}
+     */
+    static warning(msg: string | Node, options?: MessageShowOptions): MessageHandle;
+    /**
+     * Shows a floating error toast.
+     * @param {string|Node} msg Text or DOM content.
+     * @param {MessageShowOptions} [options={}] Display options.
+     * @returns {MessageHandle}
+     */
+    static error(msg: string | Node, options?: MessageShowOptions): MessageHandle;
+    /**
+     * Shows a floating toast.
+     * @param {string|Node} msg Text or DOM content.
+     * @param {MessageShowOptions} [options={}] Display options.
+     * @returns {MessageHandle}
+     */
+    static show(msg: string | Node, options?: MessageShowOptions): MessageHandle;
+    /**
+     * Shows a floating progress status.
+     * @param {string} text Initial status text.
+     * @returns {ProgressHandle}
+     */
+    static progress(text: string): ProgressHandle;
+    /** @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 {{pct: number, text: string}|null} [progress=null]
+     * @returns {any}
+     */
+    _createEntry(msg: string | Node, settings: {
+        kind: MessageKind;
+        timeout: number;
+        closable: boolean;
+    }, progress?: {
+        pct: number;
+        text: string;
+    } | null): any;
+    /** @param {any} entry @returns {void} */
+    _activate(entry: any): void;
+    /** @param {any} entry @returns {void} */
+    _schedule(entry: any): void;
+    /** @param {any} entry @returns {void} */
+    _pause(entry: any): void;
+    /** @param {any} entry @returns {void} */
+    _resume(entry: any): void;
+    /** @param {any} entry @returns {void} */
+    _close(entry: any): void;
+    /** @param {any} entry @returns {void} */
+    _finish(entry: any): void;
+}

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

@@ -0,0 +1,105 @@
+import { Component } from '../../core/component.js';
+export type ModalOptions = {
+    /**
+     * Modal content.
+     */
+    content?: Node | string | number | {
+        toElement: () => Node | null;
+    } | null;
+    /**
+     * CSS width, or a pixel width when numeric.
+     */
+    width?: string | number;
+    /**
+     * Whether Escape may close the modal.
+     */
+    closable?: boolean;
+    /**
+     * Whether a backdrop click closes the modal.
+     */
+    lightDismiss?: boolean;
+    /**
+     * Whether to destroy the modal after it closes.
+     */
+    destroyOnClose?: boolean;
+    /**
+     * Open event listener.
+     */
+    onopen?: (event: CustomEvent<Record<string, never>>) => void;
+    /**
+     * Close event listener.
+     */
+    onclose?: (event: CustomEvent<{
+        result: unknown;
+    }>) => void;
+    /**
+     * Cancel event listener.
+     */
+    oncancel?: (event: CustomEvent<Record<string, never>>) => void;
+};
+/**
+ * @typedef {Object} ModalOptions
+ * @property {Node|string|number|{toElement: () => Node|null}|null} [content=null] Modal content.
+ * @property {string|number} [width='auto'] CSS width, or a pixel width when numeric.
+ * @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 {(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.
+ */
+/**
+ * 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.
+ * @fires Modal#open
+ * @fires Modal#close
+ * @fires Modal#cancel
+ * @extends {Component<ModalOptions>}
+ */
+export declare class Modal extends Component<ModalOptions> {
+    #private;
+    static cssName: string;
+    /** @type {Readonly<ModalOptions>} */
+    static defaults: Readonly<ModalOptions>;
+    /**
+     * Creates a modal appended to `document.body`.
+     * @param {Element|string|null} [_target=null] Ignored; Modal always owns its root dialog.
+     * @param {ModalOptions} [options={}] Modal options.
+     */
+    constructor(_target?: Element | string | null, options?: ModalOptions);
+    /**
+     * Creates the owned native dialog.
+     * @returns {HTMLDialogElement}
+     */
+    render(): HTMLDialogElement;
+    /**
+     * Opens the modal in the browser top layer.
+     * @returns {this}
+     * @fires Modal#open
+     */
+    open(): this;
+    /**
+     * Closes the modal with an optional result.
+     * @param {unknown} [result] Result included in the close event.
+     * @returns {this}
+     */
+    close(result?: unknown): this;
+    /**
+     * Replaces the modal content without interpreting strings as HTML.
+     * @param {Node|string|number|{toElement: () => Node|null}|null} content Content to display.
+     * @returns {this}
+     */
+    setContent(content: Node | string | number | {
+        toElement: () => Node | null;
+    } | null): this;
+    /**
+     * Reports whether the native dialog is open.
+     * @returns {boolean}
+     */
+    isOpen(): boolean;
+    /**
+     * Closes and removes the owned dialog. Safe to call repeatedly.
+     * @returns {void}
+     */
+    destroy(): void;
+}

package/dist/types/components/multi-value-editor/field-adapter.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Registers the MultiValueEditor-backed `multivalueeditor` field type.
+ * @returns {void}
+ */
+export declare function registerMultiValueEditorFieldAdapter(): void;

package/dist/types/components/multi-value-editor/multi-value-editor.d.ts

@@ -0,0 +1,66 @@
+import { Component } from '../../core/component.js';
+export type MultiValueEditorOptions = {
+    /**
+     * Initial ordered values.
+     */
+    values?: unknown[];
+    /**
+     * Allowed values; null uses text inputs.
+     */
+    options?: unknown[] | Record<string, string> | null;
+    /**
+     * Add-row button text.
+     */
+    addLabel?: string;
+};
+/**
+ * @typedef {Object} MultiValueEditorOptions
+ * @property {unknown[]} [values=[]] Initial ordered values.
+ * @property {unknown[]|Record<string, string>|null} [options=null] Allowed values; null uses text inputs.
+ * @property {string} [addLabel='Add value'] Add-row button text.
+ */
+/**
+ * Ordered value editor with explicit editable rows and controls.
+ * @fires MultiValueEditor#change
+ * @extends {Component<MultiValueEditorOptions>}
+ */
+export declare class MultiValueEditor extends Component<MultiValueEditorOptions> {
+    _values: string[];
+    _ownedNodes: any[];
+    _rows: HTMLElement;
+    _add: HTMLElement;
+    static cssName: string;
+    /** @type {MultiValueEditorOptions} */
+    static defaults: MultiValueEditorOptions;
+    /** @returns {HTMLElement} */
+    render(): HTMLElement;
+    /**
+     * Returns a copy of the ordered values.
+     * @returns {string[]}
+     */
+    getValues(): string[];
+    /**
+     * Replaces all rows.
+     * @param {unknown[]} values New ordered values.
+     * @param {{silent?: boolean}} [options={}] Set `silent` to suppress `change`.
+     * @returns {this}
+     */
+    setValues(values: unknown[], { silent }?: {
+        silent?: boolean;
+    }): this;
+    /** @param {number} [focusIndex=-1] @returns {void} */
+    _renderRows(focusIndex?: number): void;
+    /** @param {MouseEvent} event @returns {void} */
+    _handleClick(event: MouseEvent): void;
+    /** @param {Event} event @returns {void} */
+    _handleChange(event: Event): void;
+    /** @returns {void} */
+    _emitChange(): void;
+    /** @returns {void} */
+    destroy(): void;
+}
+/**
+ * Ordered values changed event.
+ * @event MultiValueEditor#change
+ * @type {CustomEvent<{values: string[]}>
+ */

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

@@ -0,0 +1,229 @@
+import { Component } from '../../core/component.js';
+import { MenuButton } from '../menu-button/menu-button.js';
+export type NavigationPanelContent = Node | Component | (() => Node | Component);
+export type NavigationItem = {
+    /**
+     * Stable item name.
+     */
+    name: string;
+    /**
+     * Visible item title.
+     */
+    title: string;
+    /**
+     * Optional badge text.
+     */
+    badge?: string | null;
+    /**
+     * Optional panel content; its presence enables tab semantics.
+     */
+    content?: NavigationPanelContent;
+    /**
+     * Optional link destination for plain navigation.
+     */
+    href?: string;
+    /**
+     * Whether the item is unavailable.
+     */
+    disabled?: boolean;
+    /**
+     * Selection callback.
+     */
+    onselect?: (name: string, item: NavigationItem, navigation: NavigationBar) => void;
+};
+export type NavigationActionDescriptor = {
+    /**
+     * Visible button label.
+     */
+    label?: string;
+    /**
+     * Icon name from the kernel icon set.
+     */
+    icon?: string | null;
+    /**
+     * Visual intent.
+     */
+    kind?: 'default' | 'primary' | 'danger' | 'ghost';
+    /**
+     * Control size.
+     */
+    size?: 'md' | 'sm';
+    /**
+     * Whether the action is disabled.
+     */
+    disabled?: boolean;
+    /**
+     * Native title text.
+     */
+    title?: string;
+    /**
+     * Click callback.
+     */
+    onclick?: (event: MouseEvent) => void;
+};
+export type NavigationAction = Element | NavigationActionDescriptor;
+export type NavigationBarOptions = {
+    /**
+     * Brand or application title.
+     */
+    title?: string;
+    /**
+     * Navigation items.
+     */
+    items?: NavigationItem[];
+    /**
+     * Initially active item, or the first enabled item.
+     */
+    active?: string | null;
+    /**
+     * Right-aligned action elements or descriptors.
+     */
+    actions?: NavigationAction[];
+    /**
+     * Change callback.
+     */
+    onchange?: (event: CustomEvent<{
+        name: string;
+    }>) => void;
+};
+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 {Node|Component|(() => Node|Component)} NavigationPanelContent */
+/**
+ * @typedef {Object} NavigationItem
+ * @property {string} name Stable item name.
+ * @property {string} title Visible item title.
+ * @property {string|null} [badge=null] Optional badge text.
+ * @property {NavigationPanelContent} [content] Optional panel content; its presence enables tab semantics.
+ * @property {string} [href] Optional link destination for plain navigation.
+ * @property {boolean} [disabled=false] Whether the item is unavailable.
+ * @property {(name: string, item: NavigationItem, navigation: NavigationBar) => void} [onselect] Selection callback.
+ */
+/**
+ * @typedef {Object} NavigationActionDescriptor
+ * @property {string} [label=''] Visible button label.
+ * @property {string|null} [icon=null] Icon name from the kernel icon set.
+ * @property {'default'|'primary'|'danger'|'ghost'} [kind='default'] Visual intent.
+ * @property {'md'|'sm'} [size='md'] Control size.
+ * @property {boolean} [disabled=false] Whether the action is disabled.
+ * @property {string} [title] Native title text.
+ * @property {(event: MouseEvent) => void} [onclick] Click callback.
+ */
+/** @typedef {Element|NavigationActionDescriptor} NavigationAction */
+/**
+ * @typedef {Object} NavigationBarOptions
+ * @property {string} [title=''] Brand or application title.
+ * @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 {(event: CustomEvent<{name: string}>) => void} [onchange] Change callback.
+ */
+/**
+ * @typedef {Object} NavigationRecord
+ * @property {NavigationItem} definition Normalized item definition.
+ * @property {HTMLElement} item Rendered link or button.
+ * @property {HTMLElement} badge Badge element.
+ * @property {HTMLElement|null} panel Optional tab panel.
+ * @property {boolean} built Whether panel content has been mounted.
+ */
+/**
+ * Responsive application navigation with MenuButton overflow.
+ * @fires NavigationBar#change
+ * @extends {Component<NavigationBarOptions>}
+ */
+export declare class NavigationBar extends Component<NavigationBarOptions> {
+    _overflow: MenuButton;
+    _createdRoot: boolean;
+    _original: {
+        attributes: Array<[string, string]>;
+        children: Node[];
+    };
+    _cleaned: boolean;
+    /** @type {NavigationRecord[]} */
+    _items: NavigationRecord[];
+    _activeName: string;
+    _tabMode: boolean;
+    static cssName: string;
+    /** @type {Readonly<NavigationBarOptions>} */
+    static defaults: Readonly<NavigationBarOptions>;
+    /**
+     * Creates or enhances an application navigation bar.
+     * @param {Element|string|null} target Existing container, selector, or null.
+     * @param {NavigationBarOptions} [options={}] Navigation options.
+     */
+    constructor(target: Element | string | null, options?: NavigationBarOptions);
+    /** @returns {HTMLElement} */
+    render(): HTMLElement;
+    /**
+     * Replaces the brand or application title.
+     * @param {string} title Next title.
+     * @returns {this}
+     */
+    setTitle(title: string): this;
+    /**
+     * Replaces navigation items.
+     * @param {NavigationItem[]} list Item definitions.
+     * @returns {this}
+     */
+    setItems(list: NavigationItem[]): this;
+    /**
+     * Selects a navigation item.
+     * @param {string} name Item name.
+     * @returns {this}
+     * @fires NavigationBar#change
+     */
+    setActive(name: string): this;
+    /**
+     * Sets or clears an item badge.
+     * @param {string} name Item name.
+     * @param {string|null} text Badge text, or null to remove it.
+     * @returns {this}
+     */
+    setBadge(name: string, text: string | null): this;
+    /**
+     * Replaces right-aligned application actions.
+     * @param {NavigationAction[]} list Action elements or button descriptors.
+     * @returns {this}
+     */
+    setActions(list: NavigationAction[]): this;
+    /** @returns {void} */
+    destroy(): void;
+    /** @param {NavigationItem} definition @returns {void} */
+    _appendItem(definition: NavigationItem): void;
+    /** @param {NavigationRecord} record @returns {void} */
+    _applyActive(record: NavigationRecord): void;
+    /** @param {NavigationRecord} record @returns {void} */
+    _ensurePanel(record: NavigationRecord): void;
+    /** @param {KeyboardEvent} event @returns {void} */
+    _onTabKeydown(event: KeyboardEvent): void;
+    /** @returns {void} */
+    _syncOverflow(): void;
+    /** @param {NavigationRecord} record @returns {void} */
+    _focusTab(record: NavigationRecord): void;
+    /** @returns {NavigationRecord[]} */
+    _enabledItems(): NavigationRecord[];
+    /** @param {string} name @returns {NavigationRecord|null} */
+    _find(name: string): NavigationRecord | null;
+    /** @param {string} name @returns {NavigationRecord} */
+    _require(name: string): NavigationRecord;
+}

package/dist/types/components/number-field/field-adapter.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Registers the NumberField-backed `number` field type.
+ * @returns {void}
+ */
+export declare function registerNumberFieldAdapter(): void;