@zeyos/zx 2.2.1 → 3.0.0

package/dist/types/components/app-sidebar/app-sidebar.d.ts

@@ -0,0 +1,169 @@
+import { Component } from '../../core/component.js';
+import { AppRail } from '../app-rail/app-rail.js';
+export type AppNavItem = import('../app-rail/app-rail.js').AppNavItem;
+export type AppNavSelectDetail = import('../app-rail/app-rail.js').AppNavSelectDetail;
+export type AppSidebarOptions = {
+    /**
+     * Application navigation tree.
+     */
+    items?: AppNavItem[];
+    /**
+     * Active item id.
+     */
+    active?: string | number | null;
+    /**
+     * Initially expanded branch ids.
+     */
+    expanded?: Array<string | number>;
+    /**
+     * Whether the minimized AppRail is shown.
+     */
+    collapsed?: boolean;
+    /**
+     * Workspace side.
+     */
+    side?: 'left' | 'right';
+    /**
+     * Navigation accessible label.
+     */
+    label?: string;
+    /**
+     * Expanded header content.
+     */
+    header?: Node | string | number | {
+        toElement: () => Node | null;
+    } | null;
+    /**
+     * Expanded sticky footer content.
+     */
+    footer?: Node | string | number | {
+        toElement: () => Node | null;
+    } | null;
+    /**
+     * Minimized rail header content.
+     */
+    railHeader?: Node | string | number | {
+        toElement: () => Node | null;
+    } | null;
+    /**
+     * Minimized rail footer content.
+     */
+    railFooter?: Node | string | number | {
+        toElement: () => Node | null;
+    } | null;
+    /**
+     * Preventable action listener.
+     */
+    onselect?: (event: CustomEvent<AppNavSelectDetail>) => void;
+    /**
+     * Branch-state listener; bulk replacement reports null state.
+     */
+    onbranchchange?: (event: CustomEvent<{
+        item: AppNavItem | null;
+        id: string | number | null;
+        expanded: boolean | null;
+        ids: Array<string | number>;
+    }>) => void;
+    /**
+     * Presentation-state listener.
+     */
+    oncollapsechange?: (event: CustomEvent<{
+        collapsed: boolean;
+    }>) => void;
+};
+/** @typedef {import('../app-rail/app-rail.js').AppNavItem} AppNavItem */
+/** @typedef {import('../app-rail/app-rail.js').AppNavSelectDetail} AppNavSelectDetail */
+/**
+ * @typedef {Object} AppSidebarOptions
+ * @property {AppNavItem[]} [items=[]] Application navigation tree.
+ * @property {string|number|null} [active=null] Active item id.
+ * @property {Array<string|number>} [expanded=[]] Initially expanded branch ids.
+ * @property {boolean} [collapsed=false] Whether the minimized AppRail is shown.
+ * @property {'left'|'right'} [side='left'] Workspace side.
+ * @property {string} [label='Applications'] Navigation accessible label.
+ * @property {Node|string|number|{toElement: () => Node|null}|null} [header=null] Expanded header content.
+ * @property {Node|string|number|{toElement: () => Node|null}|null} [footer=null] Expanded sticky footer content.
+ * @property {Node|string|number|{toElement: () => Node|null}|null} [railHeader=null] Minimized rail header content.
+ * @property {Node|string|number|{toElement: () => Node|null}|null} [railFooter=null] Minimized rail footer content.
+ * @property {(event: CustomEvent<AppNavSelectDetail>) => void} [onselect] Preventable action listener.
+ * @property {(event: CustomEvent<{item: AppNavItem|null, id: string|number|null, expanded: boolean|null, ids: Array<string|number>}>) => void} [onbranchchange] Branch-state listener; bulk replacement reports null state.
+ * @property {(event: CustomEvent<{collapsed: boolean}>) => void} [oncollapsechange] Presentation-state listener.
+ */
+/**
+ * Expanded vertical application navigation; the only Xenon shell mode with inline descendants.
+ * @fires AppSidebar#select
+ * @fires AppSidebar#branchchange
+ * @fires AppSidebar#collapsechange
+ * @extends {Component<AppSidebarOptions>}
+ */
+export declare class AppSidebar extends Component<AppSidebarOptions> {
+    _railExpandButton: HTMLElement;
+    _rail: AppRail;
+    _createdRoot: boolean;
+    _original: {
+        attributes: string[][];
+        children: ChildNode[];
+    };
+    _items: import("../app-rail/app-rail.js").AppNavItem[];
+    _active: string | number;
+    _expanded: Set<string>;
+    _collapsed: boolean;
+    static cssName: string;
+    /** @type {Readonly<AppSidebarOptions>} */
+    static defaults: Readonly<AppSidebarOptions>;
+    /**
+     * Creates or enhances an application-sidebar host.
+     * @param {Element|string|null} target Sidebar target.
+     * @param {AppSidebarOptions} [options={}] Sidebar options.
+     */
+    constructor(target?: Element | string | null, options?: AppSidebarOptions);
+    /** @returns {HTMLElement} */
+    render(): HTMLElement;
+    /** Replaces the navigation tree in both expanded and rail presentations. @param {AppNavItem[]} items @returns {this} */
+    setItems(items: AppNavItem[]): this;
+    /** Sets the active id in both presentations without routing. @param {string|number|null} id @returns {this} */
+    setActive(id: string | number | null): this;
+    /** Replaces expanded branch ids. @param {Array<string|number>} ids @param {{silent?: boolean}} [options={}] @returns {this} */
+    setExpanded(ids: Array<string | number>, { silent }?: {
+        silent?: boolean;
+    }): this;
+    /** Returns expanded branch ids in navigation order. @returns {Array<string|number>} */
+    getExpanded(): Array<string | number>;
+    /** Toggles one inline branch. @param {string|number} id @param {{silent?: boolean}} [options={}] @returns {this} */
+    toggleBranch(id: string | number, { silent }?: {
+        silent?: boolean;
+    }): this;
+    /** Shows the expanded sidebar presentation. @param {{silent?: boolean}} [options={}] @returns {this} */
+    expand(options?: {
+        silent?: boolean;
+    }): this;
+    /** Shows the minimized AppRail presentation. @param {{silent?: boolean}} [options={}] @returns {this} */
+    collapse(options?: {
+        silent?: boolean;
+    }): this;
+    /** Sets expanded/minimized presentation while preserving branch state. @param {boolean} collapsed @param {{silent?: boolean}} [options={}] @returns {this} */
+    setCollapsed(collapsed: boolean, { silent }?: {
+        silent?: boolean;
+    }): this;
+    /** Reports whether the rail presentation is active. @returns {boolean} */
+    isCollapsed(): boolean;
+    /** Returns the composed minimized rail. @returns {AppRail} */
+    getRail(): AppRail;
+    /** Destroys the rail and restores/removes the sidebar host. @returns {void} */
+    destroy(): void;
+    /** @returns {void} */
+    _renderTree(): void;
+    /** @param {AppNavItem} item @param {number} level @returns {HTMLElement} */
+    _treeRow(item: AppNavItem, level: number): HTMLElement;
+    /** Handles dynamic tree controls without retaining detached nodes after a rerender. @param {Event} event @returns {void} */
+    _onTreeClick(event: Event): void;
+    /** @param {AppNavItem} item @param {Event} event @returns {void} */
+    _select(item: AppNavItem, event: Event): void;
+    /** @returns {void} */
+    _syncActive(): void;
+    /** @returns {void} */
+    _reconcileExpanded(): void;
+}
+/** Fired when a destination/action is activated. @event AppSidebar#select @type {CustomEvent<AppNavSelectDetail>} */
+/** Fired when an inline branch changes. @event AppSidebar#branchchange @type {CustomEvent<{item: AppNavItem|null, id: string|number|null, expanded: boolean|null, ids: Array<string|number>}>} */
+/** Fired when expanded/minimized presentation changes. @event AppSidebar#collapsechange @type {CustomEvent<{collapsed: boolean}>} */

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

