@zeyos/zx 2.1.0 → 2.2.0

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

@@ -0,0 +1,132 @@
+export type StackOptions = {
+    /**
+     * Flow direction.
+     */
+    direction?: 'column' | 'row';
+    /**
+     * Space between children. A number 1–8 picks the matching
+     * `--zx-space-*` step; a string is used as-is.
+     */
+    gap?: number | string;
+    /**
+     * Cross-axis alignment.
+     */
+    align?: 'start' | 'center' | 'end' | 'stretch' | 'baseline';
+    /**
+     * Main-axis distribution.
+     */
+    justify?: 'start' | 'center' | 'end' | 'between' | 'around';
+    /**
+     * Whether a row wraps.
+     */
+    wrap?: boolean;
+    /**
+     * Whether the stack is laid out inline.
+     */
+    inline?: boolean;
+    /**
+     * Extra class names.
+     */
+    class?: string;
+};
+export type GridOptions = {
+    /**
+     * Column count at full width. Null fills the row with as
+     * many tracks of `min` width as fit.
+     */
+    columns?: number | null;
+    /**
+     * Narrowest a track may get before the grid drops a
+     * column. A number is read as pixels.
+     */
+    min?: number | string;
+    /**
+     * Space between cells, as in `stack`.
+     */
+    gap?: number | string;
+    /**
+     * Block-axis alignment of each cell.
+     */
+    align?: 'start' | 'center' | 'end' | 'stretch';
+    /**
+     * Extra class names.
+     */
+    class?: string;
+};
+export type AspectOptions = {
+    /**
+     * Aspect ratio of the box.
+     */
+    ratio?: string;
+    /**
+     * How the single child fills the box.
+     */
+    fit?: 'cover' | 'contain' | 'fill';
+    /**
+     * Extra class names.
+     */
+    class?: string;
+};
+export type DomChild = import('../../core/dom.js').DomChild;
+/**
+ * @typedef {Object} StackOptions
+ * @property {'column'|'row'} [direction='column'] Flow direction.
+ * @property {number|string} [gap=4] Space between children. A number 1–8 picks the matching
+ *   `--zx-space-*` step; a string is used as-is.
+ * @property {'start'|'center'|'end'|'stretch'|'baseline'} [align] Cross-axis alignment.
+ * @property {'start'|'center'|'end'|'between'|'around'} [justify] Main-axis distribution.
+ * @property {boolean} [wrap=false] Whether a row wraps.
+ * @property {boolean} [inline=false] Whether the stack is laid out inline.
+ * @property {string} [class=''] Extra class names.
+ */
+/**
+ * @typedef {Object} GridOptions
+ * @property {number|null} [columns=null] Column count at full width. Null fills the row with as
+ *   many tracks of `min` width as fit.
+ * @property {number|string} [min='16rem'] Narrowest a track may get before the grid drops a
+ *   column. A number is read as pixels.
+ * @property {number|string} [gap=4] Space between cells, as in `stack`.
+ * @property {'start'|'center'|'end'|'stretch'} [align] Block-axis alignment of each cell.
+ * @property {string} [class=''] Extra class names.
+ */
+/**
+ * @typedef {Object} AspectOptions
+ * @property {string} [ratio='16 / 9'] Aspect ratio of the box.
+ * @property {'cover'|'contain'|'fill'} [fit='cover'] How the single child fills the box.
+ * @property {string} [class=''] Extra class names.
+ */
+/** @typedef {import('../../core/dom.js').DomChild} DomChild */
+/**
+ * Creates a one-dimensional flow of children with consistent spacing.
+ *
+ * Zx ships no page grid on purpose: an ERP screen is a shell of panels, and `SplitView`,
+ * `MasterPanel`, and `Panel` already own that layer. `stack` and `grid` are the small pieces that
+ * were missing under them — the spacing every form section, toolbar row, and card list was
+ * otherwise re-inventing with an ad-hoc flex rule.
+ *
+ * @param {StackOptions} [options={}] Stack options.
+ * @param {...DomChild} children Children.
+ * @returns {HTMLDivElement}
+ */
+export declare function stack(options?: StackOptions, ...children: DomChild[]): HTMLDivElement;
+/**
+ * Creates a grid that keeps its tracks readable, dropping a column when the container gets too
+ * narrow to hold them at `min` width.
+ *
+ * The reflow is intrinsic — `auto-fit` against a `min` track width — so a grid behaves the same
+ * in a full-width page, a split pane, and a modal. Nothing here consults the viewport, which is
+ * the usual reason a "responsive" grid still breaks inside a narrow panel.
+ *
+ * @param {GridOptions} [options={}] Grid options.
+ * @param {...DomChild} children Cells.
+ * @returns {HTMLDivElement}
+ */
+export declare function grid(options?: GridOptions, ...children: DomChild[]): HTMLDivElement;
+/**
+ * Creates a box that holds a fixed aspect ratio whatever its width, so an image, a map, or a
+ * chart placeholder reserves its space before it loads.
+ * @param {AspectOptions} [options={}] Aspect options.
+ * @param {...DomChild} children The single child to fit.
+ * @returns {HTMLDivElement}
+ */
+export declare function aspect(options?: AspectOptions, ...children: DomChild[]): HTMLDivElement;

