carconnect-gatherleads-ui-lib 2.4.1 → 2.4.5

package/README.md

@@ -870,66 +870,80 @@ interface GatherTextareaFieldConfig extends BaseFieldConfig {
 }
 ```
 
-### 6. **GatherDateFieldConfig** - Campos de Fecha
+#### **Características Destacadas**
 
-```tsx
-interface GatherDateFieldConfig extends BaseFieldConfig {
-  type: 'date' | 'daterange';
-  maxDate?: Date;
-  minDate?: Date;
-  singleDate?: boolean; // Solo para daterange
-  displayFormat?: string; // Formato de visualización
-  size?: 'sm' | 'md' | 'lg';
-}
-```
+✨ **Nuevas Funcionalidades:**
 
-**Ejemplos:**
+1. **Scroll en selector de años** - El selector ahora tiene altura máxima y scroll automático
+2. **Control de años personalizables** - `pastYearsCount={10}` muestra año actual + últimos 10 años
+3. **Textos personalizables** - Botones Apply/Cancel en cualquier idioma
+4. **Callbacks para eventos** - `onApply`, `onCancel`, `onOpenChange` para lógica personalizada
+5. **Formatos de fecha flexibles** - Personaliza cómo se muestran las fechas
+6. **Auto-cierre inteligente** - Cierre automático tras selección para UX más rápida
+7. **Modo sin botones** - `hideActionButtons={true}` para aplicar cambios inmediatamente
+
+#### **Ejemplos de Uso Avanzado**
 
 ```tsx
-// FECHA SIMPLE
-{
-  name: "birthDate",
-  label: "Fecha de nacimiento",
-  type: "date",
-  maxDate: new Date(),                    // No futuro
-  minDate: new Date("1900-01-01"),       // Desde 1900
-  displayFormat: "DD/MM/YYYY",           // Formato día/mes/año
-  required: true,
-  size: "md"
-}
+// EJEMPLO 1: Date Picker rápido sin confirmación
+<GatherDatePicker
+  mode="single"
+  selected={date}
+  onSelect={setDate}
+  autoClose={true}
+  hideActionButtons={true}
+  placeholder="Selección rápida"
+/>
 
-// RANGO DE FECHAS
-{
-  name: "vacationPeriod",
-  label: "Período de vacaciones",
-  type: "daterange",
-  singleData: false,
-  minDate: new Date(),                    // Desde hoy
-  maxDate: new Date("2025-12-31"),       // Hasta fin de año
-  displayFormat: "DD/MM/YYYY",
-  helperText: "Seleccione fecha de inicio y fin"
-}
+// EJEMPLO 2: Con validación y callbacks
+<GatherDatePicker
+  mode="single"
+  selected={date}
+  onSelect={setDate}
+  applyButtonText="Guardar Fecha"
+  cancelButtonText="Descartar"
+  onApply={(selectedDate) => {
+    // Validar y guardar
+    if (selectedDate) {
+      saveToAPI(selectedDate);
+      toast.success('Fecha guardada');
+    }
+  }}
+  onCancel={() => {
+    toast.info('Cambios descartados');
+  }}
+/>
 
-// FECHA CON HORA
-{
-  name: "appointmentDateTime",
-  label: "Fecha y hora de la cita",
-  type: "date",
-  minDate: new Date(),
-  displayFormat: "DD/MM/YYYY HH:mm",     // Con hora
-  size: "lg"
-}
+// EJEMPLO 3: Rango con formato personalizado y años limitados
+<GatherDatePicker
+  mode="range"
+  selected={dateRange}
+  onSelect={setDateRange}
+  rangeFromFormat="dd/MM/yy"
+  rangeToFormat="dd/MM/yy"
+  pastYearsCount={5}  // Solo últimos 5 años
+  placeholder="Del - Al"
+/>
 
-// FECHA ÚNICA EN RANGO
-{
-  name: "singleDateInRange",
-  label: "Seleccione una fecha",
-  type: "daterange",
-  singleDate: true,                      // Solo una fecha aunque sea daterange
-  displayFormat: "MMMM D, YYYY"          // "Enero 15, 2025"
-}
+// EJEMPLO 4: Input de formulario completo
+<GatherDatePickerInput
+  label="Fecha de Registro"
+  description="Seleccione la fecha de registro del cliente"
+  placeholder="dd/mm/aaaa"
+  mode="single"
+  selected={date}
+  onSelect={setDate}
+  dateFormat="dd/MM/yyyy"
+  showSelectedDate={true}
+  selectedDateLabel="Registrado el:"
+  autoClose={true}
+  minDate={subDays(new Date(), 365)}
+  maxDate={new Date()}
+/>
 ```
 
+---
+
 ### 7. **GatherCheckboxGroupFieldConfig** - Grupo de Checkboxes
 
 ```tsx
