@zeyos/zx 2.3.0 → 4.0.0

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

@@ -0,0 +1,327 @@
+/**
+ * Pure questionnaire logic: normalization, visibility, branch resolution, validation, and
+ * progress. Nothing here touches the DOM, so the rules a branching questionnaire lives or dies by
+ * are testable in Node.
+ * @module questionnaire/items
+ */
+export type QuestionnaireChoice = {
+    /**
+     * Answer value, unique within its item.
+     */
+    value: string | number;
+    /**
+     * Visible answer text.
+     */
+    label: string;
+    /**
+     * Supporting line under the label.
+     */
+    description?: string;
+    /**
+     * Icon name drawn before the label.
+     */
+    icon?: string | null;
+    /**
+     * Shortcut key. Assigned `1`–`9` then `a`–`z` when omitted.
+     */
+    key?: string;
+    /**
+     * Whether the choice can be picked.
+     */
+    disabled?: boolean;
+    /**
+     * Whether picking it clears every other choice of a
+     * `multiple` item — the "None of the above" behaviour.
+     */
+    exclusive?: boolean;
+};
+export type QuestionnaireInput = {
+    /**
+     * Accessible name of the freeform control.
+     */
+    label?: string;
+    /**
+     * Placeholder text. Never a substitute for the label.
+     */
+    placeholder?: string;
+    /**
+     * Whether to render a `textarea`.
+     */
+    multiline?: boolean;
+    /**
+     * Native maximum length, 0 for none.
+     */
+    maxLength?: number;
+};
+export type QuestionnaireItem = {
+    /**
+     * Unique key. Doubles as the native input name.
+     */
+    name: string;
+    /**
+     * The question. Rendered as the item's `<legend>`.
+     */
+    prompt: string;
+    /**
+     * Supporting line, associated via `aria-describedby`.
+     */
+    description?: string;
+    /**
+     * Grouping label shown in the counter and the review list.
+     */
+    section?: string;
+    /**
+     * Whether an answer is needed to advance.
+     */
+    required?: boolean;
+    /**
+     * Whether several choices can be picked at once.
+     */
+    multiple?: boolean;
+    /**
+     * Whether the Skip action is offered.
+     */
+    skippable?: boolean;
+    /**
+     * Fixed answers.
+     */
+    choices?: QuestionnaireChoice[];
+    /**
+     * Freeform answer offered beside the choices.
+     */
+    input?: QuestionnaireInput | null;
+    /**
+     * Any registered Zx `Field` type used as the answer control.
+     */
+    field?: any | null;
+    /**
+     * Visibility predicate.
+     */
+    when?: ((answers: Record<string, unknown>) => boolean) | null;
+    /**
+     * Branch target: an item name, or a function returning one.
+     */
+    next?: string | ((answer: unknown, answers: Record<string, unknown>) => string | null) | null;
+    /**
+     * Extra validation returning an error message, or null when the answer is acceptable.
+     */
+    validate?: ((answer: unknown, answers: Record<string, unknown>) => string | null | Promise<string | null>) | null;
+};
+export type NormalizedItem = {
+    /**
+     * Unique key.
+     */
+    name: string;
+    /**
+     * The question.
+     */
+    prompt: string;
+    /**
+     * Supporting line, or null.
+     */
+    description: string | null;
+    /**
+     * Grouping label, empty when ungrouped.
+     */
+    section: string;
+    /**
+     * Whether an answer is needed.
+     */
+    required: boolean;
+    /**
+     * Whether several choices can be picked.
+     */
+    multiple: boolean;
+    /**
+     * Whether Skip is offered.
+     */
+    skippable: boolean;
+    /**
+     * Fixed answers with shortcut keys assigned.
+     */
+    choices: NormalizedChoice[];
+    /**
+     * Freeform answer, or null.
+     */
+    input: Required<QuestionnaireInput> | null;
+    /**
+     * Field options, or null.
+     */
+    field: any | null;
+    /**
+     * Visibility predicate.
+     */
+    when: ((answers: Record<string, unknown>) => boolean) | null;
+    /**
+     * Branch target.
+     */
+    next: string | ((answer: unknown, answers: Record<string, unknown>) => string | null) | null;
+    /**
+     * Extra validation.
+     */
+    validate: ((answer: unknown, answers: Record<string, unknown>) => string | null | Promise<string | null>) | null;
+};
+export type NormalizedChoice = {
+    /**
+     * Answer value.
+     */
+    value: string | number;
+    /**
+     * Visible answer text.
+     */
+    label: string;
+    /**
+     * Supporting line, or null.
+     */
+    description: string | null;
+    /**
+     * Icon name, or null.
+     */
+    icon: string | null;
+    /**
+     * Shortcut key, a single lowercase character, or empty when the item has
+     * more choices than there are keys to hand out.
+     */
+    key: string;
+    /**
+     * Whether the choice can be picked.
+     */
+    disabled: boolean;
+    /**
+     * Whether picking it clears the other choices.
+     */
+    exclusive: boolean;
+};
+export type ResolvedFlow = {
+    /**
+     * Answers of visible items only, in declaration order.
+     */
+    answers: Record<string, unknown>;
+    /**
+     * Items whose conditions currently pass.
+     */
+    visible: NormalizedItem[];
+};
+export type QuestionnaireProgress = {
+    /**
+     * Zero-based position of the active item along the path walked so far.
+     */
+    index: number;
+    /**
+     * How many items on the path carry an answer.
+     */
+    answered: number;
+    /**
+     * Path length plus the items still reachable. An estimate whenever a
+     * function `next` is involved, since a dynamic jump is unknowable before the answer exists.
+     */
+    total: number;
+    /**
+     * Completion share of `total`, 0–100.
+     */
+    percent: number;
+    /**
+     * Section of the active item, empty when ungrouped.
+     */
+    section: string;
+};
+/**
+ * Normalizes and validates a list of item definitions. Never mutates its input.
+ * @param {QuestionnaireItem[]} list Item definitions.
+ * @returns {NormalizedItem[]}
+ * @throws {TypeError} When the list, an item, or a name is malformed, or a name repeats.
+ */
+export declare function normalizeItems(list: QuestionnaireItem[]): NormalizedItem[];
+/**
+ * Normalizes an item's choices and hands out the shortcut keys. Explicit keys are reserved before
+ * any are assigned, so adding one to the third choice never renumbers the others.
+ * @param {QuestionnaireChoice[]} list Choice definitions.
+ * @param {string} [itemName=''] Owning item name, used in error messages.
+ * @returns {NormalizedChoice[]}
+ * @throws {TypeError} When the list or a choice is malformed, or a value repeats.
+ */
+export declare function normalizeChoices(list: QuestionnaireChoice[], itemName?: string): NormalizedChoice[];
+/**
+ * Reports whether an item's `when` predicate passes for a given set of answers. An item without
+ * one is always visible, and a predicate that throws hides nothing — a broken condition must not
+ * strand the reader mid-questionnaire.
+ * @param {NormalizedItem} item Item to test.
+ * @param {Record<string, unknown>} answers Answers visible to the predicate.
+ * @returns {boolean}
+ */
+export declare function isVisible(item: NormalizedItem, answers: Record<string, unknown>): boolean;
+/**
+ * Resolves visibility and the effective answers in one forward pass.
+ *
+ * Conditions have to cascade: if "VAT id" is conditioned out because the customer turned out to be
+ * a private buyer, a question conditioned on the VAT id must disappear with it. Walking the items
+ * in declaration order and letting each predicate see only the answers of *visible* items before
+ * it gives exactly that, and terminates — a predicate can never depend on its own visibility.
+ *
+ * The raw store keeps answers to conditioned-out items, so walking back into a branch restores
+ * what was typed there; they are simply not part of the resolved answers.
+ * @param {NormalizedItem[]} items All items.
+ * @param {Record<string, unknown>} raw Every answer given, including hidden ones.
+ * @returns {ResolvedFlow}
+ */
+export declare function resolveFlow(items: NormalizedItem[], raw: Record<string, unknown>): ResolvedFlow;
+/**
+ * Returns the items whose conditions currently pass, in declaration order.
+ * @param {NormalizedItem[]} items All items.
+ * @param {Record<string, unknown>} raw Every answer given.
+ * @returns {NormalizedItem[]}
+ */
+export declare function visibleItems(items: NormalizedItem[], raw: Record<string, unknown>): NormalizedItem[];
+/**
+ * Resolves which item follows the given one.
+ *
+ * A `next` of `null` falls through to the next visible item in declaration order. A string, or a
+ * function returning a string, names a target: when that target is currently hidden the walk
+ * continues forward from it rather than stranding the reader on an invisible question.
+ * @param {NormalizedItem[]} items All items.
+ * @param {NormalizedItem} item Item being left.
+ * @param {Record<string, unknown>} raw Every answer given.
+ * @returns {string|null} Name of the next item, or null at the end of the questionnaire.
+ * @throws {RangeError} When `next` names an item that does not exist.
+ */
+export declare function resolveNext(items: NormalizedItem[], item: NormalizedItem, raw: Record<string, unknown>): string | null;
+/**
+ * Reports whether an answer counts as absent. An empty string, an empty array, null, and undefined
+ * are all "no answer"; `false` and `0` are answers.
+ * @param {unknown} value Answer value.
+ * @returns {boolean}
+ */
+export declare function isEmptyAnswer(value: unknown): boolean;
+/**
+ * Runs the synchronous part of validation: the required check. An item's own `validate` may be
+ * asynchronous and is awaited by the component instead.
+ * @param {NormalizedItem} item Item to check.
+ * @param {unknown} answer Current answer.
+ * @param {(key: string) => string} message Message resolver, called with a message key.
+ * @returns {string|null} Error message, or null when the answer passes.
+ */
+export declare function validateAnswer(item: NormalizedItem, answer: unknown, message: (key: string) => string): string | null;
+/**
+ * Applies "None of the above" exclusivity to a multiple-choice selection.
+ *
+ * Picking an exclusive choice drops everything else; picking anything else drops the exclusive
+ * ones. The result is returned in choice order, so the answer never depends on click order.
+ * @param {NormalizedChoice[]} choices The item's choices.
+ * @param {Array<string|number>} selected Values currently selected.
+ * @param {string|number|null} [toggled=null] Value the reader just switched on.
+ * @returns {Array<string|number>}
+ */
+export declare function applyExclusive(choices: NormalizedChoice[], selected: Array<string | number>, toggled?: string | number | null): Array<string | number>;
+/**
+ * Computes progress along the path actually walked.
+ *
+ * The index is the position within `path`, not within `items`: once a branch has been taken, the
+ * declaration index says nothing about how far the reader has come. `total` adds the items still
+ * reachable under the current answers, which is exact for static flows and an estimate as soon as
+ * a function `next` can jump somewhere the walk cannot predict.
+ * @param {NormalizedItem[]} items All items.
+ * @param {Record<string, unknown>} raw Every answer given.
+ * @param {string[]} path Item names visited so far, active item last.
+ * @returns {QuestionnaireProgress}
+ */
+export declare function progressOf(items: NormalizedItem[], raw: Record<string, unknown>, path: string[]): QuestionnaireProgress;