@zeyos/zx 2.1.0 → 2.2.0

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

@@ -0,0 +1,194 @@
+import { Component } from '../../core/component.js';
+export type PanelContent = string | Node | Component | null;
+export type PanelButtonDescriptor = {
+    /**
+     * Visible button label.
+     */
+    label?: string;
+    /**
+     * Icon name from the kernel icon set.
+     */
+    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;
+};
+export type PanelButton = Element | PanelButtonDescriptor;
+export type PanelOptions = {
+    /**
+     * Section title.
+     */
+    title?: string;
+    /**
+     * Initial body content.
+     */
+    content?: PanelContent;
+    /**
+     * Initial expanded state.
+     */
+    open?: boolean;
+    /**
+     * Whether the header toggles the body.
+     */
+    collapsible?: boolean;
+    /**
+     * Header actions, right-aligned next to the title.
+     */
+    buttons?: PanelButton[];
+    /**
+     * Optional footer content.
+     */
+    footer?: PanelContent;
+    /**
+     * Footer actions, right-aligned in the footer bar.
+     */
+    footerButtons?: PanelButton[];
+    /**
+     * Open callback.
+     */
+    onopen?: (event: CustomEvent<Record<string, never>>) => void;
+    /**
+     * Close callback.
+     */
+    onclose?: (event: CustomEvent<Record<string, never>>) => void;
+};
+/** @typedef {string|Node|Component|null} PanelContent */
+/**
+ * @typedef {Object} PanelButtonDescriptor
+ * @property {string} [label=''] Visible button label.
+ * @property {string|null} [icon=null] Icon name from the kernel icon set.
+ * @property {'default'|'primary'|'danger'|'ghost'} [kind='default'] Visual intent.
+ * @property {'md'|'sm'} [size='md'] Control size.
+ * @property {boolean} [disabled=false] Whether the button is disabled.
+ * @property {string} [title] Native title text.
+ * @property {(event: MouseEvent) => void} [onclick] Click callback.
+ */
+/** @typedef {Element|PanelButtonDescriptor} PanelButton */
+/**
+ * @typedef {Object} PanelOptions
+ * @property {string} [title=''] Section title.
+ * @property {PanelContent} [content=null] Initial body content.
+ * @property {boolean} [open=true] Initial expanded state.
+ * @property {boolean} [collapsible=true] Whether the header toggles the body.
+ * @property {PanelButton[]} [buttons=[]] Header actions, right-aligned next to the title.
+ * @property {PanelContent} [footer=null] Optional footer content.
+ * @property {PanelButton[]} [footerButtons=[]] Footer actions, right-aligned in the footer bar.
+ * @property {(event: CustomEvent<Record<string, never>>) => void} [onopen] Open callback.
+ * @property {(event: CustomEvent<Record<string, never>>) => void} [onclose] Close callback.
+ */
+/**
+ * Framed, optionally collapsible titled section.
+ *
+ * The header is a row rather than one big button: the title and chevron form the collapse control
+ * and the action area sits beside it, because a button may not contain other buttons.
+ * @fires Panel#open
+ * @fires Panel#close
+ * @extends {Component<PanelOptions>}
+ */
+export declare class Panel extends Component<PanelOptions> {
+    _createdRoot: boolean;
+    _original: {
+        attributes: Array<[string, string]>;
+        children: Node[];
+    };
+    _cleaned: boolean;
+    _open: boolean;
+    _collapsible: boolean;
+    _hasFooterContent: boolean;
+    static cssName: string;
+    /** @type {Readonly<PanelOptions>} */
+    static defaults: Readonly<PanelOptions>;
+    /**
+     * Creates or enhances a panel.
+     * @param {Element|string|null} target Existing container, selector, or null.
+     * @param {PanelOptions} [options={}] Panel options.
+     */
+    constructor(target: Element | string | null, options?: PanelOptions);
+    /** @returns {HTMLElement} */
+    render(): HTMLElement;
+    /**
+     * Replaces the visible title.
+     * @param {string} title Next title.
+     * @returns {this}
+     */
+    setTitle(title: string): this;
+    /**
+     * Replaces the panel body.
+     * @param {PanelContent} content Next text, node, component, or null to clear.
+     * @returns {this}
+     */
+    setContent(content: PanelContent): this;
+    /**
+     * Replaces the header action area, right-aligned beside the title.
+     * @param {PanelButton[]} list Button descriptors or elements.
+     * @returns {this}
+     */
+    setButtons(list: PanelButton[]): this;
+    /**
+     * Replaces or removes the footer content. The footer bar appears whenever it has content,
+     * footer buttons, or both.
+     * @param {PanelContent} content Next footer content, or null to remove it.
+     * @returns {this}
+     */
+    setFooter(content: PanelContent): this;
+    /**
+     * Replaces the footer action area, right-aligned in the footer bar.
+     * @param {PanelButton[]} list Button descriptors or elements.
+     * @returns {this}
+     */
+    setFooterButtons(list: PanelButton[]): this;
+    /**
+     * Expands the panel.
+     * @returns {this}
+     * @fires Panel#open
+     */
+    open(): this;
+    /**
+     * Collapses the panel.
+     * @returns {this}
+     * @fires Panel#close
+     */
+    close(): this;
+    /**
+     * Toggles the panel's expanded state.
+     * @returns {this}
+     * @fires Panel#open
+     * @fires Panel#close
+     */
+    toggle(): this;
+    /**
+     * Reports whether the body is expanded.
+     * @returns {boolean}
+     */
+    isOpen(): boolean;
+    /** @returns {void} */
+    destroy(): void;
+    /** @returns {void} */
+    _syncOpenState(): void;
+    /** @returns {void} */
+    _syncFooter(): void;
+    /**
+     * Turns button descriptors into elements, passing through any Element unchanged.
+     * @param {PanelButton[]} list Button descriptors or elements.
+     * @param {string} label Error-message prefix.
+     * @returns {Element[]}
+     */
+    _buildButtons(list: PanelButton[], label: string): Element[];
+}

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

