@saastro/forms 0.6.2 → 0.7.0

package/dist/index.d.ts

@@ -815,6 +815,10 @@ type StepCondition = ConditionGroup & {
 type Step = {
     /** Step identifier. Optional when using `Record<string, Step>` — the key serves as the id. */
     id?: string;
+    /** Human-facing step title (set by the builder; rendered in multi-step UIs). i18n-translatable. */
+    title?: string;
+    /** Human-facing step description. i18n-translatable. */
+    description?: string;
     fields: string[];
     next?: StepCondition[];
     defaultNext?: string;
@@ -1221,6 +1225,53 @@ interface SubmitConfirmationConfig {
      */
     showOnce?: boolean;
 }
+/** Overlay de traducciones para un idioma concreto. Solo los campos a
+ *  traducir; lo no especificado cae al config base. */
+interface LocaleOverlay {
+    fields?: Record<string, {
+        label?: string;
+        placeholder?: string;
+        helperText?: string;
+        description?: string;
+        /** Opciones traducidas; se casan con las del base por `value`. */
+        options?: Array<{
+            value: string | number;
+            label: string;
+        }>;
+    }>;
+    buttons?: {
+        submit?: {
+            label?: string;
+        };
+        next?: {
+            label?: string;
+        };
+        back?: {
+            label?: string;
+        };
+    };
+    steps?: Record<string, {
+        title?: string;
+        description?: string;
+    }>;
+    messages?: {
+        success?: string;
+        error?: string;
+    };
+}
+/**
+ * Traducciones del formulario. El config base contiene los strings del
+ * `defaultLocale`; `translations[locale]` aporta overlays que se mergean
+ * sobre la base al renderizar (ver `applyLocale`). Aditivo y opcional.
+ */
+interface FormI18n {
+    /** Idioma en el que están escritos los strings base del config. */
+    defaultLocale?: string;
+    /** Idiomas disponibles (para el switcher del builder, p.ej. ['es','en','fr']). */
+    locales?: string[];
+    /** Overlays por idioma. */
+    translations?: Record<string, LocaleOverlay>;
+}
 interface FormConfig {
     formId: string;
     fields: Fields;
@@ -1258,6 +1309,14 @@ interface FormConfig {
      * Define si las acciones se ejecutan en paralelo o secuencial.
      */
     submitExecution?: SubmitExecutionConfig;
+    /**
+     * Idioma activo a renderizar. Cuando se setea (y hay `i18n.translations`
+     * para ese locale), `useFormState` aplica el overlay sobre el config base.
+     * Lo pasa el consumidor (p.ej. `HubForm locale=`).
+     */
+    locale?: string;
+    /** Traducciones por idioma (overlays). Ver `FormI18n` / `applyLocale`. */
+    i18n?: FormI18n;
 }
 
 /**
@@ -3460,6 +3519,7 @@ declare function useFormState({ config: rawConfig, fields: rawFields, steps: raw
     fields: Fields;
     steps?: Steps;
 }): {
+    config: FormConfig;
     currentStepId: string;
     loading: boolean;
     submitted: boolean;
@@ -3861,6 +3921,13 @@ interface HubFormProps {
     hubUrl?: string;
     siteId: string;
     formSlug: string;
+    /**
+     * Active locale to render the form in. When the fetched schema carries
+     * `i18n.translations[locale]`, labels/placeholders/options/buttons/steps
+     * are translated; untranslated strings fall back to the base. Pass the
+     * host page's current language (e.g. Astro `Astro.locals.lang`).
+     */
+    locale?: string;
     /** Custom UI while the schema is being fetched. Defaults to a skeleton. */
     loadingFallback?: ReactNode;
     /**
@@ -3893,7 +3960,21 @@ interface HubFormProps {
      */
     formProps?: Omit<FormProps, 'config'>;
 }
-declare function HubForm({ hubUrl, siteId, formSlug, loadingFallback, errorFallback, unconfiguredFallback, successFallback, onSuccess, onError, formProps, }: HubFormProps): string | number | bigint | boolean | Iterable<ReactNode> | Promise<string | number | bigint | boolean | React$1.ReactPortal | React$1.ReactElement<unknown, string | React$1.JSXElementConstructor<any>> | Iterable<ReactNode> | null | undefined> | react_jsx_runtime.JSX.Element;
+declare function HubForm({ hubUrl, siteId, formSlug, locale, loadingFallback, errorFallback, unconfiguredFallback, successFallback, onSuccess, onError, formProps, }: HubFormProps): string | number | bigint | boolean | Iterable<ReactNode> | Promise<string | number | bigint | boolean | React$1.ReactPortal | React$1.ReactElement<unknown, string | React$1.JSXElementConstructor<any>> | Iterable<ReactNode> | null | undefined> | react_jsx_runtime.JSX.Element;
+
+/**
+ * Applies a locale's translation overlay onto a base FormConfig.
+ *
+ * The base config holds the strings for `i18n.defaultLocale`. This merges
+ * `config.i18n.translations[locale]` on top — labels, placeholders, helper
+ * text, descriptions, option labels (matched by `value`), button labels,
+ * step titles/descriptions and success/error messages. Anything not
+ * translated falls back to the base value (graceful degradation).
+ *
+ * Pure: returns a new config and never mutates the input. A missing locale
+ * or empty overlay is a no-op (returns the original reference).
+ */
+declare function applyLocale(config: FormConfig, locale?: string): FormConfig;
 
 /**
  * Test Data Generator — generates realistic field values for form testing.
@@ -3949,4 +4030,4 @@ declare function getFieldClass(formLayout?: {
  */
 declare function getHiddenClasses(hidden?: Partial<Record<Breakpoint, 'visible' | 'hidden'>>): string;
 
-export { type AccordionContentProps, type AccordionItemProps, type AccordionProps, type AccordionTriggerProps, BUILD_METHODS, BUILTIN_RESOLVERS, type BaseFieldProps, type Breakpoint$1 as Breakpoint, type BuiltinTransform, type ButtonCardFieldProps, type ButtonCardOption, type ButtonCheckboxFieldProps, type ButtonConfig, type ButtonProps, type ButtonRadioFieldProps, COMMON_CLASSES, COMMON_METHODS, COMMON_STRINGS, type CalendarProps, type CheckboxFieldProps, type CheckboxGroupFieldProps, type CheckboxProps, type ColumnsValue, type ComboboxFieldProps, type CommandEmptyProps, type CommandFieldProps, type CommandGroupProps, type CommandInputProps, type CommandItemProps, type CommandListProps, type CommandProps, type ComponentName, type ComponentOverrides, ComponentProvider, type ComponentProviderProps, type ComponentRegistry, type ComponentRegistryInput, ComponentResolver, type ComponentResolverConfig, type Condition, type ConditionGroup, type ConditionOperator, type CreateHubFormSubmitOptions, type CurrencyFieldProps, type CustomSubmitAction, type CustomSubmitConfig, DEFAULT_HUB_URL, type DatabowlConfig, type DateFieldProps, type DateRangeFieldProps, type DefaultSubmitConfig, type DefinePlugin, type DialogContentProps, type DialogDescriptionProps, type DialogHeaderProps, type DialogProps, type DialogTitleProps, type DialogTriggerProps, type EmailProvider, type EmailSubmitAction, type EndpointConfig, FIELD_DEFAULTS, FieldBuilder, type FieldConfig, type FieldDescriptionProps, type FieldErrorProps, type FieldLabelProps, type FieldLayoutConfig, type FieldMapEntry, type FieldMapping, type FieldMappingConfig, type FieldProps, FieldRenderer, type FieldResolver, type FieldTransformFn, type Fields, type FileFieldProps, Form, FormBuilder, type FormButtonProps, type FormButtons, FormComponentsProvider, type FormComponentsProviderProps, type FormConfig, type FormControlProps, type FormFieldProps, type FormLayout, type FormPlugin, type FormProps, type FormRef, type FormStepsInfo, type GapValue, type GlobModules, type HiddenFieldProps, type HtmlFieldProps, type HttpAuthConfig, type HttpBodyConfig, type HttpEndpointConfig, type HttpRetryConfig, type HttpSubmitAction, HubForm, type HubFormProps, type InputGroupFieldProps, type InputOTPGroupProps, type InputOTPProps, type InputOTPSlotProps, type InputProps, type InputSize, type IntegrationSubmitAction, InternalComponentProvider, type InternalComponentProviderProps, type LabelProps, MissingComponentFallback, type MissingComponentFallbackProps, type NativeSelectFieldProps, type NativeSelectProps, OPTION_BASED_TYPES, type Option, type OtpFieldProps, type PartialComponentRegistry, PluginManager, type PopoverContentProps, type PopoverProps, type PopoverTriggerProps, type PropertyMapping, type RadioFieldProps, type RadioGroupItemProps, type RadioGroupProps, type RangeFieldProps, type RecaptchaConfig, type RecaptchaPluginConfig, type RepeaterFieldProps, type ResolvedComponents, SUSPENSE_CONFIG, type SchemaType, type SelectContentProps, type SelectFieldProps, type SelectItemProps, type SelectProps, type SelectTriggerProps, type SelectValueProps, type SeparatorProps, type SerializableFieldResolver, type SerializationHint, type SliderFieldProps, type SliderProps, type Step, type StepCondition, type StepInfo, type StepStatus, type Steps, StepsAccordion, StepsNavigation, StepsProgress, type SubmitAction, type SubmitActionCondition, type SubmitActionNode, type SubmitActionResult, type SubmitActionType, type SubmitActionsResult, type SubmitConfig, type SubmitConfirmationConfig, type SubmitExecutionConfig, type SubmitTrigger, type SubmitTriggerType, type SubmitType, type SwitchFieldProps, type SwitchGroupFieldProps, type SwitchProps, TYPE_SPECIFIC_PROPERTIES, type TestDataLocale, type TestDataOptions, type TextFieldProps, type TextareaFieldProps, type TextareaProps, type TooltipContentProps, type TooltipProps, type TooltipProviderProps, type TooltipTriggerProps, type TurnstilePluginConfig, type UseSubmitConfirmationReturn, VALIDATION_METHODS, type ValidateComponentRegistry, type ValidationContext, type ValidationPresetMeta, type ValidationRules, type WebhookSubmitAction, analyticsPlugin, applyBuiltinTransform, applyFieldMapping, applyFieldMappingSync, applyFieldTransforms, applyTransform, autosavePlugin, buildRequiredOnlySchema, compileValidationRules, configureComponents, coreComponents, createComponentRegistry, createHubFormSubmit, createMissingComponentPlaceholder, createShadcnRegistry, databowlAction, databowlPlugin, defaultSubmit, definePlugin, detectLocale, executeCustomAction, executeEmailAction, executeHttpAction, executeSubmitAction, executeSubmitActions, executeSubmitActionsByTrigger, executeWebhookAction, fieldTypeComponents, generateFieldValue, generateTestData, getActionsByTrigger, getAllKnownMethods, getAvailablePresets, getComponentResolver, getFieldClass, getFormGridClass, getHiddenClasses, getInstallCommand, getMinDelayMs, getMissingComponents, getRequiredComponents, globalPluginManager, groupMissingByPackage, iconVariants, iconVariantsConfig, inputVariants, inputVariantsConfig, isAdvancedMapping, isValidationRules, isZodSchema, localStoragePlugin, mergeComponentRegistries, parseGlobModules, pxToRem, recaptchaPlugin, registerPreset, resolvePreset, resolveValue, resolveValueSync, textareaVariants, textareaVariantsConfig, turnstilePlugin, useComponentMode, useComponents, useComputedFields, useFormLayout, useFormState, useFormStepsInfo, useHasComponentProvider, useHiddenFieldResolvers, usePartialComponents, useRecaptcha, useSubmitActionTriggers, useSubmitConfirmation, withComponents };
+export { type AccordionContentProps, type AccordionItemProps, type AccordionProps, type AccordionTriggerProps, BUILD_METHODS, BUILTIN_RESOLVERS, type BaseFieldProps, type Breakpoint$1 as Breakpoint, type BuiltinTransform, type ButtonCardFieldProps, type ButtonCardOption, type ButtonCheckboxFieldProps, type ButtonConfig, type ButtonProps, type ButtonRadioFieldProps, COMMON_CLASSES, COMMON_METHODS, COMMON_STRINGS, type CalendarProps, type CheckboxFieldProps, type CheckboxGroupFieldProps, type CheckboxProps, type ColumnsValue, type ComboboxFieldProps, type CommandEmptyProps, type CommandFieldProps, type CommandGroupProps, type CommandInputProps, type CommandItemProps, type CommandListProps, type CommandProps, type ComponentName, type ComponentOverrides, ComponentProvider, type ComponentProviderProps, type ComponentRegistry, type ComponentRegistryInput, ComponentResolver, type ComponentResolverConfig, type Condition, type ConditionGroup, type ConditionOperator, type CreateHubFormSubmitOptions, type CurrencyFieldProps, type CustomSubmitAction, type CustomSubmitConfig, DEFAULT_HUB_URL, type DatabowlConfig, type DateFieldProps, type DateRangeFieldProps, type DefaultSubmitConfig, type DefinePlugin, type DialogContentProps, type DialogDescriptionProps, type DialogHeaderProps, type DialogProps, type DialogTitleProps, type DialogTriggerProps, type EmailProvider, type EmailSubmitAction, type EndpointConfig, FIELD_DEFAULTS, FieldBuilder, type FieldConfig, type FieldDescriptionProps, type FieldErrorProps, type FieldLabelProps, type FieldLayoutConfig, type FieldMapEntry, type FieldMapping, type FieldMappingConfig, type FieldProps, FieldRenderer, type FieldResolver, type FieldTransformFn, type Fields, type FileFieldProps, Form, FormBuilder, type FormButtonProps, type FormButtons, FormComponentsProvider, type FormComponentsProviderProps, type FormConfig, type FormControlProps, type FormFieldProps, type FormI18n, type FormLayout, type FormPlugin, type FormProps, type FormRef, type FormStepsInfo, type GapValue, type GlobModules, type HiddenFieldProps, type HtmlFieldProps, type HttpAuthConfig, type HttpBodyConfig, type HttpEndpointConfig, type HttpRetryConfig, type HttpSubmitAction, HubForm, type HubFormProps, type InputGroupFieldProps, type InputOTPGroupProps, type InputOTPProps, type InputOTPSlotProps, type InputProps, type InputSize, type IntegrationSubmitAction, InternalComponentProvider, type InternalComponentProviderProps, type LabelProps, type LocaleOverlay, MissingComponentFallback, type MissingComponentFallbackProps, type NativeSelectFieldProps, type NativeSelectProps, OPTION_BASED_TYPES, type Option, type OtpFieldProps, type PartialComponentRegistry, PluginManager, type PopoverContentProps, type PopoverProps, type PopoverTriggerProps, type PropertyMapping, type RadioFieldProps, type RadioGroupItemProps, type RadioGroupProps, type RangeFieldProps, type RecaptchaConfig, type RecaptchaPluginConfig, type RepeaterFieldProps, type ResolvedComponents, SUSPENSE_CONFIG, type SchemaType, type SelectContentProps, type SelectFieldProps, type SelectItemProps, type SelectProps, type SelectTriggerProps, type SelectValueProps, type SeparatorProps, type SerializableFieldResolver, type SerializationHint, type SliderFieldProps, type SliderProps, type Step, type StepCondition, type StepInfo, type StepStatus, type Steps, StepsAccordion, StepsNavigation, StepsProgress, type SubmitAction, type SubmitActionCondition, type SubmitActionNode, type SubmitActionResult, type SubmitActionType, type SubmitActionsResult, type SubmitConfig, type SubmitConfirmationConfig, type SubmitExecutionConfig, type SubmitTrigger, type SubmitTriggerType, type SubmitType, type SwitchFieldProps, type SwitchGroupFieldProps, type SwitchProps, TYPE_SPECIFIC_PROPERTIES, type TestDataLocale, type TestDataOptions, type TextFieldProps, type TextareaFieldProps, type TextareaProps, type TooltipContentProps, type TooltipProps, type TooltipProviderProps, type TooltipTriggerProps, type TurnstilePluginConfig, type UseSubmitConfirmationReturn, VALIDATION_METHODS, type ValidateComponentRegistry, type ValidationContext, type ValidationPresetMeta, type ValidationRules, type WebhookSubmitAction, analyticsPlugin, applyBuiltinTransform, applyFieldMapping, applyFieldMappingSync, applyFieldTransforms, applyLocale, applyTransform, autosavePlugin, buildRequiredOnlySchema, compileValidationRules, configureComponents, coreComponents, createComponentRegistry, createHubFormSubmit, createMissingComponentPlaceholder, createShadcnRegistry, databowlAction, databowlPlugin, defaultSubmit, definePlugin, detectLocale, executeCustomAction, executeEmailAction, executeHttpAction, executeSubmitAction, executeSubmitActions, executeSubmitActionsByTrigger, executeWebhookAction, fieldTypeComponents, generateFieldValue, generateTestData, getActionsByTrigger, getAllKnownMethods, getAvailablePresets, getComponentResolver, getFieldClass, getFormGridClass, getHiddenClasses, getInstallCommand, getMinDelayMs, getMissingComponents, getRequiredComponents, globalPluginManager, groupMissingByPackage, iconVariants, iconVariantsConfig, inputVariants, inputVariantsConfig, isAdvancedMapping, isValidationRules, isZodSchema, localStoragePlugin, mergeComponentRegistries, parseGlobModules, pxToRem, recaptchaPlugin, registerPreset, resolvePreset, resolveValue, resolveValueSync, textareaVariants, textareaVariantsConfig, turnstilePlugin, useComponentMode, useComponents, useComputedFields, useFormLayout, useFormState, useFormStepsInfo, useHasComponentProvider, useHiddenFieldResolvers, usePartialComponents, useRecaptcha, useSubmitActionTriggers, useSubmitConfirmation, withComponents };

package/dist/index.js

@@ -2611,6 +2611,82 @@ function compileValidationRules(rules, fieldType) {
   return buildStringSchema(mergedRules);
 }
 
+// src/utils/applyLocale.ts
+function applyLocale(config, locale) {
+  const overlay = locale ? config.i18n?.translations?.[locale] : void 0;
+  if (!overlay) return config;
+  return {
+    ...config,
+    fields: mergeFields(config.fields, overlay.fields),
+    ...overlay.steps ? { steps: mergeSteps(config.steps, overlay.steps) } : {},
+    ...overlay.buttons ? { buttons: mergeButtons(config.buttons, overlay.buttons) } : {},
+    ...mergeMessages(config, overlay.messages)
+  };
+}
+function mergeFields(fields, tFields) {
+  if (!tFields) return fields;
+  const out = {};
+  for (const [name, field] of Object.entries(fields)) {
+    const t = tFields[name];
+    if (!t) {
+      out[name] = field;
+      continue;
+    }
+    const merged = { ...field };
+    if (t.label !== void 0) merged.label = t.label;
+    if (t.placeholder !== void 0) merged.placeholder = t.placeholder;
+    if (t.helperText !== void 0) merged.helperText = t.helperText;
+    if (t.description !== void 0) merged.description = t.description;
+    if (t.options) merged.options = mergeOptions(merged.options, t.options);
+    out[name] = merged;
+  }
+  return out;
+}
+function mergeOptions(baseOptions, tOptions) {
+  if (!Array.isArray(baseOptions)) return baseOptions;
+  const byValue = new Map(tOptions.map((o) => [o.value, o.label]));
+  return baseOptions.map((opt) => {
+    if (opt && typeof opt === "object" && "value" in opt) {
+      const label = byValue.get(opt.value);
+      if (label !== void 0) return { ...opt, label };
+    }
+    return opt;
+  });
+}
+function mergeSteps(steps, tSteps) {
+  const out = {};
+  for (const [id, step] of Object.entries(steps)) {
+    const t = tSteps[id];
+    out[id] = t ? {
+      ...step,
+      ...t.title !== void 0 ? { title: t.title } : {},
+      ...t.description !== void 0 ? { description: t.description } : {}
+    } : step;
+  }
+  return out;
+}
+function mergeButtons(buttons, tButtons) {
+  const merged = { ...buttons ?? {} };
+  for (const key of ["submit", "next", "back"]) {
+    const tLabel = tButtons[key]?.label;
+    if (tLabel !== void 0) {
+      merged[key] = { ...merged[key] ?? { type: key }, label: tLabel };
+    }
+  }
+  return merged;
+}
+function mergeMessages(config, tMessages) {
+  if (!tMessages) return {};
+  const out = {};
+  if (tMessages.success !== void 0 && typeof config.successMessage !== "function") {
+    out.successMessage = tMessages.success;
+  }
+  if (tMessages.error !== void 0 && typeof config.errorMessage !== "function") {
+    out.errorMessage = tMessages.error;
+  }
+  return out;
+}
+
 // src/hooks/useFormSteps.ts
 import { useState as useState2 } from "react";
 function useFormSteps(steps, initialStepId) {
@@ -2939,10 +3015,8 @@ function useFormState({
   steps: rawSteps
 }) {
   const config = useMemo3(() => {
-    if (rawConfig.pluginManager) {
-      return rawConfig.pluginManager.transformConfig(rawConfig);
-    }
-    return rawConfig;
+    const transformed = rawConfig.pluginManager ? rawConfig.pluginManager.transformConfig(rawConfig) : rawConfig;
+    return transformed.locale ? applyLocale(transformed, transformed.locale) : transformed;
   }, [rawConfig]);
   const fields = config.fields;
   const steps = config.steps;
@@ -3106,6 +3180,10 @@ function useFormState({
     return success;
   };
   return {
+    // The locale-resolved config (plugin transforms + i18n overlay applied).
+    // Consumers MUST render from this, not the raw config prop, so translated
+    // labels/placeholders/options/button labels/step titles reach the UI.
+    config,
     currentStepId,
     loading,
     submitted,
@@ -3867,9 +3945,12 @@ function getInstallCommand(missing) {
 
 // src/components/Form.tsx
 import { Fragment as Fragment2, jsx as jsx10, jsxs as jsxs7 } from "react/jsx-runtime";
-var FormInner = forwardRef(function FormInner2({ config, onSubmit, onError, className }, ref) {
+var FormInner = forwardRef(function FormInner2({ config: rawConfig, onSubmit, onError, className }, ref) {
   const components = useComponents();
   const {
+    // Locale-resolved config (plugin transforms + i18n overlay). Render from
+    // this, NOT rawConfig, so translated labels/placeholders/buttons show up.
+    config,
     currentStepId,
     loading,
     submitted,
@@ -3883,9 +3964,9 @@ var FormInner = forwardRef(function FormInner2({ config, onSubmit, onError, clas
     handleSubmit,
     stepHistory
   } = useFormState({
-    config,
-    fields: config.fields,
-    steps: config.steps
+    config: rawConfig,
+    fields: rawConfig.fields,
+    steps: rawConfig.steps
   });
   useImperativeHandle(
     ref,
@@ -7120,6 +7201,7 @@ function HubForm({
   hubUrl,
   siteId,
   formSlug,
+  locale,
   loadingFallback,
   errorFallback,
   unconfiguredFallback,
@@ -7205,6 +7287,7 @@ function HubForm({
   const config = {
     ...state.schema,
     submit: wrappedSubmit,
+    ...locale ? { locale } : {},
     ...captcha ? { pluginManager: captcha.pm } : {}
   };
   return /* @__PURE__ */ jsxs11(Fragment3, { children: [
@@ -7495,6 +7578,7 @@ export {
   applyFieldMapping,
   applyFieldMappingSync,
   applyFieldTransforms,
+  applyLocale,
   applyTransform,
   autosavePlugin,
   buildRequiredOnlySchema,