@marktiderman/genesis-forms 0.0.0-stage → 0.1.0

package/conformance/contact-details-anonymous-form-skips-identifying-fields.scenario.json

@@ -0,0 +1,125 @@
+{
+  "scenarioVersion": 1,
+  "name": "contact-details: anonymous form skips identifying fields",
+  "description": "With settings.anonymous true, identifying fields are off the path and not required; the server drops client-sent values for them and lists them in ignored.",
+  "tags": [
+    "contact-details",
+    "identifying",
+    "anonymous",
+    "server",
+    "security"
+  ],
+  "definition": {
+    "schemaVersion": 1,
+    "id": "contact-details-anonymous",
+    "title": "Tell us about your visit",
+    "blocks": [
+      {
+        "kind": "field",
+        "id": "overall",
+        "key": "overall",
+        "type": "rating",
+        "label": "How was your visit?",
+        "required": true,
+        "props": {
+          "max": 5
+        }
+      },
+      {
+        "kind": "field",
+        "id": "name",
+        "key": "name",
+        "type": "short-text",
+        "label": "Your name",
+        "required": true,
+        "identifying": true
+      },
+      {
+        "kind": "field",
+        "id": "email",
+        "key": "email",
+        "type": "email",
+        "label": "Email",
+        "required": true,
+        "identifying": true
+      },
+      {
+        "kind": "field",
+        "id": "phone",
+        "key": "phone",
+        "type": "phone",
+        "label": "Phone",
+        "identifying": true
+      },
+      {
+        "kind": "field",
+        "id": "comments",
+        "key": "comments",
+        "type": "long-text",
+        "label": "Anything else?"
+      }
+    ],
+    "endings": [
+      {
+        "id": "default",
+        "title": "Thanks!"
+      }
+    ],
+    "settings": {
+      "anonymous": true
+    }
+  },
+  "events": [
+    {
+      "type": "answer",
+      "field": "overall",
+      "value": 5
+    },
+    {
+      "type": "answer",
+      "field": "name",
+      "value": "Ada"
+    },
+    {
+      "type": "answer",
+      "field": "email",
+      "value": "ada@example.com"
+    },
+    {
+      "type": "answer",
+      "field": "phone",
+      "value": "+1 555 010 0199"
+    },
+    {
+      "type": "submit"
+    }
+  ],
+  "expect": {
+    "path": [
+      "overall",
+      "comments"
+    ],
+    "visible": [
+      "overall",
+      "comments"
+    ],
+    "current": "overall",
+    "status": "completed",
+    "ending": "default",
+    "answers": {
+      "overall": 5
+    },
+    "server": {
+      "ok": true,
+      "answers": {
+        "overall": 5
+      },
+      "context": {},
+      "ignored": [
+        "name",
+        "email",
+        "phone"
+      ]
+    }
+  }
+}

package/conformance/contact-details-named-form-asks-for-identifying-fields.scenario.json

@@ -0,0 +1,129 @@
+{
+  "scenarioVersion": 1,
+  "name": "contact-details: named form asks for identifying fields",
+  "description": "With settings.anonymous false, name, email and phone are asked, validated and stored (email and phone trimmed).",
+  "tags": [
+    "contact-details",
+    "identifying"
+  ],
+  "definition": {
+    "schemaVersion": 1,
+    "id": "contact-details",
+    "title": "Tell us about your visit",
+    "blocks": [
+      {
+        "kind": "field",
+        "id": "overall",
+        "key": "overall",
+        "type": "rating",
+        "label": "How was your visit?",
+        "required": true,
+        "props": {
+          "max": 5
+        }
+      },
+      {
+        "kind": "field",
+        "id": "name",
+        "key": "name",
+        "type": "short-text",
+        "label": "Your name",
+        "required": true,
+        "identifying": true
+      },
+      {
+        "kind": "field",
+        "id": "email",
+        "key": "email",
+        "type": "email",
+        "label": "Email",
+        "required": true,
+        "identifying": true
+      },
+      {
+        "kind": "field",
+        "id": "phone",
+        "key": "phone",
+        "type": "phone",
+        "label": "Phone",
+        "identifying": true
+      },
+      {
+        "kind": "field",
+        "id": "comments",
+        "key": "comments",
+        "type": "long-text",
+        "label": "Anything else?"
+      }
+    ],
+    "endings": [
+      {
+        "id": "default",
+        "title": "Thanks!"
+      }
+    ],
+    "settings": {
+      "anonymous": false
+    }
+  },
+  "events": [
+    {
+      "type": "answer",
+      "field": "overall",
+      "value": 4
+    },
+    {
+      "type": "answer",
+      "field": "name",
+      "value": "Ada"
+    },
+    {
+      "type": "answer",
+      "field": "email",
+      "value": " ada@example.com "
+    },
+    {
+      "type": "answer",
+      "field": "phone",
+      "value": "+1 (555) 010-0199"
+    },
+    {
+      "type": "submit"
+    }
+  ],
+  "expect": {
+    "path": [
+      "overall",
+      "name",
+      "email",
+      "phone",
+      "comments"
+    ],
+    "visible": [
+      "overall",
+      "name",
+      "email",
+      "phone",
+      "comments"
+    ],
+    "current": "overall",
+    "status": "completed",
+    "ending": "default",
+    "answers": {
+      "overall": 4,
+      "name": "Ada",
+      "email": "ada@example.com",
+      "phone": "+1 (555) 010-0199"
+    },
+    "server": {
+      "ok": true,
+      "answers": {
+        "overall": 4,
+        "name": "Ada",
+        "email": "ada@example.com",
+        "phone": "+1 (555) 010-0199"
+      },
+      "context": {}
+    }
+  }
+}

