@zeyos/zx 2.1.0 → 2.2.0

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

@@ -0,0 +1,91 @@
+import { Component } from '../../core/component.js';
+export type CopyInputOptions = {
+    /**
+     * Text shown and copied.
+     */
+    value?: string;
+    /**
+     * Visible label above the box.
+     */
+    label?: string;
+    /**
+     * Whether the label is kept for assistive technology only.
+     */
+    hideLabel?: boolean;
+    /**
+     * Confirmation shown after a copy.
+     */
+    feedback?: string;
+    /**
+     * Accessible name of the copy button.
+     */
+    buttonTitle?: string;
+    /**
+     * Control size.
+     */
+    size?: 'md' | 'sm';
+    /**
+     * Copy listener.
+     */
+    oncopy?: (event: CustomEvent<{
+        value: string;
+        copied: boolean;
+    }>) => void;
+};
+/**
+ * @typedef {Object} CopyInputOptions
+ * @property {string} [value=''] Text shown and copied.
+ * @property {string} [label=''] Visible label above the box.
+ * @property {boolean} [hideLabel=false] Whether the label is kept for assistive technology only.
+ * @property {string} [feedback='Copied'] Confirmation shown after a copy.
+ * @property {string} [buttonTitle='Copy'] Accessible name of the copy button.
+ * @property {'md'|'sm'} [size='md'] Control size.
+ * @property {(event: CustomEvent<{value: string, copied: boolean}>) => void} [oncopy] Copy listener.
+ */
+/**
+ * A read-only box holding a value to be copied — an API endpoint, a document number, a share link
+ * — with the copy button attached.
+ *
+ * The field is `readonly` rather than `disabled` so the text stays selectable and reachable by
+ * keyboard; focusing it selects the whole value, which is what someone reaching for Ctrl+C
+ * expects.
+ *
+ * @fires CopyInput#copy
+ * @extends {Component<CopyInputOptions>}
+ */
+export declare class CopyInput extends Component<CopyInputOptions> {
+    _createdRoot: boolean;
+    _snapshot: import("../../core/dom.js").TargetSnapshot;
+    static cssName: string;
+    /** @type {CopyInputOptions} */
+    static defaults: CopyInputOptions;
+    /** @returns {HTMLElement} */
+    render(): HTMLElement;
+    /**
+     * Returns the current value.
+     * @returns {string}
+     */
+    get(): string;
+    /**
+     * Replaces the value.
+     * @param {string} value Text to show and copy.
+     * @returns {this}
+     */
+    set(value: string): this;
+    /**
+     * Focuses the box and selects its contents.
+     *
+     * The selection is made here as well as in the `focus` listener: the listener covers a click or
+     * a Tab, but a programmatic `focus()` fires no focus event when the document itself is not
+     * focused, and the value would then be left uncopied under the caret.
+     * @returns {this}
+     */
+    focus(): this;
+    /** Restores an enhanced target to the markup it had before the takeover. @returns {void} */
+    destroy(): void;
+}
+/**
+ * Fired after a copy attempt; `copied` is false when the clipboard refused the write.
+ * @event CopyInput#copy
+ * @type {CustomEvent<{value: string, copied: boolean}>}
+ */

package/dist/types/components/data-filter/data-filter.d.ts

