@marktiderman/genesis-forms 0.4.2 → 0.6.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
@@ -210,6 +239,129 @@ 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.
+
+### Option details, filtered lists, search and links
+
+An option can carry more than its value and label, from the question's own `options` or the
+app's list:
+
+```ts
+{ value: "cff", label: "CrossFit Fairfield",
+  description: "12 Main St",                    // a muted line under the label
+  image: "https://cdn.example.com/cff.png",      // a small picture; https only
+  attributes: { region: "north", coaches: ["ada", "sam"] } } // for filters and recall
+```
+
+`readOption` keeps each detail only when it is well formed and within `OPTION_LIMITS`
+(description 500 characters, image URL 2048 and `https://` only (`isHttpsUrl`), at most 20
+attributes, each a text or a list of up to 50 texts of 200 characters). `parseForm` reports a
+definition's malformed details; an app's list is read leniently (the bad detail is dropped).
+
+**Filtered by another answer.** `optionsFrom.filter` shows only the options whose attribute
+matches an earlier question's answer, such as coaches at the chosen location:
+
+```ts
+f.dropdown("location", { label: "Where?", optionsFrom: { source: "host", key: "locations" } });
+f.singleChoice("coach", {
+  label: "Who coached you?",
+  optionsFrom: { source: "host", key: "coaches", filter: { attribute: "location", field: "location" } },
+});
+// a coach: { value: "ada", label: "Ada", attributes: { location: ["cff", "cornerstone"] } }
+```
+
+`field` is the earlier question's key (`parseForm` checks it exists and comes first). An option
+matches when its attribute (a text or a list) shares a value with the answer (a text, or a
+multiple choice's list); one without the attribute never matches. Until that question is answered
+(or while it is off the path) every option shows. `visibleOptions(definition, field, values)`
+says what shows, `answersOnPath(state)` gives it the answers it should read, and React renderers
+use `useChoiceOptions` (genesis-forms-react). When the answer changes, the engine clears picks the
+filter no longer shows (`clearFilteredAnswers`, following on through filters of filters); a pick
+outside the filtered list is refused by the engine and by `validateSubmission`
+(`filteredChoiceError`).
+
+**Search.** `isSearchable(field, count)` says whether a renderer puts a search box over the
+options: `props.searchable` when it is true or false, else more than `SEARCHABLE_OPTION_COUNT`
+(10) options. `searchOptions(options, query)` is the match every renderer uses: every word of the
+query in the label, value or description, ignoring case and accents.
+
+**Preselect from a link.** `props.prefill: { param }` on a choice question takes a link's query
+parameter, such as `?location=cornerstone`:
+
+```ts
+f.dropdown("location", { label: "Where?", optionsFrom: { source: "host", key: "locations" },
+  prefill: { param: "location", hideWhenPrefilled: true } });
+
+createForm(definition, { hostOptions: lists, linkParams: new URLSearchParams(location.search) });
+// or <Form hostOptions={lists} linkParams={new URLSearchParams(location.search)}>
+```
+
+`prefillFromLink(definition, params, values)` resolves it: the value is taken only when it is one
+of the options the question shows (a filtered list too), anything else is ignored; a multiple
+choice takes repeated parameters or one comma-separated value. The picks become `initialValues`
+(logged as `source: "prefill"` answers; the host's own `initialValues` win), so the server checks
+them like any answer. With `hideWhenPrefilled` the question is skipped while it holds the link's
+answer: `hiddenByPrefill(definition, state)` lists such questions, the engine's Next and Back step
+over them, and `respondentPath(definition, state)` is the path a renderer shows and counts. The
+answer is stored as usual. A parameter name is letters, digits, `_`, `-` and `.`, at most 64
+characters (`isPrefillParam`).
+
+**Snapshots of what was picked.** Store the option's label with its value, so reports group by the
+id and history keeps the name it had then:
+
+```ts
+import { answerSnapshots, answersFromSnapshots, withHostOptions } from "@marktiderman/genesis-forms/server";
+
+const shown = withHostOptions(definition, lists);
+const snapshots = answerSnapshots(shown, result.submission.answers);
+// { location: { value: "cff", label: "CrossFit Fairfield" }, helpers: [{ value: "ada", label: "Ada" }] }
+
+// An edit link: find each pick again in today's lists.
+const { answers, missing } = answersFromSnapshots(withHostOptions(definition, listsNow), stored);
+createForm(definition, { hostOptions: listsNow, initialValues: answers });
+```
+
+`answerSnapshots` covers questions with `optionsFrom`; a typed "Other" answer is marked `other`.
+`answersFromSnapshots` keeps a value still offered, else takes an option with the same label
+(ignoring case and accents), keeps a typed "Other" answer when the question still allows one, and
+reports the rest in `missing`. Both are also exported from the main entry.
+
+### 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
@@ -235,6 +387,49 @@ limits above (`maxEvents`, `maxValues`, `maxReplayWork`). Events of an unknown t
 client's log still replays. With `settings.clearHiddenValues: false`, a hidden field's value is kept
 only if its format is valid.
 
+### Edit links
+
+A respondent can change a sent response through a signed link, `?edit=<id>.<nonce>.<expires>.<sig>`:
+an HMAC-SHA256 (Web Crypto) under a server secret of at least 32 bytes, working for 30 days. The app
+keeps a nonce per response and changes it after each edit, so only the newest link works; it checks
+the nonce itself. Without a usable secret there are no edit links: signing returns null and nothing
+verifies.
+
+```ts
+import {
+  createEditSecretReader,
+  editLinkUrl,
+  verifyEditToken,
+  withEditLinkHeaders,
+} from "@marktiderman/genesis-forms/server";
+
+const editSecret = createEditSecretReader({ variable: "FORM_EDIT_SECRET" }); // warns once when missing
+const editUrl = await editLinkUrl(`/f/${slug}`, { id: response.id, nonce: response.editNonce }, editSecret(env));
+const claims = await verifyEditToken(url.searchParams.get("edit"), editSecret(env)); // then compare claims.nonce
+// The link is a credential: no Referer, no caching, on the page it opens.
+return withEditLinkHeaders(request, response, { isFormPage: (u) => u.pathname.startsWith("/f/") });
+```
+
+`signEditToken`, `withEditToken`, `isEditLinkRequest`, `isUsableEditSecret`, `EDIT_LINK_TTL_SECONDS`,
+`MIN_EDIT_SECRET_BYTES` and `EDIT_LINK_PARAM` are the parts. `carryAnswers` (main entry) moves a
+stored response's answers onto a newer version of the form by field key, for the edit page's prefill.
+
+### Rate limits
+
+The submit endpoint's limit, without the counter: `clientIp(headers, trusted?)` reads the first
+trusted proxy header (`DEFAULT_TRUSTED_IP_HEADERS`: `x-vercel-forwarded-for`, `x-forwarded-for`,
+`x-real-ip`; trust only headers your proxy overwrites), `addressPrefix` keeps an IPv4 address whole
+and an IPv6 one by its /64, and `rateLimitKey({ kind, scope, ip, secret })` is
+`<kind>:<scope>:<hex HMAC-SHA256 of the prefix>`, so the address is never stored. The app's
+`RateLimitStore.hit(key, limit, windowSeconds)` counts (shared by every instance); `allow` fails
+open, and logs, when it answers null or throws. `RATE_LIMIT_DEFAULTS` holds 60 submits, 900 saves as
+they go and 120 photo uploads per 10 minutes.
+
+```ts
+const key = await rateLimitKey({ kind: "submit", scope: practiceId, ip: clientIp(request.headers), secret });
+if (!(await allow(store, { key, ...RATE_LIMIT_DEFAULTS.submit }, { log }))) return tooMany();
+```
+
 ## Destinations
 
 `@marktiderman/genesis-forms/destinations` sends a checked submission somewhere. No dependencies:

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,12 +436,78 @@ function summarizeValue(value, field) {
   if (Array.isArray(value)) return value.join(", ");
   return String(value);
 }
+var OPTION_LIMITS = {
+  /** Characters in a description. */
+  description: 500,
+  /** Characters in an image URL. */
+  image: 2048,
+  /** Attributes on one option. */
+  attributes: 20,
+  /** Characters in an attribute's name. */
+  attributeName: 64,
+  /** Characters in one attribute value. */
+  attributeValue: 200,
+  /** Values in one attribute's list. */
+  attributeItems: 50
+};
+function isHttpsUrl(url) {
+  return typeof url === "string" && url.length <= OPTION_LIMITS.image && /^https:\/\/[^\s/?#@\\]+(?:[/?#][^\s]*)?$/i.test(url) && // No control characters anywhere (a line break would end a CSV row or an HTML attribute).
+  ![...url].some((c) => c.charCodeAt(0) < 32 || c.charCodeAt(0) === 127);
+}
+function attributeName(name) {
+  return name.trim() !== "" && name.length <= OPTION_LIMITS.attributeName && !(name in Object.prototype);
+}
+function readAttributes(raw) {
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) return void 0;
+  const out = {};
+  let count = 0;
+  for (const name of Object.keys(raw)) {
+    if (count >= OPTION_LIMITS.attributes) break;
+    if (!attributeName(name)) continue;
+    const v = raw[name];
+    const fits = (x) => typeof x === "string" && x.length <= OPTION_LIMITS.attributeValue;
+    if (fits(v)) out[name] = v;
+    else if (Array.isArray(v) && v.length <= OPTION_LIMITS.attributeItems && v.every(fits)) out[name] = [...v];
+    else continue;
+    count++;
+  }
+  return count ? out : void 0;
+}
+function readOption(raw) {
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) return null;
+  const o = raw;
+  if (typeof o.value !== "string") return null;
+  const out = { value: o.value };
+  if (typeof o.label === "string") out.label = o.label;
+  if (typeof o.description === "string" && o.description.trim() && o.description.length <= OPTION_LIMITS.description) {
+    out.description = o.description;
+  }
+  if (isHttpsUrl(o.image)) out.image = o.image;
+  const attributes = readAttributes(o.attributes);
+  if (attributes) out.attributes = attributes;
+  return out;
+}
+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 [];
-  return raw.flatMap(
-    (o) => o && typeof o === "object" && !Array.isArray(o) && typeof o.value === "string" ? [{ value: o.value, label: typeof o.label === "string" ? o.label : void 0 }] : []
-  );
+  return raw.flatMap((o) => {
+    const option = readOption(o);
+    return option ? [option] : [];
+  });
 }
 function optionLabel(field, value) {
   const option = choiceOptions(field).find((o) => o.value === value);
@@ -488,7 +627,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 +639,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 +661,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 +768,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) {