@form-engine-ts/core 1.1.0 → 2.1.0

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.");
@@ -325,12 +373,157 @@ function validateField(value, path, issues) {
   }
   return true;
 }
-function validateFormSchema(input) {
+function collectSchemaText(schema) {
+  const entries = [{ path: "title", value: schema.title }];
+  if (schema.description !== void 0) entries.push({ path: "description", value: schema.description });
+  if (schema.completionMessage !== void 0)
+    entries.push({ path: "completionMessage", value: schema.completionMessage });
+  for (const [locale, translation] of Object.entries(schema.translations ?? {})) {
+    for (const property of ["title", "description", "completionMessage"]) {
+      const value = translation[property];
+      if (value !== void 0) entries.push({ path: `translations.${locale}.${property}`, value });
+    }
+  }
+  schema.fields.forEach((field, fieldIndex) => {
+    entries.push({ path: `fields[${fieldIndex}].title`, value: field.title });
+    if (field.description !== void 0)
+      entries.push({ path: `fields[${fieldIndex}].description`, value: field.description });
+    for (const [locale, translation] of Object.entries(field.translations ?? {})) {
+      for (const property of ["title", "description"]) {
+        const value = translation[property];
+        if (value !== void 0)
+          entries.push({ path: `fields[${fieldIndex}].translations.${locale}.${property}`, value });
+      }
+    }
+    if (!("options" in field)) return;
+    field.options.forEach((option, optionIndex) => {
+      entries.push({ path: `fields[${fieldIndex}].options[${optionIndex}].label`, value: option.label });
+      for (const [locale, value] of Object.entries(option.translations ?? {})) {
+        entries.push({ path: `fields[${fieldIndex}].options[${optionIndex}].translations.${locale}`, value });
+      }
+    });
+  });
+  schema.pages?.forEach((page, pageIndex) => {
+    if (page.title !== void 0) entries.push({ path: `pages[${pageIndex}].title`, value: page.title });
+    if (page.description !== void 0)
+      entries.push({ path: `pages[${pageIndex}].description`, value: page.description });
+    for (const [locale, translation] of Object.entries(page.translations ?? {})) {
+      for (const property of ["title", "description"]) {
+        const value = translation[property];
+        if (value !== void 0)
+          entries.push({ path: `pages[${pageIndex}].translations.${locale}.${property}`, value });
+      }
+    }
+  });
+  return entries;
+}
+function addRequiredTranslationIssues(schema, locale, issues) {
+  if (!(schema.supportedLocales ?? []).includes(locale)) {
+    issue(issues, "supportedLocales", "required_locale_missing", `Required locale ${locale} is missing.`);
+  }
+  if (locale === schema.defaultLocale) return;
+  const required = [
+    { path: `translations.${locale}.title`, value: schema.translations?.[locale]?.title }
+  ];
+  if (schema.description !== void 0)
+    required.push({ path: `translations.${locale}.description`, value: schema.translations?.[locale]?.description });
+  if (schema.completionMessage !== void 0) {
+    required.push({
+      path: `translations.${locale}.completionMessage`,
+      value: schema.translations?.[locale]?.completionMessage
+    });
+  }
+  schema.fields.forEach((field, fieldIndex) => {
+    required.push({
+      path: `fields[${fieldIndex}].translations.${locale}.title`,
+      value: field.translations?.[locale]?.title
+    });
+    if (field.description !== void 0) {
+      required.push({
+        path: `fields[${fieldIndex}].translations.${locale}.description`,
+        value: field.translations?.[locale]?.description
+      });
+    }
+    if (!("options" in field)) return;
+    field.options.forEach((option, optionIndex) => {
+      required.push({
+        path: `fields[${fieldIndex}].options[${optionIndex}].translations.${locale}`,
+        value: option.translations?.[locale]
+      });
+    });
+  });
+  schema.pages?.forEach((page, pageIndex) => {
+    if (page.title !== void 0) {
+      required.push({
+        path: `pages[${pageIndex}].translations.${locale}.title`,
+        value: page.translations?.[locale]?.title
+      });
+    }
+    if (page.description !== void 0) {
+      required.push({
+        path: `pages[${pageIndex}].translations.${locale}.description`,
+        value: page.translations?.[locale]?.description
+      });
+    }
+  });
+  for (const translation of required) {
+    if (translation.value === void 0 || translation.value.trim().length === 0) {
+      issue(
+        issues,
+        translation.path,
+        "required_translation_missing",
+        `A translation for required locale ${locale} is missing.`
+      );
+    }
+  }
+}
+function validatePolicy(schema, policy, issues) {
+  if (policy.maxFields !== void 0 && schema.fields.length > policy.maxFields) {
+    issue(issues, "fields", "max_fields_exceeded", `At most ${policy.maxFields} fields are allowed.`);
+  }
+  schema.fields.forEach((field, fieldIndex) => {
+    if (policy.allowedFieldTypes !== void 0 && !policy.allowedFieldTypes.includes(field.type)) {
+      issue(issues, `fields[${fieldIndex}].type`, "disallowed_field_type", `Field type ${field.type} is not allowed.`);
+    }
+    if (policy.maxOptionsPerField !== void 0 && "options" in field && field.options.length > policy.maxOptionsPerField) {
+      issue(
+        issues,
+        `fields[${fieldIndex}].options`,
+        "max_options_exceeded",
+        `At most ${policy.maxOptionsPerField} options are allowed.`
+      );
+    }
+  });
+  if (policy.maxTextLength !== void 0) {
+    for (const entry of collectSchemaText(schema)) {
+      if (entry.value.length > policy.maxTextLength) {
+        issue(
+          issues,
+          entry.path,
+          "max_text_length_exceeded",
+          `Text must be at most ${policy.maxTextLength} characters.`
+        );
+      }
+    }
+  }
+  for (const locale of policy.requiredLocales ?? []) addRequiredTranslationIssues(schema, locale, issues);
+  if (policy.maxSchemaBytes !== void 0) {
+    try {
+      const byteLength = new TextEncoder().encode(JSON.stringify(schema)).byteLength;
+      if (byteLength > policy.maxSchemaBytes) {
+        issue(issues, "$", "max_schema_bytes_exceeded", `Schema must be at most ${policy.maxSchemaBytes} bytes.`);
+      }
+    } catch {
+    }
+  }
+}
+function validateFormSchema(input, options = {}) {
   const issues = [];
   if (!isRecord(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 +531,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 +599,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)) {
@@ -469,6 +663,14 @@ function validateFormSchema(input) {
       }
     }
   }
+  if (Array.isArray(input.fields)) {
+    const policyIssues = [];
+    try {
+      validatePolicy(input, options.policy ?? {}, policyIssues);
+      issues.push(...policyIssues);
+    } catch {
+    }
+  }
   return issues.length === 0 ? { valid: true, value: input, issues: [] } : { valid: false, issues };
 }
 function assertValidFormSchema(input) {
@@ -697,15 +899,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 +933,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;
 }
 
