@zeyos/zx 2.1.0 → 2.2.0

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

@@ -0,0 +1,200 @@
+import { Component } from '../../core/component.js';
+import { MenuButton } from '../menu-button/menu-button.js';
+export type BreadcrumbSeparator = 'chevron' | 'slash';
+export type BreadcrumbItem = {
+    /**
+     * Stable item name, unique within the trail.
+     */
+    name: string;
+    /**
+     * Visible label.
+     */
+    label: string;
+    /**
+     * Icon name passed to `icon()`, rendered before the label.
+     */
+    icon?: string;
+    /**
+     * Link destination; items without one render as buttons.
+     */
+    href?: string;
+};
+export type NormalizedBreadcrumbItem = {
+    /**
+     * Stable item name.
+     */
+    name: string;
+    /**
+     * Visible label.
+     */
+    label: string;
+    /**
+     * Icon name, or null.
+     */
+    icon: string | null;
+    /**
+     * Link destination, or null.
+     */
+    href: string | null;
+};
+export type BreadcrumbOptions = {
+    /**
+     * Trail from the root to the current page.
+     */
+    items?: BreadcrumbItem[];
+    /**
+     * Number of items rendered inline; 0 renders all of them.
+     * Anything in between collapses into an ellipsis menu, always keeping the first and last item.
+     * Values below 2 behave as 2.
+     */
+    maxVisible?: number;
+    /**
+     * Glyph drawn between items.
+     */
+    separator?: BreadcrumbSeparator;
+    /**
+     * Icon for the first item when it carries none itself.
+     */
+    rootIcon?: string | null;
+    /**
+     * Localized messages.
+     */
+    msg?: Record<string, string> | Record<string, Record<string, string>>;
+    /**
+     * Selection listener.
+     */
+    onselect?: (event: CustomEvent<BreadcrumbSelectDetail>) => void;
+};
+export type BreadcrumbSelectDetail = {
+    /**
+     * Selected item name.
+     */
+    name: string;
+    /**
+     * Copy of the selected item.
+     */
+    item: NormalizedBreadcrumbItem;
+    /**
+     * Zero-based index in the full trail, collapsed items included.
+     */
+    index: number;
+};
+/**
+ * The trail of ancestors above the current page. Pairs with {@link Finder} and {@link TreeView}:
+ * feed `setItems()` from a `change` event's `nodes`, and turn a `select` back into a path.
+ *
+ * The last item is the page you are on, so it is plain text marked `aria-current="page"` and never
+ * interactive. Every other item is a real `<a>` when it carries an `href` — its navigation is left
+ * alone — and a `<button>` otherwise, for trails an application resolves in JavaScript.
+ * @fires Breadcrumb#select
+ * @extends {Component<BreadcrumbOptions>}
+ */
+export declare class Breadcrumb extends Component<BreadcrumbOptions> {
+    _createdRoot: boolean;
+    _snapshot: import("../../core/dom.js").TargetSnapshot;
+    _destroyed: boolean;
+    /** @type {NormalizedBreadcrumbItem[]} */
+    _items: NormalizedBreadcrumbItem[];
+    /** @type {MenuButton|null} */
+    _overflow: MenuButton | null;
+    static cssName: string;
+    /** @type {Readonly<BreadcrumbOptions>} */
+    static defaults: Readonly<BreadcrumbOptions>;
+    /**
+     * Creates or enhances a breadcrumb trail.
+     * @param {Element|string|null} target Existing container, selector, or null.
+     * @param {BreadcrumbOptions} [options={}] Breadcrumb options.
+     */
+    constructor(target: Element | string | null, options?: BreadcrumbOptions);
+    /**
+     * Builds the trail. Runs inside the base constructor, so instance state is initialized here.
+     * @returns {HTMLElement}
+     */
+    render(): HTMLElement;
+    /**
+     * Replaces the whole trail.
+     * @param {BreadcrumbItem[]} list Items from the root to the current page.
+     * @returns {this}
+     * @throws {TypeError} When the list or an item is malformed.
+     * @throws {RangeError} When two items share a name.
+     */
+    setItems(list: BreadcrumbItem[]): this;
+    /**
+     * Returns a copy of the trail.
+     * @returns {NormalizedBreadcrumbItem[]}
+     */
+    getItems(): NormalizedBreadcrumbItem[];
+    /**
+     * Appends one level, which becomes the current page.
+     * @param {BreadcrumbItem} item Item to append.
+     * @returns {this}
+     */
+    push(item: BreadcrumbItem): this;
+    /**
+     * Removes the deepest level.
+     * @returns {NormalizedBreadcrumbItem|null} The removed item, or null when the trail was empty.
+     */
+    pop(): NormalizedBreadcrumbItem | null;
+    /**
+     * Drops every level below a named item, making it the current page.
+     * @param {string} name Item name.
+     * @returns {this}
+     * @throws {RangeError} When no item carries that name.
+     */
+    truncateTo(name: string): this;
+    /**
+     * Destroys the overflow menu, aborts listeners, and restores an enhanced target.
+     * @returns {void}
+     */
+    destroy(): void;
+    /**
+     * Rebuilds the list from the current items.
+     * @returns {void}
+     */
+    _build(): void;
+    /**
+     * Splits the trail into the inline head, the collapsed middle, and the inline tail.
+     * @returns {{head: NormalizedBreadcrumbItem[], hidden: NormalizedBreadcrumbItem[], tail: NormalizedBreadcrumbItem[]}}
+     */
+    _split(): {
+        head: NormalizedBreadcrumbItem[];
+        hidden: NormalizedBreadcrumbItem[];
+        tail: NormalizedBreadcrumbItem[];
+    };
+    /**
+     * @param {NormalizedBreadcrumbItem} item Item to render.
+     * @param {boolean} current Whether this is the page the user is on.
+     * @returns {HTMLElement}
+     */
+    _renderItem(item: NormalizedBreadcrumbItem, current: boolean): HTMLElement;
+    /**
+     * Renders (and, on first use, creates) the ellipsis menu holding the collapsed levels. The
+     * MenuButton is kept for the component's lifetime because its dropdown panel lives on
+     * `document.body`; rebuilding the trail only refills its items.
+     * @param {NormalizedBreadcrumbItem[]} hidden Collapsed items.
+     * @returns {HTMLElement}
+     */
+    _renderOverflow(hidden: NormalizedBreadcrumbItem[]): HTMLElement;
+    /** @returns {HTMLElement} */
+    _renderSeparator(): HTMLElement;
+    /**
+     * @param {string|undefined} name Item name from a control's `data-crumb`.
+     * @returns {void}
+     * @fires Breadcrumb#select
+     */
+    _select(name: string | undefined): void;
+    /**
+     * Resolves a message through the host translator, falling back to the built-in English text.
+     * @param {string} key Message key.
+     * @param {string} fallback Built-in text, with `%1`-style placeholders.
+     * @param {...unknown} args Interpolation values.
+     * @returns {string}
+     */
+    _message(key: string, fallback: string, ...args: unknown[]): string;
+}
+/**
+ * Fired when an interactive crumb is chosen, from the trail itself or from the overflow menu. A
+ * crumb with an `href` still navigates: the event reports the choice, it does not gate it.
+ * @event Breadcrumb#select
+ * @type {CustomEvent<BreadcrumbSelectDetail>}
+ */

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

