@zeyos/zx 2.1.0 → 2.2.1

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

@@ -0,0 +1,125 @@
+import { Component } from '../../core/component.js';
+import { Field } from '../field/field.js';
+export type FieldsetOptions = {
+    /**
+     * Legend text.
+     */
+    title?: string;
+    /**
+     * Grid column count.
+     */
+    columns?: 1 | 2 | 3;
+    /**
+     * Initial fields.
+     */
+    fields?: Record<string, FieldOptions | Field | Element | Component>;
+};
+export type FieldOptions = import('../field/field.js').FieldOptions;
+/**
+ * @typedef {Object} FieldsetOptions
+ * @property {string} [title=''] Legend text.
+ * @property {1|2|3} [columns=1] Grid column count.
+ * @property {Record<string, FieldOptions|Field|Element|Component>} [fields={}] Initial fields.
+ */
+/** @typedef {import('../field/field.js').FieldOptions} FieldOptions */
+/**
+ * Native fieldset that owns and coordinates labelled fields.
+ * @extends {Component<FieldsetOptions>}
+ */
+export declare class Fieldset extends Component<FieldsetOptions> {
+    _fields: Map<any, any>;
+    _ownedFields: Set<any>;
+    _origins: Map<any, any>;
+    _fieldIdAttributes: Map<any, any>;
+    _ownedNodes: any[];
+    _columnAttribute: string;
+    _grid: HTMLElement;
+    static cssName: string;
+    /** @type {FieldsetOptions} */
+    static defaults: FieldsetOptions;
+    /** @returns {HTMLElement} */
+    render(): HTMLElement;
+    /**
+     * Adds a field from options, an existing field, an element, or a component.
+     * @param {string} id Logical field identifier.
+     * @param {FieldOptions|Field|Element|Component} field Field source.
+     * @returns {Field}
+     */
+    addField(id: string, field: FieldOptions | Field | Element | Component): Field;
+    /**
+     * Returns a field by logical identifier.
+     * @param {string} id Field identifier.
+     * @returns {Field|null}
+     */
+    getField(id: string): Field | null;
+    /**
+     * Reports whether a field exists.
+     * @param {string} id Field identifier.
+     * @returns {boolean}
+     */
+    hasField(id: string): boolean;
+    /**
+     * Returns the fields keyed by logical identifier.
+     * @returns {Record<string, Field>}
+     */
+    getFields(): Record<string, Field>;
+    /**
+     * Returns all field values.
+     * @returns {Record<string, unknown>}
+     */
+    getValues(): Record<string, unknown>;
+    /**
+     * Sets matching field values.
+     * @param {Record<string, unknown>} values Values keyed by field identifier.
+     * @param {{silent?: boolean}} [options={}] Set `silent` to suppress field change events.
+     * @returns {this}
+     */
+    setValues(values: Record<string, unknown>, { silent }?: {
+        silent?: boolean;
+    }): this;
+    /**
+     * Returns one field value.
+     * @param {string} id Field identifier.
+     * @returns {unknown}
+     */
+    getValue(id: string): unknown;
+    /**
+     * Sets one field value.
+     * @param {string} id Field identifier.
+     * @param {unknown} value New value.
+     * @returns {this}
+     */
+    setValue(id: string, value: unknown): this;
+    /**
+     * Restores every field to its initial value.
+     * @returns {this}
+     */
+    reset(): this;
+    /**
+     * Removes every field from this fieldset.
+     * @returns {this}
+     */
+    clear(): this;
+    /**
+     * Focuses one field.
+     * @param {string} id Field identifier.
+     * @returns {this}
+     */
+    focus(id: string): this;
+    /**
+     * Applies messages to matching fields and clears unspecified highlights.
+     * @param {Record<string, string>} highlights Messages keyed by field identifier.
+     * @param {'danger'|'warning'|'success'} [kind='danger'] Highlight kind.
+     * @returns {number}
+     */
+    setHighlights(highlights?: Record<string, string>, kind?: 'danger' | 'warning' | 'success'): number;
+    /**
+     * Clears every field highlight.
+     * @returns {this}
+     */
+    clearHighlights(): this;
+    /** @param {Field} field @returns {void} */
+    _releaseField(field: Field): void;
+    /** @returns {void} */
+    destroy(): void;
+}

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

