@zeyos/zx 2.3.0 → 3.0.0

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

@@ -0,0 +1,449 @@
+import { Component } from '../../core/component.js';
+import { Field } from '../field/field.js';
+import { ProgressBar } from '../loading/progress-bar.js';
+export type QuestionnaireItem = import('./items.js').QuestionnaireItem;
+export type QuestionnaireChoice = import('./items.js').QuestionnaireChoice;
+export type NormalizedItem = import('./items.js').NormalizedItem;
+export type QuestionnaireProgress = import('./items.js').QuestionnaireProgress;
+export type QuestionnaireAdvance = 'manual' | 'auto';
+export type QuestionnaireStatus = 'asking' | 'review' | 'complete';
+export type QuestionnaireOptions = {
+    /**
+     * Ordered question definitions.
+     */
+    items?: QuestionnaireItem[];
+    /**
+     * Answers to start from. Together with `active`
+     * this is the resume pair: hand back what a previous session collected.
+     */
+    answers?: Record<string, unknown>;
+    /**
+     * Item to open, defaulting to the first visible one.
+     */
+    active?: string | null;
+    /**
+     * Whether the progress bar and counter are shown.
+     */
+    progress?: boolean;
+    /**
+     * Whether a summary of every answer is shown before submitting.
+     */
+    review?: boolean;
+    /**
+     * `auto` moves on by itself once a
+     * single-choice question is answered.
+     */
+    advance?: QuestionnaireAdvance;
+    /**
+     * Whether `1`–`9` and `a`–`z` pick an answer.
+     */
+    shortcuts?: boolean;
+    /**
+     * Whether the Back action is offered.
+     */
+    allowBack?: boolean;
+    /**
+     * Localized messages.
+     */
+    msg?: Record<string, string> | Record<string, Record<string, string>>;
+    /**
+     * Answer listener.
+     */
+    onchange?: (event: CustomEvent<QuestionnaireChangeDetail>) => void;
+    /**
+     * Navigation listener.
+     */
+    onnavigate?: (event: CustomEvent<QuestionnaireNavigateDetail>) => void;
+    /**
+     * Skip listener.
+     */
+    onskip?: (event: CustomEvent<QuestionnaireSkipDetail>) => void;
+    /**
+     * Validation listener.
+     */
+    oninvalid?: (event: CustomEvent<QuestionnaireInvalidDetail>) => void;
+    /**
+     * Submit listener.
+     */
+    onsubmit?: (event: CustomEvent<QuestionnaireSubmitDetail>) => void;
+    /**
+     * Completion listener.
+     */
+    oncomplete?: (event: CustomEvent<QuestionnaireCompleteDetail>) => void;
+};
+export type QuestionnaireChangeDetail = {
+    /**
+     * Item whose answer changed.
+     */
+    name: string;
+    /**
+     * The new answer.
+     */
+    value: unknown;
+    /**
+     * Every visible answer after the change.
+     */
+    answers: Record<string, unknown>;
+};
+export type QuestionnaireNavigateDetail = {
+    /**
+     * Item being left, or null.
+     */
+    from: string | null;
+    /**
+     * Item being opened, or null when the review screen is being entered.
+     */
+    to: string | null;
+    /**
+     * What triggered the move.
+     */
+    reason: 'next' | 'previous' | 'skip' | 'goto' | 'review';
+};
+export type QuestionnaireSkipDetail = {
+    name: string;
+};
+export type QuestionnaireInvalidDetail = {
+    name: string;
+    message: string;
+};
+export type QuestionnaireSubmitDetail = {
+    answers: Record<string, unknown>;
+    path: string[];
+};
+export type QuestionnaireCompleteDetail = {
+    answers: Record<string, unknown>;
+    path: string[];
+};
+/**
+ * @typedef {Object} QuestionnaireOptions
+ * @property {QuestionnaireItem[]} [items=[]] Ordered question definitions.
+ * @property {Record<string, unknown>} [answers={}] Answers to start from. Together with `active`
+ *   this is the resume pair: hand back what a previous session collected.
+ * @property {string|null} [active=null] Item to open, defaulting to the first visible one.
+ * @property {boolean} [progress=true] Whether the progress bar and counter are shown.
+ * @property {boolean} [review=false] Whether a summary of every answer is shown before submitting.
+ * @property {QuestionnaireAdvance} [advance='manual'] `auto` moves on by itself once a
+ *   single-choice question is answered.
+ * @property {boolean} [shortcuts=true] Whether `1`–`9` and `a`–`z` pick an answer.
+ * @property {boolean} [allowBack=true] Whether the Back action is offered.
+ * @property {Record<string, string>|Record<string, Record<string, string>>} [msg] Localized messages.
+ * @property {(event: CustomEvent<QuestionnaireChangeDetail>) => void} [onchange] Answer listener.
+ * @property {(event: CustomEvent<QuestionnaireNavigateDetail>) => void} [onnavigate] Navigation listener.
+ * @property {(event: CustomEvent<QuestionnaireSkipDetail>) => void} [onskip] Skip listener.
+ * @property {(event: CustomEvent<QuestionnaireInvalidDetail>) => void} [oninvalid] Validation listener.
+ * @property {(event: CustomEvent<QuestionnaireSubmitDetail>) => void} [onsubmit] Submit listener.
+ * @property {(event: CustomEvent<QuestionnaireCompleteDetail>) => void} [oncomplete] Completion listener.
+ */
+/**
+ * @typedef {Object} QuestionnaireChangeDetail
+ * @property {string} name Item whose answer changed.
+ * @property {unknown} value The new answer.
+ * @property {Record<string, unknown>} answers Every visible answer after the change.
+ */
+/**
+ * @typedef {Object} QuestionnaireNavigateDetail
+ * @property {string|null} from Item being left, or null.
+ * @property {string|null} to Item being opened, or null when the review screen is being entered.
+ * @property {'next'|'previous'|'skip'|'goto'|'review'} reason What triggered the move.
+ */
+/** @typedef {{name: string}} QuestionnaireSkipDetail */
+/** @typedef {{name: string, message: string}} QuestionnaireInvalidDetail */
+/** @typedef {{answers: Record<string, unknown>, path: string[]}} QuestionnaireSubmitDetail */
+/** @typedef {{answers: Record<string, unknown>, path: string[]}} QuestionnaireCompleteDetail */
+/**
+ * A guided, one-question-at-a-time flow: onboarding intake, a service-call checklist, an audit
+ * form, a feedback survey. The questionnaire owns the ordered items, the active one, the answers,
+ * validation, progress and navigation; the page, card, dialog or drawer around it owns closing,
+ * persistence and transport.
+ *
+ * Three things separate it from a `Form` with one `Fieldset` per question. It **branches**: an item
+ * carries a `when` predicate and a `next` target, conditions cascade, and Back retraces the path
+ * actually walked rather than an array index. Its answer control is **any registered Zx `Field`
+ * type**, so a question can ask for a date, a number, a rating or an upload instead of a choice.
+ * And its `validate` may be asynchronous, which is what lets a question be gated on a server check.
+ *
+ * The root is a real `<form>` and choices are native radios and checkboxes carrying the item name,
+ * so `new FormData(questionnaire.toElement())` reads the answers, arrow-key navigation inside a
+ * choice group is the browser's rather than ours, and nothing depends on JavaScript for semantics.
+ *
+ * @fires Questionnaire#change
+ * @fires Questionnaire#navigate
+ * @fires Questionnaire#skip
+ * @fires Questionnaire#invalid
+ * @fires Questionnaire#submit
+ * @fires Questionnaire#complete
+ * @extends {Component<QuestionnaireOptions>}
+ */
+export declare class Questionnaire extends Component<QuestionnaireOptions> {
+    _createdRoot: boolean;
+    _snapshot: import("../../core/dom.js").TargetSnapshot;
+    _destroyed: boolean;
+    /** @type {NormalizedItem[]} */
+    _items: NormalizedItem[];
+    /** @type {Map<string, Array<string|number>>} */
+    _selected: Map<string, Array<string | number>>;
+    /** @type {Map<string, string>} */
+    _freeform: Map<string, string>;
+    /** @type {Map<string, Field>} */
+    _fields: Map<string, Field>;
+    /** @type {string[]} */
+    _path: string[];
+    /** @type {QuestionnaireStatus} */
+    _status: QuestionnaireStatus;
+    _returnToReview: any;
+    _busy: boolean;
+    _error: string;
+    _advanceTimer: number;
+    _uid: string;
+    _form: HTMLElement;
+    _progressHost: HTMLElement;
+    _itemHost: HTMLElement;
+    _reviewHost: HTMLElement;
+    _actionsHost: HTMLElement;
+    _bar: ProgressBar;
+    _back: HTMLButtonElement;
+    _skip: HTMLButtonElement;
+    _forward: HTMLButtonElement;
+    static cssName: string;
+    /** @type {QuestionnaireOptions & {msg: Record<string, string>}} */
+    static defaults: QuestionnaireOptions & {
+        msg: Record<string, string>;
+    };
+    /**
+     * Builds the questionnaire. Runs inside the base constructor, so every piece of instance state
+     * is initialized here rather than in class fields.
+     * @returns {HTMLElement}
+     */
+    render(): HTMLElement;
+    /**
+     * Replaces the whole item list. Answers survive for items that are still present, and so does
+     * the active item; when it is gone the first visible item takes over. This is a structural
+     * change, so it never emits `navigate`.
+     * @param {QuestionnaireItem[]} list Item definitions.
+     * @returns {this}
+     * @throws {TypeError} When the list, an item, or a name is malformed, or a name repeats.
+     */
+    setItems(list: QuestionnaireItem[]): this;
+    /**
+     * Returns the normalized items, including ones currently conditioned out.
+     * @returns {NormalizedItem[]}
+     */
+    getItems(): NormalizedItem[];
+    /**
+     * Opens an item without validating the one being left — what the review screen's Edit action
+     * does. An item already on the path truncates it, so Back keeps working; a new one is appended.
+     * @param {string} name Item name.
+     * @returns {boolean} False when the move was vetoed or the item is conditioned out.
+     * @throws {RangeError} When no item carries that name.
+     * @fires Questionnaire#navigate
+     */
+    goTo(name: string): boolean;
+    /**
+     * Validates the active item and moves on: to the branch target, then the review screen, then
+     * submission. Returns a promise because an item's `validate` may be asynchronous.
+     * @returns {Promise<boolean>} False when validation failed or the move was vetoed.
+     * @fires Questionnaire#navigate
+     * @fires Questionnaire#invalid
+     */
+    next(): Promise<boolean>;
+    /**
+     * Steps back along the path actually walked — which is not `index - 1` once a branch has been
+     * taken. From the review screen it reopens the last question.
+     * @returns {boolean} False at the start of the questionnaire, or when the move was vetoed.
+     * @fires Questionnaire#navigate
+     */
+    previous(): boolean;
+    /**
+     * Clears the active item's answer and moves on without validating it. Skipping the last
+     * question submits, so this is a promise for the same reason `submit()` is.
+     * @returns {Promise<boolean>} False when the item is not skippable or the move was vetoed.
+     * @fires Questionnaire#skip
+     * @fires Questionnaire#navigate
+     */
+    skip(): Promise<boolean>;
+    /**
+     * Validates the active item (unless already on the review screen) and submits.
+     * @returns {Promise<boolean>} False when validation failed or `submit` was prevented.
+     * @fires Questionnaire#submit
+     * @fires Questionnaire#complete
+     */
+    submit(): Promise<boolean>;
+    /**
+     * Returns the answers of every visible question that carries one, in declaration order.
+     * Questions conditioned out are left out, so an abandoned branch never submits stale data.
+     * @returns {Record<string, unknown>}
+     */
+    getAnswers(): Record<string, unknown>;
+    /**
+     * Returns one answer, whether or not its question is currently visible.
+     * @param {string} name Item name.
+     * @returns {unknown}
+     */
+    getAnswer(name: string): unknown;
+    /**
+     * Sets several answers at once.
+     * @param {Record<string, unknown>} values Answers keyed by item name.
+     * @param {{silent?: boolean}} [options={}] Set `silent` to suppress `change`.
+     * @returns {this}
+     * @fires Questionnaire#change
+     */
+    setAnswers(values: Record<string, unknown>, { silent }?: {
+        silent?: boolean;
+    }): this;
+    /**
+     * Sets one answer. A value matching a choice selects it; anything else lands in the freeform
+     * input when the item has one.
+     * @param {string} name Item name.
+     * @param {unknown} value New answer, or null to clear it.
+     * @param {{silent?: boolean}} [options={}] Set `silent` to suppress `change`.
+     * @returns {this}
+     * @throws {RangeError} When no item carries that name.
+     * @fires Questionnaire#change
+     */
+    setAnswer(name: string, value: unknown, { silent }?: {
+        silent?: boolean;
+    }): this;
+    /**
+     * Returns the active item name, or null on the review or completion screen.
+     * @returns {string|null}
+     */
+    getActive(): string | null;
+    /**
+     * Returns the item names visited so far, active last. This is the questionnaire's memory of the
+     * route through the branches.
+     * @returns {string[]}
+     */
+    getPath(): string[];
+    /**
+     * Returns progress along the path walked. `total` is exact while the flow is static and an
+     * estimate once a function `next` can jump somewhere the forward walk cannot predict.
+     * @returns {QuestionnaireProgress}
+     */
+    getProgress(): QuestionnaireProgress;
+    /**
+     * Returns everything a caller needs to resume this questionnaire later.
+     * @returns {{active: string|null, status: QuestionnaireStatus, answers: Record<string, unknown>, path: string[], progress: QuestionnaireProgress}}
+     */
+    getState(): {
+        active: string | null;
+        status: QuestionnaireStatus;
+        answers: Record<string, unknown>;
+        path: string[];
+        progress: QuestionnaireProgress;
+    };
+    /**
+     * Returns the visible answers as form data, with one entry per value of a multiple-choice item —
+     * the same shape `new FormData(questionnaire.toElement())` produces.
+     * @returns {FormData}
+     */
+    toFormData(): FormData;
+    /**
+     * Clears every answer and returns to the first visible question.
+     * @returns {this}
+     */
+    reset(): this;
+    /**
+     * Moves focus to the active question, which is what a screen reader announces after a move.
+     * @returns {this}
+     */
+    focus(): this;
+    /** @returns {void} */
+    destroy(): void;
+    /** @returns {NormalizedItem|null} */
+    _activeItem(): NormalizedItem | null;
+    /**
+     * Every answer given, including ones on branches that are currently conditioned out — walking
+     * back into a branch restores what was typed there. `resolveFlow()` filters this down.
+     * @returns {Record<string, unknown>}
+     */
+    _rawAnswers(): Record<string, unknown>;
+    /** @param {NormalizedItem} item @returns {unknown} */
+    _answerOf(item: NormalizedItem): unknown;
+    /**
+     * Returns the item's Field, building it on first use. Fields are cached rather than rebuilt per
+     * paint, so what a reader typed survives walking away from the question and back.
+     * @param {NormalizedItem} item Item carrying `field` options.
+     * @returns {Field}
+     */
+    _field(item: NormalizedItem): Field;
+    /** @param {string} name @param {QuestionnaireNavigateDetail['reason']} reason @returns {boolean} */
+    _navigate(name: string, reason: QuestionnaireNavigateDetail['reason']): boolean;
+    /** @returns {boolean} */
+    _enterReview(): boolean;
+    /** @returns {Promise<boolean>} */
+    _validateActive(): Promise<boolean>;
+    /** @param {boolean} busy @returns {void} */
+    _setBusy(busy: boolean): void;
+    /** @returns {void} */
+    _paint(): void;
+    /** @returns {void} */
+    _syncState(): void;
+    /** @returns {void} */
+    _paintProgress(): void;
+    /** @returns {void} */
+    _paintItem(): void;
+    /** @param {NormalizedItem} item @returns {HTMLElement} */
+    _choices(item: NormalizedItem): HTMLElement;
+    /** @param {NormalizedItem} item @returns {void} */
+    _paintError(item: NormalizedItem): void;
+    /** @returns {void} */
+    _paintReview(): void;
+    /** @param {NormalizedItem} item @param {unknown} value @returns {string} */
+    _formatAnswer(item: NormalizedItem, value: unknown): string;
+    /** @returns {void} */
+    _paintActions(): void;
+    /**
+     * @param {string} action @param {string} label @param {string|null} glyph
+     * @param {'default'|'primary'|'ghost'} kind @returns {HTMLButtonElement}
+     */
+    _action(action: string, label: string, glyph: string | null, kind: 'default' | 'primary' | 'ghost'): HTMLButtonElement;
+    /** @param {Event} event @returns {void} */
+    _onControlChange(event: Event): void;
+    /** @param {Event} event @returns {void} */
+    _onFreeformInput(event: Event): void;
+    /** @param {Event} event @returns {void} */
+    _onActionClick(event: Event): void;
+    /** @param {Event} event @returns {void} */
+    _onReviewClick(event: Event): void;
+    /** @param {KeyboardEvent} event @returns {void} */
+    _onKeydown(event: KeyboardEvent): void;
+    /** @param {NormalizedItem} item @returns {void} */
+    _maybeAutoAdvance(item: NormalizedItem): void;
+    /** @param {NormalizedItem} item @returns {void} */
+    _emitChange(item: NormalizedItem): void;
+    /** @returns {void} */
+    _focusItem(): void;
+    /** @returns {void} */
+    _focusControl(): void;
+}
+/**
+ * An answer changed.
+ * @event Questionnaire#change
+ * @type {CustomEvent<QuestionnaireChangeDetail>}
+ */
+/**
+ * A move between questions, into the review screen, or back. Preventable: call
+ * `event.preventDefault()` to refuse the move.
+ * @event Questionnaire#navigate
+ * @type {CustomEvent<QuestionnaireNavigateDetail>}
+ */
+/**
+ * A skippable question was skipped, clearing its answer.
+ * @event Questionnaire#skip
+ * @type {CustomEvent<QuestionnaireSkipDetail>}
+ */
+/**
+ * Validation of the active question failed.
+ * @event Questionnaire#invalid
+ * @type {CustomEvent<QuestionnaireInvalidDetail>}
+ */
+/**
+ * The questionnaire is being submitted. Preventable.
+ * @event Questionnaire#submit
+ * @type {CustomEvent<QuestionnaireSubmitDetail>}
+ */
+/**
+ * Submission was not prevented and the questionnaire is finished.
+ * @event Questionnaire#complete
+ * @type {CustomEvent<QuestionnaireCompleteDetail>}
+ */

