@zeyos/zx 2.1.0 → 2.2.0

package/dist/types/components/tag-picker/field-adapter.d.ts

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

package/dist/types/components/tag-picker/tag-picker.d.ts

@@ -0,0 +1,375 @@
+import { Component } from '../../core/component.js';
+export type TagItem = Record<string, any> | string | number;
+export type TagValueReader = string | ((item: TagItem) => unknown);
+export type TagLabelReader = string | ((item: TagItem) => string);
+export type TagPickerOptions = {
+    /**
+     * Selectable items.
+     */
+    items?: TagItem[];
+    /**
+     * Initially selected IDs.
+     */
+    values?: unknown[];
+    /**
+     * Item ID property or reader.
+     */
+    valueKey?: TagValueReader;
+    /**
+     * Item label property or reader.
+     */
+    labelKey?: TagLabelReader;
+    /**
+     * Fields searched by local filtering.
+     */
+    searchKeys?: Array<TagValueReader> | null;
+    /**
+     * Filtering mode.
+     */
+    filter?: 'local' | ((query: string) => Promise<TagItem[]> | TagItem[]);
+    /**
+     * Minimum async query length.
+     */
+    minQuery?: number;
+    /**
+     * Async query delay in milliseconds.
+     */
+    debounce?: number;
+    /**
+     * Whether unknown values may be created from the query.
+     */
+    allowCreate?: boolean;
+    /**
+     * Maximum number of selected values.
+     */
+    max?: number | null;
+    /**
+     * Whether picking an item closes the list.
+     */
+    closeOnSelect?: boolean;
+    /**
+     * Empty-state input text.
+     */
+    placeholder?: string;
+    /**
+     * Maximum list height in pixels.
+     */
+    listHeight?: number;
+    /**
+     * Whether interaction is disabled.
+     */
+    disabled?: boolean;
+    /**
+     * Whether tags may be added or removed.
+     */
+    readonly?: boolean;
+    /**
+     * Option renderer.
+     */
+    renderItem?: ((item: TagItem) => Node | string) | null;
+    /**
+     * Tag-label renderer.
+     */
+    renderTag?: ((item: TagItem) => Node | string) | null;
+    /**
+     * Localized messages.
+     */
+    msg?: Record<string, string> | Record<string, Record<string, string>>;
+    /**
+     * Change listener.
+     */
+    onchange?: (event: CustomEvent<{
+        values: unknown[];
+        items: TagItem[];
+    }>) => void;
+    /**
+     * Add listener.
+     */
+    onadd?: (event: CustomEvent<{
+        value: unknown;
+        item: TagItem;
+    }>) => void;
+    /**
+     * Remove listener.
+     */
+    onremove?: (event: CustomEvent<{
+        value: unknown;
+        item: TagItem;
+    }>) => void;
+    /**
+     * Create listener.
+     */
+    oncreate?: (event: CustomEvent<{
+        value: unknown;
+        item: TagItem;
+    }>) => void;
+    /**
+     * Async-query listener.
+     */
+    onquery?: (event: CustomEvent<{
+        query: string;
+    }>) => void;
+    /**
+     * Open listener.
+     */
+    onopen?: (event: CustomEvent<Record<string, never>>) => void;
+    /**
+     * Close listener.
+     */
+    onclose?: (event: CustomEvent<Record<string, never>>) => void;
+    /**
+     * Async-failure listener.
+     */
+    onerror?: (event: CustomEvent<{
+        error: Error;
+    }>) => void;
+};
+/** @typedef {Record<string, any>|string|number} TagItem */
+/** @typedef {string|((item: TagItem) => unknown)} TagValueReader */
+/** @typedef {string|((item: TagItem) => string)} TagLabelReader */
+/**
+ * @typedef {Object} TagPickerOptions
+ * @property {TagItem[]} [items=[]] Selectable items.
+ * @property {unknown[]} [values=[]] Initially selected IDs.
+ * @property {TagValueReader} [valueKey='ID'] Item ID property or reader.
+ * @property {TagLabelReader} [labelKey='name'] Item label property or reader.
+ * @property {Array<TagValueReader>|null} [searchKeys=null] Fields searched by local filtering.
+ * @property {'local'|((query: string) => Promise<TagItem[]>|TagItem[])} [filter='local'] Filtering mode.
+ * @property {number} [minQuery=0] Minimum async query length.
+ * @property {number} [debounce=200] Async query delay in milliseconds.
+ * @property {boolean} [allowCreate=false] Whether unknown values may be created from the query.
+ * @property {number|null} [max=null] Maximum number of selected values.
+ * @property {boolean} [closeOnSelect=false] Whether picking an item closes the list.
+ * @property {string} [placeholder=''] Empty-state input text.
+ * @property {number} [listHeight=260] Maximum list height in pixels.
+ * @property {boolean} [disabled=false] Whether interaction is disabled.
+ * @property {boolean} [readonly=false] Whether tags may be added or removed.
+ * @property {((item: TagItem) => Node|string)|null} [renderItem=null] Option renderer.
+ * @property {((item: TagItem) => Node|string)|null} [renderTag=null] Tag-label renderer.
+ * @property {Record<string, string>|Record<string, Record<string, string>>} [msg] Localized messages.
+ * @property {(event: CustomEvent<{values: unknown[], items: TagItem[]}>) => void} [onchange] Change listener.
+ * @property {(event: CustomEvent<{value: unknown, item: TagItem}>) => void} [onadd] Add listener.
+ * @property {(event: CustomEvent<{value: unknown, item: TagItem}>) => void} [onremove] Remove listener.
+ * @property {(event: CustomEvent<{value: unknown, item: TagItem}>) => void} [oncreate] Create listener.
+ * @property {(event: CustomEvent<{query: string}>) => void} [onquery] Async-query listener.
+ * @property {(event: CustomEvent<Record<string, never>>) => void} [onopen] Open listener.
+ * @property {(event: CustomEvent<Record<string, never>>) => void} [onclose] Close listener.
+ * @property {(event: CustomEvent<{error: Error}>) => void} [onerror] Async-failure listener.
+ */
+/**
+ * Multi-select combobox that renders its selection as removable tags inside the control
+ * (APG combobox with a multi-selectable listbox).
+ *
+ * It differs from the two neighbouring components on purpose: `ValueList` takes free text with no
+ * catalogue behind it, `Checklist` shows a fixed set in full, and `TagPicker` searches a large
+ * catalogue and keeps the chosen values visible in the control.
+ *
+ * @fires TagPicker#change
+ * @fires TagPicker#add
+ * @fires TagPicker#remove
+ * @fires TagPicker#create
+ * @fires TagPicker#query
+ * @fires TagPicker#open
+ * @fires TagPicker#close
+ * @fires TagPicker#error
+ * @extends {Component<TagPickerOptions>}
+ */
+export declare class TagPicker extends Component<TagPickerOptions> {
+    _items: any[] | TagItem[];
+    _selected: any[];
+    _visible: any[];
+    _entries: any[];
+    _activeIndex: number;
+    _open: boolean;
+    _disabled: boolean;
+    _readonly: boolean;
+    _loading: boolean;
+    _requestSequence: any;
+    _queryTimer: number;
+    _position: import("../../core/position.js").PositionController;
+    _activeId: string;
+    _createdRoot: boolean;
+    _snapshot: import("../../core/dom.js").TargetSnapshot;
+    static cssName: string;
+    /** @type {TagPickerOptions} */
+    static defaults: TagPickerOptions;
+    /** @returns {HTMLElement} */
+    render(): HTMLElement;
+    /** Selected IDs. @returns {unknown[]} */
+    get values(): unknown[];
+    /** @param {unknown[]} next Selected IDs. */
+    set values(next: unknown[]);
+    /**
+     * Returns the selected IDs in selection order.
+     * @returns {unknown[]}
+     */
+    getValues(): unknown[];
+    /**
+     * Returns the selected items.
+     * @returns {TagItem[]}
+     */
+    getItems(): TagItem[];
+    /**
+     * Replaces the whole selection.
+     * @param {unknown[]} values Item IDs, or items.
+     * @param {{silent?: boolean}} [options={}] Set `silent` to suppress `change`.
+     * @returns {this}
+     * @fires TagPicker#change
+     */
+    setValues(values: unknown[], { silent }?: {
+        silent?: boolean;
+    }): this;
+    /**
+     * Adds one value to the selection.
+     * @param {unknown} value Item ID, or an item.
+     * @param {{silent?: boolean}} [options={}] Set `silent` to suppress events.
+     * @returns {this}
+     * @fires TagPicker#add
+     * @fires TagPicker#change
+     */
+    addValue(value: unknown, { silent }?: {
+        silent?: boolean;
+    }): this;
+    /**
+     * Removes one value from the selection.
+     * @param {unknown} value Item ID, or an item.
+     * @param {{silent?: boolean}} [options={}] Set `silent` to suppress events.
+     * @returns {this}
+     * @fires TagPicker#remove
+     * @fires TagPicker#change
+     */
+    removeValue(value: unknown, { silent }?: {
+        silent?: boolean;
+    }): this;
+    /**
+     * Clears the selection.
+     * @param {{silent?: boolean}} [options={}] Set `silent` to suppress `change`.
+     * @returns {this}
+     */
+    clear({ silent }?: {
+        silent?: boolean;
+    }): this;
+    /**
+     * Restores the configured initial selection.
+     * @param {{silent?: boolean}} [options={}] Reset behavior.
+     * @returns {this}
+     */
+    reset({ silent }?: {
+        silent?: boolean;
+    }): this;
+    /**
+     * Replaces the catalogue of selectable items.
+     * @param {TagItem[]} items Available items.
+     * @returns {this}
+     */
+    setItems(items: TagItem[]): this;
+    /** Reports whether the configured maximum is reached. @returns {boolean} */
+    isFull(): boolean;
+    /** Opens the option list. @returns {this} */
+    open(): this;
+    /** Closes the option list. @returns {this} */
+    close(): this;
+    /** Focuses the text input. @returns {this} */
+    focus(): this;
+    /** Enables user interaction. @returns {this} */
+    enable(): this;
+    /** Disables user interaction and closes the list. @returns {this} */
+    disable(): this;
+    /**
+     * Sets the read-only state.
+     * @param {boolean} readonly Whether tags may be added or removed.
+     * @returns {this}
+     */
+    setReadonly(readonly: boolean): this;
+    /** Cancels pending work and restores an enhanced target. @returns {void} */
+    destroy(): void;
+    /** @returns {void} */
+    _renderTags(): void;
+    /** @returns {void} */
+    _renderOptions(): void;
+    /**
+     * Stable identity for an option entry across re-renders.
+     * @param {{item: TagItem|null, create: boolean}} entry Entry.
+     * @returns {string}
+     */
+    _entryId(entry: {
+        item: TagItem | null;
+        create: boolean;
+    }): string;
+    /** @returns {void} */
+    _syncPlaceholder(): void;
+    /** @returns {void} */
+    _onInput(): void;
+    /** @param {KeyboardEvent} event @returns {void} */
+    _onKeydown(event: KeyboardEvent): void;
+    /** @param {MouseEvent} event @returns {void} */
+    _onOptionClick(event: MouseEvent): void;
+    /**
+     * Applies the active entry: toggles an item, or creates one from the query.
+     * @param {{item: TagItem|null, element: HTMLElement, create: boolean}|undefined} entry Entry.
+     * @returns {void}
+     */
+    _commitEntry(entry: {
+        item: TagItem | null;
+        element: HTMLElement;
+        create: boolean;
+    } | undefined): void;
+    /**
+     * Moves the active option. The APG combobox map stops at the ends rather than wrapping.
+     * @param {number} delta Signed step.
+     * @returns {void}
+     */
+    _move(delta: number): void;
+    /** @param {number} index @returns {void} */
+    _setActive(index: number): void;
+    /** @param {string} query @returns {void} */
+    _applyLocalFilter(query: string): void;
+    /** @param {string} query @returns {void} */
+    _scheduleAsyncQuery(query: string): void;
+    /** @param {string} query @returns {Promise<void>} */
+    _runQuery(query: string): Promise<void>;
+    /** @returns {void} */
+    _cancelQuery(): void;
+    /** @param {boolean} loading @returns {void} */
+    _setLoading(loading: boolean): void;
+    /**
+     * Reports whether an item is already selected.
+     * @param {unknown} value Item ID.
+     * @returns {boolean}
+     */
+    _isSelected(value: unknown): boolean;
+    /** @param {string} query @returns {boolean} */
+    _canCreate(query: string): boolean;
+    /**
+     * Builds a stand-in item for a value that is not in the catalogue.
+     * @param {string} label Visible label.
+     * @param {unknown} [value=label] ID to keep, so the original type survives.
+     * @returns {TagItem}
+     */
+    _createItem(label: string, value?: unknown): TagItem;
+    /**
+     * Resolves an ID or an item to a catalogue item, falling back to a bare value.
+     * @param {unknown} value ID or item.
+     * @returns {TagItem|null}
+     */
+    _resolve(value: unknown): TagItem | null;
+    /** @param {TagItem} a @param {TagItem} b @returns {boolean} */
+    _sameValue(a: TagItem, b: TagItem): boolean;
+    /** @param {unknown} item @returns {unknown} */
+    _valueOf(item: unknown): unknown;
+    /** @param {unknown} item @returns {string} */
+    _labelOf(item: unknown): string;
+    /** @returns {void} */
+    _emitChange(): void;
+    /** Grows the input to fit its text so the caret stays visible next to the tags. @returns {void} */
+    _syncInputWidth(): void;
+    /** @returns {void} */
+    _syncDisabled(): void;
+    /**
+     * @param {string} key Message key.
+     * @param {string} fallback Template used when the host has no translation.
+     * @param {unknown[]} [args=[]] Positional interpolation values.
+     * @returns {string}
+     */
+    _message(key: string, fallback: string, args?: unknown[]): string;
+}

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

