@form-engine-ts/core 1.1.0 → 2.0.0

package/README.md

@@ -30,11 +30,20 @@ Add `pages` to partition every field into an accessible wizard and use `validate
 for step-scoped validation. Schemas without `pages` remain single-page forms.
 
 Store authoring-time translations on forms, fields, options, and pages. `resolveLocalizedSchema` applies them synchronously,
-while `populateSchemaTranslations` fills them through an injected `AsyncTranslationAdapter`.
+while `populateSchemaTranslations` fills them through an injected `AsyncTranslationAdapter`. Population defaults to
+`overwrite: "missing-only"`, accepts per-slot `shouldOverwrite` and `createMetadata` callbacks, and returns
+`{ schema, report }` with updated and skipped translation slots.
+
+Forms, pages, fields, options, and submissions accept JSON-only `metadata` and per-locale/property
+`translationMetadata`. These extension values survive sanitization, localization, submission creation, and storage
+round-trips. `completionMessage` is localized with the rest of the form text.
 
 `calculateCrossTabulation` builds a two-question frequency matrix from submissions. `dispatchWebhook` posts typed
 `response.submitted` or `schema.updated` events with timeout handling, custom headers, and optional HMAC-SHA256 signing.
 
+CSV export neutralizes string cells whose first non-whitespace character is `=`, `+`, `-`, or `@`. This is enabled by
+default; trusted callers can pass `{ neutralizeFormulas: false }`. RFC 4180 quoting and the UTF-8 BOM remain unchanged.
+
 Storage adapters share inclusive ISO 8601 submission-range filtering:
 
 ```ts

package/dist/index.cjs

@@ -187,6 +187,52 @@ 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.");
@@ -197,7 +243,7 @@ function validateLocalizedTextMap(value, path, issues) {
       issue(issues, `${path}.${locale}`, "invalid_translation", "Expected a translation object.");
       continue;
     }
-    for (const key of ["title", "description"]) {
+    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.");
       }
@@ -248,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)) {
@@ -293,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.");
@@ -378,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.");
@@ -385,13 +434,13 @@ 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."
       );
     }
   }
@@ -453,6 +502,7 @@ function validateFormSchema(input) {
             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)) {
@@ -744,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);
@@ -773,7 +828,8 @@ 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;
 }
 
