@zeyos/zx 2.1.0 → 2.2.0

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

@@ -0,0 +1,118 @@
+import { Component } from '../../core/component.js';
+declare const HANDLE_POINTER_DISMISS: unique symbol;
+declare const HANDLE_ESCAPE_DISMISS: unique symbol;
+export type DropdownOptions = {
+    /**
+     * Panel content.
+     */
+    content?: Node | string | number | {
+        toElement: () => Node | null;
+    } | null;
+    /**
+     * Panel placement.
+     */
+    placement?: 'bottom-start' | 'bottom-end' | 'top-start' | 'top-end' | 'bottom' | 'top';
+    /**
+     * Gap between anchor and panel in pixels.
+     */
+    offset?: number;
+    /**
+     * Whether the panel matches the anchor width.
+     */
+    matchWidth?: boolean;
+    /**
+     * Trigger behavior.
+     */
+    openOn?: 'click' | 'manual';
+    /**
+     * Whether a click within the panel closes it.
+     */
+    closeOnSelect?: boolean;
+    /**
+     * Open event listener.
+     */
+    onopen?: (event: CustomEvent<Record<string, never>>) => void;
+    /**
+     * Close event listener.
+     */
+    onclose?: (event: CustomEvent<Record<string, never>>) => void;
+};
+/**
+ * @typedef {Object} DropdownOptions
+ * @property {Node|string|number|{toElement: () => Node|null}|null} [content=null] Panel content.
+ * @property {'bottom-start'|'bottom-end'|'top-start'|'top-end'|'bottom'|'top'} [placement='bottom-start'] Panel placement.
+ * @property {number} [offset=4] Gap between anchor and panel in pixels.
+ * @property {boolean} [matchWidth=false] Whether the panel matches the anchor width.
+ * @property {'click'|'manual'} [openOn='click'] Trigger behavior.
+ * @property {boolean} [closeOnSelect=false] Whether a click within the panel closes it.
+ * @property {(event: CustomEvent<Record<string, never>>) => void} [onopen] Open event listener.
+ * @property {(event: CustomEvent<Record<string, never>>) => void} [onclose] Close event listener.
+ */
+/**
+ * Generic anchored floating panel using the browser popover top layer.
+ * @fires Dropdown#open
+ * @fires Dropdown#close
+ * @extends {Component<DropdownOptions>}
+ */
+export declare class Dropdown extends Component<DropdownOptions> {
+    #private;
+    static cssName: string;
+    /** @type {Readonly<DropdownOptions>} */
+    static defaults: Readonly<DropdownOptions>;
+    /**
+     * Creates a floating panel anchored to an existing element.
+     * @param {Element|string} anchor Anchor element or selector.
+     * @param {DropdownOptions} [options={}] Dropdown options.
+     */
+    constructor(anchor: Element | string, options?: DropdownOptions);
+    /**
+     * Creates the owned popover panel.
+     * @returns {HTMLElement}
+     */
+    render(): HTMLElement;
+    /**
+     * Opens and positions the panel.
+     * @returns {this}
+     * @fires Dropdown#open
+     */
+    open(): this;
+    /**
+     * Closes the panel and releases its positioning resources.
+     * @returns {this}
+     * @fires Dropdown#close
+     */
+    close(): this;
+    /**
+     * Toggles the panel.
+     * @returns {this}
+     */
+    toggle(): this;
+    /**
+     * Reports whether the panel is open.
+     * @returns {boolean}
+     */
+    isOpen(): boolean;
+    /**
+     * Replaces panel content without interpreting strings as HTML.
+     * @param {Node|string|number|{toElement: () => Node|null}|null} content Panel content.
+     * @returns {this}
+     */
+    setContent(content: Node | string | number | {
+        toElement: () => Node | null;
+    } | null): this;
+    /**
+     * Returns the owned popover panel.
+     * @returns {HTMLElement}
+     */
+    getPanel(): HTMLElement;
+    /**
+     * Closes and removes the panel, restoring anchor ARIA attributes.
+     * @returns {void}
+     */
+    destroy(): void;
+    /** @param {PointerEvent} event @returns {void} */
+    [HANDLE_POINTER_DISMISS](event: PointerEvent): void;
+    /** @param {KeyboardEvent} event @returns {void} */
+    [HANDLE_ESCAPE_DISMISS](event: KeyboardEvent): void;
+}
+export {};

