@zeyos/zx 2.1.0 → 2.2.1

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

@@ -0,0 +1,230 @@
+import { Component } from '../../core/component.js';
+export type ToolbarItemDescriptor = {
+    /**
+     * Identifier for `getItem()`, `enable()`, `disable()`, and `setActive()`.
+     */
+    name?: string;
+    /**
+     * Visible button label.
+     */
+    label?: string;
+    /**
+     * Icon name from `icons.js`.
+     */
+    icon?: string;
+    /**
+     * Button kind.
+     */
+    kind?: 'default' | 'primary' | 'danger' | 'ghost';
+    /**
+     * Button size; defaults to `'sm'` in a dense toolbar.
+     */
+    size?: 'md' | 'sm';
+    /**
+     * Whether the control starts disabled.
+     */
+    disabled?: boolean;
+    /**
+     * Native title text.
+     */
+    title?: string;
+    /**
+     * Renders the button as a pressed toggle (`aria-pressed`).
+     */
+    active?: boolean;
+    /**
+     * Click callback, called after the `action` event.
+     */
+    onclick?: (event: MouseEvent) => void;
+};
+export type ToolbarItem = Element | ToolbarItemDescriptor | '-';
+export type ToolbarEntry = {
+    type: 'separator';
+} | {
+    type: 'element';
+    element: Element;
+} | {
+    type: 'descriptor';
+    descriptor: ToolbarItemDescriptor;
+};
+export type ToolbarOptions = {
+    /**
+     * Controls, separators (`'-'`), and ready-made Elements.
+     */
+    items?: ToolbarItem[];
+    /**
+     * Horizontal distribution.
+     */
+    align?: 'start' | 'end' | 'between';
+    /**
+     * Accessible name of the toolbar.
+     */
+    label?: string;
+    /**
+     * Collapses items that no longer fit into a trailing menu.
+     */
+    overflow?: boolean;
+    /**
+     * Accessible name of the overflow menu trigger.
+     */
+    overflowLabel?: string;
+    /**
+     * Tighter spacing and small controls.
+     */
+    dense?: boolean;
+    /**
+     * Action listener.
+     */
+    onaction?: (event: CustomEvent<{
+        name: string | null;
+        item: Element;
+    }>) => void;
+};
+/**
+ * @typedef {Object} ToolbarItemDescriptor
+ * @property {string} [name] Identifier for `getItem()`, `enable()`, `disable()`, and `setActive()`.
+ * @property {string} [label] Visible button label.
+ * @property {string} [icon] Icon name from `icons.js`.
+ * @property {'default'|'primary'|'danger'|'ghost'} [kind='default'] Button kind.
+ * @property {'md'|'sm'} [size] Button size; defaults to `'sm'` in a dense toolbar.
+ * @property {boolean} [disabled=false] Whether the control starts disabled.
+ * @property {string} [title] Native title text.
+ * @property {boolean} [active=false] Renders the button as a pressed toggle (`aria-pressed`).
+ * @property {(event: MouseEvent) => void} [onclick] Click callback, called after the `action` event.
+ */
+/** @typedef {Element|ToolbarItemDescriptor|'-'} ToolbarItem */
+/**
+ * @typedef {{type: 'separator'}
+ *   |{type: 'element', element: Element}
+ *   |{type: 'descriptor', descriptor: ToolbarItemDescriptor}} ToolbarEntry
+ */
+/**
+ * @typedef {Object} ToolbarOptions
+ * @property {ToolbarItem[]} [items=[]] Controls, separators (`'-'`), and ready-made Elements.
+ * @property {'start'|'end'|'between'} [align='start'] Horizontal distribution.
+ * @property {string} [label='Toolbar'] Accessible name of the toolbar.
+ * @property {boolean} [overflow=true] Collapses items that no longer fit into a trailing menu.
+ * @property {string} [overflowLabel='More'] Accessible name of the overflow menu trigger.
+ * @property {boolean} [dense=false] Tighter spacing and small controls.
+ * @property {(event: CustomEvent<{name: string|null, item: Element}>) => void} [onaction] Action listener.
+ */
+/**
+ * APG toolbar: one tab stop, arrow keys between controls, Home and End to the ends, and an
+ * optional overflow menu that swallows the items that no longer fit.
+ * @fires Toolbar#action
+ * @extends {Component<ToolbarOptions>}
+ */
+export declare class Toolbar extends Component<ToolbarOptions> {
+    #private;
+    /** @type {ToolbarRecord[]} */
+    _records: ToolbarRecord[];
+    /** @type {Map<string, ToolbarRecord>} */
+    _named: Map<string, ToolbarRecord>;
+    _createdRoot: boolean;
+    _snapshot: import("../../core/dom.js").TargetSnapshot;
+    _initialItems: ToolbarItem[];
+    static cssName: string;
+    /** @type {Readonly<ToolbarOptions>} */
+    static defaults: Readonly<ToolbarOptions>;
+    /**
+     * Creates a toolbar, or turns an existing element into one.
+     * @param {Element|string|null} [target=null] Existing container, selector, or null to create one.
+     * @param {ToolbarOptions} [options={}] Toolbar options.
+     */
+    constructor(target?: Element | string | null, options?: ToolbarOptions);
+    /**
+     * Prepares the toolbar root. Instance state is initialized here because `render()` runs inside
+     * the base constructor, before any class-field initializer.
+     * @returns {HTMLElement}
+     */
+    render(): HTMLElement;
+    /**
+     * Replaces every item and remeasures the overflow.
+     * @param {ToolbarItem[]} list Controls, separators, and Elements.
+     * @returns {this}
+     */
+    setItems(list: ToolbarItem[]): this;
+    /**
+     * Looks up an item element by name.
+     * @param {string} name Descriptor name, or the `data-name` of an Element item.
+     * @returns {Element|null}
+     */
+    getItem(name: string): Element | null;
+    /**
+     * Enables an item.
+     * @param {string} name Item name.
+     * @returns {this}
+     */
+    enable(name: string): this;
+    /**
+     * Disables an item.
+     * @param {string} name Item name.
+     * @returns {this}
+     */
+    disable(name: string): this;
+    /**
+     * Sets the pressed state of a toggle item.
+     * @param {string} name Item name.
+     * @param {boolean} [active=true] Whether the item reads as pressed.
+     * @returns {this}
+     */
+    setActive(name: string, active?: boolean): this;
+    /**
+     * Removes listeners, the resize observer, the overflow menu, and any DOM changes made to an
+     * adopted target.
+     * @returns {void}
+     */
+    destroy(): void;
+}
+export type ToolbarRecord = {
+    /**
+     * Entry kind.
+     */
+    type: 'separator' | 'element' | 'descriptor';
+    /**
+     * Rendered element.
+     */
+    element: Element;
+    /**
+     * Lookup name.
+     */
+    name: string | null;
+    /**
+     * Label mirrored into the overflow menu.
+     */
+    label: string;
+    /**
+     * Icon name mirrored into the overflow menu.
+     */
+    icon: string | null;
+    /**
+     * Descriptor callback.
+     */
+    onclick: ((event: MouseEvent) => void) | null;
+    /**
+     * Whether the caller handed the item over already hidden.
+     */
+    userHidden: boolean;
+};
+/**
+ * Emitted when a descriptor-built item is activated, from the toolbar or from the overflow menu.
+ * @event Toolbar#action
+ * @type {CustomEvent<{name: string|null, item: Element}>}
+ */
+/**
+ * @typedef {Object} ToolbarRecord
+ * @property {'separator'|'element'|'descriptor'} type Entry kind.
+ * @property {Element} element Rendered element.
+ * @property {string|null} name Lookup name.
+ * @property {string} label Label mirrored into the overflow menu.
+ * @property {string|null} icon Icon name mirrored into the overflow menu.
+ * @property {((event: MouseEvent) => void)|null} onclick Descriptor callback.
+ * @property {boolean} userHidden Whether the caller handed the item over already hidden.
+ */
+/**
+ * Normalizes a raw item list: drops nullish entries, classifies each item, and collapses leading,
+ * trailing, and repeated separators. Pure — it touches no DOM.
+ * @param {ToolbarItem[]} list Raw item list.
+ * @returns {ToolbarEntry[]}
+ */
+export declare function normalizeItems(list: ToolbarItem[]): ToolbarEntry[];

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

