@marktiderman/genesis-forms 0.4.2 → 0.5.0

package/dist/server.d.cts

@@ -1,5 +1,5 @@
-import { J as Json, e as FormEvent, F as FormDefinition } from './types-BBKBQ8sp.cjs';
-import { F as FieldValidator } from './validate-BXXqi0fq.cjs';
+import { F as FieldValidator, H as HostOptions } from './validate-BsZ0YTQS.cjs';
+import { J as Json, e as FormEvent, F as FormDefinition } from './types-BhYUbLJ-.cjs';
 
 interface SubmissionInput {
     /** Answers keyed by field id. Ignored when `events` is given. */
@@ -35,6 +35,13 @@ interface SubmissionOptions {
      * replay counts: the submit that follows it does not.
      */
     maxReplayWork?: number | undefined;
+    /**
+     * The option lists the app supplies for `optionsFrom: { source: "host" }`
+     * choice fields, loaded here on the server (never taken from the client):
+     * an answer must be one of the field's own options or of these. Pass what
+     * the form was shown with, loaded afresh, such as the current staff.
+     */
+    hostOptions?: HostOptions | undefined;
 }
 interface CheckedSubmission {
     status: "draft" | "completed";
@@ -74,7 +81,7 @@ declare const RAW_EVENTS_PER_EVENT = 10;
  * Check a submission against the published definition. Never throws on a
  * malformed submission: it returns `{ ok: false, errors: { "": … } }`.
  */
-declare function validateSubmission(definition: FormDefinition, submission: SubmissionInput, options?: SubmissionOptions): SubmissionResult;
+declare function validateSubmission(published: FormDefinition, submission: SubmissionInput, options?: SubmissionOptions): SubmissionResult;
 /**
  * The definition as respondents may see it. R1 forms hold nothing secret;
  * assessment answer keys (R4) will be stripped here.

package/dist/server.d.ts

@@ -1,5 +1,5 @@
-import { J as Json, e as FormEvent, F as FormDefinition } from './types-BBKBQ8sp.js';
-import { F as FieldValidator } from './validate-BjNwF1UE.js';
+import { F as FieldValidator, H as HostOptions } from './validate-Bs1lyoOl.js';
+import { J as Json, e as FormEvent, F as FormDefinition } from './types-BhYUbLJ-.js';
 
 interface SubmissionInput {
     /** Answers keyed by field id. Ignored when `events` is given. */
@@ -35,6 +35,13 @@ interface SubmissionOptions {
      * replay counts: the submit that follows it does not.
      */
     maxReplayWork?: number | undefined;
+    /**
+     * The option lists the app supplies for `optionsFrom: { source: "host" }`
+     * choice fields, loaded here on the server (never taken from the client):
+     * an answer must be one of the field's own options or of these. Pass what
+     * the form was shown with, loaded afresh, such as the current staff.
+     */
+    hostOptions?: HostOptions | undefined;
 }
 interface CheckedSubmission {
     status: "draft" | "completed";
@@ -74,7 +81,7 @@ declare const RAW_EVENTS_PER_EVENT = 10;
  * Check a submission against the published definition. Never throws on a
  * malformed submission: it returns `{ ok: false, errors: { "": … } }`.
  */
-declare function validateSubmission(definition: FormDefinition, submission: SubmissionInput, options?: SubmissionOptions): SubmissionResult;
+declare function validateSubmission(published: FormDefinition, submission: SubmissionInput, options?: SubmissionOptions): SubmissionResult;
 /**
  * The definition as respondents may see it. R1 forms hold nothing secret;
  * assessment answer keys (R4) will be stripped here.

package/dist/server.js

@@ -719,6 +719,80 @@ 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 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(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;
@@ -755,6 +829,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 [];
@@ -762,6 +850,42 @@ function choiceOptions(field) {
     (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(field) {
+  const raw = field.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(field, value) {
   const option = choiceOptions(field).find((o) => o.value === value);
   return option?.label ?? value;
@@ -880,7 +1004,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))
   },
   {
@@ -892,7 +1016,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)
   },
@@ -913,7 +1038,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))
   },
   {
@@ -1020,7 +1145,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/events.ts
 function isPlainObject(value) {
@@ -1289,7 +1414,8 @@ function readsAny(node, ids) {
 function createForm(definition, options = {}) {
   return build(definition, options).engine;
 }
-function build(definition, options, replaying = false, budget) {
+function build(given, options, replaying = false, budget) {
+  const definition = withHostOptions(given, options.hostOptions);
   const fields = fieldMap(definition);
   const byKey = new Map([...fields.values()].map((f) => [f.key, f]));
   const blocks = new Map(definition.blocks.map((b) => [b.id, b]));
@@ -1335,6 +1461,7 @@ function build(definition, options, replaying = false, budget) {
     path: first.path,
     current: first.path[0] ?? null,
     history: [],
+    furthest: first.path[0] ?? null,
     errors: {},
     status: "in_progress",
     ending: null,
@@ -1435,7 +1562,8 @@ function build(definition, options, replaying = false, budget) {
         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() {
@@ -1480,6 +1608,15 @@ function build(definition, options, replaying = false, budget) {
     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)) {
@@ -1667,6 +1804,22 @@ function parseForm(input) {
       }
     }
     if (type === "consent") optionalText(props.text, `${path}.text`);
+    if (type === PHOTO_TYPE) {
+      if (props.maxFiles !== void 0 && !(isInt(props.maxFiles) && props.maxFiles >= 1 && props.maxFiles <= MAX_PHOTO_FILES)) {
+        issue(`${path}.maxFiles`, `Must be a whole number from 1 to ${MAX_PHOTO_FILES}.`);
+      }
+      if (props.maxSizeMb !== void 0 && !(isInt(props.maxSizeMb) && props.maxSizeMb >= 1 && props.maxSizeMb <= MAX_PHOTO_SIZE_MB)) {
+        issue(`${path}.maxSizeMb`, `Must be a whole number from 1 to ${MAX_PHOTO_SIZE_MB}.`);
+      }
+      if (props.formats !== void 0) {
+        const formats = props.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.");
@@ -1687,6 +1840,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))) {
@@ -1727,6 +1881,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;
@@ -1737,10 +1899,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 : {};
@@ -1815,6 +1987,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.` });
       }
     }
   });
@@ -2079,9 +2253,10 @@ function wellFormed(input) {
   }
   return { answers, events: known, hidden };
 }
-function validateSubmission(definition, submission, options = {}) {
-  const invalid = checkDefinition(definition);
+function validateSubmission(published, submission, options = {}) {
+  const invalid = checkDefinition(published);
   if (invalid) return { ok: false, errors: { "": invalid } };
+  const definition = withHostOptions(published, options.hostOptions);
   if (!isPlainObject(submission)) return MALFORMED;
   const maxEvents = options.maxEvents ?? MAX_EVENTS;
   let sent = submission;