@@ -0,0 +1,252 @@
+import { Component } from '../../core/component.js';
+export type TreeNode = import('../tree/hierarchy.js').TreeNode;
+export type FinderOptions = {
+    /**
+     * Nested nodes.
+     */
+    items?: TreeNode[];
+    /**
+     * Node ID property or reader.
+     */
+    valueKey?: string | ((node: TreeNode) => unknown);
+    /**
+     * Node label property or reader.
+     */
+    labelKey?: string | ((node: TreeNode) => string);
+    /**
+     * Property holding child nodes.
+     */
+    childrenKey?: string;
+    /**
+     * Initially selected node IDs, from the root down.
+     */
+    path?: unknown[];
+    /**
+     * Lazy child loader.
+     */
+    load?: ((node: TreeNode) => Promise<TreeNode[]> | TreeNode[]) | null;
+    /**
+     * Renderer for the leaf preview pane.
+     */
+    preview?: ((node: TreeNode) => Node | string | null) | null;
+    /**
+     * Accessible name of the first column.
+     */
+    rootLabel?: string;
+    /**
+     * Column width in pixels.
+     */
+    columnWidth?: number;
+    /**
+     * Component height in pixels or any CSS length.
+     */
+    height?: number | string | null;
+    /**
+     * Whether to render folder and file icons.
+     */
+    icons?: boolean;
+    /**
+     * Row renderer.
+     */
+    renderItem?: ((node: TreeNode) => Node | string) | null;
+    /**
+     * Text shown in an empty column.
+     */
+    emptyText?: string;
+    /**
+     * Localized messages.
+     */
+    msg?: Record<string, string> | Record<string, Record<string, string>>;
+    /**
+     * Path listener.
+     */
+    onchange?: (event: CustomEvent<{
+        path: unknown[];
+        nodes: TreeNode[];
+        node: TreeNode | null;
+    }>) => void;
+    /**
+     * Activation listener.
+     */
+    onactivate?: (event: CustomEvent<{
+        node: TreeNode;
+        id: unknown;
+    }>) => void;
+    /**
+     * Loader-failure listener.
+     */
+    onerror?: (event: CustomEvent<{
+        error: Error;
+        node: TreeNode;
+        id: unknown;
+    }>) => void;
+};
+/** @typedef {import('../tree/hierarchy.js').TreeNode} TreeNode */
+/**
+ * @typedef {Object} FinderOptions
+ * @property {TreeNode[]} [items=[]] Nested nodes.
+ * @property {string|((node: TreeNode) => unknown)} [valueKey='ID'] Node ID property or reader.
+ * @property {string|((node: TreeNode) => string)} [labelKey='name'] Node label property or reader.
+ * @property {string} [childrenKey='children'] Property holding child nodes.
+ * @property {unknown[]} [path=[]] Initially selected node IDs, from the root down.
+ * @property {((node: TreeNode) => Promise<TreeNode[]>|TreeNode[])|null} [load=null] Lazy child loader.
+ * @property {((node: TreeNode) => Node|string|null)|null} [preview=null] Renderer for the leaf preview pane.
+ * @property {string} [rootLabel=''] Accessible name of the first column.
+ * @property {number} [columnWidth=220] Column width in pixels.
+ * @property {number|string|null} [height=320] Component height in pixels or any CSS length.
+ * @property {boolean} [icons=true] Whether to render folder and file icons.
+ * @property {((node: TreeNode) => Node|string)|null} [renderItem=null] Row renderer.
+ * @property {string} [emptyText='Empty'] Text shown in an empty column.
+ * @property {Record<string, string>|Record<string, Record<string, string>>} [msg] Localized messages.
+ * @property {(event: CustomEvent<{path: unknown[], nodes: TreeNode[], node: TreeNode|null}>) => void} [onchange] Path listener.
+ * @property {(event: CustomEvent<{node: TreeNode, id: unknown}>) => void} [onactivate] Activation listener.
+ * @property {(event: CustomEvent<{error: Error, node: TreeNode, id: unknown}>) => void} [onerror] Loader-failure listener.
+ */
+/**
+ * Miller-columns hierarchy browser: each column lists the children of the row selected in the
+ * column to its left, the way the macOS Finder's column view works.
+ *
+ * Columns are linked listboxes with a single roving tab stop across the whole component: Up and
+ * Down move inside a column, Right steps into the selection's children, Left steps back.
+ *
+ * @fires Finder#change
+ * @fires Finder#activate
+ * @fires Finder#error
+ * @extends {Component<FinderOptions>}
+ */
+export declare class Finder extends Component<FinderOptions> {
+    _items: any[] | import("../tree/hierarchy.js").TreeNode[];
+    _path: any[];
+    _columns: any[] | {
+        nodes: TreeNode[];
+        selectedId: unknown;
+        owner: TreeNode | null;
+    }[];
+    _activeColumn: any;
+    /** @type {Map<unknown, Promise<void>>} In-flight lazy loads, keyed by node ID. */
+    _loading: Map<unknown, Promise<void>>;
+    _pathSequence: any;
+    _createdRoot: boolean;
+    _snapshot: import("../../core/dom.js").TargetSnapshot;
+    _readers: import("../tree/hierarchy.js").NodeReaders;
+    _childrenKey: string;
+    _handleTypeahead: (event: KeyboardEvent | string) => void;
+    static cssName: string;
+    /** @type {FinderOptions} */
+    static defaults: FinderOptions;
+    /** @returns {HTMLElement} */
+    render(): HTMLElement;
+    /**
+     * Returns the selected IDs from the root down.
+     * @returns {unknown[]}
+     */
+    getPath(): unknown[];
+    /**
+     * Returns the selected nodes from the root down.
+     * @returns {TreeNode[]}
+     */
+    getNodes(): TreeNode[];
+    /**
+     * Returns the deepest selected node.
+     * @returns {TreeNode|null}
+     */
+    getSelection(): TreeNode | null;
+    /**
+     * Selects a path, loading every branch along it.
+     * @param {unknown[]} ids Node IDs from the root down.
+     * @param {{silent?: boolean, focus?: boolean}} [options={}] Behavior.
+     * @returns {Promise<this>}
+     * @fires Finder#change
+     */
+    setPath(ids: unknown[], { silent, focus }?: {
+        silent?: boolean;
+        focus?: boolean;
+    }): Promise<this>;
+    /**
+     * Reveals and selects a node anywhere in the tree.
+     * @param {unknown} id Node ID.
+     * @param {{silent?: boolean}} [options={}] Behavior.
+     * @returns {Promise<this>}
+     */
+    reveal(id: unknown, { silent }?: {
+        silent?: boolean;
+    }): Promise<this>;
+    /**
+     * Replaces the whole hierarchy and clears the path.
+     * @param {TreeNode[]} items Nested nodes.
+     * @returns {this}
+     */
+    setItems(items: TreeNode[]): this;
+    /** Focuses the active column. @returns {this} */
+    focus(): this;
+    /**
+     * Rebuilds every column from the current path.
+     * @param {{focus?: boolean}} options Behavior.
+     * @returns {void}
+     */
+    _render({ focus }: {
+        focus?: boolean;
+    }): void;
+    /**
+     * @param {{nodes: TreeNode[], selectedId: unknown, owner: TreeNode|null}} column Column spec.
+     * @param {number} index Column index.
+     * @returns {HTMLElement}
+     */
+    _renderColumn(column: {
+        nodes: TreeNode[];
+        selectedId: unknown;
+        owner: TreeNode | null;
+    }, index: number): HTMLElement;
+    /** Keeps exactly one tab stop across all columns. @returns {void} */
+    _syncTabStop(): void;
+    /** @param {MouseEvent} event @returns {void} */
+    _onClick(event: MouseEvent): void;
+    /** @param {MouseEvent} event @returns {void} */
+    _onDoubleClick(event: MouseEvent): void;
+    /** @param {KeyboardEvent} event @returns {void} */
+    _onKeydown(event: KeyboardEvent): void;
+    /**
+     * Selects a row in a column, truncating the path below it.
+     * @param {number} column Column index.
+     * @param {number} index Row index inside the column.
+     * @param {{focus?: boolean}} [options={}] Behavior.
+     * @returns {Promise<void>}
+     * @fires Finder#change
+     */
+    _selectAt(column: number, index: number, { focus }?: {
+        focus?: boolean;
+    }): Promise<void>;
+    /**
+     * Moves into a branch's children column.
+     * @param {number} column Column index.
+     * @param {number} index Row index.
+     * @returns {Promise<void>}
+     */
+    _enter(column: number, index: number): Promise<void>;
+    /**
+     * Loads a branch's children through the configured loader, once.
+     * @param {TreeNode} node Branch node.
+     * @returns {Promise<void>}
+     */
+    _ensureChildren(node: TreeNode): Promise<void>;
+    /** @param {number} column @returns {TreeNode[]} */
+    _columnNodes(column: number): TreeNode[];
+    /** @param {Element} row @returns {{column: number, index: number}} */
+    _locate(row: Element): {
+        column: number;
+        index: number;
+    };
+    /** @param {number} column @param {number} index @returns {HTMLElement|null} */
+    _rowAt(column: number, index: number): HTMLElement | null;
+    /** @param {number} column @returns {HTMLElement|null} */
+    _activeRow(column: number): HTMLElement | null;
+    /** @returns {void} */
+    _emitChange(): void;
+    /** @param {string} key @param {string} fallback @returns {string} */
+    _message(key: string, fallback: string): string;
+    /** Restores an enhanced target to the markup it had before the takeover. @returns {void} */
+    destroy(): void;
+}
+/** Path change. @event Finder#change @type {CustomEvent<{path: unknown[], nodes: TreeNode[], node: TreeNode|null}>} */
+/** Leaf activated by Enter or double-click. @event Finder#activate @type {CustomEvent<{node: TreeNode, id: unknown}>} */
+/** A lazy loader rejected. @event Finder#error @type {CustomEvent<{error: Error, node: TreeNode, id: unknown}>} */

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