@@ -0,0 +1,183 @@
+import { Component } from '../../core/component.js';
+export type TooltipContentValue = string | number | Node | {
+    toElement: () => Node | null;
+} | null;
+export type TooltipContent = TooltipContentValue | (() => TooltipContentValue);
+export type TooltipOptions = {
+    /**
+     * Bubble content, re-evaluated on each open when a function.
+     */
+    content?: TooltipContent;
+    /**
+     * Preferred side; flips when it would overflow.
+     */
+    placement?: 'top' | 'bottom' | 'top-start' | 'top-end' | 'bottom-start' | 'bottom-end';
+    /**
+     * Gap between anchor and bubble in pixels.
+     */
+    offset?: number;
+    /**
+     * Delay before a hover opens the tooltip, in milliseconds.
+     */
+    delay?: number;
+    /**
+     * Delay before a leave or blur closes it, in milliseconds.
+     */
+    hideDelay?: number;
+    /**
+     * Maximum bubble width; a number is pixels, a string is any CSS length.
+     */
+    maxWidth?: number | string;
+    /**
+     * Which interactions open the tooltip.
+     */
+    trigger?: 'hover' | 'focus' | 'both' | 'manual';
+    /**
+     * Whether the tooltip starts suppressed.
+     */
+    disabled?: boolean;
+    /**
+     * Open event listener.
+     */
+    onopen?: (event: CustomEvent<Record<string, never>>) => void;
+    /**
+     * Close event listener.
+     */
+    onclose?: (event: CustomEvent<Record<string, never>>) => void;
+};
+/**
+ * @typedef {string|number|Node|{toElement: () => Node|null}|null} TooltipContentValue
+ * A value the tooltip can render: text, a node, or anything exposing `toElement()`.
+ */
+/**
+ * @typedef {TooltipContentValue|(() => TooltipContentValue)} TooltipContent
+ * Tooltip content, or a function returning it. A function is called on every open, so a tooltip
+ * can describe state that changes between hovers.
+ */
+/**
+ * @typedef {Object} TooltipOptions
+ * @property {TooltipContent} [content=''] Bubble content, re-evaluated on each open when a function.
+ * @property {'top'|'bottom'|'top-start'|'top-end'|'bottom-start'|'bottom-end'} [placement='top'] Preferred side; flips when it would overflow.
+ * @property {number} [offset=6] Gap between anchor and bubble in pixels.
+ * @property {number} [delay=400] Delay before a hover opens the tooltip, in milliseconds.
+ * @property {number} [hideDelay=80] Delay before a leave or blur closes it, in milliseconds.
+ * @property {number|string} [maxWidth=260] Maximum bubble width; a number is pixels, a string is any CSS length.
+ * @property {'hover'|'focus'|'both'|'manual'} [trigger='both'] Which interactions open the tooltip.
+ * @property {boolean} [disabled=false] Whether the tooltip starts suppressed.
+ * @property {(event: CustomEvent<Record<string, never>>) => void} [onopen] Open event listener.
+ * @property {(event: CustomEvent<Record<string, never>>) => void} [onclose] Close event listener.
+ */
+/**
+ * A non-interactive description bubble anchored to another element.
+ *
+ * The bubble is a manual popover in the top layer, positioned by `position()` from the kernel, so
+ * it escapes clipping and stacking contexts and flips near a viewport edge. It never takes focus
+ * and never receives pointer events: it describes the anchor rather than adding a target of its
+ * own. While open, the anchor carries `aria-describedby` pointing at the bubble; closing restores
+ * whatever the anchor had before — including nothing at all.
+ *
+ * A hover opens it after `delay`; keyboard focus opens it at once, because a keyboard user has no
+ * way to "hover a little longer". Touch never opens it: a bubble that cannot be dismissed by
+ * moving the pointer away would simply stick, so touch pointers are ignored and the anchor is left
+ * to its own label.
+ * @fires Tooltip#open
+ * @fires Tooltip#close
+ * @extends {Component<TooltipOptions>}
+ */
+export declare class Tooltip extends Component<TooltipOptions> {
+    #private;
+    static cssName: string;
+    /** @type {Readonly<TooltipOptions>} */
+    static defaults: Readonly<TooltipOptions>;
+    /**
+     * Attaches a tooltip to an existing element.
+     * @param {Element|string} anchor Anchor element or selector.
+     * @param {TooltipOptions} [options={}] Tooltip options.
+     */
+    constructor(anchor: Element | string, options?: TooltipOptions);
+    /**
+     * Creates the owned bubble. Runs inside the base constructor, so it touches nothing but the DOM.
+     * @returns {HTMLElement}
+     */
+    render(): HTMLElement;
+    /**
+     * Opens the tooltip, evaluating the content first. Does nothing while disabled, already open, or
+     * when the content resolves to nothing.
+     * @returns {this}
+     * @fires Tooltip#open
+     */
+    show(): this;
+    /**
+     * Closes the tooltip and restores the anchor's original `aria-describedby`.
+     * @returns {this}
+     * @fires Tooltip#close
+     */
+    hide(): this;
+    /**
+     * Opens a closed tooltip, closes an open one.
+     * @returns {this}
+     */
+    toggle(): this;
+    /**
+     * Reports whether the bubble is currently visible.
+     * @returns {boolean}
+     */
+    isOpen(): boolean;
+    /**
+     * Replaces the content. Strings are never parsed as HTML. A function is stored, not called, and
+     * runs on every subsequent open.
+     * @param {TooltipContent} content Next content.
+     * @returns {this}
+     */
+    setContent(content: TooltipContent): this;
+    /**
+     * Allows the tooltip to open again.
+     * @returns {this}
+     */
+    enable(): this;
+    /**
+     * Suppresses the tooltip and closes it if it is open.
+     * @returns {this}
+     */
+    disable(): this;
+    /**
+     * Reports whether the tooltip is currently suppressed.
+     * @returns {boolean}
+     */
+    isDisabled(): boolean;
+    /**
+     * Returns the anchor the tooltip describes.
+     * @returns {Element}
+     */
+    getAnchor(): Element;
+    /**
+     * Closes the tooltip, removes the bubble, and puts the anchor's ARIA back as it was found.
+     * @returns {void}
+     */
+    destroy(): void;
+}
+/**
+ * Fired when the bubble becomes visible. Never fired for a `show()` on an open tooltip.
+ * @event Tooltip#open
+ * @type {CustomEvent<Record<string, never>>}
+ */
+/**
+ * Fired when the bubble is hidden. Never fired for a `hide()` on a closed tooltip.
+ * @event Tooltip#close
+ * @type {CustomEvent<Record<string, never>>}
+ */
+/**
+ * Creates a tooltip from either a content value or a full option object.
+ * @param {Element|string} anchor Anchor element or selector.
+ * @param {TooltipContent|TooltipOptions} [contentOrOptions=''] Content, or tooltip options.
+ * @returns {Tooltip}
+ */
+export declare function tooltip(anchor: Element | string, contentOrOptions?: TooltipContent | TooltipOptions): Tooltip;
+/**
+ * Attaches a plain-text tooltip with every default in place — the one-liner replacement for a
+ * `title` attribute.
+ * @param {Element|string} anchor Anchor element or selector.
+ * @param {string} text Description text, inserted as a text node.
+ * @returns {Tooltip}
+ */
+export declare function describe(anchor: Element | string, text: string): Tooltip;

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

