@adamosuiteservices/ui 2.10.13 → 2.11.13

package/docs/components/ui/date-picker-selector.md

@@ -0,0 +1,376 @@
+# Date Picker Selector
+
+A comprehensive date range selector component combining preset date ranges with custom calendar selection.
+
+## Descripción
+
+El componente `DatePickerSelector` proporciona una interfaz intuitiva para seleccionar rangos de fechas. Incluye opciones predefinidas (últimos 7, 30, 90 días) y un selector de calendario personalizado para rangos específicos.
+
+## Características
+
+- ✅ Rangos predefinidos (7, 30, 90 días)
+- ✅ Selector de calendario personalizado para rangos específicos
+- ✅ Formato de fecha limpio (medianoche, sin horas)
+- ✅ Labels personalizables para internacionalización
+- ✅ Integración con Combobox y Calendar
+- ✅ Props personalizables para Combobox y Calendar
+- ✅ Estado controlado con callback onChange
+
+## Importación
+
+```typescript
+import { DatePickerSelector } from "@adamosuiteservices/ui/date-picker-selector";
+import type { DateRange } from "react-day-picker";
+```
+
+## Uso Básico
+
+```tsx
+import { DatePickerSelector } from "@adamosuiteservices/ui/date-picker-selector";
+import { useState } from "react";
+import type { DateRange } from "react-day-picker";
+
+function MyComponent() {
+  const [dateRange, setDateRange] = useState<DateRange>({
+    from: undefined,
+    to: undefined,
+  });
+
+  return (
+    <DatePickerSelector
+      dateRange={dateRange}
+      onDateRangeChange={setDateRange}
+    />
+  );
+}
+```
+
+## Props
+
+| Prop               | Tipo                     | Default     | Descripción                                                    |
+| ------------------ | ------------------------ | ----------- | -------------------------------------------------------------- |
+| `dateRange`        | `DateRange`              | -           | **Requerido**. Rango de fechas actual                          |
+| `onDateRangeChange`| `(dateRange: DateRange) => void` | - | **Requerido**. Callback al cambiar el rango                    |
+| `labels`           | `DatePickerSelectorLabels` | -         | Labels personalizables para todos los textos de UI             |
+| `combobox`         | `ComboboxProps`          | -           | Props adicionales para el componente Combobox                  |
+| `calendar`         | `CalendarProps`          | -           | Props adicionales para el componente Calendar                  |
+| `className`        | `string`                 | -           | Clases CSS adicionales para el contenedor                      |
+| ...props           | `HTMLAttributes<HTMLDivElement>` | - | Props nativas de div                                           |
+
+### DateRange Type
+
+```typescript
+type DateRange = {
+  from: Date | undefined;
+  to: Date | undefined;
+};
+```
+
+### DatePickerSelectorLabels Type
+
+```typescript
+type DatePickerSelectorLabels = {
+  last30Days?: string;   // Default: "Last 30 days"
+  last7Days?: string;    // Default: "Last 7 days"
+  last90Days?: string;   // Default: "Last 90 days"
+  custom?: string;       // Default: "Custom"
+  placeholder?: string;  // Default: "Date"
+  cancel?: string;       // Default: "Cancel"
+  apply?: string;        // Default: "Apply"
+};
+```
+
+## Patrones de Uso
+
+### Con Valor Inicial
+
+```tsx
+import { subDays, startOfDay } from "date-fns";
+
+function MyComponent() {
+  const today = startOfDay(new Date());
+  const [dateRange, setDateRange] = useState<DateRange>({
+    from: subDays(today, 30),
+    to: today,
+  });
+
+  return (
+    <DatePickerSelector
+      dateRange={dateRange}
+      onDateRangeChange={setDateRange}
+    />
+  );
+}
+```
+
+### Con Labels Personalizados (Internacionalización)
+
+```tsx
+<DatePickerSelector
+  dateRange={dateRange}
+  onDateRangeChange={setDateRange}
+  labels={{
+    last7Days: "Últimos 7 días",
+    last30Days: "Últimos 30 días",
+    last90Days: "Últimos 90 días",
+    custom: "Personalizado",
+    placeholder: "Fecha",
+    cancel: "Cancelar",
+    apply: "Aplicar",
+  }}
+/>
+```
+
+### Con Props Personalizados del Combobox
+
+```tsx
+<DatePickerSelector
+  dateRange={dateRange}
+  onDateRangeChange={setDateRange}
+  combobox={{
+    classNames: {
+      trigger: "w-[300px]",
+    },
+  }}
+/>
+```
+
+### Con Props Personalizados del Calendar
+
+```tsx
+<DatePickerSelector
+  dateRange={dateRange}
+  onDateRangeChange={setDateRange}
+  calendar={{
+    fromYear: 2020,
+    toYear: 2030,
+  }}
+/>
+```
+
+### Formato de Fecha con date-fns
+
+```tsx
+import { format } from "date-fns";
+
+function MyComponent() {
+  const [dateRange, setDateRange] = useState<DateRange>({
+    from: undefined,
+    to: undefined,
+  });
+
+  const formatDateRange = () => {
+    if (!dateRange.from || !dateRange.to) return "No date selected";
+    return `${format(dateRange.from, "MMM d, yyyy")} - ${format(dateRange.to, "MMM d, yyyy")}`;
+  };
+
+  return (
+    <div>
+      <DatePickerSelector
+        dateRange={dateRange}
+        onDateRangeChange={setDateRange}
+      />
+      <p>Selected: {formatDateRange()}</p>
+    </div>
+  );
+}
+```
+
+### Validación de Rango
+
+```tsx
+function MyComponent() {
+  const [dateRange, setDateRange] = useState<DateRange>({
+    from: undefined,
+    to: undefined,
+  });
+
+  const handleDateRangeChange = (newRange: DateRange) => {
+    // Validate that both dates are selected
+    if (newRange.from && newRange.to) {
+      setDateRange(newRange);
+    }
+  };
+
+  const isValidRange = dateRange.from && dateRange.to;
+
+  return (
+    <div>
+      <DatePickerSelector
+        dateRange={dateRange}
+        onDateRangeChange={handleDateRangeChange}
+      />
+      {!isValidRange && (
+        <p className="text-destructive text-sm mt-2">
+          Please select a complete date range
+        </p>
+      )}
+    </div>
+  );
+}
+```
+
+## Comportamiento
+
+### Rangos Predefinidos
+
+El componente ofrece tres rangos predefinidos:
+
+- **Last 7 days**: Desde hace 7 días hasta hoy
+- **Last 30 days**: Desde hace 30 días hasta hoy
+- **Last 90 days**: Desde hace 90 días hasta hoy
+
+Todos los rangos predefinidos:
+- Usan `date-fns` para cálculos precisos
+- Establecen las fechas a medianoche (00:00:00)
+- Se calculan dinámicamente basándose en la fecha actual
+
+### Rango Personalizado
+
+Al seleccionar la opción "Custom":
+1. Se abre un popover con un calendario
+2. El usuario selecciona un rango de fechas
+3. Los botones "Cancel" y "Apply" permiten confirmar o descartar la selección
+4. El rango personalizado se mantiene independiente de los rangos predefinidos
+
+### Separación de Estados
+
+- Los rangos predefinidos resetean cualquier selección personalizada previa
+- El rango personalizado mantiene su valor hasta que se seleccione un rango predefinido
+- Esto previene conflictos entre los dos modos de selección
+
+## Casos de Uso
+
+**Filtros de reportes**: Seleccionar rango de fechas para generar reportes  
+**Dashboards**: Filtrar datos por períodos de tiempo  
+**Analytics**: Comparar métricas en diferentes rangos  
+**Búsquedas**: Filtrar resultados por rango de fechas  
+**Logs**: Visualizar registros en períodos específicos  
+
+## Dependencias
+
+Este componente utiliza internamente:
+
+- **Combobox**: Para el selector de opciones con el ícono de calendario
+- **Calendar**: Para la selección de rangos personalizados
+- **Popover**: Para mostrar el calendario
+- **Button**: Para las acciones "Cancel" y "Apply"
+- **date-fns**: Para cálculos de fechas (`startOfDay`, `subDays`)
+- **react-day-picker**: Para la gestión del calendario
+
+## Estilos Base
+
+- **Contenedor**: `flex w-max flex-col`
+- **Combobox**: Con placeholder siempre visible, ícono de calendario, feedback tipo check
+- **Calendar**: Con `captionLayout="dropdown"` para navegación por años
+- **Botones**: Estilo `variant="link"` para Cancel y Apply
+
+## Accesibilidad
+
+- ✅ Labels descriptivos para todas las opciones
+- ✅ Navegación por teclado en combobox y calendario
+- ✅ Estados de selección claramente indicados
+- ✅ Feedback visual en checkmarks
+- ✅ Acciones claramente etiquetadas (Cancel/Apply)
+
+## Mejores Prácticas
+
+### Gestión del Estado
+
+```tsx
+// ✅ Correcto - Estado controlado
+const [dateRange, setDateRange] = useState<DateRange>({
+  from: undefined,
+  to: undefined,
+});
+
+<DatePickerSelector
+  dateRange={dateRange}
+  onDateRangeChange={setDateRange}
+/>
+
+// ❌ Incorrecto - Estado no inicializado
+const [dateRange, setDateRange] = useState();
+```
+
+### Validación
+
+```tsx
+// ✅ Correcto - Validar rango completo
+const handleChange = (range: DateRange) => {
+  if (range.from && range.to) {
+    // Procesar rango válido
+    setDateRange(range);
+  }
+};
+
+// ✅ Correcto - Mostrar feedback de validación
+{!dateRange.from || !dateRange.to ? (
+  <p className="text-destructive">Please select both dates</p>
+) : null}
+```
+
+### Formateo de Fechas
+
+```tsx
+import { format } from "date-fns";
+
+// ✅ Correcto - Formatear con date-fns
+const displayDate = dateRange.from 
+  ? format(dateRange.from, "PP")
+  : "Not selected";
+
+// ❌ Evitar - toString() no es user-friendly
+const displayDate = dateRange.from?.toString();
+```
+
+### Internacionalización
+
+```tsx
+// ✅ Correcto - Proporcionar todos los labels
+<DatePickerSelector
+  labels={{
+    last7Days: t("dateRange.last7Days"),
+    last30Days: t("dateRange.last30Days"),
+    last90Days: t("dateRange.last90Days"),
+    custom: t("dateRange.custom"),
+    placeholder: t("dateRange.placeholder"),
+    cancel: t("actions.cancel"),
+    apply: t("actions.apply"),
+  }}
+/>
+```
+
+## Limitaciones
+
+- ❌ Solo soporta rangos (no fechas individuales)
+- ❌ Los rangos predefinidos son fijos (7, 30, 90 días)
+- ❌ No incluye presets personalizables adicionales
+- ❌ No soporta selección de hora (solo fechas)
+
+## Troubleshooting
+
+**Problema**: Las fechas tienen horas no deseadas  
+**Solución**: El componente usa `startOfDay()` automáticamente. Si pasas fechas con horas, normalízalas antes:
+
+```tsx
+import { startOfDay } from "date-fns";
+
+const normalizedRange = {
+  from: dateRange.from ? startOfDay(dateRange.from) : undefined,
+  to: dateRange.to ? startOfDay(dateRange.to) : undefined,
+};
+```
+
+**Problema**: El calendario no se abre  
+**Solución**: Verifica que estás pasando las props correctamente y que el componente Calendar está importado.
+
+**Problema**: Los rangos predefinidos no funcionan  
+**Solución**: Asegúrate de que `onDateRangeChange` esté actualizando el estado correctamente.
+
+## Referencias
+
+- **Combobox**: [Ver documentación](./combobox.md)
+- **Calendar**: [Ver documentación](./calendar.md)
+- **date-fns**: https://date-fns.org/
+- **react-day-picker**: https://react-day-picker.js.org/

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adamosuiteservices/ui",
-  "version": "2.10.13",
+  "version": "2.11.13",
   "private": false,
   "type": "module",
   "main": "./dist/index.js",
@@ -38,6 +38,10 @@
       "types": "./dist/components/layout/toaster/index.d.ts",
       "import": "./dist/toaster.js"
     },
+    "./full-screen-loader": {
+      "types": "./dist/components/layout/full-screen-loader/index.d.ts",
+      "import": "./dist/full-screen-loader.js"
+    },
     "./accordion": {
       "types": "./dist/components/ui/accordion/accordion.d.ts",
       "import": "./dist/accordion.js"
@@ -94,6 +98,10 @@
       "types": "./dist/components/ui/context-menu/context-menu.d.ts",
       "import": "./dist/context-menu.js"
     },
+    "./date-picker-selector": {
+      "types": "./dist/components/ui/date-picker-selector/date-picker-selector.d.ts",
+      "import": "./dist/date-picker-selector.js"
+    },
     "./dialog": {
       "types": "./dist/components/ui/dialog/dialog.d.ts",
       "import": "./dist/dialog.js"