carconnect-gatherleads-ui-lib 2.4.2 → 3.0.0

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
@@ -3010,3 +3024,167 @@ const DetailsSidebar = ({ user, isOpen, onClose }) => (
 ```
 
 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}
+/>
+```