@@ -0,0 +1,93 @@
+import { Component } from '../../core/component.js';
+import { Select } from '../select/select.js';
+export type PermissionGroup = Record<string, any> | string | number | boolean | symbol | bigint | null | undefined;
+export type PermissionOptions = {
+    /**
+     * Public, private, or group ID.
+     */
+    value?: boolean | string | number | symbol | bigint | null;
+    /**
+     * Available groups.
+     */
+    groups?: PermissionGroup[];
+    /**
+     * Group ID property or reader.
+     */
+    groupsValueKey?: string | ((item: PermissionGroup) => unknown);
+    /**
+     * Group label property or reader.
+     */
+    groupsLabelKey?: string | ((item: PermissionGroup) => string);
+    /**
+     * Localized messages.
+     */
+    msg?: Record<string, string> | Record<string, Record<string, string>>;
+    /**
+     * Change listener.
+     */
+    onchange?: (event: CustomEvent<PermissionChangeDetail>) => void;
+};
+export type PermissionChangeDetail = {
+    value: unknown;
+};
+/** @typedef {Record<string, any>|string|number|boolean|symbol|bigint|null|undefined} PermissionGroup */
+/**
+ * @typedef {Object} PermissionOptions
+ * @property {boolean|string|number|symbol|bigint|null} [value=true] Public, private, or group ID.
+ * @property {PermissionGroup[]} [groups=[]] Available groups.
+ * @property {string|((item: PermissionGroup) => unknown)} [groupsValueKey='ID'] Group ID property or reader.
+ * @property {string|((item: PermissionGroup) => string)} [groupsLabelKey='name'] Group label property or reader.
+ * @property {Record<string, string>|Record<string, Record<string, string>>} [msg] Localized messages.
+ * @property {(event: CustomEvent<PermissionChangeDetail>) => void} [onchange] Change listener.
+ */
+/** @typedef {{value: unknown}} PermissionChangeDetail */
+/**
+ * Record-permission choice for private, public, and group access.
+ *
+ * @fires Permission#change
+ * @extends {Component<PermissionOptions>}
+ */
+export declare class Permission extends Component<PermissionOptions> {
+    _mode: string;
+    _groupValue: any;
+    _groupSelect: Select;
+    _createdRoot: boolean;
+    _originalChildren: any[] | ChildNode[];
+    _root: HTMLElement;
+    _originalState: string;
+    static cssName: string;
+    /** @type {PermissionOptions} */
+    static defaults: PermissionOptions;
+    /** @returns {HTMLElement} */
+    render(): HTMLElement;
+    /** Returns the normalized permission value. @returns {'private'|'public'|unknown} */
+    get(): 'private' | 'public' | unknown;
+    /**
+     * Sets a public, private, or group permission.
+     * @param {boolean|string|number|symbol|bigint|null} value Permission value.
+     * @param {{silent?: boolean}} [options={}] Update behavior.
+     * @returns {this}
+     * @fires Permission#change
+     */
+    set(value: boolean | string | number | symbol | bigint | null, { silent }?: {
+        silent?: boolean;
+    }): this;
+    /** Destroys the embedded Select and restores an enhanced target. @returns {void} */
+    destroy(): void;
+    /** @returns {void} */
+    _selectGroupMode(): void;
+    /** @returns {void} */
+    _sync(): void;
+    /**
+     * @param {string} name
+     * @param {'private'|'public'|'group'} value
+     * @param {string} text
+     * @returns {{label: HTMLLabelElement, input: HTMLInputElement}}
+     */
+    _choice(name: string, value: 'private' | 'public' | 'group', text: string): {
+        label: HTMLLabelElement;
+        input: HTMLInputElement;
+    };
+    /** @param {string} key @param {string} fallback @returns {string} */
+    _message(key: string, fallback: string): string;
+}

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

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

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

