@zeyos/zx 2.1.0 → 2.2.1

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

@@ -0,0 +1,235 @@
+import { Component } from '../../core/component.js';
+export type Primitive = string | number | boolean | symbol | bigint | null | undefined;
+export type SelectItem = Record<string, any> | Primitive;
+export type SelectValueReader = string | ((item: SelectItem) => unknown);
+export type SelectLabelReader = string | ((item: SelectItem) => string);
+export type SelectOptions = {
+    /**
+     * Available values.
+     */
+    items?: SelectItem[];
+    /**
+     * Item ID property or reader.
+     */
+    valueKey?: SelectValueReader;
+    /**
+     * Item label property or reader.
+     */
+    labelKey?: SelectLabelReader;
+    /**
+     * Option renderer.
+     */
+    renderItem?: ((item: SelectItem) => Node | string) | null;
+    /**
+     * Selected-value renderer.
+     */
+    renderValue?: ((item: SelectItem) => string) | null;
+    /**
+     * Initially selected ID or item.
+     */
+    value?: unknown;
+    /**
+     * Whether interaction is disabled.
+     */
+    disabled?: boolean;
+    /**
+     * Empty control text.
+     */
+    placeholder?: string;
+    /**
+     * Whether selection may be cleared.
+     */
+    clearable?: boolean;
+    /**
+     * Filtering mode.
+     */
+    filter?: false | 'local' | ((query: string) => Promise<SelectItem[]> | SelectItem[]);
+    /**
+     * Fields searched by local filtering.
+     */
+    searchKeys?: Array<SelectValueReader> | null;
+    /**
+     * Minimum async query length.
+     */
+    minQuery?: number;
+    /**
+     * Async query delay in milliseconds.
+     */
+    debounce?: number;
+    /**
+     * Maximum list height in pixels.
+     */
+    listHeight?: number;
+    /**
+     * Optional group reader.
+     */
+    groupKey?: SelectValueReader | null;
+    /**
+     * Localized messages.
+     */
+    msg?: Record<string, string> | Record<string, Record<string, string>>;
+    /**
+     * Change listener.
+     */
+    onchange?: (event: CustomEvent<SelectChangeDetail>) => void;
+    /**
+     * Open listener.
+     */
+    onopen?: (event: CustomEvent<Record<string, never>>) => void;
+    /**
+     * Close listener.
+     */
+    onclose?: (event: CustomEvent<Record<string, never>>) => void;
+    /**
+     * Async-query listener.
+     */
+    onquery?: (event: CustomEvent<SelectQueryDetail>) => void;
+    /**
+     * Async-loaded listener.
+     */
+    onloaded?: (event: CustomEvent<SelectLoadedDetail>) => void;
+};
+export type SelectChangeDetail = {
+    value: unknown;
+    item: SelectItem | null;
+};
+export type SelectQueryDetail = {
+    query: string;
+};
+export type SelectLoadedDetail = {
+    items: SelectItem[];
+};
+export type SelectOptionEntry = {
+    item: SelectItem | null;
+    clear: boolean;
+    element: HTMLElement;
+};
+export type SelectSetOptions = {
+    silent?: boolean;
+};
+/**
+ * APG editable combobox with optional local or asynchronous filtering.
+ *
+ * @fires Select#change
+ * @fires Select#open
+ * @fires Select#close
+ * @fires Select#query
+ * @fires Select#loaded
+ * @extends {Component<SelectOptions>}
+ */
+export declare class Select extends Component<SelectOptions> {
+    _items: any[] | SelectItem[];
+    _visibleItems: any[];
+    _selected: any;
+    _optionEntries: any[];
+    _activeIndex: number;
+    _open: boolean;
+    _disabled: boolean;
+    _loading: boolean;
+    _requestSequence: number;
+    _queryTimer: number;
+    _position: import("../../core/position.js").PositionController;
+    _createdRoot: boolean;
+    _root: HTMLElement;
+    _originalChildren: any[] | ChildNode[];
+    _originalAttributes: Map<any, any>;
+    _handleTypeahead: (event: KeyboardEvent | string) => void;
+    static cssName: string;
+    /** @type {SelectOptions} */
+    static defaults: SelectOptions;
+    /** @returns {HTMLElement} */
+    render(): HTMLElement;
+    /** Selected item ID, or null. */
+    get value(): unknown;
+    /** @param {unknown} id Selected item ID. */
+    set value(id: unknown);
+    /** Selected item, or null. @returns {SelectItem|null} */
+    get selected(): SelectItem | null;
+    /**
+     * Selects an item or item ID.
+     * @param {unknown} idOrItem Item ID, item, or null.
+     * @param {SelectSetOptions} [options={}] Update behavior.
+     * @returns {this}
+     * @fires Select#change
+     */
+    set(idOrItem: unknown, { silent }?: SelectSetOptions): this;
+    /**
+     * Replaces the available items and preserves selection by ID when possible.
+     * @param {SelectItem[]} items New items.
+     * @returns {this}
+     */
+    setItems(items: SelectItem[]): this;
+    /**
+     * Restores the configured initial value.
+     * @param {{silent?: boolean}} [options={}] Reset behavior.
+     * @returns {this}
+     */
+    reset({ silent }?: {
+        silent?: boolean;
+    }): this;
+    /** Opens the option panel. @returns {this} @fires Select#open */
+    open(): this;
+    /** Closes the option panel and restores the selected label. @returns {this} @fires Select#close */
+    close(): this;
+    /** Enables user interaction. @returns {this} */
+    enable(): this;
+    /** Disables user interaction and closes the panel. @returns {this} */
+    disable(): this;
+    /** Moves focus to the combobox input. @returns {this} */
+    focus(): this;
+    /**
+     * Creates the five-level priority preset.
+     * @param {Element|string|null} target Component target.
+     * @param {SelectOptions} [options={}] Select overrides other than fixed items and renderer.
+     * @returns {Select}
+     */
+    static priority(target: Element | string | null, options?: SelectOptions): Select;
+    /** Cleans up the panel, pending async work, and enhanced target contents. @returns {void} */
+    destroy(): void;
+    /** @param {KeyboardEvent} event @returns {void} */
+    _onKeydown(event: KeyboardEvent): void;
+    /** @returns {void} */
+    _onInput(): void;
+    /** @param {Event} event @returns {void} */
+    _onOptionClick(event: Event): void;
+    /** @param {SelectOptionEntry|undefined} entry @returns {void} */
+    _chooseEntry(entry: SelectOptionEntry | undefined): void;
+    /** @param {number} delta @returns {void} */
+    _moveActive(delta: number): void;
+    /** @param {number} index @returns {void} */
+    _setActive(index: number): void;
+    /** @returns {void} */
+    _renderOptions(): void;
+    /** @param {SelectItem|null} item @param {boolean} clear @param {string} [label] @returns {void} */
+    _appendOption(item: SelectItem | null, clear: boolean, label?: string): void;
+    /** @param {SelectItem|null} item @returns {Node|string} */
+    _renderItem(item: SelectItem | null): Node | string;
+    /** @param {string} query @returns {void} */
+    _scheduleAsyncQuery(query: string): void;
+    /** @param {string} query @param {number} sequence @returns {Promise<void>} */
+    _runAsyncQuery(query: string, sequence: number): Promise<void>;
+    /** @returns {void} */
+    _cancelQuery(): void;
+    /** @param {boolean} loading @returns {void} */
+    _setLoading(loading: boolean): void;
+    /** @returns {void} */
+    _syncInputValue(): void;
+    /** @returns {void} */
+    _syncDisabled(): void;
+    /** @param {unknown} candidate @returns {SelectItem|null} */
+    _findItem(candidate: unknown): SelectItem | null;
+    /** @param {SelectItem|null} item @returns {unknown} */
+    _itemValue(item: SelectItem | null): unknown;
+    /** @param {SelectItem|null} item @returns {string} */
+    _itemLabel(item: SelectItem | null): string;
+    /** @param {SelectItem|null} item @param {SelectValueReader|SelectLabelReader} reader @returns {unknown} */
+    _read(item: SelectItem | null, reader: SelectValueReader | SelectLabelReader): unknown;
+    /** @returns {number} */
+    _selectedEntryIndex(): number;
+    /** @param {number} itemIndex @returns {number} */
+    _itemEntryIndex(itemIndex: number): number;
+    /** @param {string} name @returns {void} */
+    _rememberAttribute(element: any, name: string): void;
+    /** @param {string} key @param {string} fallback @returns {string} */
+    _message(key: string, fallback: string): string;
+}

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