@@ -0,0 +1,5 @@
+/**
+ * Registers the duration-oriented `time` field type.
+ * @returns {void}
+ */
+export declare function registerTimeboxFieldAdapter(): void;

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

@@ -0,0 +1,121 @@
+import { Component } from '../../core/component.js';
+export type TimeUnit = 'minutes' | 'seconds' | 'hours';
+export type TimeParts = {
+    hours: number;
+    minutes: number;
+    seconds: number;
+    negative: boolean;
+};
+export type TimeboxOptions = {
+    /**
+     * Initial duration in `unit`.
+     */
+    value?: number;
+    /**
+     * Default input and output unit.
+     */
+    unit?: TimeUnit;
+    /**
+     * Show a seconds segment.
+     */
+    seconds?: boolean;
+    /**
+     * Show a positive/negative toggle.
+     */
+    signed?: boolean;
+    /**
+     * Disable all controls.
+     */
+    disabled?: boolean;
+    /**
+     * Change listener.
+     */
+    onchange?: (event: CustomEvent<{
+        value: number;
+    }>) => void;
+};
+export type TimeboxSetOptions = {
+    silent?: boolean;
+};
+/** @typedef {'minutes'|'seconds'|'hours'} TimeUnit */
+/** @typedef {{hours: number, minutes: number, seconds: number, negative: boolean}} TimeParts */
+/**
+ * @typedef {Object} TimeboxOptions
+ * @property {number} [value=0] Initial duration in `unit`.
+ * @property {TimeUnit} [unit='minutes'] Default input and output unit.
+ * @property {boolean} [seconds=false] Show a seconds segment.
+ * @property {boolean} [signed=false] Show a positive/negative toggle.
+ * @property {boolean} [disabled=false] Disable all controls.
+ * @property {(event: CustomEvent<{value: number}>) => void} [onchange] Change listener.
+ */
+/** @typedef {{silent?: boolean}} TimeboxSetOptions */
+/**
+ * Splits a duration into unlimited hours and normalized minute/second segments.
+ * @param {number} value Duration value.
+ * @param {TimeUnit} [unit='minutes'] Unit of `value`.
+ * @returns {TimeParts}
+ */
+export declare function splitTime(value: number, unit?: TimeUnit): TimeParts;
+/**
+ * Joins duration segments and converts them to the requested unit.
+ * Minute and second overflow is carried into the unlimited hours value.
+ * @param {Partial<TimeParts>} parts Duration segments.
+ * @param {TimeUnit} [unit='minutes'] Unit of the returned number.
+ * @returns {number}
+ */
+export declare function joinTime(parts: Partial<TimeParts>, unit?: TimeUnit): number;
+/**
+ * Segmented duration input supporting unlimited and signed hours.
+ * @fires Timebox#change
+ * @extends {Component<TimeboxOptions>}
+ */
+export declare class Timebox extends Component<TimeboxOptions> {
+    _originalAriaDisabled: string;
+    _disabled: boolean;
+    _parts: TimeParts | {
+        hours: number;
+        minutes: number;
+        seconds: number;
+        negative: boolean;
+    };
+    _inputs: any[];
+    _content: HTMLElement;
+    static cssName: string;
+    /** @type {TimeboxOptions} */
+    static defaults: TimeboxOptions;
+    /** @returns {HTMLElement} */
+    render(): HTMLElement;
+    /**
+     * Returns the current duration.
+     * @param {TimeUnit} [unit=this.options.unit] Output unit.
+     * @returns {number}
+     */
+    get(unit?: TimeUnit): number;
+    /**
+     * Sets the current duration.
+     * @param {number} value Duration value.
+     * @param {TimeUnit|TimeboxSetOptions} [unit=this.options.unit] Input unit, or options when omitted.
+     * @param {TimeboxSetOptions} [options={}] Update behavior.
+     * @returns {this}
+     * @fires Timebox#change
+     */
+    set(value: number, unit?: TimeUnit | TimeboxSetOptions, options?: TimeboxSetOptions): this;
+    /** Enables the timebox. @returns {this} */
+    enable(): this;
+    /** Disables the timebox. @returns {this} */
+    disable(): this;
+    /** Removes generated content from an enhanced target. @returns {void} */
+    destroy(): void;
+    /** @param {HTMLElement} parent @param {'hours'|'minutes'|'seconds'} name @param {string} label @param {boolean} bounded @returns {void} */
+    _addSegment(parent: HTMLElement, name: 'hours' | 'minutes' | 'seconds', label: string, bounded: boolean): void;
+    /** @returns {TimeParts} */
+    _readParts(): TimeParts;
+    /** @returns {void} */
+    _commitSegments(): void;
+    /** @returns {void} */
+    _writeParts(): void;
+    /** @returns {void} */
+    _syncDisabled(): void;
+    /** @returns {void} */
+    _emitChange(): void;
+}

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