@@ -0,0 +1,213 @@
+import { Component } from '../../core/component.js';
+export type RatingOptions = {
+    /**
+     * Initial rating; 0 means unrated.
+     */
+    value?: number;
+    /**
+     * Number of symbols.
+     */
+    max?: number;
+    /**
+     * Whether half steps are selectable.
+     */
+    allowHalf?: boolean;
+    /**
+     * Whether re-selecting the current value clears it.
+     */
+    clearable?: boolean;
+    /**
+     * Whether the rating is display-only.
+     */
+    readonly?: boolean;
+    /**
+     * Whether interaction is disabled.
+     */
+    disabled?: boolean;
+    /**
+     * Accessible name of the group.
+     */
+    label?: string;
+    /**
+     * Icon name used for each symbol.
+     */
+    icon?: string;
+    /**
+     * Per-step accessible names, lowest first.
+     */
+    labels?: string[] | null;
+    /**
+     * Whether to render the numeric value beside the symbols.
+     */
+    showValue?: boolean;
+    /**
+     * Optional rating count rendered beside the value.
+     */
+    count?: number | null;
+    /**
+     * Symbol size.
+     */
+    size?: 'sm' | 'md' | 'lg';
+    /**
+     * Localized messages.
+     */
+    msg?: Record<string, string> | Record<string, Record<string, string>>;
+    /**
+     * Change listener.
+     */
+    onchange?: (event: CustomEvent<{
+        value: number;
+    }>) => void;
+    /**
+     * Hover-preview listener.
+     */
+    onhover?: (event: CustomEvent<{
+        value: number | null;
+    }>) => void;
+};
+/**
+ * @typedef {Object} RatingOptions
+ * @property {number} [value=0] Initial rating; 0 means unrated.
+ * @property {number} [max=5] Number of symbols.
+ * @property {boolean} [allowHalf=false] Whether half steps are selectable.
+ * @property {boolean} [clearable=true] Whether re-selecting the current value clears it.
+ * @property {boolean} [readonly=false] Whether the rating is display-only.
+ * @property {boolean} [disabled=false] Whether interaction is disabled.
+ * @property {string} [label='Rating'] Accessible name of the group.
+ * @property {string} [icon='star'] Icon name used for each symbol.
+ * @property {string[]|null} [labels=null] Per-step accessible names, lowest first.
+ * @property {boolean} [showValue=false] Whether to render the numeric value beside the symbols.
+ * @property {number|null} [count=null] Optional rating count rendered beside the value.
+ * @property {'sm'|'md'|'lg'} [size='md'] Symbol size.
+ * @property {Record<string, string>|Record<string, Record<string, string>>} [msg] Localized messages.
+ * @property {(event: CustomEvent<{value: number}>) => void} [onchange] Change listener.
+ * @property {(event: CustomEvent<{value: number|null}>) => void} [onhover] Hover-preview listener.
+ */
+/**
+ * Star-rating control implementing the APG radio-group pattern: one radio per selectable step,
+ * a single tab stop, and arrow-key navigation. Half steps add a second radio per symbol rather
+ * than bending the radio semantics, so every reachable value has a real, nameable control.
+ *
+ * @fires Rating#change
+ * @fires Rating#hover
+ * @extends {Component<RatingOptions>}
+ */
+export declare class Rating extends Component<RatingOptions> {
+    _value: number;
+    _preview: any;
+    _disabled: boolean;
+    _readonly: boolean;
+    _radios: any[];
+    _createdRoot: boolean;
+    _snapshot: import("../../core/dom.js").TargetSnapshot;
+    _max: number;
+    _step: number;
+    _name: string;
+    _count: number;
+    static cssName: string;
+    /** @type {RatingOptions} */
+    static defaults: RatingOptions;
+    /** @returns {HTMLElement} */
+    render(): HTMLElement;
+    /** Current rating. @returns {number} */
+    get value(): number;
+    /** @param {number} next Next rating. */
+    set value(next: number);
+    /**
+     * Returns the current rating.
+     * @returns {number}
+     */
+    get(): number;
+    /**
+     * Sets the rating, snapped to the configured step and clamped to `[0, max]`.
+     * @param {number} next Next rating; 0 clears it.
+     * @param {{silent?: boolean}} [options={}] Set `silent` to suppress `change`.
+     * @returns {this}
+     * @fires Rating#change
+     */
+    set(next: number, { silent }?: {
+        silent?: boolean;
+    }): this;
+    /**
+     * Clears the rating.
+     * @param {{silent?: boolean}} [options={}] Set `silent` to suppress `change`.
+     * @returns {this}
+     */
+    clear({ silent }?: {
+        silent?: boolean;
+    }): this;
+    /**
+     * Restores the configured initial value.
+     * @param {{silent?: boolean}} [options={}] Reset behavior.
+     * @returns {this}
+     */
+    reset({ silent }?: {
+        silent?: boolean;
+    }): this;
+    /**
+     * Replaces the rating count shown beside the value.
+     * @param {number|null} count Number of ratings, or null to hide it.
+     * @returns {this}
+     */
+    setCount(count: number | null): this;
+    /** Focuses the selected step, or the first one when unrated. @returns {this} */
+    focus(): this;
+    /** Enables user interaction. @returns {this} */
+    enable(): this;
+    /** Disables user interaction. @returns {this} */
+    disable(): this;
+    /**
+     * Sets the read-only state.
+     * @param {boolean} readonly Whether the rating is display-only.
+     * @returns {this}
+     */
+    setReadonly(readonly: boolean): this;
+    /**
+     * Builds one selectable step.
+     * @param {number} value Step value.
+     * @param {'half'|'full'} part Which half of the symbol the control covers.
+     * @returns {HTMLButtonElement}
+     */
+    _radio(value: number, part: 'half' | 'full'): HTMLButtonElement;
+    /**
+     * @param {number} value Step value.
+     * @returns {string}
+     */
+    _stepLabel(value: number): string;
+    /**
+     * Resolves a localized message, falling back to a built-in template.
+     * @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;
+    /**
+     * Applies an activation, honoring `clearable`.
+     * @param {number} value Step value.
+     * @param {boolean} allowClear Whether re-selecting the current value may clear it. Keyboard
+     *   activation never clears, because the APG radio pattern requires Space on an already
+     *   checked radio to do nothing.
+     * @returns {void}
+     */
+    _choose(value: number, allowClear: boolean): void;
+    /** @param {KeyboardEvent} event @returns {void} */
+    _onKeydown(event: KeyboardEvent): void;
+    /**
+     * @param {number|null} value Previewed value, or null to drop the preview.
+     * @returns {void}
+     */
+    _setPreview(value: number | null): void;
+    /** @param {unknown} raw @returns {number} */
+    _clamp(raw: unknown): number;
+    /** @returns {void} */
+    _sync(): void;
+    /** Paints the filled portion of every symbol from the preview or the value. @returns {void} */
+    _paint(): void;
+    /** @returns {void} */
+    _syncReadout(): void;
+    /** @returns {void} */
+    _syncDisabled(): void;
+    /** Restores an enhanced target to the markup it had before the takeover. @returns {void} */
+    destroy(): void;
+}

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

