@zeyos/zx 2.1.0 → 2.2.1

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

@@ -0,0 +1,383 @@
+import { Component } from '../../core/component.js';
+export type TreeNode = import('./hierarchy.js').TreeNode;
+export type TreeOptions = {
+    /**
+     * 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 expanded node IDs.
+     */
+    expanded?: unknown[];
+    /**
+     * Selection mode.
+     */
+    selection?: false | 'single' | 'multi';
+    /**
+     * Initially selected node IDs.
+     */
+    selected?: unknown[];
+    /**
+     * Whether to render tri-state checkboxes.
+     */
+    checkboxes?: boolean;
+    /**
+     * Initially checked node IDs.
+     */
+    checked?: unknown[];
+    /**
+     * Whether to render folder and file icons.
+     */
+    icons?: boolean;
+    /**
+     * Label renderer.
+     */
+    renderLabel?: ((node: TreeNode) => Node | string) | null;
+    /**
+     * Lazy child loader.
+     */
+    load?: ((node: TreeNode) => Promise<TreeNode[]> | TreeNode[]) | null;
+    /**
+     * Label substring the tree is filtered by.
+     */
+    filter?: string;
+    /**
+     * Accessible name of the tree.
+     */
+    label?: string;
+    /**
+     * Text shown when the tree is empty.
+     */
+    emptyText?: string;
+    /**
+     * Scroll height in pixels or any CSS length.
+     */
+    height?: number | string | null;
+    /**
+     * Localized messages.
+     */
+    msg?: Record<string, string> | Record<string, Record<string, string>>;
+    /**
+     * Selection listener.
+     */
+    onselect?: (event: CustomEvent<{
+        node: TreeNode;
+        id: unknown;
+        ids: unknown[];
+    }>) => void;
+    /**
+     * Expand listener.
+     */
+    onexpand?: (event: CustomEvent<{
+        node: TreeNode;
+        id: unknown;
+    }>) => void;
+    /**
+     * Collapse listener.
+     */
+    oncollapse?: (event: CustomEvent<{
+        node: TreeNode;
+        id: unknown;
+    }>) => void;
+    /**
+     * Activation listener.
+     */
+    onactivate?: (event: CustomEvent<{
+        node: TreeNode;
+        id: unknown;
+    }>) => void;
+    /**
+     * Check listener.
+     */
+    oncheck?: (event: CustomEvent<{
+        ids: unknown[];
+        node: TreeNode | null;
+    }>) => void;
+    /**
+     * Loader-failure listener.
+     */
+    onerror?: (event: CustomEvent<{
+        error: Error;
+        node: TreeNode;
+        id: unknown;
+    }>) => void;
+};
+/** @typedef {import('./hierarchy.js').TreeNode} TreeNode */
+/**
+ * @typedef {Object} TreeOptions
+ * @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[]} [expanded=[]] Initially expanded node IDs.
+ * @property {false|'single'|'multi'} [selection='single'] Selection mode.
+ * @property {unknown[]} [selected=[]] Initially selected node IDs.
+ * @property {boolean} [checkboxes=false] Whether to render tri-state checkboxes.
+ * @property {unknown[]} [checked=[]] Initially checked node IDs.
+ * @property {boolean} [icons=true] Whether to render folder and file icons.
+ * @property {((node: TreeNode) => Node|string)|null} [renderLabel=null] Label renderer.
+ * @property {((node: TreeNode) => Promise<TreeNode[]>|TreeNode[])|null} [load=null] Lazy child loader.
+ * @property {string} [filter=''] Label substring the tree is filtered by.
+ * @property {string} [label='Tree'] Accessible name of the tree.
+ * @property {string} [emptyText='Nothing to show'] Text shown when the tree is empty.
+ * @property {number|string|null} [height=null] Scroll height in pixels or any CSS length.
+ * @property {Record<string, string>|Record<string, Record<string, string>>} [msg] Localized messages.
+ * @property {(event: CustomEvent<{node: TreeNode, id: unknown, ids: unknown[]}>) => void} [onselect] Selection listener.
+ * @property {(event: CustomEvent<{node: TreeNode, id: unknown}>) => void} [onexpand] Expand listener.
+ * @property {(event: CustomEvent<{node: TreeNode, id: unknown}>) => void} [oncollapse] Collapse listener.
+ * @property {(event: CustomEvent<{node: TreeNode, id: unknown}>) => void} [onactivate] Activation listener.
+ * @property {(event: CustomEvent<{ids: unknown[], node: TreeNode|null}>) => void} [oncheck] Check listener.
+ * @property {(event: CustomEvent<{error: Error, node: TreeNode, id: unknown}>) => void} [onerror] Loader-failure listener.
+ */
+/**
+ * Hierarchical tree implementing the APG tree pattern.
+ *
+ * Rows are rendered as a flat list carrying `aria-level` / `aria-setsize` / `aria-posinset`
+ * rather than nested `role="group"` containers — the flattened variant the APG allows. It keeps
+ * roving tabindex, arrow-key movement, and virtualization-friendly re-rendering simple.
+ *
+ * @fires TreeView#select
+ * @fires TreeView#expand
+ * @fires TreeView#collapse
+ * @fires TreeView#activate
+ * @fires TreeView#check
+ * @fires TreeView#error
+ * @extends {Component<TreeOptions>}
+ */
+export declare class TreeView extends Component<TreeOptions> {
+    _items: any[] | import("./hierarchy.js").TreeNode[];
+    _rows: any[] | {
+        node: import("./hierarchy.js").TreeNode;
+        id: unknown;
+        level: number;
+        parent: import("./hierarchy.js").TreeNode | null;
+        posinset: number;
+        setsize: number;
+    }[];
+    _expanded: Set<any>;
+    _selected: Set<any> | Set<unknown>;
+    _checked: Set<any>;
+    /** @type {Map<unknown, Promise<boolean>>} In-flight lazy loads, keyed by node ID. */
+    _loading: Map<unknown, Promise<boolean>>;
+    _focusId: any;
+    _filter: string;
+    _createdRoot: boolean;
+    _snapshot: import("../../core/dom.js").TargetSnapshot;
+    _readers: import("./hierarchy.js").NodeReaders;
+    _childrenKey: string;
+    _handleTypeahead: (event: KeyboardEvent | string) => void;
+    static cssName: string;
+    /** @type {TreeOptions} */
+    static defaults: TreeOptions;
+    /** @returns {HTMLElement} */
+    render(): HTMLElement;
+    /**
+     * Replaces the whole tree.
+     * @param {TreeNode[]} items Nested nodes.
+     * @returns {this}
+     */
+    setItems(items: TreeNode[]): this;
+    /**
+     * Returns the working copy of the tree, including lazily loaded children.
+     * @returns {TreeNode[]}
+     */
+    getItems(): TreeNode[];
+    /**
+     * Looks a node up by ID.
+     * @param {unknown} id Node ID.
+     * @returns {TreeNode|null}
+     */
+    getNode(id: unknown): TreeNode | null;
+    /**
+     * Returns the chain of nodes from a root down to the given node.
+     * @param {unknown} id Node ID.
+     * @returns {TreeNode[]}
+     */
+    getPath(id: unknown): TreeNode[];
+    /**
+     * Filters the tree by a label substring, keeping the ancestors of every match.
+     * @param {string} query Search text; an empty string restores the full tree.
+     * @returns {this}
+     */
+    setFilter(query: string): this;
+    /**
+     * Expands one branch, loading its children first when a lazy loader is configured.
+     * @param {unknown} id Node ID.
+     * @returns {Promise<this>}
+     * @fires TreeView#expand
+     */
+    expand(id: unknown): Promise<this>;
+    /**
+     * Collapses one branch.
+     * @param {unknown} id Node ID.
+     * @returns {this}
+     * @fires TreeView#collapse
+     */
+    collapse(id: unknown): this;
+    /**
+     * Expands or collapses one branch.
+     * @param {unknown} id Node ID.
+     * @returns {Promise<this>}
+     */
+    toggle(id: unknown): Promise<this>;
+    /**
+     * Expands every already-loaded branch.
+     * @returns {this}
+     */
+    expandAll(): this;
+    /** Collapses every branch. @returns {this} */
+    collapseAll(): this;
+    /**
+     * Expands every ancestor of a node so the node becomes visible.
+     * @param {unknown} id Node ID.
+     * @returns {this}
+     */
+    reveal(id: unknown): this;
+    /**
+     * Selects one node, replacing the selection in single mode.
+     * @param {unknown} id Node ID.
+     * @param {{silent?: boolean, additive?: boolean}} [options={}] Selection behavior.
+     * @returns {this}
+     * @fires TreeView#select
+     */
+    select(id: unknown, { silent, additive }?: {
+        silent?: boolean;
+        additive?: boolean;
+    }): this;
+    /**
+     * Returns the selected node IDs.
+     * @returns {unknown[]}
+     */
+    getSelection(): unknown[];
+    /**
+     * Replaces the selection.
+     * @param {unknown[]} ids Node IDs.
+     * @param {{silent?: boolean}} [options={}] Set `silent` to suppress `select`.
+     * @returns {this}
+     */
+    setSelection(ids: unknown[], { silent }?: {
+        silent?: boolean;
+    }): this;
+    /** Clears the selection. @returns {this} */
+    clearSelection(): this;
+    /**
+     * Returns the checked node IDs.
+     * @param {{leavesOnly?: boolean}} [options={}] Set `leavesOnly` to skip fully checked branches.
+     * @returns {unknown[]}
+     */
+    getChecked({ leavesOnly }?: {
+        leavesOnly?: boolean;
+    }): unknown[];
+    /**
+     * Replaces the checked set, propagating each ID down its sub-tree.
+     * @param {unknown[]} ids Node IDs.
+     * @param {{silent?: boolean}} [options={}] Set `silent` to suppress `check`.
+     * @returns {this}
+     * @fires TreeView#check
+     */
+    setChecked(ids: unknown[], { silent }?: {
+        silent?: boolean;
+    }): this;
+    /**
+     * Checks or unchecks one node and its sub-tree.
+     * @param {unknown} id Node ID.
+     * @param {boolean} checked Next state.
+     * @param {{silent?: boolean}} [options={}] Set `silent` to suppress `check`.
+     * @returns {this}
+     * @fires TreeView#check
+     */
+    check(id: unknown, checked: boolean, { silent }?: {
+        silent?: boolean;
+    }): this;
+    /**
+     * Moves DOM focus to a node, revealing it first.
+     * @param {unknown} id Node ID.
+     * @returns {this}
+     */
+    focusNode(id: unknown): this;
+    /** @returns {TreeNode[]} */
+    _visibleItems(): TreeNode[];
+    /** Rebuilds every row from the current tree, expansion set, and filter. @returns {void} */
+    _renderRows(): void;
+    /**
+     * @param {{node: TreeNode, id: unknown, level: number, posinset: number, setsize: number}} row Row spec.
+     * @returns {HTMLElement}
+     */
+    _renderRow(row: {
+        node: TreeNode;
+        id: unknown;
+        level: number;
+        posinset: number;
+        setsize: number;
+    }): HTMLElement;
+    /** Applies expansion, selection, check, loading, and roving-tabindex state to every row. */
+    _syncRows(): 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;
+    /**
+     * Expands every sibling branch of a row, the APG `*` shortcut.
+     * @param {{parent: TreeNode|null}} row Focused row.
+     * @returns {void}
+     */
+    _expandSiblings(row: {
+        parent: TreeNode | null;
+    }): void;
+    /**
+     * Loads a branch's children through the configured loader, once.
+     * @param {TreeNode} node Branch node.
+     * @param {unknown} id Node ID.
+     * @returns {Promise<void>}
+     */
+    _ensureChildren(node: TreeNode, id: unknown): Promise<void>;
+    /**
+     * @param {unknown} id Node ID.
+     * @param {boolean} checked Next state.
+     * @param {{silent?: boolean}} options Behavior.
+     * @returns {TreeNode|null}
+     */
+    _applyCheck(id: unknown, checked: boolean, { silent }: {
+        silent?: boolean;
+    }): TreeNode | null;
+    /**
+     * Derives a node's tri-state check state from its descendants.
+     * @param {TreeNode} node Node to inspect.
+     * @returns {'checked'|'partial'|'unchecked'}
+     */
+    _checkState(node: TreeNode): 'checked' | 'partial' | 'unchecked';
+    /**
+     * The visible rows starting just after the focused one, wrapping around.
+     * @returns {{node: TreeNode, id: unknown}[]}
+     */
+    _rotatedRows(): {
+        node: TreeNode;
+        id: unknown;
+    }[];
+    /** @param {Element} element @returns {number} */
+    _rowIndex(element: Element): number;
+    /** @param {unknown} id @returns {Element|null} */
+    _rowElement(id: unknown): Element | null;
+    /** @param {number} index @returns {void} */
+    _focusRow(index: number): void;
+    /** @param {unknown} id @returns {void} */
+    _focusNodeId(id: unknown): 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;
+}

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

