@zeyos/zx 2.1.0 → 2.2.1

package/dist/types/components/stepper/steps.d.ts

@@ -0,0 +1,131 @@
+/**
+ * DOM-free step-list logic shared by {@link Stepper}: validation, normalization, and the
+ * index arithmetic behind `next()` / `previous()`.
+ * @module components/stepper/steps
+ */
+export type StepDefinition = {
+    /**
+     * Stable step name, unique within the stepper.
+     */
+    name: string;
+    /**
+     * Visible step title.
+     */
+    title: string;
+    /**
+     * Secondary line rendered under the title.
+     */
+    description?: string;
+    /**
+     * Marks the step as skippable.
+     */
+    optional?: boolean;
+    /**
+     * Whether the step can be activated.
+     */
+    disabled?: boolean;
+};
+export type NormalizedStep = {
+    /**
+     * Stable step name.
+     */
+    name: string;
+    /**
+     * Visible step title.
+     */
+    title: string;
+    /**
+     * Secondary line, or null.
+     */
+    description: string | null;
+    /**
+     * Whether the step is skippable.
+     */
+    optional: boolean;
+    /**
+     * Whether the step can be activated.
+     */
+    disabled: boolean;
+};
+/**
+ * @typedef {Object} StepDefinition
+ * @property {string} name Stable step name, unique within the stepper.
+ * @property {string} title Visible step title.
+ * @property {string} [description] Secondary line rendered under the title.
+ * @property {boolean} [optional=false] Marks the step as skippable.
+ * @property {boolean} [disabled=false] Whether the step can be activated.
+ */
+/**
+ * @typedef {Object} NormalizedStep
+ * @property {string} name Stable step name.
+ * @property {string} title Visible step title.
+ * @property {string|null} description Secondary line, or null.
+ * @property {boolean} optional Whether the step is skippable.
+ * @property {boolean} disabled Whether the step can be activated.
+ */
+/**
+ * Validates and normalizes a step list. Every step needs a unique non-empty name; every other
+ * property is coerced to its documented type.
+ * @param {StepDefinition[]} list Step definitions.
+ * @returns {NormalizedStep[]} Normalized copies — the input objects are never mutated.
+ * @throws {TypeError} When the list or a step is malformed.
+ * @throws {RangeError} When two steps share a name.
+ */
+export declare function normalizeSteps(list: StepDefinition[]): NormalizedStep[];
+/**
+ * Returns the index of a step by name.
+ * @param {NormalizedStep[]} steps Normalized steps.
+ * @param {string|null} name Step name.
+ * @returns {number} Zero-based index, or -1 when the name is unknown or null.
+ */
+export declare function stepIndex(steps: NormalizedStep[], name: string | null): number;
+/**
+ * Resolves the next enabled step in a direction, skipping disabled steps. Starting from -1 walks
+ * in from the matching end, so `resolveStepIndex(steps, -1, 1)` is the first enabled step.
+ * @param {NormalizedStep[]} steps Normalized steps.
+ * @param {number} from Zero-based index to start from, or -1 for "outside the list".
+ * @param {number} direction Positive to move forward, negative to move backward.
+ * @returns {number} Zero-based index, or -1 when no enabled step lies that way.
+ */
+export declare function resolveStepIndex(steps: NormalizedStep[], from: number, direction: number): number;
+/**
+ * Names of the steps a move marks complete. Advancing past a step completes it — including every
+ * step skipped over by a jump — while moving backwards completes nothing, so a user can walk back
+ * through a wizard without erasing their progress.
+ * @param {NormalizedStep[]} steps Normalized steps.
+ * @param {number} from Zero-based index being left, or -1 when nothing was active.
+ * @param {number} to Zero-based index being activated.
+ * @returns {string[]} Names to add to the completed set, in step order.
+ */
+export declare function completedByAdvance(steps: NormalizedStep[], from: number, to: number): string[];
+export type StepStateContext = {
+    /**
+     * Zero-based active index, or -1 when nothing is active.
+     */
+    activeIndex?: number;
+    /**
+     * Completed step names.
+     */
+    completed?: Set<string> | string[];
+    /**
+     * Errored step names.
+     */
+    errored?: Set<string> | string[];
+};
+/**
+ * @typedef {Object} StepStateContext
+ * @property {number} [activeIndex=-1] Zero-based active index, or -1 when nothing is active.
+ * @property {Set<string>|string[]} [completed] Completed step names.
+ * @property {Set<string>|string[]} [errored] Errored step names.
+ */
+/**
+ * Resolves the rendered state of one step. Errors win over everything, so a step the user has to
+ * come back and fix stays visible as a problem even while it is the active one; being active in
+ * turn wins over being complete, because where the user stands matters more than where they have
+ * already been.
+ * @param {NormalizedStep} step Normalized step.
+ * @param {number} index Zero-based index of the step.
+ * @param {StepStateContext} [context={}] Rail state.
+ * @returns {'upcoming'|'active'|'complete'|'error'}
+ */
+export declare function stepState(step: NormalizedStep, index: number, context?: StepStateContext): 'upcoming' | 'active' | 'complete' | 'error';

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