package/conformance/monthly-pulse-default-ending.scenario.json

@@ -0,0 +1,148 @@
+{
+  "scenarioVersion": 1,
+  "name": "monthly-pulse: default ending",
+  "description": "NPS 8 is one under the jump's boundary: every question is asked and the default ending is reached.",
+  "tags": [
+    "monthly-pulse",
+    "ending"
+  ],
+  "definition": {
+    "schemaVersion": 1,
+    "id": "monthly-pulse",
+    "title": "Monthly check-in",
+    "blocks": [
+      {
+        "kind": "field",
+        "id": "recommend",
+        "key": "recommend",
+        "type": "nps",
+        "label": "How likely are you to recommend CrossFit Fairfield to a friend?",
+        "required": true
+      },
+      {
+        "kind": "field",
+        "id": "why",
+        "key": "why",
+        "type": "long-text",
+        "label": "What's the main reason for your score?"
+      },
+      {
+        "kind": "field",
+        "id": "frequency",
+        "key": "frequency",
+        "type": "single-choice",
+        "label": "How often did you train with us this month?",
+        "props": {
+          "options": [
+            {
+              "value": "1-4",
+              "label": "1–4 times"
+            },
+            {
+              "value": "5-8",
+              "label": "5–8 times"
+            },
+            {
+              "value": "9-12",
+              "label": "9–12 times"
+            },
+            {
+              "value": "13+",
+              "label": "13 or more"
+            }
+          ]
+        }
+      }
+    ],
+    "layout": {
+      "mode": "focus"
+    },
+    "logic": [
+      {
+        "id": "r1",
+        "when": {
+          "op": "gte",
+          "left": {
+            "field": "recommend"
+          },
+          "right": {
+            "value": 9
+          }
+        },
+        "effect": "jump",
+        "from": "recommend",
+        "to": {
+          "ending": "promoter"
+        }
+      }
+    ],
+    "endings": [
+      {
+        "id": "default",
+        "title": "Thanks for the honest feedback."
+      },
+      {
+        "id": "promoter",
+        "title": "Thank you! Bring a friend to a free class anytime."
+      }
+    ],
+    "settings": {
+      "anonymous": true
+    }
+  },
+  "events": [
+    {
+      "type": "answer",
+      "field": "recommend",
+      "value": 8
+    },
+    {
+      "type": "next"
+    },
+    {
+      "type": "answer",
+      "field": "why",
+      "value": "Busy month"
+    },
+    {
+      "type": "next"
+    },
+    {
+      "type": "answer",
+      "field": "frequency",
+      "value": "5-8"
+    },
+    {
+      "type": "submit"
+    }
+  ],
+  "expect": {
+    "path": [
+      "recommend",
+      "why",
+      "frequency"
+    ],
+    "visible": [
+      "recommend",
+      "why",
+      "frequency"
+    ],
+    "current": "frequency",
+    "status": "completed",
+    "ending": "default",
+    "answers": {
+      "recommend": 8,
+      "why": "Busy month",
+      "frequency": "5-8"
+    },
+    "server": {
+      "ok": true,
+      "answers": {
+        "recommend": 8,
+        "why": "Busy month",
+        "frequency": "5-8"
+      },
+      "context": {}
+    }
+  }
+}

package/conformance/monthly-pulse-promoter-ending-via-jump.scenario.json