package/dist/types/components/empty-state/empty-state.d.ts

@@ -0,0 +1,38 @@
+export type ButtonOptions = import('../button/button.js').ButtonOptions;
+export type EmptyStateOptions = {
+    /**
+     * Decorative icon name; null renders no icon.
+     */
+    icon?: string | null;
+    /**
+     * Headline text, rendered as a paragraph so page outlines stay intact.
+     */
+    title?: string;
+    /**
+     * Supporting sentence below the headline.
+     */
+    description?: string;
+    /**
+     * Buttons or button descriptors below the text.
+     */
+    actions?: Array<Element | ButtonOptions>;
+    /**
+     * Overall scale.
+     */
+    size?: 'md' | 'sm';
+    /**
+     * Content alignment.
+     */
+    align?: 'center' | 'start';
+};
+/**
+ * Creates the placeholder shown where a list, table, or panel has no content yet.
+ *
+ * Purely presentational: the icon is decorative, the headline is a paragraph rather than a heading
+ * so dropping the element into a Table's empty slot or a Panel body never disturbs the page's
+ * heading outline.
+ *
+ * @param {EmptyStateOptions} [opts={}] Empty-state options.
+ * @returns {HTMLDivElement}
+ */
+export declare function emptyState(opts?: EmptyStateOptions): HTMLDivElement;

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

