@form-engine-ts/react 4.6.0 → 4.7.0

package/README.md

@@ -80,8 +80,9 @@ 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 locale, default locale, current locales, and policy.
+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,87 @@ function asAsyncAdapter(adapter) {
     )
   };
 }
-function validateLocaleByPolicy(locale, currentLocales, policy) {
-  if (locale.length === 0) {
+function isValidBcp47Locale(locale) {
+  const language = locale.split("-")[0];
+  if (language === void 0 || !/^[a-z]{2,3}$/iu.test(language)) return false;
+  try {
+    Intl.getCanonicalLocales(locale);
+    return true;
+  } catch {
+    return false;
+  }
+}
+var validateLocalePipeline = (locale, schema, policy, customValidator) => {
+  const currentLocales = schema.supportedLocales ?? [];
+  const defaultLocale = schema.defaultLocale ?? "";
+  if (!isValidBcp47Locale(locale)) {
     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 {
+  if (locale === defaultLocale || currentLocales.includes(locale)) {
     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 "${locale}" is already registered.`
+      }
     };
   }
   if (policy?.allowedLocales !== void 0 && !policy.allowedLocales.includes(locale)) {
     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 "${locale}" 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 customContext = policy === void 0 ? Object.assign([...currentLocales], { locale, defaultLocale, currentLocales }) : Object.assign([...currentLocales], { locale, defaultLocale, currentLocales, policy });
+    const customResult = customValidator(locale, customContext);
+    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 {
@@ -3437,20 +3488,8 @@ function useTranslationWorkspace({
     (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 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 +3497,15 @@ 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;
+      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 +4878,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

@@ -3257,37 +3257,87 @@ function asAsyncAdapter(adapter) {
     )
   };
 }
-function validateLocaleByPolicy(locale, currentLocales, policy) {
-  if (locale.length === 0) {
+function isValidBcp47Locale(locale) {
+  const language = locale.split("-")[0];
+  if (language === void 0 || !/^[a-z]{2,3}$/iu.test(language)) return false;
+  try {
+    Intl.getCanonicalLocales(locale);
+    return true;
+  } catch {
+    return false;
+  }
+}
+var validateLocalePipeline = (locale, schema, policy, customValidator) => {
+  const currentLocales = schema.supportedLocales ?? [];
+  const defaultLocale = schema.defaultLocale ?? "";
+  if (!isValidBcp47Locale(locale)) {
     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 {
+  if (locale === defaultLocale || currentLocales.includes(locale)) {
     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 "${locale}" is already registered.`
+      }
     };
   }
   if (policy?.allowedLocales !== void 0 && !policy.allowedLocales.includes(locale)) {
     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 "${locale}" 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 customContext = policy === void 0 ? Object.assign([...currentLocales], { locale, defaultLocale, currentLocales }) : Object.assign([...currentLocales], { locale, defaultLocale, currentLocales, policy });
+    const customResult = customValidator(locale, customContext);
+    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 {
@@ -3413,20 +3463,8 @@ function useTranslationWorkspace({
     (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 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 +3472,15 @@ 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;
+      return validateLocalePipeline(normalized, currentSchema, policy, validateLocale).valid;
     },
-    [currentSchema, policy, readOnly, sourceLocale, validateLocale]
+    [currentSchema, policy, readOnly, validateLocale]
   );
   const removeLocale = useCallback3(
     (locale) => {
@@ -4832,5 +4863,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.7.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/core": "4.7.0",
+    "@form-engine-ts/privacy": "4.7.0"
   },
   "peerDependencies": {
     "react": ">=18.2 <20",