@@ -0,0 +1,61 @@
+export type TruncateOptions = {
+    /**
+     * Lines to keep. One line ends in an ellipsis; more clamp the block.
+     */
+    lines?: number;
+    /**
+     * Whether a native `title` tooltip is set — and kept up to date —
+     * while the text is actually cut off, so the full value stays reachable on hover.
+     */
+    title?: boolean;
+};
+export type TruncateController = {
+    /**
+     * Re-measures and returns whether the text is currently cut off.
+     */
+    update: () => boolean;
+    /**
+     * Whether the text was cut off at the last measurement.
+     */
+    isTruncated: () => boolean;
+    /**
+     * Removes the classes, the observer, and any title this set.
+     */
+    destroy: () => void;
+};
+/**
+ * @typedef {Object} TruncateOptions
+ * @property {number} [lines=1] Lines to keep. One line ends in an ellipsis; more clamp the block.
+ * @property {boolean} [title=true] Whether a native `title` tooltip is set — and kept up to date —
+ *   while the text is actually cut off, so the full value stays reachable on hover.
+ */
+/**
+ * @typedef {Object} TruncateController
+ * @property {() => boolean} update Re-measures and returns whether the text is currently cut off.
+ * @property {() => boolean} isTruncated Whether the text was cut off at the last measurement.
+ * @property {() => void} destroy Removes the classes, the observer, and any title this set.
+ */
+/**
+ * Clamps an element's text to a number of lines, and gives the cut-off text back on hover.
+ *
+ * The `title` half is what makes this more than a CSS class. A table cell that silently drops the
+ * end of a value is a data-loss bug wearing a layout costume; a tooltip that is always present is
+ * noise. Measuring on every resize means the tooltip appears exactly when the text is short of
+ * room and disappears when the column is widened.
+ *
+ * @param {Element|string} target Element or selector to clamp.
+ * @param {TruncateOptions} [options={}] Truncation options.
+ * @returns {TruncateController}
+ */
+export declare function truncate(target: Element | string, options?: TruncateOptions): TruncateController;
+/**
+ * Whether an element's text overflows the box it is in.
+ *
+ * Both axes are checked because the two clamping modes overflow differently: a single line runs
+ * out of width, a multi-line clamp runs out of height. The one-pixel tolerance absorbs the
+ * sub-pixel difference between scroll and client sizes that fractional zoom levels produce.
+ *
+ * @param {Element} element Element to measure.
+ * @returns {boolean}
+ */
+export declare function isTruncated(element: Element): boolean;

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

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

