carconnect-gatherleads-ui-lib 3.0.0 → 3.1.0

package/README.md

@@ -3025,166 +3025,232 @@ 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
+# 📅 Guía Completa de GatherCalendar y DatePicker
 
 ## 🎯 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.
+El sistema de fechas de `carconnect-gatherleads-ui-lib` incluye tres componentes principales robustos y flexibles:
+1. **GatherDatePicker**: Botón que abre un popover con calendario.
+2. **GatherDatePickerInput**: Input de texto que abre un popover, ideal para formularios.
+3. **GatherCalendar**: Componente de calendario visual para incrustar directamente.
 
-## 📦 Uso Básico
+> **⚠️ CAMBIO IMPORTANTE (v3.0)**: Para garantizar consistencia, la propiedad `selected` y el callback `onSelect` ahora utilizan **SIEMPRE** el tipo `DateRange` (de `react-day-picker`), incluso si `mode='single'`.
+>
+> - **Modo Single**: La fecha seleccionada estará en `selected.from` (con `to: undefined`).
+> - **Modo Range**: Fecha inicio en `selected.from`, fecha fin en `selected.to`.
+
+## 📦 GatherDatePicker (Botón)
 
-### Selector de Fecha Simple (Botón)
+### Uso Básico
 
 ```tsx
 import { GatherDatePicker } from '@/base/date-picker/gather-date-picker';
+import type { DateRange } from 'react-day-picker';
 
 const SimpleDatePicker = () => {
-  const [date, setDate] = React.useState<Date | undefined>(new Date());
+  // Inicializamos el estado compatible con DateRange
+  const [selected, setSelected] = React.useState<DateRange | undefined>({
+    from: new Date(),
+    to: undefined // En modo single, 'to' se ignora o es undefined
+  });
 
   return (
     <GatherDatePicker
       mode='single'
-      selected={date}
-      onSelect={setDate}
+      selected={selected}
+      onSelect={setSelected}
       placeholder='Seleccionar fecha'
     />
   );
 };
 ```
 
-### Input de Fecha
+### Uso Avanzado con Selectores de Año (Dropdown)
+
+```tsx
+<GatherDatePicker
+  mode="single"
+  layout="dropdown" // Habilita navegación por selects
+  selectProps={{
+    pastYearsCount: 100,  // Años hacia el pasado (ej: nacimientos)
+    futureYearsCount: 10  // Años hacia el futuro (ej: vencimientos)
+  }}
+  selected={selected}
+  onSelect={setSelected}
+/>
+```
+
+## 📦 GatherDatePickerInput
+
+Componente optimizado para formularios, con manejo de etiquetas, errores y descripciones.
 
 ```tsx
 import { GatherDatePickerInput } from '@/base/date-picker/gather-date-picker-input';
 
 const InputDatePicker = () => {
-  const [date, setDate] = React.useState<Date | undefined>();
+  const [selected, setSelected] = React.useState<DateRange | undefined>();
 
   return (
     <GatherDatePickerInput
       mode='single'
-      selected={date}
-      onSelect={setDate}
-      label='Fecha de nacimiento'
-      placeholder='Seleccione su fecha de nacimiento'
+      label='Fecha de Nacimiento'
+      placeholder='dd/mm/aaaa'
+      selected={selected}
+      onSelect={setSelected}
+      // Validación
+      required
+      error={!selected?.from}
+      helperText={!selected?.from ? "Campo requerido" : "Formato válido"}
+      // Comportamiento
+      autoClose={true}
     />
   );
 };
 ```
 
-## ⚙️ Props Principales
+## 📦 GatherCalendar (Standalone)
 
-### GatherDatePickerProps & GatherDatePickerInputProps
-
-Ambos componentes comparten la mayoría de las props, heredando de una base común:
+Para cuando necesitas mostrar el calendario directamente en la interfaz (sin popover).
 
 ```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')
+import { GatherCalendar } from '@/base/calendar/gather-calendar';
 
-  // VISUAL
-  placeholder?: string; // Texto placeholder
-  disabled?: boolean; // Estado deshabilitado
-  className?: string; // Clases adicionales
+const DashboardCalendar = () => {
+  const [range, setRange] = React.useState<DateRange | undefined>();
+
+  return (
+    <div className="p-4 border rounded-xl bg-white shadow-sm">
+      <h3 className="mb-4 font-bold">Seleccionar Periodo</h3>
+      <GatherCalendar
+        mode="range"
+        selected={range}
+        onSelect={setRange}
+        layout="default"
+      />
+    </div>
+  );
+};
+```
 
-  // 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
+## ⚙️ Props Principales (Comunes)
 
-  // FORMATO
-  dateFormat?: string; // Formato de fecha (ej: 'dd MMM yyyy')
-  rangeFromFormat?: string; // Formato inicio rango
-  rangeToFormat?: string; // Formato fin rango
+Estas props aplican a `GatherDatePicker`, `GatherDatePickerInput` y `GatherCalendar` (vía `GatherBaseCalendarProps`).
 
