@form-engine-ts/react 4.6.0 → 4.8.0

package/README.md

@@ -80,8 +80,12 @@ single-slot or batch translation with stale/manual status handling. The MUI pack
 schema-driven pre-submit confirmation controls in the builder.
 
 `useTranslationWorkspace` validates added locales against `policy.allowedLocales` and `policy.maxLocales` and returns
-a structured `{ success, error }` result from `addLocale`. Use `validateLocale` for application-specific BCP 47 or
-tenant rules, and `isAddLocaleAllowed` to disable locale controls before submission. Removing a locale also clears its
+a structured `{ success, error }` result from `addLocale`. Built-in BCP 47, duplicate, and policy checks always run
+before the optional `validateLocale` callback, which receives the canonical locale and a plain context object containing
+the canonical default locale, current locales, and policy.
+Locale input is normalized to its canonical BCP 47 form before duplicate, policy, custom-validation, and schema updates;
+underscore-separated values such as `EN_us` are accepted as compatibility input.
+Use `isAddLocaleAllowed` to disable locale controls before submission. Removing a locale also clears its
 localized values and metadata; the default locale remains protected.
 
 ## Headless builder and renderer lifecycle

package/dist/index.cjs

@@ -39,7 +39,8 @@ __export(index_exports, {
   useForm: () => useForm,
   useFormBuilder: () => useFormBuilder,
   useSubmissionReceipts: () => useSubmissionReceipts,
-  useTranslationWorkspace: () => useTranslationWorkspace
+  useTranslationWorkspace: () => useTranslationWorkspace,
+  validateLocalePipeline: () => validateLocalePipeline
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -3281,37 +3282,83 @@ function asAsyncAdapter(adapter) {
     )
   };
 }