@@ -2614,3 +2628,563 @@ const apiData = await fetch('/api/users').then((r) => r.json());
 ```
 
 Esta guía completa cubre todos los aspectos de GatherTable, desde uso básico hasta implementaciones avanzadas con ordenamiento, filtrado y renderizado personalizado.
+
+# 🪟 Guía Completa de GatherModal
+
+## 🎯 Introducción
+
+`GatherModal` es un componente modal genérico y altamente personalizable que proporciona diálogos flexibles con soporte completo para diferentes posiciones, tamaños, animaciones y accesibilidad avanzada.
+
+## 🏗️ Características Principales
+
+- **Posiciones**: center, left, right (ideal para paneles laterales)
+- **Tamaños**: sm, md, lg, xl, full
+- **Header personalizable**: Título simple o contenido completamente custom
+- **Footer flexible**: Botones por defecto o contenido personalizado
+- **Accesibilidad avanzada**: Focus management, keyboard navigation
+- **Animaciones**: Transiciones suaves configurables
+- **Portal rendering**: Se renderiza fuera del árbol DOM
+
+## 📋 Uso Básico
+
+### Modal Simple de Confirmación
+
+```tsx
+import { GatherModal } from '@/base/modal';
+import { useState } from 'react';
+
+const BasicModalExample = () => {
+  const [isOpen, setIsOpen] = useState(false);
+
+  return (
+    <>
+      <button onClick={() => setIsOpen(true)}>Abrir Modal</button>
+
+      <GatherModal
+        open={isOpen}
+        onClose={() => setIsOpen(false)}
+        header={{
+          title: 'Confirmar Acción',
+          subtitle: '¿Estás seguro de continuar?',
+        }}
+        footer={{
+          acceptText: 'Confirmar',
+          cancelText: 'Cancelar',
+          acceptVariant: 'gather-primary',
+          cancelVariant: 'gather-outline',
+          onAccept: () => {
+            console.log('Confirmado');
+            setIsOpen(false);
+          },
+          onCancel: () => setIsOpen(false),
+        }}
+      >
+        <p>Esta acción no se puede deshacer.</p>
+      </GatherModal>
+    </>
+  );
+};
+```
+
+### Modal de Formulario
+
+```tsx
+const FormModalExample = () => {
+  const [isOpen, setIsOpen] = useState(false);
+  const [loading, setLoading] = useState(false);
+
+  const handleSubmit = async () => {
+    setLoading(true);
+    try {
+      // Simular API call
+      await new Promise((resolve) => setTimeout(resolve, 2000));
+      setIsOpen(false);
+    } finally {
+      setLoading(false);
+    }
+  };
+
+  return (
+    <GatherModal
+      open={isOpen}
+      onClose={() => setIsOpen(false)}
+      size='lg'
+      header={{
+        title: 'Nuevo Usuario',
+        subtitle: 'Complete los datos del usuario',
+      }}
+      footer={{
+        acceptText: 'Guardar',
+        cancelText: 'Cancelar',
+        acceptLoading: loading,
+        acceptDisabled: loading,
+        onAccept: handleSubmit,
+        onCancel: () => setIsOpen(false),
+      }}
+    >
+      <div className='space-y-4'>
+        <div>
+          <label className='mb-1 block text-sm font-medium'>
+            Nombre completo
+          </label>
+          <input
+            type='text'
+            className='w-full rounded border p-2'
+            placeholder='Juan Pérez'
+          />
+        </div>
+        <div>
+          <label className='mb-1 block text-sm font-medium'>Email</label>
+          <input
+            type='email'
+            className='w-full rounded border p-2'
+            placeholder='juan@ejemplo.com'
+          />
+        </div>
+      </div>
+    </GatherModal>
+  );
+};
+```
+
+## 🎨 Posiciones y Tamaños
+
+### Modal Centrado (Por Defecto)
+
+```tsx
+<GatherModal
+  open={isOpen}
+  position='center' // Por defecto
+  size='md' // Tamaño mediano
+  onClose={() => setIsOpen(false)}
+>
+  <p>Modal centrado en la pantalla</p>
+</GatherModal>
+```
+
+### Panel Lateral Derecho
+
+```tsx
+<GatherModal
+  open={isOpen}
+  position='right'
+  size='lg'
+  onClose={() => setIsOpen(false)}
+  header={{
+    title: 'Panel de Configuración',
+  }}
+>
+  <div className='space-y-4'>
+    <h3>Configuraciones</h3>
+    <div>Contenido del panel lateral...</div>
+  </div>
+</GatherModal>
+```
+
+### Modal de Pantalla Completa
+
+```tsx
+<GatherModal
+  open={isOpen}
+  size='full'
+  onClose={() => setIsOpen(false)}
+  header={{
+    title: 'Vista Completa',
+  }}
+  scrollBehavior={{
+    bodyScrollable: true,
+    bodyMaxHeight: '80vh',
+  }}
+>
+  <div>Contenido que ocupa toda la pantalla...</div>
+</GatherModal>
+```
+
+## 🔧 Configuración Avanzada
+
+### Modal con Contenido Personalizado
+
+```tsx
+<GatherModal
+  open={isOpen}
+  onClose={() => setIsOpen(false)}
+  header={{
+    children: (
+      <div className='flex items-center gap-3'>
+        <div className='flex h-8 w-8 items-center justify-center rounded-full bg-blue-500'>
+          <span className='text-sm text-white'>!</span>
+        </div>
+        <div>
+          <h2 className='text-lg font-semibold'>Advertencia</h2>
+          <p className='text-sm text-gray-600'>Acción requerida</p>
+        </div>
+      </div>
+    ),
+    showCloseButton: true,
+  }}
+  footer={{
+    children: (
+      <div className='flex w-full justify-between'>
+        <span className='text-sm text-gray-500'>
+          Última actualización: hace 5 min
+        </span>
+        <div className='flex gap-2'>
+          <button className='rounded px-4 py-2 text-gray-600 hover:bg-gray-100'>
+            Ignorar
+          </button>
+          <button className='rounded bg-red-500 px-4 py-2 text-white hover:bg-red-600'>
+            Resolver
+          </button>
+        </div>
+      </div>
+    ),
+  }}
+>
+  <p>Contenido del modal con header y footer personalizados.</p>
+</GatherModal>
+```
+
+### Modal con Scroll Personalizado
+
+```tsx
+<GatherModal
+  open={isOpen}
+  onClose={() => setIsOpen(false)}
+  header={{
+    title: 'Contenido Extenso',
+    scrollable: true,
+    maxHeight: '150px',
+  }}
+  scrollBehavior={{
+    bodyScrollable: true,
+    bodyMaxHeight: '400px',
+    modalScrollable: false,
+  }}
+  footer={{
+    scrollable: true,
+    maxHeight: '100px',
+  }}
+>
+  <div className='space-y-4'>
+    {Array.from({ length: 20 }, (_, i) => (
+      <p key={i}>
+        Párrafo {i + 1}: Lorem ipsum dolor sit amet consectetur adipisicing
+        elit...
+      </p>
+    ))}
+  </div>
+</GatherModal>
+```
+
+## ⚙️ Props Principales
+
+### Props del Modal
+
+```tsx
+interface GatherModalProps {
+  // ESTADO
+  open: boolean; // Si el modal está abierto
+  onClose?: () => void; // Función de cierre
+
+  // DISEÑO
+  position?: 'center' | 'left' | 'right'; // Posición
+  size?: 'sm' | 'md' | 'lg' | 'xl' | 'full'; // Tamaño
+
+  // COMPORTAMIENTO
+  closeOnOverlayClick?: boolean; // Cerrar al hacer clic fuera
+  closeOnEscape?: boolean; // Cerrar con tecla Escape
+  preventBodyScroll?: boolean; // Prevenir scroll del body
+  autoFocus?: boolean; // Enfocar automáticamente
+
+  // CONTENIDO
+  header?: GatherModalHeaderProps; // Configuración del header
+  footer?: GatherModalFooterProps; // Configuración del footer
+  children: React.ReactNode; // Contenido principal
+
+  // ACCESIBILIDAD Y ANIMACIÓN
+  animationDuration?: number; // Duración de animaciones (ms)
+  zIndex?: number; // Z-index base
+  scrollBehavior?: ScrollConfig; // Configuración de scroll
+}
+```
+
+### Props del Header
+
+```tsx
+interface GatherModalHeaderProps {
+  title?: string; // Título del modal
+  subtitle?: string; // Subtítulo
+  showCloseButton?: boolean; // Mostrar botón X
+  onClose?: () => void; // Función del botón cerrar
+  closeIcon?: React.ReactNode; // Ícono personalizado
+  scrollable?: boolean; // Si el header hace scroll
+  children?: React.ReactNode; // Contenido personalizado
+}
+```
+
+### Props del Footer
+
+```tsx
+interface GatherModalFooterProps {
+  // BOTONES POR DEFECTO
+  acceptText?: string; // Texto botón aceptar
+  cancelText?: string; // Texto botón cancelar
+  onAccept?: () => void; // Acción de aceptar
+  onCancel?: () => void; // Acción de cancelar
+
+  // ESTADOS DE LOS BOTONES
+  acceptLoading?: boolean; // Loading en botón aceptar
+  acceptDisabled?: boolean; // Deshabilitar aceptar
+
+  // VARIANTES Y DISEÑO
+  acceptVariant?: ButtonVariant; // Estilo del botón aceptar
+  cancelVariant?: ButtonVariant; // Estilo del botón cancelar
+  buttonsOrder?: 'normal' | 'reverse'; // Orden de botones
+  buttonsAlignment?: 'start' | 'center' | 'end' | 'between';
+
+  // PERSONALIZACIÓN
+  children?: React.ReactNode; // Footer completamente personalizado
+  scrollable?: boolean; // Si el footer hace scroll
+}
+```
+
+## 🎯 Casos de Uso Comunes
+
+### Modal de Confirmación de Eliminación
+
+```tsx
+const DeleteConfirmModal = ({ item, onConfirm, onCancel }) => (
+  <GatherModal
+    open={!!item}
+    onClose={onCancel}
+    size='sm'
+    header={{
+      title: 'Confirmar Eliminación',
+      subtitle: '¿Estás seguro de eliminar este elemento?',
+    }}
+    footer={{
+      acceptText: 'Eliminar',
+      cancelText: 'Cancelar',
+      acceptVariant: 'gather-error',
+      onAccept: () => onConfirm(item),
+      onCancel: onCancel,
+    }}
+  >
+    <p>Esta acción no se puede deshacer.</p>
+    {item && (
+      <div className='mt-3 rounded bg-gray-50 p-3'>
+        <strong>{item.name}</strong>
+      </div>
+    )}
+  </GatherModal>
+);
+```
+
+### Panel de Detalles Lateral
+
+```tsx
+const DetailsSidebar = ({ user, isOpen, onClose }) => (
+  <GatherModal
+    open={isOpen}
+    onClose={onClose}
+    position='right'
+    size='lg'
+    header={{
+      title: 'Detalles del Usuario',
+      subtitle: user?.name,
+    }}
+    preventBodyScroll={true}
+  >
+    {user && (
+      <div className='space-y-6'>
+        <div className='text-center'>
+          <img
+            src={user.avatar}
+            alt={user.name}
+            className='mx-auto mb-4 h-20 w-20 rounded-full'
+          />
+          <h3 className='text-xl font-semibold'>{user.name}</h3>
+          <p className='text-gray-600'>{user.email}</p>
+        </div>
+
+        <div className='space-y-4'>
+          <div>
+            <label className='font-medium'>Departamento</label>
+            <p>{user.department}</p>
+          </div>
+          <div>
+            <label className='font-medium'>Rol</label>
+            <p>{user.role}</p>
+          </div>
+        </div>
+      </div>
+    )}
+  </GatherModal>
+);
+```
+
+Esta guía cubre los aspectos principales de GatherModal, proporcionando ejemplos prácticos para implementaciones comunes desde modales simples hasta paneles laterales complejos.
+
+# 📅 Guía Completa de GatherDatePicker
+
+## 🎯 Introducción
+
+`GatherDatePicker` es un componente de selección de fechas flexible y robusto, basado en `react-day-picker`. Ofrece dos variantes principales: un botón que abre un popover (`GatherDatePicker`) y un input de texto (`GatherDatePickerInput`). Soporta selección de fechas individuales y rangos, zonas horarias, y validaciones.
+
+## 📦 Uso Básico
+
+### Selector de Fecha Simple (Botón)
+
+```tsx
+import { GatherDatePicker } from '@/base/date-picker/gather-date-picker';
+
+const SimpleDatePicker = () => {
+  const [date, setDate] = React.useState<Date | undefined>(new Date());
+
+  return (
+    <GatherDatePicker
+      mode='single'
+      selected={date}
+      onSelect={setDate}
+      placeholder='Seleccionar fecha'
+    />
+  );
+};
+```
+
+### Input de Fecha
+
+```tsx
+import { GatherDatePickerInput } from '@/base/date-picker/gather-date-picker-input';
+
+const InputDatePicker = () => {
+  const [date, setDate] = React.useState<Date | undefined>();
+
+  return (
+    <GatherDatePickerInput
+      mode='single'
+      selected={date}
+      onSelect={setDate}
+      label='Fecha de nacimiento'
+      placeholder='Seleccione su fecha de nacimiento'
+    />
+  );
+};
+```
+
+## ⚙️ Props Principales
+
+### GatherDatePickerProps & GatherDatePickerInputProps
+
+Ambos componentes comparten la mayoría de las props, heredando de una base común:
+
+```tsx
+interface GatherDatePickerProps {
+  // CONFIGURACIÓN
+  mode?: 'single' | 'range'; // Modo de selección
+  selected?: Date | DateRange; // Valor seleccionado
+  onSelect?: (date: any) => void; // Callback de selección
+  timeZone?: string; // Zona horaria (default: 'America/Guayaquil')
+
+  // VISUAL
+  placeholder?: string; // Texto placeholder
+  disabled?: boolean; // Estado deshabilitado
+  className?: string; // Clases adicionales
+
+  // RANGO Y RESTRICCIONES
+  minDate?: Date; // Fecha mínima
+  maxDate?: Date; // Fecha máxima
+  disabledDates?: Date[]; // Fechas deshabilitadas específicas
+  pastYearsCount?: number; // Años pasados a mostrar en selector
+
+  // FORMATO
+  dateFormat?: string; // Formato de fecha (ej: 'dd MMM yyyy')
+  rangeFromFormat?: string; // Formato inicio rango
+  rangeToFormat?: string; // Formato fin rango
+
+  // COMPORTAMIENTO
+  autoClose?: boolean; // Cerrar al seleccionar (single mode)
+
+  // VALIDACIÓN (NUEVO)
+  error?: boolean; // Estado de error (borde rojo)
+  helperText?: string; // Texto de ayuda/error
+  required?: boolean; // Marca de campo requerido (*)
+}
+```
+
+### Props Específicas de GatherDatePicker (Botón)
+
+```tsx
+interface GatherDatePickerProps {
+  // ... props comunes
+  variant?: 'default' | 'outline' | 'ghost' | 'secondary'; // Variante del botón
+  hideActionButtons?: boolean; // Ocultar botones Aplicar/Cancelar
+  applyButtonText?: string; // Texto botón Aplicar
+  cancelButtonText?: string; // Texto botón Cancelar
+  showPresets?: boolean; // Mostrar panel de presets (ayer, hoy, etc.)
+  presets?: DatePreset[]; // Presets personalizados
+}
+```
+
+### Props Específicas de GatherDatePickerInput (Input)
+
+```tsx
+interface GatherDatePickerInputProps {
+  // ... props comunes
+  label?: string; // Etiqueta del input
+  description?: string; // Descripción bajo el label
+  showSelectedDate?: boolean; // Mostrar texto de fecha seleccionada
+  selectedDateLabel?: string; // Prefijo para fecha seleccionada
+}
+```
+
+## 🚨 Manejo de Errores y Validaciones
+
+Los componentes ahora soportan estados visuales de error y campos requeridos para integrarse mejor en formularios.
+
+### Input con Error y Mensaje
+
+```tsx
+<GatherDatePickerInput
+  mode='single'
+  label='Fecha de Facturación'
+  required={true} // Muestra asterisco rojo *
+  error={true} // Borde rojo en el input
+  helperText='La fecha es obligatoria' // Muestra mensaje en rojo si hay error
+  onSelect={setDate}
+  selected={date}
+/>
+```
+
+### Botón con Estado de Error
+
+```tsx
+<GatherDatePicker
+  mode='single'
+  selected={date}
+  onSelect={setDate}
+  error={true} // El botón tendrá un borde rojo
+  className='w-full'
+/>;
+{
+  /* Puedes renderizar el texto de error manualmente si usas la versión de botón */
+}
+{
+  hasError && (
+    <p className='mt-1 text-xs text-red-500'>Seleccione una fecha válida</p>
+  );
+}
+```
+
+## 🌍 Zonas Horarias y Formatos
+
+El componente maneja zonas horarias utilizando `date-fns-tz`. Por defecto usa `America/Guayaquil`.
+
+```tsx
+<GatherDatePicker
+  timeZone='Europe/Madrid' // Configurar zona horaria
+  dateFormat='dd/MM/yyyy' // Configurar formato visual
+  selected={date}
+  onSelect={setDate}
+/>
+```