@envisiongroup/porygon 0.1.0-rc.1

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

@@ -0,0 +1,981 @@
+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 { EFWFormMessageBar } from '../EFWFormMessageBarGroup/EFWFormMessageBarGroup.types';
+import { MutableRefObject } from 'react';
+
+/**
+ * Arreglo constante que define todos los tipos de campos de formulario soportados.
+ * Estos tipos se utilizan para identificar qué tipo de componente renderizar
+ * y qué validaciones aplicar a cada campo.
+ *
+ * @example
+ * // Usar para validar tipos
+ * if (FORM_FIELD_TYPES.includes(fieldType)) {
+ *   // El tipo es válido
+ * }
+ */
+export 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.
+ *
+ * @example
+ * const fieldType: EFWFormFieldType = 'Text'; // ✓ Válido
+ * const invalidType: EFWFormFieldType = 'Email'; // ✗ Error de TypeScript
+ */
+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.
+ *
+ * @example
+ * // Obtener el tipo de valor para un campo específico
+ * type TextFieldValue = EFWFormFieldValueMap['Text']; // EFWInputFieldValue
+ * type NumberFieldValue = EFWFormFieldValueMap['Number']; // EFWNumberInputFieldValue
+ */
+export type EFWFormFieldValueMap = {
+    'Text': EFWInputFieldValue;
+    'Number': EFWNumberInputFieldValue;
+    'Choice': EFWTagPickerFieldValue[];
+    'Note': EFWTextAreaFieldValue;
+    'Boolean': EFWSwitchFieldValue;
+    'MultiChoice': EFWTagPickerFieldValue[];
+    'Date': EFWDatePickerFieldValue[];
+    'Attachments': EFWAttachmentsFieldValue[];
+};
+/**
+ * Tipo genérico que obtiene el tipo de valor para un campo específico.
+ * Utiliza el mapeo EFWFormFieldValueMap para determinar el tipo correcto.
+ *
+ * @template T - Tipo de campo (por defecto todos los tipos)
+ * @example
+ * type TextValue = EFWFormFieldValue<'Text'>; // EFWInputFieldValue
+ * type AnyValue = EFWFormFieldValue; // Union de todos los valores posibles
+ */
+export type EFWFormFieldValue<T extends EFWFormFieldType = EFWFormFieldType> = EFWFormFieldValueMap[T];
+/**
+ * Interfaz base que define las propiedades comunes a todos los campos de formulario.
+ * Proporciona la estructura fundamental que deben implementar todos los tipos de campos.
+ *
+ * @template T - Tipo específico de campo
+ *
+ * @example
+ * // Implementación para un campo de texto
+ * const textField: EFWFormFieldBaseProps<'Text'> = {
+ *   id: 'field-1',
+ *   typeAsString: 'Text',
+ *   internalName: 'userName',
+ *   value: 'John Doe'
+ * };
+ */
+export interface EFWFormFieldBaseProps<T extends EFWFormFieldType = EFWFormFieldType> {
+    readonly id: string;
+    readonly typeAsString: T;
+    readonly internalName: string;
+    value?: EFWFormFieldValueMap[T];
+}
+/**
+ * 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 {
+}
+/**
+ * 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 {
+}
+/**
+ * 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 {
+}
+/**
+ * Propiedades para campos de selección múltiple.
+ * Extiende TagPicker con la propiedad multiple obligatoria en true.
+ *
+ * @property {true} multiple - Marca obligatoria que indica selección múltiple
+ */
+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 {
+}
+/**
+ * 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 {
+}
+/**
+ * Propiedades para campos de tipo switch/boolean.
+ * Representa valores de encendido/apagado, sí/no, habilitado/deshabilitado.
+ */
+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 {
+}
+/**
+ * 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;
+};
+/**
+ * Tipo genérico que resuelve las propiedades correctas para un tipo de campo específico.
+ *
+ * @template T - Tipo de campo (por defecto todos los tipos)
+ * @example
+ * type TextFieldProps = EFWFormFieldProps<'Text'>; // EFWFormInputFieldProps
+ * type AnyFieldProps = EFWFormFieldProps; // Union de todas las propiedades posibles
+ */
+export type EFWFormFieldProps<T extends EFWFormFieldType = EFWFormFieldType> = EFWFormFieldPropsMap[T];
+/**
+ * Configuración para grid responsivo usando CSS auto-fit.
+ * Permite crear layouts que se adaptan automáticamente al espacio disponible.
+ *
+ * @example
+ * const gridConfig: ResponsiveGridConfig = {
+ *   autoFit: {
+ *     minColumnWidth: "300px",
+ *     maxColumns: 4
+ *   }
+ * };
+ */
+export interface ResponsiveGridConfig {
+    autoFit: {
+        minColumnWidth: string;
+        maxColumns?: number;
+    };
+}
+/**
+ * Tipo que permite especificar columnas de grid de forma fija o responsiva.
+ *
+ * @example
+ * // Grid fijo de 3 columnas
+ * const fixedGrid: GridTemplateColumnsType = 3;
+ *
+ * // Grid responsivo
+ * const responsiveGrid: GridTemplateColumnsType = {
+ *   autoFit: { minColumnWidth: "250px", maxColumns: 5 }
+ * };
+ */
+export type GridTemplateColumnsType = number | ResponsiveGridConfig;
+/**
+ * Tipo utilitario que detecta si un tipo es una unión (union type).
+ * Se utiliza internamente para determinar si se debe aplicar tipado estricto o genérico.
+ *
+ * @template T - Tipo a evaluar
+ * @template U - Tipo de comparación (por defecto igual a T)
+ * @typedef {boolean} IsUnion
+ * @private
+ */
+type IsUnion<T, U = T> = (T extends any ? (U extends T ? 0 : 1) : never) extends 0 ? false : true;
+/**
+ * Extrae los nombres de campos como tipos literales de un array de propiedades de campos.
+ *
+ * @template T - Array readonly de propiedades de campos
+ * @example
+ * type MyFields = readonly [
+ *   { internalName: 'name', typeAsString: 'Text', id: '1' },
+ *   { internalName: 'age', typeAsString: 'Number', id: '2' }
+ * ];
+ * type FieldNames = ExtractFieldNames<MyFields>; // 'name' | 'age'
+ */
+export type ExtractFieldNames<T extends readonly EFWFormFieldProps[]> = T[number]['internalName'];
+/**
+ * Extrae el tipo de campo basándose en el nombre interno (internalName).
+ *
+ * @template T - Array readonly de propiedades de campos
+ * @template K - Nombre interno del campo
+ * @typedef {string} ExtractFieldType
+ * @example
+ * 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], {
+    internalName: K;
+}>['typeAsString'];
+/**
+ * Obtiene el tipo de valor correcto para un campo específico.
+ *
+ * @template T - Array readonly de propiedades de campos
+ * @template K - Nombre interno del campo
+ * @example
+ * type NameValue = GetFieldValue<MyFields, 'name'>; // EFWInputFieldValue (string)
+ * type AgeValue = GetFieldValue<MyFields, 'age'>; // EFWNumberInputFieldValue (number)
+ */
+export type GetFieldValue<T extends readonly EFWFormFieldProps[], K extends string> = ExtractFieldType<T, K> extends keyof EFWFormFieldValueMap ? EFWFormFieldValueMap[ExtractFieldType<T, K>] : EFWFormFieldValue;
+/**
+ * Obtiene el tipo de propiedades correcto para un campo específico.
+ *
+ * @template T - Array readonly de propiedades de campos
+ * @template K - Nombre interno del campo
+ * @example
+ * 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;
+/**
+ * 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.
+ *
+ * @template T - Array readonly de propiedades de campos
+ * @example
+ * type MyFormValues = EFWFormValues<MyFields>;
+ * // Resultado: { name: string; age: number; }
+ *
+ * const formValues: MyFormValues = {
+ *   name: "John Doe",
+ *   age: 30
+ * };
+ */
+export type EFWFormValues<T extends readonly EFWFormFieldProps[]> = {
+    [K in ExtractFieldNames<T>]: GetFieldValue<T, K>;
+};
+/**
+ * Determina si un array de campos es genérico (sin tipado estricto) o específico.
+ * Se usa para aplicar diferentes estrategias de tipado.
+ *
+ * @template T - Array readonly de propiedades de campos
+ * @private
+ */
+type IsGenericFields<T extends readonly EFWFormFieldProps[]> = string extends ExtractFieldNames<T> ? true : false;
+/**
+ * Define el tipo de actualización para campos del formulario.
+ * Incluye propiedades específicas para cada tipo de campo con nombres más semánticos.
+ *
+ * @template T - Array readonly de propiedades de campos
+ * @example
+ * // Para un campo de selección
+ * const choiceUpdate: EFWFormFieldUpdate<MyFields> = {
+ *   selectedOptions: [{ id: '1', label: 'Option 1' }]
+ * };
+ *
+ * // Para un campo de fecha
+ * const dateUpdate: EFWFormFieldUpdate<MyFields> = {
+ *   selectedDates: [new Date()]
+ * };
+ */
+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;
+    };
+}[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.
+ *
+ * @template F - Tipo de campo específico (debe especificarse explícitamente)
+ * @example
+ * // Debe especificar el tipo explícitamente
+ * updateField<'Text'>(['field1', 'field2'], { value: 'nuevo valor' });
+ */
+export type GenericUpdateFieldFunctionArray = <F extends EFWFormFieldType = never>(internalNames: readonly string[], updates: Partial<EFWFormFieldPropsMap[F]>) => 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.
+ *
+ * @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' });
+ *
+ * // ✗ Error: 'name' es Text pero 'age' es Number (tipos diferentes)
+ * updateField(['name', 'age'], { value: 'algo' });
+ */
+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;
+/**
+ * Función de actualización tipada que se adapta según si los campos son genéricos o específicos.
+ *
+ * @template T - Array readonly de propiedades de campos
+ */
+export type EFWUpdateFieldFunction<T extends readonly EFWFormFieldProps[]> = IsGenericFields<T> extends true ? GenericUpdateFieldFunctionArray : StrictUpdateFieldFunctionArray<T>;
+/**
+ * Función de lógica genérica que se ejecuta cuando cambia el valor de un campo.
+ * Se usa cuando los campos no tienen tipado específico.
+ *
+ * @template T - Array readonly de propiedades de campo
+ * @example
+ * const genericLogic: GenericFieldLogicFunction<MyFields> = (value, allValues, updateField) => {
+ *   // Lógica genérica que funciona con cualquier tipo de valor
+ *   console.log('Campo cambió:', value);
+ * };
+ */
+export type GenericFieldLogicFunction<T extends readonly EFWFormFieldProps[]> = (value: EFWFormFieldValue, allValues: EFWFormValues<T>, updateField: EFWUpdateFieldFunction<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.
+ *
+ * @template T - Array readonly de propiedades de campos
+ * @template K - Nombre interno del campo específico
+ * @typedef {Function} StrictFieldLogicFunction
+ * @example
+ * const nameLogic: StrictFieldLogicFunction<MyFields, 'name'> = (value, allValues, updateField) => {
+ *   // value es específicamente string (tipo del campo 'name')
+ *   if (value.length > 50) {
+ *     updateField(['description'], { value: 'Nombre muy largo' });
+ *   }
+ * };
+ */
+export type StrictFieldLogicFunction<T extends readonly EFWFormFieldProps[], K extends ExtractFieldNames<T>> = (value: GetFieldValue<T, K>, allValues: EFWFormValues<T>, updateField: EFWUpdateFieldFunction<T>) => void;
+/**
+ * Configuración de lógica de campos que se adapta según el tipado.
+ * Para campos genéricos usa claves string, para campos específicos usa los nombres literales.
+ *
+ * @template T - Array readonly de propiedades de campos
+ *
+ * @example
+ * // Para campos tipados específicamente
+ * const typedLogic: EFWFieldLogic<MyFields> = {
+ *   name: (value, allValues, updateField) => {
+ *     // value es string, tipado automáticamente
+ *   },
+ *   age: (value, allValues, updateField) => {
+ *     // value es number, tipado automáticamente
+ *   }
+ * };
+ *
+ * // Para campos genéricos
+ * const genericLogic: EFWFieldLogic<EFWFormFieldProps[]> = {
+ *   'anyField': (value, allValues, updateField) => {
+ *     // value es union de todos los tipos posibles
+ *   }
+ * };
+ */
+export type EFWFieldLogic<T extends readonly EFWFormFieldProps[] = EFWFormFieldProps[]> = IsGenericFields<T> extends true ? Partial<Record<string, GenericFieldLogicFunction<T>>> : {
+    [K in ExtractFieldNames<T>]?: StrictFieldLogicFunction<T, K>;
+};
+/**
+ * Opciones para la función setValues que controla el comportamiento al actualizar valores.
+ *
+ * @interface EFWFormSetValuesOptions
+ * @example
+ * const options: EFWFormSetValuesOptions = {
+ *   triggerOnChange: false,    // No disparar onChange
+ *   triggerFieldLogic: true,   // Pero sí ejecutar fieldLogic
+ *   overwriteAll: false        // Solo actualizar campos especificados
+ * };
+ * formRef.current?.setValues({ name: 'Nuevo nombre' }, options);
+ */
+export interface EFWFormSetValuesOptions {
+    triggerOnChange?: boolean;
+    triggerFieldLogic?: boolean;
+    overwriteAll?: boolean;
+}
+/**
+ * Interfaz que define todos los métodos expuestos por el componente EFWForm.
+ * Estos métodos permiten control programático completo del formulario desde componentes padre.
+ *
+ * @template T - Array readonly de propiedades de campos
+ * @interface EFWFormMethods
+ */
+export interface EFWFormMethods<T extends readonly EFWFormFieldProps[] = EFWFormFieldProps[]> {
+    /**
+     * Obtiene una copia de todos los valores actuales del formulario.
+     *
+     * @returns {EFWFormValues<T>} Objeto con todos los valores tipados
+     * @example
+     * const currentValues = formRef.current?.getValues();
+     * console.log('Nombre actual:', currentValues?.name);
+     */
+    getValues: () => EFWFormValues<T>;
+    /**
+     * Establece nuevos valores para campos específicos del formulario.
+     * Permite actualización parcial o completa con control fino del comportamiento.
+     *
+     * @param {Partial<EFWFormValues<T>>} newValues - Nuevos valores a establecer
+     * @param {EFWFormSetValuesOptions} [options] - Opciones de comportamiento
+     * @example
+     * // Actualización simple
+     * formRef.current?.setValues({ name: 'Juan', age: 25 });
+     *
+     * // Con opciones específicas
+     * formRef.current?.setValues(
+     *   { name: 'María' },
+     *   { triggerOnChange: false, triggerFieldLogic: true }
+     * );
+     */
+    setValues: (newValues: Partial<EFWFormValues<T>>, options?: EFWFormSetValuesOptions) => void;
+    /**
+     * Restablece todos los valores del formulario a su estado inicial.
+     * Útil para formularios de "limpiar" o "resetear".
+     *
+     * @example
+     * // Botón de limpiar formulario
+     * const handleReset = () => {
+     *   formRef.current?.resetValues();
+     * };
+     */
+    resetValues: () => void;
+    /**
+     * Controla el estado de deshabilitación de campos específicos o todos los campos.
+     *
+     * @param {boolean} disabled - true para deshabilitar, false para habilitar
+     * @param {ExtractFieldNames<T>[]} [fieldKeys] - Campos específicos (opcional)
+     * @returns {ExtractFieldNames<T>[]} Lista de campos que fueron modificados
+     * @example
+     * // Deshabilitar todo el formulario
+     * formRef.current?.setDisabled(true);
+     *
+     * // Deshabilitar solo campos específicos
+     * const modifiedFields = formRef.current?.setDisabled(true, ['name', 'email']);
+     */
+    setDisabled: (disabled: boolean, fieldKeys?: ExtractFieldNames<T>[]) => ExtractFieldNames<T>[];
+    /**
+     * Controla el estado de edición de campos específicos o todos los campos.
+     * Un campo no editable es de solo lectura pero visualmente diferente a uno deshabilitado.
+     *
+     * @param {boolean} editable - true para permitir edición, false para solo lectura
+     * @param {ExtractFieldNames<T>[]} [fieldKeys] - Campos específicos (opcional)
+     * @returns {ExtractFieldNames<T>[]} Lista de campos que fueron modificados
+     * @example
+     * // Hacer todo el formulario de solo lectura
+     * formRef.current?.setEditable(false);
+     *
+     * // Hacer editables solo ciertos campos
+     * formRef.current?.setEditable(true, ['description', 'notes']);
+     */
+    setEditable: (editable: boolean, fieldKeys?: ExtractFieldNames<T>[]) => ExtractFieldNames<T>[];
+    /**
+     * Verifica si el formulario completo está en estado deshabilitado.
+     *
+     * @returns {boolean} true si está deshabilitado, false si no
+     * @example
+     * if (formRef.current?.isDisabled()) {
+     *   console.log('El formulario está deshabilitado');
+     * }
+     */
+    isDisabled: () => boolean;
+    /**
+     * Verifica si el formulario completo está en modo editable.
+     *
+     * @returns {boolean} true si es editable, false si es solo lectura
+     * @example
+     * const canEdit = formRef.current?.isEditable();
+     * if (!canEdit) {
+     *   showReadOnlyMessage();
+     * }
+     */
+    isEditable: () => boolean;
+    /**
+     * Ejecuta validación completa del formulario según las reglas definidas.
+     * Puede mostrar notificaciones de error opcionalmente.
+     *
+     * @param {boolean} [showErrorNotification=false] - Si mostrar notificaciones de error
+     * @returns {boolean} true si es válido, false si hay errores
+     * @example
+     * // Validar antes de enviar
+     * const handleSubmit = () => {
+     *   if (formRef.current?.validateForm(true)) {
+     *     // Proceder con envío
+     *     submitForm(formRef.current.getValues());
+     *   }
+     * };
+     */
+    validateForm: (showErrorNotification?: boolean) => boolean;
+    /**
+     * 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
+     * @example
+     * // Mostrar mensaje de éxito
+     * formRef.current?.addMessageBar({
+     *   id: 'success-1',
+     *   type: 'success',
+     *   message: 'Datos guardados correctamente'
+     * });
+     *
+     * // Mostrar error de validación personalizada
+     * formRef.current?.addMessageBar({
+     *   id: 'validation-error',
+     *   type: 'error',
+     *   message: 'La edad debe ser mayor a 18 años'
+     * }, 'internal');
+     */
+    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...' });
+     * setTimeout(() => {
+     *   formRef.current?.removeMessageBar('temp-msg');
+     * }, 5000);
+     */
+    removeMessageBar: (messageId: string | number) => void;
+    /**
+     * Elimina todos los mensajes de la barra de mensajes del formulario.
+     * Útil para limpiar todas las notificaciones de una vez.
+     *
+     * @example
+     * // Limpiar todos los mensajes antes de una nueva operación
+     * const handleNewOperation = () => {
+     *   formRef.current?.removeAllMessagesBar();
+     *   // ... resto de la lógica
+     * };
+     */
+    removeAllMessagesBar: () => void;
+}
+/**
+ * Tipo que representa la referencia al componente EFWForm.
+ * Puede ser null si el componente no está montado o la referencia no está inicializada.
+ *
+ * @template T - Array readonly de propiedades de campos
+ * @typedef {EFWFormMethods<T> | null} EFWFormRef
+ * @example
+ * const formRef = useRef<EFWFormRef<MyFields>>(null);
+ *
+ * // Verificar si está disponible antes de usar
+ * if (formRef.current) {
+ *   const values = formRef.current.getValues();
+ * }
+ */
+export type EFWFormRef<T extends readonly EFWFormFieldProps[] = EFWFormFieldProps[]> = EFWFormMethods<T> | null;
+/**
+ * Interfaz que extiende EFWFormMethods con funcionalidades específicas del hook useFormController.
+ * Proporciona una forma reactiva de interactuar con el formulario desde componentes React.
+ *
+ * @template T - Array readonly de propiedades de campos
+ * @interface useFormController
+ * @extends {EFWFormMethods<T>}
+ */
+export interface UseFormController<T extends readonly EFWFormFieldProps[] = EFWFormFieldProps[]> extends EFWFormMethods<T> {
+    /**
+     * Referencia mutable que debe asignarse a la prop formRef del componente EFWForm.
+     * Esta referencia conecta el hook con la instancia del formulario.
+     *
+     * @type {React.MutableRefObject<EFWFormRef<T>>}
+     * @example
+     * const form = useFormController<MyFields>();
+     *
+     * return (
+     *   <EFWForm
+     *     formRef={form.formRef}
+     *     fields={myFields}
+     *     onValuesChange={form.onValuesChange}
+     *   />
+     * );
+     */
+    formRef: React.MutableRefObject<EFWFormRef<T>>;
+    /**
+     * Estado reactivo que contiene los valores actuales del formulario.
+     * Se actualiza automáticamente cuando cambian los valores mediante onValuesChange.
+     *
+     * @type {EFWFormValues<T>}
+     * @example
+     * const form = useFormController<MyFields>();
+     *
+     * // Los valores están siempre actualizados
+     * useEffect(() => {
+     *   console.log('Nombre cambió a:', form.values.name);
+     * }, [form.values.name]);
+     */
+    values: EFWFormValues<T>;
+    /**
+     * Callback que debe pasarse a la prop onValuesChange del componente EFWForm.
+     * Mantiene sincronizado el estado reactivo con los valores del formulario.
+     *
+     * @param {EFWFormValues<T>} newValues - Nuevos valores del formulario
+     * @example
+     * const form = useFormController<MyFields>();
+     *
+     * return (
+     *   <EFWForm
+     *     fields={myFields}
+     *     onValuesChange={form.onValuesChange} // ← Conecta el estado reactivo
+     *   />
+     * );
+     */
+    onValuesChange: (newValues: EFWFormValues<T>) => void;
+}
+/**
+ * Interfaz que define una sección del formulario para organizar campos en grupos lógicos.
+ * Las secciones permiten crear formularios más organizados y fáciles de navegar.
+ *
+ * @template T - Tipo específico de campo que contiene esta sección
+ * @interface EFWFormSection
+ */
+export interface EFWFormSection<T extends EFWFormFieldProps = EFWFormFieldProps> {
+    /**
+     * Título opcional de la sección, puede ser texto o JSX.
+     * Se muestra como encabezado de la sección.
+     *
+     * @type {string | React.ReactNode}
+     * @example
+     * // Título simple
+     * title: "Información Personal"
+     *
+     * // Título con JSX
+     * title: <h3 className="section-title">Información Personal</h3>
+     */
+    title?: string | React.ReactNode;
+    /**
+     * Descripción opcional de la sección, puede ser texto o JSX.
+     * Proporciona contexto adicional sobre los campos de la sección.
+     *
+     * @type {string | React.ReactNode}
+     * @example
+     * description: "Complete los siguientes datos personales obligatorios"
+     */
+    description?: string | React.ReactNode;
+    /**
+     * Array de campos que pertenecen a esta sección.
+     * Cada campo debe implementar las propiedades de EFWFormFieldProps.
+     *
+     * @type {T[]}
+     * @example
+     * fields: [
+     *   { id: '1', typeAsString: 'Text', internalName: 'firstName', ... },
+     *   { id: '2', typeAsString: 'Text', internalName: 'lastName', ... }
+     * ]
+     */
+    fields: T[];
+    /**
+     * Configuración de columnas del grid para esta sección específica.
+     * Puede ser un número fijo de columnas o configuración responsiva.
+     *
+     * @type {GridTemplateColumnsType}
+     * @default 1
+     * @example
+     * // Grid fijo de 2 columnas
+     * gridTemplateColumns: 2
+     *
+     * // Grid responsivo
+     * gridTemplateColumns: {
+     *   autoFit: { minColumnWidth: "300px", maxColumns: 3 }
+     * }
+     */
+    gridTemplateColumns?: GridTemplateColumnsType;
+}
+/**
+ * Interfaz base que define las propiedades comunes del componente EFWForm.
+ * Estas propiedades son compartidas tanto para formularios con fields como con sections.
+ *
+ * @template T - Array de propiedades de campos
+ * @interface EFWFormBaseProps
+ */
+export interface EFWFormBaseProps<T extends EFWFormFieldProps[] = EFWFormFieldProps[]> {
+    /**
+     * Estilos CSS inline opcionales para el contenedor principal del formulario.
+     *
+     * @type {React.CSSProperties}
+     * @example
+     * style={{ backgroundColor: '#f5f5f5', padding: '20px' }}
+     */
+    style?: React.CSSProperties;
+    /**
+     * Clase CSS opcional para personalización adicional del formulario.
+     *
+     * @type {string}
+     * @example
+     * className="custom-form-container"
+     */
+    className?: string;
+    /**
+     * Título principal del formulario, mostrado en la parte superior.
+     *
+     * @type {string | React.ReactNode}
+     * @example
+     * // Título simple
+     * title="Registro de Usuario"
+     *
+     * // Título con JSX
+     * title={<h1 className="form-title">Registro de Usuario</h1>}
+     */
+    title?: string | React.ReactNode;
+    /**
+     * Descripción del formulario, mostrada debajo del título.
+     * Proporciona contexto sobre el propósito del formulario.
+     *
+     * @type {string | React.ReactNode}
+     * @example
+     * description="Complete todos los campos para crear su cuenta"
+     */
+    description?: string | React.ReactNode;
+    /**
+     * Indica si el formulario es obligatorio para el flujo de la aplicación.
+     * Puede afectar validaciones y comportamiento de envío.
+     *
+     * @type {boolean}
+     * @default false
+     */
+    required?: boolean;
+    /**
+     * Controla si los campos del formulario son editables.
+     * false convierte el formulario en modo de solo lectura.
+     *
+     * @type {boolean}
+     * @default true
+     * @example
+     * // Formulario de solo lectura para mostrar datos
+     * editable={false}
+     */
+    editable?: boolean;
+    /**
+     * Controla si el formulario completo está deshabilitado.
+     * Los campos deshabilitados no son interactivos y tienen apariencia atenuada.
+     *
+     * @type {boolean}
+     * @default false
+     * @example
+     * // Deshabilitar durante carga
+     * disabled={isLoading}
+     */
+    disabled?: boolean;
+    /**
+     * Controla la visibilidad del formulario completo.
+     * true oculta completamente el formulario del DOM.
+     *
+     * @type {boolean}
+     * @default false
+     * @example
+     * // Mostrar condicionalmente
+     * hidden={!showAdvancedOptions}
+     */
+    hidden?: boolean;
+    /**
+     * Espaciado en píxeles entre columnas y filas del grid del formulario.
+     *
+     * @type {number}
+     * @default 16
+     * @example
+     * gridTemplateGap={24} // Más espaciado
+     */
+    gridTemplateGap?: number;
+    /**
+     * Configuración de lógica personalizada para los campos del formulario.
+     * Permite definir comportamientos automáticos basados en cambios de valores.
+     *
+     * @type {EFWFieldLogic<T>}
+     * @example
+     * fieldLogic={{
+     *   age: (value, allValues, updateField) => {
+     *     if (value >= 18) {
+     *       updateField(['canVote'], { value: true });
+     *     }
+     *   }
+     * }}
+     */
+    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.
+     *
+     * @type {(values: EFWFormValues<T>) => void}
+     * @example
+     * onValuesChange={(values) => {
+     *   setFormState(values);
+     *   validateInRealTime(values);
+     * }}
+     */
+    onValuesChange?: (values: EFWFormValues<T>) => void;
+    /**
+     * Array opcional de mensajes para mostrar en la barra de mensajes del formulario.
+     * Útil para feedback, errores o información contextual.
+     *
+     * @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' }
+     * ]}
+     */
+    messages?: EFWFormMessageBar[];
+    /**
+     * Referencia mutable para acceder a los métodos del formulario desde el componente padre.
+     *
+     * @type {MutableRefObject<EFWFormRef<T>>}
+     * @example
+     * const formRef = useRef<EFWFormRef<MyFields>>(null);
+     *
+     * const handleSubmit = () => {
+     *   if (formRef.current?.validateForm()) {
+     *     const values = formRef.current.getValues();
+     *     submitForm(values);
+     *   }
+     * };
+     */
+    formRef?: MutableRefObject<EFWFormRef<T>>;
+    /**
+     * Contenido React opcional renderizado antes del título y descripción.
+     * Útil para logos, breadcrumbs o elementos de navegación.
+     *
+     * @type {React.ReactNode}
+     * @example
+     * header={
+     *   <div className="form-header">
+     *     <Logo />
+     *     <Breadcrumbs />
+     *   </div>
+     * }
+     */
+    header?: React.ReactNode;
+    /**
+     * Contenido React opcional renderizado después de los campos pero antes de children.
+     * Ideal para botones de acción o información adicional.
+     *
+     * @type {React.ReactNode}
+     * @example
+     * footer={
+     *   <div className="form-actions">
+     *     <Button type="submit">Guardar</Button>
+     *     <Button variant="secondary" onClick={handleCancel}>Cancelar</Button>
+     *   </div>
+     * }
+     */
+    footer?: React.ReactNode;
+    /**
+     * Valores iniciales para precargar el formulario.
+     * Útil para formularios de edición o valores por defecto.
+     *
+     * @type {Partial<EFWFormValues<T>>}
+     * @example
+     * initialValues={{
+     *   name: 'John Doe',
+     *   email: 'john@example.com',
+     *   age: 30
+     * }}
+     */
+    initialValues?: Partial<EFWFormValues<T>>;
+    /**
+     * Callback opcional ejecutado una vez al inicializar el formulario.
+     * Útil para configuraciones dinámicas como cargar opciones desde API.
+     * Soporta operaciones asíncronas.
+     *
+     * @type {(allValues: EFWFormValues<T>, updateField: EFWUpdateFieldFunction<T>) => void | Promise<void>}
+     * @example
+     * onInit={async (allValues, updateField) => {
+     *   const options = await fetchOptionsFromAPI();
+     *   updateField(['category'], { options });
+     * }}
+     */
+    onInit?: (allValues: EFWFormValues<T>, updateField: EFWUpdateFieldFunction<T>) => void | Promise<void>;
+    /**
+     * Contenido React adicional renderizado al final del formulario.
+     * Permite extensibilidad completa del formulario.
+     *
+     * @type {React.ReactNode}
+     * @example
+     * children={
+     *   <div className="additional-content">
+     *     <Terms />
+     *     <PrivacyNotice />
+     *   </div>
+     * }
+     */
+    children?: React.ReactNode;
+}
+/**
+ * Interfaz principal del componente EFWForm que combina propiedades base con
+ * configuración específica para fields o sections (mutuamente excluyentes).
+ *
+ * @template T - Array de propiedades de campos
+ * @interface EFWFormProps
+ * @extends {EFWFormBaseProps<T>}
+ */
+export interface EFWFormProps<T extends EFWFormFieldProps[] = EFWFormFieldProps[]> extends EFWFormBaseProps<T> {
+    /**
+     * Array de campos que componen el formulario.
+     * No se puede usar junto con la propiedad sections.
+     *
+     * @type {T}
+     * @example
+     * fields={[
+     *   { id: '1', typeAsString: 'Text', internalName: 'name', label: 'Nombre' },
+     *   { id: '2', typeAsString: 'Number', internalName: 'age', label: 'Edad' }
+     * ]}
+     */
+    fields?: T;
+    /**
+     * Configuración de columnas del grid cuando se usa la propiedad fields.
+     * Solo disponible cuando NO se usan sections.
+     *
+     * @type {GridTemplateColumnsType}
+     * @default 1
+     * @example
+     * // Grid fijo de 3 columnas
+     * gridTemplateColumns={3}
+     *
+     * // Grid responsivo
+     * gridTemplateColumns={{
+     *   autoFit: { minColumnWidth: "250px", maxColumns: 4 }
+     * }}
+     */
+    gridTemplateColumns?: GridTemplateColumnsType;
+    /**
+     * Array de secciones para organizar campos en grupos lógicos.
+     * No se puede usar junto con la propiedad fields.
+     * Cada sección puede tener su propia configuración de grid.
+     *
+     * @type {EFWFormSection<T[number]>[]}
+     * @example
+     * sections={[
+     *   {
+     *     title: "Información Personal",
+     *     description: "Datos básicos del usuario",
+     *     gridTemplateColumns: 2,
+     *     fields: [
+     *       { id: '1', typeAsString: 'Text', internalName: 'firstName' },
+     *       { id: '2', typeAsString: 'Text', internalName: 'lastName' }
+     *     ]
+     *   },
+     *   {
+     *     title: "Contacto",
+     *     gridTemplateColumns: 1,
+     *     fields: [
+     *       { id: '3', typeAsString: 'Text', internalName: 'email' }
+     *     ]
+     *   }
+     * ]}
+     */
+    sections?: EFWFormSection<T[number]>[];
+}
+export {};