@@ -771,6 +979,58 @@ async function dispatchWebhook(event, config, fetchImpl = globalThis.fetch) {
   }
 }
 
+// src/field.ts
+var DEFAULT_OPTION = { id: "option-1", label: "Option 1" };
+function transformFieldType(field, nextType) {
+  const common = {
+    id: field.id,
+    title: field.title,
+    required: field.required,
+    ...field.description === void 0 ? {} : { description: field.description },
+    ...field.translationKey === void 0 ? {} : { translationKey: field.translationKey },
+    ...field.messages === void 0 ? {} : { messages: field.messages },
+    ...field.displayCondition === void 0 ? {} : { displayCondition: field.displayCondition },
+    ...field.translations === void 0 ? {} : { translations: field.translations },
+    ...field.metadata === void 0 ? {} : { metadata: field.metadata },
+    ...field.translationMetadata === void 0 ? {} : { translationMetadata: field.translationMetadata }
+  };
+  if (nextType === "text" || nextType === "textarea") {
+    const textProperties = field.type === "text" || field.type === "textarea" ? {
+      ...field.placeholderKey === void 0 ? {} : { placeholderKey: field.placeholderKey },
+      ...field.minLength === void 0 ? {} : { minLength: field.minLength },
+      ...field.maxLength === void 0 ? {} : { maxLength: field.maxLength },
+      ...field.pattern === void 0 ? {} : { pattern: field.pattern }
+    } : {};
+    return { ...common, ...textProperties, type: nextType };
+  }
+  if (nextType === "number") {
+    const numberProperties = field.type === "number" ? {
+      ...field.placeholderKey === void 0 ? {} : { placeholderKey: field.placeholderKey },
+      ...field.min === void 0 ? {} : { min: field.min },
+      ...field.max === void 0 ? {} : { max: field.max },
+      ...field.step === void 0 ? {} : { step: field.step }
+    } : {};
+    return { ...common, ...numberProperties, type: nextType };
+  }
+  if (nextType === "rating") {
+    const ratingProperties = field.type === "rating" ? {
+      ...field.min === void 0 ? {} : { min: field.min },
+      ...field.max === void 0 ? {} : { max: field.max }
+    } : { min: 1, max: 5 };
+    return { ...common, ...ratingProperties, type: nextType };
+  }
+  if (nextType === "checkbox") return { ...common, type: nextType };
+  const options = "options" in field && field.options.length > 0 ? field.options : [DEFAULT_OPTION];
+  if (nextType === "multi-select") {
+    const selectionProperties = field.type === "multi-select" ? {
+      ...field.minSelections === void 0 ? {} : { minSelections: field.minSelections },
+      ...field.maxSelections === void 0 ? {} : { maxSelections: field.maxSelections }
+    } : {};
+    return { ...common, ...selectionProperties, type: nextType, options };
+  }
+  return { ...common, type: nextType, options };
+}
+
 // src/validation.ts
 var DEFAULT_MESSAGES = {
   required: "validation.required",
@@ -936,69 +1196,129 @@ 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, nodeMetadata, existingTranslationMetadata) {
+  return {
+    kind,
+    nodeId,
+    property,
+    locale,
+    sourceText,
+    ...existingText === void 0 ? {} : { existingText },
+    ...nodeMetadata === void 0 ? {} : { nodeMetadata, metadata: nodeMetadata },
+    ...existingTranslationMetadata === void 0 ? {} : { existingTranslationMetadata }
+  };
+}
+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,
+      schema.translationMetadata?.[locale]?.[property]
+    );
+    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,
+        field.translationMetadata?.[locale]?.[property]
+      );
+      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,
+          option.translationMetadata?.[locale]?.label
+        );
+        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 +1328,51 @@ 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,
+        page.translationMetadata?.[locale]?.[property]
+      );
+      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 +1403,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 +1441,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,
@@ -1132,6 +1473,7 @@ export {
   resolveLocalizedSchema,
   sanitizeSchema,
   selectVisibleAnswers,
+  transformFieldType,
   validateAnswers,
   validateFormSchema,
   validatePageAnswers,