@envisiongroup/porygon 1.0.0-rc.9 → 1.0.0

package/dist/react-components/forms/EFWForm/EFWForm.types.d.ts

@@ -1,11 +1,12 @@
-import { EFWInputFieldProps, EFWInputFieldValue } from '../../fields/EFWInputField';
-import { EFWTagPickerFieldProps, EFWTagPickerFieldValue } from '../../fields/EFWTagPickerField';
-import { EFWDatePickerFieldProps, EFWDatePickerFieldValue } from '../../fields/EFWDatePickerField';
-import { EFWTextAreaFieldProps, EFWTextAreaFieldValue } from '../../fields/EFWTextAreaField';
-import { EFWSwitchFieldProps, EFWSwitchFieldValue } from '../../fields/EFWSwitchField';
-import { EFWAttachmentsFieldProps, EFWAttachmentsFieldValue } from '../../fields/EFWAttachmentsField';
-import { EFWNumberInputFieldProps, EFWNumberInputFieldValue } from '../../fields/EFWNumberInputField';
+import { EFWInputFieldProps, EFWInputFieldValue } from '../../fields/Input';
+import { EFWTagPickerFieldProps, EFWTagPickerFieldValue } from '../../fields/TagPicker';
+import { EFWDatePickerFieldProps, EFWDatePickerFieldValue } from '../../fields/DatePicker';
+import { EFWTextAreaFieldProps, EFWTextAreaFieldValue } from '../../fields/TextArea';
+import { EFWSwitchFieldProps, EFWSwitchFieldValue } from '../../fields/Switch';
+import { EFWAttachmentsFieldProps, EFWAttachmentsFieldValue } from '../../fields/Attachments';
+import { EFWNumberInputFieldProps, EFWNumberInputFieldValue } from '../../fields/NumberInput';
 import { EFWFormMessageBar } from '../EFWFormMessageBarGroup/EFWFormMessageBarGroup.types';
+import { EFWFormExtendedLocaleText } from '../../i18n';
 import { MutableRefObject } from 'react';
 
 /**
@@ -19,7 +20,7 @@ import { MutableRefObject } from 'react';
  *   // El tipo es válido
  * }
  */
-export declare const FORM_FIELD_TYPES: readonly ["Text", "Number", "Choice", "Note", "Boolean", "MultiChoice", "Date", "Attachments"];
+declare const FORM_FIELD_TYPES: readonly ["Text", "Number", "Choice", "Note", "Boolean", "MultiChoice", "Date", "Attachments"];
 /**
  * Tipo union literal derivado de FORM_FIELD_TYPES.
  * Representa todos los tipos de campos posibles en el sistema.
@@ -28,7 +29,7 @@ export declare const FORM_FIELD_TYPES: readonly ["Text", "Number", "Choice", "No
  * const fieldType: EFWFormFieldType = 'Text'; // ✓ Válido
  * const invalidType: EFWFormFieldType = 'Email'; // ✗ Error de TypeScript
  */
-export type EFWFormFieldType = typeof FORM_FIELD_TYPES[number];
+export type EFWFormFieldType = (typeof FORM_FIELD_TYPES)[number];
 /**
  * Mapeo que asocia cada tipo de campo con su tipo de valor correspondiente.
  * Este mapeo es fundamental para el tipado estricto de los valores del formulario.
@@ -39,14 +40,14 @@ export type EFWFormFieldType = typeof FORM_FIELD_TYPES[number];
  * type NumberFieldValue = EFWFormFieldValueMap['Number']; // EFWNumberInputFieldValue
  */
 export type EFWFormFieldValueMap = {
-    'Text': EFWInputFieldValue;
-    'Number': EFWNumberInputFieldValue;
-    'Choice': EFWTagPickerFieldValue[];
-    'Note': EFWTextAreaFieldValue;
-    'Boolean': EFWSwitchFieldValue;
-    'MultiChoice': EFWTagPickerFieldValue[];
-    'Date': EFWDatePickerFieldValue[] | undefined;
-    'Attachments': EFWAttachmentsFieldValue[] | undefined;
+    Text: EFWInputFieldValue;
+    Number: EFWNumberInputFieldValue;
+    Choice: EFWTagPickerFieldValue[];
+    Note: EFWTextAreaFieldValue;
+    Boolean: EFWSwitchFieldValue;
+    MultiChoice: EFWTagPickerFieldValue[];
+    Date: EFWDatePickerFieldValue[] | undefined;
+    Attachments: EFWAttachmentsFieldValue[] | undefined;
 };
 /**
  * Tipo genérico que obtiene el tipo de valor para un campo específico.
@@ -73,7 +74,7 @@ export type EFWFormFieldValue<T extends EFWFormFieldType = EFWFormFieldType> = E
  *   value: 'John Doe'
  * };
  */