package/dist/types/components/value-list/value-list.d.ts

@@ -0,0 +1,143 @@
+import { Component } from '../../core/component.js';
+export type ValueListOptions = {
+    /**
+     * Initial ordered values.
+     */
+    values?: unknown[];
+    /**
+     * Input placeholder.
+     */
+    placeholder?: string;
+    /**
+     * Whether values can be removed.
+     */
+    deletable?: boolean;
+    /**
+     * Whether values can be reordered.
+     */
+    sortable?: boolean;
+    /**
+     * Whether duplicate strings are rejected.
+     */
+    unique?: boolean;
+    /**
+     * Value validator.
+     */
+    validate?: ((value: string) => boolean | string) | null;
+};
+/**
+ * @typedef {Object} ValueListOptions
+ * @property {unknown[]} [values=[]] Initial ordered values.
+ * @property {string} [placeholder=''] Input placeholder.
+ * @property {boolean} [deletable=true] Whether values can be removed.
+ * @property {boolean} [sortable=true] Whether values can be reordered.
+ * @property {boolean} [unique=true] Whether duplicate strings are rejected.
+ * @property {((value: string) => boolean|string)|null} [validate=null] Value validator.
+ */
+/**
+ * Tag/chip editor. It uses the APG listbox/option focus model: each chip is an option, arrow keys
+ * move focus, Ctrl+Left/Right reorders, and Delete/Backspace removes the focused option.
+ * @fires ValueList#change
+ * @fires ValueList#add
+ * @fires ValueList#remove
+ * @extends {Component<ValueListOptions>}
+ */
+export declare class ValueList extends Component<ValueListOptions> {
+    _ownedNodes: any[];
+    _disabled: boolean;
+    _dragIndex: number;
+    _initialState: string;
+    _initialDisabled: string;
+    _values: string[];
+    _list: HTMLElement;
+    _input: HTMLElement;
+    _status: HTMLElement;
+    _instructions: HTMLElement;
+    static cssName: string;
+    /** @type {ValueListOptions} */
+    static defaults: ValueListOptions;
+    /** @returns {HTMLElement} */
+    render(): HTMLElement;
+    /**
+     * Returns a copy of the ordered values.
+     * @returns {string[]}
+     */
+    getValues(): string[];
+    /**
+     * Replaces all values.
+     * @param {unknown[]} values New values.
+     * @param {{silent?: boolean}} [options={}] Set `silent` to suppress `change`.
+     * @returns {this}
+     */
+    setValues(values: unknown[], { silent }?: {
+        silent?: boolean;
+    }): this;
+    /**
+     * Validates and appends one value.
+     * @param {unknown} value Value to append.
+     * @returns {boolean} Whether the value was added.
+     * @fires ValueList#add
+     * @fires ValueList#change
+     */
+    addValue(value: unknown): boolean;
+    /**
+     * Removes the first matching value.
+     * @param {unknown} value Value to remove.
+     * @returns {boolean} Whether a value was removed.
+     * @fires ValueList#remove
+     * @fires ValueList#change
+     */
+    removeValue(value: unknown): boolean;
+    /**
+     * Focuses the value input.
+     * @returns {this}
+     */
+    focus(): this;
+    /**
+     * Enables editing.
+     * @returns {this}
+     */
+    enable(): this;
+    /**
+     * Disables editing, removal, and reordering.
+     * @returns {this}
+     */
+    disable(): this;
+    /** @returns {void} */
+    _renderChips(focusIndex?: number): void;
+    /** @param {KeyboardEvent} event @returns {void} */
+    _handleInputKeydown(event: KeyboardEvent): void;
+    /** @param {KeyboardEvent} event @returns {void} */
+    _handleChipKeydown(event: KeyboardEvent): void;
+    /** @param {MouseEvent} event @returns {void} */
+    _handleChipClick(event: MouseEvent): void;
+    /** @param {DragEvent} event @returns {void} */
+    _handleDragStart(event: DragEvent): void;
+    /** @param {DragEvent} event @returns {void} */
+    _handleDrop(event: DragEvent): void;
+    /** @returns {void} */
+    _finishDrag(): void;
+    /** @param {number} start @param {number} end @param {boolean} focus @returns {void} */
+    _move(start: number, end: number, focus: boolean): void;
+    /** @param {number} index @param {number} [focusIndex=-1] @returns {void} */
+    _removeAt(index: number, focusIndex?: number): void;
+    /** @param {string} message @returns {void} */
+    _showError(message: string): void;
+    /** @returns {void} */
+    destroy(): void;
+}
+/**
+ * Values changed event.
+ * @event ValueList#change
+ * @type {CustomEvent<{values: string[]}>
+ */
+/**
+ * Value added event.
+ * @event ValueList#add
+ * @type {CustomEvent<{value: string}>
+ */
+/**
+ * Value removed event.
+ * @event ValueList#remove
+ * @type {CustomEvent<{value: string}>
+ */