@@ -0,0 +1,42 @@
+export type ButtonOptions = {
+    /**
+     * Visible button label.
+     */
+    label?: string;
+    /**
+     * Icon name from `icons.js`.
+     */
+    icon?: string | null;
+    /**
+     * Visual intent.
+     */
+    kind?: 'default' | 'primary' | 'danger' | 'ghost';
+    /**
+     * Control size.
+     */
+    size?: 'md' | 'sm';
+    /**
+     * Whether the button is disabled.
+     */
+    disabled?: boolean;
+    /**
+     * Native title text.
+     */
+    title?: string;
+    /**
+     * Click callback.
+     */
+    onclick?: (event: MouseEvent) => void;
+};
+/**
+ * Creates a styled native button.
+ * @param {ButtonOptions} [opts={}] Button options.
+ * @returns {HTMLButtonElement}
+ */
+export declare function button(opts?: ButtonOptions): HTMLButtonElement;
+/**
+ * Groups buttons into a joined control.
+ * @param {HTMLButtonElement[]} buttons Buttons to group.
+ * @returns {HTMLDivElement}
+ */
+export declare function buttonGroup(buttons: HTMLButtonElement[]): HTMLDivElement;

package/dist/types/components/check-button/check-button.d.ts

@@ -0,0 +1,98 @@
+import { Component } from '../../core/component.js';
+export type CheckButtonOptions = {
+    /**
+     * A shared label or `[onLabel, offLabel]`.
+     */
+    label?: string | [string, string];
+    /**
+     * Initial pressed state.
+     */
+    checked?: boolean;
+    /**
+     * Whether to show the check indicator.
+     */
+    icon?: boolean;
+    /**
+     * Initial disabled state.
+     */
+    disabled?: boolean;
+    /**
+     * Change callback.
+     */
+    onchange?: (event: CustomEvent<{
+        checked: boolean;
+    }>) => void;
+};
+/**
+ * @typedef {Object} CheckButtonOptions
+ * @property {string|[string, string]} [label=''] A shared label or `[onLabel, offLabel]`.
+ * @property {boolean} [checked=false] Initial pressed state.
+ * @property {boolean} [icon=true] Whether to show the check indicator.
+ * @property {boolean} [disabled=false] Initial disabled state.
+ * @property {(event: CustomEvent<{checked: boolean}>) => void} [onchange] Change callback.
+ */
+/**
+ * Two-state native press button.
+ * @fires CheckButton#change
+ * @extends {Component<CheckButtonOptions>}
+ */
+export declare class CheckButton extends Component<CheckButtonOptions> {
+    _createdRoot: boolean;
+    _original: {
+        attributes: [string, string][];
+        children: Node[];
+    };
+    _checked: any;
+    _disabled: boolean;
+    _labels: {
+        on: string;
+        off: string;
+    };
+    _cleaned: boolean;
+    static cssName: string;
+    /** @type {Readonly<CheckButtonOptions>} */
+    static defaults: Readonly<CheckButtonOptions>;
+    /** @returns {HTMLButtonElement} */
+    render(): HTMLButtonElement;
+    /**
+     * Returns the current pressed state.
+     * @returns {boolean}
+     */
+    get(): boolean;
+    /**
+     * Sets the pressed state.
+     * @param {boolean} checked Next state.
+     * @param {{silent?: boolean}} [options={}] Set `silent` to suppress `change`.
+     * @returns {this}
+     * @fires CheckButton#change
+     */
+    set(checked: boolean, { silent }?: {
+        silent?: boolean;
+    }): this;
+    /**
+     * Toggles the pressed state.
+     * @returns {this}
+     * @fires CheckButton#change
+     */
+    toggle(): this;
+    /**
+     * Replaces the state labels.
+     * @param {string|[string, string]} label A shared label or `[onLabel, offLabel]`.
+     * @returns {this}
+     */
+    setLabel(label: string | [string, string]): this;
+    /**
+     * Enables user interaction.
+     * @returns {this}
+     */
+    enable(): this;
+    /**
+     * Disables user interaction.
+     * @returns {this}
+     */
+    disable(): this;
+    /** @returns {void} */
+    destroy(): void;
+    /** @returns {void} */
+    _sync(): void;
+}

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