package/dist/types/components/sheet/sheet-stack.d.ts

@@ -0,0 +1,167 @@
+/** @typedef {import('./sheet.js').Sheet} Sheet */
+export type Sheet = import('./sheet.js').Sheet;
+export type SheetStackOptions = {
+    /**
+     * How depth is expressed. `stack` slides each
+     * covered sheet back toward its edge and scales it down, leaving only the top one usable —
+     * the drill-down feel. `cascade` shifts each covered sheet clear of the ones in front so they
+     * sit side by side and all stay usable, which is what an ERP screen usually wants: the parent
+     * record stays readable while a line item is edited.
+     */
+    layout?: 'stack' | 'cascade';
+    /**
+     * Pixels a `stack` layout moves per depth step.
+     */
+    offset?: number;
+    /**
+     * How much a `stack` layout shrinks per depth step, as a fraction.
+     */
+    scale?: number;
+    /**
+     * Depth at which a sheet stops being drawn. Deeper sheets stay open and
+     * in the stack; they are simply no longer visible behind the ones in front.
+     */
+    max?: number;
+    /**
+     * Push listener.
+     */
+    onpush?: (event: CustomEvent<{
+        sheet: Sheet;
+        depth: number;
+    }>) => void;
+    /**
+     * Pop listener.
+     */
+    onpop?: (event: CustomEvent<{
+        sheet: Sheet;
+    }>) => void;
+};
+/**
+ * @typedef {Object} SheetStackOptions
+ * @property {'stack'|'cascade'} [layout='stack'] How depth is expressed. `stack` slides each
+ *   covered sheet back toward its edge and scales it down, leaving only the top one usable —
+ *   the drill-down feel. `cascade` shifts each covered sheet clear of the ones in front so they
+ *   sit side by side and all stay usable, which is what an ERP screen usually wants: the parent
+ *   record stays readable while a line item is edited.
+ * @property {number} [offset=24] Pixels a `stack` layout moves per depth step.
+ * @property {number} [scale=0.04] How much a `stack` layout shrinks per depth step, as a fraction.
+ * @property {number} [max=3] Depth at which a sheet stops being drawn. Deeper sheets stay open and
+ *   in the stack; they are simply no longer visible behind the ones in front.
+ * @property {(event: CustomEvent<{sheet: Sheet, depth: number}>) => void} [onpush] Push listener.
+ * @property {(event: CustomEvent<{sheet: Sheet}>) => void} [onpop] Pop listener.
+ */
+/**
+ * An ordered group of Sheets that read as one drill-down.
+ *
+ * Deliberately tiny, because the browser already does the hard part: nested dialogs stack in the
+ * top layer by open order, so there is no z-index bookkeeping here, and Escape closes only the
+ * topmost, so unwinding one level at a time is native behaviour rather than something to
+ * implement. What is left is bookkeeping — which sheet is at which depth — written onto the
+ * elements as `data-depth` and `--zx-sheet-depth` for CSS to interpret.
+ *
+ * Owns no element of its own, so it is a controller rather than a `Component`: there is nothing
+ * to render, only sheets to arrange.
+ *
+ * @fires SheetStack#push
+ * @fires SheetStack#pop
+ */
+export declare class SheetStack extends EventTarget {
+    #private;
+    options: Readonly<{
+        layout?: 'stack' | 'cascade';
+        offset?: number;
+        scale?: number;
+        max?: number;
+        onpush?: (event: CustomEvent<{
+            sheet: Sheet;
+            depth: number;
+        }>) => void;
+        onpop?: (event: CustomEvent<{
+            sheet: Sheet;
+        }>) => void;
+    }>;
+    /** @type {Readonly<SheetStackOptions>} */
+    static defaults: Readonly<SheetStackOptions>;
+    /**
+     * Creates a sheet stack.
+     * @param {SheetStackOptions} [options={}] Stack options.
+     */
+    constructor(options?: SheetStackOptions);
+    /**
+     * Adds a sheet to the top of the stack, opening it if it is closed. A sheet already in the stack
+     * is raised rather than added twice.
+     * @param {Sheet} sheet Sheet to push.
+     * @returns {this}
+     * @fires SheetStack#push
+     */
+    push(sheet: Sheet): this;
+    /**
+     * Closes the top sheet and removes it from the stack.
+     *
+     * The removal is synchronous while the close is not — a dialog dispatches `close` in a queued
+     * task — so the stack updates itself here rather than waiting for the event. The close listener
+     * is left to handle the other direction: a sheet dismissed by Escape or its own button.
+     * @returns {Sheet|null} The sheet that was closed, or null on an empty stack.
+     * @fires SheetStack#pop
+     */
+    pop(): Sheet | null;
+    /**
+     * Closes everything above a sheet, leaving it on top.
+     * @param {Sheet} sheet Sheet to return to.
+     * @returns {this}
+     */
+    popTo(sheet: Sheet): this;
+    /**
+     * Closes every sheet, from the top down.
+     * @returns {this}
+     */
+    clear(): this;
+    /**
+     * The sheet currently on top.
+     * @returns {Sheet|null}
+     */
+    top(): Sheet | null;
+    /**
+     * How many sheets the stack holds.
+     * @returns {number}
+     */
+    size(): number;
+    /**
+     * The sheets, bottom first.
+     * @returns {Sheet[]}
+     */
+    sheets(): Sheet[];
+    /**
+     * Whether a sheet is in this stack.
+     * @param {Sheet} sheet Sheet to look for.
+     * @returns {boolean}
+     */
+    has(sheet: Sheet): boolean;
+    /**
+     * Subscribes to a stack event.
+     * @param {string} type Event name.
+     * @param {(event: any) => void} fn Listener.
+     * @returns {this}
+     */
+    on(type: string, fn: (event: any) => void): this;
+    /**
+     * Removes a stack event listener.
+     * @param {string} type Event name.
+     * @param {(event: any) => void} fn Listener.
+     * @returns {this}
+     */
+    off(type: string, fn: (event: any) => void): this;
+    /**
+     * Subscribes to one occurrence of a stack event.
+     * @param {string} type Event name.
+     * @param {(event: any) => void} fn Listener.
+     * @returns {this}
+     */
+    once(type: string, fn: (event: any) => void): this;
+    /**
+     * Empties the stack without closing anything. The sheets are not the stack's to destroy, so
+     * they are simply released with their depth styling removed.
+     * @returns {void}
+     */
+    destroy(): void;
+}