@@ -0,0 +1,5 @@
+/**
+ * Registers the boolean `toggle` field type.
+ * @returns {void}
+ */
+export declare function registerToggleFieldAdapter(): void;

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

@@ -0,0 +1,94 @@
+import { Component } from '../../core/component.js';
+export type ToggleOptions = {
+    /**
+     * Initial switch state.
+     */
+    checked?: boolean;
+    /**
+     * Value returned while on.
+     */
+    value?: any;
+    /**
+     * Optional visible label.
+     */
+    label?: string | null;
+    /**
+     * Initial disabled state.
+     */
+    disabled?: boolean;
+    /**
+     * Change callback.
+     */
+    onchange?: (event: CustomEvent<{
+        checked: boolean;
+        value: any;
+    }>) => void;
+};
+/**
+ * @typedef {Object} ToggleOptions
+ * @property {boolean} [checked=false] Initial switch state.
+ * @property {*} [value=true] Value returned while on.
+ * @property {string|null} [label=null] Optional visible label.
+ * @property {boolean} [disabled=false] Initial disabled state.
+ * @property {(event: CustomEvent<{checked: boolean, value: *}>) => void} [onchange] Change callback.
+ */
+/**
+ * Accessible on/off switch.
+ * @fires Toggle#change
+ * @extends {Component<ToggleOptions>}
+ */
+export declare class Toggle extends Component<ToggleOptions> {
+    _createdRoot: boolean;
+    _original: {
+        attributes: [string, string][];
+        children: Node[];
+    };
+    _checked: any;
+    _disabled: boolean;
+    _cleaned: boolean;
+    static cssName: string;
+    /** @type {Readonly<ToggleOptions>} */
+    static defaults: Readonly<ToggleOptions>;
+    /** @returns {HTMLButtonElement} */
+    render(): HTMLButtonElement;
+    /**
+     * Returns the current switch state.
+     * @returns {boolean}
+     */
+    get(): boolean;
+    /**
+     * Sets the switch state.
+     * @param {boolean} checked Next state.
+     * @param {{silent?: boolean}} [options={}] Set `silent` to suppress `change`.
+     * @returns {this}
+     * @fires Toggle#change
+     */
+    set(checked: boolean, { silent }?: {
+        silent?: boolean;
+    }): this;
+    /**
+     * Toggles the switch state.
+     * @returns {this}
+     * @fires Toggle#change
+     */
+    toggle(): this;
+    /**
+     * Returns the configured value while on, otherwise `false`.
+     * @returns {*}
+     */
+    getValue(): any;
+    /**
+     * Enables user interaction.
+     * @returns {this}
+     */
+    enable(): this;
+    /**
+     * Disables user interaction.
+     * @returns {this}
+     */
+    disable(): this;
+    /** @returns {void} */
+    destroy(): void;
+    /** @returns {void} */
+    _sync(): void;
+}