@@ -0,0 +1,113 @@
+/**
+ * Shared helpers for the hierarchical components (`TreeView` and `Finder`). Both take the same
+ * nested node shape and the same `valueKey` / `labelKey` / `childrenKey` readers, so the reading
+ * and walking logic lives here once.
+ * @module
+ */
+export type TreeNode = Record<string, any>;
+export type NodeReader = string | ((node: TreeNode) => unknown);
+export type NodeReaders = {
+    /**
+     * Node ID.
+     */
+    value: (node: TreeNode) => unknown;
+    /**
+     * Node label.
+     */
+    label: (node: TreeNode) => string;
+    /**
+     * Loaded children, or null when unknown.
+     */
+    children: (node: TreeNode) => TreeNode[] | null;
+};
+/** @typedef {Record<string, any>} TreeNode */
+/** @typedef {string|((node: TreeNode) => unknown)} NodeReader */
+/**
+ * @typedef {Object} NodeReaders
+ * @property {(node: TreeNode) => unknown} value Node ID.
+ * @property {(node: TreeNode) => string} label Node label.
+ * @property {(node: TreeNode) => TreeNode[]|null} children Loaded children, or null when unknown.
+ */
+/**
+ * Builds reader functions for one component's key configuration.
+ * @param {{valueKey?: NodeReader, labelKey?: NodeReader, childrenKey?: string}} options Key configuration.
+ * @returns {NodeReaders}
+ */
+export declare function createReaders({ valueKey, labelKey, childrenKey }?: {
+    valueKey?: NodeReader;
+    labelKey?: NodeReader;
+    childrenKey?: string;
+}): NodeReaders;
+/**
+ * Reports whether a node can have children: it already has some, or it is explicitly marked as a
+ * branch whose children have not been loaded yet.
+ * @param {TreeNode} node Node to inspect.
+ * @param {NodeReaders} readers Node readers.
+ * @returns {boolean}
+ */
+export declare function isBranch(node: TreeNode, readers: NodeReaders): boolean;
+/**
+ * Depth-first walk over every node, deepest last.
+ * @param {TreeNode[]} nodes Root nodes.
+ * @param {NodeReaders} readers Node readers.
+ * @param {(node: TreeNode, context: {level: number, parent: TreeNode|null, index: number, siblings: TreeNode[]}) => void} visit Visitor.
+ * @param {{level?: number, parent?: TreeNode|null}} [context={}] Starting context.
+ * @returns {void}
+ */
+export declare function walk(nodes: TreeNode[], readers: NodeReaders, visit: (node: TreeNode, context: {
+    level: number;
+    parent: TreeNode | null;
+    index: number;
+    siblings: TreeNode[];
+}) => void, { level, parent }?: {
+    level?: number;
+    parent?: TreeNode | null;
+}): void;
+/**
+ * Finds a node by ID anywhere in the tree.
+ * @param {TreeNode[]} nodes Root nodes.
+ * @param {unknown} id Node ID.
+ * @param {NodeReaders} readers Node readers.
+ * @returns {TreeNode|null}
+ */
+export declare function findNode(nodes: TreeNode[], id: unknown, readers: NodeReaders): TreeNode | null;
+/**
+ * Returns the chain of nodes from a root down to the node with the given ID, inclusive.
+ * @param {TreeNode[]} nodes Root nodes.
+ * @param {unknown} id Node ID.
+ * @param {NodeReaders} readers Node readers.
+ * @returns {TreeNode[]} Empty when the ID is not in the tree.
+ */
+export declare function pathTo(nodes: TreeNode[], id: unknown, readers: NodeReaders): TreeNode[];
+/**
+ * Returns every descendant of a node, excluding the node itself.
+ * @param {TreeNode} node Root of the sub-tree.
+ * @param {NodeReaders} readers Node readers.
+ * @returns {TreeNode[]}
+ */
+export declare function descendants(node: TreeNode, readers: NodeReaders): TreeNode[];
+/**
+ * Flattens the tree to the rows a tree view currently shows: every root, plus the children of
+ * every expanded branch. The returned rows carry the ARIA bookkeeping each row needs.
+ * @param {TreeNode[]} nodes Root nodes.
+ * @param {NodeReaders} readers Node readers.
+ * @param {Set<unknown>} expanded IDs of expanded branches.
+ * @returns {{node: TreeNode, id: unknown, level: number, parent: TreeNode|null, posinset: number, setsize: number}[]}
+ */
+export declare function flattenVisible(nodes: TreeNode[], readers: NodeReaders, expanded: Set<unknown>): {
+    node: TreeNode;
+    id: unknown;
+    level: number;
+    parent: TreeNode | null;
+    posinset: number;
+    setsize: number;
+}[];
+/**
+ * Filters a tree to the nodes matching a predicate, keeping the ancestors that lead to a match.
+ * @param {TreeNode[]} nodes Root nodes.
+ * @param {NodeReaders} readers Node readers.
+ * @param {(node: TreeNode) => boolean} matches Predicate.
+ * @param {string} childrenKey Property the filtered children are written to.
+ * @returns {TreeNode[]} New nodes; the originals are not mutated.
+ */
+export declare function filterTree(nodes: TreeNode[], readers: NodeReaders, matches: (node: TreeNode) => boolean, childrenKey: string): TreeNode[];