@zeyos/zx 2.1.0 → 2.2.1

package/dist/types/components/datebox/date-range-box.d.ts

@@ -0,0 +1,218 @@
+import { Component } from '../../core/component.js';
+import { DateRangePicker } from '../date-picker/date-range-picker.js';
+export type DateRange = import('../date-picker/date-range-picker.js').DateRange;
+export type DateRangePreset = import('../date-picker/date-range-picker.js').DateRangePreset;
+export type DateRangeSeconds = {
+    start: number | null;
+    end: number | null;
+};
+export type DateRangeInput = Date | number | string | null;
+export type DateRangeBoxOptions = {
+    /**
+     * Initial start: Date, Unix seconds, or formatted text.
+     */
+    start?: Date | number | string | null;
+    /**
+     * Initial end: Date, Unix seconds, or formatted text.
+     */
+    end?: Date | number | string | null;
+    /**
+     * Kernel date format used for both endpoints.
+     */
+    format?: string;
+    /**
+     * Text placed between the two formatted dates.
+     */
+    separator?: string;
+    /**
+     * Input placeholder; null derives one from the format.
+     */
+    placeholder?: string | null;
+    /**
+     * Show a clear button while a range is present.
+     */
+    clearable?: boolean;
+    /**
+     * Earliest selectable local calendar day.
+     */
+    min?: Date | null;
+    /**
+     * Latest selectable local calendar day.
+     */
+    max?: Date | null;
+    /**
+     * Month panels in the popover; narrow ones show only the first.
+     */
+    months?: number;
+    /**
+     * First weekday, from 0 (Sunday) through 6 (Saturday).
+     */
+    weekStart?: number;
+    /**
+     * Show ISO week numbers.
+     */
+    showWeekNumbers?: boolean;
+    /**
+     * Smallest number of nights a complete range may span.
+     */
+    minNights?: number;
+    /**
+     * Largest number of nights a complete range may span.
+     */
+    maxNights?: number | null;
+    /**
+     * Preset buttons, or `true` for the built-in set.
+     */
+    presets?: DateRangePreset[] | boolean;
+    /**
+     * Disable all controls.
+     */
+    disabled?: boolean;
+    /**
+     * Change listener.
+     */
+    onchange?: (event: CustomEvent<DateRange>) => void;
+    /**
+     * Invalid-input listener.
+     */
+    oninvalid?: (event: CustomEvent<{
+        text: string;
+    }>) => void;
+    /**
+     * Open listener.
+     */
+    onopen?: (event: CustomEvent<Record<string, never>>) => void;
+    /**
+     * Close listener.
+     */
+    onclose?: (event: CustomEvent<Record<string, never>>) => void;
+};
+export type DateRangeBoxSetOptions = {
+    silent?: boolean;
+};
+export type DateRangeBoxUnit = 'date' | 'seconds';
+/**
+ * Parses `"<start><separator><end>"` into a range. A lone date is read as a one-day range, and a
+ * trailing separator as a start-only range, so a half-typed value is not thrown away.
+ * @param {string} text Input text.
+ * @param {string} format Kernel date format for each endpoint.
+ * @param {string} separator Separator between the two dates; surrounding spaces are optional.
+ * @returns {DateRange|null} The parsed range, or null when the text does not match.
+ */
+export declare function parseRangeText(text: string, format: string, separator: string): DateRange | null;
+/**
+ * Renders a range as `"<start><separator><end>"`. An incomplete range yields the endpoint it has.
+ * @param {DateRange|null} range Range to render.
+ * @param {string} format Kernel date format for each endpoint.
+ * @param {string} separator Separator between the two dates.
+ * @returns {string}
+ */
+export declare function formatRangeText(range: DateRange | null, format: string, separator: string): string;
+/**
+ * Formatted date-range input with an anchored two-month range calendar.
+ * @fires DateRangeBox#change
+ * @fires DateRangeBox#invalid
+ * @fires DateRangeBox#open
+ * @fires DateRangeBox#close
+ * @extends {Component<DateRangeBoxOptions>}
+ */
+export declare class DateRangeBox extends Component<DateRangeBoxOptions> {
+    _originalState: string;
+    _originalAriaDisabled: string;
+    _format: string;
+    _separator: string;
+    _disabled: boolean;
+    _open: boolean;
+    _position: import("../../core/position.js").PositionController;
+    _range: import("../date-picker/date-range-picker.js").DateRange | {
+        start: unknown;
+        end: unknown;
+    };
+    _content: HTMLElement;
+    _picker: DateRangePicker;
+    static cssName: string;
+    /** @type {DateRangeBoxOptions} */
+    static defaults: DateRangeBoxOptions;
+    /** @returns {HTMLElement} */
+    render(): HTMLElement;
+    /**
+     * Returns the selected range as dates or as Unix timestamps.
+     * @param {DateRangeBoxUnit} [unit='date'] Return unit.
+     * @returns {DateRange|DateRangeSeconds}
+     */
+    get(unit?: DateRangeBoxUnit): DateRange | DateRangeSeconds;
+    /**
+     * Sets a range. Each endpoint may be a Date, Unix seconds, or text in the configured format;
+     * a whole formatted range string and `null` are accepted too.
+     * @param {DateRange|{start: DateRangeInput, end: DateRangeInput}|string|null} range New range.
+     * @param {DateRangeBoxSetOptions} [options={}] Update behavior.
+     * @returns {this}
+     * @fires DateRangeBox#change
+     */
+    set(range: DateRange | {
+        start: DateRangeInput;
+        end: DateRangeInput;
+    } | string | null, { silent }?: DateRangeBoxSetOptions): this;
+    /**
+     * Clears the selection.
+     * @param {DateRangeBoxSetOptions} [options={}] Update behavior.
+     * @returns {this}
+     * @fires DateRangeBox#change
+     */
+    clear({ silent }?: DateRangeBoxSetOptions): this;
+    /**
+     * Opens and positions the range calendar, then moves focus into its grid.
+     * @returns {this}
+     * @fires DateRangeBox#open
+     */
+    open(): this;
+    /**
+     * Closes the range calendar.
+     * @returns {this}
+     * @fires DateRangeBox#close
+     */
+    close(): this;
+    /** Enables the box. @returns {this} */
+    enable(): this;
+    /** Disables the box and closes its popover. @returns {this} */
+    disable(): this;
+    /** Moves focus to the text input. @returns {this} */
+    focus(): this;
+    /** Cleans up the open popover, child picker, and generated host content. @returns {void} */
+    destroy(): void;
+    /**
+     * Stores a range, optionally pushing it back into the picker, and reports it.
+     * @param {DateRange} range Already-coerced range.
+     * @param {{silent?: boolean, push?: boolean}} [options={}] Update behavior.
+     * @returns {void}
+     * @fires DateRangeBox#change
+     */
+    _apply(range: DateRange, { silent, push }?: {
+        silent?: boolean;
+        push?: boolean;
+    }): void;
+    /** @param {KeyboardEvent} event @returns {void} */
+    _onInputKeydown(event: KeyboardEvent): void;
+    /** @returns {void} */
+    _commitText(): void;
+    /**
+     * Coerces any accepted input shape into a bounded range of local dates.
+     * @param {unknown} value Range-ish input.
+     * @returns {DateRange}
+     */
+    _coerce(value: unknown): DateRange;
+    /** @param {unknown} value @returns {Date|null} */
+    _toDate(value: unknown): Date | null;
+    /** @param {DateRange} range @returns {DateRange} */
+    _clamp(range: DateRange): DateRange;
+    /** @returns {string} */
+    _placeholder(): string;
+    /** @returns {void} */
+    _syncDisplay(): void;
+    /** @returns {void} */
+    _syncDisabled(): void;
+    /** @returns {void} */
+    _setValid(): void;
+    /** @param {boolean} returnFocus @returns {void} */
+    _close(returnFocus: boolean): void;
+}

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