@@ -0,0 +1,231 @@
+import { Component } from '../../core/component.js';
+export type FieldOptions = {
+    /**
+     * Control ID and logical field identifier.
+     */
+    id?: string | null;
+    /**
+     * Registered field type.
+     */
+    type?: string;
+    /**
+     * Visible label.
+     */
+    label?: string;
+    /**
+     * Supporting description.
+     */
+    description?: string;
+    /**
+     * Initial value.
+     */
+    value?: unknown;
+    /**
+     * Control placeholder.
+     */
+    placeholder?: string;
+    /**
+     * Whether a value is required.
+     */
+    required?: boolean;
+    /**
+     * Whether the control is disabled.
+     */
+    disabled?: boolean;
+    /**
+     * Select or option-list values.
+     */
+    options?: string[] | Record<string, string> | null;
+    /**
+     * Label/control layout.
+     */
+    layout?: 'stack' | 'inline';
+    /**
+     * Adapter-specific control properties.
+     */
+    props?: Record<string, unknown>;
+    /**
+     * Adapter used by the `custom` type.
+     */
+    adapter?: FieldAdapterFactory;
+};
+export type FieldAdapter = {
+    /**
+     * Control root.
+     */
+    el: Element;
+    /**
+     * Read the current value.
+     */
+    get: () => unknown;
+    /**
+     * Set the current value.
+     */
+    set: (value: unknown, options?: {
+        silent?: boolean;
+    }) => void;
+    /**
+     * Focus the control.
+     */
+    focus: () => void;
+    /**
+     * Set disabled state.
+     */
+    setDisabled: (disabled: boolean) => void;
+    /**
+     * Release adapter-owned resources.
+     */
+    destroy?: () => void;
+};
+export type FieldAdapterFactory = (field: Field, options: Readonly<FieldOptions>) => FieldAdapter;
+export type NumericCoercion = {
+    valid: boolean;
+    value: number | string;
+};
+/**
+ * @typedef {Object} FieldOptions
+ * @property {string|null} [id=null] Control ID and logical field identifier.
+ * @property {string} [type='text'] Registered field type.
+ * @property {string} [label=''] Visible label.
+ * @property {string} [description=''] Supporting description.
+ * @property {unknown} [value=undefined] Initial value.
+ * @property {string} [placeholder=''] Control placeholder.
+ * @property {boolean} [required=false] Whether a value is required.
+ * @property {boolean} [disabled=false] Whether the control is disabled.
+ * @property {string[]|Record<string, string>|null} [options=null] Select or option-list values.
+ * @property {'stack'|'inline'} [layout='stack'] Label/control layout.
+ * @property {Record<string, unknown>} [props={}] Adapter-specific control properties.
+ * @property {FieldAdapterFactory} [adapter] Adapter used by the `custom` type.
+ */
+/**
+ * @typedef {Object} FieldAdapter
+ * @property {Element} el Control root.
+ * @property {() => unknown} get Read the current value.
+ * @property {(value: unknown, options?: {silent?: boolean}) => void} set Set the current value.
+ * @property {() => void} focus Focus the control.
+ * @property {(disabled: boolean) => void} setDisabled Set disabled state.
+ * @property {() => void} [destroy] Release adapter-owned resources.
+ */
+/** @typedef {(field: Field, options: Readonly<FieldOptions>) => FieldAdapter} FieldAdapterFactory */
+/** @typedef {{valid: boolean, value: number|string}} NumericCoercion */
+/**
+ * One labelled form control backed by a registered adapter.
+ * @fires Field#change
+ * @fires Field#invalid
+ * @extends {Component<FieldOptions>}
+ */
+export declare class Field extends Component<FieldOptions> {
+    #private;
+    _ownedComponents: Set<any>;
+    _ownedNodes: any[];
+    _rootAttributes: Map<string, string>;
+    controlId: string;
+    adapter: FieldAdapter;
+    _baseDescribedBy: string;
+    _descriptionId: string;
+    _highlightId: string;
+    _highlight: HTMLElement;
+    initialValue: unknown;
+    static cssName: string;
+    /** @type {FieldOptions & {msg: Record<string, string>}} */
+    static defaults: FieldOptions & {
+        msg: Record<string, string>;
+    };
+    /**
+     * Registers or replaces a field adapter.
+     * @param {string} type Adapter type name.
+     * @param {FieldAdapterFactory} adapter Adapter factory.
+     * @returns {typeof Field}
+     */
+    static register(type: string, adapter: FieldAdapterFactory): typeof Field;
+    /**
+     * Reports whether a field adapter is registered.
+     * @param {string} type Adapter type name.
+     * @returns {boolean}
+     */
+    static has(type: string): boolean;
+    /** @returns {HTMLElement} */
+    render(): HTMLElement;
+    /**
+     * Returns the adapter value.
+     * @returns {unknown}
+     */
+    getValue(): unknown;
+    /**
+     * Sets the adapter value.
+     * @param {unknown} value New value.
+     * @param {{silent?: boolean}} [options={}] Set `silent` to suppress `change`.
+     * @returns {this}
+     * @fires Field#change
+     */
+    setValue(value: unknown, { silent }?: {
+        silent?: boolean;
+    }): this;
+    /**
+     * Focuses the adapter control.
+     * @returns {this}
+     */
+    focus(): this;
+    /**
+     * Restores the initial value without emitting `change`.
+     * @returns {this}
+     */
+    reset(): this;
+    /**
+     * Enables or disables the adapter control.
+     * @param {boolean} disabled Disabled state.
+     * @returns {this}
+     */
+    setDisabled(disabled: boolean): this;
+    /**
+     * Displays a validation or status message.
+     * @param {string} message Message text.
+     * @param {'danger'|'warning'|'success'} [kind='danger'] Message kind.
+     * @returns {this}
+     */
+    setHighlight(message: string, kind?: 'danger' | 'warning' | 'success'): this;
+    /**
+     * Clears the current validation or status message.
+     * @returns {this}
+     */
+    clearHighlight(): this;
+    /**
+     * Returns the adapter's control root.
+     * @returns {Element}
+     */
+    getInput(): Element;
+    /**
+     * Registers a child component for destruction with this field.
+     * @template {Component} T
+     * @param {T} component Child component.
+     * @returns {T} The registered component.
+     */
+    own<T extends Component>(component: T): T;
+    /** @param {boolean} [highlighted=false] @returns {void} */
+    _syncDescription(highlighted?: boolean): void;
+    /** @returns {void} */
+    destroy(): void;
+}
+/**
+ * Coerces a localized integer string. Empty strings remain empty and valid.
+ * @param {unknown} input Input value.
+ * @returns {NumericCoercion}
+ */
+export declare function coerceInteger(input: unknown): NumericCoercion;
+/**
+ * Coerces a localized floating-point string. The rightmost comma or dot is the decimal separator
+ * when both occur, so values such as `1.234,56` are accepted.
+ * @param {unknown} input Input value.
+ * @returns {NumericCoercion}
+ */
+export declare function coerceFloat(input: unknown): NumericCoercion;
+/**
+ * Field value change event.
+ * @event Field#change
+ * @type {CustomEvent<{value: unknown}>}
+ */
+/**
+ * Field validation failure event.
+ * @event Field#invalid
+ * @type {CustomEvent<{message: string}>}
+ */

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