package/dist/types/components/loading/inline-loading.d.ts

@@ -0,0 +1,86 @@
+import { Component } from '../../core/component.js';
+export type InlineLoadingOptions = {
+    /**
+     * Initial state.
+     */
+    status?: 'inactive' | 'active' | 'success' | 'error';
+    /**
+     * Text shown beside the indicator.
+     */
+    description?: string;
+    /**
+     * Indicator size.
+     */
+    size?: 'sm' | 'md';
+    /**
+     * Whether state changes are announced through `aria-live`.
+     */
+    live?: boolean;
+    /**
+     * State-change listener.
+     */
+    onstatuschange?: (event: CustomEvent<{
+        status: string;
+        description: string;
+    }>) => void;
+};
+/**
+ * The status line that replaces a spinner once the wait resolves — "Saving…" becoming "Saved" or
+ * "Could not save" in the same place, beside the control that started the work.
+ *
+ * The whole element is one polite live region, so a screen reader hears the outcome without the
+ * focus moving. Reach for `Message` instead when the outcome deserves a dismissible notification
+ * rather than a line of text that stays put.
+ *
+ * @fires InlineLoading#statuschange
+ * @extends {Component<InlineLoadingOptions>}
+ */
+export declare class InlineLoading extends Component<InlineLoadingOptions> {
+    _status: string;
+    _description: string;
+    _createdRoot: boolean;
+    _snapshot: import("../../core/dom.js").TargetSnapshot;
+    static cssName: string;
+    /** @type {InlineLoadingOptions} */
+    static defaults: InlineLoadingOptions;
+    /** @returns {HTMLElement} */
+    render(): HTMLElement;
+    /**
+     * Returns the current state.
+     * @returns {'inactive'|'active'|'success'|'error'}
+     */
+    get(): 'inactive' | 'active' | 'success' | 'error';
+    /**
+     * Returns the current description.
+     * @returns {string}
+     */
+    getDescription(): string;
+    /**
+     * Moves to a state, optionally replacing the description with it.
+     * @param {'inactive'|'active'|'success'|'error'} status Next state.
+     * @param {string} [description] Replacement description; the current one is kept when omitted.
+     * @param {{silent?: boolean}} [options={}] Set `silent` to suppress `statuschange`.
+     * @returns {this}
+     * @fires InlineLoading#statuschange
+     */
+    set(status: 'inactive' | 'active' | 'success' | 'error', description?: string, { silent }?: {
+        silent?: boolean;
+    }): this;
+    /**
+     * Replaces the description without changing the state.
+     * @param {string} description Text beside the indicator.
+     * @returns {this}
+     */
+    setDescription(description: string): this;
+    /** Paints the indicator and the description for the current state. @returns {void} */
+    _sync(): void;
+    /** @returns {Node[]} */
+    _indicator(): Node[];
+    /** Restores an enhanced target to the markup it had before the takeover. @returns {void} */
+    destroy(): void;
+}
+/**
+ * State change.
+ * @event InlineLoading#statuschange
+ * @type {CustomEvent<{status: string, description: string}>}
+ */