@@ -0,0 +1,160 @@
+import { Component } from '../../core/component.js';
+import { DatePicker } from '../date-picker/date-picker.js';
+export type DateboxOptions = {
+    /**
+     * Date, Unix seconds, or formatted string.
+     */
+    value?: Date | number | string | null;
+    /**
+     * Kernel date format.
+     */
+    format?: string;
+    /**
+     * Append `%H:%M` and show time controls.
+     */
+    time?: boolean;
+    /**
+     * Earliest selectable date.
+     */
+    min?: Date | null;
+    /**
+     * Latest selectable date.
+     */
+    max?: Date | null;
+    /**
+     * Input placeholder; null derives one from the format.
+     */
+    placeholder?: string | null;
+    /**
+     * Show a clear button when a value is present.
+     */
+    clearable?: boolean;
+    /**
+     * Disable all controls.
+     */
+    disabled?: boolean;
+    /**
+     * Change listener.
+     */
+    onchange?: (event: CustomEvent<{
+        date: Date | null;
+    }>) => void;
+    /**
+     * Invalid-input listener.
+     */
+    oninvalid?: (event: CustomEvent<{
+        text: string;
+    }>) => void;
+    /**
+     * Open listener.
+     */
+    onopen?: (event: CustomEvent<Record<string, never>>) => void;
+    /**
+     * Close listener.
+     */
+    onclose?: (event: CustomEvent<Record<string, never>>) => void;
+};
+export type DateboxSetOptions = {
+    silent?: boolean;
+};
+export type DateboxUnit = 'date' | 'seconds';
+/**
+ * @typedef {Object} DateboxOptions
+ * @property {Date|number|string|null} [value=null] Date, Unix seconds, or formatted string.
+ * @property {string} [format='%d.%m.%Y'] Kernel date format.
+ * @property {boolean} [time=false] Append `%H:%M` and show time controls.
+ * @property {Date|null} [min=null] Earliest selectable date.
+ * @property {Date|null} [max=null] Latest selectable date.
+ * @property {string|null} [placeholder=null] Input placeholder; null derives one from the format.
+ * @property {boolean} [clearable=true] Show a clear button when a value is present.
+ * @property {boolean} [disabled=false] Disable all controls.
+ * @property {(event: CustomEvent<{date: Date|null}>) => void} [onchange] Change listener.
+ * @property {(event: CustomEvent<{text: string}>) => void} [oninvalid] Invalid-input listener.
+ * @property {(event: CustomEvent<Record<string, never>>) => void} [onopen] Open listener.
+ * @property {(event: CustomEvent<Record<string, never>>) => void} [onclose] Close listener.
+ */
+/** @typedef {{silent?: boolean}} DateboxSetOptions */
+/** @typedef {'date'|'seconds'} DateboxUnit */
+/**
+ * Formatted date input with an anchored calendar popover.
+ * @fires Datebox#change
+ * @fires Datebox#invalid
+ * @fires Datebox#open
+ * @fires Datebox#close
+ * @extends {Component<DateboxOptions>}
+ */
+export declare class Datebox extends Component<DateboxOptions> {
+    _originalState: string;
+    _originalAriaDisabled: string;
+    _format: string;
+    _disabled: boolean;
+    _open: boolean;
+    _position: import("../../core/position.js").PositionController;
+    _min: Date;
+    _max: Date;
+    _value: Date;
+    _content: HTMLElement;
+    _picker: DatePicker;
+    static cssName: string;
+    /** @type {DateboxOptions} */
+    static defaults: DateboxOptions;
+    /** @returns {HTMLElement} */
+    render(): HTMLElement;
+    /**
+     * Returns the selected date or Unix timestamp.
+     * @param {DateboxUnit} [unit='date'] Return unit.
+     * @returns {Date|number|null}
+     */
+    get(unit?: DateboxUnit): Date | number | null;
+    /**
+     * Sets a Date, Unix-seconds number, formatted string, or null.
+     * @param {Date|number|string|null} value Value to set.
+     * @param {DateboxSetOptions} [options={}] Update behavior.
+     * @returns {this}
+     * @fires Datebox#change
+     */
+    set(value: Date | number | string | null, { silent }?: DateboxSetOptions): this;
+    /**
+     * Opens and positions the calendar popover, then moves focus into its grid.
+     * @returns {this}
+     * @fires Datebox#open
+     */
+    open(): this;
+    /**
+     * Closes the calendar popover.
+     * @returns {this}
+     * @fires Datebox#close
+     */
+    close(): this;
+    /** Enables the datebox. @returns {this} */
+    enable(): this;
+    /** Disables the datebox and closes its popover. @returns {this} */
+    disable(): this;
+    /** Moves focus to the text input. @returns {this} */
+    focus(): this;
+    /** Cleans up the open popover, child picker, and generated host content. @returns {void} */
+    destroy(): void;
+    /** @param {KeyboardEvent} event @returns {void} */
+    _onInputKeydown(event: KeyboardEvent): void;
+    /** @returns {void} */
+    _commitText(): void;
+    /** @param {Date|number|string|null|unknown} value @returns {Date|null} */
+    _normalizeValue(value: Date | number | string | null | unknown): Date | null;
+    /** @returns {void} */
+    _syncDisplay(): void;
+    /** @returns {void} */
+    _syncDisabled(): void;
+    /** @returns {void} */
+    _setValid(): void;
+    /** @param {boolean} returnFocus @returns {void} */
+    _close(returnFocus: boolean): void;
+    /** @returns {Date|null} */
+    _copyValue(): Date | null;
+}
+/**
+ * Datebox factory with time selection enabled. It is callable with or without `new`.
+ * @param {Element|string|null} target Existing component root, selector, or null.
+ * @param {DateboxOptions} [options={}] Datebox options; `time` is always enabled.
+ * @returns {Datebox}
+ */
+export declare const DateTimeBox: (target: Element | string | null, options?: DateboxOptions) => Datebox;

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