@@ -0,0 +1,100 @@
+import { Component } from '../../core/component.js';
+export type AvatarOptions = {
+    /**
+     * Image URL.
+     */
+    src?: string | null;
+    /**
+     * Name used to derive fallback initials.
+     */
+    name?: string;
+    /**
+     * Explicit fallback initials.
+     */
+    initials?: string | null;
+    /**
+     * Accessible label; null makes the avatar decorative.
+     */
+    label?: string | null;
+    /**
+     * Preset (`sm`, `md`, `lg`) or pixel size.
+     */
+    size?: string | number;
+    /**
+     * Avatar shape.
+     */
+    shape?: 'circle' | 'rounded' | 'square';
+    /**
+     * Optional presence state.
+     */
+    status?: 'online' | 'away' | 'busy' | 'offline' | null;
+    /**
+     * Text alternative for the presence state.
+     */
+    statusLabel?: string | null;
+};
+/**
+ * @typedef {Object} AvatarOptions
+ * @property {string|null} [src=null] Image URL.
+ * @property {string} [name=''] Name used to derive fallback initials.
+ * @property {string|null} [initials=null] Explicit fallback initials.
+ * @property {string|null} [label=null] Accessible label; null makes the avatar decorative.
+ * @property {string|number} [size='md'] Preset (`sm`, `md`, `lg`) or pixel size.
+ * @property {'circle'|'rounded'|'square'} [shape='circle'] Avatar shape.
+ * @property {'online'|'away'|'busy'|'offline'|null} [status=null] Optional presence state.
+ * @property {string|null} [statusLabel=null] Text alternative for the presence state.
+ */
+/**
+ * Stable-size user image with deterministic initials fallback and optional presence state.
+ * @extends {Component<AvatarOptions>}
+ */
+export declare class Avatar extends Component<AvatarOptions> {
+    _createdRoot: boolean;
+    _original: {
+        attributes: string[][];
+        children: ChildNode[];
+    };
+    _state: {
+        src: string;
+        name: string;
+        initials: string;
+        label: string;
+        size: string | number;
+        shape: "circle" | "rounded" | "square";
+        status: "away" | "busy" | "offline" | "online";
+        statusLabel: string;
+    };
+    static cssName: string;
+    /** @type {Readonly<AvatarOptions>} */
+    static defaults: Readonly<AvatarOptions>;
+    /** @returns {HTMLElement} */
+    render(): HTMLElement;
+    /**
+     * Replaces avatar identity and presentation values.
+     * @param {Partial<AvatarOptions>} values New values.
+     * @returns {this}
+     */
+    set(values?: Partial<AvatarOptions>): this;
+    /** Sets the presence state and its text alternative. @param {AvatarOptions['status']} status @param {string|null} [label=null] @returns {this} */
+    setStatus(status: AvatarOptions['status'], label?: string | null): this;
+    /** Returns whether the image is currently visible. @returns {boolean} */
+    hasImage(): boolean;
+    /** Restores an enhanced target or removes an owned root. @returns {void} */
+    destroy(): void;
+    /** @returns {void} */
+    _sync(): void;
+    /** Synchronizes the standalone accessible name, including valid presence text. @returns {void} */
+    _syncLabel(): void;
+    /** @param {boolean} visible @returns {void} */
+    _showImage(visible: boolean): void;
+    /** Ignores a late load/error from a source that has already been replaced. @returns {boolean} */
+    _isCurrentImageSource(): boolean;
+    /** @returns {void} */
+    _syncStatus(): void;
+}
+/**
+ * Derives at most two uppercase initials from the first and last words of a name.
+ * @param {unknown} name Name-like value.
+ * @returns {string}
+ */
+export declare function avatarInitials(name: unknown): string;

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;
 }