carconnect-gatherleads-ui-lib 2.2.5 → 2.4.0

package/README.md

@@ -1315,6 +1315,145 @@ interface GatherFormBuilderProps {
   onSubmit={(data) => console.log(data)}
 />
 
+// EJEMPLOS CON ONCHANGE
+
+// Ejemplo 1:
+<GatherFormBuilder
+  config={{
+    fields: [
+      { name: 'user.firstName', label: 'Nombre', type: 'text' },
+      { name: 'user.email', label: 'Email', type: 'email' },
+      { name: 'phone', label: 'Telefono', type: 'tel' },
+      { name: 'address.country', label: 'País', type: 'select' },
+    ]
+  }}
+  watchFields={['user.email','phone']}
+  onChange={(data, changedField, formMethods) => {
+    // ✅ Funciona con datos anidados
+    if (changedField.name === 'address.country') {
+      formMethods.setValue('address.city', '');
+    }
+  }}
+  defaultValues={{
+    user: { firstName: '', email: '' },
+    address: { country: '', city: '' }
+  }}
+  onSubmit={(data) => console.log(data)}
+/>
+
+
+
+// Ejemplo 2:
+const nestedFormConfig = {
+  fields: [
+    { name: 'user.firstName', label: 'Nombre', type: 'text' },
+    { name: 'user.lastName', label: 'Apellido', type: 'text' },
+    { name: 'user.email', label: 'Email', type: 'email' },
+    { name: 'address.country', label: 'País', type: 'select' },
+    { name: 'address.city', label: 'Ciudad', type: 'select' },
+    { name: 'address.street', label: 'Calle', type: 'text' },
+    { name: 'preferences.notifications', label: 'Notificaciones', type: 'switch' },
+  ]
+};
+
+<GatherFormBuilder
+  config={nestedFormConfig}
+  watchFields={['address.country','preferences.notifications']}
+  onChange={(data, changedField, formMethods) => {
+    console.log('Campo que cambió:', changedField.name); // ej: 'user.firstName'
+    console.log('Nuevo valor:', changedField.value);
+    console.log('Datos completos:', data); // { user: { firstName: '...', lastName: '...' }, address: { ... } }
+
+    // Validación condicional con campos anidados
+    if (changedField.name === 'address.country') {
+      // Limpiar ciudad cuando cambia país
+      formMethods.setValue('address.city', '');
+      formMethods.clearErrors('address.city');
+    }
+
+    // Lógica basada en preferencias anidadas
+    if (changedField.name === 'preferences.notifications' && !changedField.value) {
+      // Si deshabilita notificaciones, limpiar campos relacionados
+      formMethods.setValue('preferences.emailFrequency', 'never');
+    }
+  }}
+  defaultValues={{
+    user: {
+      firstName: '',
+      lastName: '',
+      email: ''
+    },
+    address: {
+      country: '',
+      city: '',
+      street: ''
+    },
+    preferences: {
+      notifications: true
+    }
+  }}
+  onSubmit={(data) => console.log('Submit:', data)}
+/>
+
+// Ejemplo 3:
+<GatherFormBuilder
+  config={nestedFormConfig}
+  onChange={(data, changedField, formMethods) => {
+    if (changedField.name === 'user.email') {
+      // Validar email en tiempo real
+      validateEmail(changedField.value).then(isValid => {
+        if (!isValid) {
+          formMethods.setError('user.email', { message: 'Email inválido' });
+        }
+      });
+    }
+  }}
+  watchFields={['user.email', 'address.country']} // Solo observa estos campos anidados
+  debounceMs={300}
+  onSubmit={(data) => submitForm(data)}
+/>
+
+// Ejemplo 3:
+const calculatorFormConfig = {
+  fields: [
+    { name: 'invoice.items[0].quantity', label: 'Cantidad Item 1', type: 'number' },
+    { name: 'invoice.items[0].price', label: 'Precio Item 1', type: 'number' },
+    { name: 'invoice.items[1].quantity', label: 'Cantidad Item 2', type: 'number' },
+    { name: 'invoice.items[1].price', label: 'Precio Item 2', type: 'number' },
+    { name: 'invoice.discount', label: 'Descuento %', type: 'number' },
+    { name: 'invoice.total', label: 'Total', type: 'number', disabled: true },
+  ]
+};
+
+<GatherFormBuilder
+  config={calculatorFormConfig}
+  onChange={(data, changedField, formMethods) => {
+    // Recalcular total cuando cambien items o descuento
+    if (changedField.name.startsWith('invoice.items') || changedField.name === 'invoice.discount') {
+      const items = data.invoice?.items || [];
+      const subtotal = items.reduce((sum: number, item: any) => {
+        return sum + ((item?.quantity || 0) * (item?.price || 0));
+      }, 0);
+
+      const discount = (data.invoice?.discount || 0) / 100;
+      const total = subtotal * (1 - discount);
+
+      formMethods.setValue('invoice.total', total.toFixed(2));
+    }
+  }}
+  defaultValues={{
+    invoice: {
+      items: [
+        { quantity: 0, price: 0 },
+        { quantity: 0, price: 0 }
+      ],
+      discount: 0,
+      total: 0
+    }
+  }}
+  onSubmit={(data) => console.log('Invoice:', data)}
+/>
+
 // EJEMPLO CON TODAS LAS PROPS
 <GatherFormBuilder
   // CONFIG: Configuración del formulario (requerida)
@@ -1361,6 +1500,17 @@ interface GatherFormBuilderProps {
   // VALIDATIONMODE: Cuándo validar (opcional)
   validationMode="onChange"  // Valida en cada cambio
 
+  // DEBOUCEMS: tiempo de respuesta para cualquier cambio en el form
+  debouceMs={100}
+
+  // WATCHFIELDS: campos del form que se vizualizaran en tiempo real
+  watchFields={['nombre', 'pais']}
+
+  // ONCHANGE: cambios en tiempo real del form
+  onChange={(data,changedField, formMethods )=> {
+    console.log({data,changedField,formMethods})
+  }}
+
   // LOADINGCOMPONENT: Componente de carga (opcional)
   loadingComponent={<CustomSpinner />}
 />

package/dist/carconnect-gatherleads-ui-lib.d.ts

@@ -203,6 +203,21 @@ export declare const createColumns: <T>(columns: GatherTableColumn<T>[]) => Gath
  */
 export declare const createFlexibleColumns: (columns: BaseGatherTableColumn[]) => BaseGatherTableColumn[];
 
+/**
+ * Función debounce para limitar la frecuencia de ejecución
+ */
+export declare const debounce: <T extends (...args: any[]) => void>(func: T, wait: number) => ((...args: Parameters<T>) => void);
+
+/**
+ * Clona un objeto de forma profunda
+ */
+export declare const deepClone: (obj: any) => any;
+
+/**
+ * Compara dos valores de forma profunda, incluyendo objetos y arrays anidados
+ */
+export declare const deepEqual: (obj1: any, obj2: any) => boolean;
+
 /**
  * Tipo unión de todas las configuraciones de campo posibles
  */
@@ -525,18 +540,28 @@ export declare interface GatherDateFieldConfig extends BaseFieldConfig {
 }
 
 /**
- * Componente que construye un formulario dinámico en base a una configuración declarativa.
+ * Componente que construye un formulario dinámico a partir de una configuración declarativa.
+ *
+ * Se apoya en **React Hook Form** para la gestión del estado, validaciones
+ * y envío del formulario. Permite definir campos, layout, validaciones,
+ * botones y callbacks personalizados para diferentes acciones.
  *
  * @component
- * @param {GatherFormBuilderProps} props - Propiedades para configurar el formulario.
- *
- * @property {Object} config - Configuración del formulario (campos, botones, layout, título, etc).
- * @property {Function} onSubmit - Función asíncrona que se ejecuta al enviar el formulario.
- * @property {Function} [onAction] - Función que se ejecuta al presionar el botón de acción (ej: limpiar).
- * @property {boolean} [resetData=true] - Si `true`, resetea los datos después de enviar el formulario exitosamente.
- * @property {Object} [defaultValues={}] - Valores iniciales para los campos del formulario.
- * @property {boolean} [isLoading=false] - Indica si el formulario está en estado de carga.
- * @property {string} [className=""] - Clases adicionales para el contenedor principal.
+ * @param {GatherFormBuilderProps} props - Propiedades del componente.
+ *
+ * @property {Object} config - Configuración principal del formulario (campos, layout, título, botones, etc).
+ * @property {Function} onSubmit - Función asíncrona ejecutada al enviar el formulario.
+ * @property {Function} [onAction] - Callback para el botón de acción secundaria (ej: limpiar).
+ * @property {Function} [onChange] - Callback ejecutado cuando cambia el valor de un campo observado.
+ *    Recibe `(data, changedField, formMethods)`, donde `changedField` incluye `{ name, value, previousValue }`
+ *    y `formMethods` expone utilidades de React Hook Form (`setValue`, `getValues`, `reset`, `clearErrors`, `setError`, `watch`).
+ * @property {string[]} [watchFields=[]] - Lista de nombres de campos que deben ser observados por `onChange`.
+ * @property {number} [debounceMs=0] - Tiempo en milisegundos para aplicar `debounce` al callback `onChange`.
+ * @property {boolean} [resetData=true] - Si es `true`, el formulario se resetea tras un submit exitoso.
+ * @property {Object} [defaultValues={}] - Valores iniciales de los campos.
+ * @property {boolean} [isLoading=false] - Indica si el formulario está en estado de carga (bloquea inputs y botones).
+ * @property {boolean} [disabled=false] - Deshabilita todos los campos independientemente del estado de carga.
+ * @property {string} [className=""] - Clases CSS adicionales para el contenedor principal.
  * @property {'onBlur' | 'onChange' | 'onSubmit' | 'onTouched' | 'all'} [validationMode='onChange'] - Modo de validación usado por React Hook Form.
  *
  * @example
@@ -561,6 +586,9 @@ export declare interface GatherDateFieldConfig extends BaseFieldConfig {
  *     }
  *   }}
  *   onSubmit={(data) => console.log("Datos enviados:", data)}
+ *   onChange={(data, changedField, formMethods ) => console.log("Cambio:", changedField)}
+ *   watchFields={["nombre", "email"]}
+ *   debounceMs={500}
  * />
  * ```
  */
@@ -600,6 +628,55 @@ export declare interface GatherFormBuilderProps {
      * @example onAction={() => navigate('/home')}
      */
     onAction?: () => void;
+    /**
+     * Función que se ejecuta cada vez que cambia algún campo del formulario.
+     * Útil para validaciones en tiempo real, cálculos dinámicos, o sincronización con estado externo.
+     *
+     * @param data - Valores actuales de todos los campos del formulario
+     * @param changedField - Información sobre el campo que cambió
+     * @param formMethods - Métodos de React Hook Form para manipular el formulario
+     *
+     * @example
+     * onChange={(data, changedField, formMethods) => {
+     *   if (changedField.name === 'country') {
+     *     // Limpiar campo ciudad cuando cambia país
+     *     formMethods.setValue('city', '');
+     *   }
+     *
+     *   // Auto-guardar borrador
+     *   saveDraft(data);
+     * }}
+     */
+    onChange?: (data: Record<string, any>, changedField: {
+        name: string;
+        value: any;
+        previousValue?: any;
+    }, formMethods: {
+        setValue: (name: string, value: any) => void;
+        getValues: (name?: string) => any;
+        reset: (values?: any) => void;
+        clearErrors: (name?: string) => void;
+        setError: (name: string, error: {
+            message: string;
+        }) => void;
+        watch: (name?: string) => any;
+    }) => void;
+    /**
+     * Lista de campos específicos a observar para el onChange.
+     * Si no se especifica, observa todos los campos.
+     * Útil para optimizar performance en formularios grandes.
+     *
+     * @example watchFields: ['country', 'state'] // Solo observa estos campos
+     */
+    watchFields?: string[];
+    /**
+     * Debounce en milisegundos para el onChange.
+     * Útil para evitar muchas llamadas en campos de texto.
+     *
+     * @default 0 (sin debounce)
+     * @example debounceMs: 300 // Espera 300ms después del último cambio
+     */
+    debounceMs?: number;
     /**
      * Valores iniciales para los campos del formulario.
      * Se asignan según la propiedad `name` de cada campo.
@@ -697,8 +774,10 @@ export declare interface GatherInputFieldConfig extends BaseFieldConfig {
     maxLength?: number;
     /** Expresión regular para validar el formato del valor */
     pattern?: string;
+    /** Funcion para validar el formato del valor */
+    validateFn?: (value: string) => boolean | string;
     /** Mensaje que se muestra cuando el patrón no es válido */
-    patternMessage?: string;
+    errorMessage?: string;
     /** Valor numérico mínimo permitido (para inputs number) */
     min?: number;
     /** Valor numérico máximo permitido (para inputs number) */
@@ -1781,6 +1860,23 @@ export declare interface GatherTextareaFieldConfig extends BaseFieldConfig {
  */
 export declare const generateValidationRules: (field: FieldConfig) => ValidationRule;
 
+export declare const getAllPaths: (obj: any, prefix?: string) => string[];
+
+/**
+ * Determina las clases de layout dinámicamente en base al tipo (`grid`, `horizontal`, `stack`, etc).
+ */
+export declare const getLayoutClasses: (config: FormConfig) => string;
+
+/**
+ * Busca campos anidados en estructuras complejas de objetos (ej: direcciones.calle).
+ */
+export declare const getNestedField: (obj: any, path: string) => any;
+
+/**
+ * Ordena los campos en base al array `orderFields` definido en la config.
+ */
+export declare const getOrderedFields: (fields: FieldConfig[], orderFields?: string[]) => FieldConfig[];
+
 /**
  * Tipo de opción para el componente MultiSelect
  * @interface OptionType
@@ -1819,7 +1915,7 @@ export declare interface SelectInputOption {
     value: string;
     /** Patrón de expresión regular para validar el input asociado */
     validationPattern?: RegExp;
-    validateFn?: (value: string) => boolean;
+    validateFn?: (value: string) => boolean | string;
     /** Mensaje de error personalizado cuando la validación falla */
     errorMessage?: string;
     /** Texto placeholder específico para esta opción */