@@ -0,0 +1,98 @@
+import { Component } from '../../core/component.js';
+export type SearchOptions = {
+    /**
+     * Input placeholder.
+     */
+    placeholder?: string;
+    /**
+     * Initial query.
+     */
+    value?: string;
+    /**
+     * Whether to show a clear control.
+     */
+    clearable?: boolean;
+    /**
+     * Input debounce in milliseconds.
+     */
+    debounce?: number;
+    /**
+     * Input callback.
+     */
+    oninput?: (event: CustomEvent<{
+        value: string;
+    }>) => void;
+    /**
+     * Submit callback.
+     */
+    onsubmit?: (event: CustomEvent<{
+        value: string;
+    }>) => void;
+    /**
+     * Clear callback.
+     */
+    onclear?: (event: CustomEvent<Record<string, never>>) => void;
+};
+/**
+ * @typedef {Object} SearchOptions
+ * @property {string} [placeholder=''] Input placeholder.
+ * @property {string} [value=''] Initial query.
+ * @property {boolean} [clearable=true] Whether to show a clear control.
+ * @property {number} [debounce=250] Input debounce in milliseconds.
+ * @property {(event: CustomEvent<{value: string}>) => void} [oninput] Input callback.
+ * @property {(event: CustomEvent<{value: string}>) => void} [onsubmit] Submit callback.
+ * @property {(event: CustomEvent<Record<string, never>>) => void} [onclear] Clear callback.
+ */
+/**
+ * Search field with embedded submit and optional clear controls.
+ * @fires Search#input
+ * @fires Search#submit
+ * @fires Search#clear
+ * @extends {Component<SearchOptions>}
+ */
+export declare class Search extends Component<SearchOptions> {
+    _createdRoot: boolean;
+    _original: {
+        attributes: [string, string][];
+        children: Node[];
+    };
+    _inputTimer: number;
+    _cleaned: boolean;
+    static cssName: string;
+    /** @type {Readonly<SearchOptions>} */
+    static defaults: Readonly<SearchOptions>;
+    /** @returns {HTMLElement} */
+    render(): HTMLElement;
+    /**
+     * Returns the current query.
+     * @returns {string}
+     */
+    get(): string;
+    /**
+     * Sets the current query.
+     * @param {string} value Next query.
+     * @param {{silent?: boolean}} [options={}] Set `silent` to suppress `input`.
+     * @returns {this}
+     */
+    set(value: string, { silent }?: {
+        silent?: boolean;
+    }): this;
+    /**
+     * Focuses the input.
+     * @returns {this}
+     */
+    focus(): this;
+    /**
+     * Clears the query and reports both the value update and clear action.
+     * @returns {this}
+     * @fires Search#input
+     * @fires Search#clear
+     */
+    clear(): this;
+    /** @returns {void} */
+    destroy(): void;
+    /** @returns {void} */
+    _scheduleInput(): void;
+    /** @returns {void} */
+    _syncClear(): void;
+}

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

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

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

@@ -0,0 +1,11 @@
+/**
+ * Returns items whose searchable values contain every query word.
+ * Matching is case- and diacritic-insensitive.
+ *
+ * @template T
+ * @param {T[]} items Items to search.
+ * @param {string} query User-entered search text.
+ * @param {Array<string|((item: T) => unknown)>} keys Searchable object keys or value readers.
+ * @returns {T[]} Matching items in their original order.
+ */
+export declare function matchItems<T>(items: T[], query: string, keys: Array<string | ((item: T) => unknown)>): T[];