@@ -0,0 +1,128 @@
+{
+  "scenarioVersion": 1,
+  "name": "monthly-pulse: promoter ending via jump",
+  "description": "NPS 9 or more jumps straight to the promoter ending; why and frequency are never asked.",
+  "tags": [
+    "monthly-pulse",
+    "jump",
+    "ending"
+  ],
+  "definition": {
+    "schemaVersion": 1,
+    "id": "monthly-pulse",
+    "title": "Monthly check-in",
+    "blocks": [
+      {
+        "kind": "field",
+        "id": "recommend",
+        "key": "recommend",
+        "type": "nps",
+        "label": "How likely are you to recommend CrossFit Fairfield to a friend?",
+        "required": true
+      },
+      {
+        "kind": "field",
+        "id": "why",
+        "key": "why",
+        "type": "long-text",
+        "label": "What's the main reason for your score?"
+      },
+      {
+        "kind": "field",
+        "id": "frequency",
+        "key": "frequency",
+        "type": "single-choice",
+        "label": "How often did you train with us this month?",
+        "props": {
+          "options": [
+            {
+              "value": "1-4",
+              "label": "1–4 times"
+            },
+            {
+              "value": "5-8",
+              "label": "5–8 times"
+            },
+            {
+              "value": "9-12",
+              "label": "9–12 times"
+            },
+            {
+              "value": "13+",
+              "label": "13 or more"
+            }
+          ]
+        }
+      }
+    ],
+    "layout": {
+      "mode": "focus"
+    },
+    "logic": [
+      {
+        "id": "r1",
+        "when": {
+          "op": "gte",
+          "left": {
+            "field": "recommend"
+          },
+          "right": {
+            "value": 9
+          }
+        },
+        "effect": "jump",
+        "from": "recommend",
+        "to": {
+          "ending": "promoter"
+        }
+      }
+    ],
+    "endings": [
+      {
+        "id": "default",
+        "title": "Thanks for the honest feedback."
+      },
+      {
+        "id": "promoter",
+        "title": "Thank you! Bring a friend to a free class anytime."
+      }
+    ],
+    "settings": {
+      "anonymous": true
+    }
+  },
+  "events": [
+    {
+      "type": "answer",
+      "field": "recommend",
+      "value": 9
+    },
+    {
+      "type": "next"
+    },
+    {
+      "type": "submit"
+    }
+  ],
+  "expect": {
+    "path": [
+      "recommend"
+    ],
+    "visible": [
+      "recommend"
+    ],
+    "current": "recommend",
+    "status": "completed",
+    "ending": "promoter",
+    "answers": {
+      "recommend": 9
+    },
+    "server": {
+      "ok": true,
+      "answers": {
+        "recommend": 9
+      },
+      "context": {}
+    }
+  }
+}

package/dist/engine-Cp5t2_Am.d.ts

@@ -0,0 +1,75 @@
+import { f as FormEvent, J as Json, e as FieldValidator, a as FormDefinition, F as FieldBlock, B as Block } from './validate-j8Z188mF.js';
+
+/** Guards and helpers for event logs and other untrusted JSON. No dependencies. */
+
+/**
+ * Whether a value is JSON: strings, finite numbers, booleans, null, arrays and
+ * plain objects, nested to any depth. Iterative, so a deeply nested value
+ * cannot overflow the stack.
+ */
+declare function isJson(value: unknown): value is Json;
+/** Whether `value` is a well-formed `FormEvent` of a known type. */
+declare function isFormEvent(value: unknown): value is FormEvent;
+/**
+ * Merge consecutive answer events to the same field, keeping the last value.
+ * Text inputs log one event per keystroke; the merged log replays to the same
+ * state, because the path is derived from values alone.
+ */
+declare function compactEvents(events: FormEvent[]): FormEvent[];
+
+interface FormState {
+    /** Answers keyed by block id. */
+    values: Record<string, Json | undefined>;
+    /** URL and host inputs (untrusted) and server-resolved inputs, by name. */
+    hidden: Record<string, Json | undefined>;
+    /** Block ids the respondent steps through, given the answers so far. */
+    path: string[];
+    /** The block on screen in focus layout. */
+    current: string | null;
+    /** Visited blocks, for Back. */
+    history: string[];
+    errors: Record<string, string>;
+    status: "in_progress" | "completed";
+    /** The ending reached once completed. */
+    ending: string | null;
+    events: FormEvent[];
+}
+interface CreateFormOptions {
+    /** Prefilled answers by field id. Logged as leading `answer` events with `source: "prefill"`. */
+    initialValues?: Record<string, Json>;
+    /** Hidden inputs by name. Declared ones are typed with `coerceHidden`, as the server types them. */
+    hidden?: Record<string, Json | undefined>;
+    validators?: Record<string, FieldValidator>;
+    /** Timestamps on events. Pass `() => undefined` to record none (anonymous forms). */
+    clock?: () => number | undefined;
+}
+interface FormEngine {
+    readonly definition: FormDefinition;
+    getState(): FormState;
+    subscribe(listener: () => void): () => void;
+    /** A field's id, from its key. */
+    idOf(key: string): string;
+    field(id: string): FieldBlock | undefined;
+    block(id: string): Block | undefined;
+    isVisible(id: string): boolean;
+    /**
+     * Set an answer. Like `next`, `back` and `submit`, it does nothing once the
+     * response is completed: a completed response is final, so its stored
+     * answers are the ones that were validated.
+     */
+    setValue(id: string, value: Json | undefined): void;
+    /** Validate the current step and move on. Returns false if it has errors. */
+    next(): boolean;
+    back(): void;
+    /** Validate every visible field and complete. Returns false if it has errors or is already completed. */
+    submit(): boolean;
+    /** Text with `{{recall}}` tokens resolved. */
+    text(template: string): string;
+    /** Visible field values only, keyed by id: what a submit stores. */
+    answers(): Record<string, Json>;
+}
+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;
+
+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-LsPRTzt3.d.cts