package/dist/types/components/loading/progress-bar.d.ts

@@ -0,0 +1,168 @@
+import { Component } from '../../core/component.js';
+export type ProgressBarOptions = {
+    /**
+     * Completed amount, clamped to `[0, max]`.
+     */
+    value?: number;
+    /**
+     * Amount that counts as finished.
+     */
+    max?: number;
+    /**
+     * Visible name of the task.
+     */
+    label?: string;
+    /**
+     * Supporting line below the track.
+     */
+    helperText?: string;
+    /**
+     * Visual state of the track.
+     */
+    status?: 'active' | 'success' | 'error';
+    /**
+     * Whether the amount done is unknown.
+     */
+    indeterminate?: boolean;
+    /**
+     * Track thickness.
+     */
+    size?: 'md' | 'sm';
+    /**
+     * Whether the label is kept for assistive technology only.
+     */
+    hideLabel?: boolean;
+    /**
+     * Whether the formatted value is drawn opposite the label.
+     */
+    showValue?: boolean;
+    /**
+     * Replaces the
+     * default percentage readout.
+     */
+    formatValue?: ((value: number, max: number) => string) | null;
+    /**
+     * Value listener.
+     */
+    onchange?: (event: CustomEvent<{
+        value: number;
+        percent: number;
+    }>) => void;
+    /**
+     * Listener for reaching `max`.
+     */
+    oncomplete?: (event: CustomEvent<{
+        value: number;
+    }>) => void;
+};
+/**
+ * @typedef {Object} ProgressBarOptions
+ * @property {number} [value=0] Completed amount, clamped to `[0, max]`.
+ * @property {number} [max=100] Amount that counts as finished.
+ * @property {string} [label=''] Visible name of the task.
+ * @property {string} [helperText=''] Supporting line below the track.
+ * @property {'active'|'success'|'error'} [status='active'] Visual state of the track.
+ * @property {boolean} [indeterminate=false] Whether the amount done is unknown.
+ * @property {'md'|'sm'} [size='md'] Track thickness.
+ * @property {boolean} [hideLabel=false] Whether the label is kept for assistive technology only.
+ * @property {boolean} [showValue=true] Whether the formatted value is drawn opposite the label.
+ * @property {((value: number, max: number) => string)|null} [formatValue=null] Replaces the
+ *   default percentage readout.
+ * @property {(event: CustomEvent<{value: number, percent: number}>) => void} [onchange] Value listener.
+ * @property {(event: CustomEvent<{value: number}>) => void} [oncomplete] Listener for reaching `max`.
+ */
+/**
+ * Determinate progress track for work whose completed share is known — a file upload, a batch
+ * posting run, an import.
+ *
+ * The track carries `role="progressbar"` and its ARIA value attributes, which is what a screen
+ * reader reports; an indeterminate bar drops `aria-valuenow` rather than reporting a fake number.
+ * `status` is a display concern only: a finished-with-errors bar still reads 100%.
+ *
+ * @fires ProgressBar#change
+ * @fires ProgressBar#complete
+ * @extends {Component<ProgressBarOptions>}
+ */
+export declare class ProgressBar extends Component<ProgressBarOptions> {
+    _value: number;
+    _createdRoot: boolean;
+    _snapshot: import("../../core/dom.js").TargetSnapshot;
+    _max: number;
+    _status: "active" | "error" | "success";
+    _indeterminate: boolean;
+    _labelId: string;
+    static cssName: string;
+    /** @type {ProgressBarOptions} */
+    static defaults: ProgressBarOptions;
+    /** @returns {HTMLElement} */
+    render(): HTMLElement;
+    /** Current value. @returns {number} */
+    get value(): number;
+    /** @param {number} next Next value. */
+    set value(next: number);
+    /**
+     * Returns the current value.
+     * @returns {number}
+     */
+    get(): number;
+    /**
+     * Sets the completed amount, clamped to `[0, max]`.
+     * @param {number} next Completed amount.
+     * @param {{silent?: boolean}} [options={}] Set `silent` to suppress events.
+     * @returns {this}
+     * @fires ProgressBar#change
+     * @fires ProgressBar#complete
+     */
+    set(next: number, { silent }?: {
+        silent?: boolean;
+    }): this;
+    /**
+     * Completed share of the track, as a number between 0 and 100.
+     * @returns {number}
+     */
+    percent(): number;
+    /**
+     * Replaces the upper bound, re-clamping the current value against it.
+     * @param {number} max New maximum.
+     * @returns {this}
+     */
+    setMax(max: number): this;
+    /**
+     * Sets the visual state, optionally replacing the helper line with it.
+     * @param {'active'|'success'|'error'} status Track state.
+     * @param {string} [helperText] Replacement helper line.
+     * @returns {this}
+     */
+    setStatus(status: 'active' | 'success' | 'error', helperText?: string): this;
+    /**
+     * Replaces the visible task name.
+     * @param {string} label Task name.
+     * @returns {this}
+     */
+    setLabel(label: string): this;
+    /**
+     * Replaces the supporting line below the track.
+     * @param {string} helperText Supporting line.
+     * @returns {this}
+     */
+    setHelperText(helperText: string): this;
+    /**
+     * Switches between a known and an unknown completed share.
+     * @param {boolean} [indeterminate=true] Whether the amount done is unknown.
+     * @returns {this}
+     */
+    setIndeterminate(indeterminate?: boolean): this;
+    /** Paints the track, the readout, and the ARIA value attributes. @returns {void} */
+    _sync(): void;
+    /** @returns {string} */
+    _format(): string;
+    /**
+     * The readout beside the label: the formatted value, prefixed by a status glyph once the run
+     * has finished one way or the other.
+     * @param {string} text Formatted value.
+     * @returns {Node[]}
+     */
+    _readout(text: string): Node[];
+    /** Restores an enhanced target to the markup it had before the takeover. @returns {void} */
+    destroy(): void;
+}

