@zeyos/zx 2.3.0 → 3.0.0

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

@@ -0,0 +1,321 @@
+import { Component } from '../../core/component.js';
+export type ChartDataset = {
+    label?: string;
+    data?: unknown[];
+    [key: string]: unknown;
+};
+export type ChartData = {
+    labels?: unknown[];
+    datasets?: ChartDataset[];
+    [key: string]: unknown;
+};
+export type ChartSpec = {
+    /**
+     * Chart type.
+     */
+    type: string;
+    /**
+     * Chart data.
+     */
+    data: ChartData;
+    /**
+     * Engine-specific options.
+     */
+    options: Record<string, unknown>;
+    /**
+     * Point-selection callback.
+     */
+    onSelect: (detail: ChartSelectDetail) => void;
+};
+export type ChartHandle = {
+    /**
+     * Update the mounted chart.
+     */
+    update: (spec: ChartSpec) => void;
+    /**
+     * Resize the mounted chart.
+     */
+    resize: () => void;
+    /**
+     * Destroy the mounted chart.
+     */
+    destroy: () => void;
+    /**
+     * Engine instance.
+     */
+    instance?: unknown;
+};
+export type ChartAdapter = {
+    create: (canvas: HTMLCanvasElement, spec: ChartSpec) => ChartHandle;
+};
+export type ChartJsAdapterOptions = Object;
+export type ChartSelectDetail = {
+    /**
+     * Dataset index.
+     */
+    datasetIndex: number;
+    /**
+     * Data index.
+     */
+    index: number;
+    /**
+     * Dataset definition.
+     */
+    dataset: ChartDataset | null;
+    /**
+     * Label at the selected index.
+     */
+    label: unknown;
+    /**
+     * Data value.
+     */
+    value: unknown;
+    /**
+     * Engine-native event when available.
+     */
+    nativeEvent: Event | null;
+};
+export type ChartOptions = {
+    /**
+     * Injected engine adapter.
+     */
+    adapter?: ChartAdapter | null;
+    /**
+     * Chart type passed to the adapter.
+     */
+    type?: string;
+    /**
+     * Chart data.
+     */
+    data?: ChartData;
+    /**
+     * Engine-specific options.
+     */
+    chartOptions?: Record<string, unknown>;
+    /**
+     * Accessible canvas and summary label; blank text falls back to `Chart`.
+     */
+    label?: string;
+    /**
+     * Accessible description.
+     */
+    description?: string;
+    /**
+     * Semantic data-table presentation.
+     */
+    summary?: 'hidden' | 'visible';
+    /**
+     * Initial loading state.
+     */
+    loading?: boolean;
+    /**
+     * Empty-state text.
+     */
+    emptyText?: string;
+    /**
+     * Loading-state text.
+     */
+    loadingText?: string;
+    /**
+     * Error fallback text.
+     */
+    errorText?: string;
+    /**
+     * Responsive container aspect ratio.
+     */
+    aspectRatio?: string;
+    /**
+     * Engine-ready listener.
+     */
+    onready?: (event: CustomEvent<{
+        instance: unknown;
+    }>) => void;
+    /**
+     * Update listener.
+     */
+    onupdate?: (event: CustomEvent<{
+        data: ChartData;
+        type: string;
+    }>) => void;
+    /**
+     * Point-selection listener.
+     */
+    onselect?: (event: CustomEvent<ChartSelectDetail>) => void;
+    /**
+     * Engine error listener.
+     */
+    onerror?: (event: CustomEvent<{
+        error: unknown;
+    }>) => void;
+};
+/** @typedef {{label?: string, data?: unknown[], [key: string]: unknown}} ChartDataset */
+/** @typedef {{labels?: unknown[], datasets?: ChartDataset[], [key: string]: unknown}} ChartData */
+/**
+ * @typedef {Object} ChartSpec
+ * @property {string} type Chart type.
+ * @property {ChartData} data Chart data.
+ * @property {Record<string, unknown>} options Engine-specific options.
+ * @property {(detail: ChartSelectDetail) => void} onSelect Point-selection callback.
+ */
+/**
+ * @typedef {Object} ChartHandle
+ * @property {(spec: ChartSpec) => void} update Update the mounted chart.
+ * @property {() => void} resize Resize the mounted chart.
+ * @property {() => void} destroy Destroy the mounted chart.
+ * @property {unknown} [instance] Engine instance.
+ */
+/** @typedef {{create: (canvas: HTMLCanvasElement, spec: ChartSpec) => ChartHandle}} ChartAdapter */
+/**
+ * @typedef {Object} ChartJsAdapterOptions
+ * Generated API marker for the adapter class; its constructor accepts an injected engine and
+ * optional defaults directly rather than a component options object.
+ */
+/**
+ * @typedef {Object} ChartSelectDetail
+ * @property {number} datasetIndex Dataset index.
+ * @property {number} index Data index.
+ * @property {ChartDataset|null} dataset Dataset definition.
+ * @property {unknown} label Label at the selected index.
+ * @property {unknown} value Data value.
+ * @property {Event|null} nativeEvent Engine-native event when available.
+ */
+/**
+ * @typedef {Object} ChartOptions
+ * @property {ChartAdapter|null} [adapter=null] Injected engine adapter.
+ * @property {string} [type='bar'] Chart type passed to the adapter.
+ * @property {ChartData} [data={labels: [], datasets: []}] Chart data.
+ * @property {Record<string, unknown>} [chartOptions={}] Engine-specific options.
+ * @property {string} [label='Chart'] Accessible canvas and summary label; blank text falls back to `Chart`.
+ * @property {string} [description=''] Accessible description.
+ * @property {'hidden'|'visible'} [summary='hidden'] Semantic data-table presentation.
+ * @property {boolean} [loading=false] Initial loading state.
+ * @property {string} [emptyText='No chart data'] Empty-state text.
+ * @property {string} [loadingText='Loading chart…'] Loading-state text.
+ * @property {string} [errorText='Unable to render chart'] Error fallback text.
+ * @property {string} [aspectRatio='16 / 9'] Responsive container aspect ratio.
+ * @property {(event: CustomEvent<{instance: unknown}>) => void} [onready] Engine-ready listener.
+ * @property {(event: CustomEvent<{data: ChartData, type: string}>) => void} [onupdate] Update listener.
+ * @property {(event: CustomEvent<ChartSelectDetail>) => void} [onselect] Point-selection listener.
+ * @property {(event: CustomEvent<{error: unknown}>) => void} [onerror] Engine error listener.
+ */
+/**
+ * Accessible, engine-neutral chart host with explicit adapter lifecycle.
+ * @fires Chart#ready
+ * @fires Chart#update
+ * @fires Chart#select
+ * @fires Chart#error
+ * @extends {Component<ChartOptions>}
+ */
+export declare class Chart extends Component<ChartOptions> {
+    _createdRoot: boolean;
+    _original: {
+        attributes: string[][];
+        children: ChildNode[];
+    };
+    _adapter: ChartAdapter;
+    _type: string;
+    _data: ChartData;
+    _label: string;
+    _chartOptions: Record<string, unknown>;
+    _loading: boolean;
+    _error: unknown;
+    _handle: ChartHandle;
+    _destroyed: boolean;
+    _observer: ResizeObserver;
+    static cssName: string;
+    /** @type {Readonly<ChartOptions>} */
+    static defaults: Readonly<ChartOptions>;
+    /**
+     * Creates or enhances a chart host.
+     * @param {Element|string|null} target Chart target.
+     * @param {ChartOptions} [options={}] Chart options.
+     */
+    constructor(target?: Element | string | null, options?: ChartOptions);
+    /** @returns {HTMLElement} */
+    render(): HTMLElement;
+    /** Replaces chart data and updates or mounts the engine. @param {ChartData} data @returns {this} */
+    setData(data: ChartData): this;
+    /** Changes the chart type and updates/recreates the engine as needed. @param {string} type @returns {this} */
+    setType(type: string): this;
+    /** Replaces engine-specific options. @param {Record<string, unknown>} options @returns {this} */
+    update(options: Record<string, unknown>): this;
+    /** Replaces the engine adapter. @param {ChartAdapter|null} adapter @returns {this} */
+    setAdapter(adapter: ChartAdapter | null): this;
+    /** Toggles loading state. Loading charts do not keep an engine instance alive. @param {boolean} [loading=true] @returns {this} */
+    setLoading(loading?: boolean): this;
+    /** Shows an error and destroys the current engine. @param {unknown} error @returns {this} */
+    setError(error: unknown): this;
+    /** Clears the error and remounts when data and an adapter are available. @returns {this} */
+    clearError(): this;
+    /** Requests an engine resize. @returns {this} */
+    resize(): this;
+    /** Re-applies computed theme defaults through the adapter update path. @returns {this} */
+    refreshTheme(): this;
+    /** Returns the underlying engine instance when the adapter exposes it. @returns {unknown} */
+    getInstance(): unknown;
+    /** Destroys the engine/observer and restores or removes the host. @returns {void} */
+    destroy(): void;
+    /** @param {boolean} emitUpdate @returns {void} */
+    _mountOrUpdate(emitUpdate: boolean): void;
+    /** @returns {ChartSpec} */
+    _spec(): ChartSpec;
+    /** @returns {void} */
+    _destroyHandle(): void;
+    /** @returns {void} */
+    _syncState(): void;
+    /** @returns {void} */
+    _renderSummary(): void;
+}
+/**
+ * Adapter for an injected Chart.js 4 constructor or namespace.
+ */
+export declare class ChartJsAdapter {
+    engine: Function;
+    defaults: Record<string, unknown>;
+    /**
+     * @param {Function|{Chart?: Function}} engine Injected Chart.js constructor or namespace.
+     * @param {Record<string, unknown>} [defaults={}] Adapter-wide Chart.js options.
+     */
+    constructor(engine: Function | {
+        Chart?: Function;
+    }, defaults?: Record<string, unknown>);
+    /**
+     * Creates one Chart.js lifecycle handle.
+     * @param {HTMLCanvasElement} canvas Canvas.
+     * @param {ChartSpec} spec Initial chart specification.
+     * @returns {ChartHandle}
+     */
+    create(canvas: HTMLCanvasElement, spec: ChartSpec): ChartHandle;
+}
+/**
+ * Clones arrays and plain objects while preserving callbacks and engine-specific object instances.
+ * @template T
+ * @param {T} value Value.
+ * @returns {T}
+ */
+export declare function cloneChartValue<T>(value: T): T;
+/** @param {ChartData} data @returns {boolean} */
+export declare function isEmptyChartData(data: ChartData): boolean;
+/**
+ * Builds the semantic table mirrored alongside the canvas.
+ * @param {ChartData} data Chart data.
+ * @param {string} label Caption.
+ * @returns {HTMLTableElement}
+ */
+export declare function chartSummaryTable(data: ChartData, label?: string): HTMLTableElement;
+/**
+ * Produces the exact text matrix rendered by the semantic chart summary.
+ * @param {ChartData} data Chart data.
+ * @returns {{headers: string[], rows: Array<{label: string, values: string[]}>}}
+ */
+export declare function chartSummaryModel(data: ChartData): {
+    headers: string[];
+    rows: Array<{
+        label: string;
+        values: string[];
+    }>;
+};
+/** Fired after the adapter creates an engine instance. @event Chart#ready @type {CustomEvent<{instance: unknown}>} */
+/** Fired after an existing chart updates. @event Chart#update @type {CustomEvent<{data: ChartData, type: string}>} */
+/** Fired when the engine reports a selected point. @event Chart#select @type {CustomEvent<ChartSelectDetail>} */
+/** Fired when adapter creation/update fails. @event Chart#error @type {CustomEvent<{error: unknown}>} */

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

@@ -40,6 +40,12 @@ export declare class MonthPicker extends DatePicker {
     static cssName: string;
     /** @type {MonthPickerOptions} */
     static defaults: MonthPickerOptions;
+    /**
+     * Creates a month picker with its narrower month-based option contract.
+     * @param {Element|string|null} target Existing element, selector, or null.
+     * @param {MonthPickerOptions} [options={}] Month-picker options.
+     */
+    constructor(target: Element | string | null, options?: MonthPickerOptions);
     /** @returns {HTMLElement} */
     render(): HTMLElement;
     /** @returns {Date|null} */

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

@@ -281,4 +281,13 @@ export declare class Dialog extends Modal {
      * @returns {Promise<string|null>}
      */
     static prompt({ title, message, value, placeholder }?: PromptOptions): Promise<string | null>;
+    /**
+     * Applies the dialog width. Subclasses that size themselves on a different axis override this.
+     *
+     * Called from the constructor before any subclass field initializers have run, so an override
+     * may only touch the DOM — reading an uninitialized private field here throws.
+     * @param {'sm'|'md'|'lg'|number} size Preset or pixel width.
+     * @returns {void}
+     */
+    _applySize(size: 'sm' | 'md' | 'lg' | number): void;
 }