@marktiderman/genesis-forms 0.3.1 → 0.4.1

package/dist/index.cjs

@@ -30,6 +30,537 @@ function fingerprint(value) {
   return (4294967296 * (2097151 & h2) + (h1 >>> 0)).toString(16).padStart(14, "0");
 }
 
+// src/formula.ts
+var FORMULA_FUNCTIONS = ["sum", "avg", "min", "max"];
+var MAX_FORMULA_LENGTH = 2e3;
+var MAX_DEPTH = 64;
+var OP_ALIASES = { "\u2212": "-", "\xD7": "*", "\xF7": "/", "\u2260": "!=", "\u2264": "<=", "\u2265": ">=", "=": "==" };
+var TWO_CHAR = /* @__PURE__ */ new Set(["==", "!=", "<=", ">="]);
+var ONE_CHAR = /* @__PURE__ */ new Set(["+", "-", "*", "/", "<", ">", "(", ")", "?", ":", ",", ".", "=", "\u2212", "\xD7", "\xF7", "\u2260", "\u2264", "\u2265"]);
+var COMPARISONS = /* @__PURE__ */ new Set(["==", "!=", "<", "<=", ">", ">="]);
+var FormulaError = class extends Error {
+  constructor(message, at) {
+    super(message);
+    this.at = at;
+  }
+  at;
+};
+var isIdStart = (c) => c >= "a" && c <= "z" || c >= "A" && c <= "Z" || c === "_";
+var isIdPart = (c) => isIdStart(c) || c >= "0" && c <= "9";
+var isDigit = (c) => c >= "0" && c <= "9";
+function tokenize(source) {
+  const tokens = [];
+  let i = 0;
+  while (i < source.length) {
+    const c = source[i];
+    if (c === " " || c === "	" || c === "\n" || c === "\r") {
+      i++;
+      continue;
+    }
+    const at = i;
+    if (isDigit(c) || c === "." && isDigit(source[i + 1] ?? "")) {
+      while (isDigit(source[i] ?? "")) i++;
+      if (source[i] === "." && isDigit(source[i + 1] ?? "")) {
+        i++;
+        while (isDigit(source[i] ?? "")) i++;
+      }
+      if (isIdStart(source[i] ?? "")) throw new FormulaError("Write a number in digits only, like 1000000.", at);
+      const v = Number(source.slice(at, i));
+      if (!Number.isFinite(v)) throw new FormulaError("This number is too large.", at);
+      tokens.push({ t: "num", v, at });
+      continue;
+    }
+    if (isIdStart(c)) {
+      while (isIdPart(source[i] ?? "")) i++;
+      tokens.push({ t: "id", v: source.slice(at, i), at });
+      continue;
+    }
+    if (c === '"' || c === "'" || c === "\u201C") {
+      const close = c === "\u201C" ? "\u201D" : c;
+      const end = source.indexOf(close, i + 1);
+      if (end === -1) throw new FormulaError("This text has no closing quote.", at);
+      tokens.push({ t: "str", v: source.slice(i + 1, end), at });
+      i = end + 1;
+      continue;
+    }
+    const two = source.slice(i, i + 2);
+    if (TWO_CHAR.has(two)) {
+      tokens.push({ t: "op", v: two, at });
+      i += 2;
+      continue;
+    }
+    if (ONE_CHAR.has(c)) {
+      tokens.push({ t: "op", v: OP_ALIASES[c] ?? c, at });
+      i++;
+      continue;
+    }
+    throw new FormulaError(`"${c}" can't be used in a formula.`, at);
+  }
+  tokens.push({ t: "end", at: source.length });
+  return tokens;
+}
+function parseFormula(source) {
+  if (typeof source !== "string" || source.trim() === "") return { ok: false, message: "Write a formula.", at: 0 };
+  if (source.length > MAX_FORMULA_LENGTH) {
+    return { ok: false, message: `Keep the formula under ${MAX_FORMULA_LENGTH} characters.`, at: MAX_FORMULA_LENGTH };
+  }
+  let tokens;
+  try {
+    tokens = tokenize(source);
+  } catch (e) {
+    const err = e;
+    return { ok: false, message: err.message, at: err.at };
+  }
+  let pos = 0;
+  const refs = [];
+  const peek = () => tokens[pos];
+  const isOp = (v) => {
+    const tok = peek();
+    return tok.t === "op" && tok.v === v;
+  };
+  const expect = (v, message) => {
+    if (!isOp(v)) throw new FormulaError(message, peek().at);
+    pos++;
+  };
+  const describe = (tok) => tok.t === "end" ? "the formula ends there" : `found "${String(tok.v)}"`;
+  const guard = (depth) => {
+    if (depth > MAX_DEPTH) throw new FormulaError("The formula is nested too deeply.", peek().at);
+  };
+  const ternary = (depth) => {
+    guard(depth);
+    const test = comparison(depth);
+    if (!isOp("?")) return test;
+    pos++;
+    const then = ternary(depth + 1);
+    expect(":", "A `?` needs a `:` and the other value: `test ? a : b`.");
+    const otherwise = ternary(depth + 1);
+    return { kind: "if", test, then, else: otherwise };
+  };
+  const comparison = (depth) => {
+    const left = additive(depth);
+    const tok = peek();
+    if (tok.t !== "op" || !COMPARISONS.has(tok.v)) return left;
+    pos++;
+    const right = additive(depth);
+    const next = peek();
+    if (next.t === "op" && COMPARISONS.has(next.v)) {
+      throw new FormulaError("Compare two values at a time; combine comparisons with `? :`.", next.at);
+    }
+    return { kind: "binary", op: tok.v, left, right };
+  };
+  const additive = (depth) => {
+    let left = multiplicative(depth);
+    for (let tok = peek(); tok.t === "op" && (tok.v === "+" || tok.v === "-"); tok = peek()) {
+      pos++;
+      left = { kind: "binary", op: tok.v, left, right: multiplicative(depth) };
+    }
+    return left;
+  };
+  const multiplicative = (depth) => {
+    let left = unary(depth);
+    for (let tok = peek(); tok.t === "op" && (tok.v === "*" || tok.v === "/"); tok = peek()) {
+      pos++;
+      left = { kind: "binary", op: tok.v, left, right: unary(depth) };
+    }
+    return left;
+  };
+  const unary = (depth) => {
+    guard(depth);
+    if (isOp("-")) {
+      pos++;
+      return { kind: "unary", op: "-", arg: unary(depth + 1) };
+    }
+    if (isOp("+")) {
+      pos++;
+      return unary(depth + 1);
+    }
+    return primary(depth);
+  };
+  const primary = (depth) => {
+    const tok = peek();
+    if (tok.t === "num") {
+      pos++;
+      return { kind: "number", value: tok.v };
+    }
+    if (tok.t === "str") {
+      pos++;
+      return { kind: "text", value: tok.v };
+    }
+    if (tok.t === "op" && tok.v === "(") {
+      pos++;
+      const inner = ternary(depth + 1);
+      expect(")", "A `(` has no matching `)`.");
+      return inner;
+    }
+    if (tok.t === "id") {
+      pos++;
+      if (isOp("(")) {
+        if (!FORMULA_FUNCTIONS.includes(tok.v)) {
+          throw new FormulaError(`There is no function "${tok.v}"; use ${FORMULA_FUNCTIONS.join(", ")}.`, tok.at);
+        }
+        pos++;
+        const args = [];
+        if (!isOp(")")) {
+          args.push(ternary(depth + 1));
+          while (isOp(",")) {
+            pos++;
+            args.push(ternary(depth + 1));
+          }
+        }
+        expect(")", `"${tok.v}(" has no matching ")".`);
+        if (!args.length) throw new FormulaError(`${tok.v}() needs something to work on.`, tok.at);
+        return { kind: "call", fn: tok.v, args };
+      }
+      if (isOp(".")) {
+        pos++;
+        const column = peek();
+        if (column.t !== "id") throw new FormulaError(`Name a column after "${tok.v}.".`, column.at);
+        pos++;
+        refs.push({ key: tok.v, column: column.v });
+        return { kind: "ref", key: tok.v, column: column.v, at: tok.at };
+      }
+      refs.push({ key: tok.v });
+      return { kind: "ref", key: tok.v, at: tok.at };
+    }
+    throw new FormulaError(`Expected a number, an answer or "(", but ${describe(tok)}.`, tok.at);
+  };
+  try {
+    const ast = ternary(0);
+    const rest = peek();
+    if (rest.t !== "end") throw new FormulaError(`Expected an operator such as + or *, but ${describe(rest)}.`, rest.at);
+    return { ok: true, ast, refs };
+  } catch (e) {
+    if (e instanceof FormulaError) return { ok: false, message: e.message, at: e.at };
+    return { ok: false, message: "The formula is nested too deeply.", at: 0 };
+  }
+}
+function formulaRefs(source) {
+  const parsed = parseFormula(source);
+  if (!parsed.ok) return [];
+  const seen = /* @__PURE__ */ new Set();
+  return parsed.refs.filter((r) => {
+    const id = `${r.key}\0${r.column ?? ""}`;
+    if (seen.has(id)) return false;
+    seen.add(id);
+    return true;
+  });
+}
+function renameFormulaKey(source, from, to) {
+  let tokens;
+  try {
+    tokens = tokenize(source);
+  } catch {
+    return source;
+  }
+  let out = "";
+  let last = 0;
+  tokens.forEach((tok, i) => {
+    if (tok.t !== "id" || tok.v !== from) return;
+    const prev = tokens[i - 1];
+    const next = tokens[i + 1];
+    if (prev?.t === "op" && prev.v === ".") return;
+    if (next?.t === "op" && next.v === "(") return;
+    out += source.slice(last, tok.at) + to;
+    last = tok.at + from.length;
+  });
+  return out + source.slice(last);
+}
+var NUMERIC = /^[+-]?(\d+(\.\d*)?|\.\d+)([eE][+-]?\d+)?$/;
+function formulaNumber(v) {
+  if (typeof v === "number") return Number.isFinite(v) ? v : null;
+  if (typeof v === "boolean") return v ? 1 : 0;
+  if (typeof v === "string") {
+    const t = v.trim().replace(/,/g, "");
+    return t.length <= 64 && NUMERIC.test(t) ? finite(Number(t)) : null;
+  }
+  return null;
+}
+var finite = (n) => Number.isFinite(n) ? n : null;
+var scalar = (v) => Array.isArray(v) ? null : v;
+function truthy(v) {
+  if (v === null) return false;
+  if (typeof v === "boolean") return v;
+  if (typeof v === "number") return v !== 0;
+  if (typeof v === "string") return v.trim() !== "";
+  return v.length > 0;
+}
+function numbersIn(values, out = []) {
+  for (const v of values) {
+    if (Array.isArray(v)) numbersIn(v, out);
+    else {
+      const n = formulaNumber(v);
+      if (n !== null) out.push(n);
+    }
+  }
+  return out;
+}
+var listTotals = /* @__PURE__ */ new WeakMap();
+var ownLists = /* @__PURE__ */ new WeakSet();
+function ownFormulaList(list) {
+  Object.freeze(list);
+  ownLists.add(list);
+  return list;
+}
+function totalsOf(list) {
+  const own2 = ownLists.has(list);
+  let t = own2 ? listTotals.get(list) : void 0;
+  if (t) return t;
+  const nums = numbersIn(list);
+  t = { sum: 0, count: nums.length, min: Infinity, max: -Infinity };
+  for (const n of nums) {
+    t.sum += n;
+    if (n < t.min) t.min = n;
+    if (n > t.max) t.max = n;
+  }
+  if (own2) listTotals.set(list, t);
+  return t;
+}
+function compare(op, a, b) {
+  const blank2 = (v) => v === null || Array.isArray(v) || typeof v === "string" && v.trim() === "";
+  if (blank2(a) || blank2(b)) return op === "!=";
+  const x = formulaNumber(a);
+  const y = formulaNumber(b);
+  if (x !== null && y !== null) {
+    if (op === "==") return x === y;
+    if (op === "!=") return x !== y;
+    if (op === "<") return x < y;
+    if (op === "<=") return x <= y;
+    if (op === ">") return x > y;
+    return x >= y;
+  }
+  if (op === "==") return String(a) === String(b);
+  if (op === "!=") return String(a) !== String(b);
+  return false;
+}
+function evaluateFormula(ast, read) {
+  const run = (node) => {
+    switch (node.kind) {
+      case "number":
+      case "text":
+        return node.value;
+      case "ref":
+        return read(node);
+      case "unary": {
+        const n = formulaNumber(scalar(run(node.arg)));
+        return n === null ? null : -n;
+      }
+      case "if":
+        return truthy(run(node.test)) ? run(node.then) : run(node.else);
+      case "call": {
+        let total = 0;
+        let count = 0;
+        let min = Infinity;
+        let max = -Infinity;
+        for (const arg of node.args) {
+          const v = run(arg);
+          if (Array.isArray(v)) {
+            const t = totalsOf(v);
+            total += t.sum;
+            count += t.count;
+            if (t.min < min) min = t.min;
+            if (t.max > max) max = t.max;
+            continue;
+          }
+          const n = formulaNumber(v);
+          if (n === null) continue;
+          total += n;
+          count++;
+          if (n < min) min = n;
+          if (n > max) max = n;
+        }
+        if (node.fn === "sum") return finite(total);
+        if (!count) return null;
+        if (node.fn === "avg") return finite(total / count);
+        return node.fn === "min" ? min : max;
+      }
+      case "binary": {
+        const a = run(node.left);
+        const b = run(node.right);
+        if (node.op === "+" || node.op === "-" || node.op === "*" || node.op === "/") {
+          const x = formulaNumber(scalar(a));
+          const y = formulaNumber(scalar(b));
+          if (x === null || y === null) return null;
+          if (node.op === "+") return finite(x + y);
+          if (node.op === "-") return finite(x - y);
+          if (node.op === "*") return finite(x * y);
+          return y === 0 ? null : finite(x / y);
+        }
+        return compare(node.op, a, b);
+      }
+    }
+  };
+  try {
+    return run(ast);
+  } catch {
+    return null;
+  }
+}
+
+// src/calculated.ts
+var CALCULATED_TYPE = "calculated";
+var COMPUTED_FIELD_TYPES = [CALCULATED_TYPE];
+var MAX_FORM_FORMULA_LENGTH = 2e4;
+var MAX_CALCULATED_DECIMALS = 10;
+function calculatedProps(field2) {
+  const p = field2.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;
+}
+var isCalculated = (field2) => field2?.type === CALCULATED_TYPE;
+var round = (n, decimals) => {
+  if (decimals === void 0) return n;
+  const r = Number(n.toFixed(decimals));
+  return Object.is(r, -0) ? 0 : r;
+};
+function calculatedValue(result, field2) {
+  const { format, decimals } = calculatedProps(field2);
+  if (result === null || Array.isArray(result)) return void 0;
+  if (format === "number" || format === "percent") {
+    const n = formulaNumber(result);
+    return n === null ? void 0 : round(n, decimals);
+  }
+  if (format === "text") {
+    if (typeof result === "number") return decimals === void 0 ? String(result) : result.toFixed(decimals);
+    return typeof result === "boolean" ? result ? "Yes" : "No" : result;
+  }
+  return typeof result === "number" ? round(result, decimals) : result;
+}
+function formatCalculated(value, field2) {
+  if (value === void 0 || value === null) return "";
+  const { format, decimals } = calculatedProps(field2);
+  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 MAX_FORMULA_ITEMS = 1e4;
+var MAX_SETTLE_ITEMS = 5e4;
+var extract = (value, column) => column !== void 0 ? value.flatMap((row) => {
+  if (!row || typeof row !== "object" || Array.isArray(row)) return [];
+  const cell = row[column];
+  return typeof cell === "string" || typeof cell === "number" ? [cell] : [];
+}) : value.flatMap((v) => typeof v === "string" || typeof v === "number" || typeof v === "boolean" ? [v] : []);
+var extracted = /* @__PURE__ */ new WeakMap();
+function cachedList(value, column) {
+  let byColumn = extracted.get(value);
+  if (!byColumn) extracted.set(value, byColumn = /* @__PURE__ */ new Map());
+  const key = column ?? "";
+  let list = byColumn.get(key);
+  if (!list) byColumn.set(key, list = ownFormulaList(extract(value, column)));
+  return list;
+}
+function readAnswer(value, column) {
+  if (Array.isArray(value)) return cachedList(value, column);
+  return column !== void 0 ? null : formulaInput(value);
+}
+function formulaInput(value, column) {
+  if (value === void 0 || value === null) return null;
+  if (Array.isArray(value) && value.length > MAX_FORMULA_ITEMS) return null;
+  if (column !== void 0) {
+    if (!Array.isArray(value)) return null;
+    return extract(value, column);
+  }
+  if (Array.isArray(value)) return extract(value, void 0);
+  return typeof value === "object" ? null : value;
+}
+function refNodes(node, out = []) {
+  if (node.kind === "ref") out.push(node);
+  else if (node.kind === "unary") refNodes(node.arg, out);
+  else if (node.kind === "binary") refNodes(node.left, out), refNodes(node.right, out);
+  else if (node.kind === "if") refNodes(node.test, out), refNodes(node.then, out), refNodes(node.else, out);
+  else if (node.kind === "call") for (const a of node.args) refNodes(a, out);
+  return out;
+}
+var UNREAD = /* @__PURE__ */ Symbol("unread");
+var OVER = /* @__PURE__ */ Symbol("over");
+function calculator(definition) {
+  const compiled = [];
+  const idByKey = /* @__PURE__ */ new Map();
+  for (const block of definition.blocks) {
+    if (block.kind !== "field") continue;
+    idByKey.set(block.key, block.id);
+  }
+  for (const block of definition.blocks) {
+    if (block.kind !== "field" || !isCalculated(block)) continue;
+    const parsed = parseFormula(calculatedProps(block).formula);
+    const reads = [];
+    const slots = /* @__PURE__ */ new Map();
+    const byKey = /* @__PURE__ */ new Map();
+    for (const ref of parsed.ok ? refNodes(parsed.ast) : []) {
+      const id = idByKey.get(ref.key);
+      const key = `${id ?? ""}\0${ref.column ?? ""}`;
+      let slot = byKey.get(key);
+      if (slot === void 0) {
+        slot = reads.push({ id, column: ref.column, key }) - 1;
+        byKey.set(key, slot);
+      }
+      slots.set(ref, slot);
+    }
+    compiled.push({ field: block, ast: parsed.ok ? parsed.ast : null, reads, slots, last: null });
+  }
+  const withCalculated = (values, path) => {
+    if (!compiled.length) return values;
+    const visible = new Set(path);
+    let next = values;
+    let budget = MAX_SETTLE_ITEMS;
+    const within = /* @__PURE__ */ new Map();
+    const input = ({ id, key }) => {
+      if (id === void 0 || !visible.has(id) || !Object.prototype.hasOwnProperty.call(next, id)) return UNREAD;
+      const value = next[id];
+      if (!Array.isArray(value)) return value;
+      let ok = within.get(key);
+      if (ok === void 0) {
+        ok = value.length <= MAX_FORMULA_ITEMS && value.length <= budget;
+        if (ok) budget -= value.length;
+        within.set(key, ok);
+      }
+      return ok ? value : OVER;
+    };
+    for (const entry of compiled) {
+      const { field: field2, ast } = entry;
+      const inputs = entry.reads.map(input);
+      let value;
+      if (entry.last && entry.last.inputs.length === inputs.length && entry.last.inputs.every((v, i) => v === inputs[i])) {
+        value = entry.last.value;
+      } else {
+        const resolved = new Array(inputs.length);
+        const read = (ref) => {
+          const slot = entry.slots.get(ref);
+          if (slot === void 0) return null;
+          let v = resolved[slot];
+          if (v === void 0) {
+            const raw = inputs[slot];
+            v = resolved[slot] = raw === UNREAD ? null : readAnswer(raw, entry.reads[slot].column);
+          }
+          return v;
+        };
+        value = ast && !inputs.includes(OVER) ? calculatedValue(evaluateFormula(ast, read), field2) : void 0;
+        entry.last = { inputs, value };
+      }
+      const current = Object.prototype.hasOwnProperty.call(next, field2.id) ? next[field2.id] : void 0;
+      if (current !== value) next = { ...next, [field2.id]: value };
+    }
+    return next;
+  };
+  return { active: compiled.length > 0, withCalculated };
+}
+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, field2) => formatCalculated(value, field2)
+};
+
 // src/events.ts
 function isPlainObject(value) {
   if (!value || typeof value !== "object" || Array.isArray(value)) return false;
@@ -324,7 +855,7 @@ function intRange(field2, min, maxDefault) {
   const max = typeof field2.props?.max === "number" ? field2.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(field2, fallback) {
   return typeof field2.props?.maxLength === "number" ? field2.props.maxLength : fallback;
@@ -402,23 +933,30 @@ var builtins = [
     label: "Rating",
     category: "scale",
     value: { json: true },
-    operators: numberOps,
+    operators: numberOps2,
     a11y: { semantics: "group" },
     validate: (value, field2) => {
       const { min, max } = intRange(field2, 1, 5);
       return Number.isInteger(value) && value >= min && value <= max ? null : `Choose a rating from ${min} to ${max}.`;
     },
-    summarize: (value, field2) => `${value}/${intRange(field2, 1, 5).max}`
+    summarize: (value, field2) => {
+      const { max } = intRange(field2, 1, 5);
+      const end = scaleEndLabel(field2, 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, field2) => {
+      const end = scaleEndLabel(field2, value, 0, 10);
+      return end ? `${value}/10 (${end})` : `${value}/10`;
+    }
   },
   {
     type: "single-choice",
@@ -452,9 +990,125 @@ 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, field2) => typeof value === "string" && choiceOptions(field2).some((o) => o.value === value) ? null : "Choose one of the options.",
+    summarize: (value, field2) => optionLabel(field2, String(value))
+  },
+  {
+    type: "number",
+    label: "Number",
+    category: "text",
+    value: { json: true },
+    operators: numberOps2,
+    a11y: { semantics: "control", inputMode: "decimal" },
+    validate: (value, field2) => {
+      if (typeof value !== "number" || !Number.isFinite(value)) return "Enter a number.";
+      const { min, max, step } = numberLimits(field2);
+      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: (field2) => {
+      const { min, max } = numberLimits(field2);
+      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, field2) => {
+      if (typeof value !== "string" || !isIsoDate(value.trim())) return "Enter a date like 2026-10-22.";
+      const date = value.trim();
+      const { min, max } = dateLimits(field2);
+      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: (field2) => {
+      const { min, max } = dateLimits(field2);
+      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(field2) {
+  const out = {};
+  const low = field2.props?.lowLabel;
+  const high = field2.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 ratingDisplay(field2) {
+  return field2.props?.display === "stars" ? "stars" : "numbers";
+}
+function scaleEndLabel(field2, value, min, max) {
+  const { low, high } = scaleLabels(field2);
+  return value === min ? low : value === max ? high : void 0;
+}
+var finite2 = (v) => typeof v === "number" && Number.isFinite(v) ? v : void 0;
+function numberLimits(field2) {
+  const out = {};
+  const min = finite2(field2.props?.min);
+  const max = finite2(field2.props?.max);
+  const step = finite2(field2.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(field2) {
+  const out = {};
+  const min = field2.props?.min;
+  const max = field2.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) {
@@ -626,8 +1280,15 @@ var LITERAL_TYPE = {
   "single-choice": "string",
   "multi-choice": "string",
   "yes-no": "boolean",
-  list: "string"
+  list: "string",
+  dropdown: "string",
+  number: "number",
+  date: "string",
+  consent: "boolean",
+  // A calculated field holds a number unless its format says text; see `literalType`.
+  calculated: "number"
 };
+var CHOICE_TYPES = /* @__PURE__ */ new Set(["single-choice", "multi-choice", "dropdown"]);
 var ORDERING = /* @__PURE__ */ new Set(["lt", "lte", "gt", "gte"]);
 var OPERATORS = /* @__PURE__ */ new Set([
   "eq",
@@ -707,8 +1368,45 @@ function parseForm(input) {
     } else if (type === "text-highlights") {
       optionalText(props2.text, `${path}.text`);
       optionalInt(props2.maxHighlights, `${path}.maxHighlights`, 1);
+    } else if (type === CALCULATED_TYPE) {
+      if (props2.format !== void 0 && props2.format !== "number" && props2.format !== "percent" && props2.format !== "text") {
+        issue(`${path}.format`, "Must be number, percent or text.");
+      }
+      if (props2.decimals !== void 0 && !(isInt(props2.decimals) && props2.decimals >= 0 && props2.decimals <= MAX_CALCULATED_DECIMALS)) {
+        issue(`${path}.decimals`, `Must be a whole number from 0 to ${MAX_CALCULATED_DECIMALS}.`);
+      }
     }
   };
+  const isFiniteNumber = (v) => typeof v === "number" && Number.isFinite(v);
+  const fieldProps = (type, props2, path) => {
+    if (type === "rating" || type === "nps") {
+      optionalText(props2.lowLabel, `${path}.lowLabel`);
+      optionalText(props2.highLabel, `${path}.highLabel`);
+    }
+    if (type === "rating" && props2.display !== void 0 && props2.display !== "numbers" && props2.display !== "stars") {
+      issue(`${path}.display`, "Must be numbers or stars.");
+    }
+    if (type === "number") {
+      for (const k of ["min", "max", "step"]) {
+        if (props2[k] !== void 0 && !isFiniteNumber(props2[k])) issue(`${path}.${k}`, "Must be a number.");
+      }
+      if (isFiniteNumber(props2.step) && props2.step <= 0) issue(`${path}.step`, "Must be above 0.");
+      if (isFiniteNumber(props2.min) && isFiniteNumber(props2.max) && props2.min > props2.max) {
+        issue(`${path}.min`, "Can't be more than the largest number.");
+      }
+    }
+    if (type === "date") {
+      for (const k of ["min", "max"]) {
+        if (props2[k] !== void 0 && !(typeof props2[k] === "string" && isIsoDate(props2[k]))) {
+          issue(`${path}.${k}`, "Must be a date like 2026-10-22.");
+        }
+      }
+      if (typeof props2.min === "string" && typeof props2.max === "string" && isIsoDate(props2.min) && isIsoDate(props2.max) && props2.min > props2.max) {
+        issue(`${path}.min`, "Can't be after the latest date.");
+      }
+    }
+    if (type === "consent") optionalText(props2.text, `${path}.text`);
+  };
   if (!isObject2(input)) {
     issue("", "A form definition must be an object.");
     return fail();
@@ -742,7 +1440,9 @@ function parseForm(input) {
   const keys = /* @__PURE__ */ new Map();
   const fieldTypes = /* @__PURE__ */ new Map();
   const order = /* @__PURE__ */ new Map();
+  const tableColumnKeys = /* @__PURE__ */ new Map();
   const choices = /* @__PURE__ */ new Map();
+  const calculatedLiteral = /* @__PURE__ */ new Map();
   input.blocks.forEach((block, i) => {
     const path = `blocks[${i}]`;
     if (!isObject2(block) || typeof block.id !== "string" || !block.id) {
@@ -792,12 +1492,24 @@ function parseForm(input) {
       }
       if (typeof block.type === "string" && (block.props === void 0 || isObject2(block.props))) {
         structuredProps(block.type, block.props ?? {}, `${path}.props`);
+        fieldProps(block.type, block.props ?? {}, `${path}.props`);
       }
       if (validKey) {
         if (keys.has(block.key)) issue(`${path}.key`, `Duplicate key "${String(block.key)}".`);
         keys.set(block.key, block.id);
       }
       fieldTypes.set(block.id, typeof block.type === "string" ? block.type : "");
+      if (block.type === CALCULATED_TYPE) {
+        const format = isObject2(block.props) ? block.props.format : void 0;
+        if (format === "text") calculatedLiteral.set(block.id, "string");
+        else if (format !== "number" && format !== "percent") calculatedLiteral.set(block.id, void 0);
+      }
+      if (block.type === "table" && isObject2(block.props) && Array.isArray(block.props.columns)) {
+        tableColumnKeys.set(
+          block.id,
+          new Set(block.props.columns.flatMap((c) => isObject2(c) && typeof c.key === "string" ? [c.key] : []))
+        );
+      }
     } else if (block.kind === "content") {
       if (block.type !== "heading" && block.type !== "text") issue(`${path}.type`, "Must be heading or text.");
       text(block.text, `${path}.text`);
@@ -807,6 +1519,44 @@ function parseForm(input) {
       issue(`${path}.kind`, "Unknown block kind.");
     }
   });
+  let formulaChars = 0;
+  input.blocks.forEach((block, i) => {
+    if (!isObject2(block) || block.kind !== "field" || block.type !== CALCULATED_TYPE) return;
+    const path = `blocks[${i}].props.formula`;
+    const source = isObject2(block.props) && typeof block.props.formula === "string" ? block.props.formula : "";
+    formulaChars += source.length;
+    if (formulaChars > MAX_FORM_FORMULA_LENGTH && formulaChars - source.length <= MAX_FORM_FORMULA_LENGTH) {
+      issue(path, `The form's formulas together are over ${MAX_FORM_FORMULA_LENGTH} characters; shorten some, or work part out once in an earlier calculated field.`);
+    }
+    if (block.required === true) {
+      warnings.push({ path: `blocks[${i}].required`, message: "A calculated field is worked out, not answered, so it is never required." });
+    }
+    const formula = isObject2(block.props) ? block.props.formula : void 0;
+    if (typeof formula !== "string" || !formula.trim()) return issue(path, "A calculated field needs a formula.");
+    const parsed = parseFormula(formula);
+    if (!parsed.ok) return issue(path, `${parsed.message} (at character ${parsed.at + 1})`);
+    const reported = /* @__PURE__ */ new Set();
+    for (const ref of parsed.refs) {
+      const name2 = ref.column === void 0 ? ref.key : `${ref.key}.${ref.column}`;
+      if (reported.has(name2)) continue;
+      reported.add(name2);
+      const target = keys.get(ref.key);
+      const targetType = target === void 0 ? void 0 : fieldTypes.get(target);
+      const at = target === void 0 ? void 0 : order.get(target);
+      if (target === void 0 || targetType === void 0) issue(path, `The formula uses "${ref.key}", which is not the answer name of a question in this form.`);
+      else if (target === block.id) issue(path, "The formula uses this field's own value.");
+      else if (targetType === CALCULATED_TYPE && (at ?? 0) > i) {
+        issue(path, `The formula uses "${ref.key}", a calculated field that comes after this one; move it earlier.`);
+      } else if (targetType === "table") {
+        const columns = tableColumnKeys.get(target);
+        if (ref.column === void 0) issue(path, `"${ref.key}" is a table: name one of its columns, like ${ref.key}.${[...columns ?? []][0] ?? "column"}.`);
+        else if (columns && !columns.has(ref.column)) issue(path, `The table "${ref.key}" has no column "${ref.column}".`);
+      } else if (ref.column !== void 0) issue(path, `"${ref.key}" is not a table, so it has no column "${ref.column}".`);
+      else if (targetType === "media-notes" || targetType === "text-highlights") {
+        warnings.push({ path, message: `"${ref.key}" holds notes, not numbers; the formula reads it as blank.` });
+      }
+    }
+  });
   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.");
@@ -890,8 +1640,8 @@ function parseForm(input) {
     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);
+      type = calculatedLiteral.has(left.field) ? calculatedLiteral.get(left.field) : LITERAL_TYPE[fieldType];
+      if (CHOICE_TYPES.has(fieldType)) 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);
@@ -1037,11 +1787,33 @@ var f = {
   longText: (key, o) => field("long-text", key, o, o.maxLength ? { maxLength: o.maxLength } : void 0),
   email: (key, o) => field("email", key, o),
   phone: (key, o) => field("phone", key, o),
-  rating: (key, o) => field("rating", key, o, { max: o.max ?? 5 }),
-  nps: (key, o) => field("nps", key, o),
+  /**
+   * A 1-to-`max` scale. `lowLabel` and `highLabel` are optional words under
+   * its ends ("Poor", "Great"); `display: "stars"` draws stars instead of numbers.
+   */
+  rating: (key, o) => field(
+    "rating",
+    key,
+    o,
+    props({ max: o.max ?? 5, lowLabel: o.lowLabel || void 0, highLabel: o.highLabel || void 0, display: o.display })
+  ),
+  /** A 0-to-10 Net Promoter Score. The end labels default to "Not likely" and "Very likely" in the renderer. */
+  nps: (key, o) => field("nps", key, o, props({ lowLabel: o.lowLabel || void 0, highLabel: o.highLabel || void 0 })),
   singleChoice: (key, o) => field("single-choice", key, o, choiceProps(o.options)),
   multiChoice: (key, o) => field("multi-choice", key, o, choiceProps(o.options)),
   yesNo: (key, o) => field("yes-no", key, o),
+  /** One option from a compact menu: for a long list (a country, a class), where single choice would be a wall of buttons. */
+  dropdown: (key, o) => field("dropdown", key, o, choiceProps(o.options)),
+  /** A number, optionally between `min` and `max` and on a `step` (from `min`, else 0): `step: 1` for whole numbers. */
+  number: (key, o) => field("number", key, o, props({ min: o.min, max: o.max, step: o.step })),
+  /** A calendar day, stored as `YYYY-MM-DD`, optionally between `min` and `max` (also `YYYY-MM-DD`). */
+  date: (key, o) => field("date", key, o, props({ min: o.min, max: o.max })),
+  /**
+   * A single checkbox to agree to something. `text` is the checkbox's own
+   * words ("I agree to the terms"); the renderer defaults to "I agree".
+   * Checked stores `true`; unchecked is unanswered, so `required` means it must be checked.
+   */
+  consent: (key, o) => field("consent", key, o, props({ text: o.text || void 0 })),
   /** Several short answers, one per line: goals, action items, three things that went well. */
   list: (key, o) => field(
     "list",
@@ -1049,6 +1821,12 @@ var f = {
     o,
     props({ min: o.min, max: o.max, itemMaxLength: o.itemMaxLength, placeholder: o.itemPlaceholder })
   ),
+  /**
+   * A value worked out from other answers and shown read-only, such as a
+   * total or a score: `formula` names answers by key (`hours * rate`,
+   * `sum(plan.cost)`). Stored with the answers; never required.
+   */
+  calculated: (key, o) => field("calculated", key, o, props({ formula: o.formula, format: o.format, decimals: o.decimals })),
   /**
    * A small table each answer fills row by row, one answer per column: an
    * action plan (What / Who / By when), pros and cons.
@@ -1108,9 +1886,9 @@ function effects(fromKey, condition) {
     })
   };
 }
-var compare = (key, op, value) => (r) => value === void 0 ? { op, left: { field: r(key) } } : { op, left: { field: r(key) }, right: { value } };
+var compare2 = (key, op, value) => (r) => value === void 0 ? { op, left: { field: r(key) } } : { op, left: { field: r(key) }, right: { value } };
 function when(key) {
-  const on = (op, value) => effects(key, compare(key, op, value));
+  const on = (op, value) => effects(key, compare2(key, op, value));
   return {
     is: (value) => on("eq", value),
     isNot: (value) => on("neq", value),
@@ -1238,7 +2016,7 @@ function runCustom(validator, value) {
 }
 function validateField(field2, value, options = {}) {
   if (isEmptyValue(value, field2)) {
-    return field2.required && options.requireAnswers !== false ? REQUIRED_MESSAGE : null;
+    return field2.required && field2.type !== CALCULATED_TYPE && options.requireAnswers !== false ? REQUIRED_MESSAGE : null;
   }
   const manifest = getFieldType(field2.type);
   if (!manifest) return `Unknown field type "${field2.type}".`;
@@ -1269,9 +2047,21 @@ function build(definition, options, replaying = false) {
     if (!declared.has(name)) initialHidden[name] = value;
   }
   Object.assign(initialHidden, coerceHidden(definition, options.hidden).values);
-  const first = computePath(definition, scopeOf({}, initialHidden));
+  const calc = calculator(definition);
+  const settle = (values, hidden) => {
+    let { path } = computePath(definition, scopeOf(values, hidden));
+    if (!calc.active) return { values, path };
+    for (let round2 = 0; round2 < 4; round2++) {
+      const next = calc.withCalculated(values, path);
+      if (next === values) break;
+      values = next;
+      path = computePath(definition, scopeOf(values, hidden)).path;
+    }
+    return { values, path };
+  };
+  const first = settle({}, initialHidden);
   let state = {
-    values: {},
+    values: first.values,
     hidden: initialHidden,
     path: first.path,
     current: first.path[0] ?? null,
@@ -1306,12 +2096,25 @@ function build(definition, options, replaying = false) {
     }
     return errors;
   };
+  let unsettled = false;
+  const settleNow = () => {
+    if (!unsettled) return;
+    unsettled = false;
+    const { values, path } = settle(state.values, state.hidden);
+    state = { ...state, values, path };
+  };
   const answer = (id, value, event) => {
-    if (state.status === "completed" || own(state.values, id) === value) return;
-    const values = { ...state.values, [id]: value };
-    const { path } = computePath(definition, scopeOf(values, state.hidden));
+    if (state.status === "completed" || own(state.values, id) === value || isCalculated(fields.get(id))) return;
     const errors = { ...state.errors };
     delete errors[id];
+    if (batch) {
+      state.values = { ...state.values, [id]: value };
+      state.errors = errors;
+      log(event);
+      unsettled = true;
+      return;
+    }
+    const { values, path } = settle({ ...state.values, [id]: value }, state.hidden);
     emit({ ...state, values, path, errors, events: log(event) });
   };
   const engine = {
@@ -1383,10 +2186,14 @@ function build(definition, options, replaying = false) {
     }
   };
   if (options.initialValues) {
+    const wasBatch = batch;
+    batch = true;
     for (const [id, value] of Object.entries(options.initialValues)) {
       if (!fields.has(id) || value === void 0) continue;
       answer(id, value, stamp({ type: "answer", field: id, value, source: "prefill" }));
     }
+    settleNow();
+    batch = wasBatch;
   }
   const apply = (event) => {
     if (event.type === "answer") {
@@ -1394,11 +2201,19 @@ function build(definition, options, replaying = false) {
         const { at: _at, ...logged } = event;
         answer(event.field, event.value, logged);
       }
-    } else if (event.type === "next") engine.next();
-    else if (event.type === "back") engine.back();
-    else if (event.type === "submit") engine.submit();
+    } else if (event.type === "next") {
+      settleNow();
+      engine.next();
+    } else if (event.type === "back") {
+      settleNow();
+      engine.back();
+    } else if (event.type === "submit") {
+      settleNow();
+      engine.submit();
+    }
   };
   const finish = () => {
+    settleNow();
     batch = false;
     state = { ...state, events: [...state.events] };
   };
@@ -1547,42 +2362,64 @@ function describeCondition(condition, def, fields = fieldMap(def)) {
   return `${left} ${op} ${right}`;
 }
 
+exports.CALCULATED_TYPE = CALCULATED_TYPE;
+exports.COMPUTED_FIELD_TYPES = COMPUTED_FIELD_TYPES;
+exports.FORMULA_FUNCTIONS = FORMULA_FUNCTIONS;
 exports.HIGHLIGHT_NOTE_MESSAGE = HIGHLIGHT_NOTE_MESSAGE;
+exports.MAX_CALCULATED_DECIMALS = MAX_CALCULATED_DECIMALS;
+exports.MAX_FORMULA_ITEMS = MAX_FORMULA_ITEMS;
+exports.MAX_FORMULA_LENGTH = MAX_FORMULA_LENGTH;
+exports.MAX_FORM_FORMULA_LENGTH = MAX_FORM_FORMULA_LENGTH;
 exports.MAX_HIDDEN_STRING_LENGTH = MAX_HIDDEN_STRING_LENGTH;
 exports.MAX_HIGHLIGHT_NOTE_LENGTH = MAX_HIGHLIGHT_NOTE_LENGTH;
 exports.MAX_HIGHLIGHT_QUOTE_LENGTH = MAX_HIGHLIGHT_QUOTE_LENGTH;
+exports.MAX_SETTLE_ITEMS = MAX_SETTLE_ITEMS;
 exports.MAX_TABLE_CELL_LENGTH = MAX_TABLE_CELL_LENGTH;
 exports.MAX_TABLE_COLUMNS = MAX_TABLE_COLUMNS;
 exports.MAX_TIMESTAMP_SECONDS = MAX_TIMESTAMP_SECONDS;
 exports.REQUIRED_MESSAGE = REQUIRED_MESSAGE;
 exports.STRUCTURED_FIELD_TYPES = STRUCTURED_FIELD_TYPES;
+exports.calculatedProps = calculatedProps;
+exports.calculatedValue = calculatedValue;
 exports.canonicalJson = canonicalJson;
 exports.choiceOptions = choiceOptions;
 exports.coerceHidden = coerceHidden;
 exports.coerceHiddenValue = coerceHiddenValue;
 exports.computePath = computePath;
 exports.createForm = createForm;
+exports.dateLimits = dateLimits;
 exports.defineForm = defineForm;
 exports.describeCondition = describeCondition;
 exports.evaluate = evaluate;
+exports.evaluateFormula = evaluateFormula;
 exports.explain = explain;
 exports.f = f;
 exports.fingerprint = fingerprint;
+exports.formatCalculated = formatCalculated;
 exports.formatTimestamp = formatTimestamp;
+exports.formulaInput = formulaInput;
+exports.formulaNumber = formulaNumber;
+exports.formulaRefs = formulaRefs;
 exports.getFieldType = getFieldType;
 exports.isEmptyValue = isEmptyValue;
 exports.isFormEvent = isFormEvent;
+exports.isIsoDate = isIsoDate;
 exports.isJson = isJson;
 exports.isSensitive = isSensitive;
 exports.listFieldTypes = listFieldTypes;
 exports.listLimits = listLimits;
 exports.normalizeValue = normalizeValue;
+exports.numberLimits = numberLimits;
 exports.parseForm = parseForm;
+exports.parseFormula = parseFormula;
 exports.parseTimestamp = parseTimestamp;
+exports.ratingDisplay = ratingDisplay;
 exports.recall = recall;
 exports.registerFieldType = registerFieldType;
+exports.renameFormulaKey = renameFormulaKey;
 exports.replay = replay;
 exports.ruleVisible = ruleVisible;
+exports.scaleLabels = scaleLabels;
 exports.steps = steps;
 exports.summarizeValue = summarizeValue;
 exports.tableColumns = tableColumns;