@form-engine-ts/core 5.0.1 → 6.0.0

package/README.md

@@ -56,6 +56,11 @@ translation adapter runs.
 `ja_JP`, and returns `null` for invalid tags. Schema validation, sanitization, locale policy checks, and translation
 slot lookup use this same normalization so equivalent locale spellings cannot bypass constraints.
 
+Submissions use `values` as their canonical answer property. `toFormSubmissionWire` and
+`fromFormSubmissionWire` preserve the optional submission `locale` across validated wire payloads. Legacy payloads with
+`answers` are isolated under `LegacyFormSubmission` and `fromLegacyFormSubmission` in the compatibility namespace.
+`serializeSubmissionError` and `deserializeSubmissionError` provide the JSON boundary for `FormSubmissionError`.
+
 Fields can use a `displayRule` with nested `all`/`any` condition groups and `show` or `hide` actions. Supported
 operators include equality, containment, emptiness, and numeric comparisons; the legacy `displayCondition` and
 `not_empty` forms remain supported. `submissionSettings` can enable pre-submit confirmation and select its

package/dist/index.cjs

@@ -22,6 +22,9 @@ var index_exports = {};
 __export(index_exports, {
   DEFAULT_FIELD_TYPE_DEFINITIONS: () => DEFAULT_FIELD_TYPE_DEFINITIONS,
   EN_MESSAGES: () => EN_MESSAGES,
+  FormSubmissionError: () => FormSubmissionError,
+  FormSubmissionMetadataSchema: () => FormSubmissionMetadataSchema,
+  FormSubmissionWireSchema: () => FormSubmissionWireSchema,
   JA_MESSAGES: () => JA_MESSAGES,
   aggregateResponses: () => aggregateResponses,
   applyTransitionPlan: () => applyTransitionPlan,
@@ -48,6 +51,7 @@ __export(index_exports, {
   decodeSubmissionCursor: () => decodeSubmissionCursor,
   decodeTextAnswerCursor: () => decodeTextAnswerCursor,
   deleteDraft: () => deleteDraft,
+  deserializeSubmissionError: () => deserializeSubmissionError,
   dispatchWebhook: () => dispatchWebhook,
   encodeStorageSubmissionCursor: () => encodeStorageSubmissionCursor,
   encodeStorageTextAnswerCursor: () => encodeStorageTextAnswerCursor,
@@ -56,6 +60,8 @@ __export(index_exports, {
   escapeCsvCell: () => escapeCsvCell,
   exportResponsesToCsv: () => exportResponsesToCsv,
   exportResponsesToCsvStream: () => exportResponsesToCsvStream,
+  fromFormSubmissionWire: () => fromFormSubmissionWire,
+  fromLegacyFormSubmission: () => fromLegacyFormSubmission,
   getTranslationStatus: () => getTranslationStatus,
   isDisplayConditionGroupSatisfied: () => isDisplayConditionGroupSatisfied,
   isDisplayConditionSatisfied: () => isDisplayConditionSatisfied,
@@ -77,6 +83,8 @@ __export(index_exports, {
   resolveLocalizedSchema: () => resolveLocalizedSchema,
   sanitizeSchema: () => sanitizeSchema,
   selectVisibleAnswers: () => selectVisibleAnswers,
+  serializeSubmissionError: () => serializeSubmissionError,
+  toFormSubmissionWire: () => toFormSubmissionWire,
   transformFieldType: () => transformFieldType,
   validateAnswers: () => validateAnswers,
   validateFormSchema: () => validateFormSchema,
@@ -1474,7 +1482,7 @@ function aggregateResponses(schema, submissions) {
 function responseValues(submission) {
   if (typeof submission !== "object" || submission === null) return void 0;
   if ("values" in submission) return submission.values;
-  return "answers" in submission ? submission.answers : void 0;
+  return submission.answers;
 }
 function responseIdentifier(submission) {
   if (typeof submission !== "object" || submission === null) return "<unknown>";
@@ -1670,14 +1678,17 @@ function serializeValue(value) {
 }
 function asFormResponse(submission) {
   if (!("values" in submission)) return submission;
+  const metadata = submission.metadata === void 0 ? void 0 : Object.fromEntries(
+    Object.entries(submission.metadata).filter((entry) => entry[1] !== void 0)
+  );
   return {
     responseId: submission.id,
     formId: submission.formId,
-    sourceLocale: submission.locale,
+    ...submission.locale === void 0 ? {} : { sourceLocale: submission.locale },
     formVersion: submission.formVersion,
     answers: submission.values,
     submittedAt: submission.submittedAt,
-    ...submission.metadata === void 0 ? {} : { metadata: submission.metadata },
+    ...metadata === void 0 ? {} : { metadata },
     ...submission.translationMetadata === void 0 ? {} : { translationMetadata: submission.translationMetadata }
   };
 }
@@ -1686,15 +1697,28 @@ function serializeUnknown(value) {
   if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") return value;
   return JSON.stringify(value);
 }
+function submissionWithMetadata(submission) {
+  return { ...submission, metadata: submission.metadata ?? {} };
+}
 async function* exportResponsesToCsvStream(schema, submissions, options = {}) {
   assertValidFormSchema(schema);
   const includeDefaultColumns = options.includeDefaultColumns ?? true;
   const customColumns = options.columns ?? [];
+  const contractColumns = options.customColumns ?? [];
+  const includeLocale = options.includeLocale ?? true;
+  const includePiiStatus = options.includePiiStatus ?? false;
   const headers = [
-    ...includeDefaultColumns ? ["submissionId", "submittedAt", "locale", ...schema.fields.map((field) => field.id)] : [],
-    ...customColumns.map((column) => column.header)
+    ...includeDefaultColumns ? [
+      "submissionId",
+      "submittedAt",
+      ...includeLocale ? ["locale"] : [],
+      ...includePiiStatus ? ["piiStatus"] : [],
+      ...schema.fields.map((field) => field.id)
+    ] : [],
+    ...customColumns.map((column) => column.header),
+    ...contractColumns.map((column) => column.header)
   ];
-  const neutralizeFormulas = options.neutralizeFormulas ?? true;
+  const neutralizeFormulas = options.preventFormulaInjection ?? options.neutralizeFormulas ?? true;
   const header = headers.map((value) => escapeCsvCell(value, neutralizeFormulas)).join(",");
   yield `${options.withBom ?? true ? "\uFEFF" : ""}${header}`;
   for await (const submission of submissions) {
@@ -1703,10 +1727,12 @@ async function* exportResponsesToCsvStream(schema, submissions, options = {}) {
     const response = asFormResponse(submission);
     const answers = response.answers;
     const visible = selectVisibleAnswers(schema, answers);
+    const piiStatus = response.metadata?.piiConfirmed === true ? "confirmed" : "unconfirmed";
     const defaultCells = includeDefaultColumns ? [
       response.responseId,
       response.submittedAt,
-      response.sourceLocale ?? "",
+      ...includeLocale ? [response.sourceLocale ?? ""] : [],
+      ...includePiiStatus ? [piiStatus] : [],
       ...schema.fields.map((field) => serializeUnknown(visible[field.id]))
     ] : [];
     const context = {
@@ -1716,8 +1742,9 @@ async function* exportResponsesToCsvStream(schema, submissions, options = {}) {
       schema
     };
     const customCells = await Promise.all(customColumns.map((column) => column.getValue(context)));
+    const contractCells = "values" in submission ? contractColumns.map((column) => column.getValue(submissionWithMetadata(submission), schema)) : contractColumns.map(() => void 0);
     yield `\r
-${[...defaultCells, ...customCells].map((value) => escapeCsvCell(value, neutralizeFormulas)).join(",")}`;
+${[...defaultCells, ...customCells, ...contractCells].map((value) => escapeCsvCell(value, neutralizeFormulas)).join(",")}`;
   }
 }
 function isWebWritableStream(writable) {
@@ -1774,23 +1801,68 @@ function exportResponsesToCsv(schema, responses, options = {}) {
       throw new TypeError(`Submission ${response.id} does not match ${schema.id}@${schema.version}.`);
     }
   }
+  const includeLocale = options.includeLocale ?? true;
+  const includePiiStatus = options.includePiiStatus ?? false;
+  const customColumns = options.customColumns ?? [];
+  const headers = [
+    "submissionId",
+    "submittedAt",
+    ...includeLocale ? ["locale"] : [],
+    ...includePiiStatus ? ["piiStatus"] : [],
+    ...schema.fields.map((field) => field.id),
+    ...customColumns.map((column) => column.header)
+  ];
   const rows = [
-    ["submissionId", "submittedAt", "locale", ...schema.fields.map((field) => field.id)],
+    headers,
     ...responses.map((response) => {
       const visible = selectVisibleAnswers(schema, response.values);
+      const piiStatus = response.metadata?.piiConfirmed === true ? "confirmed" : "unconfirmed";
+      const submissionForCustomColumns = submissionWithMetadata(response);
       return [
         response.id,
         response.submittedAt,
-        response.locale,
-        ...schema.fields.map((field) => serializeValue(visible[field.id]))
+        ...includeLocale ? [response.locale] : [],
+        ...includePiiStatus ? [piiStatus] : [],
+        ...schema.fields.map((field) => serializeValue(visible[field.id])),
+        ...customColumns.map((column) => column.getValue(submissionForCustomColumns, schema))
       ];
     })
   ];
-  const neutralizeFormulas = options.neutralizeFormulas ?? true;
+  const neutralizeFormulas = options.preventFormulaInjection ?? 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;
+  return options.useBom ?? options.withBom ?? true ? `\uFEFF${csv}` : csv;
 }
 
+// src/compat/legacy.ts
+var fromLegacyFormSubmission = (legacy) => {
+  const { id, formId, formVersion, answers, locale, metadata, submittedAt, schemaRevision } = legacy;
+  return {
+    id,
+    formId,
+    formVersion,
+    values: { ...answers },
+    ...locale === void 0 ? {} : { locale },
+    metadata,
+    submittedAt,
+    ...schemaRevision === void 0 ? {} : { schemaRevision }
+  };
+};
+
+// src/errors.ts
+var FormSubmissionError = class extends Error {
+  payload;
+  constructor(payload) {
+    super(payload.messageKey);
+    this.name = "FormSubmissionError";
+    this.payload = payload;
+  }
+  toJSON() {
+    return this.payload;
+  }
+};
+var serializeSubmissionError = (error) => error.toJSON();
+var deserializeSubmissionError = (json) => new FormSubmissionError(json);
+
 // src/events.ts
 function bytesToHex(bytes) {
   return [...new Uint8Array(bytes)].map((byte) => byte.toString(16).padStart(2, "0")).join("");
@@ -2113,7 +2185,20 @@ var EN_MESSAGES = Object.freeze({
   "workspace.errors.maxLocalesExceeded": "The maximum number of locales ({{max}}) has been reached.",
   "workspace.errors.readOnly": "This workspace is read-only.",
   "workspace.errors.adapterNotConfigured": "A translation adapter is not configured.",
-  "workspace.errors.translationFailed": "Translation failed."
+  "workspace.errors.translationFailed": "Translation failed.",
+  "workspace.header.title": "Translation workspace",
+  "workspace.header.sourceLocale": "Source language",
+  "workspace.header.targetLocale": "Target language",
+  "workspace.header.translateAll": "Translate all",
+  "workspace.header.progress": "{{translated}}/{{total}} translated ({{percent}}%)",
+  "workspace.slot.sourceText": "Source",
+  "workspace.slot.translatedText": "Translation",
+  "workspace.slot.translateSingle": "Translate this slot",
+  "workspace.slot.revertManual": "Revert manual translation",
+  "workspace.confirm.removeLocaleTitle": "Remove language?",
+  "workspace.confirm.removeLocaleMessage": "This will remove {{locale}} and its translations.",
+  "workspace.empty.noTargetLocales": "No target languages are configured.",
+  "workspace.empty.noSlotsToTranslate": "There are no translation slots for this language."
 });
 
 // src/i18n/catalogs/ja.ts
@@ -2285,7 +2370,20 @@ var JA_MESSAGES = Object.freeze({
   "workspace.errors.maxLocalesExceeded": "\u767B\u9332\u53EF\u80FD\u306A\u6700\u5927\u8A00\u8A9E\u6570 ({{max}}) \u306B\u9054\u3057\u307E\u3057\u305F\u3002",
   "workspace.errors.readOnly": "\u8AAD\u307F\u53D6\u308A\u5C02\u7528\u30E2\u30FC\u30C9\u306E\u305F\u3081\u5909\u66F4\u3067\u304D\u307E\u305B\u3093\u3002",
   "workspace.errors.adapterNotConfigured": "\u7FFB\u8A33\u30A2\u30C0\u30D7\u30BF\u30FC\u304C\u8A2D\u5B9A\u3055\u308C\u3066\u3044\u307E\u305B\u3093\u3002",
-  "workspace.errors.translationFailed": "\u7FFB\u8A33\u51E6\u7406\u306B\u5931\u6557\u3057\u307E\u3057\u305F\u3002"
+  "workspace.errors.translationFailed": "\u7FFB\u8A33\u51E6\u7406\u306B\u5931\u6557\u3057\u307E\u3057\u305F\u3002",
+  "workspace.header.title": "\u591A\u8A00\u8A9E\u7FFB\u8A33\u30EF\u30FC\u30AF\u30B9\u30DA\u30FC\u30B9",
+  "workspace.header.sourceLocale": "\u5143\u8A00\u8A9E",
+  "workspace.header.targetLocale": "\u7FFB\u8A33\u8A00\u8A9E",
+  "workspace.header.translateAll": "\u4E00\u62EC\u81EA\u52D5\u7FFB\u8A33",
+  "workspace.header.progress": "{{translated}}/{{total}} \u7FFB\u8A33\u6E08\u307F ({{percent}}%)",
+  "workspace.slot.sourceText": "\u539F\u6587",
+  "workspace.slot.translatedText": "\u7FFB\u8A33\u6587",
+  "workspace.slot.translateSingle": "\u3053\u306E\u9805\u76EE\u3092\u7FFB\u8A33",
+  "workspace.slot.revertManual": "\u624B\u52D5\u7FFB\u8A33\u3092\u5143\u306B\u623B\u3059",
+  "workspace.confirm.removeLocaleTitle": "\u8A00\u8A9E\u3092\u524A\u9664\u3057\u307E\u3059\u304B\uFF1F",
+  "workspace.confirm.removeLocaleMessage": "{{locale}} \u3068\u305D\u306E\u7FFB\u8A33\u3092\u524A\u9664\u3057\u307E\u3059\u3002",
+  "workspace.empty.noTargetLocales": "\u7FFB\u8A33\u5148\u306E\u8A00\u8A9E\u304C\u8A2D\u5B9A\u3055\u308C\u3066\u3044\u307E\u305B\u3093\u3002",
+  "workspace.empty.noSlotsToTranslate": "\u3053\u306E\u8A00\u8A9E\u306B\u306F\u7FFB\u8A33\u9805\u76EE\u304C\u3042\u308A\u307E\u305B\u3093\u3002"
 });
 
 // src/i18n/translator.ts
@@ -2347,14 +2445,17 @@ async function paginateWithFilter(params) {
   return { items: collected, hasMore: false, totalScannedCount };
 }
 function asFormResponse2(submission) {
+  const metadata = submission.metadata === void 0 ? void 0 : Object.fromEntries(
+    Object.entries(submission.metadata).filter((entry) => entry[1] !== void 0)
+  );
   return {
     responseId: submission.id,
     formId: submission.formId,
     formVersion: submission.formVersion,
-    sourceLocale: submission.locale,
+    ...submission.locale === void 0 ? {} : { sourceLocale: submission.locale },
     answers: submission.values,
     submittedAt: submission.submittedAt,
-    ...submission.metadata === void 0 ? {} : { metadata: submission.metadata }
+    ...metadata === void 0 ? {} : { metadata }
   };
 }
 async function* iterateSubmissionPages(adapter, formId, queryOptions = {}, options = {}) {
@@ -2574,6 +2675,20 @@ function matchesSubmissionPageFilters(submission, options) {
   );
 }
 
+// src/schemas/submission.zod.ts
+var import_zod = require("zod");
+var FormSubmissionMetadataSchema = import_zod.z.record(import_zod.z.string(), import_zod.z.unknown());
+var FormSubmissionWireSchema = import_zod.z.object({
+  id: import_zod.z.string().min(1),
+  formId: import_zod.z.string().min(1),
+  formVersion: import_zod.z.number().int().positive(),
+  values: import_zod.z.record(import_zod.z.string(), import_zod.z.unknown()),
+  locale: import_zod.z.string().min(1).optional(),
+  metadata: FormSubmissionMetadataSchema,
+  submittedAt: import_zod.z.string().datetime(),
+  schemaRevision: import_zod.z.number().int().optional()
+});
+
 // src/validation.ts
 var DEFAULT_MESSAGES = {
   required: "validation.required",
@@ -2754,6 +2869,33 @@ function toFormValues(answers) {
 function isFormValue(value) {
   return value === void 0 || typeof value === "string" || typeof value === "number" || typeof value === "boolean" || Array.isArray(value) && value.every((item) => typeof item === "string");
 }
+function toFormSubmissionWire(submission) {
+  const { id, formId, formVersion, values, locale, metadata, submittedAt, schemaRevision } = submission;
+  return {
+    id,
+    formId,
+    formVersion,
+    values: { ...values },
+    ...locale === void 0 ? {} : { locale },
+    metadata: { ...metadata ?? {} },
+    submittedAt,
+    ...schemaRevision === void 0 ? {} : { schemaRevision }
+  };
+}
+function fromFormSubmissionWire(wire) {
+  const { id, formId, formVersion, values, locale, metadata, submittedAt, schemaRevision } = wire;
+  const canonicalMetadata = { ...metadata };
+  return {
+    id,
+    formId,
+    formVersion,
+    values: { ...values },
+    ...locale === void 0 ? {} : { locale },
+    metadata: canonicalMetadata,
+    submittedAt,
+    ...schemaRevision === void 0 ? {} : { schemaRevision }
+  };
+}
 function createSubmission(schemaOrInput, values, options) {
   if ("answers" in schemaOrInput) {
     const input = schemaOrInput;
@@ -2773,7 +2915,6 @@ function createSubmission(schemaOrInput, values, options) {
       formVersion: input.formVersion,
       locale: "",
       values: Object.freeze(cloneValues(toFormValues(answers))),
-      answers,
       metadata: input.metadata,
       submittedAt,
       ...input.schemaRevision === void 0 ? {} : { schemaRevision: input.schemaRevision }
@@ -2800,7 +2941,6 @@ function createSubmission(schemaOrInput, values, options) {
     formVersion: schema.version,
     locale: options.locale,
     values: Object.freeze(cloneValues(visibleValues)),
-    answers: Object.freeze({ ...visibleValues }),
     submittedAt: options.submittedAt,
     ...options.metadata === void 0 ? {} : { metadata: Object.freeze({ ...options.metadata }) },
     ...options.translationMetadata === void 0 ? {} : { translationMetadata: Object.freeze({ ...options.translationMetadata }) }
@@ -3177,18 +3317,20 @@ var migrateSchemaTranslationMetadata = (schema, migratorOrOptions) => {
   };
 };
 var removeLocaleFromSchema = (schema, localeToRemove) => {
-  if (localeToRemove === schema.defaultLocale) {
+  const normalizedLocaleToRemove = normalizeLocale(localeToRemove) ?? localeToRemove;
+  const normalizedDefaultLocale = schema.defaultLocale === void 0 ? void 0 : normalizeLocale(schema.defaultLocale) ?? schema.defaultLocale;
+  if (normalizedLocaleToRemove === normalizedDefaultLocale) {
     throw new Error(`Cannot remove defaultLocale: ${localeToRemove}`);
   }
-  const form = removeLocalizedNodeLocale(schema, localeToRemove);
+  const form = removeLocalizedNodeLocale(schema, normalizedLocaleToRemove);
   const fields = schema.fields.map((field) => {
-    const localizedField = removeLocalizedNodeLocale(field, localeToRemove);
+    const localizedField = removeLocalizedNodeLocale(field, normalizedLocaleToRemove);
     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 = removeLocaleRecord(option.translations, normalizedLocaleToRemove);
+        const translationMetadata = removeLocaleRecord(option.translationMetadata, normalizedLocaleToRemove);
         const { translations: _translations, translationMetadata: _translationMetadata, ...base } = option;
         return {
           ...base,
@@ -3198,10 +3340,12 @@ var removeLocaleFromSchema = (schema, localeToRemove) => {
       })
     };
   });
-  const pages = schema.pages?.map((page) => removeLocalizedNodeLocale(page, localeToRemove));
+  const pages = schema.pages?.map((page) => removeLocalizedNodeLocale(page, normalizedLocaleToRemove));
   return {
     ...form,
-    supportedLocales: (schema.supportedLocales ?? []).filter((locale) => locale !== localeToRemove),
+    supportedLocales: (schema.supportedLocales ?? []).filter(
+      (locale) => (normalizeLocale(locale) ?? locale) !== normalizedLocaleToRemove
+    ),
     fields,
     ...pages === void 0 ? {} : { pages }
   };
@@ -3660,6 +3804,9 @@ async function commitVersionTransition(options) {
 0 && (module.exports = {
   DEFAULT_FIELD_TYPE_DEFINITIONS,
   EN_MESSAGES,
+  FormSubmissionError,
+  FormSubmissionMetadataSchema,
+  FormSubmissionWireSchema,
   JA_MESSAGES,
   aggregateResponses,
   applyTransitionPlan,
@@ -3686,6 +3833,7 @@ async function commitVersionTransition(options) {
   decodeSubmissionCursor,
   decodeTextAnswerCursor,
   deleteDraft,
+  deserializeSubmissionError,
   dispatchWebhook,
   encodeStorageSubmissionCursor,
   encodeStorageTextAnswerCursor,
@@ -3694,6 +3842,8 @@ async function commitVersionTransition(options) {
   escapeCsvCell,
   exportResponsesToCsv,
   exportResponsesToCsvStream,
+  fromFormSubmissionWire,
+  fromLegacyFormSubmission,
   getTranslationStatus,
   isDisplayConditionGroupSatisfied,
   isDisplayConditionSatisfied,
@@ -3715,6 +3865,8 @@ async function commitVersionTransition(options) {
   resolveLocalizedSchema,
   sanitizeSchema,
   selectVisibleAnswers,
+  serializeSubmissionError,
+  toFormSubmissionWire,
   transformFieldType,
   validateAnswers,
   validateFormSchema,