@form-engine-ts/core 4.4.0 → 4.6.0

package/dist/index.cjs

@@ -31,6 +31,8 @@ __export(index_exports, {
   calculatePageVisibility: () => calculatePageVisibility,
   cloneVersionToDraft: () => cloneVersionToDraft,
   collectSchemaLocales: () => collectSchemaLocales,
+  collectTranslationSlots: () => collectTranslationSlots,
+  computeSourceTextHash: () => computeSourceTextHash,
   createCloneTransitionPlan: () => createCloneTransitionPlan,
   createDeleteDraftTransitionPlan: () => createDeleteDraftTransitionPlan,
   createPublishTransitionPlan: () => createPublishTransitionPlan,
@@ -45,16 +47,21 @@ __export(index_exports, {
   escapeCsvCell: () => escapeCsvCell,
   exportResponsesToCsv: () => exportResponsesToCsv,
   exportResponsesToCsvStream: () => exportResponsesToCsvStream,
+  getTranslationStatus: () => getTranslationStatus,
+  isDisplayConditionGroupSatisfied: () => isDisplayConditionGroupSatisfied,
   isDisplayConditionSatisfied: () => isDisplayConditionSatisfied,
+  isManualTranslationMetadata: () => isManualTranslationMetadata,
   isQuestionVisible: () => isQuestionVisible,
   iterateSubmissionPages: () => iterateSubmissionPages,
   jsonValuesEqual: () => jsonValuesEqual,
   matchesSubmissionFilter: () => matchesSubmissionFilter,
   matchesSubmissionPageFilters: () => matchesSubmissionPageFilters,
+  migrateSchemaTranslationMetadata: () => migrateSchemaTranslationMetadata,
   normalizeSubmissionPageSize: () => normalizeSubmissionPageSize,
   pipeResponsesToCsvStream: () => pipeResponsesToCsvStream,
   populateSchemaTranslations: () => populateSchemaTranslations,
   publishDraft: () => publishDraft,
+  removeLocaleFromSchema: () => removeLocaleFromSchema,
   resolveFormTranslation: () => resolveFormTranslation,
   resolveLocalizedSchema: () => resolveLocalizedSchema,
   sanitizeSchema: () => sanitizeSchema,
@@ -116,6 +123,19 @@ function collectSchemaLocales(schema) {
 }
 
 // src/sanitization.ts
+function displayRuleSourceIds(field) {
+  if (field.displayRule === void 0)
+    return field.displayCondition?.questionId === void 0 ? [] : [field.displayCondition.questionId];
+  const ids = [];
+  const visit = (group) => {
+    for (const condition of group.conditions) {
+      if ("logic" in condition) visit(condition);
+      else ids.push(condition.fieldId);
+    }
+  };
+  visit(field.displayRule.condition);
+  return ids;
+}
 function registeredEntries(value, registeredLocales) {
   if (value === void 0) return void 0;
   const entries = Object.entries(value).filter(([locale]) => registeredLocales.has(locale));
@@ -183,26 +203,28 @@ function cyclicQuestionIds(fields) {
     if (!firstById.has(field.id)) firstById.set(field.id, field);
   }
   const cyclic = /* @__PURE__ */ new Set();
-  const resolved = /* @__PURE__ */ new Set();
-  for (const startId of firstById.keys()) {
-    if (resolved.has(startId)) continue;
-    const path = [];
-    const pathIndex = /* @__PURE__ */ new Map();
-    let currentId = startId;
-    while (currentId !== void 0 && firstById.has(currentId) && !resolved.has(currentId)) {
-      const existingIndex = pathIndex.get(currentId);
-      if (existingIndex !== void 0) {
-        for (const id of path.slice(existingIndex)) cyclic.add(id);
-        break;
-      }
-      pathIndex.set(currentId, path.length);
-      path.push(currentId);
-      const field = firstById.get(currentId);
-      const sourceId = field?.displayCondition?.questionId;
-      currentId = sourceId === currentId ? void 0 : sourceId;
+  const visiting = /* @__PURE__ */ new Set();
+  const visited = /* @__PURE__ */ new Set();
+  const path = [];
+  const visit = (id) => {
+    if (visiting.has(id)) {
+      const start = path.indexOf(id);
+      for (const member of path.slice(start < 0 ? 0 : start)) cyclic.add(member);
+      return;
     }
-    for (const id of path) resolved.add(id);
-  }
+    if (visited.has(id)) return;
+    visiting.add(id);
+    path.push(id);
+    const field = firstById.get(id);
+    if (field === void 0) return;
+    for (const sourceId of displayRuleSourceIds(field)) {
+      if (sourceId !== id && firstById.has(sourceId)) visit(sourceId);
+    }
+    path.pop();
+    visiting.delete(id);
+    visited.add(id);
+  };
+  for (const id of firstById.keys()) visit(id);
   return cyclic;
 }
 function validateSchemaStructure(schema) {
@@ -234,20 +256,20 @@ function validateSchemaStructure(schema) {
     }
   }
   for (const field of schema.fields) {
-    const sourceId = field.displayCondition?.questionId;
-    if (sourceId === void 0) continue;
-    if (sourceId === field.id) {
-      issues.push({
-        type: "self_condition_reference",
-        questionId: field.id,
-        message: `Question "${field.id}" cannot depend on itself.`
-      });
-    } else if (!questionIds.has(sourceId)) {
-      issues.push({
-        type: "dangling_condition_reference",
-        questionId: field.id,
-        message: `Question "${field.id}" references missing question "${sourceId}".`
-      });
+    for (const sourceId of displayRuleSourceIds(field)) {
+      if (sourceId === field.id) {
+        issues.push({
+          type: "self_condition_reference",
+          questionId: field.id,
+          message: `Question "${field.id}" cannot depend on itself.`
+        });
+      } else if (!questionIds.has(sourceId)) {
+        issues.push({
+          type: "dangling_condition_reference",
+          questionId: field.id,
+          message: `Question "${field.id}" references missing question "${sourceId}".`
+        });
+      }
     }
   }
   const cyclic = cyclicQuestionIds(schema.fields);
@@ -256,6 +278,11 @@ function validateSchemaStructure(schema) {
     issues.push({
       type: "cyclic_condition_reference",
       questionId: field.id,
+      cycle: [
+        field.id,
+        ...displayRuleSourceIds(field).filter((sourceId) => cyclic.has(sourceId)).slice(0, 1),
+        field.id
+      ],
       message: `Question "${field.id}" participates in a display-condition cycle.`
     });
   }
@@ -270,11 +297,17 @@ function sanitizeSchema(schema, options = {}) {
   const cyclic = cyclicQuestionIds(schema.fields);
   const sanitizedFields = schema.fields.map((sourceField) => {
     const field = sanitizeFieldConstraints(sanitizeFieldLocales(sourceField, registeredLocales), options.policy);
-    const sourceId = field.displayCondition?.questionId;
-    if (sourceId === void 0 || existingQuestionIds.has(sourceId) && sourceId !== field.id && !cyclic.has(field.id)) {
-      return field;
+    let sanitized = field;
+    const ruleSources = displayRuleSourceIds(field);
+    if (field.displayRule !== void 0 && (cyclic.has(field.id) || ruleSources.some((sourceId2) => sourceId2 === field.id || !existingQuestionIds.has(sourceId2)))) {
+      const { displayRule: _displayRule, ...withoutRule } = sanitized;
+      sanitized = withoutRule;
+    }
+    const sourceId = sanitized.displayCondition?.questionId;
+    if (sourceId !== void 0 && (!existingQuestionIds.has(sourceId) || sourceId === sanitized.id || cyclic.has(sanitized.id))) {
+      const { displayCondition: _displayCondition, ...withoutCondition } = sanitized;
+      return withoutCondition;
     }
-    const { displayCondition: _displayCondition, ...sanitized } = field;
     return sanitized;
   });
   const localizedSchema = sanitizeNodeLocales(schema, registeredLocales);
@@ -317,7 +350,17 @@ function sanitizeSchema(schema, options = {}) {
 
 // src/schema.ts
 var FIELD_TYPES = /* @__PURE__ */ new Set(["text", "textarea", "number", "rating", "select", "multi-select", "checkbox", "radio"]);
-var CONDITION_OPERATORS = /* @__PURE__ */ new Set(["equals", "not_equals", "contains", "not_empty"]);
+var CONDITION_OPERATORS = /* @__PURE__ */ new Set([
+  "equals",
+  "not_equals",
+  "contains",
+  "not_contains",
+  "is_empty",
+  "is_not_empty",
+  "greater_than",
+  "less_than",
+  "not_empty"
+]);
 function isRecord(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
@@ -474,7 +517,7 @@ function validateDisplayCondition(value, path, issues) {
     return false;
   }
   const hasValue = Object.hasOwn(value, "value") && value.value !== void 0;
-  if (value.operator === "not_empty") {
+  if (value.operator === "not_empty" || value.operator === "is_empty" || value.operator === "is_not_empty") {
     if (hasValue) issue(issues, `${path}.value`, "unexpected_condition_value", "not_empty does not accept a value.");
   } else if (!hasValue) {
     issue(issues, `${path}.value`, "missing_condition_value", `${value.operator} requires a value.`);
@@ -485,6 +528,75 @@ function validateDisplayCondition(value, path, issues) {
   }
   return true;
 }
+function validateDisplayConditionGroup(value, path, issues) {
+  if (!isRecord(value)) {
+    issue(issues, path, "invalid_condition_group", "Expected a display condition group.");
+    return false;
+  }
+  if (value.logic !== "all" && value.logic !== "any") {
+    issue(issues, `${path}.logic`, "invalid_condition_logic", "Expected all or any.");
+  }
+  if (!Array.isArray(value.conditions)) {
+    issue(issues, `${path}.conditions`, "invalid_condition_group", "Expected a conditions array.");
+    return false;
+  }
+  value.conditions.forEach((condition, index) => {
+    const conditionPath = `${path}.conditions[${index}]`;
+    if (isRecord(condition) && Object.hasOwn(condition, "logic")) {
+      validateDisplayConditionGroup(condition, conditionPath, issues);
+      return;
+    }
+    if (!isRecord(condition)) {
+      issue(issues, conditionPath, "invalid_condition", "Expected a field display condition.");
+      return;
+    }
+    if (!isNonEmptyString(condition.fieldId)) {
+      issue(issues, `${conditionPath}.fieldId`, "invalid_condition_source", "Expected a field ID.");
+    }
+    if (typeof condition.operator !== "string" || !CONDITION_OPERATORS.has(condition.operator)) {
+      issue(issues, `${conditionPath}.operator`, "invalid_condition_operator", "Unsupported condition operator.");
+      return;
+    }
+    const needsValue = !["not_empty", "is_empty", "is_not_empty"].includes(condition.operator);
+    const hasValue = Object.hasOwn(condition, "value") && condition.value !== void 0;
+    if (needsValue && !hasValue)
+      issue(issues, `${conditionPath}.value`, "missing_condition_value", "A value is required.");
+  });
+  return true;
+}
+function validateDisplayRule(value, path, issues) {
+  if (!isRecord(value)) {
+    issue(issues, path, "invalid_display_rule", "Expected a display rule object.");
+    return false;
+  }
+  if (value.action !== "show" && value.action !== "hide") {
+    issue(issues, `${path}.action`, "invalid_display_action", "Expected show or hide.");
+  }
+  validateDisplayConditionGroup(value.condition, `${path}.condition`, issues);
+  return true;
+}
+function validateSubmissionSettings(value, path, issues) {
+  if (!isRecord(value)) {
+    issue(issues, path, "invalid_submission_settings", "Expected submission settings to be an object.");
+    return;
+  }
+  validateExtensibleNode(value, path, issues);
+  if (value.showConfirmationBeforeSubmit !== void 0 && typeof value.showConfirmationBeforeSubmit !== "boolean") {
+    issue(issues, `${path}.showConfirmationBeforeSubmit`, "invalid_submission_setting", "Expected a boolean.");
+  }
+  if (value.confirmationRenderMode !== void 0 && !["dialog", "inline", "replace"].includes(String(value.confirmationRenderMode))) {
+    issue(
+      issues,
+      `${path}.confirmationRenderMode`,
+      "invalid_submission_setting",
+      "Unsupported confirmation render mode."
+    );
+  }
+  for (const key of ["confirmButtonLabel", "cancelButtonLabel"]) {
+    if (value[key] !== void 0 && !isNonEmptyString(value[key]))
+      issue(issues, `${path}.${key}`, "invalid_submission_setting", "Expected non-empty text.");
+  }
+}
 function validateField(value, path, issues) {
   if (!isRecord(value)) {
     issue(issues, path, "invalid_field", "Expected a field object.");
@@ -508,6 +620,7 @@ function validateField(value, path, issues) {
   if (value.displayCondition !== void 0) {
     validateDisplayCondition(value.displayCondition, `${path}.displayCondition`, issues);
   }
+  if (value.displayRule !== void 0) validateDisplayRule(value.displayRule, `${path}.displayRule`, 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.");
@@ -892,6 +1005,8 @@ function validateFormSchema(input, options = {}) {
     }
   }
   if (input.translations !== void 0) validateLocalizedTextMap(input.translations, "translations", issues);
+  if (input.submissionSettings !== void 0)
+    validateSubmissionSettings(input.submissionSettings, "submissionSettings", issues);
   if (!Array.isArray(input.fields) || input.fields.length === 0) {
     issue(issues, "fields", "invalid_fields", "Expected at least one field.");
   } else {
@@ -915,8 +1030,19 @@ function validateFormSchema(input, options = {}) {
         continue;
       }
       const fieldIndex = inputFields.findIndex((field) => isRecord(field) && field.id === structuralIssue.questionId);
-      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);
+      const currentField = inputFields[fieldIndex];
+      const usesDisplayRule = isRecord(currentField) && currentField.displayRule !== void 0;
+      const code = structuralIssue.type === "dangling_condition_reference" ? "unknown_condition_source" : structuralIssue.type === "self_condition_reference" ? "self_condition" : usesDisplayRule ? "circular_display_condition" : "condition_cycle";
+      const path = usesDisplayRule ? `fields[${fieldIndex}].displayRule` : `fields[${fieldIndex}].displayCondition`;
+      if (usesDisplayRule && structuralIssue.type === "cyclic_condition_reference") {
+        issues.push({
+          path,
+          code,
+          type: code,
+          message: structuralIssue.message,
+          ...structuralIssue.cycle === void 0 ? {} : { cycle: structuralIssue.cycle }
+        });
+      } else issue(issues, path, code, structuralIssue.message);
     }
     if (input.pages !== void 0) {
       if (!Array.isArray(input.pages) || input.pages.length === 0) {
@@ -1025,23 +1151,61 @@ function normalizeString(value) {
   return value.trim().normalize("NFKC").toLowerCase();
 }
 function valuesEqual(left, right) {
-  return typeof left === "string" && typeof right === "string" ? normalizeString(left) === normalizeString(right) : left === right;
+  if (typeof left === "string" && typeof right === "string") return normalizeString(left) === normalizeString(right);
+  if (Array.isArray(left) && Array.isArray(right)) {
+    return left.length === right.length && left.every((item, index) => valuesEqual(item, right[index]));
+  }
+  return left === right;
+}
+function evaluateFieldCondition(condition, currentAnswers) {
+  const sourceId = "fieldId" in condition ? condition.fieldId : condition.questionId;
+  const answer = currentAnswers[sourceId];
+  if (isEmpty(answer) && ["equals", "not_equals", "contains"].includes(condition.operator)) return false;
+  if (condition.operator === "is_empty") return isEmpty(answer);
+  if (condition.operator === "is_not_empty" || condition.operator === "not_empty") return !isEmpty(answer);
+  if (condition.operator === "contains" || condition.operator === "not_contains") {
+    const contains = typeof answer === "string" && typeof condition.value === "string" ? normalizeString(answer).includes(normalizeString(condition.value)) : Array.isArray(answer) && answer.some((item) => valuesEqual(item, condition.value));
+    return condition.operator === "not_contains" ? !contains : contains;
+  }
+  if (condition.value === void 0) return false;
+  if (condition.operator === "equals") return valuesEqual(answer, condition.value);
+  if (condition.operator === "not_equals") return !valuesEqual(answer, condition.value);
+  if (condition.operator === "greater_than")
+    return typeof answer === "number" && typeof condition.value === "number" && answer > condition.value;
+  if (condition.operator === "less_than")
+    return typeof answer === "number" && typeof condition.value === "number" && answer < condition.value;
+  return false;
+}
+function isDisplayConditionGroupSatisfied(group, currentAnswers) {
+  const results = group.conditions.map(
+    (condition) => "logic" in condition ? isDisplayConditionGroupSatisfied(condition, currentAnswers) : evaluateFieldCondition(condition, currentAnswers)
+  );
+  return group.logic === "all" ? results.every(Boolean) : results.some(Boolean);
 }
 function isQuestionVisible(question, currentAnswers) {
+  if (question.displayRule !== void 0) {
+    const satisfied = isDisplayConditionGroupSatisfied(question.displayRule.condition, currentAnswers);
+    return question.displayRule.action === "hide" ? !satisfied : satisfied;
+  }
   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;
-  if (condition.operator === "not_empty") return true;
-  if (condition.value === void 0) return false;
-  if (condition.operator === "equals") return valuesEqual(answer, condition.value);
-  if (condition.operator === "not_equals") return !valuesEqual(answer, condition.value);
-  if (typeof answer === "string" && typeof condition.value === "string") {
-    return normalizeString(answer).includes(normalizeString(condition.value));
-  }
-  return Array.isArray(answer) && answer.some((item) => valuesEqual(item, condition.value));
+  if ("logic" in condition) return isDisplayConditionGroupSatisfied(condition, currentAnswers);
+  return evaluateFieldCondition(condition, currentAnswers);
+}
+function conditionSourceIds(condition) {
+  if (condition === void 0) return [];
+  if ("questionId" in condition) return [condition.questionId];
+  const ids = [];
+  const visit = (group) => {
+    for (const item of group.conditions) {
+      if ("logic" in item) visit(item);
+      else ids.push(item.fieldId);
+    }
+  };
+  visit(condition.condition);
+  return ids;
 }
 function calculateBaseFieldVisibility(schema, currentAnswers) {
   const fields = new Map(schema.fields.map((field) => [field.id, field]));
@@ -1052,10 +1216,12 @@ function calculateBaseFieldVisibility(schema, currentAnswers) {
     if (existing !== void 0) return existing;
     if (resolving.has(field.id)) return false;
     resolving.add(field.id);
-    const sourceId = field.displayCondition?.questionId;
-    const source = sourceId === void 0 ? void 0 : fields.get(sourceId);
-    const sourceVisible = source === void 0 ? sourceId === void 0 : resolve(source);
-    const visible = sourceVisible && isQuestionVisible(field, currentAnswers);
+    const sources = field.displayRule === void 0 ? conditionSourceIds(field.displayCondition) : conditionSourceIds(field.displayRule);
+    const sourcesVisible = sources.every((sourceId) => {
+      const source = fields.get(sourceId);
+      return source !== void 0 && source.id !== field.id && resolve(source);
+    });
+    const visible = sourcesVisible && isQuestionVisible(field, currentAnswers);
     resolving.delete(field.id);
     resolved.set(field.id, visible);
     return visible;
@@ -2053,6 +2219,39 @@ function createSubmission(schema, values, options) {
 }
 
 // src/translation.ts
+var isManualTranslationMetadata = (metadata) => {
+  if (metadata === void 0) return false;
+  if ("isManuallyEdited" in metadata && metadata.isManuallyEdited === true || "isManual" in metadata && metadata.isManual === true)
+    return true;
+  return typeof metadata.translationSource === "string" && metadata.translationSource.toLowerCase() === "manual";
+};
+var computeSourceTextHash = (text) => {
+  const normalized = text.normalize("NFKC").trim().replace(/\s+/gu, " ");
+  let hash = 2166136261;
+  for (let index = 0; index < normalized.length; index += 1) {
+    hash ^= normalized.charCodeAt(index);
+    hash = Math.imul(hash, 16777619);
+  }
+  return (hash >>> 0).toString(16).padStart(8, "0");
+};
+function getTranslationStatus(sourceText, translatedText, metadata) {
+  return getTranslationStatusWithManualOverride(sourceText, translatedText, metadata, void 0);
+}
+function getTranslationStatusWithManualOverride(sourceText, translatedText, metadata, manualOverride) {
+  if (translatedText === void 0 || translatedText.trim() === "") return "missing";
+  if (metadata === void 0) return "translated";
+  const currentHash = computeSourceTextHash(sourceText);
+  const sourceHash = typeof metadata.sourceTextHash === "string" ? metadata.sourceTextHash : void 0;
+  const isManual = manualOverride ?? isManualTranslationMetadata(metadata);
+  if (isManual) return sourceHash === void 0 || sourceHash === currentHash ? "manual" : "manual-stale";
+  return sourceHash === void 0 || sourceHash === currentHash ? "translated" : "stale";
+}
+async function translateBatch(adapter, texts, locale, sourceLocale) {
+  if ("translateBatch" in adapter) return adapter.translateBatch(texts, locale, sourceLocale);
+  return texts.map(
+    (text) => adapter.translate(text, locale, sourceLocale === void 0 ? void 0 : { sourceLocale }) ?? text
+  );
+}
 function mergeLocalizedText(translations, locale, property, value) {
   return { ...translations, [locale]: { ...translations?.[locale], [property]: value } };
 }
@@ -2069,19 +2268,27 @@ function withTranslationMetadata(node, locale, property, metadata) {
     }
   };
 }
-function createSlot(kind, nodeId, property, locale, sourceText, existingText, nodeMetadata, existingTranslationMetadata) {
+function createSlot(kind, nodeId, property, locale, sourceText, existingText, nodeMetadata, existingTranslationMetadata, options = {}) {
+  const path = `${kind}.${nodeId}.${property}`;
+  const manual = options.isManualTranslation?.(existingTranslationMetadata, { path, locale }) ?? isManualTranslationMetadata(existingTranslationMetadata);
+  const normalizedMetadata = existingTranslationMetadata === void 0 ? void 0 : options.normalizeMetadata === void 0 ? existingTranslationMetadata : { ...options.normalizeMetadata(existingTranslationMetadata, sourceText) };
+  const status = getTranslationStatusWithManualOverride(sourceText, existingText, normalizedMetadata, manual);
   return {
     kind,
     nodeId,
     property,
     locale,
     sourceText,
+    target: { kind, ...nodeId.length === 0 ? {} : { id: nodeId }, property },
+    path,
+    sourceTextHash: computeSourceTextHash(sourceText),
+    status,
     ...existingText === void 0 ? {} : { existingText },
     ...nodeMetadata === void 0 ? {} : { nodeMetadata, metadata: nodeMetadata },
-    ...existingTranslationMetadata === void 0 ? {} : { existingTranslationMetadata }
+    ...normalizedMetadata === void 0 ? {} : { existingTranslationMetadata: normalizedMetadata }
   };
 }
-function translationSlots(schema, locale) {
+function translationSlots(schema, locale, options = {}) {
   const descriptors = [];
   const addFormSlot = (property, sourceText) => {
     const slot = createSlot(
@@ -2092,10 +2299,15 @@ function translationSlots(schema, locale) {
       sourceText,
       schema.translations?.[locale]?.[property],
       schema.metadata,
-      schema.translationMetadata?.[locale]?.[property]
+      schema.translationMetadata?.[locale]?.[property],
+      options
     );
     descriptors.push({
       slot,
+      manual: options.isManualTranslation?.(schema.translationMetadata?.[locale]?.[property], {
+        path: slot.path ?? "",
+        locale
+      }) ?? isManualTranslationMetadata(schema.translationMetadata?.[locale]?.[property]),
       apply: (current, value, metadata) => withTranslationMetadata(
         { ...current, translations: mergeLocalizedText(current.translations, locale, property, value) },
         locale,
@@ -2117,10 +2329,15 @@ function translationSlots(schema, locale) {
         sourceText,
         field.translations?.[locale]?.[property],
         field.metadata,
-        field.translationMetadata?.[locale]?.[property]
+        field.translationMetadata?.[locale]?.[property],
+        options
       );
       descriptors.push({
         slot,
+        manual: options.isManualTranslation?.(field.translationMetadata?.[locale]?.[property], {
+          path: slot.path ?? "",
+          locale
+        }) ?? isManualTranslationMetadata(field.translationMetadata?.[locale]?.[property]),
         apply: (current, value, metadata) => ({
           ...current,
           fields: current.fields.map(
@@ -2149,10 +2366,15 @@ function translationSlots(schema, locale) {
           option.label,
           option.translations?.[locale],
           option.metadata,
-          option.translationMetadata?.[locale]?.label
+          option.translationMetadata?.[locale]?.label,
+          options
         );
         descriptors.push({
           slot,
+          manual: options.isManualTranslation?.(option.translationMetadata?.[locale]?.label, {
+            path: slot.path ?? "",
+            locale
+          }) ?? isManualTranslationMetadata(option.translationMetadata?.[locale]?.label),
           apply: (current, value, metadata) => ({
             ...current,
             fields: current.fields.map((candidate, candidateIndex) => {
@@ -2187,10 +2409,15 @@ function translationSlots(schema, locale) {
         sourceText,
         page.translations?.[locale]?.[property],
         page.metadata,
-        page.translationMetadata?.[locale]?.[property]
+        page.translationMetadata?.[locale]?.[property],
+        options
       );
       descriptors.push({
         slot,
+        manual: options.isManualTranslation?.(page.translationMetadata?.[locale]?.[property], {
+          path: slot.path ?? "",
+          locale
+        }) ?? isManualTranslationMetadata(page.translationMetadata?.[locale]?.[property]),
         apply: (current, value, metadata) => ({
           ...current,
           ...current.pages === void 0 ? {} : {
@@ -2214,6 +2441,125 @@ function translationSlots(schema, locale) {
   });
   return descriptors;
 }
+function removeLocaleRecord(record, locale) {
+  if (record === void 0) return void 0;
+  const remaining = Object.entries(record).filter(([candidate]) => candidate !== locale);
+  return remaining.length === 0 ? void 0 : Object.fromEntries(remaining);
+}
+function removeLocalizedNodeLocale(node, locale) {
+  const translations = removeLocaleRecord(node.translations, locale);
+  const translationMetadata = removeLocaleRecord(node.translationMetadata, locale);
+  const { translations: _translations, translationMetadata: _translationMetadata, ...base } = node;
+  return {
+    ...base,
+    ...translations === void 0 ? {} : { translations },
+    ...translationMetadata === void 0 ? {} : { translationMetadata }
+  };
+}
+function migrateMetadata(metadata, sourceText, defaultLocale, customMigrator) {
+  if (customMigrator !== void 0) return customMigrator(metadata, sourceText);
+  const record = metadata !== null && typeof metadata === "object" ? metadata : void 0;
+  const sourceLocale = typeof record?.sourceLocale === "string" ? record.sourceLocale : defaultLocale ?? "";
+  const translationSource = isManualTranslationMetadata(record) ? "manual" : "automatic";
+  return {
+    sourceLocale,
+    sourceTextHash: computeSourceTextHash(sourceText),
+    translationSource,
+    ...typeof record?.translatedAt === "string" ? { translatedAt: record.translatedAt } : {},
+    ...typeof record?.editedAt === "string" ? { editedAt: record.editedAt } : {}
+  };
+}
+function migrateNodeMetadata(node, sourceTexts, defaultLocale, customMigrator) {
+  if (node.translationMetadata === void 0) return node;
+  const translationMetadata = Object.fromEntries(
+    Object.entries(node.translationMetadata).map(([locale, properties]) => [
+      locale,
+      Object.fromEntries(
+        Object.entries(properties).map(([property, metadata]) => [
+          property,
+          migrateMetadata(metadata, sourceTexts[property] ?? "", defaultLocale, customMigrator)
+        ])
+      )
+    ])
+  );
+  return { ...node, translationMetadata };
+}
+var migrateSchemaTranslationMetadata = (schema, customMigrator) => {
+  const migratedSchema = migrateNodeMetadata(
+    schema,
+    {
+      title: schema.title,
+      ...schema.description === void 0 ? {} : { description: schema.description },
+      ...schema.completionMessage === void 0 ? {} : { completionMessage: schema.completionMessage }
+    },
+    schema.defaultLocale,
+    customMigrator
+  );
+  const fields = schema.fields.map((field) => {
+    const migratedField = migrateNodeMetadata(
+      field,
+      { title: field.title, ...field.description === void 0 ? {} : { description: field.description } },
+      schema.defaultLocale,
+      customMigrator
+    );
+    if (!("options" in migratedField)) return migratedField;
+    return {
+      ...migratedField,
+      options: migratedField.options.map(
+        (option) => migrateNodeMetadata(option, { label: option.label }, schema.defaultLocale, customMigrator)
+      )
+    };
+  });
+  const pages = schema.pages?.map(
+    (page) => migrateNodeMetadata(
+      page,
+      {
+        ...page.title === void 0 ? {} : { title: page.title },
+        ...page.description === void 0 ? {} : { description: page.description }
+      },
+      schema.defaultLocale,
+      customMigrator
+    )
+  );
+  return {
+    ...migratedSchema,
+    fields,
+    ...pages === void 0 ? {} : { pages }
+  };
+};
+var removeLocaleFromSchema = (schema, localeToRemove) => {
+  if (localeToRemove === schema.defaultLocale) {
+    throw new Error(`Cannot remove defaultLocale: ${localeToRemove}`);
+  }
+  const form = removeLocalizedNodeLocale(schema, localeToRemove);
+  const fields = schema.fields.map((field) => {
+    const localizedField = removeLocalizedNodeLocale(field, localeToRemove);
+    if (!("options" in localizedField)) return localizedField;
+    return {
+      ...localizedField,
+      options: localizedField.options.map((option) => {
+        const translations = removeLocaleRecord(option.translations, localeToRemove);
+        const translationMetadata = removeLocaleRecord(option.translationMetadata, localeToRemove);
+        const { translations: _translations, translationMetadata: _translationMetadata, ...base } = option;
+        return {
+          ...base,
+          ...translations === void 0 ? {} : { translations },
+          ...translationMetadata === void 0 ? {} : { translationMetadata }
+        };
+      })
+    };
+  });
+  const pages = schema.pages?.map((page) => removeLocalizedNodeLocale(page, localeToRemove));
+  return {
+    ...form,
+    supportedLocales: (schema.supportedLocales ?? []).filter((locale) => locale !== localeToRemove),
+    fields,
+    ...pages === void 0 ? {} : { pages }
+  };
+};
+function collectTranslationSlots(schema, locale) {
+  return translationSlots(schema, locale).map((descriptor) => descriptor.slot);
+}
 function resolveLocalizedSchema(schema, targetLocale) {
   if (targetLocale === void 0 || targetLocale.length === 0 || targetLocale === schema.defaultLocale) return schema;
   const formTranslation = schema.translations?.[targetLocale];
@@ -2270,17 +2616,32 @@ async function populateSchemaTranslations(schema, targetLocales, adapter, option
   }
   const updatedSlots = [];
   const skippedSlots = [];
+  const staleSlots = [];
+  const skippedReasons = {};
   let result = schema;
   for (const locale of locales) {
-    const descriptors = translationSlots(schema, locale);
+    const descriptors = translationSlots(schema, locale, options);
+    if (options.markStaleTranslations ?? true) {
+      for (const descriptor of descriptors) {
+        if (descriptor.slot.status === "stale" || descriptor.slot.status === "manual-stale")
+          staleSlots.push(descriptor.slot);
+      }
+    }
     const selected = [];
     for (const descriptor of descriptors) {
-      const shouldTranslate = options.shouldOverwrite?.(descriptor.slot) ?? (options.overwrite === "all" || descriptor.slot.existingText === void 0);
+      const status = descriptor.slot.status ?? "missing";
+      const manual = descriptor.manual || status === "manual" || status === "manual-stale";
+      const requestedOverwrite = options.shouldOverwrite?.(descriptor.slot);
+      const shouldTranslate = (options.preserveManualTranslations ?? true) && manual ? false : requestedOverwrite ?? (options.overwrite === "all" || (options.overwrite === "stale-and-missing" || options.overwrite === void 0 ? status === "missing" || status === "stale" || !(options.preserveManualTranslations ?? true) && status === "manual-stale" : status === "missing"));
       if (shouldTranslate) selected.push(descriptor);
-      else skippedSlots.push(descriptor.slot);
+      else {
+        skippedSlots.push(descriptor.slot);
+        skippedReasons[descriptor.slot.path ?? `${descriptor.slot.kind}.${descriptor.slot.nodeId}.${descriptor.slot.property}`] = manual ? "manual" : "unchanged";
+      }
     }
     if (selected.length === 0) continue;
-    const translated = await adapter.translateBatch(
+    const translated = await translateBatch(
+      adapter,
       selected.map((descriptor) => descriptor.slot.sourceText),
       locale,
       schema.defaultLocale
@@ -2291,7 +2652,12 @@ async function populateSchemaTranslations(schema, targetLocales, adapter, option
     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);
+      const metadata = options.createMetadata?.(descriptor.slot, translatedText) ?? {
+        sourceLocale: schema.defaultLocale ?? "",
+        sourceTextHash: computeSourceTextHash(descriptor.slot.sourceText),
+        translationSource: "automatic",
+        translatedAt: (/* @__PURE__ */ new Date()).toISOString()
+      };
       result = descriptor.apply(result, translatedText, metadata);
       updatedSlots.push(descriptor.slot);
     });
@@ -2305,7 +2671,7 @@ async function populateSchemaTranslations(schema, targetLocales, adapter, option
   ];
   if (supportedLocales.length > 0) result = { ...result, supportedLocales };
   assertValidFormSchema(result);
-  return { schema: result, report: { updatedSlots, skippedSlots } };
+  return { schema: result, report: { updatedSlots, skippedSlots, staleSlots, skippedReasons } };
 }
 async function resolveFormTranslation(schema, adapter, targetLocale, sourceLocale) {
   const populated = await populateSchemaTranslations(
@@ -2609,6 +2975,8 @@ function assertVersionMutable(status) {
   calculatePageVisibility,
   cloneVersionToDraft,
   collectSchemaLocales,
+  collectTranslationSlots,
+  computeSourceTextHash,
   createCloneTransitionPlan,
   createDeleteDraftTransitionPlan,
   createPublishTransitionPlan,
@@ -2623,16 +2991,21 @@ function assertVersionMutable(status) {
   escapeCsvCell,
   exportResponsesToCsv,
   exportResponsesToCsvStream,
+  getTranslationStatus,
+  isDisplayConditionGroupSatisfied,
   isDisplayConditionSatisfied,
+  isManualTranslationMetadata,
   isQuestionVisible,
   iterateSubmissionPages,
   jsonValuesEqual,
   matchesSubmissionFilter,
   matchesSubmissionPageFilters,
+  migrateSchemaTranslationMetadata,
   normalizeSubmissionPageSize,
   pipeResponsesToCsvStream,
   populateSchemaTranslations,
   publishDraft,
+  removeLocaleFromSchema,
   resolveFormTranslation,
   resolveLocalizedSchema,
   sanitizeSchema,