@@ -0,0 +1,230 @@
+import { Component } from '../../core/component.js';
+export type TabContent = Node | Component | (() => Node | Component);
+export type TabDefinition = {
+    /**
+     * Stable tab name.
+     */
+    name: string;
+    /**
+     * Visible tab label.
+     */
+    title: string;
+    /**
+     * Panel content or a lazy content factory.
+     */
+    content: TabContent;
+    /**
+     * Icon name passed to `icon()`, shown before the title.
+     */
+    icon?: string;
+    /**
+     * Whether Delete can close the tab.
+     */
+    closable?: boolean;
+    /**
+     * Whether the tab is unavailable.
+     */
+    disabled?: boolean;
+};
+export type TabboxVariant = 'divided' | 'bracket' | 'line' | 'segmented';
+export type TabInsertOptions = {
+    /**
+     * Zero-based insertion index; omitted appends.
+     */
+    index?: number;
+};
+export type TabboxOptions = {
+    /**
+     * Initial tabs.
+     */
+    tabs?: TabDefinition[];
+    /**
+     * Initially active tab name, or the first enabled tab.
+     */
+    active?: string | null;
+    /**
+     * `divided` sets flat blocks on a muted track above
+     * a bordered panel; `bracket` outlines folder tabs that fuse into that panel; `line` underlines
+     * the active tab across a full-width rule; `segmented` renders a compact group that reads as one
+     * control, for a toolbar or card header.
+     */
+    variant?: TabboxVariant;
+    /**
+     * Keep inactive panel elements mounted.
+     */
+    keepAlive?: boolean;
+    /**
+     * Change callback.
+     */
+    onchange?: (event: CustomEvent<{
+        name: string;
+        previous: string | null;
+    }>) => void;
+    /**
+     * Close callback.
+     */
+    onclose?: (event: CustomEvent<{
+        name: string;
+    }>) => void;
+};
+export type TabRecord = {
+    /**
+     * Normalized definition.
+     */
+    definition: TabDefinition;
+    /**
+     * Tab element.
+     */
+    tab: HTMLButtonElement;
+    /**
+     * Title element.
+     */
+    title: HTMLElement;
+    /**
+     * Badge element.
+     */
+    badge: HTMLElement;
+    /**
+     * Tab panel.
+     */
+    panel: HTMLElement;
+    /**
+     * Whether content has been mounted.
+     */
+    built: boolean;
+};
+/**
+ * @typedef {Object} TabInsertOptions
+ * @property {number} [index] Zero-based insertion index; omitted appends.
+ */
+/**
+ * @typedef {Object} TabboxOptions
+ * @property {TabDefinition[]} [tabs=[]] Initial tabs.
+ * @property {string|null} [active=null] Initially active tab name, or the first enabled tab.
+ * @property {TabboxVariant} [variant='divided'] `divided` sets flat blocks on a muted track above
+ *   a bordered panel; `bracket` outlines folder tabs that fuse into that panel; `line` underlines
+ *   the active tab across a full-width rule; `segmented` renders a compact group that reads as one
+ *   control, for a toolbar or card header.
+ * @property {boolean} [keepAlive=true] Keep inactive panel elements mounted.
+ * @property {(event: CustomEvent<{name: string, previous: string|null}>) => void} [onchange] Change callback.
+ * @property {(event: CustomEvent<{name: string}>) => void} [onclose] Close callback.
+ */
+/**
+ * @typedef {Object} TabRecord
+ * @property {TabDefinition} definition Normalized definition.
+ * @property {HTMLButtonElement} tab Tab element.
+ * @property {HTMLElement} title Title element.
+ * @property {HTMLElement} badge Badge element.
+ * @property {HTMLElement} panel Tab panel.
+ * @property {boolean} built Whether content has been mounted.
+ */
+/**
+ * APG tabs with roving focus and manual activation.
+ * @fires Tabbox#change
+ * @fires Tabbox#close
+ * @extends {Component<TabboxOptions>}
+ */
+export declare class Tabbox extends Component<TabboxOptions> {
+    _createdRoot: boolean;
+    _original: {
+        attributes: Array<[string, string]>;
+        children: Node[];
+    };
+    _cleaned: boolean;
+    /** @type {TabRecord[]} */
+    _tabs: TabRecord[];
+    /** @type {TabRecord|null} */
+    _active: TabRecord | null;
+    _keepAlive: boolean;
+    _initializing: boolean;
+    static cssName: string;
+    /** @type {Readonly<TabboxOptions>} */
+    static defaults: Readonly<TabboxOptions>;
+    /**
+     * Creates or enhances a tabbox.
+     * @param {Element|string|null} target Existing container, selector, or null.
+     * @param {TabboxOptions} [options={}] Tabbox options.
+     */
+    constructor(target: Element | string | null, options?: TabboxOptions);
+    /** @returns {HTMLElement} */
+    render(): HTMLElement;
+    /**
+     * Adds a tab.
+     * @param {TabDefinition} definition Tab definition.
+     * @param {TabInsertOptions} [insert={}] Insertion options.
+     * @returns {this}
+     */
+    addTab(definition: TabDefinition, insert?: TabInsertOptions): this;
+    /**
+     * Removes a tab by name.
+     * @param {string} name Tab name.
+     * @returns {this}
+     */
+    removeTab(name: string): this;
+    /**
+     * Activates an enabled tab unless its change event is vetoed.
+     * @param {string} name Tab name.
+     * @returns {this}
+     * @fires Tabbox#change
+     */
+    openTab(name: string): this;
+    /**
+     * Alias of `openTab()`.
+     * @param {string} name Tab name.
+     * @returns {this}
+     * @fires Tabbox#change
+     */
+    show(name: string): this;
+    /**
+     * Returns the active tab name.
+     * @returns {string|null}
+     */
+    getActive(): string | null;
+    /**
+     * Changes a tab title.
+     * @param {string} name Tab name.
+     * @param {string} title Next title.
+     * @returns {this}
+     */
+    setTitle(name: string, title: string): this;
+    /**
+     * Sets or clears a tab badge.
+     * @param {string} name Tab name.
+     * @param {string|null} text Badge text, or null to remove it.
+     * @returns {this}
+     */
+    setBadge(name: string, text: string | null): this;
+    /**
+     * Enables a tab.
+     * @param {string} name Tab name.
+     * @returns {this}
+     */
+    enableTab(name: string): this;
+    /**
+     * Disables a tab, moving selection when it is active.
+     * @param {string} name Tab name.
+     * @returns {this}
+     * @fires Tabbox#change
+     */
+    disableTab(name: string): this;
+    /** @returns {void} */
+    destroy(): void;
+    /** @param {KeyboardEvent} event @returns {void} */
+    _onKeydown(event: KeyboardEvent): void;
+    /** @param {string} name @param {boolean} emitClose @returns {boolean} */
+    _removeTab(name: string, emitClose: boolean): boolean;
+    /** @param {TabRecord} record @returns {void} */
+    _applyActive(record: TabRecord): void;
+    /** @param {TabRecord} record @returns {void} */
+    _ensureContent(record: TabRecord): void;
+    /** @param {TabRecord} record @param {boolean} [focus=true] @returns {void} */
+    _setFocused(record: TabRecord, focus?: boolean): void;
+    /** @returns {TabRecord[]} */
+    _enabledTabs(): TabRecord[];
+    /** @param {string} name @returns {TabRecord|null} */
+    _find(name: string): TabRecord | null;
+    /** @param {string} name @returns {TabRecord} */
+    _require(name: string): TabRecord;
+    /** @param {Element} tab @returns {TabRecord|null} */
+    _recordForTab(tab: Element): TabRecord | null;
+}

