@form-engine-ts/core 1.0.0 → 2.0.0

package/dist/index.cjs

@@ -23,17 +23,24 @@ __export(index_exports, {
   aggregateResponses: () => aggregateResponses,
   assertValidFormSchema: () => assertValidFormSchema,
   calculateChoiceDistribution: () => calculateChoiceDistribution,
+  calculateCrossTabulation: () => calculateCrossTabulation,
   calculateFieldVisibility: () => calculateFieldVisibility,
   calculateNumericSummary: () => calculateNumericSummary,
+  calculatePageVisibility: () => calculatePageVisibility,
   createSubmission: () => createSubmission,
+  dispatchWebhook: () => dispatchWebhook,
   escapeCsvCell: () => escapeCsvCell,
   exportResponsesToCsv: () => exportResponsesToCsv,
+  isDisplayConditionSatisfied: () => isDisplayConditionSatisfied,
   isQuestionVisible: () => isQuestionVisible,
+  populateSchemaTranslations: () => populateSchemaTranslations,
   resolveFormTranslation: () => resolveFormTranslation,
+  resolveLocalizedSchema: () => resolveLocalizedSchema,
   sanitizeSchema: () => sanitizeSchema,
   selectVisibleAnswers: () => selectVisibleAnswers,
   validateAnswers: () => validateAnswers,
   validateFormSchema: () => validateFormSchema,
+  validatePageAnswers: () => validatePageAnswers,
   validateSchemaStructure: () => validateSchemaStructure
 });
 module.exports = __toCommonJS(index_exports);