package/dist/types/components/loading/spinner.d.ts

@@ -0,0 +1,34 @@
+export type SpinnerOptions = {
+    /**
+     * Ring diameter: 16px, 24px, or 40px.
+     */
+    size?: 'sm' | 'md' | 'lg';
+    /**
+     * Accessible name. Empty renders a decorative ring that assistive
+     * technology skips — correct whenever a nearby element already announces the wait.
+     */
+    label?: string;
+    /**
+     * Whether the label is also drawn beside the ring.
+     */
+    showLabel?: boolean;
+    /**
+     * Ring colour: the accent token, or `currentColor`
+     * so the ring inherits the colour of the button or badge it sits in.
+     */
+    kind?: 'accent' | 'current';
+};
+/**
+ * Creates an indeterminate activity ring for a wait whose duration is unknown.
+ *
+ * Presentational and stateless: there is nothing to update and nothing to destroy, so this is a
+ * factory rather than a component. Use `ProgressBar` when the share of work done is known, and
+ * `InlineLoading` when the wait resolves into a success or error message in place.
+ *
+ * A spinner with a `label` announces itself through `role="status"`; without one it is marked
+ * `aria-hidden`, which is what a ring inside an already-labelled button wants.
+ *
+ * @param {SpinnerOptions} [opts={}] Spinner options.
+ * @returns {HTMLSpanElement}
+ */
+export declare function spinner(opts?: SpinnerOptions): HTMLSpanElement;

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

