@zeyos/zx 2.1.0 → 2.2.0

package/dist/types/components/split-view/split-view.d.ts

@@ -0,0 +1,335 @@
+import { Component } from '../../core/component.js';
+export type SplitViewContent = string | Node | Component | null;
+export type SplitViewOptions = {
+    /**
+     * Split axis. `horizontal` puts the
+     * panes side by side behind a vertical divider; `vertical` stacks them behind a horizontal one.
+     */
+    orientation?: 'horizontal' | 'vertical';
+    /**
+     * Leading pane content (left, or top).
+     */
+    start?: SplitViewContent;
+    /**
+     * Trailing pane content (right, or bottom).
+     */
+    end?: SplitViewContent;
+    /**
+     * Initial size of the START pane. A number is pixels, a
+     * string is any CSS length the browser understands; `%` resolves against the container.
+     */
+    size?: number | string;
+    /**
+     * Smallest the start pane may become, in pixels.
+     */
+    min?: number;
+    /**
+     * Largest the start pane may become, in pixels; null means "as
+     * large as the container allows".
+     */
+    max?: number | null;
+    /**
+     * Which pane Enter/Space on the divider hides.
+     */
+    collapsible?: false | 'start' | 'end';
+    /**
+     * Whether a pane starts collapsed; `true` uses
+     * the `collapsible` pane.
+     */
+    collapsed?: boolean | 'start' | 'end';
+    /**
+     * Snap radius in pixels. A drag that ends within this distance of the
+     * initial size, the minimum, or the maximum lands exactly on it. `0` disables snapping.
+     */
+    snap?: number;
+    /**
+     * Key under which the size is remembered between visits.
+     * Storage failures degrade to memory rather than throwing.
+     */
+    storageKey?: string | null;
+    /**
+     * Whether resizing is blocked.
+     */
+    disabled?: boolean;
+    /**
+     * Accessible name of the divider.
+     */
+    label?: string;
+    /**
+     * Resize listener.
+     */
+    onresize?: (event: CustomEvent<{
+        size: number;
+        ratio: number;
+    }>) => void;
+    /**
+     * Resize-end listener.
+     */
+    onresizeend?: (event: CustomEvent<{
+        size: number;
+        ratio: number;
+    }>) => void;
+    /**
+     * Collapse listener.
+     */
+    oncollapse?: (event: CustomEvent<{
+        pane: 'start' | 'end';
+    }>) => void;
+    /**
+     * Expand listener.
+     */
+    onexpand?: (event: CustomEvent<Record<string, never>>) => void;
+};
+/** @typedef {string|Node|Component|null} SplitViewContent */
+/**
+ * @typedef {Object} SplitViewOptions
+ * @property {'horizontal'|'vertical'} [orientation='horizontal'] Split axis. `horizontal` puts the
+ *   panes side by side behind a vertical divider; `vertical` stacks them behind a horizontal one.
+ * @property {SplitViewContent} [start=null] Leading pane content (left, or top).
+ * @property {SplitViewContent} [end=null] Trailing pane content (right, or bottom).
+ * @property {number|string} [size='38%'] Initial size of the START pane. A number is pixels, a
+ *   string is any CSS length the browser understands; `%` resolves against the container.
+ * @property {number} [min=160] Smallest the start pane may become, in pixels.
+ * @property {number|null} [max=null] Largest the start pane may become, in pixels; null means "as
+ *   large as the container allows".
+ * @property {false|'start'|'end'} [collapsible=false] Which pane Enter/Space on the divider hides.
+ * @property {boolean|'start'|'end'} [collapsed=false] Whether a pane starts collapsed; `true` uses
+ *   the `collapsible` pane.
+ * @property {number} [snap=0] Snap radius in pixels. A drag that ends within this distance of the
+ *   initial size, the minimum, or the maximum lands exactly on it. `0` disables snapping.
+ * @property {string|null} [storageKey=null] Key under which the size is remembered between visits.
+ *   Storage failures degrade to memory rather than throwing.
+ * @property {boolean} [disabled=false] Whether resizing is blocked.
+ * @property {string} [label='Resize panes'] Accessible name of the divider.
+ * @property {(event: CustomEvent<{size: number, ratio: number}>) => void} [onresize] Resize listener.
+ * @property {(event: CustomEvent<{size: number, ratio: number}>) => void} [onresizeend] Resize-end listener.
+ * @property {(event: CustomEvent<{pane: 'start'|'end'}>) => void} [oncollapse] Collapse listener.
+ * @property {(event: CustomEvent<Record<string, never>>) => void} [onexpand] Expand listener.
+ */
+/**
+ * Two panes and a draggable divider between them.
+ *
+ * The layout is a three-track CSS grid driven by a single custom property, `--zx-split-size`, so a
+ * drag writes one style value per frame and the browser does the rest — no per-pane width
+ * arithmetic, no reflow storm. The property holds whatever was asked for: `38%` stays a percentage
+ * and keeps tracking the container until someone drags, at which point it becomes a pixel value
+ * and stays put.
+ *
+ * The divider follows the WAI-ARIA window splitter pattern: it is a focusable `separator` carrying
+ * live `aria-valuenow`/`aria-valuemin`/`aria-valuemax` in pixels, it moves with the arrow keys, and
+ * — where the component is `collapsible` — Enter or Space folds a pane away.
+ * @fires SplitView#resize
+ * @fires SplitView#resizeend
+ * @fires SplitView#collapse
+ * @fires SplitView#expand
+ * @extends {Component<SplitViewOptions>}
+ */
+export declare class SplitView extends Component<SplitViewOptions> {
+    #private;
+    _orientation: string;
+    /** Current start size in pixels, or null while the CSS value in the property is in charge. */
+    _size: number;
+    /** @type {'start'|'end'|null} */
+    _collapsed: 'start' | 'end' | null;
+    _disabled: boolean;
+    _destroyed: boolean;
+    _dragging: boolean;
+    /** Handle of the frame a pending drag update is scheduled in; `0` if none. */
+    _frame: number;
+    /** @type {number|null} */
+    _pointerId: number | null;
+    _startClient: number;
+    _startSize: number;
+    _pointerClient: number;
+    /** Whether the pointer left its starting position, which separates a drag from a click. */
+    _moved: boolean;
+    /** Container size of the last observer pass; `-1` forces the next one to run. */
+    _lastTotal: any;
+    _createdRoot: boolean;
+    _snapshot: import("../../core/dom.js").TargetSnapshot;
+    static cssName: string;
+    /** @type {Readonly<SplitViewOptions>} */
+    static defaults: Readonly<SplitViewOptions>;
+    /**
+     * Creates a split view, or turns an existing element into one.
+     * @param {Element|string|null} [target=null] Existing container, selector, or null to create one.
+     * @param {SplitViewOptions} [options={}] Split-view options.
+     */
+    constructor(target?: Element | string | null, options?: SplitViewOptions);
+    /**
+     * Builds the panes and the divider. Runs inside the base constructor, before any class field
+     * exists, so every value it needs later is an ordinary instance property assigned here.
+     * @returns {HTMLElement}
+     */
+    render(): HTMLElement;
+    /**
+     * Sets the start pane size. Pixels and percentages are clamped against `min`, `max`, and the
+     * container immediately; any other CSS length is handed to the browser unclamped. Programmatic,
+     * so it emits nothing.
+     * @param {number|string} value Pixel number or CSS length.
+     * @returns {this}
+     */
+    setSize(value: number | string): this;
+    /**
+     * Returns the start pane's current size in pixels: `0` while the start pane is collapsed, and
+     * everything but the divider while the end pane is.
+     * @returns {number}
+     */
+    getSize(): number;
+    /**
+     * Returns the start pane's share of the container, between 0 and 1.
+     * @returns {number}
+     */
+    getRatio(): number;
+    /**
+     * Replaces the start pane's content.
+     * @param {SplitViewContent} content Text, node, component, or null to empty the pane.
+     * @returns {this}
+     */
+    setStart(content: SplitViewContent): this;
+    /**
+     * Replaces the end pane's content.
+     * @param {SplitViewContent} content Text, node, component, or null to empty the pane.
+     * @returns {this}
+     */
+    setEnd(content: SplitViewContent): this;
+    /**
+     * Folds one pane away, keeping the remembered size for `expand()`. Works whatever `collapsible`
+     * says — that option only governs the keyboard affordance.
+     * @param {'start'|'end'} [which] Pane to hide; defaults to the `collapsible` pane, else `start`.
+     * @returns {this}
+     * @fires SplitView#collapse
+     */
+    collapse(which?: 'start' | 'end'): this;
+    /**
+     * Restores a collapsed pane to the size it had.
+     * @returns {this}
+     * @fires SplitView#expand
+     */
+    expand(): this;
+    /**
+     * Reports which pane is collapsed, if any.
+     * @returns {'start'|'end'|false}
+     */
+    isCollapsed(): 'start' | 'end' | false;
+    /**
+     * Allows resizing again and puts the divider back in the tab order.
+     * @returns {this}
+     */
+    enable(): this;
+    /**
+     * Blocks pointer and keyboard resizing and takes the divider out of the tab order. Any drag in
+     * flight ends immediately.
+     * @returns {this}
+     */
+    disable(): this;
+    /**
+     * Reports whether resizing is blocked.
+     * @returns {boolean}
+     */
+    isDisabled(): boolean;
+    /**
+     * Disconnects the observer, drops listeners, and restores an enhanced target's original content.
+     * @returns {void}
+     */
+    destroy(): void;
+}
+export type SizeBounds = {
+    /**
+     * Smallest legal start size in pixels.
+     */
+    min: number;
+    /**
+     * Largest legal start size in pixels.
+     */
+    max: number;
+};
+export type ClampSizeInput = {
+    /**
+     * Requested start size in pixels.
+     */
+    size: number;
+    /**
+     * Smallest start size in pixels.
+     */
+    min?: number;
+    /**
+     * Largest start size in pixels, or null for "whatever fits".
+     */
+    max?: number | null;
+    /**
+     * Container size along the split axis, in pixels.
+     */
+    total?: number;
+    /**
+     * Divider thickness, in pixels.
+     */
+    divider?: number;
+};
+/**
+ * Fired while the divider moves, at most once per animation frame during a drag.
+ * @event SplitView#resize
+ * @type {CustomEvent<{size: number, ratio: number}>}
+ */
+/**
+ * Fired once an interaction settles: a drag ends, a key moves the divider, or a double-click
+ * resets it.
+ * @event SplitView#resizeend
+ * @type {CustomEvent<{size: number, ratio: number}>}
+ */
+/**
+ * Fired when a pane folds away.
+ * @event SplitView#collapse
+ * @type {CustomEvent<{pane: 'start'|'end'}>}
+ */
+/**
+ * Fired when a collapsed pane comes back.
+ * @event SplitView#expand
+ * @type {CustomEvent<Record<string, never>>}
+ */
+/**
+ * @typedef {Object} SizeBounds
+ * @property {number} min Smallest legal start size in pixels.
+ * @property {number} max Largest legal start size in pixels.
+ */
+/**
+ * @typedef {Object} ClampSizeInput
+ * @property {number} size Requested start size in pixels.
+ * @property {number} [min=0] Smallest start size in pixels.
+ * @property {number|null} [max=null] Largest start size in pixels, or null for "whatever fits".
+ * @property {number} [total=0] Container size along the split axis, in pixels.
+ * @property {number} [divider=0] Divider thickness, in pixels.
+ */
+/**
+ * Restricts a start-pane size to what the container can actually give it.
+ *
+ * The upper bound is never more than the space left after the divider, so the trailing pane can
+ * never be pushed to a negative size; when the container is too small even for `min`, the minimum
+ * yields rather than overflowing. A container that measures zero or less — a hidden tab, a node
+ * that is not in the document — has nothing to clamp against, so the requested size passes through
+ * untouched instead of being flattened to zero.
+ * @param {ClampSizeInput} input Requested size and the geometry around it.
+ * @returns {number} A size in pixels, never negative.
+ */
+export declare function clampSize({ size, min, max, total, divider }: ClampSizeInput): number;
+/**
+ * Resolves a size option to pixels without touching the DOM.
+ *
+ * Numbers, bare numeric strings, and `px` lengths are pixels; a percentage resolves against
+ * `total`. Every other CSS length — `rem`, `vh`, `calc()` — needs the browser, so it returns `NaN`
+ * and the caller hands the value to CSS instead of guessing at it.
+ * @param {number|string} value Size option.
+ * @param {number} total Container size along the split axis, in pixels.
+ * @returns {number} Pixels, or `NaN` when only the browser can resolve the value.
+ */
+export declare function resolveSize(value: number | string, total: number): number;
+/**
+ * Pulls a size onto the nearest target within a radius, leaving it alone when nothing is close.
+ * The radius is inclusive, ties go to the target listed first, and a radius of zero or less turns
+ * snapping off.
+ * @param {number} size Size in pixels.
+ * @param {number[]|number|null|undefined} targets Sizes worth landing exactly on.
+ * @param {number} threshold Snap radius in pixels.
+ * @returns {number}
+ */
+export declare function snapSize(size: number, targets: number[] | number | null | undefined, threshold: number): number;

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