@@ -0,0 +1,75 @@
+import { f as FormEvent, J as Json, e as FieldValidator, a as FormDefinition, F as FieldBlock, B as Block } from './validate-j8Z188mF.cjs';
+
+/** Guards and helpers for event logs and other untrusted JSON. No dependencies. */
+
+/**
+ * Whether a value is JSON: strings, finite numbers, booleans, null, arrays and
+ * plain objects, nested to any depth. Iterative, so a deeply nested value
+ * cannot overflow the stack.
+ */
+declare function isJson(value: unknown): value is Json;
+/** Whether `value` is a well-formed `FormEvent` of a known type. */
+declare function isFormEvent(value: unknown): value is FormEvent;
+/**
+ * Merge consecutive answer events to the same field, keeping the last value.
+ * Text inputs log one event per keystroke; the merged log replays to the same
+ * state, because the path is derived from values alone.
+ */
+declare function compactEvents(events: FormEvent[]): FormEvent[];
+
+interface FormState {
+    /** Answers keyed by block id. */
+    values: Record<string, Json | undefined>;
+    /** URL and host inputs (untrusted) and server-resolved inputs, by name. */
+    hidden: Record<string, Json | undefined>;
+    /** Block ids the respondent steps through, given the answers so far. */
+    path: string[];
+    /** The block on screen in focus layout. */
+    current: string | null;
+    /** Visited blocks, for Back. */
+    history: string[];
+    errors: Record<string, string>;
+    status: "in_progress" | "completed";
+    /** The ending reached once completed. */
+    ending: string | null;
+    events: FormEvent[];
+}
+interface CreateFormOptions {
+    /** Prefilled answers by field id. Logged as leading `answer` events with `source: "prefill"`. */
+    initialValues?: Record<string, Json>;
+    /** Hidden inputs by name. Declared ones are typed with `coerceHidden`, as the server types them. */
+    hidden?: Record<string, Json | undefined>;
+    validators?: Record<string, FieldValidator>;
+    /** Timestamps on events. Pass `() => undefined` to record none (anonymous forms). */
+    clock?: () => number | undefined;
+}
+interface FormEngine {
+    readonly definition: FormDefinition;
+    getState(): FormState;
+    subscribe(listener: () => void): () => void;
+    /** A field's id, from its key. */
+    idOf(key: string): string;
+    field(id: string): FieldBlock | undefined;
+    block(id: string): Block | undefined;
+    isVisible(id: string): boolean;
+    /**
+     * Set an answer. Like `next`, `back` and `submit`, it does nothing once the
+     * response is completed: a completed response is final, so its stored
+     * answers are the ones that were validated.
+     */
+    setValue(id: string, value: Json | undefined): void;
+    /** Validate the current step and move on. Returns false if it has errors. */
+    next(): boolean;
+    back(): void;
+    /** Validate every visible field and complete. Returns false if it has errors or is already completed. */
+    submit(): boolean;
+    /** Text with `{{recall}}` tokens resolved. */
+    text(template: string): string;
+    /** Visible field values only, keyed by id: what a submit stores. */
+    answers(): Record<string, Json>;
+}
+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;
+
+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 };