-function validateLocaleByPolicy(locale, currentLocales, policy) {
-  if (locale.length === 0) {
+var validateLocalePipeline = (locale, schema, policy, customValidator) => {
+  const canonicalLocale = (0, import_core4.normalizeLocale)(locale);
+  if (canonicalLocale === null) {
     return {
       valid: false,
-      error: { type: "invalid_locale_format", message: "Locale must not be empty." }
+      error: {
+        type: "invalid_locale_format",
+        message: `Invalid BCP 47 locale format: "${locale}"`
+      }
     };
   }
-  try {
-    Intl.getCanonicalLocales(locale);
-  } catch {
+  const currentLocales = (schema.supportedLocales ?? []).map((candidate) => (0, import_core4.normalizeLocale)(candidate) ?? candidate);
+  const defaultLocale = schema.defaultLocale === void 0 ? "" : (0, import_core4.normalizeLocale)(schema.defaultLocale) ?? schema.defaultLocale;
+  if (canonicalLocale === defaultLocale || currentLocales.includes(canonicalLocale)) {
     return {
       valid: false,
-      error: { type: "invalid_locale_format", message: `Locale "${locale}" is not a valid BCP 47 locale.` }
+      error: {
+        type: "locale_already_exists",
+        message: `Locale "${canonicalLocale}" is already registered.`
+      }
     };
   }
-  if (policy?.allowedLocales !== void 0 && !policy.allowedLocales.includes(locale)) {
+  if (policy?.allowedLocales !== void 0 && !policy.allowedLocales.some((candidate) => (0, import_core4.normalizeLocale)(candidate) === canonicalLocale)) {
     return {
       valid: false,
-      error: { type: "locale_not_allowed", message: `Locale "${locale}" is not allowed by the form policy.` }
+      error: {
+        type: "locale_not_allowed",
+        message: `Locale "${canonicalLocale}" is not allowed by policy.`
+      }
     };
   }
-  if (policy?.maxLocales !== void 0 && !currentLocales.includes(locale) && currentLocales.length >= policy.maxLocales) {
+  const totalLocalesCount = 1 + currentLocales.length;
+  if (policy?.maxLocales !== void 0 && totalLocalesCount >= policy.maxLocales) {
     return {
       valid: false,
       error: {
         type: "max_locales_exceeded",
-        message: `At most ${policy.maxLocales} locales are allowed by the form policy.`
+        message: `Cannot add locale: maximum allowed locales limit (${policy.maxLocales}) reached.`
       }
     };
   }
+  if (customValidator !== void 0) {
+    const context = {
+      locale: canonicalLocale,
+      defaultLocale,
+      currentLocales: Object.freeze([...currentLocales]),
+      ...policy === void 0 ? {} : { policy }
+    };
+    const customResult = Reflect.apply(customValidator, void 0, [canonicalLocale, context]);
+    if (customResult === false) {
+      return {
+        valid: false,
+        error: {
+          type: "custom_validation_failed",
+          message: `Custom validation rejected locale "${locale}".`
+        }
+      };
+    }
+    if (typeof customResult === "string") {
+      return {
+        valid: false,
+        error: { type: "custom_validation_failed", message: customResult }
+      };
+    }
+    if (typeof customResult === "object" && customResult !== null && !customResult.valid) return customResult;
+  }
   return { valid: true };
+};
+function workspaceLocaleValidationMessage(validation) {
+  if (validation.error?.type === "locale_not_allowed") {
+    return validation.error.message.replace(" is not allowed by policy.", " is not allowed by the form policy.");
+  }
+  if (validation.error?.type === "max_locales_exceeded") {
+    const maximum = validation.error.message.match(/\((\d+)\)/u)?.[1];
+    return maximum === void 0 ? validation.error.message : `At most ${maximum} locales are allowed by the form policy.`;
+  }
+  return validation.error?.message ?? "Locale is not valid.";
 }
 function manualMetadata(sourceText, sourceLocale) {
   return {
@@ -3436,21 +3483,15 @@ function useTranslationWorkspace({
   const addLocale = (0, import_react4.useCallback)(
     (locale) => {
       if (readOnly) return { success: false, error: "Workspace is read-only." };
-      const normalized = locale.trim();
-      const currentLocales = [
-        .../* @__PURE__ */ new Set([
-          ...currentSchema.defaultLocale === void 0 ? [] : [currentSchema.defaultLocale],
-          sourceLocale,
-          ...(0, import_core4.collectSchemaLocales)(currentSchema).allUniqueLocales
-        ])
-      ];
-      const validation = validateLocale?.(normalized, currentLocales) ?? validateLocaleByPolicy(normalized, currentLocales, policy);
-      if (!validation.valid) return { success: false, error: validation.error?.message ?? "Locale is not valid." };
-      const alreadyRegistered = normalized === sourceLocale || normalized === currentSchema.defaultLocale || (currentSchema.supportedLocales ?? []).includes(normalized);
-      if (alreadyRegistered) {
-        setSelectedLocale(normalized);
-        return { success: true };
+      const normalized = (0, import_core4.normalizeLocale)(locale);
+      if (normalized === null) {
+        return {
+          success: false,
+          error: workspaceLocaleValidationMessage(validateLocalePipeline(locale, currentSchema, policy, validateLocale))
+        };
       }
+      const validation = validateLocalePipeline(normalized, currentSchema, policy, validateLocale);
+      if (!validation.valid) return { success: false, error: workspaceLocaleValidationMessage(validation) };
       commit({
         ...currentSchema,
         supportedLocales: [.../* @__PURE__ */ new Set([...currentSchema.supportedLocales ?? [], normalized])]
@@ -3458,22 +3499,16 @@ function useTranslationWorkspace({
       setSelectedLocale(normalized);
       return { success: true };
     },
-    [commit, currentSchema, policy, readOnly, sourceLocale, validateLocale]
+    [commit, currentSchema, policy, readOnly, validateLocale]
   );
   const isAddLocaleAllowed = (0, import_react4.useCallback)(
     (locale) => {
       if (readOnly) return false;
-      const normalized = locale.trim();
-      const currentLocales = [
-        .../* @__PURE__ */ new Set([
-          ...currentSchema.defaultLocale === void 0 ? [] : [currentSchema.defaultLocale],
-          sourceLocale,
-          ...(0, import_core4.collectSchemaLocales)(currentSchema).allUniqueLocales
-        ])
-      ];
-      return (validateLocale?.(normalized, currentLocales) ?? validateLocaleByPolicy(normalized, currentLocales, policy)).valid;
+      const normalized = (0, import_core4.normalizeLocale)(locale);
+      if (normalized === null) return false;
+      return validateLocalePipeline(normalized, currentSchema, policy, validateLocale).valid;
     },
-    [currentSchema, policy, readOnly, sourceLocale, validateLocale]
+    [currentSchema, policy, readOnly, validateLocale]
   );
   const removeLocale = (0, import_react4.useCallback)(
     (locale) => {
@@ -4846,5 +4881,6 @@ function FormRenderer(props) {
   useForm,
   useFormBuilder,
   useSubmissionReceipts,
-  useTranslationWorkspace
+  useTranslationWorkspace,
+  validateLocalePipeline
 });

package/dist/index.d.cts

@@ -708,12 +708,19 @@ interface UseTranslationWorkspaceOptions {
     readonly translationAdapter?: TranslationAdapter | AsyncTranslationAdapter;
     readonly readOnly?: boolean;
     readonly policy?: FormPolicy;
-    readonly validateLocale?: (locale: string, currentLocales: readonly string[]) => LocaleValidationResult;
+    readonly validateLocale?: ((locale: string, currentLocales: readonly string[]) => LocaleValidationResult) | CustomLocaleValidator;
 }
+interface LocaleValidationContext {
+    readonly locale: string;
+    readonly defaultLocale: string;
+    readonly currentLocales: readonly string[];
+    readonly policy?: FormPolicy;
+}
+type CustomLocaleValidator = (locale: string, context: LocaleValidationContext) => LocaleValidationResult | boolean | string | undefined | void;
 interface LocaleValidationResult {
     readonly valid: boolean;
     readonly error?: {
-        readonly type: "locale_not_allowed" | "max_locales_exceeded" | "invalid_locale_format";
+        readonly type: "locale_not_allowed" | "max_locales_exceeded" | "invalid_locale_format" | "locale_already_exists" | "custom_validation_failed";
         readonly message: string;
     };
 }
@@ -744,6 +751,7 @@ interface UseTranslationWorkspaceResult {
     readonly isTranslating: boolean;
     readonly error?: string;
 }
+declare const validateLocalePipeline: (locale: string, schema: FormSchema, policy?: FormPolicy, customValidator?: ((locale: string, currentLocales: readonly string[]) => LocaleValidationResult) | CustomLocaleValidator) => LocaleValidationResult;
 declare function useTranslationWorkspace({ schema, onChange, sourceLocale, targetLocale, translationAdapter, readOnly, policy, validateLocale }: UseTranslationWorkspaceOptions): UseTranslationWorkspaceResult;
 
 declare const BUILDER_TRANSLATION_KEYS: {
@@ -818,4 +826,4 @@ interface StandaloneFormRendererProps extends FormRendererPresentationProps {
 type FormRendererProps = FormRendererPresentationProps | StandaloneFormRendererProps;
 declare function FormRenderer(props: FormRendererProps): react.JSX.Element;
 
-export { BUILDER_TRANSLATION_ALIASES, BUILDER_TRANSLATION_KEYS, type BeforeSubmit, type BuilderActionContext, type BuilderActionError, type BuilderActionIconType, type BuilderActionResult, type BuilderButtonProps, type BuilderCheckboxProps, type BuilderErrorMessageProps, type BuilderFactories, type BuilderFieldEditorSlotProps, type BuilderFieldsetProps, type BuilderIconButtonProps, type BuilderIdKind, type BuilderLocalizationSlotProps, type BuilderOptionEditorSlotProps, type BuilderPagesSlotProps, type BuilderPolicy, type BuilderSectionProps, type BuilderSelectOption, type BuilderSelectProps, type BuilderSlotActions, type BuilderTextAreaProps, type BuilderTextInputProps, type BuilderTextTarget, type BuilderToolbarSlotProps, type BuilderTranslationActionsSlotProps, type BuilderTranslationKey, type ChoiceFieldLayoutMode, type ChoiceFieldTypeLayoutMap, type ChoiceGroupSlotProps, type ComponentBaseProps, type FieldComponentProps, type FieldComponents, type FieldEditorControlsConfig, type FieldEditorHeaderSlotProps, type FieldEditorMode, type FieldError, type FieldPropertyControlMode, type FieldState, type FieldTypeSelectOptionsConfig, type FieldTypeSelectOptionsContext, type FieldTypeSelectOptionsSorter, type FieldTypeSelectOptionsTransformer, type FieldTypeSelectSlotProps, FormBuilder, type FormBuilderActions, type FormBuilderComponents, type FormBuilderFeatures, type FormBuilderOptions, type FormBuilderProps, type FormBuilderResult, type FormBuilderSectionName, type FormBuilderSlots, type FormBuilderSubmissionSettingsOptions, type FormCompletionSlotProps, type FormContextValue, type FormFieldsSlotProps, FormProvider, type FormProviderProps, FormRenderer, type FormRendererAppearance, type FormRendererMessages, type FormRendererPresentationProps, type FormRendererProps, type FormRendererSlotProps, type FormRendererSlots, type FormServerErrorPayload, FormSubmissionError, type FormSubmitHandler, type FormSubmitState, type FormSubmitStatus, type FormSubmittedAnswerItem, type FormSuccessRenderMode, type IconButtonProps, type InputComponentProps, type LocaleValidationResult, type LocalizationSummaryContext, type ManualTranslationContext, type ManualTranslationTarget, type RenderSubmitButtonProps, type SelectComponentProps, type StandaloneFormRendererProps, type SubmissionAttempt, type SubmissionAttemptStore, type SubmissionConfirmationOptions, type SubmissionConfirmationRenderMode, type SubmissionConfirmationSlotProps, type SubmissionGuard, type SubmissionGuardResult, type SubmissionProtectionProps, type SubmissionReceipt, type SubmissionReceiptQuery, type SubmissionReceiptStore, type SubmitContext, type SubmitResponse, type SubmitResult, type SubmitStatus, type TranslationSummary, type UseFormBuilderOptions, type UseFormBuilderResult, type UseSubmissionReceiptsResult, type UseTranslationWorkspaceOptions, type UseTranslationWorkspaceResult, createLocalStorageSubmissionAttemptStore, createLocalStorageSubmissionReceiptStore, isTranslationUnresolved, resolveChoiceFieldLayout, resolveFieldEditorControls, resolveFieldTypeSelectOptions, resolveInitialFieldType, resolveTranslation, submissionReceiptQueryKey, useField, useForm, useFormBuilder, useSubmissionReceipts, useTranslationWorkspace };
+export { BUILDER_TRANSLATION_ALIASES, BUILDER_TRANSLATION_KEYS, type BeforeSubmit, type BuilderActionContext, type BuilderActionError, type BuilderActionIconType, type BuilderActionResult, type BuilderButtonProps, type BuilderCheckboxProps, type BuilderErrorMessageProps, type BuilderFactories, type BuilderFieldEditorSlotProps, type BuilderFieldsetProps, type BuilderIconButtonProps, type BuilderIdKind, type BuilderLocalizationSlotProps, type BuilderOptionEditorSlotProps, type BuilderPagesSlotProps, type BuilderPolicy, type BuilderSectionProps, type BuilderSelectOption, type BuilderSelectProps, type BuilderSlotActions, type BuilderTextAreaProps, type BuilderTextInputProps, type BuilderTextTarget, type BuilderToolbarSlotProps, type BuilderTranslationActionsSlotProps, type BuilderTranslationKey, type ChoiceFieldLayoutMode, type ChoiceFieldTypeLayoutMap, type ChoiceGroupSlotProps, type ComponentBaseProps, type CustomLocaleValidator, type FieldComponentProps, type FieldComponents, type FieldEditorControlsConfig, type FieldEditorHeaderSlotProps, type FieldEditorMode, type FieldError, type FieldPropertyControlMode, type FieldState, type FieldTypeSelectOptionsConfig, type FieldTypeSelectOptionsContext, type FieldTypeSelectOptionsSorter, type FieldTypeSelectOptionsTransformer, type FieldTypeSelectSlotProps, FormBuilder, type FormBuilderActions, type FormBuilderComponents, type FormBuilderFeatures, type FormBuilderOptions, type FormBuilderProps, type FormBuilderResult, type FormBuilderSectionName, type FormBuilderSlots, type FormBuilderSubmissionSettingsOptions, type FormCompletionSlotProps, type FormContextValue, type FormFieldsSlotProps, FormProvider, type FormProviderProps, FormRenderer, type FormRendererAppearance, type FormRendererMessages, type FormRendererPresentationProps, type FormRendererProps, type FormRendererSlotProps, type FormRendererSlots, type FormServerErrorPayload, FormSubmissionError, type FormSubmitHandler, type FormSubmitState, type FormSubmitStatus, type FormSubmittedAnswerItem, type FormSuccessRenderMode, type IconButtonProps, type InputComponentProps, type LocaleValidationContext, type LocaleValidationResult, type LocalizationSummaryContext, type ManualTranslationContext, type ManualTranslationTarget, type RenderSubmitButtonProps, type SelectComponentProps, type StandaloneFormRendererProps, type SubmissionAttempt, type SubmissionAttemptStore, type SubmissionConfirmationOptions, type SubmissionConfirmationRenderMode, type SubmissionConfirmationSlotProps, type SubmissionGuard, type SubmissionGuardResult, type SubmissionProtectionProps, type SubmissionReceipt, type SubmissionReceiptQuery, type SubmissionReceiptStore, type SubmitContext, type SubmitResponse, type SubmitResult, type SubmitStatus, type TranslationSummary, type UseFormBuilderOptions, type UseFormBuilderResult, type UseSubmissionReceiptsResult, type UseTranslationWorkspaceOptions, type UseTranslationWorkspaceResult, createLocalStorageSubmissionAttemptStore, createLocalStorageSubmissionReceiptStore, isTranslationUnresolved, resolveChoiceFieldLayout, resolveFieldEditorControls, resolveFieldTypeSelectOptions, resolveInitialFieldType, resolveTranslation, submissionReceiptQueryKey, useField, useForm, useFormBuilder, useSubmissionReceipts, useTranslationWorkspace, validateLocalePipeline };

package/dist/index.d.ts

@@ -708,12 +708,19 @@ interface UseTranslationWorkspaceOptions {
     readonly translationAdapter?: TranslationAdapter | AsyncTranslationAdapter;
     readonly readOnly?: boolean;
     readonly policy?: FormPolicy;
-    readonly validateLocale?: (locale: string, currentLocales: readonly string[]) => LocaleValidationResult;
+    readonly validateLocale?: ((locale: string, currentLocales: readonly string[]) => LocaleValidationResult) | CustomLocaleValidator;
 }
+interface LocaleValidationContext {
+    readonly locale: string;
+    readonly defaultLocale: string;
+    readonly currentLocales: readonly string[];
+    readonly policy?: FormPolicy;
+}
+type CustomLocaleValidator = (locale: string, context: LocaleValidationContext) => LocaleValidationResult | boolean | string | undefined | void;
 interface LocaleValidationResult {
     readonly valid: boolean;
     readonly error?: {
-        readonly type: "locale_not_allowed" | "max_locales_exceeded" | "invalid_locale_format";
+        readonly type: "locale_not_allowed" | "max_locales_exceeded" | "invalid_locale_format" | "locale_already_exists" | "custom_validation_failed";
         readonly message: string;
     };
 }
@@ -744,6 +751,7 @@ interface UseTranslationWorkspaceResult {
     readonly isTranslating: boolean;
     readonly error?: string;
 }
+declare const validateLocalePipeline: (locale: string, schema: FormSchema, policy?: FormPolicy, customValidator?: ((locale: string, currentLocales: readonly string[]) => LocaleValidationResult) | CustomLocaleValidator) => LocaleValidationResult;
 declare function useTranslationWorkspace({ schema, onChange, sourceLocale, targetLocale, translationAdapter, readOnly, policy, validateLocale }: UseTranslationWorkspaceOptions): UseTranslationWorkspaceResult;
 
 declare const BUILDER_TRANSLATION_KEYS: {
@@ -818,4 +826,4 @@ interface StandaloneFormRendererProps extends FormRendererPresentationProps {
 type FormRendererProps = FormRendererPresentationProps | StandaloneFormRendererProps;
 declare function FormRenderer(props: FormRendererProps): react.JSX.Element;
 
-export { BUILDER_TRANSLATION_ALIASES, BUILDER_TRANSLATION_KEYS, type BeforeSubmit, type BuilderActionContext, type BuilderActionError, type BuilderActionIconType, type BuilderActionResult, type BuilderButtonProps, type BuilderCheckboxProps, type BuilderErrorMessageProps, type BuilderFactories, type BuilderFieldEditorSlotProps, type BuilderFieldsetProps, type BuilderIconButtonProps, type BuilderIdKind, type BuilderLocalizationSlotProps, type BuilderOptionEditorSlotProps, type BuilderPagesSlotProps, type BuilderPolicy, type BuilderSectionProps, type BuilderSelectOption, type BuilderSelectProps, type BuilderSlotActions, type BuilderTextAreaProps, type BuilderTextInputProps, type BuilderTextTarget, type BuilderToolbarSlotProps, type BuilderTranslationActionsSlotProps, type BuilderTranslationKey, type ChoiceFieldLayoutMode, type ChoiceFieldTypeLayoutMap, type ChoiceGroupSlotProps, type ComponentBaseProps, type FieldComponentProps, type FieldComponents, type FieldEditorControlsConfig, type FieldEditorHeaderSlotProps, type FieldEditorMode, type FieldError, type FieldPropertyControlMode, type FieldState, type FieldTypeSelectOptionsConfig, type FieldTypeSelectOptionsContext, type FieldTypeSelectOptionsSorter, type FieldTypeSelectOptionsTransformer, type FieldTypeSelectSlotProps, FormBuilder, type FormBuilderActions, type FormBuilderComponents, type FormBuilderFeatures, type FormBuilderOptions, type FormBuilderProps, type FormBuilderResult, type FormBuilderSectionName, type FormBuilderSlots, type FormBuilderSubmissionSettingsOptions, type FormCompletionSlotProps, type FormContextValue, type FormFieldsSlotProps, FormProvider, type FormProviderProps, FormRenderer, type FormRendererAppearance, type FormRendererMessages, type FormRendererPresentationProps, type FormRendererProps, type FormRendererSlotProps, type FormRendererSlots, type FormServerErrorPayload, FormSubmissionError, type FormSubmitHandler, type FormSubmitState, type FormSubmitStatus, type FormSubmittedAnswerItem, type FormSuccessRenderMode, type IconButtonProps, type InputComponentProps, type LocaleValidationResult, type LocalizationSummaryContext, type ManualTranslationContext, type ManualTranslationTarget, type RenderSubmitButtonProps, type SelectComponentProps, type StandaloneFormRendererProps, type SubmissionAttempt, type SubmissionAttemptStore, type SubmissionConfirmationOptions, type SubmissionConfirmationRenderMode, type SubmissionConfirmationSlotProps, type SubmissionGuard, type SubmissionGuardResult, type SubmissionProtectionProps, type SubmissionReceipt, type SubmissionReceiptQuery, type SubmissionReceiptStore, type SubmitContext, type SubmitResponse, type SubmitResult, type SubmitStatus, type TranslationSummary, type UseFormBuilderOptions, type UseFormBuilderResult, type UseSubmissionReceiptsResult, type UseTranslationWorkspaceOptions, type UseTranslationWorkspaceResult, createLocalStorageSubmissionAttemptStore, createLocalStorageSubmissionReceiptStore, isTranslationUnresolved, resolveChoiceFieldLayout, resolveFieldEditorControls, resolveFieldTypeSelectOptions, resolveInitialFieldType, resolveTranslation, submissionReceiptQueryKey, useField, useForm, useFormBuilder, useSubmissionReceipts, useTranslationWorkspace };
+export { BUILDER_TRANSLATION_ALIASES, BUILDER_TRANSLATION_KEYS, type BeforeSubmit, type BuilderActionContext, type BuilderActionError, type BuilderActionIconType, type BuilderActionResult, type BuilderButtonProps, type BuilderCheckboxProps, type BuilderErrorMessageProps, type BuilderFactories, type BuilderFieldEditorSlotProps, type BuilderFieldsetProps, type BuilderIconButtonProps, type BuilderIdKind, type BuilderLocalizationSlotProps, type BuilderOptionEditorSlotProps, type BuilderPagesSlotProps, type BuilderPolicy, type BuilderSectionProps, type BuilderSelectOption, type BuilderSelectProps, type BuilderSlotActions, type BuilderTextAreaProps, type BuilderTextInputProps, type BuilderTextTarget, type BuilderToolbarSlotProps, type BuilderTranslationActionsSlotProps, type BuilderTranslationKey, type ChoiceFieldLayoutMode, type ChoiceFieldTypeLayoutMap, type ChoiceGroupSlotProps, type ComponentBaseProps, type CustomLocaleValidator, type FieldComponentProps, type FieldComponents, type FieldEditorControlsConfig, type FieldEditorHeaderSlotProps, type FieldEditorMode, type FieldError, type FieldPropertyControlMode, type FieldState, type FieldTypeSelectOptionsConfig, type FieldTypeSelectOptionsContext, type FieldTypeSelectOptionsSorter, type FieldTypeSelectOptionsTransformer, type FieldTypeSelectSlotProps, FormBuilder, type FormBuilderActions, type FormBuilderComponents, type FormBuilderFeatures, type FormBuilderOptions, type FormBuilderProps, type FormBuilderResult, type FormBuilderSectionName, type FormBuilderSlots, type FormBuilderSubmissionSettingsOptions, type FormCompletionSlotProps, type FormContextValue, type FormFieldsSlotProps, FormProvider, type FormProviderProps, FormRenderer, type FormRendererAppearance, type FormRendererMessages, type FormRendererPresentationProps, type FormRendererProps, type FormRendererSlotProps, type FormRendererSlots, type FormServerErrorPayload, FormSubmissionError, type FormSubmitHandler, type FormSubmitState, type FormSubmitStatus, type FormSubmittedAnswerItem, type FormSuccessRenderMode, type IconButtonProps, type InputComponentProps, type LocaleValidationContext, type LocaleValidationResult, type LocalizationSummaryContext, type ManualTranslationContext, type ManualTranslationTarget, type RenderSubmitButtonProps, type SelectComponentProps, type StandaloneFormRendererProps, type SubmissionAttempt, type SubmissionAttemptStore, type SubmissionConfirmationOptions, type SubmissionConfirmationRenderMode, type SubmissionConfirmationSlotProps, type SubmissionGuard, type SubmissionGuardResult, type SubmissionProtectionProps, type SubmissionReceipt, type SubmissionReceiptQuery, type SubmissionReceiptStore, type SubmitContext, type SubmitResponse, type SubmitResult, type SubmitStatus, type TranslationSummary, type UseFormBuilderOptions, type UseFormBuilderResult, type UseSubmissionReceiptsResult, type UseTranslationWorkspaceOptions, type UseTranslationWorkspaceResult, createLocalStorageSubmissionAttemptStore, createLocalStorageSubmissionReceiptStore, isTranslationUnresolved, resolveChoiceFieldLayout, resolveFieldEditorControls, resolveFieldTypeSelectOptions, resolveInitialFieldType, resolveTranslation, submissionReceiptQueryKey, useField, useForm, useFormBuilder, useSubmissionReceipts, useTranslationWorkspace, validateLocalePipeline };

package/dist/index.js

@@ -3238,6 +3238,7 @@ import {
   collectSchemaLocales as collectSchemaLocales2,
   collectTranslationSlots,
   computeSourceTextHash,
+  normalizeLocale,
   populateSchemaTranslations as populateSchemaTranslations2,
   removeLocaleFromSchema
 } from "@form-engine-ts/core";
@@ -3257,37 +3258,83 @@ function asAsyncAdapter(adapter) {
     )
   };
 }
-function validateLocaleByPolicy(locale, currentLocales, policy) {
-  if (locale.length === 0) {
+var validateLocalePipeline = (locale, schema, policy, customValidator) => {
+  const canonicalLocale = normalizeLocale(locale);
+  if (canonicalLocale === null) {
     return {
       valid: false,
-      error: { type: "invalid_locale_format", message: "Locale must not be empty." }
+      error: {
+        type: "invalid_locale_format",
+        message: `Invalid BCP 47 locale format: "${locale}"`
+      }
     };
   }
-  try {
-    Intl.getCanonicalLocales(locale);
-  } catch {
+  const currentLocales = (schema.supportedLocales ?? []).map((candidate) => normalizeLocale(candidate) ?? candidate);
+  const defaultLocale = schema.defaultLocale === void 0 ? "" : normalizeLocale(schema.defaultLocale) ?? schema.defaultLocale;
+  if (canonicalLocale === defaultLocale || currentLocales.includes(canonicalLocale)) {
     return {
       valid: false,
-      error: { type: "invalid_locale_format", message: `Locale "${locale}" is not a valid BCP 47 locale.` }
+      error: {
+        type: "locale_already_exists",
+        message: `Locale "${canonicalLocale}" is already registered.`
+      }
     };
   }
-  if (policy?.allowedLocales !== void 0 && !policy.allowedLocales.includes(locale)) {
+  if (policy?.allowedLocales !== void 0 && !policy.allowedLocales.some((candidate) => normalizeLocale(candidate) === canonicalLocale)) {
     return {
       valid: false,
-      error: { type: "locale_not_allowed", message: `Locale "${locale}" is not allowed by the form policy.` }
+      error: {
+        type: "locale_not_allowed",
+        message: `Locale "${canonicalLocale}" is not allowed by policy.`
+      }
     };
   }
-  if (policy?.maxLocales !== void 0 && !currentLocales.includes(locale) && currentLocales.length >= policy.maxLocales) {
+  const totalLocalesCount = 1 + currentLocales.length;
+  if (policy?.maxLocales !== void 0 && totalLocalesCount >= policy.maxLocales) {
     return {
       valid: false,
       error: {
         type: "max_locales_exceeded",
-        message: `At most ${policy.maxLocales} locales are allowed by the form policy.`
+        message: `Cannot add locale: maximum allowed locales limit (${policy.maxLocales}) reached.`
       }
     };
   }
+  if (customValidator !== void 0) {
+    const context = {
+      locale: canonicalLocale,
+      defaultLocale,
+      currentLocales: Object.freeze([...currentLocales]),
+      ...policy === void 0 ? {} : { policy }
+    };
+    const customResult = Reflect.apply(customValidator, void 0, [canonicalLocale, context]);
+    if (customResult === false) {
+      return {
+        valid: false,
+        error: {
+          type: "custom_validation_failed",
+          message: `Custom validation rejected locale "${locale}".`
+        }
+      };
+    }
+    if (typeof customResult === "string") {
+      return {
+        valid: false,
+        error: { type: "custom_validation_failed", message: customResult }
+      };
+    }
+    if (typeof customResult === "object" && customResult !== null && !customResult.valid) return customResult;
+  }
   return { valid: true };
+};
+function workspaceLocaleValidationMessage(validation) {
+  if (validation.error?.type === "locale_not_allowed") {
+    return validation.error.message.replace(" is not allowed by policy.", " is not allowed by the form policy.");
+  }
+  if (validation.error?.type === "max_locales_exceeded") {
+    const maximum = validation.error.message.match(/\((\d+)\)/u)?.[1];
+    return maximum === void 0 ? validation.error.message : `At most ${maximum} locales are allowed by the form policy.`;
+  }
+  return validation.error?.message ?? "Locale is not valid.";
 }
 function manualMetadata(sourceText, sourceLocale) {
   return {
@@ -3412,21 +3459,15 @@ function useTranslationWorkspace({
   const addLocale = useCallback3(
     (locale) => {
       if (readOnly) return { success: false, error: "Workspace is read-only." };
-      const normalized = locale.trim();
-      const currentLocales = [
-        .../* @__PURE__ */ new Set([
-          ...currentSchema.defaultLocale === void 0 ? [] : [currentSchema.defaultLocale],
-          sourceLocale,
-          ...collectSchemaLocales2(currentSchema).allUniqueLocales
-        ])
-      ];
-      const validation = validateLocale?.(normalized, currentLocales) ?? validateLocaleByPolicy(normalized, currentLocales, policy);
-      if (!validation.valid) return { success: false, error: validation.error?.message ?? "Locale is not valid." };
-      const alreadyRegistered = normalized === sourceLocale || normalized === currentSchema.defaultLocale || (currentSchema.supportedLocales ?? []).includes(normalized);
-      if (alreadyRegistered) {
-        setSelectedLocale(normalized);
-        return { success: true };
+      const normalized = normalizeLocale(locale);
+      if (normalized === null) {
+        return {
+          success: false,
+          error: workspaceLocaleValidationMessage(validateLocalePipeline(locale, currentSchema, policy, validateLocale))
+        };
       }
+      const validation = validateLocalePipeline(normalized, currentSchema, policy, validateLocale);
+      if (!validation.valid) return { success: false, error: workspaceLocaleValidationMessage(validation) };
       commit({
         ...currentSchema,
         supportedLocales: [.../* @__PURE__ */ new Set([...currentSchema.supportedLocales ?? [], normalized])]
@@ -3434,22 +3475,16 @@ function useTranslationWorkspace({
       setSelectedLocale(normalized);
       return { success: true };
     },
-    [commit, currentSchema, policy, readOnly, sourceLocale, validateLocale]
+    [commit, currentSchema, policy, readOnly, validateLocale]
   );
   const isAddLocaleAllowed = useCallback3(
     (locale) => {
       if (readOnly) return false;
-      const normalized = locale.trim();
-      const currentLocales = [
-        .../* @__PURE__ */ new Set([
-          ...currentSchema.defaultLocale === void 0 ? [] : [currentSchema.defaultLocale],
-          sourceLocale,
-          ...collectSchemaLocales2(currentSchema).allUniqueLocales
-        ])
-      ];
-      return (validateLocale?.(normalized, currentLocales) ?? validateLocaleByPolicy(normalized, currentLocales, policy)).valid;
+      const normalized = normalizeLocale(locale);
+      if (normalized === null) return false;
+      return validateLocalePipeline(normalized, currentSchema, policy, validateLocale).valid;
     },
-    [currentSchema, policy, readOnly, sourceLocale, validateLocale]
+    [currentSchema, policy, readOnly, validateLocale]
   );
   const removeLocale = useCallback3(
     (locale) => {
@@ -4832,5 +4867,6 @@ export {
   useForm,
   useFormBuilder,
   useSubmissionReceipts,
-  useTranslationWorkspace
+  useTranslationWorkspace,
+  validateLocalePipeline
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@form-engine-ts/react",
-  "version": "4.6.0",
+  "version": "4.8.0",
   "publishConfig": {
     "access": "public"
   },
@@ -42,8 +42,8 @@
     "typescript"
   ],
   "dependencies": {
-    "@form-engine-ts/core": "4.6.0",
-    "@form-engine-ts/privacy": "4.6.0"
+    "@form-engine-ts/privacy": "4.8.0",
+    "@form-engine-ts/core": "4.8.0"
   },
   "peerDependencies": {
     "react": ">=18.2 <20",