@@ -0,0 +1,194 @@
+import { Component } from '../../core/component.js';
+import { Fieldset } from '../fieldset/fieldset.js';
+export type FormAction = {
+    /**
+     * Action identifier.
+     */
+    id?: string;
+    /**
+     * Button text.
+     */
+    label?: string;
+    /**
+     * Kernel icon name.
+     */
+    icon?: string | null;
+    /**
+     * Visual intent.
+     */
+    kind?: 'default' | 'primary' | 'danger' | 'ghost';
+    /**
+     * Button size.
+     */
+    size?: 'md' | 'sm';
+    /**
+     * Native button type.
+     */
+    type?: 'button' | 'submit' | 'reset';
+    /**
+     * Disabled state.
+     */
+    disabled?: boolean;
+    /**
+     * Native button title.
+     */
+    title?: string;
+    /**
+     * Click callback.
+     */
+    onClick?: (event: MouseEvent, form: Form) => void;
+};
+export type FormOptions = {
+    /**
+     * Initial fieldsets.
+     */
+    fieldsets?: Array<Fieldset | import('../fieldset/fieldset.js').FieldsetOptions>;
+    /**
+     * Form action descriptors.
+     */
+    actions?: FormAction[];
+    /**
+     * Native `novalidate` state.
+     */
+    novalidate?: boolean;
+};
+/**
+ * @typedef {Object} FormAction
+ * @property {string} [id] Action identifier.
+ * @property {string} [label] Button text.
+ * @property {string|null} [icon=null] Kernel icon name.
+ * @property {'default'|'primary'|'danger'|'ghost'} [kind='default'] Visual intent.
+ * @property {'md'|'sm'} [size='md'] Button size.
+ * @property {'button'|'submit'|'reset'} [type='button'] Native button type.
+ * @property {boolean} [disabled=false] Disabled state.
+ * @property {string} [title] Native button title.
+ * @property {(event: MouseEvent, form: Form) => void} [onClick] Click callback.
+ */
+/**
+ * @typedef {Object} FormOptions
+ * @property {Array<Fieldset|import('../fieldset/fieldset.js').FieldsetOptions>} [fieldsets=[]] Initial fieldsets.
+ * @property {FormAction[]} [actions=[]] Form action descriptors.
+ * @property {boolean} [novalidate=true] Native `novalidate` state.
+ */
+/**
+ * Real form element coordinating fieldsets, validation, and actions.
+ * @fires Form#submit
+ * @fires Form#invalid
+ * @fires Form#change
+ * @extends {Component<FormOptions>}
+ */
+export declare class Form extends Component<FormOptions> {
+    _fieldsets: any[];
+    _ownedFieldsets: Set<any>;
+    _origins: Map<any, any>;
+    _ownedNodes: any[];
+    _novalidateAttribute: string;
+    _body: HTMLElement;
+    _actions: HTMLElement;
+    _actionDescriptors: {
+        id?: string;
+        label?: string;
+        icon?: string | null;
+        kind?: 'default' | 'primary' | 'danger' | 'ghost';
+        size?: 'md' | 'sm';
+        type?: 'button' | 'submit' | 'reset';
+        disabled?: boolean;
+        title?: string;
+        onClick?: (event: MouseEvent, form: Form) => void;
+    }[];
+    static cssName: string;
+    /** @type {FormOptions & {msg: Record<string, string>}} */
+    static defaults: FormOptions & {
+        msg: Record<string, string>;
+    };
+    /** @returns {HTMLElement} */
+    render(): HTMLElement;
+    /**
+     * Adds an existing fieldset or constructs one from options.
+     * @param {Fieldset|import('../fieldset/fieldset.js').FieldsetOptions} fieldset Fieldset source.
+     * @returns {Fieldset}
+     */
+    addFieldset(fieldset: Fieldset | import('../fieldset/fieldset.js').FieldsetOptions): Fieldset;
+    /**
+     * Replaces the rendered action buttons.
+     * @param {FormAction[]} list Button descriptors.
+     * @returns {this}
+     */
+    setActions(list: FormAction[]): this;
+    /**
+     * Returns all values merged in fieldset order.
+     * @returns {Record<string, unknown>}
+     */
+    getValues(): Record<string, unknown>;
+    /**
+     * Sets matching values across all fieldsets.
+     * @param {Record<string, unknown>} values Values keyed by field identifier.
+     * @param {{silent?: boolean}} [options={}] Set `silent` to suppress field change events.
+     * @returns {this}
+     */
+    setValues(values: Record<string, unknown>, { silent }?: {
+        silent?: boolean;
+    }): this;
+    /**
+     * Returns the first matching field.
+     * @param {string} id Field identifier.
+     * @returns {import('../field/field.js').Field|null}
+     */
+    getField(id: string): import('../field/field.js').Field | null;
+    /**
+     * Sets one matching field value.
+     * @param {string} id Field identifier.
+     * @param {unknown} value New value.
+     * @returns {this}
+     */
+    setValue(id: string, value: unknown): this;
+    /**
+     * Returns one matching field value.
+     * @param {string} id Field identifier.
+     * @returns {unknown}
+     */
+    getValue(id: string): unknown;
+    /**
+     * Resets all fieldsets and highlights.
+     * @returns {this}
+     */
+    reset(): this;
+    /**
+     * Applies field highlights across all fieldsets.
+     * @param {Record<string, string>} highlights Messages keyed by field identifier.
+     * @param {'danger'|'warning'|'success'} [kind='danger'] Highlight kind.
+     * @returns {number}
+     */
+    setHighlights(highlights: Record<string, string>, kind?: 'danger' | 'warning' | 'success'): number;
+    /**
+     * Clears all field highlights.
+     * @returns {this}
+     */
+    clearHighlights(): this;
+    /**
+     * Validates and emits a preventable submit event.
+     * @returns {boolean} True when valid and not prevented.
+     * @fires Form#submit
+     * @fires Form#invalid
+     */
+    submit(): boolean;
+    /** @param {Event} event @returns {void} */
+    _handleAction(event: Event): void;
+    /** @returns {void} */
+    destroy(): void;
+}
+/**
+ * Successful form submission event.
+ * @event Form#submit
+ * @type {CustomEvent<{values: Record<string, unknown>}>
+ */
+/**
+ * Form validation failure event.
+ * @event Form#invalid
+ * @type {CustomEvent<{errors: Record<string, string>}>
+ */
+/**
+ * Delegated field value change event.
+ * @event Form#change
+ * @type {CustomEvent<{id: string, value: unknown}>
+ */

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