@@ -0,0 +1,250 @@
+import { Component } from '../../core/component.js';
+export type DataFilterRow = Record<string, any>;
+export type DataFilterOption = {
+    /**
+     * Option value.
+     */
+    value: unknown;
+    /**
+     * Option label.
+     */
+    label?: string;
+};
+export type SelectFilterDefinition = {
+    type: 'select';
+    /**
+     * State key.
+     */
+    id: string;
+    /**
+     * Visible label.
+     */
+    label: string;
+    /**
+     * Single row field.
+     */
+    field?: string;
+    /**
+     * Row fields combined with OR.
+     */
+    fields?: Array<string | ((row: DataFilterRow) => unknown)>;
+    /**
+     * Custom value accessor.
+     */
+    get?: (row: DataFilterRow) => unknown;
+    /**
+     * Explicit options; omitted derives distinct values.
+     */
+    options?: Array<unknown | DataFilterOption>;
+    /**
+     * Empty option label.
+     */
+    emptyLabel?: string;
+};
+export type TextFilterDefinition = {
+    type: 'text';
+    /**
+     * State key.
+     */
+    id: string;
+    /**
+     * Visible label.
+     */
+    label: string;
+    /**
+     * Search fields.
+     */
+    fields: Array<string | ((row: DataFilterRow) => unknown)>;
+    /**
+     * Search placeholder.
+     */
+    placeholder?: string;
+};
+export type CustomFilterDefinition = {
+    type: 'custom';
+    /**
+     * State key.
+     */
+    id: string;
+    /**
+     * Visible label.
+     */
+    label: string;
+    /**
+     * User-supplied native or custom control.
+     */
+    element: Element;
+    /**
+     * Row predicate.
+     */
+    predicate: (row: DataFilterRow, value: unknown) => boolean;
+};
+export type FilterDefinition = SelectFilterDefinition | TextFilterDefinition | CustomFilterDefinition;
+export type DataFilterOptions = {
+    /**
+     * Declarative filters.
+     */
+    filters?: FilterDefinition[];
+    /**
+     * Rows to filter.
+     */
+    data?: DataFilterRow[];
+    /**
+     * Apply and emit whenever a control changes.
+     */
+    autoApply?: boolean;
+    /**
+     * Clear button label; null resolves `dataFilter.clear`.
+     */
+    clearLabel?: string | null;
+    onfilter?: (event: CustomEvent<DataFilterEventDetail>) => void;
+};
+export type DataFilterEventDetail = {
+    rows: DataFilterRow[];
+    state: Record<string, unknown>;
+};
+/** @typedef {Record<string, any>} DataFilterRow */
+/**
+ * @typedef {Object} DataFilterOption
+ * @property {unknown} value Option value.
+ * @property {string} [label] Option label.
+ */
+/**
+ * @typedef {Object} SelectFilterDefinition
+ * @property {'select'} type
+ * @property {string} id State key.
+ * @property {string} label Visible label.
+ * @property {string} [field] Single row field.
+ * @property {Array<string|((row: DataFilterRow) => unknown)>} [fields] Row fields combined with OR.
+ * @property {(row: DataFilterRow) => unknown} [get] Custom value accessor.
+ * @property {Array<unknown|DataFilterOption>} [options] Explicit options; omitted derives distinct values.
+ * @property {string} [emptyLabel] Empty option label.
+ */
+/**
+ * @typedef {Object} TextFilterDefinition
+ * @property {'text'} type
+ * @property {string} id State key.
+ * @property {string} label Visible label.
+ * @property {Array<string|((row: DataFilterRow) => unknown)>} fields Search fields.
+ * @property {string} [placeholder] Search placeholder.
+ */
+/**
+ * @typedef {Object} CustomFilterDefinition
+ * @property {'custom'} type
+ * @property {string} id State key.
+ * @property {string} label Visible label.
+ * @property {Element} element User-supplied native or custom control.
+ * @property {(row: DataFilterRow, value: unknown) => boolean} predicate Row predicate.
+ */
+/** @typedef {SelectFilterDefinition|TextFilterDefinition|CustomFilterDefinition} FilterDefinition */
+/**
+ * @typedef {Object} DataFilterOptions
+ * @property {FilterDefinition[]} [filters=[]] Declarative filters.
+ * @property {DataFilterRow[]} [data=[]] Rows to filter.
+ * @property {boolean} [autoApply=true] Apply and emit whenever a control changes.
+ * @property {string|null} [clearLabel=null] Clear button label; null resolves `dataFilter.clear`.
+ * @property {(event: CustomEvent<DataFilterEventDetail>) => void} [onfilter]
+ */
+/** @typedef {{rows: DataFilterRow[], state: Record<string, unknown>}} DataFilterEventDetail */
+/**
+ * Inline declarative filter bar that produces a filtered copy of client-side data.
+ * @fires DataFilter#filter
+ * @extends {Component<DataFilterOptions>}
+ */
+export declare class DataFilter extends Component<DataFilterOptions> {
+    _originalChildren: ChildNode[];
+    _filters: ({
+        type: 'custom';
+        id: string;
+        label: string;
+        element: Element;
+        predicate: (row: DataFilterRow, value: unknown) => boolean;
+    } | {
+        type: 'select';
+        id: string;
+        label: string;
+        field?: string;
+        fields?: Array<string | ((row: DataFilterRow) => unknown)>;
+        get?: (row: DataFilterRow) => unknown;
+        options?: Array<unknown | DataFilterOption>;
+        emptyLabel?: string;
+    } | {
+        type: 'text';
+        id: string;
+        label: string;
+        fields: Array<string | ((row: DataFilterRow) => unknown)>;
+        placeholder?: string;
+    })[];
+    _data: DataFilterRow[];
+    _state: {};
+    _entries: Map<any, any>;
+    _customOrigins: Map<any, any>;
+    _restored: boolean;
+    _filtered: import("./filter-core.js").FilterRow[];
+    _controls: HTMLElement;
+    _badge: HTMLElement;
+    _clearButton: HTMLElement;
+    static cssName: string;
+    /** @type {DataFilterOptions} */
+    static defaults: DataFilterOptions;
+    /**
+     * Creates a filter bar around a target or creates a new root when target is null.
+     * @param {Element|string|null} target Existing root, selector, or null.
+     * @param {DataFilterOptions} [options={}] Filter options.
+     */
+    constructor(target: Element | string | null, options?: DataFilterOptions);
+    /** @returns {HTMLElement} Filter root. */
+    render(): HTMLElement;
+    /**
+     * Replaces source rows and refreshes auto-derived select options.
+     * @param {DataFilterRow[]} rows New source rows.
+     * @returns {this}
+     * @fires DataFilter#filter
+     */
+    setData(rows: DataFilterRow[]): this;
+    /**
+     * Applies current state, emits the filtered rows, and returns them.
+     * @returns {DataFilterRow[]} Filtered copy.
+     * @fires DataFilter#filter
+     */
+    apply(): DataFilterRow[];
+    /**
+     * Clears every control and applies the empty state.
+     * @returns {this}
+     * @fires DataFilter#filter
+     */
+    clear(): this;
+    /** @returns {Record<string, unknown>} Shallow copy of state keyed by filter id. */
+    getState(): Record<string, unknown>;
+    /**
+     * Replaces filter state. Missing filter ids are cleared.
+     * @param {Record<string, unknown>} state State keyed by filter id.
+     * @returns {this}
+     * @fires DataFilter#filter
+     */
+    setState(state: Record<string, unknown>): this;
+    /**
+     * Adds one filter control without mutating the original options array.
+     * @param {FilterDefinition} definition Filter definition.
+     * @returns {this}
+     */
+    addFilter(definition: FilterDefinition): this;
+    /** Restores enhanced content and user-owned custom controls. @returns {void} */
+    destroy(): void;
+    /** @param {FilterDefinition} definition @returns {void} */
+    _appendFilter(definition: FilterDefinition): void;
+    /** @param {SelectFilterDefinition} definition @param {{element: HTMLSelectElement, options: Array<{value: unknown, label: string}>}} entry @returns {void} */
+    _populateSelect(definition: SelectFilterDefinition, entry: {
+        element: HTMLSelectElement;
+        options: Array<{
+            value: unknown;
+            label: string;
+        }>;
+    }): void;
+    /** @returns {void} */
+    _controlChanged(): void;
+    /** @returns {void} */
+    _syncControls(): void;
+    /** @returns {void} */
+    _syncActiveState(): void;
+}

