@form-engine-ts/react 3.2.0 → 4.0.0

package/README.md

@@ -96,11 +96,14 @@ When either is enabled, the builder omits its `form-engine-builder` and `feb-*`
 and `Select` components receive the field `label` and accessibility attributes and are responsible for rendering their
 own labels. Builder action icons can be supplied with `renderIcon`, which resolves `actionType` values such as
 `moveUp`, `moveDown`, `delete`, and `add`. `renderFieldTypeIcon` supplies icons for field-type selectors. Select
-options may be strings or `BuilderSelectOption` objects with `icon`, `description`, `kind`, and `metadata`; custom
+options may be strings or `BuilderSelectOption` objects with `icon`, `description`, `group`, `groupLabel`, `kind`, and
+`metadata`; custom
 `renderOption` and `renderValue` functions can control their presentation. `BUILDER_TRANSLATION_KEYS` exposes the
 canonical typed builder translation keys while legacy catalog aliases remain supported.
 
 The `fieldEditor` slot can expose only the type selector or header through `fieldTypeSelect` and `fieldEditorHeader`:
+The `fieldTypeSelect` slot receives the resolved `id`, `name`, `label`, `options`, and accessibility attributes in addition
+to `currentType`, `allowedTypes`, and `onChangeType`.
 
 ```tsx
 <FormBuilder

package/dist/index.cjs

@@ -28,7 +28,9 @@ __export(index_exports, {
   FormSubmissionError: () => FormSubmissionError,
   createLocalStorageSubmissionAttemptStore: () => createLocalStorageSubmissionAttemptStore,
   createLocalStorageSubmissionReceiptStore: () => createLocalStorageSubmissionReceiptStore,
+  isTranslationUnresolved: () => isTranslationUnresolved,
   resolveInitialFieldType: () => resolveInitialFieldType,
+  resolveTranslation: () => resolveTranslation,
   submissionReceiptQueryKey: () => submissionReceiptQueryKey,
   useField: () => useField,
   useForm: () => useForm,
@@ -802,6 +804,41 @@ var BUILDER_TRANSLATION_ALIASES = {
   "builder.fields.typeSelect": "builder.fieldType.select",
   "builder.fields.typeMultiSelect": "builder.fieldType.multi-select"
 };
+function isTranslationUnresolved(result, key, aliases = []) {
+  if (result === void 0 || result === null || result === "") return true;
+  if (typeof result !== "string") return false;
+  if (result === key || aliases.includes(result)) return true;
+  return result.endsWith(key) || aliases.some((alias) => result.endsWith(alias));
+}
+function isResolvedAdapterResult(result, key, aliases) {
+  return typeof result === "string" && result.startsWith("translated:") ? true : !isTranslationUnresolved(result, key, aliases);
+}
+function formatTemplate(template, params) {
+  return template.replace(
+    /\{\{(\w+)\}\}/g,
+    (token, name) => Object.hasOwn(params, name) ? String(params[name]) : token
+  );
+}
+function resolveTranslation(key, aliases, adapter, defaultCatalog, params = {}, locale = "") {
+  const adapterParams = {};
+  for (const [name, value] of Object.entries(params)) {
+    if (typeof value === "string" || typeof value === "number") adapterParams[name] = value;
+  }
+  const translate = (candidate) => adapter?.translate(candidate, locale, adapterParams);
+  const translated = translate(key);
+  if (isResolvedAdapterResult(translated, key, aliases)) return translated;
+  for (const alias of aliases) {
+    const aliased = translate(alias);
+    if (isResolvedAdapterResult(aliased, alias, aliases)) return aliased;
+  }
+  const catalogValue = defaultCatalog?.[key];
+  if (catalogValue !== void 0) return formatTemplate(catalogValue, params);
+  for (const alias of aliases) {
+    const aliasValue = defaultCatalog?.[alias];
+    if (aliasValue !== void 0) return formatTemplate(aliasValue, params);
+  }
+  return key;
+}
 
 // src/builder.tsx
 var import_jsx_runtime = require("react/jsx-runtime");
@@ -1334,6 +1371,18 @@ var BUILDER_DEFAULTS = {
   "builder.fields.typeMultiSelect": "Multi-select",
   "builder.fields.typeCheckbox": "Checkbox",
   "builder.fields.typeRadio": "Radio",
+  "builder.fieldCategory.text": "Text",
+  "builder.fieldCategory.choice": "Choice",
+  "builder.fieldCategory.number": "Number",
+  "builder.fieldCategory.advanced": "Advanced",
+  "builder.fieldTypeDescription.text": "A single-line text answer",
+  "builder.fieldTypeDescription.textarea": "A long-form text answer",
+  "builder.fieldTypeDescription.number": "A numeric answer",
+  "builder.fieldTypeDescription.rating": "A rating scale answer",
+  "builder.fieldTypeDescription.radio": "A single-choice answer",
+  "builder.fieldTypeDescription.checkbox": "A yes/no answer",
+  "builder.fieldTypeDescription.select": "A dropdown choice",
+  "builder.fieldTypeDescription.multi-select": "Multiple choices",
   "builder.actions.addField": "Add question",
   "builder.fieldType.text": "Text",
   "builder.fieldType.textarea": "Textarea",
@@ -1348,12 +1397,6 @@ var BUILDER_DEFAULTS = {
   "builder.operator.contains": "contains",
   "builder.operator.not_empty": "is not empty"
 };
-function interpolate(template, params) {
-  return template.replace(
-    /\{\{(\w+)\}\}/g,
-    (token, name) => Object.hasOwn(params, name) ? String(params[name]) : token
-  );
-}
 function BuilderSectionGroup({ children }) {
   return children;
 }
@@ -1558,20 +1601,14 @@ function FormBuilder({
   const [isTranslating, setIsTranslating] = (0, import_react2.useState)(false);
   const [translationError, setTranslationError] = (0, import_react2.useState)(null);
   const [translationReport, setTranslationReport] = (0, import_react2.useState)();
-  const translate = (key, params = {}) => {
-    const translatorParams = {};
-    for (const [name, value] of Object.entries(params)) {
-      if (typeof value === "string" || typeof value === "number") translatorParams[name] = value;
-    }
-    const translated = translator?.translate(key, locale, translatorParams);
-    if (translated !== void 0 && translated !== key) return translated;
-    const alias = BUILDER_TRANSLATION_ALIASES[key];
-    if (alias !== void 0) {
-      const aliased = translator?.translate(alias, locale, translatorParams);
-      if (aliased !== void 0 && aliased !== alias) return aliased;
-    }
-    return translated === void 0 ? interpolate(BUILDER_DEFAULTS[key] ?? key, params) : translated;
-  };
+  const translate = (key, params = {}) => resolveTranslation(
+    key,
+    BUILDER_TRANSLATION_ALIASES[key] === void 0 ? [] : [BUILDER_TRANSLATION_ALIASES[key]],
+    translator,
+    BUILDER_DEFAULTS,
+    params,
+    locale
+  );
   const pagesEnabled = features?.pages ?? true;
   const localizationEnabled = features?.localization ?? true;
   const conditionsEnabled = features?.conditions ?? true;
@@ -2852,7 +2889,7 @@ function FormProvider({
     [initialValues, locale, onSubmit, resetOnSuccess, validSchema, values]
   );
   const translate = (0, import_react3.useCallback)(
-    (key, params) => translator.translate(key, locale, params),
+    (key, params) => translator.translate(key, locale, params) ?? key,
     [locale, translator]
   );
   const contextValue = (0, import_react3.useMemo)(
@@ -3963,7 +4000,9 @@ function FormRenderer(props) {
   FormSubmissionError,
   createLocalStorageSubmissionAttemptStore,
   createLocalStorageSubmissionReceiptStore,
+  isTranslationUnresolved,
   resolveInitialFieldType,
+  resolveTranslation,
   submissionReceiptQueryKey,
   useField,
   useForm,

package/dist/index.d.cts

@@ -187,19 +187,19 @@ interface BuilderSelectOption<T extends string = string> {
     readonly icon?: ReactNode;
     readonly description?: string;
     readonly disabled?: boolean;
+    readonly group?: string;
+    readonly groupLabel?: string;
     readonly kind?: string;
     readonly metadata?: Readonly<Record<string, unknown>>;
 }
-interface SelectComponentProps extends InputComponentProps {
-    readonly options: readonly (string | BuilderSelectOption)[];
-    readonly renderOption?: (option: BuilderSelectOption) => ReactNode;
-    readonly renderValue?: (option: BuilderSelectOption | undefined) => ReactNode;
-}
-interface BuilderSelectProps extends InputComponentProps {
-    readonly options: readonly BuilderSelectOption[];
-    readonly renderOption?: (option: BuilderSelectOption) => ReactNode;
-    readonly renderValue?: (option: BuilderSelectOption | undefined) => ReactNode;
+interface SelectComponentProps<T extends string = string> extends Omit<InputComponentProps, "value" | "onChange"> {
+    readonly value: T;
+    readonly onChange: (value: T) => void;
+    readonly options: readonly (T | BuilderSelectOption<T>)[];
+    readonly renderOption?: (option: BuilderSelectOption<T>) => ReactNode;
+    readonly renderValue?: (option: BuilderSelectOption<T> | undefined) => ReactNode;
 }
+type BuilderSelectProps<T extends string = string> = SelectComponentProps<T>;
 interface BuilderCheckboxProps extends ComponentBaseProps {
     readonly name?: string;
     readonly required?: boolean;
@@ -281,11 +281,20 @@ interface BuilderFieldEditorSlotProps extends BuilderSlotBaseProps {
     readonly slots?: Pick<FormBuilderSlots, "fieldTypeSelect" | "fieldEditorHeader">;
 }
 interface FieldTypeSelectSlotProps {
+    readonly id?: string;
+    readonly name?: string;
+    readonly label?: string;
     readonly currentType: QuestionType;
     readonly allowedTypes: readonly QuestionType[];
+    readonly options: readonly BuilderSelectOption<QuestionType>[];
     readonly onChangeType: (nextType: QuestionType) => void;
     readonly disabled?: boolean;
     readonly readOnly?: boolean;
+    readonly required?: boolean;
+    readonly error?: boolean;
+    readonly helperText?: string;
+    readonly "aria-describedby"?: string;
+    readonly "aria-labelledby"?: string;
     readonly renderIcon?: (type: QuestionType) => ReactNode;
 }
 interface FieldEditorHeaderSlotProps {
@@ -601,6 +610,8 @@ declare const BUILDER_TRANSLATION_KEYS: {
 type BuilderTranslationKey = (typeof BUILDER_TRANSLATION_KEYS)[keyof typeof BUILDER_TRANSLATION_KEYS];
 /** Legacy keys are checked when an older catalog does not contain a canonical key. */
 declare const BUILDER_TRANSLATION_ALIASES: Readonly<Record<string, string>>;
+declare function isTranslationUnresolved(result: unknown, key: string, aliases?: readonly string[]): boolean;
+declare function resolveTranslation(key: string, aliases: readonly string[], adapter?: TranslationAdapter, defaultCatalog?: Readonly<Record<string, string>>, params?: Readonly<Record<string, unknown>>, locale?: string): string;
 
 interface FieldComponentProps {
     readonly field: FormField;
@@ -648,4 +659,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 ComponentBaseProps, type FieldComponentProps, type FieldComponents, type FieldEditorHeaderSlotProps, type FieldState, type FieldTypeSelectSlotProps, FormBuilder, type FormBuilderActions, type FormBuilderComponents, type FormBuilderFeatures, type FormBuilderOptions, type FormBuilderProps, type FormBuilderResult, type FormBuilderSectionName, type FormBuilderSlots, type FormCompletionSlotProps, type FormContextValue, type FormFieldsSlotProps, FormProvider, type FormProviderProps, FormRenderer, type FormRendererMessages, type FormRendererPresentationProps, type FormRendererProps, type FormRendererSlots, type FormServerErrorPayload, FormSubmissionError, type FormSubmitHandler, type FormSubmitState, type FormSubmitStatus, type FormSubmittedAnswerItem, type FormSuccessRenderMode, type IconButtonProps, type InputComponentProps, type LocalizationSummaryContext, type ManualTranslationContext, type ManualTranslationTarget, type RenderSubmitButtonProps, type SelectComponentProps, type StandaloneFormRendererProps, type SubmissionAttempt, type SubmissionAttemptStore, 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 UseSubmissionReceiptsResult, createLocalStorageSubmissionAttemptStore, createLocalStorageSubmissionReceiptStore, resolveInitialFieldType, submissionReceiptQueryKey, useField, useForm, useFormBuilder, useSubmissionReceipts };
+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 ComponentBaseProps, type FieldComponentProps, type FieldComponents, type FieldEditorHeaderSlotProps, type FieldState, type FieldTypeSelectSlotProps, FormBuilder, type FormBuilderActions, type FormBuilderComponents, type FormBuilderFeatures, type FormBuilderOptions, type FormBuilderProps, type FormBuilderResult, type FormBuilderSectionName, type FormBuilderSlots, type FormCompletionSlotProps, type FormContextValue, type FormFieldsSlotProps, FormProvider, type FormProviderProps, FormRenderer, type FormRendererMessages, type FormRendererPresentationProps, type FormRendererProps, type FormRendererSlots, type FormServerErrorPayload, FormSubmissionError, type FormSubmitHandler, type FormSubmitState, type FormSubmitStatus, type FormSubmittedAnswerItem, type FormSuccessRenderMode, type IconButtonProps, type InputComponentProps, type LocalizationSummaryContext, type ManualTranslationContext, type ManualTranslationTarget, type RenderSubmitButtonProps, type SelectComponentProps, type StandaloneFormRendererProps, type SubmissionAttempt, type SubmissionAttemptStore, 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 UseSubmissionReceiptsResult, createLocalStorageSubmissionAttemptStore, createLocalStorageSubmissionReceiptStore, isTranslationUnresolved, resolveInitialFieldType, resolveTranslation, submissionReceiptQueryKey, useField, useForm, useFormBuilder, useSubmissionReceipts };

package/dist/index.d.ts

@@ -187,19 +187,19 @@ interface BuilderSelectOption<T extends string = string> {
     readonly icon?: ReactNode;
     readonly description?: string;
     readonly disabled?: boolean;
+    readonly group?: string;
+    readonly groupLabel?: string;
     readonly kind?: string;
     readonly metadata?: Readonly<Record<string, unknown>>;
 }
-interface SelectComponentProps extends InputComponentProps {
-    readonly options: readonly (string | BuilderSelectOption)[];
-    readonly renderOption?: (option: BuilderSelectOption) => ReactNode;
-    readonly renderValue?: (option: BuilderSelectOption | undefined) => ReactNode;
-}
-interface BuilderSelectProps extends InputComponentProps {
-    readonly options: readonly BuilderSelectOption[];
-    readonly renderOption?: (option: BuilderSelectOption) => ReactNode;
-    readonly renderValue?: (option: BuilderSelectOption | undefined) => ReactNode;
+interface SelectComponentProps<T extends string = string> extends Omit<InputComponentProps, "value" | "onChange"> {
+    readonly value: T;
+    readonly onChange: (value: T) => void;
+    readonly options: readonly (T | BuilderSelectOption<T>)[];
+    readonly renderOption?: (option: BuilderSelectOption<T>) => ReactNode;
+    readonly renderValue?: (option: BuilderSelectOption<T> | undefined) => ReactNode;
 }
+type BuilderSelectProps<T extends string = string> = SelectComponentProps<T>;
 interface BuilderCheckboxProps extends ComponentBaseProps {
     readonly name?: string;
     readonly required?: boolean;
@@ -281,11 +281,20 @@ interface BuilderFieldEditorSlotProps extends BuilderSlotBaseProps {
     readonly slots?: Pick<FormBuilderSlots, "fieldTypeSelect" | "fieldEditorHeader">;
 }
 interface FieldTypeSelectSlotProps {
+    readonly id?: string;
+    readonly name?: string;
+    readonly label?: string;
     readonly currentType: QuestionType;
     readonly allowedTypes: readonly QuestionType[];
+    readonly options: readonly BuilderSelectOption<QuestionType>[];
     readonly onChangeType: (nextType: QuestionType) => void;
     readonly disabled?: boolean;
     readonly readOnly?: boolean;
+    readonly required?: boolean;
+    readonly error?: boolean;
+    readonly helperText?: string;
+    readonly "aria-describedby"?: string;
+    readonly "aria-labelledby"?: string;
     readonly renderIcon?: (type: QuestionType) => ReactNode;
 }
 interface FieldEditorHeaderSlotProps {
@@ -601,6 +610,8 @@ declare const BUILDER_TRANSLATION_KEYS: {
 type BuilderTranslationKey = (typeof BUILDER_TRANSLATION_KEYS)[keyof typeof BUILDER_TRANSLATION_KEYS];
 /** Legacy keys are checked when an older catalog does not contain a canonical key. */
 declare const BUILDER_TRANSLATION_ALIASES: Readonly<Record<string, string>>;
+declare function isTranslationUnresolved(result: unknown, key: string, aliases?: readonly string[]): boolean;
+declare function resolveTranslation(key: string, aliases: readonly string[], adapter?: TranslationAdapter, defaultCatalog?: Readonly<Record<string, string>>, params?: Readonly<Record<string, unknown>>, locale?: string): string;
 
 interface FieldComponentProps {
     readonly field: FormField;
@@ -648,4 +659,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 ComponentBaseProps, type FieldComponentProps, type FieldComponents, type FieldEditorHeaderSlotProps, type FieldState, type FieldTypeSelectSlotProps, FormBuilder, type FormBuilderActions, type FormBuilderComponents, type FormBuilderFeatures, type FormBuilderOptions, type FormBuilderProps, type FormBuilderResult, type FormBuilderSectionName, type FormBuilderSlots, type FormCompletionSlotProps, type FormContextValue, type FormFieldsSlotProps, FormProvider, type FormProviderProps, FormRenderer, type FormRendererMessages, type FormRendererPresentationProps, type FormRendererProps, type FormRendererSlots, type FormServerErrorPayload, FormSubmissionError, type FormSubmitHandler, type FormSubmitState, type FormSubmitStatus, type FormSubmittedAnswerItem, type FormSuccessRenderMode, type IconButtonProps, type InputComponentProps, type LocalizationSummaryContext, type ManualTranslationContext, type ManualTranslationTarget, type RenderSubmitButtonProps, type SelectComponentProps, type StandaloneFormRendererProps, type SubmissionAttempt, type SubmissionAttemptStore, 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 UseSubmissionReceiptsResult, createLocalStorageSubmissionAttemptStore, createLocalStorageSubmissionReceiptStore, resolveInitialFieldType, submissionReceiptQueryKey, useField, useForm, useFormBuilder, useSubmissionReceipts };
+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 ComponentBaseProps, type FieldComponentProps, type FieldComponents, type FieldEditorHeaderSlotProps, type FieldState, type FieldTypeSelectSlotProps, FormBuilder, type FormBuilderActions, type FormBuilderComponents, type FormBuilderFeatures, type FormBuilderOptions, type FormBuilderProps, type FormBuilderResult, type FormBuilderSectionName, type FormBuilderSlots, type FormCompletionSlotProps, type FormContextValue, type FormFieldsSlotProps, FormProvider, type FormProviderProps, FormRenderer, type FormRendererMessages, type FormRendererPresentationProps, type FormRendererProps, type FormRendererSlots, type FormServerErrorPayload, FormSubmissionError, type FormSubmitHandler, type FormSubmitState, type FormSubmitStatus, type FormSubmittedAnswerItem, type FormSuccessRenderMode, type IconButtonProps, type InputComponentProps, type LocalizationSummaryContext, type ManualTranslationContext, type ManualTranslationTarget, type RenderSubmitButtonProps, type SelectComponentProps, type StandaloneFormRendererProps, type SubmissionAttempt, type SubmissionAttemptStore, 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 UseSubmissionReceiptsResult, createLocalStorageSubmissionAttemptStore, createLocalStorageSubmissionReceiptStore, isTranslationUnresolved, resolveInitialFieldType, resolveTranslation, submissionReceiptQueryKey, useField, useForm, useFormBuilder, useSubmissionReceipts };

package/dist/index.js

@@ -770,6 +770,41 @@ var BUILDER_TRANSLATION_ALIASES = {
   "builder.fields.typeSelect": "builder.fieldType.select",
   "builder.fields.typeMultiSelect": "builder.fieldType.multi-select"
 };
+function isTranslationUnresolved(result, key, aliases = []) {
+  if (result === void 0 || result === null || result === "") return true;
+  if (typeof result !== "string") return false;
+  if (result === key || aliases.includes(result)) return true;
+  return result.endsWith(key) || aliases.some((alias) => result.endsWith(alias));
+}
+function isResolvedAdapterResult(result, key, aliases) {
+  return typeof result === "string" && result.startsWith("translated:") ? true : !isTranslationUnresolved(result, key, aliases);
+}
+function formatTemplate(template, params) {
+  return template.replace(
+    /\{\{(\w+)\}\}/g,
+    (token, name) => Object.hasOwn(params, name) ? String(params[name]) : token
+  );
+}
+function resolveTranslation(key, aliases, adapter, defaultCatalog, params = {}, locale = "") {
+  const adapterParams = {};
+  for (const [name, value] of Object.entries(params)) {
+    if (typeof value === "string" || typeof value === "number") adapterParams[name] = value;
+  }
+  const translate = (candidate) => adapter?.translate(candidate, locale, adapterParams);
+  const translated = translate(key);
+  if (isResolvedAdapterResult(translated, key, aliases)) return translated;
+  for (const alias of aliases) {
+    const aliased = translate(alias);
+    if (isResolvedAdapterResult(aliased, alias, aliases)) return aliased;
+  }
+  const catalogValue = defaultCatalog?.[key];
+  if (catalogValue !== void 0) return formatTemplate(catalogValue, params);
+  for (const alias of aliases) {
+    const aliasValue = defaultCatalog?.[alias];
+    if (aliasValue !== void 0) return formatTemplate(aliasValue, params);
+  }
+  return key;
+}
 
 // src/builder.tsx
 import { Fragment, jsx, jsxs } from "react/jsx-runtime";
@@ -1302,6 +1337,18 @@ var BUILDER_DEFAULTS = {
   "builder.fields.typeMultiSelect": "Multi-select",
   "builder.fields.typeCheckbox": "Checkbox",
   "builder.fields.typeRadio": "Radio",
+  "builder.fieldCategory.text": "Text",
+  "builder.fieldCategory.choice": "Choice",
+  "builder.fieldCategory.number": "Number",
+  "builder.fieldCategory.advanced": "Advanced",
+  "builder.fieldTypeDescription.text": "A single-line text answer",
+  "builder.fieldTypeDescription.textarea": "A long-form text answer",
+  "builder.fieldTypeDescription.number": "A numeric answer",
+  "builder.fieldTypeDescription.rating": "A rating scale answer",
+  "builder.fieldTypeDescription.radio": "A single-choice answer",
+  "builder.fieldTypeDescription.checkbox": "A yes/no answer",
+  "builder.fieldTypeDescription.select": "A dropdown choice",
+  "builder.fieldTypeDescription.multi-select": "Multiple choices",
   "builder.actions.addField": "Add question",
   "builder.fieldType.text": "Text",
   "builder.fieldType.textarea": "Textarea",
@@ -1316,12 +1363,6 @@ var BUILDER_DEFAULTS = {
   "builder.operator.contains": "contains",
   "builder.operator.not_empty": "is not empty"
 };
-function interpolate(template, params) {
-  return template.replace(
-    /\{\{(\w+)\}\}/g,
-    (token, name) => Object.hasOwn(params, name) ? String(params[name]) : token
-  );
-}
 function BuilderSectionGroup({ children }) {
   return children;
 }
@@ -1526,20 +1567,14 @@ function FormBuilder({
   const [isTranslating, setIsTranslating] = useState(false);
   const [translationError, setTranslationError] = useState(null);
   const [translationReport, setTranslationReport] = useState();
-  const translate = (key, params = {}) => {
-    const translatorParams = {};
-    for (const [name, value] of Object.entries(params)) {
-      if (typeof value === "string" || typeof value === "number") translatorParams[name] = value;
-    }
-    const translated = translator?.translate(key, locale, translatorParams);
-    if (translated !== void 0 && translated !== key) return translated;
-    const alias = BUILDER_TRANSLATION_ALIASES[key];
-    if (alias !== void 0) {
-      const aliased = translator?.translate(alias, locale, translatorParams);
-      if (aliased !== void 0 && aliased !== alias) return aliased;
-    }
-    return translated === void 0 ? interpolate(BUILDER_DEFAULTS[key] ?? key, params) : translated;
-  };
+  const translate = (key, params = {}) => resolveTranslation(
+    key,
+    BUILDER_TRANSLATION_ALIASES[key] === void 0 ? [] : [BUILDER_TRANSLATION_ALIASES[key]],
+    translator,
+    BUILDER_DEFAULTS,
+    params,
+    locale
+  );
   const pagesEnabled = features?.pages ?? true;
   const localizationEnabled = features?.localization ?? true;
   const conditionsEnabled = features?.conditions ?? true;
@@ -2828,7 +2863,7 @@ function FormProvider({
     [initialValues, locale, onSubmit, resetOnSuccess, validSchema, values]
   );
   const translate = useCallback2(
-    (key, params) => translator.translate(key, locale, params),
+    (key, params) => translator.translate(key, locale, params) ?? key,
     [locale, translator]
   );
   const contextValue = useMemo2(
@@ -3949,7 +3984,9 @@ export {
   FormSubmissionError,
   createLocalStorageSubmissionAttemptStore,
   createLocalStorageSubmissionReceiptStore,
+  isTranslationUnresolved,
   resolveInitialFieldType,
+  resolveTranslation,
   submissionReceiptQueryKey,
   useField,
   useForm,

package/package.json

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