@@ -126,17 +133,46 @@ function validateSchemaStructure(schema) {
 function sanitizeSchema(schema) {
   const existingQuestionIds = new Set(schema.fields.map((field) => field.id));
   const cyclic = cyclicQuestionIds(schema.fields);
-  return {
+  const sanitizedFields = schema.fields.map((field) => {
+    const sourceId = field.displayCondition?.questionId;
+    if (sourceId === void 0 || existingQuestionIds.has(sourceId) && sourceId !== field.id && !cyclic.has(field.id)) {
+      return field;
+    }
+    const { displayCondition: _displayCondition, ...sanitized } = field;
+    return sanitized;
+  });
+  const base = {
     ...schema,
-    fields: schema.fields.map((field) => {
-      const sourceId = field.displayCondition?.questionId;
-      if (sourceId === void 0 || existingQuestionIds.has(sourceId) && sourceId !== field.id && !cyclic.has(field.id)) {
-        return field;
-      }
-      const { displayCondition: _displayCondition, ...sanitized } = field;
-      return sanitized;
-    })
+    fields: sanitizedFields
   };
+  if (schema.pages === void 0) return base;
+  const assigned = /* @__PURE__ */ new Set();
+  const pages = schema.pages.map((page) => ({
+    ...page,
+    questionIds: page.questionIds.filter((id) => {
+      if (!existingQuestionIds.has(id) || assigned.has(id)) return false;
+      assigned.add(id);
+      return true;
+    })
+  })).filter((page) => page.questionIds.length > 0);
+  if (pages.length === 0) {
+    const { pages: _pages, ...singlePage } = base;
+    return singlePage;
+  }
+  const unassigned = schema.fields.map((field) => field.id).filter((id) => !assigned.has(id));
+  const completePages = pages.map(
+    (page, index) => index === pages.length - 1 ? { ...page, questionIds: [...page.questionIds, ...unassigned] } : page
+  );
+  const pageIndexByQuestion = new Map(
+    completePages.flatMap((page, pageIndex) => page.questionIds.map((id) => [id, pageIndex]))
+  );
+  const safePages = completePages.map((page, pageIndex) => {
+    const sourceIndex = page.displayCondition === void 0 ? void 0 : pageIndexByQuestion.get(page.displayCondition.questionId);
+    if (page.displayCondition === void 0 || sourceIndex !== void 0 && sourceIndex < pageIndex) return page;
+    const { displayCondition: _displayCondition, ...safePage } = page;
+    return safePage;
+  });
+  return { ...base, pages: safePages };
 }
 
 // src/schema.ts
@@ -151,6 +187,80 @@ function isNonEmptyString(value) {
 function issue(issues, path, code, message) {
   issues.push({ path, code, message });
 }
+function validateJsonValue(value, path, issues, ancestors = /* @__PURE__ */ new Set()) {
+  if (value === null || typeof value === "string" || typeof value === "boolean") return;
+  if (typeof value === "number") {
+    if (!Number.isFinite(value)) issue(issues, path, "invalid_metadata", "Metadata numbers must be finite.");
+    return;
+  }
+  if (typeof value !== "object") {
+    issue(issues, path, "invalid_metadata", "Expected JSON-serializable metadata.");
+    return;
+  }
+  if (ancestors.has(value)) {
+    issue(issues, path, "invalid_metadata", "Metadata must not contain cycles.");
+    return;
+  }
+  const nextAncestors = new Set(ancestors).add(value);
+  if (Array.isArray(value)) {
+    value.forEach((item, index) => {
+      validateJsonValue(item, `${path}[${index}]`, issues, nextAncestors);
+    });
+    return;
+  }
+  const prototype = Object.getPrototypeOf(value);
+  if (prototype !== Object.prototype && prototype !== null) {
+    issue(issues, path, "invalid_metadata", "Metadata objects must be plain JSON objects.");
+    return;
+  }
+  for (const [key, item] of Object.entries(value)) {
+    validateJsonValue(item, `${path}.${key}`, issues, nextAncestors);
+  }
+}
+function validateExtensibleNode(value, path, issues) {
+  for (const property of ["metadata", "translationMetadata"]) {
+    const candidate = value[property];
+    if (candidate === void 0) continue;
+    if (!isRecord(candidate)) {
+      issue(
+        issues,
+        path.length === 0 ? property : `${path}.${property}`,
+        "invalid_metadata",
+        "Expected a metadata object."
+      );
+      continue;
+    }
+    validateJsonValue(candidate, path.length === 0 ? property : `${path}.${property}`, issues);
+  }
+}
+function validateLocalizedTextMap(value, path, issues) {
+  if (!isRecord(value)) {
+    issue(issues, path, "invalid_translations", "Expected a locale-to-translation object.");
+    return;
+  }
+  for (const [locale, translation] of Object.entries(value)) {
+    if (!isNonEmptyString(locale) || !isRecord(translation)) {
+      issue(issues, `${path}.${locale}`, "invalid_translation", "Expected a translation object.");
+      continue;
+    }
+    for (const key of ["title", "description", "completionMessage"]) {
+      if (translation[key] !== void 0 && !isNonEmptyString(translation[key])) {
+        issue(issues, `${path}.${locale}.${key}`, "invalid_translation", "Expected non-empty translated text.");
+      }
+    }
+  }
+}
+function validateOptionTranslations(value, path, issues) {
+  if (!isRecord(value)) {
+    issue(issues, path, "invalid_translations", "Expected a locale-to-label object.");
+    return;
+  }
+  for (const [locale, label] of Object.entries(value)) {
+    if (!isNonEmptyString(locale) || !isNonEmptyString(label)) {
+      issue(issues, `${path}.${locale}`, "invalid_translation", "Expected a non-empty translated label.");
+    }
+  }
+}
 function rejectLegacyProperties(value, path, properties, issues) {
   for (const property of properties) {
     if (Object.hasOwn(value, property)) {
@@ -184,6 +294,7 @@ function validateOptions(value, path, issues) {
       return;
     }
     rejectLegacyProperties(option, optionPath, ["value", "labelKey"], issues);
+    validateExtensibleNode(option, optionPath, issues);
     if (!isNonEmptyString(option.id)) {
       issue(issues, `${optionPath}.id`, "invalid_option_id", "Expected a non-empty option ID.");
     } else if (seen.has(option.id)) {
@@ -194,6 +305,8 @@ function validateOptions(value, path, issues) {
     if (!isNonEmptyString(option.label)) {
       issue(issues, `${optionPath}.label`, "invalid_label", "Expected a non-empty option label.");
     }
+    if (option.translations !== void 0)
+      validateOptionTranslations(option.translations, `${optionPath}.translations`, issues);
   });
   return true;
 }
@@ -227,6 +340,7 @@ function validateField(value, path, issues) {
     return false;
   }
   rejectLegacyProperties(value, path, ["titleKey", "labelKey", "helpTextKey", "descriptionKey"], issues);
+  validateExtensibleNode(value, path, issues);
   if (!isNonEmptyString(value.id)) issue(issues, `${path}.id`, "invalid_id", "Expected a non-empty ID.");
   if (!isNonEmptyString(value.title)) {
     issue(issues, `${path}.title`, "invalid_title", "Expected a non-empty question title.");
@@ -243,6 +357,7 @@ function validateField(value, path, issues) {
   if (value.displayCondition !== void 0) {
     validateDisplayCondition(value.displayCondition, `${path}.displayCondition`, issues);
   }
+  if (value.translations !== void 0) validateLocalizedTextMap(value.translations, `${path}.translations`, issues);
   if (typeof value.type !== "string" || !FIELD_TYPES.has(value.type)) {
     issue(issues, `${path}.type`, "invalid_field_type", "Unsupported field type.");
     return false;
@@ -311,6 +426,7 @@ function validateFormSchema(input) {
     return { valid: false, issues: [{ path: "$", code: "invalid_schema", message: "Expected a schema object." }] };
   }
   rejectLegacyProperties(input, "", ["titleKey", "descriptionKey"], issues);
+  validateExtensibleNode(input, "", issues);
   if (!isNonEmptyString(input.id)) issue(issues, "id", "invalid_id", "Expected a non-empty ID.");
   if (!Number.isInteger(input.version) || input.version < 1) {
     issue(issues, "version", "invalid_version", "Expected a positive integer version.");
@@ -318,16 +434,36 @@ function validateFormSchema(input) {
   if (!isNonEmptyString(input.title)) {
     issue(issues, "title", "invalid_title", "Expected a non-empty form title.");
   }
-  for (const key of ["description", "submitLabelKey"]) {
+  for (const key of ["description", "completionMessage", "submitLabelKey"]) {
     if (input[key] !== void 0 && !isNonEmptyString(input[key])) {
       issue(
         issues,
         key,
-        key === "description" ? "invalid_description" : "invalid_translation_key",
-        key === "description" ? "Expected a non-empty form description." : "Expected a translation key."
+        key === "submitLabelKey" ? "invalid_translation_key" : "invalid_description",
+        key === "submitLabelKey" ? "Expected a translation key." : "Expected non-empty form text."
       );
     }
   }
+  if (input.defaultLocale !== void 0 && !isNonEmptyString(input.defaultLocale)) {
+    issue(issues, "defaultLocale", "invalid_locale", "Expected a non-empty default locale.");
+  }
+  if (input.supportedLocales !== void 0) {
+    if (!Array.isArray(input.supportedLocales) || input.supportedLocales.length === 0) {
+      issue(issues, "supportedLocales", "invalid_locales", "Expected at least one supported locale.");
+    } else {
+      const locales = /* @__PURE__ */ new Set();
+      input.supportedLocales.forEach((locale, index) => {
+        if (!isNonEmptyString(locale)) {
+          issue(issues, `supportedLocales[${index}]`, "invalid_locale", "Expected a non-empty locale.");
+        } else if (locales.has(locale)) {
+          issue(issues, `supportedLocales[${index}]`, "duplicate_locale", "Locales must be unique.");
+        } else {
+          locales.add(locale);
+        }
+      });
+    }
+  }
+  if (input.translations !== void 0) validateLocalizedTextMap(input.translations, "translations", issues);
   if (!Array.isArray(input.fields) || input.fields.length === 0) {
     issue(issues, "fields", "invalid_fields", "Expected at least one field.");
   } else {
@@ -354,6 +490,81 @@ function validateFormSchema(input) {
       const code = structuralIssue.type === "dangling_condition_reference" ? "unknown_condition_source" : structuralIssue.type === "self_condition_reference" ? "self_condition" : "condition_cycle";
       issue(issues, `fields[${fieldIndex}].displayCondition`, code, structuralIssue.message);
     }
+    if (input.pages !== void 0) {
+      if (!Array.isArray(input.pages) || input.pages.length === 0) {
+        issue(issues, "pages", "invalid_pages", "Expected at least one page when pages is defined.");
+      } else {
+        const pageIds = /* @__PURE__ */ new Set();
+        const assigned = /* @__PURE__ */ new Map();
+        input.pages.forEach((page, pageIndex) => {
+          const pagePath = `pages[${pageIndex}]`;
+          if (!isRecord(page)) {
+            issue(issues, pagePath, "invalid_page", "Expected a page object.");
+            return;
+          }
+          validateExtensibleNode(page, pagePath, issues);
+          if (!isNonEmptyString(page.id)) {
+            issue(issues, `${pagePath}.id`, "invalid_page_id", "Expected a non-empty page ID.");
+          } else if (pageIds.has(page.id)) {
+            issue(issues, `${pagePath}.id`, "duplicate_page", "Page IDs must be unique.");
+          } else {
+            pageIds.add(page.id);
+          }
+          for (const key of ["title", "description"]) {
+            if (page[key] !== void 0 && !isNonEmptyString(page[key])) {
+              issue(issues, `${pagePath}.${key}`, "invalid_page_text", "Expected non-empty page text.");
+            }
+          }
+          if (page.translations !== void 0) {
+            validateLocalizedTextMap(page.translations, `${pagePath}.translations`, issues);
+          }
+          if (page.displayCondition !== void 0) {
+            validateDisplayCondition(page.displayCondition, `${pagePath}.displayCondition`, issues);
+          }
+          if (!Array.isArray(page.questionIds) || page.questionIds.length === 0) {
+            issue(issues, `${pagePath}.questionIds`, "invalid_page_questions", "Expected at least one question ID.");
+            return;
+          }
+          page.questionIds.forEach((questionId, questionIndex) => {
+            const questionPath = `${pagePath}.questionIds[${questionIndex}]`;
+            if (!isNonEmptyString(questionId)) {
+              issue(issues, questionPath, "invalid_question_reference", "Expected a question ID.");
+            } else if (!ids.has(questionId)) {
+              issue(issues, questionPath, "unknown_page_question", "Page references an unknown question.");
+            } else if (assigned.has(questionId)) {
+              issue(issues, questionPath, "duplicate_page_question", "A question may belong to only one page.");
+            } else {
+              assigned.set(questionId, pageIndex);
+            }
+          });
+        });
+        for (const fieldId of ids) {
+          if (!assigned.has(fieldId))
+            issue(issues, "pages", "unassigned_page_question", `Question ${fieldId} has no page.`);
+        }
+        input.pages.forEach((page, pageIndex) => {
+          if (!isRecord(page) || !isRecord(page.displayCondition)) return;
+          const sourceId = page.displayCondition.questionId;
+          if (typeof sourceId !== "string") return;
+          const sourcePageIndex = assigned.get(sourceId);
+          if (sourcePageIndex === void 0) {
+            issue(
+              issues,
+              `pages[${pageIndex}].displayCondition.questionId`,
+              "unknown_page_condition_source",
+              "Page condition references an unknown question."
+            );
+          } else if (sourcePageIndex >= pageIndex) {
+            issue(
+              issues,
+              `pages[${pageIndex}].displayCondition.questionId`,
+              "forward_page_condition",
+              "Page conditions must reference a question on an earlier page."
+            );
+          }
+        });
+      }
+    }
   }
   return issues.length === 0 ? { valid: true, value: input, issues: [] } : { valid: false, issues };
 }
@@ -381,7 +592,9 @@ function valuesEqual(left, right) {
   return typeof left === "string" && typeof right === "string" ? normalizeString(left) === normalizeString(right) : left === right;
 }
 function isQuestionVisible(question, currentAnswers) {
-  const condition = question.displayCondition;
+  return isDisplayConditionSatisfied(question.displayCondition, currentAnswers);
+}
+function isDisplayConditionSatisfied(condition, currentAnswers) {
   if (condition === void 0) return true;
   const answer = currentAnswers[condition.questionId];
   if (isEmpty(answer)) return false;
@@ -394,7 +607,7 @@ function isQuestionVisible(question, currentAnswers) {
   }
   return Array.isArray(answer) && answer.some((item) => valuesEqual(item, condition.value));
 }
-function calculateFieldVisibility(schema, currentAnswers) {
+function calculateBaseFieldVisibility(schema, currentAnswers) {
   const fields = new Map(schema.fields.map((field) => [field.id, field]));
   const resolved = /* @__PURE__ */ new Map();
   const resolving = /* @__PURE__ */ new Set();
@@ -412,7 +625,34 @@ function calculateFieldVisibility(schema, currentAnswers) {
     return visible;
   };
   for (const field of schema.fields) resolve(field);
-  return Object.freeze(Object.fromEntries(resolved));
+  return Object.fromEntries(resolved);
+}
+function calculatePageVisibility(schema, currentAnswers) {
+  if (schema.pages === void 0 || schema.pages.length === 0) return {};
+  const baseFieldVisibility = calculateBaseFieldVisibility(schema, currentAnswers);
+  const pageByQuestion = new Map(schema.pages.flatMap((page) => page.questionIds.map((id) => [id, page.id])));
+  const pageVisibility = {};
+  for (const page of schema.pages) {
+    const sourceId = page.displayCondition?.questionId;
+    const sourcePageId = sourceId === void 0 ? void 0 : pageByQuestion.get(sourceId);
+    const sourceVisible = sourceId === void 0 || baseFieldVisibility[sourceId] === true && sourcePageId !== void 0 && pageVisibility[sourcePageId] === true;
+    pageVisibility[page.id] = sourceVisible && isDisplayConditionSatisfied(page.displayCondition, currentAnswers);
+  }
+  return Object.freeze(pageVisibility);
+}
+function calculateFieldVisibility(schema, currentAnswers) {
+  const baseVisibility = calculateBaseFieldVisibility(schema, currentAnswers);
+  if (schema.pages === void 0 || schema.pages.length === 0) return Object.freeze(baseVisibility);
+  const pageVisibility = calculatePageVisibility(schema, currentAnswers);
+  const pageByQuestion = new Map(schema.pages.flatMap((page) => page.questionIds.map((id) => [id, page.id])));
+  return Object.freeze(
+    Object.fromEntries(
+      schema.fields.map((field) => {
+        const pageId = pageByQuestion.get(field.id);
+        return [field.id, baseVisibility[field.id] === true && pageId !== void 0 && pageVisibility[pageId] === true];
+      })
+    )
+  );
 }
 function selectVisibleAnswers(schema, currentAnswers) {
   const visibility = calculateFieldVisibility(schema, currentAnswers);
@@ -446,6 +686,23 @@ function calculateNumericSummary(responses, questionId) {
     max: numbers.length === 0 ? null : Math.max(...numbers)
   };
 }
+function calculateCrossTabulation(responses, rowQuestionId, colQuestionId) {
+  const matrix = {};
+  const rowTotals = {};
+  const colTotals = {};
+  let grandTotal = 0;
+  for (const response of responses) {
+    const row = response.values[rowQuestionId];
+    const col = response.values[colQuestionId];
+    if (typeof row !== "string" || row.length === 0 || typeof col !== "string" || col.length === 0) continue;
+    matrix[row] ??= {};
+    matrix[row][col] = (matrix[row][col] ?? 0) + 1;
+    rowTotals[row] = (rowTotals[row] ?? 0) + 1;
+    colTotals[col] = (colTotals[col] ?? 0) + 1;
+    grandTotal += 1;
+  }
+  return { rowQuestionId, colQuestionId, matrix, rowTotals, colTotals, grandTotal };
+}
 function valueIsValid(field, value) {
   if (value === void 0 || value === "") return false;
   if (field.type === "text" || field.type === "textarea") {
@@ -537,15 +794,20 @@ function aggregateResponses(schema, submissions) {
     questions: schema.fields.map((field) => aggregateField(schema, field, submissions))
   };
 }
-function escapeCsvCell(value) {
+function escapeCsvCell(value, neutralizeFormulas = true) {
   if (value === null || value === void 0) return "";
-  const stringValue = String(value);
+  let stringValue = String(value);
+  if (neutralizeFormulas && typeof value === "string") {
+    const trimmed = stringValue.trimStart();
+    if (trimmed.length > 0 && ["=", "+", "-", "@"].includes(trimmed[0] ?? "")) {
+      stringValue = `'${stringValue}`;
+    }
+  }
   return /[",\r\n]/.test(stringValue) ? `"${stringValue.replaceAll('"', '""')}"` : stringValue;
 }
 function serializeValue(value) {
   if (value === void 0) return "";
-  if (Array.isArray(value)) return JSON.stringify(value);
-  return String(value);
+  return typeof value === "string" || typeof value === "number" || typeof value === "boolean" ? value : JSON.stringify(value);
 }
 function exportResponsesToCsv(schema, responses, options = {}) {
   assertValidFormSchema(schema);
@@ -566,10 +828,52 @@ function exportResponsesToCsv(schema, responses, options = {}) {
       ];
     })
   ];
-  const csv = rows.map((row) => row.map((cell) => escapeCsvCell(cell)).join(",")).join("\r\n");
+  const neutralizeFormulas = options.neutralizeFormulas ?? true;
+  const csv = rows.map((row) => row.map((cell) => escapeCsvCell(cell, neutralizeFormulas)).join(",")).join("\r\n");
   return options.withBom ?? true ? `\uFEFF${csv}` : csv;
 }
 
+// src/events.ts
+function bytesToHex(bytes) {
+  return [...new Uint8Array(bytes)].map((byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+async function signPayload(payload, secret) {
+  if (globalThis.crypto?.subtle === void 0) throw new Error("Web Crypto is unavailable for webhook signing.");
+  const encoder = new TextEncoder();
+  const key = await globalThis.crypto.subtle.importKey(
+    "raw",
+    encoder.encode(secret),
+    { name: "HMAC", hash: "SHA-256" },
+    false,
+    ["sign"]
+  );
+  return bytesToHex(await globalThis.crypto.subtle.sign("HMAC", key, encoder.encode(payload)));
+}
+async function dispatchWebhook(event, config, fetchImpl = globalThis.fetch) {
+  const body = JSON.stringify(event);
+  const controller = new AbortController();
+  const timeoutMs = config.timeoutMs ?? 5e3;
+  const timeout = globalThis.setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    const headers = { "content-type": "application/json", ...config.headers };
+    if (config.secret !== void 0) {
+      headers["X-Form-Engine-Signature"] = await signPayload(body, config.secret);
+    }
+    const response = await fetchImpl(config.url, {
+      method: "POST",
+      headers,
+      body,
+      signal: controller.signal
+    });
+    return response.ok ? { success: true, status: response.status } : { success: false, status: response.status, error: `Webhook returned HTTP ${response.status}.` };
+  } catch (cause) {
+    const error = controller.signal.aborted ? `Webhook request timed out after ${timeoutMs}ms.` : cause instanceof Error ? cause.message : String(cause);
+    return { success: false, error };
+  } finally {
+    globalThis.clearTimeout(timeout);
+  }
+}
+
 // src/validation.ts
 var DEFAULT_MESSAGES = {
   required: "validation.required",
@@ -696,6 +1000,18 @@ function validateAnswers(schema, values) {
   }
   return issues.length === 0 ? { valid: true, issues: [] } : { valid: false, issues };
 }
+function validatePageAnswers(schema, pageIndex, values) {
+  if (schema.pages === void 0 || schema.pages.length === 0) return validateAnswers(schema, values);
+  const page = schema.pages[pageIndex];
+  if (page === void 0) return { valid: true, issues: [] };
+  const targetIds = new Set(page.questionIds);
+  const visibility = calculateFieldVisibility(schema, values);
+  const issues = [];
+  for (const field of schema.fields) {
+    if (targetIds.has(field.id) && visibility[field.id] === true) validateField2(field, values[field.id], issues);
+  }
+  return issues.length === 0 ? { valid: true, issues: [] } : { valid: false, issues };
+}
 
 // src/submission.ts
 function cloneValues(values) {
@@ -723,68 +1039,281 @@ function createSubmission(schema, values, options) {
     formVersion: schema.version,
     locale: options.locale,
     values: Object.freeze(cloneValues(visibleValues)),
-    submittedAt: options.submittedAt
+    submittedAt: options.submittedAt,
+    ...options.metadata === void 0 ? {} : { metadata: Object.freeze({ ...options.metadata }) },
+    ...options.translationMetadata === void 0 ? {} : { translationMetadata: Object.freeze({ ...options.translationMetadata }) }
   });
 }
 
 // src/translation.ts
-async function resolveFormTranslation(schema, adapter, targetLocale, sourceLocale) {
-  assertValidFormSchema(schema);
-  const texts = [schema.title];
-  if (schema.description !== void 0) texts.push(schema.description);
-  for (const field of schema.fields) {
-    texts.push(field.title);
-    if (field.description !== void 0) texts.push(field.description);
-    if ("options" in field) texts.push(...field.options.map((option) => option.label));
-  }
-  const translated = await adapter.translateBatch(texts, targetLocale, sourceLocale);
-  if (translated.length !== texts.length) {
-    throw new Error(`Translation adapter returned ${translated.length} texts for ${texts.length} inputs.`);
-  }
-  let index = 0;
-  const next = () => {
-    const value = translated[index];
-    index += 1;
-    if (value === void 0) throw new Error("Translation adapter returned an incomplete result.");
-    return value;
+function mergeLocalizedText(translations, locale, property, value) {
+  return { ...translations, [locale]: { ...translations?.[locale], [property]: value } };
+}
+function withTranslationMetadata(node, locale, property, metadata) {
+  if (metadata === void 0) return node;
+  return {
+    ...node,
+    translationMetadata: {
+      ...node.translationMetadata,
+      [locale]: {
+        ...node.translationMetadata?.[locale],
+        [property]: metadata
+      }
+    }
   };
-  const title = next();
-  const description = schema.description === void 0 ? void 0 : next();
-  const fields = schema.fields.map((field) => {
-    const translatedTitle = next();
-    const translatedDescription = field.description === void 0 ? void 0 : next();
-    const base = {
-      ...field,
-      title: translatedTitle,
-      ...translatedDescription === void 0 ? {} : { description: translatedDescription }
+}
+function createSlot(kind, nodeId, property, locale, sourceText, existingText, metadata) {
+  return {
+    kind,
+    nodeId,
+    property,
+    locale,
+    sourceText,
+    ...existingText === void 0 ? {} : { existingText },
+    ...metadata === void 0 ? {} : { metadata }
+  };
+}
+function translationSlots(schema, locale) {
+  const descriptors = [];
+  const addFormSlot = (property, sourceText) => {
+    const slot = createSlot(
+      "form",
+      schema.id,
+      property,
+      locale,
+      sourceText,
+      schema.translations?.[locale]?.[property],
+      schema.metadata
+    );
+    descriptors.push({
+      slot,
+      apply: (current, value, metadata) => withTranslationMetadata(
+        { ...current, translations: mergeLocalizedText(current.translations, locale, property, value) },
+        locale,
+        property,
+        metadata
+      )
+    });
+  };
+  addFormSlot("title", schema.title);
+  if (schema.description !== void 0) addFormSlot("description", schema.description);
+  if (schema.completionMessage !== void 0) addFormSlot("completionMessage", schema.completionMessage);
+  schema.fields.forEach((field, fieldIndex) => {
+    const addFieldSlot = (property, sourceText) => {
+      const slot = createSlot(
+        "field",
+        field.id,
+        property,
+        locale,
+        sourceText,
+        field.translations?.[locale]?.[property],
+        field.metadata
+      );
+      descriptors.push({
+        slot,
+        apply: (current, value, metadata) => ({
+          ...current,
+          fields: current.fields.map(
+            (candidate, index) => index === fieldIndex ? withTranslationMetadata(
+              {
+                ...candidate,
+                translations: mergeLocalizedText(candidate.translations, locale, property, value)
+              },
+              locale,
+              property,
+              metadata
+            ) : candidate
+          )
+        })
+      });
+    };
+    addFieldSlot("title", field.title);
+    if (field.description !== void 0) addFieldSlot("description", field.description);
+    if ("options" in field) {
+      field.options.forEach((option, optionIndex) => {
+        const slot = createSlot(
+          "option",
+          option.id,
+          "label",
+          locale,
+          option.label,
+          option.translations?.[locale],
+          option.metadata
+        );
+        descriptors.push({
+          slot,
+          apply: (current, value, metadata) => ({
+            ...current,
+            fields: current.fields.map((candidate, candidateIndex) => {
+              if (candidateIndex !== fieldIndex || !("options" in candidate)) return candidate;
+              return {
+                ...candidate,
+                options: candidate.options.map(
+                  (candidateOption, candidateOptionIndex) => candidateOptionIndex === optionIndex ? withTranslationMetadata(
+                    {
+                      ...candidateOption,
+                      translations: { ...candidateOption.translations, [locale]: value }
+                    },
+                    locale,
+                    "label",
+                    metadata
+                  ) : candidateOption
+                )
+              };
+            })
+          })
+        });
+      });
+    }
+  });
+  schema.pages?.forEach((page, pageIndex) => {
+    const addPageSlot = (property, sourceText) => {
+      const slot = createSlot(
+        "page",
+        page.id,
+        property,
+        locale,
+        sourceText,
+        page.translations?.[locale]?.[property],
+        page.metadata
+      );
+      descriptors.push({
+        slot,
+        apply: (current, value, metadata) => ({
+          ...current,
+          ...current.pages === void 0 ? {} : {
+            pages: current.pages.map(
+              (candidate, index) => index === pageIndex ? withTranslationMetadata(
+                {
+                  ...candidate,
+                  translations: mergeLocalizedText(candidate.translations, locale, property, value)
+                },
+                locale,
+                property,
+                metadata
+              ) : candidate
+            )
+          }
+        })
+      });
     };
-    if (!("options" in field)) return base;
-    return { ...base, options: field.options.map((option) => ({ ...option, label: next() })) };
+    if (page.title !== void 0) addPageSlot("title", page.title);
+    if (page.description !== void 0) addPageSlot("description", page.description);
   });
-  const translatedSchema = {
+  return descriptors;
+}
+function resolveLocalizedSchema(schema, targetLocale) {
+  if (targetLocale.length === 0 || targetLocale === schema.defaultLocale) return schema;
+  const formTranslation = schema.translations?.[targetLocale];
+  const completionMessage = formTranslation?.completionMessage ?? schema.completionMessage;
+  return {
     ...schema,
-    title,
-    ...description === void 0 ? {} : { description },
-    fields
+    title: formTranslation?.title ?? schema.title,
+    ...(formTranslation?.description ?? schema.description) === void 0 ? {} : { description: formTranslation?.description ?? schema.description },
+    ...completionMessage === void 0 ? {} : { completionMessage },
+    fields: schema.fields.map((field) => {
+      const translation = field.translations?.[targetLocale];
+      const localized = {
+        ...field,
+        title: translation?.title ?? field.title,
+        ...(translation?.description ?? field.description) === void 0 ? {} : { description: translation?.description ?? field.description }
+      };
+      if (!("options" in field)) return localized;
+      return {
+        ...localized,
+        options: field.options.map((option) => ({
+          ...option,
+          label: option.translations?.[targetLocale] ?? option.label
+        }))
+      };
+    }),
+    ...schema.pages === void 0 ? {} : {
+      pages: schema.pages.map((page) => {
+        const translation = page.translations?.[targetLocale];
+        const title = translation?.title ?? page.title;
+        const description = translation?.description ?? page.description;
+        return {
+          ...page,
+          ...title === void 0 ? {} : { title },
+          ...description === void 0 ? {} : { description }
+        };
+      })
+    }
   };
-  assertValidFormSchema(translatedSchema);
-  return translatedSchema;
+}
+async function populateSchemaTranslations(schema, targetLocales, adapter, options = {}) {
+  assertValidFormSchema(schema);
+  const locales = [...new Set(targetLocales.filter((locale) => locale.length > 0 && locale !== schema.defaultLocale))];
+  const updatedSlots = [];
+  const skippedSlots = [];
+  let result = schema;
+  for (const locale of locales) {
+    const descriptors = translationSlots(schema, locale);
+    const selected = [];
+    for (const descriptor of descriptors) {
+      const shouldTranslate = options.shouldOverwrite?.(descriptor.slot) ?? (options.overwrite === "all" || descriptor.slot.existingText === void 0);
+      if (shouldTranslate) selected.push(descriptor);
+      else skippedSlots.push(descriptor.slot);
+    }
+    if (selected.length === 0) continue;
+    const translated = await adapter.translateBatch(
+      selected.map((descriptor) => descriptor.slot.sourceText),
+      locale,
+      schema.defaultLocale
+    );
+    if (translated.length !== selected.length) {
+      throw new Error(`Translation adapter returned ${translated.length} texts for ${selected.length} inputs.`);
+    }
+    selected.forEach((descriptor, index) => {
+      const translatedText = translated[index];
+      if (translatedText === void 0) throw new Error("Translation adapter returned an unexpected result.");
+      const metadata = options.createMetadata?.(descriptor.slot, translatedText);
+      result = descriptor.apply(result, translatedText, metadata);
+      updatedSlots.push(descriptor.slot);
+    });
+  }
+  const supportedLocales = [
+    .../* @__PURE__ */ new Set([
+      ...schema.defaultLocale === void 0 ? [] : [schema.defaultLocale],
+      ...schema.supportedLocales ?? [],
+      ...locales
+    ])
+  ];
+  if (supportedLocales.length > 0) result = { ...result, supportedLocales };
+  assertValidFormSchema(result);
+  return { schema: result, report: { updatedSlots, skippedSlots } };
+}
+async function resolveFormTranslation(schema, adapter, targetLocale, sourceLocale) {
+  const populated = await populateSchemaTranslations(
+    sourceLocale === void 0 ? schema : { ...schema, defaultLocale: sourceLocale },
+    [targetLocale],
+    adapter,
+    { overwrite: "all" }
+  );
+  return resolveLocalizedSchema(populated.schema, targetLocale);
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   aggregateResponses,
   assertValidFormSchema,
   calculateChoiceDistribution,
+  calculateCrossTabulation,
   calculateFieldVisibility,
   calculateNumericSummary,
+  calculatePageVisibility,
   createSubmission,
+  dispatchWebhook,
   escapeCsvCell,
   exportResponsesToCsv,
+  isDisplayConditionSatisfied,
   isQuestionVisible,
+  populateSchemaTranslations,
   resolveFormTranslation,
+  resolveLocalizedSchema,
   sanitizeSchema,
   selectVisibleAnswers,
   validateAnswers,
   validateFormSchema,
+  validatePageAnswers,
   validateSchemaStructure
 });