@@ -0,0 +1,112 @@
+import { Component } from '../../core/component.js';
+export type MasterPanelContent = string | Node | Component | null;
+export type MasterPanelButtonDescriptor = {
+    /**
+     * 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 MasterPanelButton = Element | MasterPanelButtonDescriptor;
+export type MasterPanelOptions = {
+    /**
+     * Header title.
+     */
+    title?: string;
+    /**
+     * Scrollable body content.
+     */
+    content?: MasterPanelContent;
+    /**
+     * Header action elements or button descriptors.
+     */
+    buttons?: MasterPanelButton[];
+    /**
+     * ZeyOS module name used for the header accent.
+     */
+    module?: string | null;
+    /**
+     * Optional fixed footer content.
+     */
+    footer?: MasterPanelContent;
+};
+/**
+ * @typedef {Object} MasterPanelOptions
+ * @property {string} [title=''] Header title.
+ * @property {MasterPanelContent} [content=null] Scrollable body content.
+ * @property {MasterPanelButton[]} [buttons=[]] Header action elements or button descriptors.
+ * @property {string|null} [module=null] ZeyOS module name used for the header accent.
+ * @property {MasterPanelContent} [footer=null] Optional fixed footer content.
+ */
+/**
+ * Full-height page panel with fixed header and footer bars.
+ * @extends {Component<MasterPanelOptions>}
+ */
+export declare class MasterPanel extends Component<MasterPanelOptions> {
+    _createdRoot: boolean;
+    _original: {
+        attributes: Array<[string, string]>;
+        children: Node[];
+    };
+    _cleaned: boolean;
+    static cssName: string;
+    /** @type {Readonly<MasterPanelOptions>} */
+    static defaults: Readonly<MasterPanelOptions>;
+    /**
+     * Creates or enhances a page-level panel.
+     * @param {Element|string|null} target Existing container, selector, or null.
+     * @param {MasterPanelOptions} [options={}] Master-panel options.
+     */
+    constructor(target: Element | string | null, options?: MasterPanelOptions);
+    /** @returns {HTMLElement} */
+    render(): HTMLElement;
+    /**
+     * Replaces the header title.
+     * @param {string} title Next title.
+     * @returns {this}
+     */
+    setTitle(title: string): this;
+    /**
+     * Replaces the scrollable body.
+     * @param {MasterPanelContent} content Next text, node, component, or null to clear.
+     * @returns {this}
+     */
+    setContent(content: MasterPanelContent): this;
+    /**
+     * Replaces the header action area.
+     * @param {MasterPanelButton[]} list Button descriptors or elements.
+     * @returns {this}
+     */
+    setButtons(list: MasterPanelButton[]): this;
+    /**
+     * Replaces or removes the fixed footer.
+     * @param {MasterPanelContent} content Next footer content, or null to remove it.
+     * @returns {this}
+     */
+    setFooter(content: MasterPanelContent): this;
+    /** @returns {void} */
+    destroy(): void;
+}

package/dist/types/components/menu-button/menu-button.d.ts