-export interface EFWFormFieldBaseProps<T extends EFWFormFieldType = EFWFormFieldType> {
+interface EFWFormFieldBaseProps<T extends EFWFormFieldType = EFWFormFieldType> {
     readonly id: string;
     readonly typeAsString: T;
     readonly internalName: string;
@@ -83,19 +84,19 @@ export interface EFWFormFieldBaseProps<T extends EFWFormFieldType = EFWFormField
  * Propiedades para campos de entrada de texto.
  * Combina las propiedades base con las específicas del componente de texto.
  */
-export interface EFWFormInputFieldProps extends EFWFormFieldBaseProps<'Text'>, EFWInputFieldProps {
+export interface EFWFormInputFieldProps extends EFWFormFieldBaseProps<"Text">, EFWInputFieldProps {
 }
 /**
  * Propiedades para campos de entrada numérica.
  * Combina las propiedades base con las específicas del componente numérico.
  */
-export interface EFWFormNumberInputFieldProps extends EFWFormFieldBaseProps<'Number'>, EFWNumberInputFieldProps {
+export interface EFWFormNumberInputFieldProps extends EFWFormFieldBaseProps<"Number">, EFWNumberInputFieldProps {
 }
 /**
  * Propiedades para campos de selección única.
  * Utiliza el componente TagPicker pero limitado a una sola selección.
  */
-export interface EFWFormTagPickerFieldProps extends EFWFormFieldBaseProps<'Choice'>, EFWTagPickerFieldProps {
+export interface EFWFormTagPickerFieldProps extends EFWFormFieldBaseProps<"Choice">, EFWTagPickerFieldProps {
 }
 /**
  * Propiedades para campos de selección múltiple.
@@ -103,47 +104,47 @@ export interface EFWFormTagPickerFieldProps extends EFWFormFieldBaseProps<'Choic
  *
  * @property {true} multiple - Marca obligatoria que indica selección múltiple
  */
-export interface EFWFormMultiChoiceFieldProps extends EFWFormFieldBaseProps<'MultiChoice'>, EFWTagPickerFieldProps {
+export interface EFWFormMultiChoiceFieldProps extends EFWFormFieldBaseProps<"MultiChoice">, EFWTagPickerFieldProps {
     multiple: true;
 }
 /**
  * Propiedades para campos de selección de fecha.
  * Puede manejar una o múltiples fechas dependiendo de la configuración.
  */
-export interface EFWFormDatePickerFieldProps extends EFWFormFieldBaseProps<'Date'>, EFWDatePickerFieldProps {
+export interface EFWFormDatePickerFieldProps extends EFWFormFieldBaseProps<"Date">, EFWDatePickerFieldProps {
 }
 /**
  * Propiedades para campos de área de texto.
  * Permite entrada de texto multilínea con mayor capacidad que los campos de texto simples.
  */
-export interface EFWFormTextAreaFieldProps extends EFWFormFieldBaseProps<'Note'>, EFWTextAreaFieldProps {
+export interface EFWFormTextAreaFieldProps extends EFWFormFieldBaseProps<"Note">, EFWTextAreaFieldProps {
 }
 /**
  * Propiedades para campos de tipo switch/boolean.
  * Representa valores de encendido/apagado, sí/no, habilitado/deshabilitado.
  */
-export interface EFWFormSwitchFieldProps extends EFWFormFieldBaseProps<'Boolean'>, EFWSwitchFieldProps {
+export interface EFWFormSwitchFieldProps extends EFWFormFieldBaseProps<"Boolean">, EFWSwitchFieldProps {
 }
 /**
  * Propiedades para campos de archivos adjuntos.
  * Permite la carga y gestión de uno o múltiples archivos.
  */
-export interface EFWFormAttachmentFieldProps extends EFWFormFieldBaseProps<'Attachments'>, EFWAttachmentsFieldProps {
+export interface EFWFormAttachmentFieldProps extends EFWFormFieldBaseProps<"Attachments">, EFWAttachmentsFieldProps {
 }
 /**
  * Mapeo que asocia cada tipo de campo con su interfaz de propiedades correspondiente.
  * Este mapeo permite la resolución automática del tipo correcto de propiedades
  * basándose en el tipo de campo especificado.
  */
-export type EFWFormFieldPropsMap = {
-    'Text': EFWFormInputFieldProps;
-    'Number': EFWFormNumberInputFieldProps;
-    'Choice': EFWFormTagPickerFieldProps;
-    'Note': EFWFormTextAreaFieldProps;
-    'Boolean': EFWFormSwitchFieldProps;
-    'MultiChoice': EFWFormMultiChoiceFieldProps;
-    'Date': EFWFormDatePickerFieldProps;
-    'Attachments': EFWFormAttachmentFieldProps;
+type EFWFormFieldPropsMap = {
+    Text: EFWFormInputFieldProps;
+    Number: EFWFormNumberInputFieldProps;
+    Choice: EFWFormTagPickerFieldProps;
+    Note: EFWFormTextAreaFieldProps;
+    Boolean: EFWFormSwitchFieldProps;
+    MultiChoice: EFWFormMultiChoiceFieldProps;
+    Date: EFWFormDatePickerFieldProps;
+    Attachments: EFWFormAttachmentFieldProps;
 };
 /**
  * Tipo genérico que resuelve las propiedades correctas para un tipo de campo específico.
@@ -166,7 +167,7 @@ export type EFWFormFieldProps<T extends EFWFormFieldType = EFWFormFieldType> = E
  *   }
  * };
  */
-export interface ResponsiveGridConfig {
+interface ResponsiveGridConfig {
     autoFit: {
         minColumnWidth: string;
         maxColumns?: number;
@@ -209,7 +210,57 @@ export type GridTemplateColumnsType = number | ResponsiveGridConfig | string;
  * @typedef {boolean} IsUnion
  * @private
  */
-type IsUnion<T, U = T> = (T extends any ? (U extends T ? 0 : 1) : never) extends 0 ? false : true;
+type IsUnion<T, U = T> = (T extends any ? U extends T ? 0 : 1 : never) extends 0 ? false : true;
+/**
+ * Convierte una unión de tipos en su intersección.
+ *
+ * @example
+ * type A = { x: string } | { y: number };
+ * type B = UnionToIntersection<A>; // { x: string } & { y: number }
+ */
+type UnionToIntersection<U> = (U extends unknown ? (value: U) => void : never) extends (value: infer I) => void ? I : never;
+/**
+ * Obtiene todas las claves de una unión de objetos.
+ */
+type UnionKeys<U> = U extends unknown ? keyof U : never;
+/**
+ * Obtiene la unión de tipos de una propiedad K en una unión de objetos U.
+ */
+type UnionProp<U, K extends PropertyKey> = U extends unknown ? K extends keyof U ? U[K] : never : never;
+/**
+ * Obtiene la intersección de tipos de una propiedad K en una unión de objetos U.
+ */
+type IntersectionProp<U, K extends PropertyKey> = UnionToIntersection<U extends unknown ? {
+    __type: K extends keyof U ? U[K] : never;
+} : never> extends {
+    __type: infer V;
+} ? V : never;
+/**
+ * Verifica si una clave K existe en todos los miembros de la unión U.
+ */
+type IsKeyInAllMembers<U, K extends PropertyKey> = Exclude<U extends unknown ? (K extends keyof U ? true : false) : never, true> extends never ? true : false;
+/**
+ * Claves que nunca deben actualizarse en modo mixto.
+ * Evita el caso de "value" con tipos incompatibles entre campos.
+ */
+type DisallowedMixedUpdateKeys = "selectedOptions" | "selectedDates" | "files";
+/**
+ * Permite "value" en modo mixto solo cuando todos los tipos involucrados son Text o Note.
+ */
+type SupportsMixedValueForFieldTypes<FT extends EFWFormFieldType> = Exclude<FT, "Text" | "Note"> extends never ? true : false;
+/**
+ * Claves que existen en todos los miembros de U y cuyo tipo es compatible entre todos.
+ * "Compatible" se define como tener una intersección no vacía del tipo de la clave.
+ */
+type CompatibleCommonKeys<U, FT extends EFWFormFieldType = EFWFormFieldType> = {
+    [K in UnionKeys<U>]: K extends "value" ? SupportsMixedValueForFieldTypes<FT> extends true ? IsKeyInAllMembers<U, K> extends true ? [IntersectionProp<U, K>] extends [never] ? never : K : never : never : K extends DisallowedMixedUpdateKeys ? never : IsKeyInAllMembers<U, K> extends true ? [IntersectionProp<U, K>] extends [never] ? never : K : never;
+}[UnionKeys<U>];
+/**
+ * Props comunes compatibles para una unión de tipos de campos.
+ */
+type CompatibleCommonProps<U, FT extends EFWFormFieldType = EFWFormFieldType> = {
+    [K in CompatibleCommonKeys<U, FT>]?: UnionProp<U, K>;
+};
 /**
  * Extrae los nombres de campos como tipos literales de un array de propiedades de campos.
  *
@@ -221,7 +272,7 @@ type IsUnion<T, U = T> = (T extends any ? (U extends T ? 0 : 1) : never) extends
  * ];
  * type FieldNames = ExtractFieldNames<MyFields>; // 'name' | 'age'
  */
-export type ExtractFieldNames<T extends readonly EFWFormFieldProps[]> = T[number]['internalName'];
+export type ExtractFieldNames<T extends readonly EFWFormFieldProps[]> = T[number]["internalName"];
 /**
  * Extrae el tipo de campo basándose en el nombre interno (internalName).
  *
@@ -232,9 +283,9 @@ export type ExtractFieldNames<T extends readonly EFWFormFieldProps[]> = T[number
  * type NameFieldType = ExtractFieldType<MyFields, 'name'>; // 'Text'
  * type AgeFieldType = ExtractFieldType<MyFields, 'age'>; // 'Number'
  */
-export type ExtractFieldType<T extends readonly EFWFormFieldProps[], K extends string> = Extract<T[number], {
+type ExtractFieldType<T extends readonly EFWFormFieldProps[], K extends string> = Extract<T[number], {
     internalName: K;
-}>['typeAsString'];
+}>["typeAsString"];
 /**
  * Obtiene el tipo de valor correcto para un campo específico.
  *
@@ -254,7 +305,7 @@ export type GetFieldValue<T extends readonly EFWFormFieldProps[], K extends stri
  * type NameProps = GetFieldProps<MyFields, 'name'>; // EFWFormInputFieldProps
  * type AgeProps = GetFieldProps<MyFields, 'age'>; // EFWFormNumberInputFieldProps
  */
-export type GetFieldProps<T extends readonly EFWFormFieldProps[], K extends string> = ExtractFieldType<T, K> extends keyof EFWFormFieldPropsMap ? EFWFormFieldPropsMap[ExtractFieldType<T, K>] : EFWFormFieldProps;
+type GetFieldProps<T extends readonly EFWFormFieldProps[], K extends string> = ExtractFieldType<T, K> extends keyof EFWFormFieldPropsMap ? EFWFormFieldPropsMap[ExtractFieldType<T, K>] : EFWFormFieldProps;
 /**
  * Crea un mapeo tipado de todos los valores del formulario.
  * Las claves son los nombres internos de los campos y los valores son del tipo correcto para cada campo.
@@ -298,39 +349,56 @@ type IsGenericFields<T extends readonly EFWFormFieldProps[]> = string extends Ex
  */
 export type EFWFormFieldUpdate<T extends readonly EFWFormFieldProps[] = EFWFormFieldProps[]> = {
     [K in ExtractFieldNames<T>]: Partial<GetFieldProps<T, K>> & {
-        value?: GetFieldValue<T, K> extends EFWFormFieldValueMap['Text' | 'Number' | 'Boolean' | 'Note'] ? GetFieldValue<T, K> : never;
-        selectedOptions?: GetFieldValue<T, K> extends EFWFormFieldValueMap['Choice' | 'MultiChoice'] ? GetFieldValue<T, K> : never;
-        selectedDates?: GetFieldValue<T, K> extends EFWFormFieldValueMap['Date'] ? GetFieldValue<T, K> : never;
-        files?: GetFieldValue<T, K> extends EFWFormFieldValueMap['Attachments'] ? GetFieldValue<T, K> : never;
+        value?: GetFieldValue<T, K> extends EFWFormFieldValueMap["Text" | "Number" | "Boolean" | "Note"] ? GetFieldValue<T, K> : never;
+        selectedOptions?: GetFieldValue<T, K> extends EFWFormFieldValueMap["Choice" | "MultiChoice"] ? GetFieldValue<T, K> : never;
+        selectedDates?: GetFieldValue<T, K> extends EFWFormFieldValueMap["Date"] ? GetFieldValue<T, K> : never;
+        files?: GetFieldValue<T, K> extends EFWFormFieldValueMap["Attachments"] ? GetFieldValue<T, K> : never;
     };
 }[ExtractFieldNames<T>];
 /**
  * Función genérica para actualizar campos cuando no hay tipado fuerte.
- * Se usa cuando el array de campos es genérico y no se conocen los tipos específicos.
+ * Soporta dos modos de uso mediante overloads:
+ *
+ * 1. **Con tipo explícito**: Acceso completo a props del tipo especificado.
+ * 2. **Sin tipo explícito**: Solo propiedades comunes compatibles entre todos los tipos de campo.
  *
- * @template F - Tipo de campo específico (debe especificarse explícitamente)
  * @example
- * // Debe especificar el tipo explícitamente
+ * // ✓ Con tipo explícito → acceso completo a props de Text
  * updateField<'Text'>(['field1', 'field2'], { value: 'nuevo valor' });
+ *
+ * // ✓ Sin tipo explícito → solo props comunes compatibles
+ * updateField(['field1', 'field2'], { disabled: true, required: false });
+ *
+ * // ✗ Error: 'value' no es compatible entre todos los tipos de campo
+ * updateField(['field1', 'field2'], { value: 'algo' });
  */
-export type GenericUpdateFieldFunctionArray = <F extends EFWFormFieldType = never>(internalNames: readonly string[], updates: Partial<EFWFormFieldPropsMap[F]>) => void;
+type GenericUpdateFieldFunctionArray = {
+    <F extends EFWFormFieldType = never>(internalNames: readonly string[], updates: Partial<EFWFormFieldPropsMap[F]>): void;
+    (internalNames: readonly string[], updates: CompatibleCommonProps<EFWFormFieldProps>): void;
+};
 /**
  * Función estricta para actualizar campos cuando hay tipado fuerte.
- * Todos los campos en el array deben ser del mismo tipo para garantizar type safety.
+ * Soporta dos modos de uso mediante overloads:
+ *
+ * 1. **Campos del mismo tipo**: Acceso completo a todas las propiedades del tipo.
+ * 2. **Campos de distintos tipos**: Solo propiedades comunes entre todos los tipos.
  *
  * @template T - Array readonly de propiedades de campos
- * @template Arr - Array de nombres de campos (inferido)
- * @template K - Nombres de campos específicos (inferido)
- * @template FT - Tipo de campo (inferido)
  *
  * @example
- * // ✓ Todos los campos son tipo 'Text'
- * updateField(['name', 'description'], { value: 'nuevo texto' });
+ * // ✓ Todos los campos son tipo 'Text' → acceso completo a props de Text
+ * updateField(['name', 'description'], { value: 'nuevo texto', maxLength: 100 });
+ *
+ * // ✓ Campos de distintos tipos → solo props comunes compatibles
+ * updateField(['name', 'age'], { disabled: true, required: false });
  *
- * // ✗ Error: 'name' es Text pero 'age' es Number (tipos diferentes)
- * updateField(['name', 'age'], { value: 'algo' });
+ * // ✗ Error: 'maxLength' no existe en Number (prop no común entre Text y Number)
+ * updateField(['name', 'age'], { maxLength: 5 });
  */
-export type StrictUpdateFieldFunctionArray<T extends readonly EFWFormFieldProps[]> = <Arr extends readonly ExtractFieldNames<T>[], K extends Arr[number], FT = ExtractFieldType<T, K>>(internalNames: Arr & (IsUnion<FT> extends true ? never : unknown), updates: Partial<GetFieldProps<T, K>>) => void;
+type StrictUpdateFieldFunctionArray<T extends readonly EFWFormFieldProps[]> = {
+    <Arr extends readonly ExtractFieldNames<T>[], K extends Arr[number], FT = ExtractFieldType<T, K>>(internalNames: Arr & (IsUnion<FT> extends true ? never : unknown), updates: Partial<GetFieldProps<T, K>>): void;
+    <Arr extends readonly ExtractFieldNames<T>[]>(internalNames: Arr, updates: CompatibleCommonProps<GetFieldProps<T, Arr[number]>, ExtractFieldType<T, Arr[number]>>): void;
+};
 /**
  * Función de actualización tipada que se adapta según si los campos son genéricos o específicos.
  *
@@ -348,7 +416,7 @@ export type EFWUpdateFieldFunction<T extends readonly EFWFormFieldProps[]> = IsG
  *   console.log('Campo cambió:', value);
  * };
  */
-export type EFWFieldLogicTrigger = 'init' | 'change';
+export type EFWFieldLogicTrigger = "init" | "change";
 /**
  * Contexto compartido para las funciones de lógica de campos.
  */
@@ -359,7 +427,7 @@ export type EFWFieldLogicContext<T extends readonly EFWFormFieldProps[], K exten
     previousValue: GetFieldValue<T, K> | undefined;
     isControlled: boolean;
 };
-export type GenericFieldLogicFunction<T extends readonly EFWFormFieldProps[]> = (value: EFWFormFieldValue, updateField: EFWUpdateFieldFunction<T>, context: EFWFieldLogicContext<T>) => void;
+type GenericFieldLogicFunction<T extends readonly EFWFormFieldProps[]> = (value: EFWFormFieldValue, updateField: EFWUpdateFieldFunction<T>, context: EFWFieldLogicContext<T>) => void;
 /**
  * Función de lógica específica tipada para un campo concreto.
  * El valor está tipado específicamente según el tipo de campo.
@@ -409,9 +477,10 @@ export type EFWFieldLogic<T extends readonly EFWFormFieldProps[] = EFWFormFieldP
  * @interface EFWFormSetValuesOptions
  * @example
  * const options: EFWFormSetValuesOptions = {
- *   triggerOnChange: false,    // No disparar onChange
+ *   triggerOnChange: false,    // No disparar onValuesChange
  *   triggerFieldLogic: true,   // Pero sí ejecutar fieldLogic
- *   overwriteAll: false        // Solo actualizar campos especificados
+ *   overwriteAll: false,       // Solo actualizar campos especificados
+ *   animateUpdatedFields: true // Resaltar campos modificados programáticamente
  * };
  * formRef.current?.setValues({ name: 'Nuevo nombre' }, options);
  */
@@ -419,6 +488,18 @@ export interface EFWFormSetValuesOptions {
     triggerOnChange?: boolean;
     triggerFieldLogic?: boolean;
     overwriteAll?: boolean;
+    animateUpdatedFields?: boolean;
+    /**
+     * Fuerza la actualización incluso cuando el valor nuevo es idéntico al actual
+     * (comparado con `Object.is`). Por defecto `false`: `setValues` omite las keys
+     * que no cambiaron, evitando renders, `fieldLogic` y notificaciones innecesarias.
+     */
+    force?: boolean;
+}
+export type EFWFormResetValuesOptions = Omit<EFWFormSetValuesOptions, "overwriteAll">;
+export interface EFWFormFieldAnimationConfig {
+    setValues?: boolean;
+    resetValues?: boolean;
 }
 /**
  * Interfaz que define todos los métodos expuestos por el componente EFWForm.
@@ -461,10 +542,10 @@ export interface EFWFormMethods<T extends readonly EFWFormFieldProps[] = EFWForm
      * @example
      * // Botón de limpiar formulario
      * const handleReset = () => {
-     *   formRef.current?.resetValues();
+     *   formRef.current?.resetValues({ animateUpdatedFields: true });
      * };
      */
-    resetValues: () => void;
+    resetValues: (options?: EFWFormResetValuesOptions) => void;
     /**
      * Controla el estado de deshabilitación de campos específicos o todos los campos.
      *
@@ -535,31 +616,44 @@ export interface EFWFormMethods<T extends readonly EFWFormFieldProps[] = EFWForm
      * Agrega un mensaje a la barra de mensajes del formulario.
      * Útil para mostrar feedback, errores o información contextual.
      *
-     * @param {EFWFormMessageBar} message - Objeto del mensaje a mostrar
-     * @param {'internal' | 'external'} [source='external'] - Origen del mensaje
+     * @param {EFWFormMessageBar} message - Objeto del mensaje a mostrar.
+     * Propiedades disponibles:
+     * - `id` (string | number) — Identificador único del mensaje.
+     * - `intent` ('info' | 'success' | 'warning' | 'error') — Nivel de importancia visual.
+     * - `title` (string) — Título opcional del mensaje.
+     * - `message` (ReactNode) — Contenido del mensaje.
+     * - `layout` (MessageBarProps['layout']) — Layout del MessageBar.
+     * - `actions` (EFWFormMessageBarAction[]) — Acciones interactivas del mensaje.
+     * - `dismissable` (boolean) — Si el usuario puede cerrar el mensaje.
+     * @param {'internal' | 'external'} [source='external'] - Origen del mensaje.
+     * Los mensajes 'internal' son generados por lógica interna del formulario (ej. validación),
+     * mientras que los 'external' provienen de la lógica de negocio de la aplicación.
      * @example
-     * // Mostrar mensaje de éxito
+     * // Mostrar mensaje de éxito simple
      * formRef.current?.addMessageBar({
      *   id: 'success-1',
-     *   type: 'success',
+     *   intent: 'success',
      *   message: 'Datos guardados correctamente'
      * });
      *
-     * // Mostrar error de validación personalizada
+     * // Mostrar error con título y acción personalizada
      * formRef.current?.addMessageBar({
      *   id: 'validation-error',
-     *   type: 'error',
-     *   message: 'La edad debe ser mayor a 18 años'
+     *   intent: 'error',
+     *   title: 'Error de validación',
+     *   message: 'La edad debe ser mayor a 18 años',
+     *   actions: [{ id: 'retry', content: 'Reintentar', onClick: () => handleRetry() }],
+     *   dismissable: true
      * }, 'internal');
      */
-    addMessageBar: (message: EFWFormMessageBar, source?: 'internal' | 'external') => void;
+    addMessageBar: (message: EFWFormMessageBar, source?: "internal" | "external") => void;
     /**
      * Elimina un mensaje específico de la barra de mensajes.
      *
      * @param {string | number} messageId - ID del mensaje a eliminar
      * @example
      * // Eliminar mensaje después de 5 segundos
-     * formRef.current?.addMessageBar({ id: 'temp-msg', type: 'info', message: 'Guardando...' });
+     * formRef.current?.addMessageBar({ id: 'temp-msg', intent: 'info', message: 'Guardando...' });
      * setTimeout(() => {
      *   formRef.current?.removeMessageBar('temp-msg');
      * }, 5000);
@@ -577,6 +671,29 @@ export interface EFWFormMethods<T extends readonly EFWFormFieldProps[] = EFWForm
      * };
      */
     removeAllMessagesBar: () => void;
+    /**
+     * Actualiza las propiedades y/o valores de uno o más campos del formulario.
+     * Permite control granular a nivel de campo, incluyendo cambiar valores,
+     * estados de validación, visibilidad, etc.
+     *
+     * Soporta dos modos de uso:
+     * 1. Con tipo explícito: acceso completo a todas las propiedades del tipo especificado.
+     * 2. Sin tipo explícito: solo propiedades comunes compatibles entre todos los campos seleccionados.
+     *
+     * @example
+     * // Actualizar un campo de texto con tipo explícito
+     * updateField<'Text'>(['name'], { value: 'Nuevo valor', disabled: true });
+     *
+     * // Actualizar propiedades comunes a varios campos de distintos tipos
+     * updateField(['name', 'age'], { disabled: true, required: false });
+     *
+     * // Actualizar opciones de un campo Choice
+     * updateField<'Choice'>(['category'], {
+     *   selectedOptions: [{ key: '1', text: 'Option 1' }],
+     *   options: newOptions
+     * });
+     */
+    updateField: EFWUpdateFieldFunction<T>;
 }
 /**
  * Tipo que representa la referencia al componente EFWForm.
@@ -716,7 +833,19 @@ export interface EFWFormSection<T extends EFWFormFieldProps = EFWFormFieldProps>
  * @template T - Array de propiedades de campos
  * @interface EFWFormBaseProps
  */
-export interface EFWFormBaseProps<T extends readonly EFWFormFieldProps[] = EFWFormFieldProps[]> {
+interface EFWFormBaseProps<T extends readonly EFWFormFieldProps[] = EFWFormFieldProps[]> {
+    /**
+     * Textos de localización para mensajes internos del formulario y, opcionalmente,
+     * para los campos (`fields`) y botones/drawers (`buttons`) hijos.
+     *
+     * Las claves base (`requiredFieldError`, `requiredFieldsNotification`, `unsupportedFieldType`)
+     * afectan solo al formulario. Si además se incluyen `fields` o `buttons`,
+     * `EFWForm` envuelve internamente su contenido con un `PorygonI18nProvider` local
+     * para que los campos hereden las traducciones sin necesidad de un provider externo.
+     *
+     * Si se omite, se usan los defaults del provider global (o defaults internos en español).
+     */
+    localeText?: Partial<EFWFormExtendedLocaleText>;
     /**
      * Estilos CSS inline opcionales para el contenedor principal del formulario.
      *
@@ -823,19 +952,7 @@ export interface EFWFormBaseProps<T extends readonly EFWFormFieldProps[] = EFWFo
     fieldLogic?: EFWFieldLogic<T>;
     /**
      * Callback ejecutado cuando cualquier valor del formulario cambia.
-     * Recibe los valores completos actualizados.
-     *
-     * @type {(values: EFWFormValues<T>) => void}
-     * @deprecated Usar onValuesChange en su lugar
-     * @example
-     * onChange={(values) => {
-     *   console.log('Formulario cambió:', values);
-     * }}
-     */
-    onChange?: (values: EFWFormValues<T>) => void;
-    /**
-     * Callback ejecutado cuando cualquier valor del formulario cambia.
-     * Versión preferida y más clara que onChange.
+     * Recibe los valores completos actualizados como copia superficial.
      *
      * @type {(values: EFWFormValues<T>) => void}
      * @example
@@ -852,8 +969,8 @@ export interface EFWFormBaseProps<T extends readonly EFWFormFieldProps[] = EFWFo
      * @type {EFWFormMessageBar[]}
      * @example
      * messages={[
-     *   { id: 'info', type: 'info', message: 'Los campos con * son obligatorios' },
-     *   { id: 'warning', type: 'warning', message: 'Revise los datos antes de enviar' }
+     *   { id: 'info', intent: 'info', message: 'Los campos con * son obligatorios' },
+     *   { id: 'warning', intent: 'warning', message: 'Revise los datos antes de enviar' }
      * ]}
      */
     messages?: EFWFormMessageBar[];
@@ -967,6 +1084,13 @@ export interface EFWFormProps<T extends readonly EFWFormFieldProps[] = EFWFormFi
      * ]}
      */
     fields?: T;
+    /**
+     * Configuración default para animar campos actualizados programáticamente.
+     *
+     * La opción por llamada (`setValues(..., { animateUpdatedFields })`) tiene prioridad
+     * sobre esta configuración global.
+     */
+    fieldAnimationConfig?: EFWFormFieldAnimationConfig;
     /**
      * Configuración de columnas del grid cuando se usa la propiedad fields.
      * Solo disponible cuando NO se usan sections.

package/dist/react-components/forms/EFWForm/EFWForm.utils.d.ts

@@ -1,17 +1,22 @@
 import { EFWFormFieldUpdate, EFWFormFieldProps, GetFieldValue, ExtractFieldNames, EFWFormValues, EFWUpdateFieldFunction, EFWFieldLogicContext, GridTemplateColumnsType } from './EFWForm.types';
-import { ValidationMessage, ValidationState } from '../../fields/EFWField/EFWField.types';
+import { ValidationMessage, ValidationState } from '../../fields/_shared/EFWField/EFWField.types';
+import { EFWFormLocaleText } from '../../i18n';
 
 export declare const generateGridTemplateColumns: (config: GridTemplateColumnsType) => string;
-declare const EFWFormFieldWrapperInner: <T extends readonly EFWFormFieldProps[]>({ field, initialValue, onValueChange, registerUpdateProps, fieldLogic, isControlled, getAllValues, updateFieldProps, onValidationChange, }: {
+declare const EFWFormFieldWrapperInner: <T extends readonly EFWFormFieldProps[]>({ field, initialValue, onValueChange, registerUpdateProps, unregisterUpdateProps, getFieldLogicByName, isControlled, getAllValues, updateFieldProps, localeText, onValidationChange, }: {
     field: T[number];
     initialValue: GetFieldValue<T, T[number]["internalName"]>;
-    onValueChange: (internalName: ExtractFieldNames<T>, value: GetFieldValue<T, T[number]["internalName"]>) => void;
+    onValueChange: (internalName: ExtractFieldNames<T>, value: GetFieldValue<T, T[number]["internalName"]>, options?: {
+        silent?: boolean;
+    }) => void;
     registerUpdateProps: (internalName: ExtractFieldNames<T>, updateFn: (updates: EFWFormFieldUpdate<T>) => void) => void;
-    fieldLogic?: (value: GetFieldValue<T, T[number]["internalName"]>, updateField: EFWUpdateFieldFunction<T>, context: EFWFieldLogicContext<T, ExtractFieldNames<T>>) => void;
+    unregisterUpdateProps: (internalName: ExtractFieldNames<T>, expectedUpdateFn: (updates: EFWFormFieldUpdate<T>) => void) => void;
+    getFieldLogicByName?: (internalName: ExtractFieldNames<T>) => ((value: GetFieldValue<T, T[number]["internalName"]>, updateField: EFWUpdateFieldFunction<T>, context: EFWFieldLogicContext<T, ExtractFieldNames<T>>) => void) | undefined;
     isControlled?: boolean;
     getAllValues: () => EFWFormValues<T>;
     updateFieldProps: EFWUpdateFieldFunction<T>;
-    onValidationChange?: (validation: {
+    localeText: EFWFormLocaleText;
+    onValidationChange?: (internalName: ExtractFieldNames<T>, validation: {
         currentValidationState: ValidationState;
         currentValidationMessage: ValidationMessage;
     }) => void;