@@ -0,0 +1,97 @@
+export type SkeletonOptions = {
+    /**
+     * Block width; a number is read as pixels.
+     */
+    width?: string | number;
+    /**
+     * Block height; a number is read as pixels.
+     */
+    height?: string | number;
+    /**
+     * Corner rounding. `full` with equal width and height
+     * gives the circle an avatar or icon placeholder needs.
+     */
+    radius?: 'sm' | 'md' | 'full';
+};
+export type SkeletonTextOptions = {
+    /**
+     * Number of text lines.
+     */
+    lines?: number;
+    /**
+     * Width of the block as a whole.
+     */
+    width?: string | number;
+    /**
+     * Whether the first line is drawn taller, as a title.
+     */
+    heading?: boolean;
+    /**
+     * Width of the final line, which reads as prose
+     * rather than as a filled rectangle.
+     */
+    lastLineWidth?: string | number;
+};
+export type SkeletonTableOptions = {
+    /**
+     * Number of body rows.
+     */
+    rows?: number;
+    /**
+     * Number of columns.
+     */
+    columns?: number;
+    /**
+     * Whether a header row is drawn.
+     */
+    header?: boolean;
+};
+/**
+ * @typedef {Object} SkeletonOptions
+ * @property {string|number} [width='100%'] Block width; a number is read as pixels.
+ * @property {string|number} [height='1rem'] Block height; a number is read as pixels.
+ * @property {'sm'|'md'|'full'} [radius='sm'] Corner rounding. `full` with equal width and height
+ *   gives the circle an avatar or icon placeholder needs.
+ */
+/**
+ * @typedef {Object} SkeletonTextOptions
+ * @property {number} [lines=3] Number of text lines.
+ * @property {string|number} [width='100%'] Width of the block as a whole.
+ * @property {boolean} [heading=false] Whether the first line is drawn taller, as a title.
+ * @property {string|number} [lastLineWidth='60%'] Width of the final line, which reads as prose
+ *   rather than as a filled rectangle.
+ */
+/**
+ * @typedef {Object} SkeletonTableOptions
+ * @property {number} [rows=5] Number of body rows.
+ * @property {number} [columns=4] Number of columns.
+ * @property {boolean} [header=true] Whether a header row is drawn.
+ */
+/**
+ * Creates one placeholder block.
+ *
+ * Skeletons stand in for content whose shape is already known, which is what makes them worth
+ * more than a spinner: the layout does not jump when the data arrives. Every skeleton is
+ * `aria-hidden`, because a screen reader gains nothing from an announced grey box — set
+ * `aria-busy="true"` on the region being filled instead, and remove it with the skeleton.
+ *
+ * @param {SkeletonOptions} [opts={}] Block options.
+ * @returns {HTMLSpanElement}
+ */
+export declare function skeleton(opts?: SkeletonOptions): HTMLSpanElement;
+/**
+ * Creates a stack of placeholder lines standing in for a paragraph or a labelled value.
+ * @param {SkeletonTextOptions} [opts={}] Text options.
+ * @returns {HTMLDivElement}
+ */
+export declare function skeletonText(opts?: SkeletonTextOptions): HTMLDivElement;
+/**
+ * Creates a placeholder grid the shape of a table that has not loaded yet.
+ *
+ * Rendered as plain elements rather than a `<table>`: there is no data to expose, and a table
+ * whose cells are all empty is worse for assistive technology than no table at all.
+ *
+ * @param {SkeletonTableOptions} [opts={}] Table options.
+ * @returns {HTMLDivElement}
+ */
+export declare function skeletonTable(opts?: SkeletonTableOptions): HTMLDivElement;

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

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

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

