@marktiderman/genesis-forms 0.4.1 → 0.5.0

package/dist/index.cjs

@@ -417,7 +417,9 @@ var round = (n, decimals) => {
   return Object.is(r, -0) ? 0 : r;
 };
 function calculatedValue(result, field2) {
-  const { format, decimals } = calculatedProps(field2);
+  return valueAs(result, calculatedProps(field2));
+}
+function valueAs(result, { format, decimals }) {
   if (result === null || Array.isArray(result)) return void 0;
   if (format === "number" || format === "percent") {
     const n = formulaNumber(result);
@@ -444,19 +446,6 @@ var extract = (value, column) => column !== void 0 ? value.flatMap((row) => {
   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;
@@ -475,9 +464,19 @@ function refNodes(node, out = []) {
   else if (node.kind === "call") for (const a of node.args) refNodes(a, out);
   return out;
 }
+function formulaSize(node) {
+  if (node.kind === "unary") return 1 + formulaSize(node.arg);
+  if (node.kind === "binary") return 1 + formulaSize(node.left) + formulaSize(node.right);
+  if (node.kind === "if") return 1 + formulaSize(node.test) + formulaSize(node.then) + formulaSize(node.else);
+  if (node.kind === "call") return node.args.reduce((n, a) => n + formulaSize(a), 1);
+  return 1;
+}
+function spend(budget, amount) {
+  return;
+}
 var UNREAD = /* @__PURE__ */ Symbol("unread");
 var OVER = /* @__PURE__ */ Symbol("over");
-function calculator(definition) {
+function calculator(definition, work) {
   const compiled = [];
   const idByKey = /* @__PURE__ */ new Map();
   for (const block of definition.blocks) {
@@ -486,7 +485,8 @@ function calculator(definition) {
   }
   for (const block of definition.blocks) {
     if (block.kind !== "field" || !isCalculated(block)) continue;
-    const parsed = parseFormula(calculatedProps(block).formula);
+    const props2 = calculatedProps(block);
+    const parsed = parseFormula(props2.formula);
     const reads = [];
     const slots = /* @__PURE__ */ new Map();
     const byKey = /* @__PURE__ */ new Map();
@@ -500,33 +500,64 @@ function calculator(definition) {
       }
       slots.set(ref, slot);
     }
-    compiled.push({ field: block, ast: parsed.ok ? parsed.ast : null, reads, slots, last: null });
+    compiled.push({ field: block, props: props2, ast: parsed.ok ? parsed.ast : null, size: parsed.ok ? formulaSize(parsed.ast) : 0, reads, slots, last: null });
   }
+  const extracted = /* @__PURE__ */ new WeakMap();
+  const 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;
+  };
+  const readAnswer = (value, column) => {
+    if (Array.isArray(value)) return cachedList(value, column);
+    return column !== void 0 ? null : formulaInput(value);
+  };
+  const forget = (value) => {
+    if (!value || typeof value !== "object") return;
+    if (Array.isArray(value)) extracted.delete(value);
+    for (const entry of compiled) if (entry.last?.inputs.includes(value)) entry.last = null;
+  };
   const withCalculated = (values, path) => {
     if (!compiled.length) return values;
     const visible = new Set(path);
     let next = values;
+    let copied = false;
     let budget = MAX_SETTLE_ITEMS;
     const within = /* @__PURE__ */ new Map();
-    const input = ({ id, key }) => {
+    const input = ({ id }) => {
       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);
+      let ok = within.get(id);
       if (ok === void 0) {
         ok = value.length <= MAX_FORMULA_ITEMS && value.length <= budget;
         if (ok) budget -= value.length;
-        within.set(key, ok);
+        within.set(id, ok);
       }
       return ok ? value : OVER;
     };
     for (const entry of compiled) {
       const { field: field2, ast } = entry;
-      const inputs = entry.reads.map(input);
+      const { reads } = entry;
+      const inputs = new Array(reads.length);
+      let over = false;
+      let same = entry.last !== null;
+      for (let i = 0; i < reads.length; i++) {
+        const v = input(reads[i]);
+        inputs[i] = v;
+        if (v === OVER) over = true;
+        if (same && entry.last.inputs[i] !== v) same = false;
+      }
       let value;
-      if (entry.last && entry.last.inputs.length === inputs.length && entry.last.inputs.every((v, i) => v === inputs[i])) {
+      if (same) {
         value = entry.last.value;
       } else {
+        spend(work, entry.size);
         const resolved = new Array(inputs.length);
         const read = (ref) => {
           const slot = entry.slots.get(ref);
@@ -534,19 +565,25 @@ function calculator(definition) {
           let v = resolved[slot];
           if (v === void 0) {
             const raw = inputs[slot];
-            v = resolved[slot] = raw === UNREAD ? null : readAnswer(raw, entry.reads[slot].column);
+            v = resolved[slot] = raw === UNREAD ? null : readAnswer(raw, reads[slot].column);
           }
           return v;
         };
-        value = ast && !inputs.includes(OVER) ? calculatedValue(evaluateFormula(ast, read), field2) : void 0;
+        value = ast && !over ? valueAs(evaluateFormula(ast, read), entry.props) : 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 };
+      if (current !== value) {
+        if (!copied) {
+          next = { ...next };
+          copied = true;
+        }
+        next[field2.id] = value;
+      }
     }
     return next;
   };
-  return { active: compiled.length > 0, withCalculated };
+  return { active: compiled.length > 0, ids: new Set(compiled.map((c) => c.field.id)), withCalculated, forget };
 }
 var numberOps = ["eq", "neq", "lt", "lte", "gt", "gte", "in", "answered", "empty"];
 var calculatedFieldType = {
@@ -798,6 +835,81 @@ var structuredFieldTypes = [
   }
 ];
 
+// src/photo.ts
+var PHOTO_TYPE = "photo";
+var UPLOAD_FIELD_TYPES = [PHOTO_TYPE];
+var PHOTO_FORMATS = {
+  jpeg: ["image/jpeg"],
+  png: ["image/png"],
+  heic: ["image/heic", "image/heif"],
+  webp: ["image/webp"]
+};
+var FORMAT_NAMES = { jpeg: "JPEG", png: "PNG", heic: "HEIC", webp: "WebP" };
+var ALL_FORMATS = Object.keys(PHOTO_FORMATS);
+var DEFAULT_PHOTO_FILES = 3;
+var MAX_PHOTO_FILES = 5;
+var DEFAULT_PHOTO_SIZE_MB = 10;
+var MAX_PHOTO_SIZE_MB = 25;
+var MAX_PHOTO_ID_LENGTH = 200;
+var MAX_PHOTO_NAME_LENGTH = 255;
+var isPhotoFormat = (v) => typeof v === "string" && Object.prototype.hasOwnProperty.call(PHOTO_FORMATS, v);
+var wholeIn = (v, min, max) => typeof v === "number" && Number.isInteger(v) && v >= min && v <= max;
+function photoLimits(field2) {
+  const maxFiles = wholeIn(field2.props?.maxFiles, 1, MAX_PHOTO_FILES) ? field2.props.maxFiles : DEFAULT_PHOTO_FILES;
+  const maxSizeMb = wholeIn(field2.props?.maxSizeMb, 1, MAX_PHOTO_SIZE_MB) ? field2.props.maxSizeMb : DEFAULT_PHOTO_SIZE_MB;
+  const raw = field2.props?.formats;
+  const picked = Array.isArray(raw) ? ALL_FORMATS.filter((f2) => raw.includes(f2)) : [];
+  const formats = picked.length ? picked : [...ALL_FORMATS];
+  return {
+    maxFiles,
+    maxSizeMb,
+    maxBytes: maxSizeMb * 1024 * 1024,
+    formats,
+    mimeTypes: formats.flatMap((f2) => PHOTO_FORMATS[f2])
+  };
+}
+function isPhotoRef(v) {
+  if (!v || typeof v !== "object" || Array.isArray(v)) return false;
+  const r = v;
+  return typeof r.id === "string" && r.id.length > 0 && r.id.length <= MAX_PHOTO_ID_LENGTH && typeof r.name === "string" && r.name.length <= MAX_PHOTO_NAME_LENGTH && typeof r.type === "string" && typeof r.size === "number" && Number.isInteger(r.size) && r.size > 0;
+}
+function photoRefs(value) {
+  if (!Array.isArray(value)) return [];
+  const refs = [];
+  for (const r of value) if (isPhotoRef(r)) refs.push({ id: r.id, name: r.name, type: r.type, size: r.size });
+  return refs;
+}
+var plural2 = (n, one, many = `${one}s`) => `${n} ${n === 1 ? one : many}`;
+function photoFormatList(formats) {
+  const names = formats.map((f2) => FORMAT_NAMES[f2]);
+  return names.length > 1 ? `${names.slice(0, -1).join(", ")} or ${names[names.length - 1]}` : names[0] ?? "";
+}
+var photoTypeMessage = (field2) => `Use a ${photoFormatList(photoLimits(field2).formats)} photo.`;
+var photoSizeMessage = (field2) => `Each photo must be ${photoLimits(field2).maxSizeMb} MB or smaller.`;
+var photoCountMessage = (field2) => `Add at most ${plural2(photoLimits(field2).maxFiles, "photo")}.`;
+var photoFieldType = {
+  type: PHOTO_TYPE,
+  label: "Photo",
+  category: "media",
+  value: { json: true },
+  operators: ["answered", "empty"],
+  a11y: { semantics: "group" },
+  isEmpty: (value) => value === void 0 || value === null || Array.isArray(value) && value.length === 0,
+  validate: (value, field2) => {
+    if (!Array.isArray(value) || !value.every(isPhotoRef)) return "Add a photo.";
+    const limits = photoLimits(field2);
+    if (value.length > limits.maxFiles) return photoCountMessage(field2);
+    const refs = value;
+    if (new Set(refs.map((r) => r.id)).size !== refs.length) return "Each photo can be added once.";
+    if (refs.some((r) => !limits.mimeTypes.includes(r.type.toLowerCase()))) return photoTypeMessage(field2);
+    if (refs.some((r) => r.size > limits.maxBytes)) return photoSizeMessage(field2);
+    return null;
+  },
+  normalize: (value) => Array.isArray(value) && value.every(isPhotoRef) ? photoRefs(value) : value,
+  summarize: (value) => photoRefs(value).map((r) => r.name || "Photo").join(", "),
+  samples: () => [[{ id: "sample-photo", name: "photo.jpg", type: "image/jpeg", size: 1024 }]]
+};
+
 // src/fields.ts
 var REGISTRY = /* @__PURE__ */ Symbol.for("@marktiderman/genesis-forms/field-types");
 var globalScope = globalThis;
@@ -840,6 +952,20 @@ function summarizeValue(value, field2) {
   if (Array.isArray(value)) return value.join(", ");
   return String(value);
 }
+var OTHER_MAX_LENGTH = 200;
+function otherOption(field2) {
+  const other = field2.props?.other;
+  if (other === true) return { label: "Other" };
+  if (other && typeof other === "object" && !Array.isArray(other)) {
+    const label = typeof other.label === "string" && other.label.trim() ? other.label.trim() : "Other";
+    return { label };
+  }
+  return null;
+}
+function isOtherValue(field2, value) {
+  return otherOption(field2) !== null && typeof value === "string" && !choiceOptions(field2).some((o) => o.value === value);
+}
+var typedOther = (field2, value) => isOtherValue(field2, value) && value.trim() !== "" && value.length <= OTHER_MAX_LENGTH;
 function choiceOptions(field2) {
   const raw = field2.props?.options;
   if (!Array.isArray(raw)) return [];
@@ -847,6 +973,42 @@ function choiceOptions(field2) {
     (o) => o && typeof o === "object" && !Array.isArray(o) && typeof o.value === "string" ? [{ value: o.value, label: typeof o.label === "string" ? o.label : void 0 }] : []
   );
 }
+function optionsSource(field2) {
+  const raw = field2.props?.optionsFrom;
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) return void 0;
+  return raw.source === "host" && typeof raw.key === "string" && raw.key ? { source: "host", key: raw.key } : void 0;
+}
+function hostList(hostOptions, key) {
+  if (!hostOptions || !Object.prototype.hasOwnProperty.call(hostOptions, key)) return [];
+  const list = hostOptions[key];
+  if (!Array.isArray(list)) return [];
+  const seen = /* @__PURE__ */ new Set();
+  const out = [];
+  for (const o of list) {
+    if (!o || typeof o !== "object" || Array.isArray(o)) continue;
+    const { value, label } = o;
+    if (typeof value !== "string" || !value || seen.has(value)) continue;
+    seen.add(value);
+    out.push(typeof label === "string" ? { value, label } : { value });
+  }
+  return out;
+}
+function withHostOptions(definition, hostOptions) {
+  let changed = false;
+  const blocks = definition.blocks.map((block) => {
+    if (block.kind !== "field") return block;
+    const from = optionsSource(block);
+    if (!from) return block;
+    const own2 = choiceOptions(block);
+    const taken = new Set(own2.map((o) => o.value));
+    const added = hostList(hostOptions, from.key).filter((o) => !taken.has(o.value));
+    if (!added.length) return block;
+    changed = true;
+    const options = [...own2, ...added].map((o) => o.label === void 0 ? { value: o.value } : { value: o.value, label: o.label });
+    return { ...block, props: { ...block.props, options } };
+  });
+  return changed ? { ...definition, blocks } : definition;
+}
 function optionLabel(field2, value) {
   const option = choiceOptions(field2).find((o) => o.value === value);
   return option?.label ?? value;
@@ -965,7 +1127,7 @@ var builtins = [
     value: { json: true },
     operators: ["eq", "neq", "in", "answered", "empty"],
     a11y: { semantics: "group" },
-    validate: (value, field2) => typeof value === "string" && choiceOptions(field2).some((o) => o.value === value) ? null : "Choose one of the options.",
+    validate: (value, field2) => typeof value === "string" && (choiceOptions(field2).some((o) => o.value === value) || typedOther(field2, value)) ? null : "Choose one of the options.",
     summarize: (value, field2) => optionLabel(field2, String(value))
   },
   {
@@ -977,7 +1139,8 @@ var builtins = [
     a11y: { semantics: "group" },
     validate: (value, field2) => {
       const allowed = new Set(choiceOptions(field2).map((o) => o.value));
-      return Array.isArray(value) && value.length <= allowed.size && new Set(value).size === value.length && value.every((v) => typeof v === "string" && allowed.has(v)) ? null : "Choose from the options.";
+      const others = Array.isArray(value) ? value.filter((v) => typeof v === "string" && !allowed.has(v)) : [];
+      return Array.isArray(value) && new Set(value).size === value.length && value.every((v) => typeof v === "string") && (others.length === 0 || others.length === 1 && typedOther(field2, others[0])) ? null : "Choose from the options.";
     },
     summarize: (value, field2) => Array.isArray(value) ? value.map((v) => optionLabel(field2, String(v))).join(", ") : String(value)
   },
@@ -998,7 +1161,7 @@ var builtins = [
     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.",
+    validate: (value, field2) => typeof value === "string" && (choiceOptions(field2).some((o) => o.value === value) || typedOther(field2, value)) ? null : "Choose one of the options.",
     summarize: (value, field2) => optionLabel(field2, String(value))
   },
   {
@@ -1108,7 +1271,7 @@ function dateLimits(field2) {
   if (typeof max === "string" && isIsoDate(max)) out.max = max;
   return out;
 }
-for (const manifest of [...builtins, ...structuredFieldTypes, calculatedFieldType]) registerFieldType(manifest);
+for (const manifest of [...builtins, ...structuredFieldTypes, calculatedFieldType, photoFieldType]) registerFieldType(manifest);
 
 // src/logic.ts
 function own(record, key) {
@@ -1181,8 +1344,8 @@ function rulesAllow(def, blockId, scope) {
 }
 function walkPath(def, scope) {
   const list = steps(def);
-  const index = new Map(list.map((b, i2) => [b.id, i2]));
-  const position = new Map(def.blocks.map((b, i2) => [b.id, i2]));
+  let index;
+  let position;
   const jumps = (def.logic ?? []).filter(
     (r) => r.effect === "jump"
   );
@@ -1206,6 +1369,7 @@ function walkPath(def, scope) {
         ending = jump.to.ending;
         break;
       }
+      index ??= new Map(list.map((b, at) => [b.id, at]));
       const target = index.get(jump.to);
       if (target !== void 0 && target > i) {
         i = nextVisible(target);
@@ -1215,6 +1379,7 @@ function walkPath(def, scope) {
     i = nextVisible(i + 1);
   }
   const scopeAt = (blockId, inclusive = false) => {
+    position ??= new Map(def.blocks.map((b, i2) => [b.id, i2]));
     const at = position.get(blockId) ?? -1;
     const values = /* @__PURE__ */ Object.create(null);
     for (const id of path) {
@@ -1406,6 +1571,22 @@ function parseForm(input) {
       }
     }
     if (type === "consent") optionalText(props2.text, `${path}.text`);
+    if (type === PHOTO_TYPE) {
+      if (props2.maxFiles !== void 0 && !(isInt(props2.maxFiles) && props2.maxFiles >= 1 && props2.maxFiles <= MAX_PHOTO_FILES)) {
+        issue(`${path}.maxFiles`, `Must be a whole number from 1 to ${MAX_PHOTO_FILES}.`);
+      }
+      if (props2.maxSizeMb !== void 0 && !(isInt(props2.maxSizeMb) && props2.maxSizeMb >= 1 && props2.maxSizeMb <= MAX_PHOTO_SIZE_MB)) {
+        issue(`${path}.maxSizeMb`, `Must be a whole number from 1 to ${MAX_PHOTO_SIZE_MB}.`);
+      }
+      if (props2.formats !== void 0) {
+        const formats = props2.formats;
+        if (!Array.isArray(formats) || formats.length === 0 || !formats.every(isPhotoFormat)) {
+          issue(`${path}.formats`, "Must be a list of one or more of jpeg, png, heic and webp.");
+        } else if (new Set(formats).size !== formats.length) {
+          issue(`${path}.formats`, "Name each format once.");
+        }
+      }
+    }
   };
   if (!isObject2(input)) {
     issue("", "A form definition must be an object.");
@@ -1426,6 +1607,7 @@ function parseForm(input) {
     else {
       optionalBoolean(input.settings.anonymous, "settings.anonymous");
       optionalBoolean(input.settings.clearHiddenValues, "settings.clearHiddenValues");
+      optionalBoolean(input.settings.saveProgress, "settings.saveProgress");
     }
   }
   if (input.meta !== void 0 && (!isObject2(input.meta) || !isJson(input.meta))) {
@@ -1466,6 +1648,14 @@ function parseForm(input) {
         issue(`${path}.type`, `Unknown field type "${String(block.type)}".`);
       }
       if (block.props !== void 0) {
+        const from = isObject2(block.props) ? block.props.optionsFrom : void 0;
+        if (from !== void 0) {
+          if (!isObject2(from) || from.source !== "host" || typeof from.key !== "string" || !from.key) {
+            issue(`${path}.props.optionsFrom`, 'Must be { source: "host", key } with a non-empty key.');
+          } else if (typeof block.type === "string" && !CHOICE_TYPES.has(block.type)) {
+            warnings.push({ path: `${path}.props.optionsFrom`, message: "Only single choice, multiple choice and dropdown questions take options from the app." });
+          }
+        }
         if (!isObject2(block.props) || !isJson(block.props)) issue(`${path}.props`, "Must be a JSON object.");
         else if (block.props.options !== void 0) {
           const options = block.props.options;
@@ -1476,10 +1666,20 @@ function parseForm(input) {
               if (!isObject2(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) => isObject2(o) && typeof o.value === "string" ? [o.value] : []))
-            );
+            if (from === void 0) {
+              choices.set(
+                block.id,
+                new Set(options.flatMap((o) => isObject2(o) && typeof o.value === "string" ? [o.value] : []))
+              );
+            }
+          }
+        }
+        const other = isObject2(block.props) ? block.props.other : void 0;
+        if (other !== void 0) {
+          if (other !== true && other !== false && !(isObject2(other) && (other.label === void 0 || typeof other.label === "string"))) {
+            issue(`${path}.props.other`, "Must be true, false or { label }.");
+          } else if (other !== false && typeof block.type === "string" && !CHOICE_TYPES.has(block.type)) {
+            warnings.push({ path: `${path}.props.other`, message: 'Only single choice, multiple choice and dropdown questions take an "Other" answer.' });
           }
         }
         const { max, maxLength: maxLength2 } = isObject2(block.props) ? block.props : {};
@@ -1554,6 +1754,8 @@ function parseForm(input) {
       } 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.` });
+      } else if (targetType === PHOTO_TYPE) {
+        warnings.push({ path, message: `"${ref.key}" holds photos, not numbers; the formula reads it as blank.` });
       }
     }
   });
@@ -1773,9 +1975,15 @@ function field(type, key, options, props2) {
   return block;
 }
 var props = (all) => Object.fromEntries(Object.entries(all).filter((e) => e[1] !== void 0));
-var choiceProps = (options) => ({
-  options: options.map((o) => o.label ? { value: o.value, label: o.label } : { value: o.value })
-});
+var choiceProps = (o) => {
+  const out = {};
+  if (o.options || !o.optionsFrom) {
+    out.options = (o.options ?? []).map((x) => x.label ? { value: x.value, label: x.label } : { value: x.value });
+  }
+  if (o.optionsFrom) out.optionsFrom = { source: o.optionsFrom.source, key: o.optionsFrom.key };
+  if (o.other) out.other = o.other === true ? true : props({ label: o.other.label });
+  return out;
+};
 var hiddenSpec = (type, o) => ({
   type,
   source: o.source ?? "url",
@@ -1799,11 +2007,11 @@ var f = {
   ),
   /** 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)),
+  singleChoice: (key, o) => field("single-choice", key, o, choiceProps(o)),
+  multiChoice: (key, o) => field("multi-choice", key, o, choiceProps(o)),
   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)),
+  dropdown: (key, o) => field("dropdown", key, o, choiceProps(o)),
   /** 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`). */
@@ -1855,6 +2063,17 @@ var f = {
     o,
     props({ text: o.text, maxHighlights: o.maxHighlights })
   ),
+  /**
+   * Up to a few photos (a picture of broken equipment). The answer holds the
+   * references the host's upload returned, never the bytes; `formats` from
+   * jpeg, png, heic and webp (default all four).
+   */
+  photo: (key, o) => field(
+    "photo",
+    key,
+    o,
+    props({ maxFiles: o.maxFiles, maxSizeMb: o.maxSizeMb, formats: o.formats ? [...o.formats] : void 0 })
+  ),
   /** Any registered field type, including plugins. */
   custom: (type, key, o) => field(type, key, o, o.props),
   heading: (id, text) => ({ kind: "content", id, type: "heading", text }),
@@ -2026,10 +2245,20 @@ function validateField(field2, value, options = {}) {
 }
 
 // src/engine.ts
+function readsAny(node, ids) {
+  if (Array.isArray(node)) return node.some((n) => readsAny(n, ids));
+  if (!node || typeof node !== "object") return false;
+  for (const [k, v] of Object.entries(node)) {
+    if (k === "field" && typeof v === "string" && ids.has(v)) return true;
+    if (typeof v === "object" && readsAny(v, ids)) return true;
+  }
+  return false;
+}
 function createForm(definition, options = {}) {
   return build(definition, options).engine;
 }
-function build(definition, options, replaying = false) {
+function build(given, options, replaying = false, budget) {
+  const definition = withHostOptions(given, options.hostOptions);
   const fields = fieldMap(definition);
   const byKey = new Map([...fields.values()].map((f2) => [f2.key, f2]));
   const blocks = new Map(definition.blocks.map((b) => [b.id, b]));
@@ -2047,15 +2276,24 @@ function build(definition, options, replaying = false) {
     if (!declared.has(name)) initialHidden[name] = value;
   }
   Object.assign(initialHidden, coerceHidden(definition, options.hidden).values);
-  const calc = calculator(definition);
+  const calc = calculator(definition, budget);
+  const pathOf = (values, hidden) => {
+    spend(budget, definition.blocks.length);
+    return computePath(definition, scopeOf(values, hidden));
+  };
+  const logicReadsCalculated = calc.active && readsAny(definition.logic, calc.ids);
   const settle = (values, hidden) => {
-    let { path } = computePath(definition, scopeOf(values, hidden));
+    let { path } = pathOf(values, hidden);
     if (!calc.active) return { values, path };
+    if (!logicReadsCalculated) return { values: calc.withCalculated(values, path), 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;
+      const again = pathOf(values, hidden).path;
+      const same = again.length === path.length && again.every((id, i) => id === path[i]);
+      path = again;
+      if (same) break;
     }
     return { values, path };
   };
@@ -2066,6 +2304,7 @@ function build(definition, options, replaying = false) {
     path: first.path,
     current: first.path[0] ?? null,
     history: [],
+    furthest: first.path[0] ?? null,
     errors: {},
     status: "in_progress",
     ending: null,
@@ -2097,14 +2336,30 @@ 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 };
+  let formulasStale = false;
+  const settleNow = (needValues = true) => {
+    if (unsettled && calc.active && !logicReadsCalculated && !needValues) {
+      unsettled = false;
+      formulasStale = true;
+      state = { ...state, path: pathOf(state.values, state.hidden).path };
+      return;
+    }
+    if (unsettled) {
+      unsettled = false;
+      formulasStale = false;
+      const { values, path } = settle(state.values, state.hidden);
+      state = { ...state, values, path };
+    } else if (formulasStale && needValues) {
+      formulasStale = false;
+      state = { ...state, values: calc.withCalculated(state.values, state.path) };
+    }
   };
   const answer = (id, value, event) => {
-    if (state.status === "completed" || own(state.values, id) === value || isCalculated(fields.get(id))) return;
+    if (state.status === "completed" || isCalculated(fields.get(id))) return;
+    if (own(state.values, id) === value) {
+      if (value === null || typeof value !== "object") return;
+      calc.forget(value);
+    }
     const errors = { ...state.errors };
     delete errors[id];
     if (batch) {
@@ -2150,7 +2405,8 @@ function build(definition, options, replaying = false) {
         emit({ ...state, events });
         return true;
       }
-      emit({ ...state, current: target, history: [...state.history, state.current], events });
+      const furthest = state.furthest && state.path.indexOf(state.furthest) >= state.path.indexOf(target) ? state.furthest : target;
+      emit({ ...state, current: target, history: [...state.history, state.current], furthest, events });
       return true;
     },
     back() {
@@ -2170,7 +2426,7 @@ function build(definition, options, replaying = false) {
         emit({ ...state, errors, current: firstError, events });
         return false;
       }
-      const { ending } = computePath(definition, scopeOf(state.values, state.hidden));
+      const { ending } = pathOf(state.values, state.hidden);
       emit({ ...state, errors: {}, status: "completed", ending, events });
       return true;
     },
@@ -2195,6 +2451,15 @@ function build(definition, options, replaying = false) {
     settleNow();
     batch = wasBatch;
   }
+  const resumeAt = options.resumeAt;
+  if (resumeAt && !replaying && state.path.includes(resumeAt)) {
+    for (let i = 0; i < state.path.length && state.current !== resumeAt; i++) {
+      if (!engine.next()) {
+        state = { ...state, errors: {} };
+        break;
+      }
+    }
+  }
   const apply = (event) => {
     if (event.type === "answer") {
       if (fields.has(event.field)) {
@@ -2202,10 +2467,11 @@ function build(definition, options, replaying = false) {
         answer(event.field, event.value, logged);
       }
     } else if (event.type === "next") {
-      settleNow();
+      settleNow(false);
+      if (formulasStale && isCalculated(fields.get(state.current ?? ""))) settleNow(true);
       engine.next();
     } else if (event.type === "back") {
-      settleNow();
+      settleNow(false);
       engine.back();
     } else if (event.type === "submit") {
       settleNow();
@@ -2220,12 +2486,46 @@ function build(definition, options, replaying = false) {
   return { engine, apply, finish };
 }
 function replay(definition, events, options = {}) {
-  const { engine, apply, finish } = build(definition, { ...options, initialValues: void 0, clock: () => void 0 }, true);
-  for (const event of events) apply(event);
-  finish();
+  return replayWithin(definition, events, options);
+}
+function replayWithin(definition, events, options, maxWork) {
+  const budget = void 0 ;
+  const { engine, apply, finish } = build(definition, { ...options, initialValues: void 0, clock: () => void 0 }, true, budget);
+  try {
+    for (const event of events) apply(event);
+    finish();
+  } finally {
+  }
   return engine;
 }
 
+// src/progress.ts
+function furthestReached(state, definition) {
+  const at = (id) => id ? state.path.indexOf(id) : -1;
+  let furthest = Math.max(at(state.current), at(state.furthest));
+  for (const id of state.history) furthest = Math.max(furthest, at(id));
+  const fields = fieldMap(definition);
+  for (let i = state.path.length - 1; i > furthest; i--) {
+    const field2 = fields.get(state.path[i]);
+    if (field2 && !isEmptyValue(own(state.values, field2.id), field2)) {
+      furthest = i;
+      break;
+    }
+  }
+  return furthest >= 0 ? state.path[furthest] : null;
+}
+function formProgress(engine) {
+  const state = engine.getState();
+  const furthest = furthestReached(state, engine.definition);
+  const index = furthest ? state.path.indexOf(furthest) : -1;
+  const fields = fieldMap(engine.definition);
+  let fieldId = null;
+  for (let i = index; i >= 0 && fieldId === null; i--) {
+    if (fields.has(state.path[i])) fieldId = state.path[i];
+  }
+  return { step: index + 1, total: state.path.length, fieldId };
+}
+
 // src/explain.ts
 function explain(source, blockId, options = {}) {
   const input = "getState" in source ? { definition: source.definition, values: source.getState().values, hidden: source.getState().hidden } : source;
@@ -2364,6 +2664,8 @@ function describeCondition(condition, def, fields = fieldMap(def)) {
 
 exports.CALCULATED_TYPE = CALCULATED_TYPE;
 exports.COMPUTED_FIELD_TYPES = COMPUTED_FIELD_TYPES;
+exports.DEFAULT_PHOTO_FILES = DEFAULT_PHOTO_FILES;
+exports.DEFAULT_PHOTO_SIZE_MB = DEFAULT_PHOTO_SIZE_MB;
 exports.FORMULA_FUNCTIONS = FORMULA_FUNCTIONS;
 exports.HIGHLIGHT_NOTE_MESSAGE = HIGHLIGHT_NOTE_MESSAGE;
 exports.MAX_CALCULATED_DECIMALS = MAX_CALCULATED_DECIMALS;
@@ -2373,12 +2675,20 @@ 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_PHOTO_FILES = MAX_PHOTO_FILES;
+exports.MAX_PHOTO_ID_LENGTH = MAX_PHOTO_ID_LENGTH;
+exports.MAX_PHOTO_NAME_LENGTH = MAX_PHOTO_NAME_LENGTH;
+exports.MAX_PHOTO_SIZE_MB = MAX_PHOTO_SIZE_MB;
 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.OTHER_MAX_LENGTH = OTHER_MAX_LENGTH;
+exports.PHOTO_FORMATS = PHOTO_FORMATS;
+exports.PHOTO_TYPE = PHOTO_TYPE;
 exports.REQUIRED_MESSAGE = REQUIRED_MESSAGE;
 exports.STRUCTURED_FIELD_TYPES = STRUCTURED_FIELD_TYPES;
+exports.UPLOAD_FIELD_TYPES = UPLOAD_FIELD_TYPES;
 exports.calculatedProps = calculatedProps;
 exports.calculatedValue = calculatedValue;
 exports.canonicalJson = canonicalJson;
@@ -2395,24 +2705,37 @@ exports.evaluateFormula = evaluateFormula;
 exports.explain = explain;
 exports.f = f;
 exports.fingerprint = fingerprint;
+exports.formProgress = formProgress;
 exports.formatCalculated = formatCalculated;
 exports.formatTimestamp = formatTimestamp;
 exports.formulaInput = formulaInput;
 exports.formulaNumber = formulaNumber;
 exports.formulaRefs = formulaRefs;
+exports.furthestReached = furthestReached;
 exports.getFieldType = getFieldType;
 exports.isEmptyValue = isEmptyValue;
 exports.isFormEvent = isFormEvent;
 exports.isIsoDate = isIsoDate;
 exports.isJson = isJson;
+exports.isOtherValue = isOtherValue;
+exports.isPhotoFormat = isPhotoFormat;
+exports.isPhotoRef = isPhotoRef;
 exports.isSensitive = isSensitive;
 exports.listFieldTypes = listFieldTypes;
 exports.listLimits = listLimits;
 exports.normalizeValue = normalizeValue;
 exports.numberLimits = numberLimits;
+exports.optionsSource = optionsSource;
+exports.otherOption = otherOption;
 exports.parseForm = parseForm;
 exports.parseFormula = parseFormula;
 exports.parseTimestamp = parseTimestamp;
+exports.photoCountMessage = photoCountMessage;
+exports.photoFormatList = photoFormatList;
+exports.photoLimits = photoLimits;
+exports.photoRefs = photoRefs;
+exports.photoSizeMessage = photoSizeMessage;
+exports.photoTypeMessage = photoTypeMessage;
 exports.ratingDisplay = ratingDisplay;
 exports.recall = recall;
 exports.registerFieldType = registerFieldType;
@@ -2426,5 +2749,6 @@ exports.tableColumns = tableColumns;
 exports.tableLimits = tableLimits;
 exports.validateField = validateField;
 exports.when = when;
+exports.withHostOptions = withHostOptions;
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map