@marktiderman/genesis-forms 0.4.1 → 0.5.0

package/README.md

@@ -62,6 +62,13 @@ const version = eventFeedback.hash();         // content fingerprint for publish
   `validateSubmission` refuses a definition that does not parse. Ids, keys, hidden names and ending
   ids may not be `Object.prototype` names (`constructor`, `__proto__`…).
 - **Unanswered recall renders its fallback** (`{{field:name|there}}`); the text is never dropped.
+- **Saving answers as they go is a setting.** `settings.saveProgress` (off by default) says the
+  host keeps the answers so far each time the respondent moves on, so an unfinished response
+  survives. `formProgress(engine)` says how far they got: `{ step, total, fieldId }`, where
+  `fieldId` is the furthest question reached (kept after Back; in classic layout, the last one
+  answered). genesis-forms-web's `onProgress` calls the host with it; the server checks the
+  answers so far with `validateSubmission(definition, input, { complete: false })`. After a
+  reload, `createForm(definition, { initialValues: saved, resumeAt: fieldId })` picks up there.
 
 ## Pieces
 
@@ -129,6 +136,28 @@ 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`.
 
+### Photo fields
+
+A `photo` field asks for up to a few photos, such as a picture of broken equipment:
+`f.photo(key, { maxFiles, maxSizeMb, formats })`. The answer holds references the host's storage
+returned, never the bytes: `PhotoRef[]`, each `{ id, name, type, size }`. The renderer uploads
+through the host (`onUpload` on genesis-forms-web's `Form`), so the engine and `validateSubmission`
+stay storage-agnostic; the host's server should check that every reference is a file it stored
+for this respondent and form before saving.
+
+| Prop | Default | Rule |
+| --- | --- | --- |
+| `maxFiles` | 3 | 1 to `MAX_PHOTO_FILES` (5). |
+| `maxSizeMb` | 10 | 1 to `MAX_PHOTO_SIZE_MB` (25), per photo. |
+| `formats` | all four | One or more of `jpeg`, `png`, `heic` (also HEIF) and `webp` (`PHOTO_FORMATS` maps each to its MIME types). |
+
+A photo is neither `sensitive` nor `identifying` by default; set either on the field when it is.
+Validation checks each reference's shape, type and size and the count; `normalize` keeps only the
+four keys; `summarizeValue` lists the file names. Like the structured types it is opt-in in a
+builder palette: `UPLOAD_FIELD_TYPES` (`["photo"]`). Helpers: `photoLimits(field)` (`maxFiles`,
+`maxSizeMb`, `maxBytes`, `formats`, `mimeTypes`), `photoRefs(value)`, `isPhotoRef`,
+`photoFormatList`, and the messages `photoTypeMessage`, `photoSizeMessage` and `photoCountMessage`.
+
 ### Calculated fields
 
 A `calculated` field shows a value worked out from other answers, such as a total, an average or a
@@ -170,12 +199,29 @@ 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).
+  list or table counted once, however many of its columns are read, 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).
+- Lists are read once per answer, so treat an engine's answers as immutable: pass `setValue` a new
+  array (the engine and the built-in renderers never change one in place). `setValue` with the
+  array it already holds works it out again. Each engine, and so each `validateSubmission` call,
+  keeps its own lists, so the same object passed again after a change is read afresh.
+- `validateSubmission` refuses a submission that would be too much work, with an error under `""`,
+  and never cuts one short. It doesn't rely on the host's request size limit. Each limit is an
+  option for a host that needs more:
+
+  | Limit | Default | Option | Counts |
+  | --- | --- | --- | --- |
+  | `MAX_EVENTS` | 10,000 | `maxEvents` | Events, after `compactEvents`; at most `RAW_EVENTS_PER_EVENT` (10) times as many may be sent |
+  | `MAX_SUBMISSION_VALUES` | 200,000 | `maxValues` | JSON values in the answers, answer events and hidden inputs: each number, text, true / false, list item, row and cell. A run of answers to one field (a table sends itself on every keystroke) counts its last only |
+  | `MAX_REPLAY_WORK` | 1,000,000 | `maxReplayWork` | Replaying the events: one unit per block each time the path is walked, one per calculated field each time the answers settle, and a formula's size (its numbers, answers and operators) each time it is worked out. The submit after the replay isn't counted |
+
+  A respondent filling in a long form with formulas uses about 400,000 units of replay work at
+  most; the limit stops a log built to make every step work out every formula. After a refusal,
+  sending the same body again gets the same answer, so show the `""` message rather than offer
+  "Try again".
 
 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
@@ -193,6 +239,44 @@ as `The formula uses "wage", which is not the answer name of a question in this
 own; `formatCalculated` shows a value as the field does. Builders offer the type only when the host
 names it (`COMPUTED_FIELD_TYPES`).
 