-  // COMPORTAMIENTO
-  autoClose?: boolean; // Cerrar al seleccionar (single mode)
+| Prop | Tipo | Descripción |
+|------|------|-------------|
+| `mode` | `'single' \| 'range'` | Modo de selección. |
+| `selected` | `DateRange` | **Siempre** es `{ from: Date, to?: Date }`. |
+| `onSelect` | `(range: DateRange) => void` | Callback con la selección actualizada. |
+| `layout` | `'default' \| 'dropdown'` | Estilo de navegación (flechas vs selects). |
+| `selectProps` | `{ pastYearsCount, futureYearsCount }` | Configuración de años para `layout='dropdown'`. |
+| `minDate` | `Date` | Fecha mínima seleccionable. |
+| `maxDate` | `Date` | Fecha máxima seleccionable. |
+| `disabled` | `boolean` | Deshabilita la interacción. |
+| `timeZone` | `string` | Zona horaria (default: 'America/Guayaquil'). |
 
-  // 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 DatePicker / Input
 
-### Props Específicas de GatherDatePicker (Botón)
+| Prop | Tipo | Componente | Descripción |
+|------|------|------------|-------------|
+| `placeholder` | `string` | Ambos | Texto cuando no hay selección. |
+| `autoClose` | `boolean` | Ambos | Cerrar popover al seleccionar (single). |
+| `showPresets` | `boolean` | DatePicker | Muestra panel lateral de opciones rápidas. |
+| `label` | `string` | Input | Etiqueta superior del campo. |
+| `error` | `boolean` | Ambos | Estado visual de error. |
+| `helperText` | `string` | Input | Texto de ayuda o mensaje de error. |
+| `applyButtonText` | `string` | DatePicker | Texto botón aceptar. |
 
-```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
-}
-```
+---
+
+# ⏳ Guía Completa de GatherLoader
+
+## 🎯 Introducción
+
+`GatherLoader` es un componente unificado para indicar estados de carga, espera o procesamiento. Está diseñado para ser flexible y adaptarse a diferentes contextos, desde spinners simples hasta overlays de pantalla completa y esqueletos de contenido.
+
+## 📦 Uso Básico
 
-### Props Específicas de GatherDatePickerInput (Input)
+### Spinner por Defecto
+
+Muestra un spinner circular con el color principal de Gather (verde).
 
 ```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
-}
+import { GatherLoader } from '@/components/loader';
+
+const LoadingState = () => (
+  <div className="flex justify-center p-4">
+    <GatherLoader />
+  </div>
+);
 ```
 
-## 🚨 Manejo de Errores y Validaciones
+## 🎨 Variantes
 
-Los componentes ahora soportan estados visuales de error y campos requeridos para integrarse mejor en formularios.
+### Default (Spinner)
 
-### Input con Error y Mensaje
+La variante estándar. Soporta diferentes tamaños y colores.
 
 ```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}
-/>
+// Tamaños
+<GatherLoader size="sm" /> // Pequeño (16px)
+<GatherLoader size="md" /> // Mediano (24px) - Default
+<GatherLoader size="lg" /> // Grande (32px)
+<GatherLoader size="xl" /> // Extra Grande (48px)
+
+// Colores personalizados
+<GatherLoader className="text-blue-500" />
+<GatherLoader className="text-white" />
 ```
 
-### Botón con Estado de Error
+### Floating (Overlay)
+
+Crea un overlay sobre el contenedor padre (o toda la pantalla si se usa en un portal o fixed container) para bloquear la interacción durante procesos críticos.
 
 ```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>
-  );
-}
+const SubmitButton = ({ isLoading }) => (
+  <div className="relative">
+    <button>Guardar Cambios</button>
+    
+    {/* Overlay de carga sobre el botón/contenedor */}
+    {isLoading && (
+      <GatherLoader 
+        variant="floating" 
+        className="bg-white/50 backdrop-blur-sm" // Fondo semitransparente con blur
+      />
+    )}
+  </div>
+);
 ```
 
-## 🌍 Zonas Horarias y Formatos
+### Skeleton (Esqueleto de Contenido)
 
-El componente maneja zonas horarias utilizando `date-fns-tz`. Por defecto usa `America/Guayaquil`.
+Utilizado para simular la estructura del contenido mientras se cargan los datos, mejorando la percepción de velocidad (Perceived Performance).
 
 ```tsx
-<GatherDatePicker
-  timeZone='Europe/Madrid' // Configurar zona horaria
-  dateFormat='dd/MM/yyyy' // Configurar formato visual
-  selected={date}
-  onSelect={setDate}
-/>
+const CardSkeleton = () => (
+  <div className="border rounded-lg p-4 space-y-3">
+    {/* Imagen hero */}
+    <GatherLoader variant="skeleton" className="h-32 w-full rounded-md" />
+    
+    {/* Título */}
+    <GatherLoader variant="skeleton" className="h-6 w-3/4 rounded" />
+    
+    {/* Líneas de texto */}
+    <div className="space-y-2">
+      <GatherLoader variant="skeleton" className="h-4 w-full rounded" />
+      <GatherLoader variant="skeleton" className="h-4 w-5/6 rounded" />
+    </div>
+  </div>
+);
 ```
+
+## ⚙️ Props
+
+| Prop | Tipo | Default | Descripción |
+|------|------|---------|-------------|
+| `variant` | `'default' \| 'floating' \| 'skeleton'` | `'default'` | El estilo visual del loader. |
+| `size` | `'sm' \| 'md' \| 'lg' \| 'xl'` | `'md'` | El tamaño del spinner (solo aplica a variants `default` y `floating`). |
+| `className` | `string` | `''` | Clases CSS adicionales. Para `skeleton`, usa esto para definir dimensions (w/h). |
+| `color` | `string` | `undefined` | (Legacy) Color del spinner. Se recomienda usar clases de Tailwind en `className` (ej: `text-red-500`). |
+
+---