@marktiderman/genesis-forms 0.3.1 → 0.4.1

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,77 @@ 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.
+
+Limits, so a large submission can't make the server slow:
+
+- A calculated field that reads a list or table of more than `MAX_FORMULA_ITEMS` (10,000) items
+  has no value: it is blank, never `0` or a partial total. The same goes for one that reads an
+  answer past `MAX_SETTLE_ITEMS` (50,000) items read by all of a form's formulas together (each
+  answer and column counted once, in form order; an answer over 10,000 items counts for none).
+  Nothing else reports this, so give a table a `maxRows` well under these if its total matters.
+- A formula is at most `MAX_FORMULA_LENGTH` characters and 64 levels of parentheses, calls, signs
+  and `? :` deep, and all of a form's formulas together at most `MAX_FORM_FORMULA_LENGTH` (20,000).
+- Lists are read once per answer, so treat answers as immutable: pass `setValue` a new array, never
+  one changed in place (the engine and the built-in renderers never change one).
+
+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

@@ -114,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) {
@@ -345,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;
@@ -423,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",
@@ -473,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) {