@zeyos/zx 2.3.0 → 4.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/select/select.d.ts

@@ -3,6 +3,14 @@ export type Primitive = string | number | boolean | symbol | bigint | null | und
 export type SelectItem = Record<string, any> | Primitive;
 export type SelectValueReader = string | ((item: SelectItem) => unknown);
 export type SelectLabelReader = string | ((item: SelectItem) => string);
+export type SelectAction = {
+    id: string | number;
+    label: string;
+    icon?: string | Node;
+    description?: string;
+    group?: string;
+    invoke?: (detail: SelectActionDetail) => void;
+};
 export type SelectOptions = {
     /**
      * Available values.
@@ -28,6 +36,22 @@ export type SelectOptions = {
      * Selected-value renderer.
      */
     renderValue?: ((item: SelectItem) => string) | null;
+    /**
+     * Decorative content before the selected text.
+     */
+    renderValueAdornment?: ((item: SelectItem) => Node | string | null) | null;
+    /**
+     * Clear-row renderer.
+     */
+    renderNone?: ((label: string) => Node | string) | null;
+    /**
+     * Clear-row label independent from the input placeholder.
+     */
+    noneLabel?: string | null;
+    /**
+     * Command rows that emit `action` without changing value.
+     */
+    actions?: SelectAction[];
     /**
      * Initially selected ID or item.
      */
@@ -92,6 +116,10 @@ export type SelectOptions = {
      * Async-loaded listener.
      */
     onloaded?: (event: CustomEvent<SelectLoadedDetail>) => void;
+    /**
+     * Preventable command-row listener.
+     */
+    onaction?: (event: CustomEvent<SelectActionDetail>) => void;
 };
 export type SelectChangeDetail = {
     value: unknown;
@@ -103,9 +131,16 @@ export type SelectQueryDetail = {
 export type SelectLoadedDetail = {
     items: SelectItem[];
 };
+export type SelectActionDetail = {
+    id: string | number;
+    action: SelectAction;
+    query: string;
+    select: Select;
+};
 export type SelectOptionEntry = {
     item: SelectItem | null;
     clear: boolean;
+    action: SelectAction | null;
     element: HTMLElement;
 };
 export type SelectSetOptions = {
@@ -126,6 +161,7 @@ export declare class Select extends Component<SelectOptions> {
     _visibleItems: any[];
     _fixedItems: any[] | SelectItem[];
     _visibleFixed: any[] | SelectItem[];
+    _actions: any[] | SelectAction[];
     _selected: SelectItem;
     _optionEntries: any[];
     _activeIndex: number;
@@ -171,6 +207,8 @@ export declare class Select extends Component<SelectOptions> {
      * @returns {this}
      */
     setFixedItems(items: SelectItem[]): this;
+    /** Replaces command rows without changing the selected value. @param {SelectAction[]} actions @returns {this} */
+    setActions(actions: SelectAction[]): this;
     /**
      * Restores the configured initial value.
      * @param {{silent?: boolean}} [options={}] Reset behavior.
@@ -196,6 +234,15 @@ export declare class Select extends Component<SelectOptions> {
      * @returns {Select}
      */
     static priority(target: Element | string | null, options?: SelectOptions): Select;
+    /**
+     * Creates a status picker with shape- and color-distinct workflow indicators.
+     * @param {Element|string|null} target Component target.
+     * @param {SelectOptions & {items?: Array<Record<string, any>>}} [options={}] Select overrides and status items.
+     * @returns {Select}
+     */
+    static status(target: Element | string | null, options?: SelectOptions & {
+        items?: Array<Record<string, any>>;
+    }): Select;
     /**
      * Creates the record-permission picker: the fixed Private and Public choices above the groups a
      * record can be shared with. The value is the tri-state ZeyOS stores — `false` for private,
@@ -228,6 +275,8 @@ export declare class Select extends Component<SelectOptions> {
     _renderOptions(): void;
     /** @param {SelectItem|null} item @param {boolean} clear @param {string} [label] @returns {void} */
     _appendOption(item: SelectItem | null, clear: boolean, label?: string): void;
+    /** @param {SelectAction} action @returns {void} */
+    _appendAction(action: SelectAction): void;
     /** @param {SelectItem|null} item @returns {Node|string} */
     _renderItem(item: SelectItem | null): Node | string;
     /** @param {string} query @returns {void} */
@@ -241,6 +290,8 @@ export declare class Select extends Component<SelectOptions> {
     /** @returns {void} */
     _syncInputValue(): void;
     /** @returns {void} */
+    _syncValueAdornment(): void;
+    /** @returns {void} */
     _syncDisabled(): void;
     /** @param {unknown} candidate @returns {SelectItem|null} */
     _findItem(candidate: unknown): SelectItem | null;