package/dist/types/components/data-filter/filter-core.d.ts

@@ -0,0 +1,52 @@
+/** @typedef {Record<string, any>} FilterRow */
+/** @typedef {Record<string, unknown>} FilterState */
+export type FilterRow = Record<string, any>;
+export type FilterState = Record<string, unknown>;
+/**
+ * Normalizes searchable text for case- and diacritic-insensitive matching.
+ * @param {unknown} value Value to normalize.
+ * @returns {string} Normalized text.
+ */
+export declare function normalizeText(value: unknown): string;
+/**
+ * Tests a text corpus with whitespace-delimited, multi-word AND semantics.
+ * @param {unknown[]} values Searchable field values.
+ * @param {unknown} query Query value.
+ * @returns {boolean} Whether every query term occurs in the combined fields.
+ */
+export declare function matchesText(values: unknown[], query: unknown): boolean;
+/**
+ * Returns whether a filter state value represents an active filter.
+ * @param {unknown} value Filter value.
+ * @returns {boolean} Whether the value is active.
+ */
+export declare function isActiveFilterValue(value: unknown): boolean;
+/**
+ * Resolves all values addressed by a select or text filter definition.
+ * @param {FilterRow} row Source row.
+ * @param {Record<string, any>} definition Filter definition.
+ * @returns {unknown[]} Resolved values.
+ */
+export declare function getFilterValues(row: FilterRow, definition: Record<string, any>): unknown[];
+/**
+ * Derives distinct native-select options in first-seen order.
+ * Values shaped as `{value, label}` (or legacy `{field, label}`) retain their display label.
+ * @param {FilterRow[]} rows Source rows.
+ * @param {Record<string, any>} definition Select filter definition.
+ * @returns {Array<{value: unknown, label: string}>} Distinct options.
+ */
+export declare function deriveSelectOptions(rows: FilterRow[], definition: Record<string, any>): Array<{
+    value: unknown;
+    label: string;
+}>;
+/** Alias for the distinct-option derivation used by DataFilter. */
+export declare const deriveOptions: typeof deriveSelectOptions;
+/**
+ * Applies all active filter definitions to an array without mutating it.
+ * Filters combine with AND; multiple fields inside one select filter combine with OR.
+ * @param {FilterRow[]} rows Source rows.
+ * @param {Array<Record<string, any>>} filterDefs Filter definitions.
+ * @param {FilterState} state Values keyed by filter id.
+ * @returns {FilterRow[]} Filtered copy.
+ */
+export declare function applyFilters(rows: FilterRow[], filterDefs: Array<Record<string, any>>, state: FilterState): FilterRow[];

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