@@ -0,0 +1,89 @@
+import { Component } from '../../core/component.js';
+export type GroupboxOptions = {
+    /**
+     * Section title.
+     */
+    title?: string;
+    /**
+     * Initial expanded state.
+     */
+    open?: boolean;
+    /**
+     * Open callback.
+     */
+    onopen?: (event: CustomEvent<Record<string, never>>) => void;
+    /**
+     * Close callback.
+     */
+    onclose?: (event: CustomEvent<Record<string, never>>) => void;
+};
+export type GroupboxContent = string | Node | Component;
+/**
+ * @typedef {Object} GroupboxOptions
+ * @property {string} [title=''] Section title.
+ * @property {boolean} [open=true] Initial expanded state.
+ * @property {(event: CustomEvent<Record<string, never>>) => void} [onopen] Open callback.
+ * @property {(event: CustomEvent<Record<string, never>>) => void} [onclose] Close callback.
+ */
+/** @typedef {string|Node|Component} GroupboxContent */
+/**
+ * Collapsible section backed by native details and summary elements.
+ * @fires Groupbox#open
+ * @fires Groupbox#close
+ * @extends {Component<GroupboxOptions>}
+ */
+export declare class Groupbox extends Component<GroupboxOptions> {
+    _adoption: any;
+    _createdRoot: boolean;
+    _original: {
+        attributes: [string, string][];
+        children: Node[];
+    };
+    _lastOpen: any;
+    _cleaned: boolean;
+    static cssName: string;
+    /** @type {Readonly<GroupboxOptions>} */
+    static defaults: Readonly<GroupboxOptions>;
+    /**
+     * Creates or adopts a native details section.
+     * @param {Element|string|null} target Existing details, plain container, selector, or null.
+     * @param {GroupboxOptions} [options={}] Groupbox options.
+     */
+    constructor(target: Element | string | null, options?: GroupboxOptions);
+    /** @returns {HTMLDetailsElement} */
+    render(): HTMLDetailsElement;
+    /**
+     * Expands the section.
+     * @returns {this}
+     */
+    open(): this;
+    /**
+     * Collapses the section.
+     * @returns {this}
+     */
+    close(): this;
+    /**
+     * Toggles the section.
+     * @returns {this}
+     */
+    toggle(): this;
+    /**
+     * Reports whether the section is expanded.
+     * @returns {boolean}
+     */
+    isOpen(): boolean;
+    /**
+     * Replaces the visible title.
+     * @param {string} title Next title.
+     * @returns {this}
+     */
+    setTitle(title: string): this;
+    /**
+     * Replaces the section body.
+     * @param {GroupboxContent} content Next text, node, or component.
+     * @returns {this}
+     */
+    setContent(content: GroupboxContent): this;
+    /** @returns {void} */
+    destroy(): void;
+}