@@ -0,0 +1,143 @@
+import { Component } from '../../core/component.js';
+export type ChecklistItem = Record<string, any> | string | number | boolean | symbol | bigint | null | undefined;
+export type ChecklistOptions = {
+    /**
+     * Available checkbox items.
+     */
+    items?: ChecklistItem[];
+    /**
+     * Item ID property or reader.
+     */
+    valueKey?: string | ((item: ChecklistItem) => unknown);
+    /**
+     * Item label property or reader.
+     */
+    labelKey?: string | ((item: ChecklistItem) => string);
+    /**
+     * Initial checked-state property or reader.
+     */
+    checkedKey?: string | ((item: ChecklistItem) => unknown);
+    /**
+     * Whether the search field is shown.
+     */
+    search?: boolean;
+    /**
+     * Maximum list height in pixels.
+     */
+    height?: number;
+    /**
+     * Fallback initial checked state.
+     */
+    defaultChecked?: boolean;
+    /**
+     * Async item loader.
+     */
+    load?: (() => Promise<ChecklistItem[]> | ChecklistItem[]) | null;
+    /**
+     * Localized messages.
+     */
+    msg?: Record<string, string> | Record<string, Record<string, string>>;
+    /**
+     * Change listener.
+     */
+    onchange?: (event: CustomEvent<ChecklistChangeDetail>) => void;
+    /**
+     * Loaded listener.
+     */
+    onloaded?: (event: CustomEvent<ChecklistLoadedDetail>) => void;
+};
+export type ChecklistChangeDetail = {
+    values: unknown[];
+};
+export type ChecklistLoadedDetail = {
+    items: ChecklistItem[];
+};
+/** @typedef {Record<string, any>|string|number|boolean|symbol|bigint|null|undefined} ChecklistItem */
+/**
+ * @typedef {Object} ChecklistOptions
+ * @property {ChecklistItem[]} [items=[]] Available checkbox items.
+ * @property {string|((item: ChecklistItem) => unknown)} [valueKey='ID'] Item ID property or reader.
+ * @property {string|((item: ChecklistItem) => string)} [labelKey='name'] Item label property or reader.
+ * @property {string|((item: ChecklistItem) => unknown)} [checkedKey='on'] Initial checked-state property or reader.
+ * @property {boolean} [search=true] Whether the search field is shown.
+ * @property {number} [height=280] Maximum list height in pixels.
+ * @property {boolean} [defaultChecked=false] Fallback initial checked state.
+ * @property {(() => Promise<ChecklistItem[]>|ChecklistItem[])|null} [load=null] Async item loader.
+ * @property {Record<string, string>|Record<string, Record<string, string>>} [msg] Localized messages.
+ * @property {(event: CustomEvent<ChecklistChangeDetail>) => void} [onchange] Change listener.
+ * @property {(event: CustomEvent<ChecklistLoadedDetail>) => void} [onloaded] Loaded listener.
+ */
+/** @typedef {{values: unknown[]}} ChecklistChangeDetail */
+/** @typedef {{items: ChecklistItem[]}} ChecklistLoadedDetail */
+/**
+ * Searchable native-checkbox group.
+ *
+ * @fires Checklist#change
+ * @fires Checklist#loaded
+ * @extends {Component<ChecklistOptions>}
+ */
+export declare class Checklist extends Component<ChecklistOptions> {
+    _items: any[] | ChecklistItem[];
+    _visibleItems: any[];
+    _checked: Set<any> | Set<unknown>;
+    _query: string;
+    _loadSequence: number;
+    _createdRoot: boolean;
+    _active: boolean;
+    _originalChildren: any[] | ChildNode[];
+    _originalAttributes: Map<any, any>;
+    static cssName: string;
+    /** @type {ChecklistOptions} */
+    static defaults: ChecklistOptions;
+    /** @returns {HTMLElement} */
+    render(): HTMLElement;
+    /**
+     * Replaces items and derives checked state from `checkedKey` and `defaultChecked`.
+     * @param {ChecklistItem[]} items New items.
+     * @returns {this}
+     */
+    setItems(items: ChecklistItem[]): this;
+    /** Returns checked IDs in item order. @returns {unknown[]} */
+    getValues(): unknown[];
+    /**
+     * Replaces the checked IDs.
+     * @param {Iterable<unknown>|unknown[]} ids Checked item IDs.
+     * @returns {this}
+     * @fires Checklist#change
+     */
+    setValues(ids: Iterable<unknown> | unknown[]): this;
+    /** Checks every item. @returns {this} @fires Checklist#change */
+    checkAll(): this;
+    /** Unchecks every item. @returns {this} @fires Checklist#change */
+    uncheckAll(): this;
+    /**
+     * Filters visible items by label.
+     * @param {string} query Search text.
+     * @returns {this}
+     */
+    search(query: string): this;
+    /**
+     * Reloads items through the configured async loader.
+     * @returns {Promise<this>}
+     * @fires Checklist#loaded
+     */
+    reload(): Promise<this>;
+    /** Restores an enhanced target and invalidates pending loads. @returns {void} */
+    destroy(): void;
+    /** @param {ChecklistItem[]} items @returns {void} */
+    _replaceItems(items: ChecklistItem[]): void;
+    /** @returns {void} */
+    _renderItems(): void;
+    /** @param {Set<unknown>} next @returns {void} */
+    _replaceChecked(next: Set<unknown>): void;
+    /** @param {ChecklistItem} item @returns {unknown} */
+    _itemValue(item: ChecklistItem): unknown;
+    /** @param {ChecklistItem} item @returns {string} */
+    _itemLabel(item: ChecklistItem): string;
+    /** @param {ChecklistItem} item @returns {unknown} */
+    _initialChecked(item: ChecklistItem): unknown;
+    /** @param {ChecklistItem} item @param {string|((item: ChecklistItem) => unknown)} reader @returns {unknown} */
+    _read(item: ChecklistItem, reader: string | ((item: ChecklistItem) => unknown)): unknown;
+    /** @param {string} key @param {string} fallback @returns {string} */
+    _message(key: string, fallback: string): string;
+}

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

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

