@marktiderman/genesis-forms 0.4.2 → 0.5.0

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

@@ -32,6 +32,18 @@ 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;
+}
 interface ContentBlock {
     kind: "content";
     id: string;
@@ -112,6 +124,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 +172,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-BhYUbLJ-.d.ts}

@@ -32,6 +32,18 @@ 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;
+}
 interface ContentBlock {
     kind: "content";
     id: string;
@@ -112,6 +124,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 +172,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-Bs1lyoOl.d.ts

@@ -0,0 +1,131 @@
+import { J as Json, g as Operator, a as FieldBlock, B as Block, O as OptionsSource, F as FormDefinition } from './types-BhYUbLJ-.js';
+
+/**
+ * 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;
+}
+/** 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 }`. */
+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;
+};
+
+/** 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 { type ChoiceOption as C, type FieldValidator as F, type HostOptions as H, OTHER_MAX_LENGTH as O, REQUIRED_MESSAGE as R, type StandardSchemaV1 as S, type FieldTypeManifest as a, isIsoDate as b, choiceOptions as c, dateLimits as d, isOtherValue as e, isSensitive as f, getFieldType as g, numberLimits as h, isEmptyValue as i, otherOption as j, registerFieldType as k, listFieldTypes as l, summarizeValue as m, normalizeValue as n, optionsSource as o, ratingDisplay as r, scaleLabels as s, validateField as v, withHostOptions as w };

package/dist/validate-BsZ0YTQS.d.cts

@@ -0,0 +1,131 @@
+import { J as Json, g as Operator, a as FieldBlock, B as Block, O as OptionsSource, F as FormDefinition } from './types-BhYUbLJ-.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;
+}
+/** 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 }`. */
+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;
+};
+
+/** 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 { type ChoiceOption as C, type FieldValidator as F, type HostOptions as H, OTHER_MAX_LENGTH as O, REQUIRED_MESSAGE as R, type StandardSchemaV1 as S, type FieldTypeManifest as a, isIsoDate as b, choiceOptions as c, dateLimits as d, isOtherValue as e, isSensitive as f, getFieldType as g, numberLimits as h, isEmptyValue as i, otherOption as j, registerFieldType as k, listFieldTypes as l, summarizeValue as m, normalizeValue as n, optionsSource as o, ratingDisplay as r, scaleLabels as s, validateField as v, withHostOptions as w };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@marktiderman/genesis-forms",
-  "version": "0.4.2",
+  "version": "0.5.0",
   "private": false,
   "type": "module",
   "sideEffects": [

package/dist/validate-BXXqi0fq.d.cts

@@ -1,30 +0,0 @@
-import { J as Json, a as FieldBlock } from './types-BBKBQ8sp.cjs';
-
-/** 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 { type FieldValidator as F, REQUIRED_MESSAGE as R, type StandardSchemaV1 as S, validateField as v };

package/dist/validate-BjNwF1UE.d.ts

@@ -1,30 +0,0 @@
-import { J as Json, a as FieldBlock } from './types-BBKBQ8sp.js';
-
-/** 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 { type FieldValidator as F, REQUIRED_MESSAGE as R, type StandardSchemaV1 as S, validateField as v };