@marktiderman/genesis-forms 0.3.0 → 0.4.0

package/README.md

@@ -5,7 +5,7 @@ can be stored, diffed, versioned, and evaluated identically in a browser, in Rea
 server. Zero dependencies.
 
 **Status: 0.1, release R1.** Field types: `short-text`, `long-text`, `email`, `phone`, `rating`,
-`nps`, `single-choice`, `multi-choice`, `yes-no`. Logic: show, hide, jump to a field or an ending. Layouts
+`nps`, `single-choice`, `multi-choice`, `yes-no`, `dropdown`, `number`, `date`, `consent`. Logic: show, hide, jump to a field or an ending. Layouts
 (rendered by `genesis-forms-web`): focus (one question at a time) and classic. The full plan is in
 [docs/FORMS.md](../../docs/FORMS.md).
 
@@ -85,6 +85,19 @@ space, `-`, `(`, `)` and `.`, 7 to 15 digits, at most 32 characters. Operators:
 `answered`, `empty`. Its manifest carries `autocomplete: "tel"` and `inputMode: "tel"` (email:
 `"email"` for both).
 
+### Dropdown, number, date and consent
+
+| Type and builder | Value | Notes |
+| --- | --- | --- |
+| `dropdown`, `f.dropdown(key, { options })` | one option's value | Like single choice, from a compact menu. Operators: `eq`, `neq`, `in`, `answered`, `empty`. |
+| `number`, `f.number(key, { min, max, step })` | `number` | All limits optional; `step` counts from `min`, else 0 (`step: 1` for whole numbers). Supports `lt`/`gt` logic. `numberLimits(field)`. |
+| `date`, `f.date(key, { min, max })` | `"YYYY-MM-DD"` | A real calendar day within the optional limits. Operators: `eq`, `neq`, `answered`, `empty`. `isIsoDate`, `dateLimits(field)`. |
+| `consent`, `f.consent(key, { text })` | `true` | One checkbox; unchecked is unanswered, so `required` means it must be checked. Summarized as "Agreed". |
+
+`f.rating` also takes `lowLabel`, `highLabel` (words under the ends, such as "Poor" and "Great") and
+`display: "numbers" | "stars"`; `f.nps` takes the labels too. `summarizeValue` adds an end's label:
+`"5/5 (Great)"`. Helpers: `scaleLabels(field)`, `ratingDisplay(field)`.
+
 ### Structured field types
 
 Four built-in types collect more than one value for a question. `STRUCTURED_FIELD_TYPES` lists
@@ -116,6 +129,67 @@ Each type validates, normalizes (trimmed, blanks dropped, notes in time order),
 samples for `coverage()`. Helpers: `listLimits`, `tableColumns`, `tableLimits`, `formatTimestamp`
 and `parseTimestamp`; types `TableColumn`, `MediaNote` and `Highlight`.
 
