@marktiderman/genesis-forms 0.4.2 → 0.6.0

package/dist/{engine-BkNuzlna.d.cts → engine-CpfOz8FN.d.ts}

@@ -1,5 +1,5 @@
-import { e as FormEvent, J as Json, F as FormDefinition, a as FieldBlock, B as Block } from './types-BBKBQ8sp.cjs';
-import { F as FieldValidator } from './validate-BXXqi0fq.cjs';
+import { e as FormEvent, J as Json, F as FormDefinition, a as FieldBlock, B as Block } from './types-oAckGR_Z.js';
+import { F as FieldValidator, H as HostOptions, L as LinkParams } from './validate-GpTXPwyl.js';
 
 /** Guards and helpers for event logs and other untrusted JSON. No dependencies. */
 
@@ -29,6 +29,11 @@ interface FormState {
     current: string | null;
     /** Visited blocks, for Back. */
     history: string[];
+    /**
+     * The furthest block reached by moving on (`next`), kept after going back;
+     * the first block until then. `formProgress` reads it.
+     */
+    furthest: string | null;
     errors: Record<string, string>;
     status: "in_progress" | "completed";
     /** The ending reached once completed. */
@@ -43,8 +48,33 @@ interface CreateFormOptions {
     validators?: Record<string, FieldValidator> | undefined;
     /** Timestamps on events. Pass `() => undefined` to record none (anonymous forms). */
     clock?: (() => number | undefined) | undefined;
+    /**
+     * Pick up where the respondent was (with `initialValues` holding their saved
+     * answers): a block id, usually `formProgress`'s `fieldId` from an earlier
+     * visit. The form moves on from the first block with Next, as they did, until
+     * it reaches this one, so Back still walks their path; it stops early at a
+     * step that no longer passes (a question since made required), and does
+     * nothing when the block isn't on the path.
+     */
+    resumeAt?: string | null | undefined;
+    /**
+     * The option lists this app supplies, by key, for choice fields with
+     * `props.optionsFrom: { source: "host", key }` (see `withHostOptions`).
+     * `engine.definition` is the definition with them filled in, so renderers
+     * show them and validation accepts only them (and the field's own options).
+     * Pass the same lists to `validateSubmission` on the server.
+     */
+    hostOptions?: HostOptions | undefined;
+    /**
+     * The query parameters of the link the form was opened from (a `URLSearchParams` or a record).
+     * Choice questions with `props.prefill: { param }` take their parameter's value when it is one
+     * of their options (`prefillFromLink`); `initialValues` win over the link. A question with
+     * `props.prefill.hideWhenPrefilled` is then stepped over (`hiddenByPrefill`).
+     */
+    linkParams?: LinkParams | undefined;
 }
 interface FormEngine {
+    /** The definition being filled in, with `hostOptions` filled in (`withHostOptions`). */
     readonly definition: FormDefinition;
     getState(): FormState;
     subscribe(listener: () => void): () => void;
@@ -72,6 +102,6 @@ interface FormEngine {
 }
 declare function createForm(definition: FormDefinition, options?: CreateFormOptions): FormEngine;
 /** Rebuild a form's state from its event log. Timestamps are ignored. */
-declare function replay(definition: FormDefinition, events: FormEvent[], options?: Omit<CreateFormOptions, "clock" | "initialValues">): FormEngine;
+declare function replay(definition: FormDefinition, events: FormEvent[], options?: Omit<CreateFormOptions, "clock" | "initialValues" | "linkParams">): FormEngine;
 
 export { type CreateFormOptions as C, type FormEngine as F, type FormState as a, isJson as b, createForm as c, compactEvents as d, isFormEvent as i, replay as r };

package/dist/{engine-Dz9J5ej2.d.ts → engine-DC4YTPdr.d.cts}

@@ -1,5 +1,5 @@
-import { e as FormEvent, J as Json, F as FormDefinition, a as FieldBlock, B as Block } from './types-BBKBQ8sp.js';
-import { F as FieldValidator } from './validate-BjNwF1UE.js';
+import { e as FormEvent, J as Json, F as FormDefinition, a as FieldBlock, B as Block } from './types-oAckGR_Z.cjs';
+import { F as FieldValidator, H as HostOptions, L as LinkParams } from './validate-B5WKHbst.cjs';
 
 /** Guards and helpers for event logs and other untrusted JSON. No dependencies. */
 
@@ -29,6 +29,11 @@ interface FormState {
     current: string | null;
     /** Visited blocks, for Back. */
     history: string[];
+    /**
+     * The furthest block reached by moving on (`next`), kept after going back;
+     * the first block until then. `formProgress` reads it.
+     */
+    furthest: string | null;
     errors: Record<string, string>;
     status: "in_progress" | "completed";
     /** The ending reached once completed. */
@@ -43,8 +48,33 @@ interface CreateFormOptions {
     validators?: Record<string, FieldValidator> | undefined;
     /** Timestamps on events. Pass `() => undefined` to record none (anonymous forms). */
     clock?: (() => number | undefined) | undefined;
+    /**
+     * Pick up where the respondent was (with `initialValues` holding their saved
+     * answers): a block id, usually `formProgress`'s `fieldId` from an earlier
+     * visit. The form moves on from the first block with Next, as they did, until
+     * it reaches this one, so Back still walks their path; it stops early at a
+     * step that no longer passes (a question since made required), and does
+     * nothing when the block isn't on the path.
+     */
+    resumeAt?: string | null | undefined;
+    /**
+     * The option lists this app supplies, by key, for choice fields with
+     * `props.optionsFrom: { source: "host", key }` (see `withHostOptions`).
+     * `engine.definition` is the definition with them filled in, so renderers
+     * show them and validation accepts only them (and the field's own options).
+     * Pass the same lists to `validateSubmission` on the server.
+     */
+    hostOptions?: HostOptions | undefined;
+    /**
+     * The query parameters of the link the form was opened from (a `URLSearchParams` or a record).
+     * Choice questions with `props.prefill: { param }` take their parameter's value when it is one
+     * of their options (`prefillFromLink`); `initialValues` win over the link. A question with
+     * `props.prefill.hideWhenPrefilled` is then stepped over (`hiddenByPrefill`).
+     */
+    linkParams?: LinkParams | undefined;
 }
 interface FormEngine {
+    /** The definition being filled in, with `hostOptions` filled in (`withHostOptions`). */
     readonly definition: FormDefinition;
     getState(): FormState;
     subscribe(listener: () => void): () => void;
@@ -72,6 +102,6 @@ interface FormEngine {
 }
 declare function createForm(definition: FormDefinition, options?: CreateFormOptions): FormEngine;
 /** Rebuild a form's state from its event log. Timestamps are ignored. */
-declare function replay(definition: FormDefinition, events: FormEvent[], options?: Omit<CreateFormOptions, "clock" | "initialValues">): FormEngine;
+declare function replay(definition: FormDefinition, events: FormEvent[], options?: Omit<CreateFormOptions, "clock" | "initialValues" | "linkParams">): FormEngine;
 
 export { type CreateFormOptions as C, type FormEngine as F, type FormState as a, isJson as b, createForm as c, compactEvents as d, isFormEvent as i, replay as r };