@@ -0,0 +1,137 @@
+import { Component } from '../../core/component.js';
+import { TimePicker } from './time-picker.js';
+export type DatePickerOptions = {
+    /**
+     * Initially selected date.
+     */
+    value?: Date | null;
+    /**
+     * Earliest selectable local calendar day.
+     */
+    min?: Date | null;
+    /**
+     * Latest selectable local calendar day.
+     */
+    max?: Date | null;
+    /**
+     * First weekday, from 0 (Sunday) through 6 (Saturday).
+     */
+    weekStart?: number;
+    /**
+     * Show ISO week numbers.
+     */
+    showWeekNumbers?: boolean;
+    /**
+     * Append a time picker below the calendar.
+     */
+    time?: boolean;
+    /**
+     * Change listener.
+     */
+    onchange?: (event: CustomEvent<{
+        date: Date | null;
+    }>) => void;
+    /**
+     * Visible-month listener.
+     */
+    onmonthchange?: (event: CustomEvent<{
+        year: number;
+        month: number;
+    }>) => void;
+};
+export type DatePickerSetOptions = {
+    silent?: boolean;
+};
+/**
+ * @typedef {Object} DatePickerOptions
+ * @property {Date|null} [value=null] Initially selected date.
+ * @property {Date|null} [min=null] Earliest selectable local calendar day.
+ * @property {Date|null} [max=null] Latest selectable local calendar day.
+ * @property {number} [weekStart=1] First weekday, from 0 (Sunday) through 6 (Saturday).
+ * @property {boolean} [showWeekNumbers=false] Show ISO week numbers.
+ * @property {boolean} [time=false] Append a time picker below the calendar.
+ * @property {(event: CustomEvent<{date: Date|null}>) => void} [onchange] Change listener.
+ * @property {(event: CustomEvent<{year: number, month: number}>) => void} [onmonthchange] Visible-month listener.
+ */
+/** @typedef {{silent?: boolean}} DatePickerSetOptions */
+/**
+ * Accessible inline calendar following the APG date-picker grid pattern.
+ * @fires DatePicker#change
+ * @fires DatePicker#monthchange
+ * @extends {Component<DatePickerOptions>}
+ */
+export declare class DatePicker extends Component<DatePickerOptions> {
+    _min: Date;
+    _max: Date;
+    _value: Date;
+    _focused: Date;
+    _viewYear: any;
+    _viewMonth: any;
+    _weekStart: number;
+    _quickOpen: boolean;
+    _timePicker: TimePicker;
+    _content: HTMLElement;
+    static cssName: string;
+    /** @type {DatePickerOptions} */
+    static defaults: DatePickerOptions;
+    /** @returns {HTMLElement} */
+    render(): HTMLElement;
+    /**
+     * Returns a copy of the selected date.
+     * @returns {Date|null}
+     */
+    get(): Date | null;
+    /**
+     * Selects a date, clamped to the configured day bounds.
+     * @param {Date|null} date Date to select, or null to clear.
+     * @param {DatePickerSetOptions} [options={}] Update behavior.
+     * @returns {this}
+     * @fires DatePicker#change
+     */
+    set(date: Date | null, { silent }?: DatePickerSetOptions): this;
+    /**
+     * Moves focus to the currently roving calendar day.
+     * @returns {this}
+     */
+    focus(): this;
+    /** Cleans up an appended time picker and generated host content. @returns {void} */
+    destroy(): void;
+    /** @param {Date|null} date @returns {Date|null} */
+    _normalizeValue(date: Date | null): Date | null;
+    /** @param {Date} date @returns {Date} */
+    _clampFocus(date: Date): Date;
+    /** @returns {void} */
+    _renderWeekdays(): void;
+    /** @returns {void} */
+    _renderCalendar(): void;
+    /** @param {Event} event @returns {void} */
+    _onDayClick(event: Event): void;
+    /** @param {KeyboardEvent} event @returns {void} */
+    _onDayKeydown(event: KeyboardEvent): void;
+    /** @param {Date} date @returns {void} */
+    _moveFocus(date: Date): void;
+    /** @param {Date} date @returns {void} */
+    _selectDate(date: Date): void;
+    /** @param {number} amount @returns {void} */
+    _pageMonth(amount: number): void;
+    /** @returns {void} */
+    _emitMonthChange(): void;
+    /** @returns {void} */
+    _toggleQuickPick(): void;
+    /** @returns {void} */
+    _closeQuickPick(): void;
+    /** @returns {void} */
+    _renderQuickPick(): void;
+    /** @param {number} amount @returns {void} */
+    _stepQuickYear(amount: number): void;
+    /** @param {Event} event @returns {void} */
+    _onQuickClick(event: Event): void;
+    /** @param {KeyboardEvent} event @returns {void} */
+    _onQuickKeydown(event: KeyboardEvent): void;
+    /** @param {number} month @returns {void} */
+    _chooseQuickMonth(month: number): void;
+    /** @param {Date} date @returns {boolean} */
+    _inRange(date: Date): boolean;
+    /** @param {Date} date @returns {HTMLButtonElement|null} */
+    _buttonForDate(date: Date): HTMLButtonElement | null;
+}