+### Calculated fields
+
+A `calculated` field shows a value worked out from other answers, such as a total, an average or a
+band, and the respondent can't change it. Its props are `{ formula, format?, decimals? }`, with
+`format` one of `"number"`, `"percent"` (`0.25` shows `25%`) or `"text"`.
+
+```ts
+const budget = defineForm({
+  id: "budget",
+  title: "Weekly budget",
+  blocks: [
+    f.shortText("hours", { label: "Hours worked" }),
+    f.shortText("rate", { label: "Hourly rate" }),
+    f.table("costs", { label: "Costs", columns: [{ key: "item", label: "Item" }, { key: "amount", label: "Amount" }] }),
+    f.calculated("income", { label: "Income", formula: "hours * rate", decimals: 2 }),
+    f.calculated("left", { label: "Left over", formula: "income - sum(costs.amount)", decimals: 2 }),
+    f.calculated("status", { label: "Status", formula: "left >= 0 ? 'On budget' : 'Over budget'", format: "text" }),
+  ],
+});
+```
+
+The formula language is small and is parsed and evaluated by this package, never run as code:
+
+| Part | Written as |
+| --- | --- |
+| Answers | Their key (`hours`); one column of a table as `key.column` (`costs.amount`) |
+| Values | Numbers (`12`, `0.5`) and text in quotes (`"High"`, `'High'`) |
+| Arithmetic | `+ - * /` (also `− × ÷`), unary minus, parentheses |
+| Comparisons | `== != < <= > >=` (also `= ≠ ≤ ≥`), true or false |
+| A choice | `test ? a : b` |
+| Functions | `sum`, `avg`, `min`, `max` of numbers, lists and table columns |
+
+An unanswered question is blank, and arithmetic with a blank is blank, so a total stays empty until
+its answers are in; dividing by zero is blank too. The functions skip blanks (`sum` of nothing is
+`0`). Text holding a number (`"12"`, `"1,200"`) counts as that number, and yes / no as 1 / 0.
+A list or table of more than `MAX_FORMULA_ITEMS` (10,000) items reads as blank. A formula is at
+most `MAX_FORMULA_LENGTH` characters and 64 levels of parentheses, calls, signs and `? :` deep.
+
+The engine works the values out from the answers on the path (an answer hidden by logic reads as
+blank), again whenever an answer it reads changes, and stores them with the answers, so `engine.answers()` and a
+checked submission hold them for later use. `setValue` on a calculated field does nothing, and
+`validateSubmission` works the values out itself, dropping any the client sent. A calculated field
+is never required. Logic may compare its value.
+
+`parseForm` checks each formula: it must parse, every key must be a question of the form, a table
+must be read by one of its columns, and a calculated field may read only calculated fields before
+it, so values never go round in a circle. A problem is an issue on `blocks[i].props.formula`, such
+as `The formula uses "wage", which is not the answer name of a question in this form.` or
+`Expected a number, an answer or "(", but the formula ends there. (at character 9)`.
+
+`parseFormula`, `evaluateFormula`, `formulaRefs` and `renameFormulaKey` work with formulas on their
+own; `formatCalculated` shows a value as the field does. Builders offer the type only when the host
+names it (`COMPUTED_FIELD_TYPES`).
+
+### Props for the host
+
+Props a field type doesn't use are kept and ignored: the engine, `parseForm` and
+`validateSubmission` treat them as data for the app. A host can mark where an answer goes after a
+submit, for example `props: { record_column: "nickname" }`, and read it from the definition when it
+stores the response. The builder offers such props as `outputs` (see its README).
+
 ## On the server
 
 ```ts

package/dist/destinations.cjs

@@ -62,6 +62,11 @@ async function timedFetch(deps, url, init, signal) {
   const timeout = AbortSignal.timeout(deps.timeoutMs ?? REQUEST_TIMEOUT_MS);
   const any = AbortSignal.any;
   const combined = signal ? any ? any([timeout, signal]) : signal.aborted ? signal : timeout : timeout;
+  try {
+    new Request(url, { method: init.method ?? "GET", headers: init.headers ?? {} });
+  } catch {
+    throw new DeliveryError("Invalid request (a header value or the URL is malformed)", { retryable: false });
+  }
   try {
     return await (deps.fetch ?? fetch)(url, { ...init, signal: combined });
   } catch (error) {
@@ -109,6 +114,39 @@ async function sha256Hex(text) {
   return Array.from(new Uint8Array(digest), (b) => b.toString(16).padStart(2, "0")).join("");
 }
 
+// src/calculated.ts
+var CALCULATED_TYPE = "calculated";
+var MAX_CALCULATED_DECIMALS = 10;
+function calculatedProps(field) {
+  const p = field.props ?? {};
+  const out = { formula: typeof p.formula === "string" ? p.formula : "" };
+  if (p.format === "number" || p.format === "percent" || p.format === "text") out.format = p.format;
+  if (typeof p.decimals === "number" && Number.isInteger(p.decimals) && p.decimals >= 0 && p.decimals <= MAX_CALCULATED_DECIMALS) {
+    out.decimals = p.decimals;
+  }
+  return out;
+}
+function formatCalculated(value, field) {
+  if (value === void 0 || value === null) return "";
+  const { format, decimals } = calculatedProps(field);
+  const fixed = (n) => decimals === void 0 ? String(Number(n.toFixed(6))) : n.toFixed(decimals);
+  if (typeof value === "number") return format === "percent" ? `${fixed(value * 100)}%` : fixed(value);
+  if (typeof value === "boolean") return value ? "Yes" : "No";
+  return typeof value === "string" ? value : "";
+}
+var numberOps = ["eq", "neq", "lt", "lte", "gt", "gte", "in", "answered", "empty"];
+var calculatedFieldType = {
+  type: CALCULATED_TYPE,
+  label: "Calculated",
+  category: "advanced",
+  value: { json: true },
+  operators: numberOps,
+  a11y: { semantics: "control" },
+  // The engine works the value out; any number, text or true / false it made is valid.
+  validate: (value) => typeof value === "number" || typeof value === "string" || typeof value === "boolean" ? null : "This value is worked out from other answers.",
+  summarize: (value, field) => formatCalculated(value, field)
+};
+
 // src/structured.ts
 var isObject = (v) => !!v && typeof v === "object" && !Array.isArray(v);
 function intProp(field, name, fallback, floor = 1) {
@@ -340,7 +378,7 @@ function intRange(field, min, maxDefault) {
   const max = typeof field.props?.max === "number" ? field.props.max : maxDefault;
   return { min, max };
 }
-var numberOps = ["eq", "neq", "lt", "lte", "gt", "gte", "in", "answered", "empty"];
+var numberOps2 = ["eq", "neq", "lt", "lte", "gt", "gte", "in", "answered", "empty"];
 var textOps = ["eq", "neq", "contains", "answered", "empty"];
 function maxLength(field, fallback) {
   return typeof field.props?.maxLength === "number" ? field.props.maxLength : fallback;
@@ -418,23 +456,30 @@ var builtins = [
     label: "Rating",
     category: "scale",
     value: { json: true },
-    operators: numberOps,
+    operators: numberOps2,
     a11y: { semantics: "group" },
     validate: (value, field) => {
       const { min, max } = intRange(field, 1, 5);
       return Number.isInteger(value) && value >= min && value <= max ? null : `Choose a rating from ${min} to ${max}.`;
     },
-    summarize: (value, field) => `${value}/${intRange(field, 1, 5).max}`
+    summarize: (value, field) => {
+      const { max } = intRange(field, 1, 5);
+      const end = scaleEndLabel(field, value, 1, max);
+      return end ? `${value}/${max} (${end})` : `${value}/${max}`;
+    }
   },
   {
     type: "nps",
     label: "Net Promoter Score",
     category: "scale",
     value: { json: true },
-    operators: numberOps,
+    operators: numberOps2,
     a11y: { semantics: "group" },
     validate: (value) => Number.isInteger(value) && value >= 0 && value <= 10 ? null : "Choose a score from 0 to 10.",
-    summarize: (value) => `${value}/10`
+    summarize: (value, field) => {
+      const end = scaleEndLabel(field, value, 0, 10);
+      return end ? `${value}/10 (${end})` : `${value}/10`;
+    }
   },
   {
     type: "single-choice",
@@ -468,9 +513,122 @@ var builtins = [
     a11y: { semantics: "group" },
     validate: (value) => typeof value === "boolean" ? null : "Choose yes or no.",
     summarize: (value) => value ? "Yes" : "No"
+  },
+  {
+    type: "dropdown",
+    label: "Dropdown",
+    category: "choice",
+    value: { json: true },
+    operators: ["eq", "neq", "in", "answered", "empty"],
+    a11y: { semantics: "control" },
+    validate: (value, field) => typeof value === "string" && choiceOptions(field).some((o) => o.value === value) ? null : "Choose one of the options.",
+    summarize: (value, field) => optionLabel(field, String(value))
+  },
+  {
+    type: "number",
+    label: "Number",
+    category: "text",
+    value: { json: true },
+    operators: numberOps2,
+    a11y: { semantics: "control", inputMode: "decimal" },
+    validate: (value, field) => {
+      if (typeof value !== "number" || !Number.isFinite(value)) return "Enter a number.";
+      const { min, max, step } = numberLimits(field);
+      if (min !== void 0 && max !== void 0 && (value < min || value > max)) {
+        return `Enter a number from ${min} to ${max}.`;
+      }
+      if (min !== void 0 && value < min) return `Enter ${min} or more.`;
+      if (max !== void 0 && value > max) return `Enter ${max} or less.`;
+      if (step !== void 0 && !onStep(value, min ?? 0, step)) {
+        return step === 1 && Number.isInteger(min ?? 0) ? "Enter a whole number." : `Enter a number in steps of ${step}.`;
+      }
+      return null;
+    },
+    summarize: (value) => String(value),
+    samples: (field) => {
+      const { min, max } = numberLimits(field);
+      return [min, max, 0, 1].filter((v) => v !== void 0);
+    }
+  },
+  {
+    type: "date",
+    label: "Date",
+    category: "date",
+    value: { json: true },
+    operators: ["eq", "neq", "answered", "empty"],
+    a11y: { semantics: "control" },
+    validate: (value, field) => {
+      if (typeof value !== "string" || !isIsoDate(value.trim())) return "Enter a date like 2026-10-22.";
+      const date = value.trim();
+      const { min, max } = dateLimits(field);
+      if (min && max && (date < min || date > max)) return `Choose a date from ${min} to ${max}.`;
+      if (min && date < min) return `Choose ${min} or later.`;
+      if (max && date > max) return `Choose ${max} or earlier.`;
+      return null;
+    },
+    normalize: (value) => typeof value === "string" ? value.trim() : value,
+    samples: (field) => {
+      const { min, max } = dateLimits(field);
+      return [min ?? max ?? "2000-01-01"];
+    }
+  },
+  {
+    type: "consent",
+    label: "Consent checkbox",
+    category: "choice",
+    value: { json: true },
+    operators: ["answered", "empty"],
+    a11y: { semantics: "group" },
+    // Unchecked is unanswered, so a required consent must be checked.
+    isEmpty: (value) => value === void 0 || value === null || value === false,
+    validate: (value) => value === true ? null : "Check the box to agree.",
+    summarize: () => "Agreed",
+    samples: () => [true]
   }
 ];
-for (const manifest of [...builtins, ...structuredFieldTypes]) registerFieldType(manifest);
+function scaleLabels(field) {
+  const out = {};
+  const low = field.props?.lowLabel;
+  const high = field.props?.highLabel;
+  if (typeof low === "string" && low.trim()) out.low = low.trim();
+  if (typeof high === "string" && high.trim()) out.high = high.trim();
+  return out;
+}
+function scaleEndLabel(field, value, min, max) {
+  const { low, high } = scaleLabels(field);
+  return value === min ? low : value === max ? high : void 0;
+}
+var finite = (v) => typeof v === "number" && Number.isFinite(v) ? v : void 0;
+function numberLimits(field) {
+  const out = {};
+  const min = finite(field.props?.min);
+  const max = finite(field.props?.max);
+  const step = finite(field.props?.step);
+  if (min !== void 0) out.min = min;
+  if (max !== void 0) out.max = max;
+  if (step !== void 0 && step > 0) out.step = step;
+  return out;
+}
+function onStep(value, base, step) {
+  const n = (value - base) / step;
+  return Math.abs(n - Math.round(n)) < 1e-9 * Math.max(1, Math.abs(n));
+}
+function isIsoDate(value) {
+  if (!/^\d{4}-\d{2}-\d{2}$/.test(value)) return false;
+  const [y, m, d] = value.split("-").map(Number);
+  if (y < 1 || m < 1 || m > 12 || d < 1) return false;
+  const days = [31, y % 4 === 0 && (y % 100 !== 0 || y % 400 === 0) ? 29 : 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31];
+  return d <= days[m - 1];
+}
+function dateLimits(field) {
+  const out = {};
+  const min = field.props?.min;
+  const max = field.props?.max;
+  if (typeof min === "string" && isIsoDate(min)) out.min = min;
+  if (typeof max === "string" && isIsoDate(max)) out.max = max;
+  return out;
+}
+for (const manifest of [...builtins, ...structuredFieldTypes, calculatedFieldType]) registerFieldType(manifest);
 
 // src/logic.ts
 function own(record, key) {
@@ -758,7 +916,7 @@ async function googleAccessToken(account, options = {}) {
   if (!clientEmail || !privateKey) throw new DeliveryError("The Google service account email or private key is not set");
   const scope = options.scope ?? SHEETS_SCOPE;
   const now = options.now?.() ?? Date.now();
-  const cacheKey = `${clientEmail} ${scope}`;
+  const cacheKey = `${clientEmail} ${scope} ${await sha256Hex(privateKey.replace(/\\n/g, "\n").trim())}`;
   const hit = cache.get(cacheKey);
   if (hit && hit.expiresAt - 6e4 > now) return hit.token;
   const iat = Math.floor(now / 1e3);
@@ -789,6 +947,7 @@ var SHEETS_API = "https://sheets.googleapis.com/v4/spreadsheets";
 var DEFAULT_SHEET_NAME = "Responses";
 var DEDUPE_WINDOW = 500;
 var HEADER_SCAN_ROWS = 100;
+var HEADER_WRITE_ATTEMPTS = 3;
 function mergeHeader(existing, keys, width = 0) {
   const header = existing.map((h) => h == null ? "" : String(h));
   while (header.length < width) header.push("");
@@ -884,35 +1043,52 @@ function sheetsDestination(options) {
     });
     const keys = [...new Set(rows.flatMap((r) => r.columns))];
     async function setUp(previous) {
-      const meta = await call(
-        "read",
-        `${base}?fields=${encodeURIComponent("sheets.properties(sheetId,title,gridProperties.columnCount)")}`
-      );
-      let sheet = meta.sheets?.map((s) => s.properties).find((p) => p?.title === sheetName);
+      const readTabs = async () => {
+        const meta = await call(
+          "read",
+          `${base}?fields=${encodeURIComponent("sheets.properties(sheetId,title,gridProperties.columnCount)")}`
+        );
+        return meta.sheets?.map((s) => s.properties).find((p) => p?.title === sheetName);
+      };
+      let sheet = await readTabs();
       if (!sheet) {
-        const added = await batchUpdate("add tab", [{ addSheet: { properties: { title: sheetName } } }]);
-        sheet = added.replies?.[0]?.addSheet?.properties ?? { sheetId: 0, title: sheetName };
-      }
-      const read = await call(
-        "read header",
-        `${range(`A1:ZZZ${HEADER_SCAN_ROWS}`)}?majorDimension=COLUMNS`
-      );
-      const used = read.values ?? [];
-      const existing = used.map((column) => column[0] ?? "");
-      const header = mergeHeader(existing, keys, used.length);
-      if (!header.includes("id")) {
-        if (used.length) header.push("id");
-        else header.unshift("id");
+        try {
+          const added = await batchUpdate("add tab", [{ addSheet: { properties: { title: sheetName } } }]);
+          sheet = added.replies?.[0]?.addSheet?.properties ?? { sheetId: 0, title: sheetName };
+        } catch (error) {
+          if (!(error instanceof DeliveryError) || error.status !== 400) throw error;
+          sheet = await readTabs();
+          if (!sheet) throw error;
+        }
       }
+      const readHeader = async () => {
+        const read = await call(
+          "read header",
+          `${range(`A1:ZZZ${HEADER_SCAN_ROWS}`)}?majorDimension=COLUMNS`
+        );
+        const used2 = read.values ?? [];
+        return { used: used2.length, existing: used2.map((column) => column[0] ?? "") };
+      };
       let columns = sheet.gridProperties?.columnCount ?? 26;
-      if (header.length > columns) {
-        await batchUpdate("add columns", [
-          { appendDimension: { sheetId: sheet.sheetId, dimension: "COLUMNS", length: header.length - columns } }
-        ]);
-        columns = header.length;
-      }
-      const changed = header.length !== existing.length || header.some((h, i) => h !== String(existing[i] ?? ""));
-      if (changed) {
+      let { used, existing } = await readHeader();
+      let header = [];
+      for (let attempt = 0; ; attempt++) {
+        header = mergeHeader(existing, keys, used);
+        if (!header.includes("id")) {
+          if (used) header.push("id");
+          else header.unshift("id");
+        }
+        const changed = header.length !== existing.length || header.some((h, i) => h !== String(existing[i] ?? ""));
+        if (!changed) break;
+        if (attempt >= HEADER_WRITE_ATTEMPTS) {
+          throw new DeliveryError("Google Sheets header kept changing while it was written", { retryable: true });
+        }
+        if (header.length > columns) {
+          await batchUpdate("add columns", [
+            { appendDimension: { sheetId: sheet.sheetId, dimension: "COLUMNS", length: header.length - columns } }
+          ]);
+          columns = header.length;
+        }
         await call("write header", `${range("A1")}?valueInputOption=RAW`, {
           method: "PUT",
           body: JSON.stringify({ values: [header] })
@@ -927,6 +1103,7 @@ function sheetsDestination(options) {
             }
           ]);
         }
+        ({ used, existing } = await readHeader());
       }
       return {
         spreadsheet_id: spreadsheetId,