@marktiderman/genesis-forms 0.4.2 → 0.6.0

package/dist/{types-BBKBQ8sp.d.cts → types-oAckGR_Z.d.cts}

@@ -32,6 +32,28 @@ interface FieldBlock {
     identifying?: boolean;
     props?: Record<string, Json>;
 }
+/**
+ * Where a choice field (single choice, multiple choice, dropdown) also takes
+ * options from, as `props.optionsFrom`. `source: "host"`: the app showing the
+ * form supplies the list named `key` when the form opens and again when a
+ * response is checked (`hostOptions` on `createForm` and `validateSubmission`),
+ * such as a practice's current coaches. They follow the field's own
+ * `props.options`, if it has any.
+ */
+interface OptionsSource {
+    source: "host";
+    key: string;
+    /**
+     * Show only the options that match another answer: those whose `attributes[attribute]` is the
+     * earlier question `field`'s answer (by key), or, for a list attribute or a multiple choice
+     * answer, shares a value with it. Until that question is answered every option shows. See
+     * `visibleOptions`.
+     */
+    filter?: {
+        attribute: string;
+        field: string;
+    };
+}
 interface ContentBlock {
     kind: "content";
     id: string;
@@ -112,6 +134,14 @@ interface FormSettings {
     anonymous?: boolean;
     /** Clear the values of fields hidden by logic on submit. Default true. */
     clearHiddenValues?: boolean;
+    /**
+     * Save answers as they go, off by default (Typeform's partial responses). When
+     * true, a host saves the answers so far each time the respondent moves on
+     * (genesis-forms-web's `onProgress`, with `formProgress` saying how far they
+     * got), so an unfinished response is kept even if they never submit. The form
+     * tells respondents so. Saving is the host's: the engine only says it's on.
+     */
+    saveProgress?: boolean;
 }
 type FormLayout = {
     mode: "classic";
@@ -152,4 +182,4 @@ type FormEvent = {
     at?: number;
 };
 
-export type { Block as B, ContentBlock as C, Ending as E, FormDefinition as F, HiddenInput as H, Json as J, LogicRule as L, Operator as O, PageBreakBlock as P, FieldBlock as a, FormLayout as b, FormSettings as c, Condition as d, FormEvent as e, Operand as f };
+export type { Block as B, ContentBlock as C, Ending as E, FormDefinition as F, HiddenInput as H, Json as J, LogicRule as L, OptionsSource as O, PageBreakBlock as P, FieldBlock as a, FormLayout as b, FormSettings as c, Condition as d, FormEvent as e, Operand as f, Operator as g };

package/dist/{types-BBKBQ8sp.d.ts → types-oAckGR_Z.d.ts}

@@ -32,6 +32,28 @@ interface FieldBlock {
     identifying?: boolean;
     props?: Record<string, Json>;
 }
+/**
+ * Where a choice field (single choice, multiple choice, dropdown) also takes
+ * options from, as `props.optionsFrom`. `source: "host"`: the app showing the
+ * form supplies the list named `key` when the form opens and again when a
+ * response is checked (`hostOptions` on `createForm` and `validateSubmission`),
+ * such as a practice's current coaches. They follow the field's own
+ * `props.options`, if it has any.
+ */
+interface OptionsSource {
+    source: "host";
+    key: string;
+    /**
+     * Show only the options that match another answer: those whose `attributes[attribute]` is the
+     * earlier question `field`'s answer (by key), or, for a list attribute or a multiple choice
+     * answer, shares a value with it. Until that question is answered every option shows. See
+     * `visibleOptions`.
+     */
+    filter?: {
+        attribute: string;
+        field: string;
+    };
+}
 interface ContentBlock {
     kind: "content";
     id: string;
@@ -112,6 +134,14 @@ interface FormSettings {
     anonymous?: boolean;
     /** Clear the values of fields hidden by logic on submit. Default true. */
     clearHiddenValues?: boolean;
+    /**
+     * Save answers as they go, off by default (Typeform's partial responses). When
+     * true, a host saves the answers so far each time the respondent moves on
+     * (genesis-forms-web's `onProgress`, with `formProgress` saying how far they
+     * got), so an unfinished response is kept even if they never submit. The form
+     * tells respondents so. Saving is the host's: the engine only says it's on.
+     */
+    saveProgress?: boolean;
 }
 type FormLayout = {
     mode: "classic";
@@ -152,4 +182,4 @@ type FormEvent = {
     at?: number;
 };
 
-export type { Block as B, ContentBlock as C, Ending as E, FormDefinition as F, HiddenInput as H, Json as J, LogicRule as L, Operator as O, PageBreakBlock as P, FieldBlock as a, FormLayout as b, FormSettings as c, Condition as d, FormEvent as e, Operand as f };
+export type { Block as B, ContentBlock as C, Ending as E, FormDefinition as F, HiddenInput as H, Json as J, LogicRule as L, OptionsSource as O, PageBreakBlock as P, FieldBlock as a, FormLayout as b, FormSettings as c, Condition as d, FormEvent as e, Operand as f, Operator as g };

package/dist/validate-B5WKHbst.d.cts

@@ -0,0 +1,322 @@
+import { J as Json, g as Operator, a as FieldBlock, B as Block, O as OptionsSource, F as FormDefinition, e as FormEvent } from './types-oAckGR_Z.cjs';
+
+/**
+ * A field type, without any UI. Renderers are registered separately per
+ * platform (`genesis-forms-react`), so a manifest runs anywhere.
+ */
+interface FieldTypeManifest {
+    type: string;
+    label: string;
+    category: "text" | "choice" | "scale" | "date" | "media" | "advanced";
+    /** `json: false` types must convert, so drafts and server replay never lose an answer. */
+    value: {
+        json: true;
+    } | {
+        json: false;
+        serialize: (value: unknown) => Json;
+        deserialize: (json: Json) => unknown;
+    };
+    operators: Operator[];
+    a11y: {
+        semantics: "control" | "group";
+        /** The HTML `autocomplete` token, such as `"email"` or `"tel"`. */
+        autocomplete?: string;
+        /** The HTML `inputmode` hint for on-screen keyboards, such as `"email"` or `"tel"`. */
+        inputMode?: "text" | "email" | "tel" | "numeric" | "decimal" | "url" | "search";
+    };
+    isEmpty?: (value: Json | undefined) => boolean;
+    /** Return an error message, or null when the (non-empty) value is valid. */
+    validate?: (value: Json, field: FieldBlock) => string | null;
+    /** Plain text for recall, exports and emails. */
+    summarize?: (value: Json, field: FieldBlock) => string;
+    /**
+     * The form a (valid, non-empty) value is stored in, such as an email
+     * without surrounding spaces. Applied by `engine.answers()` and the server.
+     */
+    normalize?: (value: Json, field: FieldBlock) => Json;
+    /** Valid example answers, used by `coverage()` and other test tools to explore a path. */
+    samples?: (field: FieldBlock) => Json[];
+}
+declare function registerFieldType(manifest: FieldTypeManifest): void;
+declare function getFieldType(type: string): FieldTypeManifest | undefined;
+declare function listFieldTypes(): FieldTypeManifest[];
+declare function isEmptyValue(value: Json | undefined, field?: FieldBlock): boolean;
+/** A value in its stored form (see `FieldTypeManifest.normalize`). */
+declare function normalizeValue(value: Json, field: FieldBlock): Json;
+/** Whether a block holds personal or secret data: `sensitive: true`, or the `props.sensitive: true` alias. */
+declare function isSensitive(block: Block): boolean;
+declare function summarizeValue(value: Json | undefined, field: FieldBlock): string;
+interface ChoiceOption {
+    value: string;
+    label?: string;
+    /** A muted line under the label, such as a location's address. At most `OPTION_LIMITS.description` characters. */
+    description?: string;
+    /** A small picture beside the label: an `https://` URL, at most `OPTION_LIMITS.image` characters. */
+    image?: string;
+    /**
+     * Facts about the option for filtering and recall, such as `{ location: ["cff", "cornerstone"] }`
+     * for a coach who works at two locations (see `props.optionsFrom.filter`). Names and values are
+     * text; a value is one text or a list of them.
+     */
+    attributes?: Record<string, string | string[]>;
+}
+/** Bounds on an option's extra details. A longer or malformed detail is dropped when options are read. */
+declare const OPTION_LIMITS: {
+    /** Characters in a description. */
+    readonly description: 500;
+    /** Characters in an image URL. */
+    readonly image: 2048;
+    /** Attributes on one option. */
+    readonly attributes: 20;
+    /** Characters in an attribute's name. */
+    readonly attributeName: 64;
+    /** Characters in one attribute value. */
+    readonly attributeValue: 200;
+    /** Values in one attribute's list. */
+    readonly attributeItems: 50;
+};
+/**
+ * Whether `url` is an `https://` link with a host and no spaces or control characters, within
+ * `OPTION_LIMITS.image`. A pattern rather than `new URL`, so it behaves the same in React Native.
+ */
+declare function isHttpsUrl(url: unknown): url is string;
+/**
+ * An option from untrusted JSON (a definition, the host's list): its string `value`, and its
+ * `label`, `description`, `image` and `attributes` when each is well formed and within
+ * `OPTION_LIMITS`; anything else is left out. Null when there is no string value.
+ */
+declare function readOption(raw: unknown): ChoiceOption | null;
+/** An option as JSON, with only the details it has. */
+declare function optionJson(option: ChoiceOption): Json;
+/** The longest answer an "Other" option takes. */
+declare const OTHER_MAX_LENGTH = 200;
+/**
+ * A choice question's "Other" option (`props.other: true` or `{ label }`): the respondent types
+ * their own answer, stored as the answer's value itself (single choice, dropdown) or as one more
+ * item (multiple choice). Null when the question has none.
+ */
+declare function otherOption(field: FieldBlock): {
+    label: string;
+} | null;
+/** Whether a value is a typed "Other" answer: text that isn't one of the question's options. */
+declare function isOtherValue(field: FieldBlock, value: unknown): value is string;
+declare function choiceOptions(field: FieldBlock): ChoiceOption[];
+/**
+ * Option lists the app showing a form supplies, by key (`OptionsSource.key`):
+ * `{ coaches: [{ value: "8c1…", label: "Ada Lovelace" }] }`.
+ */
+type HostOptions = Readonly<Record<string, readonly ChoiceOption[]>>;
+/**
+ * A choice field's `props.optionsFrom`, when it is a well-formed `{ source: "host", key }`, with its
+ * `filter` when that is well formed too (`{ attribute, field }`, both non-empty text).
+ */
+declare function optionsSource(field: FieldBlock): OptionsSource | undefined;
+/**
+ * The definition with each `optionsFrom: { source: "host" }` field's options
+ * filled in from `hostOptions`: its own `props.options` first, then the host's
+ * list for its key (a value the field already has is not added twice). A key
+ * the host does not supply adds nothing, so the field offers its own options
+ * only. `createForm` and `validateSubmission` call it with their `hostOptions`,
+ * so a respondent sees, and a submit accepts, exactly these. Returns
+ * `definition` itself when no field takes options from the host.
+ */
+declare function withHostOptions(definition: FormDefinition, hostOptions: HostOptions | undefined): FormDefinition;
+/** The optional words under the ends of a rating or NPS scale ("Poor", "Great"). */
+declare function scaleLabels(field: FieldBlock): {
+    low?: string;
+    high?: string;
+};
+/** How a rating is drawn: `"numbers"` (default) or `"stars"`. */
+declare function ratingDisplay(field: FieldBlock): "numbers" | "stars";
+/** A `number` field's limits: `min`, `max` and `step` (each optional; `step` is above 0). */
+declare function numberLimits(field: FieldBlock): {
+    min?: number;
+    max?: number;
+    step?: number;
+};
+/** `YYYY-MM-DD`, a real calendar day (no 2026-02-30), years 0001 to 9999. */
+declare function isIsoDate(value: string): boolean;
+/** A `date` field's earliest and latest days (`YYYY-MM-DD`), when set. */
+declare function dateLimits(field: FieldBlock): {
+    min?: string;
+    max?: string;
+};
+
+/**
+ * Which options a choice question shows, and how they are picked: lists filtered by another
+ * answer, search for long lists, preselecting from a link, and snapshots of what was picked.
+ * Pure and renderer-agnostic, so the engine, the server and every renderer (web and native)
+ * decide the same way.
+ */
+
+/** Field types whose answer is one or more of their options. */
+declare const CHOICE_FIELD_TYPES: ReadonlySet<string>;
+/** A choice field's `props.optionsFrom.filter` (`{ attribute, field }`), when it is well formed. */
+declare function optionFilter(field: FieldBlock): {
+    attribute: string;
+    field: string;
+} | undefined;
+/**
+ * Whether an option matches an answer on one attribute: its `attributes[attribute]` (a text or a
+ * list) shares a value with the answer (a text, or a list from a multiple choice). An option
+ * without the attribute matches nothing.
+ */
+declare function optionMatches(option: ChoiceOption, attribute: string, answer: Json | undefined): boolean;
+/**
+ * The options a choice question shows given the answers so far (`values`, keyed by field id, as
+ * in `FormState.values`): all of `choiceOptions(field)`, or, with `props.optionsFrom.filter`,
+ * only those matching the filtered-by question's answer (`optionMatches`). While that question is
+ * unanswered (or isn't in the form) every option shows. Pass the definition with the host's lists
+ * filled in (`engine.definition`, or `withHostOptions`).
+ */
+declare function visibleOptions(definition: FormDefinition, field: FieldBlock, values: Readonly<Record<string, Json | undefined>>): ChoiceOption[];
+/**
+ * The answers on the respondent's path, by field id: what a filter reads. An answer to a question
+ * off the path (hidden by logic, jumped over) counts as none, as it does for logic. Pass these to
+ * `visibleOptions` from a renderer, so it shows exactly what the engine accepts.
+ */
+declare function answersOnPath(state: {
+    path: readonly string[];
+    values: Readonly<Record<string, Json | undefined>>;
+}): Record<string, Json | undefined>;
+/**
+ * Null, or the error for a (non-empty) choice answer that is one of the question's options but
+ * not one it shows now because of its filter (`visibleOptions`). A typed "Other" answer is left
+ * to the field type's own check. The engine and `validateSubmission` both call it, so a value
+ * outside the filtered list is refused on the server too.
+ */
+declare function filteredChoiceError(definition: FormDefinition, field: FieldBlock, value: Json | undefined, values: Readonly<Record<string, Json | undefined>>): string | null;
+/** Whether any choice question in the definition filters its options by another answer. */
+declare function hasOptionFilters(definition: FormDefinition): boolean;
+/**
+ * `values` after the answer to `changedId` changed, with every choice its filter no longer
+ * shows taken out: a single choice or dropdown is cleared, a multiple choice keeps the options
+ * that still show (and a typed "Other" answer). It follows on: clearing one question clears what
+ * was filtered by it. Returns `values` itself when nothing is cleared. The engine calls it on
+ * every answer, so a pick never outlives the answer it depended on.
+ */
+declare function clearFilteredAnswers(definition: FormDefinition, values: Record<string, Json | undefined>, changedId: string): Record<string, Json | undefined>;
+/** A choice question with more options than this gets a search box, unless `props.searchable` says otherwise. */
+declare const SEARCHABLE_OPTION_COUNT = 10;
+/**
+ * Whether a choice question shows a search box over its options: `props.searchable` when it is
+ * true or false, otherwise when it has more than `SEARCHABLE_OPTION_COUNT` options. The default
+ * counts all its options (`choiceOptions(field)`, with the host's lists filled in), so a list a
+ * filter narrows keeps its search box while the respondent answers.
+ */
+declare function isSearchable(field: FieldBlock, optionCount?: number): boolean;
+/**
+ * The options that match what the respondent typed, in their order: every word of `query` is
+ * found (ignoring case and accents) in the option's label, value or description. A blank query
+ * matches every option.
+ */
+declare function searchOptions(options: readonly ChoiceOption[], query: string): ChoiceOption[];
+/** Characters in a link parameter's name. */
+declare const MAX_PREFILL_PARAM_LENGTH = 64;
+/** A choice question's `props.prefill`: the link parameter that preselects it, and whether it is then hidden. */
+interface PrefillSetting {
+    /** The query parameter, as in `?location=cornerstone`. */
+    param: string;
+    /** Skip the question while the link has filled it in. */
+    hideWhenPrefilled: boolean;
+}
+/** A well-formed parameter name: letters, digits, `_`, `-` and `.`, at most `MAX_PREFILL_PARAM_LENGTH`. */
+declare function isPrefillParam(param: unknown): param is string;
+/** A choice field's `props.prefill` (`{ param, hideWhenPrefilled? }`), when it is well formed. */
+declare function prefillSetting(field: FieldBlock): PrefillSetting | undefined;
+/**
+ * A link's query parameters: a `URLSearchParams` (or anything with `getAll`), or a plain record
+ * of a text or a list of texts per name.
+ */
+type LinkParams = {
+    getAll(name: string): string[];
+} | Readonly<Record<string, string | readonly string[] | undefined>>;
+/**
+ * Answers a link preselects, by field id, for `createForm`'s `initialValues` (its `linkParams`
+ * option calls this). Each choice question with `props.prefill: { param }` takes the parameter's
+ * value when it is one of the options the question shows (`visibleOptions`, so a filtered list is
+ * respected); anything else is ignored. A multiple choice takes every matching value, from
+ * repeated parameters (`?coach=a&coach=b`) or one comma-separated value. Questions are filled in
+ * form order, so a filtered question sees what the link picked before it. A question `values`
+ * already answers (the host's own prefill) is left alone. The server checks these like any answer.
+ */
+declare function prefillFromLink(definition: FormDefinition, params: LinkParams | undefined, values?: Readonly<Record<string, Json | undefined>>): Record<string, Json>;
+/** The parts of a form's state `hiddenByPrefill` reads (a `FormState` has them all). */
+interface PrefillState {
+    path: readonly string[];
+    values: Readonly<Record<string, Json | undefined>>;
+    errors: Readonly<Record<string, string>>;
+    events: readonly FormEvent[];
+}
+/**
+ * Questions on the path the respondent skips because a prefill answered them: those with
+ * `props.prefill.hideWhenPrefilled` whose answer is still the prefilled one (the last answer
+ * event for them came from `initialValues` or a link) and has no error. The engine steps over
+ * them and renderers leave them out; their answers are stored like any other. A question shows
+ * again once its answer is cleared or changed (by a filter, say).
+ */
+declare function hiddenByPrefill(definition: FormDefinition, state: PrefillState): string[];
+/** The blocks the respondent steps through: the path without the questions a prefill hides (`hiddenByPrefill`). */
+declare function respondentPath(definition: FormDefinition, state: PrefillState): string[];
+/** One picked option as it was when the response was stored: its value (an id) and its label then. */
+interface OptionSnapshot {
+    value: string;
+    label: string;
+    /** A typed "Other" answer rather than one of the options. */
+    other?: true;
+}
+/** A choice answer's snapshot: one pick (single choice, dropdown) or a list (multiple choice). */
+type AnswerSnapshot = OptionSnapshot | OptionSnapshot[];
+/**
+ * Each answer to a choice question that takes options from the app (`props.optionsFrom`), as
+ * `{ value, label }` pairs as of now, by field id: store them beside the answers so reports
+ * group by the value (an id) while history keeps the name it had then. Pass the definition with
+ * the host's lists filled in (`withHostOptions`, or `engine.definition`) and the checked
+ * answers (`validateSubmission`'s `submission.answers`). A value that isn't one of the options
+ * keeps itself as its label, marked `other` (a typed "Other" answer).
+ */
+declare function answerSnapshots(definition: FormDefinition, answers: Readonly<Record<string, Json | undefined>>): Record<string, AnswerSnapshot>;
+/** What `answersFromSnapshots` found again. */
+interface RestoredAnswers {
+    /** Answers by field id, for `initialValues`: each pick's current value. */
+    answers: Record<string, Json>;
+    /** Picks no longer offered, by field id: the option was removed and no option has its label now. */
+    missing: Record<string, OptionSnapshot[]>;
+}
+/**
+ * The reverse of `answerSnapshots`, for an edit link: the answers to prefill from stored
+ * snapshots. A pick whose value is still an option keeps it; otherwise an option with the same
+ * label (ignoring case and accents) stands in, such as a location deleted and added again; a
+ * typed "Other" answer stays one when the question still allows it. Anything else is reported
+ * in `missing` and left out. Pass the definition with the host's current lists filled in.
+ */
+declare function answersFromSnapshots(definition: FormDefinition, snapshots: Readonly<Record<string, unknown>>): RestoredAnswers;
+
+/** The Standard Schema interface (standardschema.dev), as far as validation needs it. */
+interface StandardSchemaV1<T = unknown> {
+    readonly "~standard": {
+        readonly version: 1;
+        readonly vendor: string;
+        readonly validate: (value: unknown) => {
+            value: T;
+            issues?: undefined;
+        } | {
+            issues: ReadonlyArray<{
+                message: string;
+            }>;
+        } | Promise<unknown>;
+    };
+}
+/** A custom check for one field: a function, or any Standard Schema (Zod, Valibot, ArkType…). */
+type FieldValidator = ((value: Json) => string | null) | StandardSchemaV1;
+declare const REQUIRED_MESSAGE = "This question needs an answer.";
+/**
+ * Validate one field's value. `requireAnswers: false` (drafts) checks the
+ * format of what was answered without requiring the rest.
+ */
+declare function validateField(field: FieldBlock, value: Json | undefined, options?: {
+    requireAnswers?: boolean;
+    custom?: FieldValidator;
+}): string | null;
+
+export { withHostOptions as $, type AnswerSnapshot as A, numberLimits as B, CHOICE_FIELD_TYPES as C, optionFilter as D, optionJson as E, type FieldValidator as F, optionMatches as G, type HostOptions as H, optionsSource as I, otherOption as J, prefillFromLink as K, type LinkParams as L, MAX_PREFILL_PARAM_LENGTH as M, prefillSetting as N, OPTION_LIMITS as O, type PrefillSetting as P, ratingDisplay as Q, REQUIRED_MESSAGE as R, SEARCHABLE_OPTION_COUNT as S, readOption as T, registerFieldType as U, respondentPath as V, scaleLabels as W, searchOptions as X, summarizeValue as Y, validateField as Z, visibleOptions as _, type ChoiceOption as a, type FieldTypeManifest as b, OTHER_MAX_LENGTH as c, type OptionSnapshot as d, type PrefillState as e, type RestoredAnswers as f, type StandardSchemaV1 as g, answerSnapshots as h, answersFromSnapshots as i, answersOnPath as j, choiceOptions as k, clearFilteredAnswers as l, dateLimits as m, filteredChoiceError as n, getFieldType as o, hasOptionFilters as p, hiddenByPrefill as q, isEmptyValue as r, isHttpsUrl as s, isIsoDate as t, isOtherValue as u, isPrefillParam as v, isSearchable as w, isSensitive as x, listFieldTypes as y, normalizeValue as z };