+### Options from the app
+
+A single choice, multiple choice or dropdown question can take its options from the app showing
+the form, such as a coach picker that always lists the current coaches:
+
+```ts
+f.dropdown("coach", { label: "Who coached you?", optionsFrom: { source: "host", key: "coaches" } });
+// stored as props: { optionsFrom: { source: "host", key: "coaches" } }
+
+const lists = { coaches: [{ value: profileId, label: "Ada Lovelace" }] }; // loaded by the app
+createForm(definition, { hostOptions: lists }); // or <Form hostOptions={lists}>
+validateSubmission(definition, body, { hostOptions: lists }); // loaded again on the server
+```
+
+`withHostOptions(definition, lists)` fills them in: the question's own `props.options` first (it
+may have some), then the list for its key, each value once. The engine does it for
+`engine.definition`, so renderers show the list and an answer must be one of these options;
+`validateSubmission` does it with the server's lists, so a value the server doesn't offer now (a
+coach who left, a made-up id) is refused. Without a list for the key, the question offers its own
+options only. Answers store the option's value; `summarizeValue` shows its label while the list has
+it. `parseForm` checks the shape of `optionsFrom`, and doesn't warn about rules comparing with
+values only the app knows.
+
+### An "Other" answer
+
+```ts
+f.multiChoice("areas", { label: "Which area?", options: [...], other: true });
+f.singleChoice("where", { label: "Where?", options: [...], other: { label: "Somewhere else" } });
+// stored as props: { other: true } or { other: { label: "Somewhere else" } }
+```
+
+A single choice, multiple choice or dropdown question with `props.other` offers one more option,
+"Other" (or its `label`), with a text box. What the respondent types is the answer: the value of a
+single choice or dropdown, one more item on a multiple choice. `validateSubmission` accepts at most
+one such value per question, not blank and at most `OTHER_MAX_LENGTH` (200) characters, and only on
+a question with `other`. `otherOption(field)` reads the setting; `isOtherValue(field, value)` tells a
+typed answer from an option.
+
 ### Props for the host
 
 Props a field type doesn't use are kept and ignored: the engine, `parseForm` and
