@marktiderman/genesis-forms 0.1.0 → 0.2.0

package/dist/index.d.cts

@@ -1,7 +1,7 @@
-import { F as FieldBlock, C as ContentBlock, P as PageBreakBlock, a as FormDefinition, H as HiddenInput, b as FormLayout, L as LogicRule, E as Ending, c as FormSettings, J as Json, d as Condition, B as Block, O as Operator, e as FieldValidator } from './validate-j8Z188mF.cjs';
-export { f as FormEvent, g as Operand, R as REQUIRED_MESSAGE, S as StandardSchemaV1, v as validateField } from './validate-j8Z188mF.cjs';
-import { F as FormEngine } from './engine-LsPRTzt3.cjs';
-export { C as CreateFormOptions, a as FormState, c as createForm, i as isFormEvent, b as isJson, r as replay } from './engine-LsPRTzt3.cjs';
+import { F as FieldBlock, C as ContentBlock, P as PageBreakBlock, a as FormDefinition, H as HiddenInput, b as FormLayout, L as LogicRule, E as Ending, c as FormSettings, J as Json, d as Condition, B as Block, O as Operator, e as FieldValidator } from './validate-BbackAjB.cjs';
+export { f as FormEvent, g as Operand, R as REQUIRED_MESSAGE, S as StandardSchemaV1, v as validateField } from './validate-BbackAjB.cjs';
+import { F as FormEngine } from './engine-Bj8-mMVb.cjs';
+export { C as CreateFormOptions, a as FormState, c as createForm, i as isFormEvent, b as isJson, r as replay } from './engine-Bj8-mMVb.cjs';
 
 /** A field block that remembers its key and value type, for answer inference. */
 type FieldSpec<K extends string = string, V = unknown> = FieldBlock & {
@@ -11,15 +11,15 @@ type FieldSpec<K extends string = string, V = unknown> = FieldBlock & {
 };
 interface FieldOptions {
     label: string;
-    description?: string;
-    placeholder?: string;
-    required?: boolean;
+    description?: string | undefined;
+    placeholder?: string | undefined;
+    required?: boolean | undefined;
     /** Personal or secret data (see `isSensitive`). */
-    sensitive?: boolean;
+    sensitive?: boolean | undefined;
     /** Identifies the respondent (name, email, phone). Not asked when `settings.anonymous` is true. */
-    identifying?: boolean;
+    identifying?: boolean | undefined;
     /** Defaults to the key. Set it before renaming a key on a live form, so answers stay linked. */
-    id?: string;
+    id?: string | undefined;
 }
 interface ChoiceFieldOptions<O extends string> extends FieldOptions {
     options: readonly {
@@ -28,20 +28,22 @@ interface ChoiceFieldOptions<O extends string> extends FieldOptions {
     }[];
 }
 interface HiddenOptions {
-    source?: HiddenInput["source"];
-    sensitive?: boolean;
+    source?: HiddenInput["source"] | undefined;
+    sensitive?: boolean | undefined;
+    /** Identifies the respondent. Not stored when `settings.anonymous` is true. */
+    identifying?: boolean | undefined;
 }
 declare const f: {
     shortText: <K extends string>(key: K, o: FieldOptions & {
-        maxLength?: number;
+        maxLength?: number | undefined;
     }) => FieldSpec<K, string>;
     longText: <K extends string>(key: K, o: FieldOptions & {
-        maxLength?: number;
+        maxLength?: number | undefined;
     }) => FieldSpec<K, string>;
     email: <K extends string>(key: K, o: FieldOptions) => FieldSpec<K, string>;
     phone: <K extends string>(key: K, o: FieldOptions) => FieldSpec<K, string>;
     rating: <K extends string>(key: K, o: FieldOptions & {
-        max?: number;
+        max?: number | undefined;
     }) => FieldSpec<K, number>;
     nps: <K extends string>(key: K, o: FieldOptions) => FieldSpec<K, number>;
     singleChoice: <K extends string, O extends string>(key: K, o: ChoiceFieldOptions<O>) => FieldSpec<K, O>;
@@ -56,19 +58,22 @@ declare const f: {
     pageBreak: (id: string, title?: string) => PageBreakBlock;
     hidden: {
         string: (o?: HiddenOptions) => {
-            sensitive?: true | undefined;
             type: "string";
-            source: "url" | "host" | "server";
+            source: HiddenInput["source"];
+            sensitive?: true;
+            identifying?: true;
         };
         number: (o?: HiddenOptions) => {
-            sensitive?: true | undefined;
             type: "number";
-            source: "url" | "host" | "server";
+            source: HiddenInput["source"];
+            sensitive?: true;
+            identifying?: true;
         };
         boolean: (o?: HiddenOptions) => {
-            sensitive?: true | undefined;
             type: "boolean";
-            source: "url" | "host" | "server";
+            source: HiddenInput["source"];
+            sensitive?: true;
+            identifying?: true;
         };
     };
 };
@@ -111,7 +116,8 @@ declare namespace when {
 type HiddenSpec = {
     type: HiddenInput["type"];
     source: HiddenInput["source"];
-    sensitive?: boolean;
+    sensitive?: boolean | undefined;
+    identifying?: boolean | undefined;
 };
 type HiddenValue<T extends HiddenSpec["type"]> = T extends "number" ? number : T extends "boolean" ? boolean : string;
 type AnyBlock = FieldSpec<string, unknown> | ContentBlock | PageBreakBlock;
@@ -187,7 +193,8 @@ interface CoercedHidden {
  * Convert one raw value to a hidden input's declared type, or `undefined` when
  * it cannot be. Only string, number and boolean primitives are accepted.
  * - `string`: a string (at most 1000 characters), or a number or boolean as text.
- * - `number`: a finite number, or a non-blank numeric string. `""` is not a number.
+ * - `number`: a finite number, or a plain decimal string such as `"12"`, `"-3"`
+ *   or `"2.5"`. No spaces, hex, exponents or `""`.
  * - `boolean`: `true`/`false`, or the strings `"true"`/`"false"`.
  */
 declare function coerceHiddenValue(value: unknown, type: HiddenInput["type"]): Json | undefined;

package/dist/index.d.ts

@@ -1,7 +1,7 @@
-import { F as FieldBlock, C as ContentBlock, P as PageBreakBlock, a as FormDefinition, H as HiddenInput, b as FormLayout, L as LogicRule, E as Ending, c as FormSettings, J as Json, d as Condition, B as Block, O as Operator, e as FieldValidator } from './validate-j8Z188mF.js';
-export { f as FormEvent, g as Operand, R as REQUIRED_MESSAGE, S as StandardSchemaV1, v as validateField } from './validate-j8Z188mF.js';
-import { F as FormEngine } from './engine-Cp5t2_Am.js';
-export { C as CreateFormOptions, a as FormState, c as createForm, i as isFormEvent, b as isJson, r as replay } from './engine-Cp5t2_Am.js';
+import { F as FieldBlock, C as ContentBlock, P as PageBreakBlock, a as FormDefinition, H as HiddenInput, b as FormLayout, L as LogicRule, E as Ending, c as FormSettings, J as Json, d as Condition, B as Block, O as Operator, e as FieldValidator } from './validate-BbackAjB.js';
+export { f as FormEvent, g as Operand, R as REQUIRED_MESSAGE, S as StandardSchemaV1, v as validateField } from './validate-BbackAjB.js';
+import { F as FormEngine } from './engine-Coc-gQIB.js';
+export { C as CreateFormOptions, a as FormState, c as createForm, i as isFormEvent, b as isJson, r as replay } from './engine-Coc-gQIB.js';
 
 /** A field block that remembers its key and value type, for answer inference. */
 type FieldSpec<K extends string = string, V = unknown> = FieldBlock & {
@@ -11,15 +11,15 @@ type FieldSpec<K extends string = string, V = unknown> = FieldBlock & {
 };
 interface FieldOptions {
     label: string;
-    description?: string;
-    placeholder?: string;
-    required?: boolean;
+    description?: string | undefined;
+    placeholder?: string | undefined;
+    required?: boolean | undefined;
     /** Personal or secret data (see `isSensitive`). */
-    sensitive?: boolean;
+    sensitive?: boolean | undefined;
     /** Identifies the respondent (name, email, phone). Not asked when `settings.anonymous` is true. */
-    identifying?: boolean;
+    identifying?: boolean | undefined;
     /** Defaults to the key. Set it before renaming a key on a live form, so answers stay linked. */
-    id?: string;
+    id?: string | undefined;
 }
 interface ChoiceFieldOptions<O extends string> extends FieldOptions {
     options: readonly {
@@ -28,20 +28,22 @@ interface ChoiceFieldOptions<O extends string> extends FieldOptions {
     }[];
 }
 interface HiddenOptions {
-    source?: HiddenInput["source"];
-    sensitive?: boolean;
+    source?: HiddenInput["source"] | undefined;
+    sensitive?: boolean | undefined;
+    /** Identifies the respondent. Not stored when `settings.anonymous` is true. */
+    identifying?: boolean | undefined;
 }
 declare const f: {
     shortText: <K extends string>(key: K, o: FieldOptions & {
-        maxLength?: number;
+        maxLength?: number | undefined;
     }) => FieldSpec<K, string>;
     longText: <K extends string>(key: K, o: FieldOptions & {
-        maxLength?: number;
+        maxLength?: number | undefined;
     }) => FieldSpec<K, string>;
     email: <K extends string>(key: K, o: FieldOptions) => FieldSpec<K, string>;
     phone: <K extends string>(key: K, o: FieldOptions) => FieldSpec<K, string>;
     rating: <K extends string>(key: K, o: FieldOptions & {
-        max?: number;
+        max?: number | undefined;
     }) => FieldSpec<K, number>;
     nps: <K extends string>(key: K, o: FieldOptions) => FieldSpec<K, number>;
     singleChoice: <K extends string, O extends string>(key: K, o: ChoiceFieldOptions<O>) => FieldSpec<K, O>;
@@ -56,19 +58,22 @@ declare const f: {
     pageBreak: (id: string, title?: string) => PageBreakBlock;
     hidden: {
         string: (o?: HiddenOptions) => {
-            sensitive?: true | undefined;
             type: "string";
-            source: "url" | "host" | "server";
+            source: HiddenInput["source"];
+            sensitive?: true;
+            identifying?: true;
         };
         number: (o?: HiddenOptions) => {
-            sensitive?: true | undefined;
             type: "number";
-            source: "url" | "host" | "server";
+            source: HiddenInput["source"];
+            sensitive?: true;
+            identifying?: true;
         };
         boolean: (o?: HiddenOptions) => {
-            sensitive?: true | undefined;
             type: "boolean";
-            source: "url" | "host" | "server";
+            source: HiddenInput["source"];
+            sensitive?: true;
+            identifying?: true;
         };
     };
 };
@@ -111,7 +116,8 @@ declare namespace when {
 type HiddenSpec = {
     type: HiddenInput["type"];
     source: HiddenInput["source"];
-    sensitive?: boolean;
+    sensitive?: boolean | undefined;
+    identifying?: boolean | undefined;
 };
 type HiddenValue<T extends HiddenSpec["type"]> = T extends "number" ? number : T extends "boolean" ? boolean : string;
 type AnyBlock = FieldSpec<string, unknown> | ContentBlock | PageBreakBlock;
@@ -187,7 +193,8 @@ interface CoercedHidden {
  * Convert one raw value to a hidden input's declared type, or `undefined` when
  * it cannot be. Only string, number and boolean primitives are accepted.
  * - `string`: a string (at most 1000 characters), or a number or boolean as text.
- * - `number`: a finite number, or a non-blank numeric string. `""` is not a number.
+ * - `number`: a finite number, or a plain decimal string such as `"12"`, `"-3"`
+ *   or `"2.5"`. No spaces, hex, exponents or `""`.
  * - `boolean`: `true`/`false`, or the strings `"true"`/`"false"`.
  */
 declare function coerceHiddenValue(value: unknown, type: HiddenInput["type"]): Json | undefined;

package/dist/index.js

@@ -397,7 +397,30 @@ function recallRefs(text) {
 }
 
 // src/parse.ts
+function shown(v) {
+  let text;
+  try {
+    text = JSON.stringify(v);
+  } catch {
+    text = void 0;
+  }
+  text ??= typeof v === "bigint" ? `${v}n` : typeof v;
+  return text.length > 60 ? `${text.slice(0, 57)}...` : text;
+}
 var isObject = (v) => !!v && typeof v === "object" && !Array.isArray(v);
+var isInt = (v) => typeof v === "number" && Number.isInteger(v);
+var LITERAL_TYPE = {
+  "short-text": "string",
+  "long-text": "string",
+  email: "string",
+  phone: "string",
+  rating: "number",
+  nps: "number",
+  "single-choice": "string",
+  "multi-choice": "string",
+  "yes-no": "boolean"
+};
+var ORDERING = /* @__PURE__ */ new Set(["lt", "lte", "gt", "gte"]);
 var OPERATORS = /* @__PURE__ */ new Set([
   "eq",
   "neq",
@@ -470,6 +493,7 @@ function parseForm(input) {
   const keys = /* @__PURE__ */ new Map();
   const fieldTypes = /* @__PURE__ */ new Map();
   const order = /* @__PURE__ */ new Map();
+  const choices = /* @__PURE__ */ new Map();
   input.blocks.forEach((block, i) => {
     const path = `blocks[${i}]`;
     if (!isObject(block) || typeof block.id !== "string" || !block.id) {
@@ -503,8 +527,19 @@ function parseForm(input) {
               if (!isObject(o) || typeof o.value !== "string") issue(at, "Each option needs a string value.");
               else optionalText(o.label, `${at}.label`);
             });
+            choices.set(
+              block.id,
+              new Set(options.flatMap((o) => isObject(o) && typeof o.value === "string" ? [o.value] : []))
+            );
           }
         }
+        const { max, maxLength: maxLength2 } = isObject(block.props) ? block.props : {};
+        if (block.type === "rating" && max !== void 0 && !(isInt(max) && max >= 2 && max <= 10)) {
+          issue(`${path}.props.max`, "Must be a whole number from 2 to 10.");
+        }
+        if (maxLength2 !== void 0 && !(isInt(maxLength2) && maxLength2 > 0)) {
+          issue(`${path}.props.maxLength`, "Must be a whole number above 0.");
+        }
       }
       if (validKey) {
         if (keys.has(block.key)) issue(`${path}.key`, `Duplicate key "${String(block.key)}".`);
@@ -521,6 +556,7 @@ function parseForm(input) {
     }
   });
   const hiddenNames = /* @__PURE__ */ new Set();
+  const hiddenTypes = /* @__PURE__ */ new Map();
   if (input.hidden !== void 0 && !Array.isArray(input.hidden)) issue("hidden", "Must be an array.");
   (Array.isArray(input.hidden) ? input.hidden : []).forEach((h, i) => {
     if (!isObject(h) || typeof h.name !== "string" || !h.name) {
@@ -536,7 +572,9 @@ function parseForm(input) {
       issue(`hidden[${i}].type`, "Must be string, number or boolean.");
     }
     optionalBoolean(h.sensitive, `hidden[${i}].sensitive`);
+    optionalBoolean(h.identifying, `hidden[${i}].identifying`);
     hiddenNames.add(h.name);
+    if (typeof h.type === "string") hiddenTypes.set(h.name, h.type);
   });
   const endingIds = /* @__PURE__ */ new Set();
   if (input.endings !== void 0 && !Array.isArray(input.endings)) issue("endings", "Must be an array.");
@@ -585,8 +623,45 @@ function parseForm(input) {
     if (typeof c.left.field === "string") {
       const manifest = getFieldType(fieldTypes.get(c.left.field) ?? "");
       if (manifest && OPERATORS.has(c.op) && !manifest.operators.includes(c.op)) {
-        issue(`${path}.op`, `"${c.op}" does not apply to a ${manifest.type} field.`);
+        return issue(`${path}.op`, `"${c.op}" does not apply to a ${manifest.type} field.`);
+      }
+    }
+    checkLiterals(c.op, c.left, c.right, path);
+  };
+  const checkLiterals = (op, left, right, path) => {
+    if (op === "answered" || op === "empty" || !OPERATORS.has(op)) return;
+    const literal = isObject(right) && "value" in right;
+    if (right !== void 0 && !literal) return;
+    let what = "the left side";
+    let type;
+    let options;
+    if (typeof left.field === "string" && fieldTypes.has(left.field)) {
+      const fieldType = fieldTypes.get(left.field);
+      what = `"${keyOf(left.field)}"`;
+      type = LITERAL_TYPE[fieldType];
+      if (fieldType === "single-choice" || fieldType === "multi-choice") options = choices.get(left.field);
+    } else if (typeof left.hidden === "string" && hiddenTypes.has(left.hidden)) {
+      what = `hidden input "${left.hidden}"`;
+      type = hiddenTypes.get(left.hidden);
+    }
+    const outcome = op === "neq" ? "always true" : "never true";
+    let values;
+    if (op === "in") {
+      if (!literal || !Array.isArray(right.value)) {
+        return void warnings.push({ path: `${path}.right`, message: "`in` needs a list of values; it never matches." });
+      }
+      values = right.value;
+    } else if (!literal) return;
+    else values = [right.value];
+    if (ORDERING.has(op)) {
+      if (type !== void 0 && type !== "number") {
+        return void warnings.push({ path: `${path}.op`, message: `"${op}" compares numbers, but ${what} holds a ${type}; it is never true.` });
       }
+      type = "number";
+    }
+    for (const v of values) {
+      const message = type !== void 0 && typeof v !== type ? `${what} holds a ${type}, but ${shown(v)} is not one; this comparison is ${outcome}.` : options && typeof v === "string" && !options.has(v) ? `${shown(v)} is not an option of ${what}; this comparison is ${outcome}.` : null;
+      if (message) warnings.push({ path: `${path}.right`, message });
     }
   };
   const keyOf = (id) => [...keys].find(([, v]) => v === id)?.[0] ?? id;
@@ -663,6 +738,18 @@ function parseForm(input) {
       }
     }
   });
+  const extra = [["description", input.description]];
+  (Array.isArray(input.endings) ? input.endings : []).forEach((e, i) => {
+    if (isObject(e)) extra.push([`endings[${i}]`, e.title], [`endings[${i}]`, e.description]);
+  });
+  for (const [path, t] of extra) {
+    if (typeof t !== "string") continue;
+    for (const ref of recallRefs(t)) {
+      if (ref.kind === "hidden" ? !hiddenNames.has(ref.name) : !keys.has(ref.name)) {
+        warnings.push({ path, message: `Recalls unknown ${ref.kind === "hidden" ? "hidden input" : "field"} "${ref.name}"; it shows its fallback text.` });
+      }
+    }
+  }
   return issues.length ? fail() : { ok: true, form: input, warnings };
 }
 
@@ -689,7 +776,8 @@ var choiceProps = (options) => ({
 var hiddenSpec = (type, o) => ({
   type,
   source: o.source ?? "url",
-  ...o.sensitive ? { sensitive: true } : {}
+  ...o.sensitive ? { sensitive: true } : {},
+  ...o.identifying ? { identifying: true } : {}
 });
 var f = {
   shortText: (key, o) => field("short-text", key, o, o.maxLength ? { maxLength: o.maxLength } : void 0),
@@ -784,7 +872,8 @@ function defineForm(input) {
       name,
       type: spec.type,
       source: spec.source,
-      ...spec.sensitive ? { sensitive: true } : {}
+      ...spec.sensitive ? { sensitive: true } : {},
+      ...spec.identifying ? { identifying: true } : {}
     }));
   }
   if (input.logic?.length) definition.logic = input.logic.map((rule, i) => rule.build(resolve2, `r${i + 1}`));
@@ -809,6 +898,7 @@ ${list}`);
 
 // src/hidden.ts
 var MAX_HIDDEN_STRING_LENGTH = 1e3;
+var DECIMAL = /^-?\d+(\.\d+)?$/;
 function coerceHiddenValue(value, type) {
   if (typeof value === "string" && value.length > MAX_HIDDEN_STRING_LENGTH) return void 0;
   if (type === "string") {
@@ -818,7 +908,7 @@ function coerceHiddenValue(value, type) {
   }
   if (type === "number") {
     if (typeof value === "number") return Number.isFinite(value) ? value : void 0;
-    if (typeof value !== "string" || value.trim() === "") return void 0;
+    if (typeof value !== "string" || !DECIMAL.test(value)) return void 0;
     const n = Number(value);
     return Number.isFinite(n) ? n : void 0;
   }
@@ -999,7 +1089,7 @@ function build(definition, options, replaying = false) {
       for (const id of state.path) {
         const field2 = fields.get(id);
         const value = own(state.values, id);
-        if (field2 && value !== void 0) out[id] = normalizeValue(value, field2);
+        if (field2 && !isEmptyValue(value, field2)) out[id] = normalizeValue(value, field2);
       }
       return out;
     }