@form-engine-ts/core 4.7.0 → 5.0.0

package/README.md

@@ -52,6 +52,9 @@ Required locales cover every source text that exists on the form, its fields, op
 safe maximum-length corrections while purging unregistered locale content. Pass
 `{ policy: { allowedLocales, maxLocales } }` to `populateSchemaTranslations` to reject inadmissible targets before the
 translation adapter runs.
+`normalizeLocale(locale)` returns the canonical BCP 47 tag, accepts underscore-separated compatibility input such as
+`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.
 
 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
@@ -96,6 +99,11 @@ const i18nextAdapter: TranslationAdapter = {
 };
 ```
 
+Core also exports the fully typed `FormEngineTranslationKey` union, `JA_MESSAGES`, `EN_MESSAGES`, and
+`createFormEngineTranslator`. The built-in translator defaults to Japanese, falls back to English, accepts partial
+custom catalogs, formats `{{placeholder}}` values, and returns an empty string for an unresolved key instead of
+exposing the key itself.
+
 Translation callbacks receive `nodeMetadata` and `existingTranslationMetadata` separately. The deprecated `metadata`
 slot property remains an alias for `nodeMetadata` during migration.
 
@@ -120,6 +128,23 @@ const submissions = await storage.listSubmissions("contact", 1, range);
 
 Results are ordered by `submittedAt`, then submission ID. Both boundaries are inclusive.
 
+Submission metadata can be strongly typed at the application boundary:
+
+```ts
+import { createSubmission, validateSubmission } from "@form-engine-ts/core";
+
+const submission = createSubmission<{ deckId: string; piiConfirmed: boolean }>({
+  formId: "guide",
+  formVersion: 1,
+  answers: { title: "Welcome" },
+  metadata: { deckId: "deck_123", piiConfirmed: false }
+});
+submission.metadata.deckId;
+const validation = validateSubmission(schema, submission, { privacyEngine });
+```
+
+`validateSubmission` returns one serializable result containing field errors, form errors, and optional PII findings.
+
 ## Versioning, incremental analytics, and paged storage
 
 `cloneVersionToDraft`, asynchronous `publishDraft`, and `deleteDraft` implement revision-checked version transitions as
@@ -150,6 +175,13 @@ may push supported nodes to their native query language while preserving identic
 implement `listTextAnswerPage` expose stable cursor pagination over individual text answers.
 `TextAnswerPageQueryOptions.fieldIds` can select multiple free-text fields for item-level paging.
 
+The `paginateWithFilter` helper in `@form-engine-ts/storage` continues fetching native pages until `pageSize` matching
+items are collected or the source is exhausted. `totalScannedCount` makes post-filter work observable and
+`maxScanPages` bounds low-density scans.
+
+`commitVersionTransition` accepts a typed `domainData` value and carries it through optional before/after hooks and the
+persistence adapter without interpreting or modifying it.
+
 `iterateSubmissionPages(adapter, formId, query, options)` safely traverses every page as an async generator. It supports
 `pageSize`, `maxItems`, and `AbortSignal`, continues through empty pages with a next cursor, and rejects missing or cyclic
 cursors instead of looping indefinitely. Publish transition validation also rejects mismatched form IDs, non-Published