package/dist/types/components/context-menu/context-menu.d.ts

@@ -0,0 +1,130 @@
+import { Component } from '../../core/component.js';
+export type MenuItem = import('../menu-button/menu-button.js').MenuItem;
+export type ContextMenuEntry = MenuItem | '-';
+export type ContextMenuOptions = {
+    /**
+     * Menu
+     * items and `'-'` separators, or a function returning them for the element the menu is opening
+     * on — which is how a row menu disables the actions that row does not allow. Returning an empty
+     * array cancels the opening.
+     */
+    items?: ContextMenuEntry[] | ((context: Element | null) => ContextMenuEntry[]);
+    /**
+     * Restricts the menu to descendants matching this
+     * selector, and reports the matched element as the context of the selection. A table passes
+     * `'tbody tr'` here to get a per-row menu from one listener.
+     */
+    selector?: string | null;
+    /**
+     * Selection listener.
+     */
+    onselect?: (event: CustomEvent<{
+        value: unknown;
+        item: MenuItem;
+        context: Element | null;
+    }>) => void;
+    /**
+     * Open listener.
+     */
+    onopen?: (event: CustomEvent<{
+        context: Element | null;
+    }>) => void;
+    /**
+     * Close listener.
+     */
+    onclose?: (event: CustomEvent<Record<string, never>>) => void;
+};
+/**
+ * Right-click menu for a region, implementing the APG menu pattern.
+ *
+ * Attaches to an existing element and never changes it: the menu itself lives in the top layer,
+ * anchored to a zero-sized element parked at the pointer. `selector` turns one instance into a
+ * per-row menu — the listener stays on the container, and the row that was clicked arrives with
+ * the selection as `context`.
+ *
+ * Reachable from the keyboard as the platform expects: the Menu key or Shift+F10 opens the menu at
+ * the focused element, and closing returns focus to where it came from. Pointer-only context
+ * menus are a common accessibility failure, so both routes are wired here rather than left to the
+ * application.
+ *
+ * Note that the component's root is the anchor, which lives on `<body>` — so the bubbling `zx-*`
+ * DOM events land there, not in the target's tree. Listen with `on('select')` or `onselect`.
+ *
+ * @fires ContextMenu#select
+ * @fires ContextMenu#open
+ * @fires ContextMenu#close
+ * @extends {Component<ContextMenuOptions>}
+ */
+export declare class ContextMenu extends Component<ContextMenuOptions> {
+    #private;
+    /** @type {ContextMenuOptions} */
+    static defaults: ContextMenuOptions;
+    /**
+     * Attaches a context menu to an existing element.
+     * @param {Element|string} target Element or selector the menu belongs to.
+     * @param {ContextMenuOptions} [options={}] Context-menu options.
+     */
+    constructor(target: Element | string, options?: ContextMenuOptions);
+    /**
+     * Creates the zero-sized element the menu is anchored to.
+     * @returns {HTMLElement}
+     */
+    render(): HTMLElement;
+    /**
+     * Replaces the menu items.
+     * @param {ContextMenuEntry[]} items Menu definitions.
+     * @returns {this}
+     */
+    setItems(items: ContextMenuEntry[]): this;
+    /**
+     * Opens the menu at a point in viewport coordinates.
+     * @param {number} x Client X.
+     * @param {number} y Client Y.
+     * @param {Element|null} [context=null] Element the menu applies to.
+     * @returns {this}
+     * @fires ContextMenu#open
+     */
+    openAt(x: number, y: number, context?: Element | null): this;
+    /**
+     * Opens the menu against an element's box, which is where a keyboard invocation puts it.
+     * @param {Element} element Element to anchor to.
+     * @returns {this}
+     * @fires ContextMenu#open
+     */
+    openAtElement(element: Element): this;
+    /**
+     * Closes the menu.
+     * @returns {this}
+     */
+    close(): this;
+    /**
+     * Reports whether the menu is open.
+     * @returns {boolean}
+     */
+    isOpen(): boolean;
+    /**
+     * The element the open menu applies to — the `selector` match under the pointer, or the target.
+     * @returns {Element|null}
+     */
+    getContext(): Element | null;
+    /**
+     * Detaches the menu and removes its anchor.
+     * @returns {void}
+     */
+    destroy(): void;
+}
+/**
+ * Fired when an enabled item is activated. `context` is the element the menu was opened on.
+ * @event ContextMenu#select
+ * @type {CustomEvent<{value: unknown, item: MenuItem, context: Element|null}>}
+ */
+/**
+ * Fired when the menu opens.
+ * @event ContextMenu#open
+ * @type {CustomEvent<{context: Element|null}>}
+ */
+/**
+ * Fired when the menu closes.
+ * @event ContextMenu#close
+ * @type {CustomEvent<Record<string, never>>}
+ */