@@ -0,0 +1,142 @@
+import { Component } from '../../core/component.js';
+export type MenuItem = {
+    /**
+     * Item label.
+     */
+    label: string;
+    /**
+     * Kernel icon name.
+     */
+    icon?: string;
+    /**
+     * Value emitted on selection.
+     */
+    value?: unknown;
+    /**
+     * Whether selection is disabled.
+     */
+    disabled?: boolean;
+    /**
+     * Whether the action is dangerous.
+     */
+    danger?: boolean;
+    /**
+     * Selection callback.
+     */
+    onselect?: (value: unknown, item: MenuItem, menuButton: MenuButton) => void;
+};
+export type MenuButtonItem = MenuItem | '-';
+export type MenuButtonOptions = {
+    /**
+     * Trigger label.
+     */
+    label?: string;
+    /**
+     * Trigger icon name.
+     */
+    icon?: string | null;
+    /**
+     * Trigger button kind.
+     */
+    kind?: 'default' | 'primary' | 'danger' | 'ghost';
+    /**
+     * Menu items and separators.
+     */
+    items?: MenuButtonItem[];
+    /**
+     * Menu placement.
+     */
+    placement?: 'bottom-start' | 'bottom-end' | 'top-start' | 'top-end' | 'bottom' | 'top';
+    /**
+     * Select event listener.
+     */
+    onselect?: (event: CustomEvent<{
+        value: unknown;
+        item: MenuItem;
+    }>) => void;
+    /**
+     * Open event listener.
+     */
+    onopen?: (event: CustomEvent<Record<string, never>>) => void;
+    /**
+     * Close event listener.
+     */
+    onclose?: (event: CustomEvent<Record<string, never>>) => void;
+};
+/**
+ * @typedef {Object} MenuItem
+ * @property {string} label Item label.
+ * @property {string} [icon] Kernel icon name.
+ * @property {unknown} [value] Value emitted on selection.
+ * @property {boolean} [disabled=false] Whether selection is disabled.
+ * @property {boolean} [danger=false] Whether the action is dangerous.
+ * @property {(value: unknown, item: MenuItem, menuButton: MenuButton) => void} [onselect] Selection callback.
+ */
+/** @typedef {MenuItem|'-'} MenuButtonItem */
+/**
+ * @typedef {Object} MenuButtonOptions
+ * @property {string} [label=''] Trigger label.
+ * @property {string|null} [icon=null] Trigger icon name.
+ * @property {'default'|'primary'|'danger'|'ghost'} [kind='default'] Trigger button kind.
+ * @property {MenuButtonItem[]} [items=[]] Menu items and separators.
+ * @property {'bottom-start'|'bottom-end'|'top-start'|'top-end'|'bottom'|'top'} [placement='bottom-start'] Menu placement.
+ * @property {(event: CustomEvent<{value: unknown, item: MenuItem}>) => void} [onselect] Select event listener.
+ * @property {(event: CustomEvent<Record<string, never>>) => void} [onopen] Open event listener.
+ * @property {(event: CustomEvent<Record<string, never>>) => void} [onclose] Close event listener.
+ */
+/**
+ * APG menu-button trigger backed by an anchored Dropdown.
+ * @fires MenuButton#select
+ * @fires MenuButton#open
+ * @fires MenuButton#close
+ * @extends {Component<MenuButtonOptions>}
+ */
+export declare class MenuButton extends Component<MenuButtonOptions> {
+    #private;
+    static cssName: string;
+    /** @type {Readonly<MenuButtonOptions>} */
+    static defaults: Readonly<MenuButtonOptions>;
+    /**
+     * Creates or enhances a menu trigger button.
+     * @param {HTMLButtonElement|string|null} target Existing button, selector, or null to create one.
+     * @param {MenuButtonOptions} [options={}] Menu-button options.
+     */
+    constructor(target?: HTMLButtonElement | string | null, options?: MenuButtonOptions);
+    /**
+     * Creates a trigger when no target was provided.
+     * @returns {HTMLButtonElement}
+     */
+    render(): HTMLButtonElement;
+    /**
+     * Replaces menu items and separators.
+     * @param {MenuButtonItem[]} items Menu definitions.
+     * @returns {this}
+     */
+    setItems(items: MenuButtonItem[]): this;
+    /**
+     * Opens the menu.
+     * @returns {this}
+     */
+    open(): this;
+    /**
+     * Closes the menu.
+     * @returns {this}
+     */
+    close(): this;
+    /**
+     * Reports whether the menu is open.
+     * @returns {boolean}
+     */
+    isOpen(): boolean;
+    /**
+     * Sets the visible trigger label.
+     * @param {string} label Trigger label.
+     * @returns {this}
+     */
+    setLabel(label: string): this;
+    /**
+     * Destroys the menu, dropdown panel, and trigger enhancements.
+     * @returns {void}
+     */
+    destroy(): void;
+}