@@ -983,69 +1039,125 @@ 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
-function mergeLocalizedText(translations, locale, key, value) {
-  return { ...translations, [locale]: { ...translations?.[locale], [key]: value } };
+function mergeLocalizedText(translations, locale, property, value) {
+  return { ...translations, [locale]: { ...translations?.[locale], [property]: value } };
 }
-function translationSlots(schema) {
-  const slots = [
-    {
-      text: schema.title,
-      apply: (current, value, locale) => ({
-        ...current,
-        translations: mergeLocalizedText(current.translations, locale, "title", value)
-      })
+function withTranslationMetadata(node, locale, property, metadata) {
+  if (metadata === void 0) return node;
+  return {
+    ...node,
+    translationMetadata: {
+      ...node.translationMetadata,
+      [locale]: {
+        ...node.translationMetadata?.[locale],
+        [property]: metadata
+      }
     }
-  ];
-  if (schema.description !== void 0) {
-    slots.push({
-      text: schema.description,
-      apply: (current, value, locale) => ({
-        ...current,
-        translations: mergeLocalizedText(current.translations, locale, "description", value)
-      })
+  };
+}
+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) => {
-    slots.push({
-      text: field.title,
-      apply: (current, value, locale) => ({
-        ...current,
-        fields: current.fields.map(
-          (item, index) => index === fieldIndex ? { ...item, translations: mergeLocalizedText(item.translations, locale, "title", value) } : item
-        )
-      })
-    });
-    if (field.description !== void 0) {
-      slots.push({
-        text: field.description,
-        apply: (current, value, locale) => ({
+    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(
-            (item, index) => index === fieldIndex ? {
-              ...item,
-              translations: mergeLocalizedText(item.translations, locale, "description", value)
-            } : item
+            (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) => {
-        slots.push({
-          text: option.label,
-          apply: (current, value, locale) => ({
+        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((item, index) => {
-              if (index !== fieldIndex || !("options" in item)) return item;
+            fields: current.fields.map((candidate, candidateIndex) => {
+              if (candidateIndex !== fieldIndex || !("options" in candidate)) return candidate;
               return {
-                ...item,
-                options: item.options.map(
-                  (candidate, candidateIndex) => candidateIndex === optionIndex ? { ...candidate, translations: { ...candidate.translations, [locale]: value } } : candidate
+                ...candidate,
+                options: candidate.options.map(
+                  (candidateOption, candidateOptionIndex) => candidateOptionIndex === optionIndex ? withTranslationMetadata(
+                    {
+                      ...candidateOption,
+                      translations: { ...candidateOption.translations, [locale]: value }
+                    },
+                    locale,
+                    "label",
+                    metadata
+                  ) : candidateOption
                 )
               };
             })
@@ -1055,42 +1167,50 @@ function translationSlots(schema) {
     }
   });
   schema.pages?.forEach((page, pageIndex) => {
-    if (page.title !== void 0) {
-      slots.push({
-        text: page.title,
-        apply: (current, value, locale) => ({
-          ...current,
-          ...current.pages === void 0 ? {} : {
-            pages: current.pages.map(
-              (item, index) => index === pageIndex ? { ...item, translations: mergeLocalizedText(item.translations, locale, "title", value) } : item
-            )
-          }
-        })
-      });
-    }
-    if (page.description !== void 0) {
-      slots.push({
-        text: page.description,
-        apply: (current, value, locale) => ({
+    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(
-              (item, index) => index === pageIndex ? { ...item, translations: mergeLocalizedText(item.translations, locale, "description", value) } : item
+              (candidate, index) => index === pageIndex ? withTranslationMetadata(
+                {
+                  ...candidate,
+                  translations: mergeLocalizedText(candidate.translations, locale, property, value)
+                },
+                locale,
+                property,
+                metadata
+              ) : candidate
             )
           }
         })
       });
-    }
+    };
+    if (page.title !== void 0) addPageSlot("title", page.title);
+    if (page.description !== void 0) addPageSlot("description", page.description);
   });
-  return slots;
+  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: 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 = {
@@ -1121,24 +1241,35 @@ function resolveLocalizedSchema(schema, targetLocale) {
     }
   };
 }
-async function populateSchemaTranslations(schema, targetLocales, adapter) {
+async function populateSchemaTranslations(schema, targetLocales, adapter, options = {}) {
   assertValidFormSchema(schema);
-  const slots = translationSlots(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(
-      slots.map((slot) => slot.text),
+      selected.map((descriptor) => descriptor.slot.sourceText),
       locale,
       schema.defaultLocale
     );
-    if (translated.length !== slots.length) {
-      throw new Error(`Translation adapter returned ${translated.length} texts for ${slots.length} inputs.`);
+    if (translated.length !== selected.length) {
+      throw new Error(`Translation adapter returned ${translated.length} texts for ${selected.length} inputs.`);
     }
-    translated.forEach((value, index) => {
-      const slot = slots[index];
-      if (slot === void 0) throw new Error("Translation adapter returned an unexpected result.");
-      result = slot.apply(result, value, locale);
+    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 = [
@@ -1148,17 +1279,18 @@ async function populateSchemaTranslations(schema, targetLocales, adapter) {
       ...locales
     ])
   ];
-  result = supportedLocales.length === 0 ? result : { ...result, supportedLocales };
+  if (supportedLocales.length > 0) result = { ...result, supportedLocales };
   assertValidFormSchema(result);
-  return 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
+    adapter,
+    { overwrite: "all" }
   );
-  return resolveLocalizedSchema(populated, targetLocale);
+  return resolveLocalizedSchema(populated.schema, targetLocale);
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {

package/dist/index.d.cts

@@ -1,6 +1,15 @@
 type FieldType = "text" | "textarea" | "number" | "rating" | "select" | "multi-select" | "checkbox" | "radio";
 type ConditionOperator = "equals" | "not_equals" | "contains" | "not_empty";
 type ConditionValue = string | number | boolean;
+type JsonValue = string | number | boolean | null | readonly JsonValue[] | {
+    readonly [key: string]: JsonValue;
+};
+/** Arbitrary, JSON-serializable data preserved by every form-engine operation. */
+interface ExtensibleNode {
+    readonly metadata?: Readonly<Record<string, JsonValue>>;
+    /** Locale -> translated property -> metadata created for that translation. */
+    readonly translationMetadata?: Readonly<Record<string, Readonly<Record<string, Readonly<Record<string, JsonValue>>>>>>;
+}
 interface DisplayCondition {
     readonly questionId: string;
     readonly operator: ConditionOperator;
@@ -9,15 +18,16 @@ interface DisplayCondition {
 interface LocalizedText {
     readonly title?: string;
     readonly description?: string;
+    readonly completionMessage?: string;
 }
 type SchemaTranslations = Readonly<Record<string, LocalizedText>>;
 type ValidationCode = "required" | "invalid_type" | "min_length" | "max_length" | "pattern" | "min" | "max" | "step" | "invalid_option" | "min_selections" | "max_selections" | "unknown_field";
-interface FieldOption {
+interface FieldOption extends ExtensibleNode {
     readonly id: string;
     readonly label: string;
     readonly translations?: Readonly<Record<string, string>>;
 }
-interface BaseField {
+interface BaseField extends ExtensibleNode {
     readonly id: string;
     readonly type: FieldType;
     readonly title: string;
@@ -61,7 +71,7 @@ interface CheckboxField extends BaseField {
     readonly type: "checkbox";
 }
 type FormField = TextField | NumberField | RatingField | SelectField | MultiSelectField | CheckboxField;
-interface FormPage {
+interface FormPage extends ExtensibleNode {
     readonly id: string;
     readonly title?: string;
     readonly description?: string;
@@ -69,11 +79,12 @@ interface FormPage {
     readonly displayCondition?: DisplayCondition;
     readonly translations?: SchemaTranslations;
 }
-interface FormSchema {
+interface FormSchema extends ExtensibleNode {
     readonly id: string;
     readonly version: number;
     readonly title: string;
     readonly description?: string;
+    readonly completionMessage?: string;
     readonly submitLabelKey?: string;
     readonly defaultLocale?: string;
     readonly supportedLocales?: readonly string[];
@@ -102,6 +113,7 @@ interface ValidationIssue {
     readonly messageKey: string;
     readonly params: Readonly<Record<string, string | number>>;
 }
+type ValidationError = ValidationIssue;
 type AnswerValidationResult = {
     readonly valid: true;
     readonly issues: readonly [];
@@ -109,7 +121,7 @@ type AnswerValidationResult = {
     readonly valid: false;
     readonly issues: readonly ValidationIssue[];
 };
-interface FormSubmission {
+interface FormSubmission extends ExtensibleNode {
     readonly id: string;
     readonly formId: string;
     readonly formVersion: number;
@@ -182,7 +194,13 @@ interface FormAnalytics {
 type Question = FormField;
 type QuestionType = FieldType;
 type ChoiceOption = FieldOption;
-type FormResponse = FormSubmission;
+interface FormResponse extends ExtensibleNode {
+    readonly responseId: string;
+    readonly formId: string;
+    readonly sourceLocale?: string;
+    readonly answers: Readonly<Record<string, unknown>>;
+    readonly submittedAt: string;
+}
 interface CrossTabulationResult {
     readonly rowQuestionId: string;
     readonly colQuestionId: string;
@@ -206,9 +224,10 @@ declare function calculateChoiceDistribution(responses: readonly FormSubmission[
 declare function calculateNumericSummary(responses: readonly FormSubmission[], questionId: string): NumericSummary;
 declare function calculateCrossTabulation(responses: readonly FormSubmission[], rowQuestionId: string, colQuestionId: string): CrossTabulationResult;
 declare function aggregateResponses(schema: FormSchema, submissions: readonly FormSubmission[]): FormAnalytics;
-declare function escapeCsvCell(value: string | number | null | undefined): string;
+declare function escapeCsvCell(value: string | number | boolean | null | undefined, neutralizeFormulas?: boolean): string;
 interface CsvExportOptions {
     readonly withBom?: boolean;
+    readonly neutralizeFormulas?: boolean;
 }
 declare function exportResponsesToCsv(schema: FormSchema, responses: readonly FormSubmission[], options?: CsvExportOptions): string;
 
@@ -246,15 +265,36 @@ declare function sanitizeSchema(schema: FormSchema): FormSchema;
 declare function validateFormSchema(input: unknown): SchemaValidationResult;
 declare function assertValidFormSchema(input: unknown): asserts input is FormSchema;
 
-interface CreateSubmissionOptions {
+interface CreateSubmissionOptions extends ExtensibleNode {
     readonly id: string;
     readonly locale: string;
     readonly submittedAt: string;
 }
 declare function createSubmission(schema: FormSchema, values: FormValues, options: CreateSubmissionOptions): FormSubmission;
 
+interface TranslationSlot {
+    readonly kind: "form" | "page" | "field" | "option";
+    readonly nodeId: string;
+    readonly property: "title" | "description" | "label" | "completionMessage";
+    readonly locale: string;
+    readonly sourceText: string;
+    readonly existingText?: string;
+    readonly metadata?: Readonly<Record<string, JsonValue>>;
+}
+interface PopulateTranslationOptions {
+    readonly overwrite?: "missing-only" | "all";
+    readonly shouldOverwrite?: (slot: TranslationSlot) => boolean;
+    readonly createMetadata?: (slot: TranslationSlot, translatedText: string) => Readonly<Record<string, JsonValue>>;
+}
+interface TranslationReport {
+    readonly updatedSlots: readonly TranslationSlot[];
+    readonly skippedSlots: readonly TranslationSlot[];
+}
 declare function resolveLocalizedSchema(schema: FormSchema, targetLocale: string): FormSchema;
-declare function populateSchemaTranslations(schema: FormSchema, targetLocales: readonly string[], adapter: AsyncTranslationAdapter): Promise<FormSchema>;
+declare function populateSchemaTranslations(schema: FormSchema, targetLocales: readonly string[], adapter: AsyncTranslationAdapter, options?: PopulateTranslationOptions): Promise<{
+    readonly schema: FormSchema;
+    readonly report: TranslationReport;
+}>;
 declare function resolveFormTranslation(schema: FormSchema, adapter: AsyncTranslationAdapter, targetLocale: string, sourceLocale?: string): Promise<FormSchema>;
 
 declare function validateAnswers(schema: FormSchema, values: FormValues): AnswerValidationResult;
@@ -266,4 +306,4 @@ declare function calculatePageVisibility(schema: FormSchema, currentAnswers: Rea
 declare function calculateFieldVisibility(schema: FormSchema, currentAnswers: Readonly<Record<string, unknown>>): Readonly<Record<string, boolean>>;
 declare function selectVisibleAnswers(schema: FormSchema, currentAnswers: FormValues): FormValues;
 
-export { type AnswerValidationResult, type AsyncTranslationAdapter, type BaseField, type CheckboxField, type CheckboxQuestionAggregate, type ChoiceDistributionEntry, type ChoiceOption, type ChoiceQuestionAggregate, type ConditionOperator, type ConditionValue, type CreateSubmissionOptions, type CrossTabulationResult, type CsvExportOptions, type DisplayCondition, type FieldOption, type FieldType, type FormAnalytics, type FormEvent, type FormEventType, type FormField, type FormPage, type FormResponse, type FormSchema, type FormStorageAdapter, type FormSubmission, type FormValue, type FormValues, type LocalizedText, type MultiSelectField, type NumberField, type NumberQuestionAggregate, type NumericSummary, type OptionAggregate, type Question, type QuestionAggregate, type QuestionType, type RatingField, type SchemaIssue, type SchemaStructureIssue, type SchemaStructureIssueType, type SchemaTranslations, type SchemaValidationResult, type SelectField, type StorageAdapter, type SubmissionQueryOptions, type TextField, type TextQuestionAggregate, type TranslationAdapter, type ValidationCode, type ValidationIssue, type WebhookConfig, type WebhookDispatchResult, aggregateResponses, assertValidFormSchema, calculateChoiceDistribution, calculateCrossTabulation, calculateFieldVisibility, calculateNumericSummary, calculatePageVisibility, createSubmission, dispatchWebhook, escapeCsvCell, exportResponsesToCsv, isDisplayConditionSatisfied, isQuestionVisible, populateSchemaTranslations, resolveFormTranslation, resolveLocalizedSchema, sanitizeSchema, selectVisibleAnswers, validateAnswers, validateFormSchema, validatePageAnswers, validateSchemaStructure };
+export { type AnswerValidationResult, type AsyncTranslationAdapter, type BaseField, type CheckboxField, type CheckboxQuestionAggregate, type ChoiceDistributionEntry, type ChoiceOption, type ChoiceQuestionAggregate, type ConditionOperator, type ConditionValue, type CreateSubmissionOptions, type CrossTabulationResult, type CsvExportOptions, type DisplayCondition, type ExtensibleNode, type FieldOption, type FieldType, type FormAnalytics, type FormEvent, type FormEventType, type FormField, type FormPage, type FormResponse, type FormSchema, type FormStorageAdapter, type FormSubmission, type FormValue, type FormValues, type JsonValue, type LocalizedText, type MultiSelectField, type NumberField, type NumberQuestionAggregate, type NumericSummary, type OptionAggregate, type PopulateTranslationOptions, type Question, type QuestionAggregate, type QuestionType, type RatingField, type SchemaIssue, type SchemaStructureIssue, type SchemaStructureIssueType, type SchemaTranslations, type SchemaValidationResult, type SelectField, type StorageAdapter, type SubmissionQueryOptions, type TextField, type TextQuestionAggregate, type TranslationAdapter, type TranslationReport, type TranslationSlot, type ValidationCode, type ValidationError, type ValidationIssue, type WebhookConfig, type WebhookDispatchResult, aggregateResponses, assertValidFormSchema, calculateChoiceDistribution, calculateCrossTabulation, calculateFieldVisibility, calculateNumericSummary, calculatePageVisibility, createSubmission, dispatchWebhook, escapeCsvCell, exportResponsesToCsv, isDisplayConditionSatisfied, isQuestionVisible, populateSchemaTranslations, resolveFormTranslation, resolveLocalizedSchema, sanitizeSchema, selectVisibleAnswers, validateAnswers, validateFormSchema, validatePageAnswers, validateSchemaStructure };

package/dist/index.d.ts

@@ -1,6 +1,15 @@
 type FieldType = "text" | "textarea" | "number" | "rating" | "select" | "multi-select" | "checkbox" | "radio";
 type ConditionOperator = "equals" | "not_equals" | "contains" | "not_empty";
 type ConditionValue = string | number | boolean;
+type JsonValue = string | number | boolean | null | readonly JsonValue[] | {
+    readonly [key: string]: JsonValue;
+};
+/** Arbitrary, JSON-serializable data preserved by every form-engine operation. */
+interface ExtensibleNode {
+    readonly metadata?: Readonly<Record<string, JsonValue>>;
+    /** Locale -> translated property -> metadata created for that translation. */
+    readonly translationMetadata?: Readonly<Record<string, Readonly<Record<string, Readonly<Record<string, JsonValue>>>>>>;
+}
 interface DisplayCondition {
     readonly questionId: string;
     readonly operator: ConditionOperator;
@@ -9,15 +18,16 @@ interface DisplayCondition {
 interface LocalizedText {
     readonly title?: string;
     readonly description?: string;
+    readonly completionMessage?: string;
 }
 type SchemaTranslations = Readonly<Record<string, LocalizedText>>;
 type ValidationCode = "required" | "invalid_type" | "min_length" | "max_length" | "pattern" | "min" | "max" | "step" | "invalid_option" | "min_selections" | "max_selections" | "unknown_field";
-interface FieldOption {
+interface FieldOption extends ExtensibleNode {
     readonly id: string;
     readonly label: string;
     readonly translations?: Readonly<Record<string, string>>;
 }
-interface BaseField {
+interface BaseField extends ExtensibleNode {
     readonly id: string;
     readonly type: FieldType;
     readonly title: string;
@@ -61,7 +71,7 @@ interface CheckboxField extends BaseField {
     readonly type: "checkbox";
 }
 type FormField = TextField | NumberField | RatingField | SelectField | MultiSelectField | CheckboxField;
-interface FormPage {
+interface FormPage extends ExtensibleNode {
     readonly id: string;
     readonly title?: string;
     readonly description?: string;
@@ -69,11 +79,12 @@ interface FormPage {
     readonly displayCondition?: DisplayCondition;
     readonly translations?: SchemaTranslations;
 }
-interface FormSchema {
+interface FormSchema extends ExtensibleNode {
     readonly id: string;
     readonly version: number;
     readonly title: string;
     readonly description?: string;
+    readonly completionMessage?: string;
     readonly submitLabelKey?: string;
     readonly defaultLocale?: string;
     readonly supportedLocales?: readonly string[];
@@ -102,6 +113,7 @@ interface ValidationIssue {
     readonly messageKey: string;
     readonly params: Readonly<Record<string, string | number>>;
 }
+type ValidationError = ValidationIssue;
 type AnswerValidationResult = {
     readonly valid: true;
     readonly issues: readonly [];
@@ -109,7 +121,7 @@ type AnswerValidationResult = {
     readonly valid: false;
     readonly issues: readonly ValidationIssue[];
 };
-interface FormSubmission {
+interface FormSubmission extends ExtensibleNode {
     readonly id: string;
     readonly formId: string;
     readonly formVersion: number;
@@ -182,7 +194,13 @@ interface FormAnalytics {
 type Question = FormField;
 type QuestionType = FieldType;
 type ChoiceOption = FieldOption;
-type FormResponse = FormSubmission;
+interface FormResponse extends ExtensibleNode {
+    readonly responseId: string;
+    readonly formId: string;
+    readonly sourceLocale?: string;
+    readonly answers: Readonly<Record<string, unknown>>;
+    readonly submittedAt: string;
+}
 interface CrossTabulationResult {
     readonly rowQuestionId: string;
     readonly colQuestionId: string;
@@ -206,9 +224,10 @@ declare function calculateChoiceDistribution(responses: readonly FormSubmission[
 declare function calculateNumericSummary(responses: readonly FormSubmission[], questionId: string): NumericSummary;
 declare function calculateCrossTabulation(responses: readonly FormSubmission[], rowQuestionId: string, colQuestionId: string): CrossTabulationResult;
 declare function aggregateResponses(schema: FormSchema, submissions: readonly FormSubmission[]): FormAnalytics;
-declare function escapeCsvCell(value: string | number | null | undefined): string;
+declare function escapeCsvCell(value: string | number | boolean | null | undefined, neutralizeFormulas?: boolean): string;
 interface CsvExportOptions {
     readonly withBom?: boolean;
+    readonly neutralizeFormulas?: boolean;
 }
 declare function exportResponsesToCsv(schema: FormSchema, responses: readonly FormSubmission[], options?: CsvExportOptions): string;
 
@@ -246,15 +265,36 @@ declare function sanitizeSchema(schema: FormSchema): FormSchema;
 declare function validateFormSchema(input: unknown): SchemaValidationResult;
 declare function assertValidFormSchema(input: unknown): asserts input is FormSchema;
 
-interface CreateSubmissionOptions {
+interface CreateSubmissionOptions extends ExtensibleNode {
     readonly id: string;
     readonly locale: string;
     readonly submittedAt: string;
 }
 declare function createSubmission(schema: FormSchema, values: FormValues, options: CreateSubmissionOptions): FormSubmission;
 
+interface TranslationSlot {
+    readonly kind: "form" | "page" | "field" | "option";
+    readonly nodeId: string;
+    readonly property: "title" | "description" | "label" | "completionMessage";
+    readonly locale: string;
+    readonly sourceText: string;
+    readonly existingText?: string;
+    readonly metadata?: Readonly<Record<string, JsonValue>>;
+}
+interface PopulateTranslationOptions {
+    readonly overwrite?: "missing-only" | "all";
+    readonly shouldOverwrite?: (slot: TranslationSlot) => boolean;
+    readonly createMetadata?: (slot: TranslationSlot, translatedText: string) => Readonly<Record<string, JsonValue>>;
+}
+interface TranslationReport {
+    readonly updatedSlots: readonly TranslationSlot[];
+    readonly skippedSlots: readonly TranslationSlot[];
+}
 declare function resolveLocalizedSchema(schema: FormSchema, targetLocale: string): FormSchema;
-declare function populateSchemaTranslations(schema: FormSchema, targetLocales: readonly string[], adapter: AsyncTranslationAdapter): Promise<FormSchema>;
+declare function populateSchemaTranslations(schema: FormSchema, targetLocales: readonly string[], adapter: AsyncTranslationAdapter, options?: PopulateTranslationOptions): Promise<{
+    readonly schema: FormSchema;
+    readonly report: TranslationReport;
+}>;
 declare function resolveFormTranslation(schema: FormSchema, adapter: AsyncTranslationAdapter, targetLocale: string, sourceLocale?: string): Promise<FormSchema>;
 
 declare function validateAnswers(schema: FormSchema, values: FormValues): AnswerValidationResult;
@@ -266,4 +306,4 @@ declare function calculatePageVisibility(schema: FormSchema, currentAnswers: Rea
 declare function calculateFieldVisibility(schema: FormSchema, currentAnswers: Readonly<Record<string, unknown>>): Readonly<Record<string, boolean>>;
 declare function selectVisibleAnswers(schema: FormSchema, currentAnswers: FormValues): FormValues;
 
-export { type AnswerValidationResult, type AsyncTranslationAdapter, type BaseField, type CheckboxField, type CheckboxQuestionAggregate, type ChoiceDistributionEntry, type ChoiceOption, type ChoiceQuestionAggregate, type ConditionOperator, type ConditionValue, type CreateSubmissionOptions, type CrossTabulationResult, type CsvExportOptions, type DisplayCondition, type FieldOption, type FieldType, type FormAnalytics, type FormEvent, type FormEventType, type FormField, type FormPage, type FormResponse, type FormSchema, type FormStorageAdapter, type FormSubmission, type FormValue, type FormValues, type LocalizedText, type MultiSelectField, type NumberField, type NumberQuestionAggregate, type NumericSummary, type OptionAggregate, type Question, type QuestionAggregate, type QuestionType, type RatingField, type SchemaIssue, type SchemaStructureIssue, type SchemaStructureIssueType, type SchemaTranslations, type SchemaValidationResult, type SelectField, type StorageAdapter, type SubmissionQueryOptions, type TextField, type TextQuestionAggregate, type TranslationAdapter, type ValidationCode, type ValidationIssue, type WebhookConfig, type WebhookDispatchResult, aggregateResponses, assertValidFormSchema, calculateChoiceDistribution, calculateCrossTabulation, calculateFieldVisibility, calculateNumericSummary, calculatePageVisibility, createSubmission, dispatchWebhook, escapeCsvCell, exportResponsesToCsv, isDisplayConditionSatisfied, isQuestionVisible, populateSchemaTranslations, resolveFormTranslation, resolveLocalizedSchema, sanitizeSchema, selectVisibleAnswers, validateAnswers, validateFormSchema, validatePageAnswers, validateSchemaStructure };
+export { type AnswerValidationResult, type AsyncTranslationAdapter, type BaseField, type CheckboxField, type CheckboxQuestionAggregate, type ChoiceDistributionEntry, type ChoiceOption, type ChoiceQuestionAggregate, type ConditionOperator, type ConditionValue, type CreateSubmissionOptions, type CrossTabulationResult, type CsvExportOptions, type DisplayCondition, type ExtensibleNode, type FieldOption, type FieldType, type FormAnalytics, type FormEvent, type FormEventType, type FormField, type FormPage, type FormResponse, type FormSchema, type FormStorageAdapter, type FormSubmission, type FormValue, type FormValues, type JsonValue, type LocalizedText, type MultiSelectField, type NumberField, type NumberQuestionAggregate, type NumericSummary, type OptionAggregate, type PopulateTranslationOptions, type Question, type QuestionAggregate, type QuestionType, type RatingField, type SchemaIssue, type SchemaStructureIssue, type SchemaStructureIssueType, type SchemaTranslations, type SchemaValidationResult, type SelectField, type StorageAdapter, type SubmissionQueryOptions, type TextField, type TextQuestionAggregate, type TranslationAdapter, type TranslationReport, type TranslationSlot, type ValidationCode, type ValidationError, type ValidationIssue, type WebhookConfig, type WebhookDispatchResult, aggregateResponses, assertValidFormSchema, calculateChoiceDistribution, calculateCrossTabulation, calculateFieldVisibility, calculateNumericSummary, calculatePageVisibility, createSubmission, dispatchWebhook, escapeCsvCell, exportResponsesToCsv, isDisplayConditionSatisfied, isQuestionVisible, populateSchemaTranslations, resolveFormTranslation, resolveLocalizedSchema, sanitizeSchema, selectVisibleAnswers, validateAnswers, validateFormSchema, validatePageAnswers, validateSchemaStructure };

package/dist/index.js

@@ -140,6 +140,52 @@ 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.");
@@ -150,7 +196,7 @@ function validateLocalizedTextMap(value, path, issues) {
       issue(issues, `${path}.${locale}`, "invalid_translation", "Expected a translation object.");
       continue;
     }
-    for (const key of ["title", "description"]) {
+    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.");
       }
@@ -201,6 +247,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)) {
@@ -246,6 +293,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.");
@@ -331,6 +379,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.");
@@ -338,13 +387,13 @@ 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."
       );
     }
   }
@@ -406,6 +455,7 @@ function validateFormSchema(input) {
             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)) {
@@ -697,15 +747,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);
@@ -726,7 +781,8 @@ 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;
 }
 
@@ -936,69 +992,125 @@ 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
-function mergeLocalizedText(translations, locale, key, value) {
-  return { ...translations, [locale]: { ...translations?.[locale], [key]: value } };
+function mergeLocalizedText(translations, locale, property, value) {
+  return { ...translations, [locale]: { ...translations?.[locale], [property]: value } };
 }
-function translationSlots(schema) {
-  const slots = [
-    {
-      text: schema.title,
-      apply: (current, value, locale) => ({
-        ...current,
-        translations: mergeLocalizedText(current.translations, locale, "title", value)
-      })
+function withTranslationMetadata(node, locale, property, metadata) {
+  if (metadata === void 0) return node;
+  return {
+    ...node,
+    translationMetadata: {
+      ...node.translationMetadata,
+      [locale]: {
+        ...node.translationMetadata?.[locale],
+        [property]: metadata
+      }
     }
-  ];
-  if (schema.description !== void 0) {
-    slots.push({
-      text: schema.description,
-      apply: (current, value, locale) => ({
-        ...current,
-        translations: mergeLocalizedText(current.translations, locale, "description", value)
-      })
+  };
+}
+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) => {
-    slots.push({
-      text: field.title,
-      apply: (current, value, locale) => ({
-        ...current,
-        fields: current.fields.map(
-          (item, index) => index === fieldIndex ? { ...item, translations: mergeLocalizedText(item.translations, locale, "title", value) } : item
-        )
-      })
-    });
-    if (field.description !== void 0) {
-      slots.push({
-        text: field.description,
-        apply: (current, value, locale) => ({
+    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(
-            (item, index) => index === fieldIndex ? {
-              ...item,
-              translations: mergeLocalizedText(item.translations, locale, "description", value)
-            } : item
+            (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) => {
-        slots.push({
-          text: option.label,
-          apply: (current, value, locale) => ({
+        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((item, index) => {
-              if (index !== fieldIndex || !("options" in item)) return item;
+            fields: current.fields.map((candidate, candidateIndex) => {
+              if (candidateIndex !== fieldIndex || !("options" in candidate)) return candidate;
               return {
-                ...item,
-                options: item.options.map(
-                  (candidate, candidateIndex) => candidateIndex === optionIndex ? { ...candidate, translations: { ...candidate.translations, [locale]: value } } : candidate
+                ...candidate,
+                options: candidate.options.map(
+                  (candidateOption, candidateOptionIndex) => candidateOptionIndex === optionIndex ? withTranslationMetadata(
+                    {
+                      ...candidateOption,
+                      translations: { ...candidateOption.translations, [locale]: value }
+                    },
+                    locale,
+                    "label",
+                    metadata
+                  ) : candidateOption
                 )
               };
             })
@@ -1008,42 +1120,50 @@ function translationSlots(schema) {
     }
   });
   schema.pages?.forEach((page, pageIndex) => {
-    if (page.title !== void 0) {
-      slots.push({
-        text: page.title,
-        apply: (current, value, locale) => ({
-          ...current,
-          ...current.pages === void 0 ? {} : {
-            pages: current.pages.map(
-              (item, index) => index === pageIndex ? { ...item, translations: mergeLocalizedText(item.translations, locale, "title", value) } : item
-            )
-          }
-        })
-      });
-    }
-    if (page.description !== void 0) {
-      slots.push({
-        text: page.description,
-        apply: (current, value, locale) => ({
+    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(
-              (item, index) => index === pageIndex ? { ...item, translations: mergeLocalizedText(item.translations, locale, "description", value) } : item
+              (candidate, index) => index === pageIndex ? withTranslationMetadata(
+                {
+                  ...candidate,
+                  translations: mergeLocalizedText(candidate.translations, locale, property, value)
+                },
+                locale,
+                property,
+                metadata
+              ) : candidate
             )
           }
         })
       });
-    }
+    };
+    if (page.title !== void 0) addPageSlot("title", page.title);
+    if (page.description !== void 0) addPageSlot("description", page.description);
   });
-  return slots;
+  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: 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 = {
@@ -1074,24 +1194,35 @@ function resolveLocalizedSchema(schema, targetLocale) {
     }
   };
 }
-async function populateSchemaTranslations(schema, targetLocales, adapter) {
+async function populateSchemaTranslations(schema, targetLocales, adapter, options = {}) {
   assertValidFormSchema(schema);
-  const slots = translationSlots(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(
-      slots.map((slot) => slot.text),
+      selected.map((descriptor) => descriptor.slot.sourceText),
       locale,
       schema.defaultLocale
     );
-    if (translated.length !== slots.length) {
-      throw new Error(`Translation adapter returned ${translated.length} texts for ${slots.length} inputs.`);
+    if (translated.length !== selected.length) {
+      throw new Error(`Translation adapter returned ${translated.length} texts for ${selected.length} inputs.`);
     }
-    translated.forEach((value, index) => {
-      const slot = slots[index];
-      if (slot === void 0) throw new Error("Translation adapter returned an unexpected result.");
-      result = slot.apply(result, value, locale);
+    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 = [
@@ -1101,17 +1232,18 @@ async function populateSchemaTranslations(schema, targetLocales, adapter) {
       ...locales
     ])
   ];
-  result = supportedLocales.length === 0 ? result : { ...result, supportedLocales };
+  if (supportedLocales.length > 0) result = { ...result, supportedLocales };
   assertValidFormSchema(result);
-  return 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
+    adapter,
+    { overwrite: "all" }
   );
-  return resolveLocalizedSchema(populated, targetLocale);
+  return resolveLocalizedSchema(populated.schema, targetLocale);
 }
 export {
   aggregateResponses,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@form-engine-ts/core",
-  "version": "1.1.0",
+  "version": "2.0.0",
   "publishConfig": {
     "access": "public"
   },