@@ -213,8 +297,8 @@ await store(result.submission); // answers, hidden, context, ending
 ```
 
 Errors are keyed by field id. The `""` key is for the whole submission: `"Malformed submission."`
-(a body of the wrong shape), a definition that fails `parseForm`, or more than `maxEvents` events
-(default 10 000, counted after `compactEvents`). Events of an unknown type are dropped, so a newer
+(a body of the wrong shape), a definition that fails `parseForm`, or a submission past one of the
+limits above (`maxEvents`, `maxValues`, `maxReplayWork`). Events of an unknown type are dropped, so a newer
 client's log still replays. With `settings.clearHiddenValues: false`, a hidden field's value is kept
 only if its format is valid.
 

package/dist/destinations.cjs

@@ -328,6 +328,79 @@ var structuredFieldTypes = [
   }
 ];
 
+// src/photo.ts
+var PHOTO_TYPE = "photo";
+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 wholeIn = (v, min, max) => typeof v === "number" && Number.isInteger(v) && v >= min && v <= max;
+function photoLimits(field) {
+  const maxFiles = wholeIn(field.props?.maxFiles, 1, MAX_PHOTO_FILES) ? field.props.maxFiles : DEFAULT_PHOTO_FILES;
+  const maxSizeMb = wholeIn(field.props?.maxSizeMb, 1, MAX_PHOTO_SIZE_MB) ? field.props.maxSizeMb : DEFAULT_PHOTO_SIZE_MB;
+  const raw = field.props?.formats;
+  const picked = Array.isArray(raw) ? ALL_FORMATS.filter((f) => raw.includes(f)) : [];
+  const formats = picked.length ? picked : [...ALL_FORMATS];
+  return {
+    maxFiles,
+    maxSizeMb,
+    maxBytes: maxSizeMb * 1024 * 1024,
+    formats,
+    mimeTypes: formats.flatMap((f) => PHOTO_FORMATS[f])
+  };
+}
+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((f) => FORMAT_NAMES[f]);
+  return names.length > 1 ? `${names.slice(0, -1).join(", ")} or ${names[names.length - 1]}` : names[0] ?? "";
+}
+var photoTypeMessage = (field) => `Use a ${photoFormatList(photoLimits(field).formats)} photo.`;
+var photoSizeMessage = (field) => `Each photo must be ${photoLimits(field).maxSizeMb} MB or smaller.`;
+var photoCountMessage = (field) => `Add at most ${plural2(photoLimits(field).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, field) => {
+    if (!Array.isArray(value) || !value.every(isPhotoRef)) return "Add a photo.";
+    const limits = photoLimits(field);
+    if (value.length > limits.maxFiles) return photoCountMessage(field);
+    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(field);
+    if (refs.some((r) => r.size > limits.maxBytes)) return photoSizeMessage(field);
+    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;
@@ -363,6 +436,20 @@ function summarizeValue(value, field) {
   if (Array.isArray(value)) return value.join(", ");
   return String(value);
 }
+var OTHER_MAX_LENGTH = 200;
+function otherOption(field) {
+  const other = field.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(field, value) {
+  return otherOption(field) !== null && typeof value === "string" && !choiceOptions(field).some((o) => o.value === value);
+}
+var typedOther = (field, value) => isOtherValue(field, value) && value.trim() !== "" && value.length <= OTHER_MAX_LENGTH;
 function choiceOptions(field) {
   const raw = field.props?.options;
   if (!Array.isArray(raw)) return [];
@@ -488,7 +575,7 @@ var builtins = [
     value: { json: true },
     operators: ["eq", "neq", "in", "answered", "empty"],
     a11y: { semantics: "group" },
-    validate: (value, field) => typeof value === "string" && choiceOptions(field).some((o) => o.value === value) ? null : "Choose one of the options.",
+    validate: (value, field) => typeof value === "string" && (choiceOptions(field).some((o) => o.value === value) || typedOther(field, value)) ? null : "Choose one of the options.",
     summarize: (value, field) => optionLabel(field, String(value))
   },
   {
@@ -500,7 +587,8 @@ var builtins = [
     a11y: { semantics: "group" },
     validate: (value, field) => {
       const allowed = new Set(choiceOptions(field).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(field, others[0])) ? null : "Choose from the options.";
     },
     summarize: (value, field) => Array.isArray(value) ? value.map((v) => optionLabel(field, String(v))).join(", ") : String(value)
   },
@@ -521,7 +609,7 @@ var builtins = [
     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.",
+    validate: (value, field) => typeof value === "string" && (choiceOptions(field).some((o) => o.value === value) || typedOther(field, value)) ? null : "Choose one of the options.",
     summarize: (value, field) => optionLabel(field, String(value))
   },
   {
@@ -628,7 +716,7 @@ function dateLimits(field) {
   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) {