@@ -0,0 +1,5 @@
+/**
+ * Registers the `upload` field type. Upload state remains server-owned, so its form value is null.
+ * @returns {void}
+ */
+export declare function registerFieldUploadAdapter(): void;

package/dist/types/components/field-upload/field-upload.d.ts

@@ -0,0 +1,213 @@
+import { Component } from '../../core/component.js';
+export type UploadTransport = {
+    /**
+     * Upload method used by stubs.
+     */
+    upload?: (url: string, options: UploadTransportOptions) => Promise<unknown>;
+    /**
+     * Http-compatible request method.
+     */
+    request?: (url: string, options: Record<string, unknown>) => Promise<unknown>;
+};
+export type UploadTransportOptions = {
+    /**
+     * Selected files.
+     */
+    files: File[];
+    /**
+     * Multipart field name.
+     */
+    paramName: string;
+    /**
+     * Extra form values.
+     */
+    params: Record<string, unknown>;
+    /**
+     * Request headers.
+     */
+    headers: Record<string, string>;
+    /**
+     * Abort signal.
+     */
+    signal: AbortSignal;
+    /**
+     * Progress callback.
+     */
+    onProgress: (percent: number) => void;
+};
+export type FieldUploadOptions = {
+    /**
+     * Upload endpoint.
+     */
+    url?: string;
+    /**
+     * Multipart file field name.
+     */
+    paramName?: string;
+    /**
+     * Extra multipart values.
+     */
+    params?: Record<string, unknown>;
+    /**
+     * Request headers.
+     */
+    headers?: Record<string, string>;
+    /**
+     * Allow multiple files.
+     */
+    multiple?: boolean;
+    /**
+     * Native accept filter.
+     */
+    accept?: string | null;
+    /**
+     * Maximum size per file in bytes.
+     */
+    maxSize?: number | null;
+    /**
+     * Upload immediately after selection.
+     */
+    autoUpload?: boolean;
+    /**
+     * Show a preview for the first selected image.
+     */
+    preview?: boolean;
+    /**
+     * Injected Http-compatible or stub upload transport.
+     */
+    http?: UploadTransport | null;
+};
+/**
+ * @typedef {Object} UploadTransport
+ * @property {(url: string, options: UploadTransportOptions) => Promise<unknown>} [upload] Upload method used by stubs.
+ * @property {(url: string, options: Record<string, unknown>) => Promise<unknown>} [request] Http-compatible request method.
+ */
+/**
+ * @typedef {Object} UploadTransportOptions
+ * @property {File[]} files Selected files.
+ * @property {string} paramName Multipart field name.
+ * @property {Record<string, unknown>} params Extra form values.
+ * @property {Record<string, string>} headers Request headers.
+ * @property {AbortSignal} signal Abort signal.
+ * @property {(percent: number) => void} onProgress Progress callback.
+ */
+/**
+ * @typedef {Object} FieldUploadOptions
+ * @property {string} [url=''] Upload endpoint.
+ * @property {string} [paramName='upload'] Multipart file field name.
+ * @property {Record<string, unknown>} [params={}] Extra multipart values.
+ * @property {Record<string, string>} [headers={}] Request headers.
+ * @property {boolean} [multiple=false] Allow multiple files.
+ * @property {string|null} [accept=null] Native accept filter.
+ * @property {number|null} [maxSize=null] Maximum size per file in bytes.
+ * @property {boolean} [autoUpload=true] Upload immediately after selection.
+ * @property {boolean} [preview=true] Show a preview for the first selected image.
+ * @property {UploadTransport|null} [http=null] Injected Http-compatible or stub upload transport.
+ */
+/**
+ * Accessible click/drop upload area. Native requests intentionally use XMLHttpRequest because
+ * browser fetch upload streams still do not expose portable upload progress events.
+ * @fires FieldUpload#select
+ * @fires FieldUpload#progress
+ * @fires FieldUpload#success
+ * @fires FieldUpload#error
+ * @fires FieldUpload#abort
+ * @extends {Component<FieldUploadOptions>}
+ */
+export declare class FieldUpload extends Component<FieldUploadOptions> {
+    _ownedNodes: any[];
+    _files: any[] | File[];
+    _disabled: boolean;
+    _running: boolean;
+    _runId: number;
+    _xhr: XMLHttpRequest;
+    _transportController: AbortController;
+    _previewUrl: string;
+    _initialState: string;
+    _initialDisabled: string;
+    _input: HTMLElement;
+    _dropzone: HTMLElement;
+    _preview: HTMLElement;
+    _progress: HTMLElement;
+    _progressText: HTMLElement;
+    _abort: HTMLElement;
+    _progressWrap: HTMLElement;
+    _status: HTMLElement;
+    static cssName: string;
+    /** @type {FieldUploadOptions} */
+    static defaults: FieldUploadOptions;
+    /** @returns {HTMLElement} */
+    render(): HTMLElement;
+    /**
+     * Uploads supplied files, or the current selection when omitted.
+     * @param {File[]|FileList|null} [files=null] Optional files to select and upload.
+     * @returns {Promise<unknown|null>} Transport response, or null when no upload starts.
+     */
+    upload(files?: File[] | FileList | null): Promise<unknown | null>;
+    /**
+     * Aborts the active upload.
+     * @returns {this}
+     * @fires FieldUpload#abort
+     */
+    abort(): this;
+    /**
+     * Clears selection, preview, progress, and status.
+     * @returns {this}
+     */
+    clear(): this;
+    /**
+     * Enables or disables file selection and dropping.
+     * @param {boolean} disabled Disabled state.
+     * @returns {this}
+     */
+    setDisabled(disabled: boolean): this;
+    /** @param {FileList|File[]|ArrayLike<File>} files @returns {void} */
+    _selectFiles(files: FileList | File[] | ArrayLike<File>): void;
+    /** @param {FileList|File[]|ArrayLike<File>} files @returns {boolean} */
+    _setFiles(files: FileList | File[] | ArrayLike<File>): boolean;
+    /** @param {DragEvent} event @returns {void} */
+    _handleDragOver(event: DragEvent): void;
+    /** @returns {Promise<unknown>} */
+    _uploadInjected(): Promise<unknown>;
+    /** @returns {Promise<unknown>} */
+    _uploadXhr(): Promise<unknown>;
+    /** @param {number} percent @returns {void} */
+    _setProgress(percent: number): void;
+    /** @returns {void} */
+    _finishAbort(): void;
+    /** @param {Error} error @returns {void} */
+    _selectionError(error: Error): void;
+    /** @returns {void} */
+    _renderPreview(): void;
+    /** @returns {void} */
+    _revokePreview(): void;
+    /** @param {string} state @returns {void} */
+    _setState(state: string): void;
+    /** @returns {void} */
+    destroy(): void;
+}
+/**
+ * Files selected event.
+ * @event FieldUpload#select
+ * @type {CustomEvent<{files: File[]}>
+ */
+/**
+ * Upload progress event.
+ * @event FieldUpload#progress
+ * @type {CustomEvent<{percent: number}>
+ */
+/**
+ * Upload success event.
+ * @event FieldUpload#success
+ * @type {CustomEvent<{response: unknown}>
+ */
+/**
+ * Upload failure event.
+ * @event FieldUpload#error
+ * @type {CustomEvent<{error: Error}>
+ */
+/**
+ * Upload aborted event.
+ * @event FieldUpload#abort
+ * @type {CustomEvent<Record<string, never>>}
+ */