@@ -0,0 +1,314 @@
+import { Component } from '../../core/component.js';
+export type StepDefinition = import('./steps.js').StepDefinition;
+export type NormalizedStep = import('./steps.js').NormalizedStep;
+export type StepperOrientation = 'horizontal' | 'vertical';
+export type StepperClickable = 'completed' | 'all' | false;
+export type StepperStepState = 'upcoming' | 'active' | 'complete' | 'error';
+export type StepperOptions = {
+    /**
+     * Ordered step definitions.
+     */
+    steps?: StepDefinition[];
+    /**
+     * Initially active step name; defaults to the first enabled step.
+     */
+    active?: string | null;
+    /**
+     * `horizontal` lays the rail out above the
+     * stage, `vertical` puts it beside the stage.
+     */
+    orientation?: StepperOrientation;
+    /**
+     * Which steps are activated by a click:
+     * `completed` (go back only), `all`, or `false` for a display-only rail.
+     */
+    clickable?: StepperClickable;
+    /**
+     * Whether upcoming and active markers show their number.
+     */
+    showNumbers?: boolean;
+    /**
+     * Whether to render a "Step 2 of 4" line above the rail.
+     */
+    counter?: boolean;
+    /**
+     * Localized messages.
+     */
+    msg?: Record<string, string> | Record<string, Record<string, string>>;
+    /**
+     * Change listener.
+     */
+    onchange?: (event: CustomEvent<StepperChangeDetail>) => void;
+};
+export type StepperChangeDetail = {
+    /**
+     * Name of the step being activated.
+     */
+    name: string;
+    /**
+     * Name of the step being left, or null.
+     */
+    previous: string | null;
+    /**
+     * Zero-based index of the step being activated.
+     */
+    index: number;
+};
+export type StepperState = {
+    /**
+     * Active step name.
+     */
+    active: string | null;
+    /**
+     * Zero-based active index, or -1 when nothing is active.
+     */
+    index: number;
+    /**
+     * Completed step names, in step order.
+     */
+    completed: string[];
+    /**
+     * Errored step names, in step order.
+     */
+    errored: string[];
+};
+export type StepRecord = {
+    /**
+     * Normalized definition.
+     */
+    step: NormalizedStep;
+    /**
+     * List item carrying `data-state` and `aria-current`.
+     */
+    item: HTMLLIElement;
+    /**
+     * Button (clickable rails) or span (display-only rails).
+     */
+    control: HTMLElement;
+    /**
+     * Number / check / warning bubble.
+     */
+    marker: HTMLElement;
+    /**
+     * Visually hidden state text for assistive technology.
+     */
+    status: HTMLElement;
+};
+/**
+ * @typedef {Object} StepperOptions
+ * @property {StepDefinition[]} [steps=[]] Ordered step definitions.
+ * @property {string|null} [active=null] Initially active step name; defaults to the first enabled step.
+ * @property {StepperOrientation} [orientation='horizontal'] `horizontal` lays the rail out above the
+ *   stage, `vertical` puts it beside the stage.
+ * @property {StepperClickable} [clickable='completed'] Which steps are activated by a click:
+ *   `completed` (go back only), `all`, or `false` for a display-only rail.
+ * @property {boolean} [showNumbers=true] Whether upcoming and active markers show their number.
+ * @property {boolean} [counter=false] Whether to render a "Step 2 of 4" line above the rail.
+ * @property {Record<string, string>|Record<string, Record<string, string>>} [msg] Localized messages.
+ * @property {(event: CustomEvent<StepperChangeDetail>) => void} [onchange] Change listener.
+ */
+/**
+ * @typedef {Object} StepperChangeDetail
+ * @property {string} name Name of the step being activated.
+ * @property {string|null} previous Name of the step being left, or null.
+ * @property {number} index Zero-based index of the step being activated.
+ */
+/**
+ * @typedef {Object} StepperState
+ * @property {string|null} active Active step name.
+ * @property {number} index Zero-based active index, or -1 when nothing is active.
+ * @property {string[]} completed Completed step names, in step order.
+ * @property {string[]} errored Errored step names, in step order.
+ */
+/**
+ * @typedef {Object} StepRecord
+ * @property {NormalizedStep} step Normalized definition.
+ * @property {HTMLLIElement} item List item carrying `data-state` and `aria-current`.
+ * @property {HTMLElement} control Button (clickable rails) or span (display-only rails).
+ * @property {HTMLElement} marker Number / check / warning bubble.
+ * @property {HTMLElement} status Visually hidden state text for assistive technology.
+ */
+/**
+ * A wizard progress rail: an ordered list of steps, each in one of four states, with the active
+ * step marked `aria-current="step"`. Advancing past a step marks it complete automatically, so a
+ * wizard only has to call `next()` / `previous()` and veto `change` when validation fails.
+ *
+ * The rail owns no stage: it reports where the user is and where they asked to go. Rendering the
+ * step's content stays with the application, exactly as in the checkout and record wizards.
+ * @fires Stepper#change
+ * @extends {Component<StepperOptions>}
+ */
+export declare class Stepper extends Component<StepperOptions> {
+    _createdRoot: boolean;
+    _snapshot: import("../../core/dom.js").TargetSnapshot;
+    _destroyed: boolean;
+    /** @type {NormalizedStep[]} */
+    _steps: NormalizedStep[];
+    /** @type {StepRecord[]} */
+    _records: StepRecord[];
+    _activeIndex: any;
+    /** @type {Set<string>} */
+    _completed: Set<string>;
+    /** @type {Set<string>} */
+    _errored: Set<string>;
+    static cssName: string;
+    /** @type {Readonly<StepperOptions>} */
+    static defaults: Readonly<StepperOptions>;
+    /**
+     * Creates or enhances a stepper.
+     * @param {Element|string|null} target Existing container, selector, or null.
+     * @param {StepperOptions} [options={}] Stepper options.
+     */
+    constructor(target: Element | string | null, options?: StepperOptions);
+    /**
+     * Builds the rail. Runs inside the base constructor, so every piece of instance state it needs
+     * is initialized here rather than in class fields.
+     * @returns {HTMLElement}
+     */
+    render(): HTMLElement;
+    /**
+     * Replaces the whole step list. Completion and error flags survive for steps that are still
+     * present, and so does the active step; when it is gone the first enabled step takes over. This
+     * is a structural change, so it never emits `change`.
+     * @param {StepDefinition[]} list Step definitions.
+     * @returns {this}
+     */
+    setSteps(list: StepDefinition[]): this;
+    /**
+     * Activates a step unless its `change` event is vetoed. Disabled steps are ignored.
+     * @param {string} name Step name.
+     * @returns {this}
+     * @throws {RangeError} When no step carries that name.
+     * @fires Stepper#change
+     */
+    goTo(name: string): this;
+    /**
+     * Activates the next enabled step, marking the current one complete. Does nothing on the last
+     * enabled step.
+     * @returns {this}
+     * @fires Stepper#change
+     */
+    next(): this;
+    /**
+     * Activates the previous enabled step. Going back never clears completion flags.
+     * @returns {this}
+     * @fires Stepper#change
+     */
+    previous(): this;
+    /**
+     * Returns the active step name.
+     * @returns {string|null}
+     */
+    getActive(): string | null;
+    /**
+     * Returns the zero-based active index.
+     * @returns {number} -1 when no step is active.
+     */
+    getIndex(): number;
+    /**
+     * Marks a step complete.
+     * @param {string} name Step name.
+     * @returns {this}
+     */
+    complete(name: string): this;
+    /**
+     * Clears a step's completion flag.
+     * @param {string} name Step name.
+     * @returns {this}
+     */
+    uncomplete(name: string): this;
+    /**
+     * Flags or clears a step's error state. An errored step renders a warning marker and keeps its
+     * completion flag, so a wizard can still send the user back to fix it.
+     * @param {string} name Step name.
+     * @param {boolean} [errored=true] Whether the step is in error.
+     * @returns {this}
+     */
+    setError(name: string, errored?: boolean): this;
+    /**
+     * Enables or disables a step. Disabling the active step leaves it active — the user is still
+     * standing on it — but `next()`, `previous()`, and `goTo()` will skip or refuse it afterwards.
+     * @param {string} name Step name.
+     * @param {boolean} [disabled=true] Whether the step is unavailable.
+     * @returns {this}
+     */
+    setDisabled(name: string, disabled?: boolean): this;
+    /**
+     * Returns a snapshot of the rail's state.
+     * @returns {StepperState}
+     */
+    getState(): StepperState;
+    /**
+     * Aborts listeners and restores an enhanced target to the markup it had before the takeover.
+     * @returns {void}
+     */
+    destroy(): void;
+    /**
+     * Activates an index, marking every step it advanced past complete.
+     * @param {number} index Zero-based index, or -1 for "nowhere to go".
+     * @returns {this}
+     * @fires Stepper#change
+     */
+    _activate(index: number): this;
+    /**
+     * Builds one step's elements. The control's tag depends only on the `clickable` option, never on
+     * the step's state, so state changes never have to swap an element out from under the focus.
+     * @param {NormalizedStep} step Normalized step.
+     * @returns {StepRecord}
+     */
+    _createRecord(step: NormalizedStep): StepRecord;
+    /**
+     * Pushes the current state onto every rendered step and the counter line.
+     * @returns {void}
+     */
+    _sync(): void;
+    /**
+     * Resolves a step's rendered state.
+     * @param {NormalizedStep} step Normalized step.
+     * @param {number} index Zero-based index.
+     * @returns {StepperStepState}
+     */
+    _stateFor(step: NormalizedStep, index: number): StepperStepState;
+    /**
+     * @param {StepperStepState} state Rendered state.
+     * @param {number} index Zero-based index.
+     * @returns {Array<Node|string>}
+     */
+    _markerContent(state: StepperStepState, index: number): Array<Node | string>;
+    /**
+     * @param {StepperStepState} state Rendered state.
+     * @returns {string} Text announced in place of the decorative marker.
+     */
+    _statusText(state: StepperStepState): string;
+    /**
+     * Whether a step's button is enabled. The active step stays enabled when it qualifies (under
+     * `all`, or under `completed` once it has been visited), because disabling the button the user
+     * just clicked would throw their focus back to the document body; activating the active step is
+     * a no-op anyway.
+     * @param {NormalizedStep} step Normalized step.
+     * @returns {boolean}
+     */
+    _isClickable(step: NormalizedStep): boolean;
+    /** @returns {void} */
+    _syncCounter(): void;
+    /**
+     * @param {string} name Step name.
+     * @returns {NormalizedStep}
+     * @throws {RangeError} When no step carries that name.
+     */
+    _require(name: string): NormalizedStep;
+    /**
+     * Resolves a message through the host translator, falling back to the built-in English text.
+     * @param {string} key Message key.
+     * @param {string} fallback Built-in text, with `%1`-style placeholders.
+     * @param {...unknown} args Interpolation values.
+     * @returns {string}
+     */
+    _message(key: string, fallback: string, ...args: unknown[]): string;
+}
+/**
+ * Fired before the active step changes. Calling `preventDefault()` vetoes the move, which is how a
+ * wizard blocks a step whose form has not validated.
+ * @event Stepper#change
+ * @type {CustomEvent<StepperChangeDetail>}
+ */