package/dist/types/core/breakpoint.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Named width thresholds, and a way to react to one being crossed.
+ *
+ * The scale lives here rather than in the token layer because a CSS custom property cannot be
+ * used inside a media query, so a `--zx-bp-*` token would be a value no stylesheet could read.
+ * Zx's own layout utilities avoid the problem entirely — `.zx-grid` reflows on intrinsic track
+ * widths, not on breakpoints — which leaves this module for the cases only script can decide:
+ * rendering a Table as cards below a width, collapsing a MasterPanel, choosing a chart density.
+ * @module zx/core/breakpoint
+ */
+export type BreakpointName = 'xs' | 'sm' | 'md' | 'lg' | 'xl';
+/** @typedef {'xs'|'sm'|'md'|'lg'|'xl'} BreakpointName */
+/**
+ * Lower bound of each named breakpoint, in pixels. A width below `sm` is `xs`.
+ * @type {Readonly<Record<Exclude<BreakpointName, 'xs'>, number>>}
+ */
+export declare const breakpoints: Readonly<Record<Exclude<BreakpointName, 'xs'>, number>>;
+/**
+ * The breakpoint a width falls into.
+ * @param {number} width Width in pixels.
+ * @returns {BreakpointName}
+ */
+export declare function breakpointOf(width: number): BreakpointName;
+/**
+ * Whether a width has reached a named breakpoint. `matchBreakpoint('md', 900)` is the script
+ * equivalent of `@media (min-width: 768px)`.
+ * @param {BreakpointName} name Breakpoint to test against.
+ * @param {number} width Width in pixels.
+ * @returns {boolean}
+ */
+export declare function matchBreakpoint(name: BreakpointName, width: number): boolean;
+export type BreakpointOptions = {
+    /**
+     * What to measure. An Element is watched with a
+     * `ResizeObserver`, which is what a component inside a split pane or a modal needs — the
+     * viewport width says nothing about the space it actually has.
+     */
+    target?: Element | Window;
+};
+export type BreakpointController = {
+    /**
+     * The breakpoint as last measured.
+     */
+    current: () => BreakpointName;
+    /**
+     * Stops observing.
+     */
+    destroy: () => void;
+};
+/**
+ * @typedef {Object} BreakpointOptions
+ * @property {Element|Window} [target=window] What to measure. An Element is watched with a
+ *   `ResizeObserver`, which is what a component inside a split pane or a modal needs — the
+ *   viewport width says nothing about the space it actually has.
+ */
+/**
+ * @typedef {Object} BreakpointController
+ * @property {() => BreakpointName} current The breakpoint as last measured.
+ * @property {() => void} destroy Stops observing.
+ */
+/**
+ * Calls back whenever the observed width crosses into another breakpoint, and once immediately
+ * with the current one.
+ * @param {(name: BreakpointName, width: number) => void} handler Called on every change.
+ * @param {BreakpointOptions} [options={}] What to observe.
+ * @returns {BreakpointController}
+ */
+export declare function onBreakpoint(handler: (name: BreakpointName, width: number) => void, options?: BreakpointOptions): BreakpointController;