@@ -0,0 +1,216 @@
+import { Component } from '../../core/component.js';
+export type SliderMark = {
+    /**
+     * Position on the scale.
+     */
+    value: number;
+    /**
+     * Text drawn under the tick; the value is used when omitted.
+     */
+    label?: string;
+};
+export type SliderOptions = {
+    /**
+     * Initial value, clamped to the range and snapped to `step`.
+     */
+    value?: number;
+    /**
+     * Lowest selectable value.
+     */
+    min?: number;
+    /**
+     * Highest selectable value.
+     */
+    max?: number;
+    /**
+     * Increment between selectable values.
+     */
+    step?: number;
+    /**
+     * Visible name of the control.
+     */
+    label?: string;
+    /**
+     * Whether the label is kept for assistive technology only.
+     */
+    hideLabel?: boolean;
+    /**
+     * Whether the current value is drawn opposite the label.
+     */
+    showValue?: boolean;
+    /**
+     * Whether `min` and `max` are drawn either side of the track.
+     */
+    showBounds?: boolean;
+    /**
+     * Whether a number box is drawn beside the track, for
+     * entering a value precisely rather than dragging to it.
+     */
+    showInput?: boolean;
+    /**
+     * Suffix appended to the readout.
+     */
+    unit?: string;
+    /**
+     * Labelled positions under the track.
+     */
+    marks?: Array<number | SliderMark> | null;
+    /**
+     * Whether the control is disabled.
+     */
+    disabled?: boolean;
+    /**
+     * Whether the value is displayed but cannot be changed.
+     */
+    readonly?: boolean;
+    /**
+     * Control size.
+     */
+    size?: 'md' | 'sm';
+    /**
+     * Replaces the default readout.
+     */
+    formatValue?: ((value: number) => string) | null;
+    /**
+     * Committed-value listener.
+     */
+    onchange?: (event: CustomEvent<{
+        value: number;
+    }>) => void;
+    /**
+     * Listener called while dragging.
+     */
+    oninput?: (event: CustomEvent<{
+        value: number;
+    }>) => void;
+};
+/**
+ * @typedef {Object} SliderMark
+ * @property {number} value Position on the scale.
+ * @property {string} [label] Text drawn under the tick; the value is used when omitted.
+ */
+/**
+ * @typedef {Object} SliderOptions
+ * @property {number} [value=0] Initial value, clamped to the range and snapped to `step`.
+ * @property {number} [min=0] Lowest selectable value.
+ * @property {number} [max=100] Highest selectable value.
+ * @property {number} [step=1] Increment between selectable values.
+ * @property {string} [label=''] Visible name of the control.
+ * @property {boolean} [hideLabel=false] Whether the label is kept for assistive technology only.
+ * @property {boolean} [showValue=true] Whether the current value is drawn opposite the label.
+ * @property {boolean} [showBounds=false] Whether `min` and `max` are drawn either side of the track.
+ * @property {boolean} [showInput=false] Whether a number box is drawn beside the track, for
+ *   entering a value precisely rather than dragging to it.
+ * @property {string} [unit=''] Suffix appended to the readout.
+ * @property {Array<number|SliderMark>|null} [marks=null] Labelled positions under the track.
+ * @property {boolean} [disabled=false] Whether the control is disabled.
+ * @property {boolean} [readonly=false] Whether the value is displayed but cannot be changed.
+ * @property {'md'|'sm'} [size='md'] Control size.
+ * @property {((value: number) => string)|null} [formatValue=null] Replaces the default readout.
+ * @property {(event: CustomEvent<{value: number}>) => void} [onchange] Committed-value listener.
+ * @property {(event: CustomEvent<{value: number}>) => void} [oninput] Listener called while dragging.
+ */
+/**
+ * Range control for a bounded numeric value — a discount rate, a threshold, a weighting.
+ *
+ * Built on a native `<input type="range">`, which is where the whole keyboard map comes from:
+ * arrows step, Page Up/Page Down jump, Home and End go to the bounds, and the value is announced
+ * as a slider without a line of ARIA. Everything Zx adds is chrome around it — the filled track,
+ * the readout, optional ticks, and an optional number box for entering a value exactly.
+ *
+ * @fires Slider#change
+ * @fires Slider#input
+ * @extends {Component<SliderOptions>}
+ */
+export declare class Slider extends Component<SliderOptions> {
+    _value: number;
+    _readonly: boolean;
+    _createdRoot: boolean;
+    _snapshot: import("../../core/dom.js").TargetSnapshot;
+    _min: number;
+    _max: number;
+    _step: number;
+    _id: string;
+    static cssName: string;
+    /** @type {SliderOptions} */
+    static defaults: SliderOptions;
+    /** @returns {HTMLElement} */
+    render(): HTMLElement;
+    /** Current value. @returns {number} */
+    get value(): number;
+    /** @param {number} next Next value. */
+    set value(next: number);
+    /**
+     * Returns the current value.
+     * @returns {number}
+     */
+    get(): number;
+    /**
+     * Sets the value, snapped to `step` and clamped to the range.
+     * @param {number} next Next value.
+     * @param {{silent?: boolean}} [options={}] Set `silent` to suppress `change`.
+     * @returns {this}
+     * @fires Slider#change
+     */
+    set(next: number, { silent }?: {
+        silent?: boolean;
+    }): this;
+    /**
+     * Replaces the range, re-snapping the current value into it.
+     * @param {number} min Lowest selectable value.
+     * @param {number} max Highest selectable value.
+     * @param {number} [step] Increment; the current one is kept when omitted.
+     * @returns {this}
+     */
+    setRange(min: number, max: number, step?: number): this;
+    /** Focuses the track. @returns {this} */
+    focus(): this;
+    /** Enables user interaction. @returns {this} */
+    enable(): this;
+    /** Disables user interaction. @returns {this} */
+    disable(): this;
+    /**
+     * Sets the read-only state: the value stays focusable and announced, but cannot be changed.
+     * @param {boolean} readonly Whether the value is fixed.
+     * @returns {this}
+     */
+    setReadonly(readonly: boolean): this;
+    /**
+     * Replaces the visible label.
+     * @param {string} label Control name.
+     * @returns {this}
+     */
+    setLabel(label: string): this;
+    /** @returns {HTMLInputElement} */
+    _numberBox(): HTMLInputElement;
+    /** @returns {HTMLElement|null} */
+    _marks(): HTMLElement | null;
+    /** @returns {void} */
+    _onInput(): void;
+    /** @returns {void} */
+    _onCommit(): void;
+    /** Writes the value into the input, the readout, and the fill. @returns {void} */
+    _paint(): void;
+    /** @returns {void} */
+    _paintTrack(): void;
+    /** @returns {void} */
+    _syncState(): void;
+    /**
+     * Snaps a raw value onto the step grid and clamps it to the range.
+     * @param {unknown} raw Value to snap.
+     * @returns {number}
+     */
+    _snap(raw: unknown): number;
+    /** @param {number} value @returns {number} */
+    _ratio(value: number): number;
+    /** @param {number} value @returns {string} */
+    _format(value: number): string;
+    /** Restores an enhanced target to the markup it had before the takeover. @returns {void} */
+    destroy(): void;
+}
+/**
+ * Decimal places a step carries, so a 0.1 step snaps to 0.3 rather than 0.30000000000000004.
+ * @param {number} step Step size.
+ * @returns {number}
+ */
+export declare function stepPrecision(step: number): number;