package/dist/types/components/table/sort.d.ts

@@ -0,0 +1,49 @@
+/** @typedef {'asc'|'desc'} SortDirection */
+export type SortDirection = 'asc' | 'desc';
+/**
+ * Compares strings with the host locale's collation rules.
+ * @param {unknown} left Left value.
+ * @param {unknown} right Right value.
+ * @returns {number} Negative, zero, or positive comparison result.
+ */
+export declare function compareStrings(left: unknown, right: unknown): number;
+/**
+ * Compares numeric values.
+ * @param {number} left Left value.
+ * @param {number} right Right value.
+ * @returns {number} Negative, zero, or positive comparison result.
+ */
+export declare function compareNumbers(left: number, right: number): number;
+/**
+ * Compares Date values by their timestamps.
+ * @param {Date} left Left date.
+ * @param {Date} right Right date.
+ * @returns {number} Negative, zero, or positive comparison result.
+ */
+export declare function compareDates(left: Date, right: Date): number;
+/**
+ * Compares values according to their runtime type. Nullish values are always placed last,
+ * including for descending sorts.
+ * @param {unknown} left Left value.
+ * @param {unknown} right Right value.
+ * @param {SortDirection} [direction='asc'] Sort direction.
+ * @returns {number} Negative, zero, or positive comparison result.
+ */
+export declare function compareValues(left: unknown, right: unknown, direction?: SortDirection): number;
+/**
+ * Creates a row comparator for a sort-value accessor.
+ * @template T
+ * @param {(row: T) => unknown} getValue Sort-value accessor.
+ * @param {SortDirection} [direction='asc'] Sort direction.
+ * @returns {(left: T, right: T) => number} Row comparator.
+ */
+export declare function createComparator<T>(getValue: (row: T) => unknown, direction?: SortDirection): (left: T, right: T) => number;
+/**
+ * Returns a stably sorted copy of an array without mutating the input.
+ * @template T
+ * @param {T[]} rows Rows to sort.
+ * @param {(row: T) => unknown} getValue Sort-value accessor.
+ * @param {SortDirection} [direction='asc'] Sort direction.
+ * @returns {T[]} Sorted copy.
+ */
+export declare function sortRows<T>(rows: T[], getValue: (row: T) => unknown, direction?: SortDirection): T[];