@@ -0,0 +1,5 @@
+/**
+ * Registers Datebox-backed `date` and DateTimeBox-backed `datetime` field types.
+ * @returns {void}
+ */
+export declare function registerDateboxFieldAdapters(): void;

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

@@ -0,0 +1,284 @@
+import { Modal } from '../modal/modal.js';
+export type DialogButtonKind = 'default' | 'primary' | 'danger' | 'ghost';
+export type DialogButton = {
+    /**
+     * Button label.
+     */
+    label: string;
+    /**
+     * Visual button kind.
+     */
+    kind?: DialogButtonKind;
+    /**
+     * Button action.
+     */
+    action?: 'close' | 'cancel' | ((dialog: Dialog) => void);
+    /**
+     * Whether this button receives initial focus.
+     */
+    autofocus?: boolean;
+};
+export type DialogOptions = {
+    /**
+     * Dialog title.
+     */
+    title?: string;
+    /**
+     * Preset or pixel width.
+     */
+    size?: 'sm' | 'md' | 'lg' | number;
+    /**
+     * Footer buttons.
+     */
+    buttons?: DialogButton[];
+    /**
+     * Whether Escape and the header button may close the dialog.
+     */
+    closable?: boolean;
+    /**
+     * Body content.
+     */
+    content?: Node | string | number | {
+        toElement: () => Node | null;
+    } | null;
+    /**
+     * Open event listener.
+     */
+    onopen?: (event: CustomEvent<Record<string, never>>) => void;
+    /**
+     * Close event listener.
+     */
+    onclose?: (event: CustomEvent<{
+        result: unknown;
+    }>) => void;
+    /**
+     * Cancel event listener.
+     */
+    oncancel?: (event: CustomEvent<Record<string, never>>) => void;
+};
+export type DialogViewOptions = {
+    /**
+     * View content.
+     */
+    content: Node | string | number | {
+        toElement: () => Node | null;
+    } | null;
+    /**
+     * View-specific footer buttons.
+     */
+    buttons?: DialogButton[];
+    /**
+     * View-specific title.
+     */
+    title?: string;
+};
+export type DialogView = {
+    /**
+     * View key.
+     */
+    key: string;
+    /**
+     * View content container.
+     */
+    content: HTMLElement;
+    /**
+     * View-specific buttons, or null to use dialog buttons.
+     */
+    buttons: DialogButton[] | null;
+    /**
+     * View-specific title, or null to use the dialog title.
+     */
+    title: string | null;
+};
+export type AlertOptions = {
+    /**
+     * Alert title.
+     */
+    title?: string;
+    /**
+     * Alert message.
+     */
+    message?: Node | string | number | null;
+    /**
+     * Confirmation label.
+     */
+    okLabel?: string;
+};
+export type ConfirmOptions = {
+    /**
+     * Confirmation title.
+     */
+    title?: string;
+    /**
+     * Confirmation message.
+     */
+    message?: Node | string | number | null;
+    /**
+     * Confirmation label.
+     */
+    okLabel?: string;
+    /**
+     * Cancellation label.
+     */
+    cancelLabel?: string;
+    /**
+     * Whether the confirmation action is dangerous.
+     */
+    danger?: boolean;
+};
+export type PromptOptions = {
+    /**
+     * Prompt title.
+     */
+    title?: string;
+    /**
+     * Prompt message.
+     */
+    message?: Node | string | number | null;
+    /**
+     * Initial input value.
+     */
+    value?: string;
+    /**
+     * Input placeholder.
+     */
+    placeholder?: string;
+};
+/** @typedef {'default'|'primary'|'danger'|'ghost'} DialogButtonKind */
+/**
+ * @typedef {Object} DialogButton
+ * @property {string} label Button label.
+ * @property {DialogButtonKind} [kind='default'] Visual button kind.
+ * @property {'close'|'cancel'|((dialog: Dialog) => void)} [action='close'] Button action.
+ * @property {boolean} [autofocus=false] Whether this button receives initial focus.
+ */
+/**
+ * @typedef {Object} DialogOptions
+ * @property {string} [title=''] Dialog title.
+ * @property {'sm'|'md'|'lg'|number} [size='md'] Preset or pixel width.
+ * @property {DialogButton[]} [buttons=[]] Footer buttons.
+ * @property {boolean} [closable=true] Whether Escape and the header button may close the dialog.
+ * @property {Node|string|number|{toElement: () => Node|null}|null} [content=null] Body content.
+ * @property {(event: CustomEvent<Record<string, never>>) => void} [onopen] Open event listener.
+ * @property {(event: CustomEvent<{result: unknown}>) => void} [onclose] Close event listener.
+ * @property {(event: CustomEvent<Record<string, never>>) => void} [oncancel] Cancel event listener.
+ */
+/**
+ * @typedef {Object} DialogViewOptions
+ * @property {Node|string|number|{toElement: () => Node|null}|null} content View content.
+ * @property {DialogButton[]} [buttons] View-specific footer buttons.
+ * @property {string} [title] View-specific title.
+ */
+/**
+ * @typedef {Object} DialogView
+ * @property {string} key View key.
+ * @property {HTMLElement} content View content container.
+ * @property {DialogButton[]|null} buttons View-specific buttons, or null to use dialog buttons.
+ * @property {string|null} title View-specific title, or null to use the dialog title.
+ */
+/**
+ * @typedef {Object} AlertOptions
+ * @property {string} [title=''] Alert title.
+ * @property {Node|string|number|null} [message=''] Alert message.
+ * @property {string} [okLabel='OK'] Confirmation label.
+ */
+/**
+ * @typedef {Object} ConfirmOptions
+ * @property {string} [title=''] Confirmation title.
+ * @property {Node|string|number|null} [message=''] Confirmation message.
+ * @property {string} [okLabel='OK'] Confirmation label.
+ * @property {string} [cancelLabel='Cancel'] Cancellation label.
+ * @property {boolean} [danger=false] Whether the confirmation action is dangerous.
+ */
+/**
+ * @typedef {Object} PromptOptions
+ * @property {string} [title=''] Prompt title.
+ * @property {Node|string|number|null} [message=''] Prompt message.
+ * @property {string} [value=''] Initial input value.
+ * @property {string} [placeholder=''] Input placeholder.
+ */
+/**
+ * Structured modal with a title, body, footer actions, and switchable views.
+ * @fires Modal#open
+ * @fires Modal#close
+ * @fires Modal#cancel
+ */
+export declare class Dialog extends Modal {
+    #private;
+    static cssName: string;
+    /** @type {Readonly<DialogOptions>} */
+    static defaults: Readonly<DialogOptions>;
+    /**
+     * Creates a structured dialog appended to `document.body`.
+     * @param {Element|string|null} [_target=null] Ignored; Dialog always owns its root.
+     * @param {DialogOptions} [options={}] Dialog options.
+     */
+    constructor(_target?: Element | string | null, options?: DialogOptions);
+    /**
+     * Creates the structured native dialog.
+     * @returns {HTMLDialogElement}
+     */
+    render(): HTMLDialogElement;
+    /**
+     * Opens the dialog and focuses its autofocus control or first focusable descendant.
+     * @returns {this}
+     */
+    open(): this;
+    /**
+     * Sets the title shown in the dialog header.
+     * @param {string} title Title text.
+     * @returns {this}
+     */
+    setTitle(title: string): this;
+    /**
+     * Replaces the body content and clears any registered views.
+     * @param {Node|string|number|{toElement: () => Node|null}|null} content Body content.
+     * @returns {this}
+     */
+    setContent(content: Node | string | number | {
+        toElement: () => Node | null;
+    } | null): this;
+    /**
+     * Replaces the default footer buttons.
+     * @param {DialogButton[]} list Button definitions.
+     * @returns {this}
+     */
+    setButtons(list: DialogButton[]): this;
+    /**
+     * Adds or replaces a named dialog view. The first view is shown immediately.
+     * @param {string} key View key.
+     * @param {DialogViewOptions} options View options.
+     * @returns {DialogView}
+     */
+    addView(key: string, options: DialogViewOptions): DialogView;
+    /**
+     * Shows one registered view and applies its title and buttons.
+     * @param {string} key View key.
+     * @returns {DialogView}
+     */
+    showView(key: string): DialogView;
+    /**
+     * Returns a registered view.
+     * @param {string} key View key.
+     * @returns {DialogView|null}
+     */
+    getView(key: string): DialogView | null;
+    /**
+     * Opens an alert and resolves after it is dismissed.
+     * @param {AlertOptions} [options={}] Alert options.
+     * @returns {Promise<void>}
+     */
+    static alert({ title, message, okLabel }?: AlertOptions): Promise<void>;
+    /**
+     * Opens a confirmation dialog.
+     * @param {ConfirmOptions} [options={}] Confirmation options.
+     * @returns {Promise<boolean>}
+     */
+    static confirm({ title, message, okLabel, cancelLabel, danger }?: ConfirmOptions): Promise<boolean>;
+    /**
+     * Opens a single-line text prompt.
+     * @param {PromptOptions} [options={}] Prompt options.
+     * @returns {Promise<string|null>}
+     */
+    static prompt({ title, message, value, placeholder }?: PromptOptions): Promise<string | null>;
+}