package/dist/types/components/copy/copy-button.d.ts

@@ -0,0 +1,48 @@
+export type CopyButtonOptions = {
+    /**
+     * Text to copy, or a function returning it — a
+     * function is what a button beside a live value wants, so the copy is never stale.
+     */
+    text?: string | (() => string);
+    /**
+     * Visible label. Empty renders an icon-only ghost button.
+     */
+    label?: string;
+    /**
+     * Accessible name, and the native tooltip on the icon-only form.
+     */
+    title?: string;
+    /**
+     * Confirmation announced and shown after a copy.
+     */
+    feedback?: string;
+    /**
+     * Milliseconds the confirmation stays.
+     */
+    feedbackDuration?: number;
+    /**
+     * Control size.
+     */
+    size?: 'md' | 'sm';
+    /**
+     * Visual intent.
+     */
+    kind?: 'default' | 'primary' | 'ghost';
+    /**
+     * Called with the text and whether
+     * the clipboard accepted it.
+     */
+    oncopy?: (text: string, copied: boolean) => void;
+};
+/**
+ * Creates a button that copies a string and confirms it in place.
+ *
+ * The confirmation is the point: a clipboard write is silent, so without it nobody knows whether
+ * the click worked. It swaps the glyph for a tick and speaks through a live region, then reverts.
+ * A failed write — no permission, an insecure context — leaves the button untouched and reports
+ * `false` to `oncopy`, rather than claiming a copy that did not happen.
+ *
+ * @param {CopyButtonOptions} [opts={}] Copy-button options.
+ * @returns {HTMLButtonElement}
+ */
+export declare function copyButton(opts?: CopyButtonOptions): HTMLButtonElement;