@adamosuiteservices/ui 2.13.2 → 2.13.4

package/docs/components/ui/calendar.md

@@ -1,1159 +1,1159 @@
-# Calendar
-
-Calendario interactivo altamente personalizable basado en `react-day-picker` para selección de fechas individuales, múltiples o rangos. Soporta navegación con dropdowns, múltiples meses, números de semana, timezones y fechas deshabilitadas.
-
-## Características Principales
-
-- **4 modos de selección**: Single (fecha única), Multiple (múltiples fechas), Range (rango de fechas), Default (sin selección)
-- **Navegación flexible**: Botones tradicionales o dropdowns mes/año para saltos rápidos
-- **Múltiples meses**: Visualización simultánea de 2+ meses para rangos amplios
-- **Números de semana**: Muestra semana del año (ISO 8601)
-- **Fechas deshabilitadas**: Bloquea fechas específicas o rangos completos
-- **Timezone awareness**: Soporte completo para zonas horarias
-- **Variantes de botones**: Personaliza navegación (ghost, outline, secondary, etc.)
-- **RTL support**: Rotación automática de chevrons en idiomas right-to-left
-- **Integración con Card/Popover**: Background transparente automático
-- **Accesibilidad**: Navegación por teclado, ARIA labels, focus visible
-
-## Importación
-
-```tsx
-import { Calendar } from "@adamosuiteservices/ui/calendar";
-import type { DateRange } from "react-day-picker";
-```
-
-```tsx
-import { Calendar } from "@adamosuiteservices/ui/calendar";
-import type { DateRange } from "react-day-picker";
-```
-
-## Uso Básico
-
-### Selección de Fecha Única
-
-El modo más común para seleccionar una sola fecha.
-
-```tsx
-import { useState } from "react";
-import { Calendar } from "@adamosuiteservices/ui/calendar";
-
-function DatePicker() {
-  const [date, setDate] = useState<Date | undefined>(new Date());
-
-  return (
-    <Calendar
-      mode="single"
-      selected={date}
-      onSelect={setDate}
-      className="rounded-md border"
-    />
-  );
-}
-```
-
-### Navegación con Dropdowns
-
-Para saltar rápidamente entre meses y años.
-
-```tsx
-const [date, setDate] = useState<Date | undefined>(new Date(2025, 5, 12));
-
-<Calendar
-  mode="single"
-  selected={date}
-  onSelect={setDate}
-  captionLayout="dropdown"
-  className="rounded-md border"
-/>;
-```
-
-**Ventaja**: Permite seleccionar fechas lejanas sin hacer múltiples clics en flechas.
-
-### Rango de Fechas
-
-Para seleccionar periodo entre dos fechas (ej: reservas de hotel).
-
-```tsx
-import type { DateRange } from "react-day-picker";
-
-function RangePicker() {
-  const [range, setRange] = useState<DateRange | undefined>({
-    from: new Date(2025, 5, 12),
-    to: new Date(2025, 5, 18),
-  });
-
-  return (
-    <Calendar
-      mode="range"
-      defaultMonth={range?.from}
-      selected={range}
-      onSelect={setRange}
-      className="rounded-md border"
-    />
-  );
-}
-```
-
-### Múltiples Meses
-
-Ideal para rangos largos o visualización amplia.
-
-```tsx
-const [range, setRange] = useState<DateRange | undefined>({
-  from: new Date(2025, 5, 12),
-  to: new Date(2025, 6, 15),
-});
-
-<Calendar
-  mode="range"
-  defaultMonth={range?.from}
-  selected={range}
-  onSelect={setRange}
-  numberOfMonths={2}
-  className="rounded-md border"
-/>;
-```
-
-**Nota**: En pantallas pequeñas, los meses se apilan verticalmente automáticamente.
-
-### Selección Múltiple
-
-Para seleccionar fechas no consecutivas (ej: días de entrenamiento).
-
-```tsx
-const [dates, setDates] = useState<Date[] | undefined>([
-  new Date(2025, 5, 12),
-  new Date(2025, 5, 15),
-  new Date(2025, 5, 20),
-]);
-
-<Calendar
-  mode="multiple"
-  selected={dates}
-  onSelect={setDates}
-  className="rounded-md border"
-/>;
-```
-
-## Componentes
-
-### Calendar
-
-El componente principal que renderiza el calendario completo.
-
-#### Props
-
-| Prop              | Tipo                                                             | Default       | Descripción                                 |
-| ----------------- | ---------------------------------------------------------------- | ------------- | ------------------------------------------- |
-| `mode`            | `"single" \| "multiple" \| "range" \| "default"`                 | `"default"`   | Modo de selección de fechas                 |
-| `selected`        | `Date \| Date[] \| DateRange \| undefined`                       | `undefined`   | Fecha(s) seleccionada(s) según modo         |
-| `onSelect`        | `(date) => void`                                                 | -             | Callback cuando cambia la selección         |
-| `defaultMonth`    | `Date`                                                           | Mes actual    | Mes inicial a mostrar                       |
-| `numberOfMonths`  | `number`                                                         | `1`           | Cantidad de meses a mostrar simultáneamente |
-| `captionLayout`   | `"label" \| "dropdown" \| "dropdown-months" \| "dropdown-years"` | `"label"`     | Tipo de navegación del header               |
-| `showOutsideDays` | `boolean`                                                        | `true`        | Mostrar días de meses adyacentes            |
-| `showWeekNumber`  | `boolean`                                                        | `false`       | Mostrar números de semana                   |
-| `disabled`        | `Date \| Date[] \| DateRange \| ((date: Date) => boolean)`       | -             | Fechas deshabilitadas                       |
-| `hidden`          | `Date \| Date[] \| DateRange \| ((date: Date) => boolean)`       | -             | Fechas ocultas completamente                |
-| `fromDate`        | `Date`                                                           | -             | Fecha mínima seleccionable                  |
-| `toDate`          | `Date`                                                           | -             | Fecha máxima seleccionable                  |
-| `fromMonth`       | `Date`                                                           | -             | Mes mínimo navegable                        |
-| `toMonth`         | `Date`                                                           | -             | Mes máximo navegable                        |
-| `fromYear`        | `number`                                                         | -             | Año mínimo navegable                        |
-| `toYear`          | `number`                                                         | -             | Año máximo navegable                        |
-| `timeZone`        | `string`                                                         | Sistema       | Zona horaria (ej: `"America/New_York"`)     |
-| `locale`          | `Locale`                                                         | Sistema       | Objeto Locale de `date-fns` para i18n       |
-| `weekStartsOn`    | `0 \| 1 \| 2 \| 3 \| 4 \| 5 \| 6`                                | `0`           | Día inicio de semana (0=Domingo, 1=Lunes)   |
-| `buttonVariant`   | `ButtonProps["variant"]`                                         | `"secondary"` | Variante para botones de navegación         |
-| `className`       | `string`                                                         | -             | Clases CSS adicionales para el contenedor   |
-| `classNames`      | `ClassNames`                                                     | -             | Objeto con clases para elementos internos   |
-| `components`      | `Components`                                                     | -             | Componentes custom para override            |
-| `formatters`      | `Formatters`                                                     | -             | Funciones de formateo custom                |
-
-### CalendarDayButton
-
-Componente interno que renderiza cada día del calendario. Raramente se usa directamente.
-
-## Modos de Selección
-
-### Mode: "single"
-
-Un solo día seleccionado a la vez.
-
-```tsx
-// Tipo de selected
-selected: Date | undefined
-
-// Callback
-onSelect: (date: Date | undefined) => void
-```
-
-**Uso común**: Fecha de nacimiento, vencimiento de documento, fecha límite.
-
-### Mode: "multiple"
-
-Array de días no consecutivos.
-
-```tsx
-// Tipo de selected
-selected: Date[] | undefined
-
-// Callback
-onSelect: (dates: Date[] | undefined) => void
-```
-
-**Uso común**: Días de entrenamiento, fechas de eventos recurrentes, días festivos.
-
-### Mode: "range"
-
-Rango continuo entre dos fechas.
-
-```tsx
-import type { DateRange } from "react-day-picker";
-
-// Tipo de selected
-selected: DateRange | undefined  // { from?: Date; to?: Date }
-
-// Callback
-onSelect: (range: DateRange | undefined) => void
-```
-
-**Uso común**: Reservas de hotel, filtros de reportes, periodos de vacaciones.
-
-### Mode: "default"
-
-Sin selección (solo visualización).
-
-```tsx
-<Calendar mode="default" />
-```
-
-**Uso común**: Mostrar calendario estático, vista de disponibilidad sin interacción.
-
-## Captionlayout (Navegación)
-
-### "label" (Default)
-
-Navegación tradicional con flechas.
-
-```tsx
-<Calendar captionLayout="label" />
-```
-
-**Ventaja**: UI simple, menos espacio vertical.
-
-### "dropdown"
-
-Dropdowns para mes Y año.
-
-```tsx
-<Calendar captionLayout="dropdown" fromYear={2020} toYear={2030} />
-```
-
-**Ventaja**: Saltos rápidos a fechas lejanas. Ideal para fecha de nacimiento.
-
-### "dropdown-months"
-
-Solo dropdown de meses, año con flechas.
-
-```tsx
-<Calendar captionLayout="dropdown-months" />
-```
-
-### "dropdown-years"
-
-Solo dropdown de años, mes con flechas.
-
-```tsx
-<Calendar captionLayout="dropdown-years" />
-```
-
-## Patrones Avanzados
-
-### Fechas Deshabilitadas (Múltiples Formas)
-
-#### Fechas Específicas
-
-```tsx
-const disabledDays = [
-  new Date(2025, 9, 15),
-  new Date(2025, 9, 16),
-  new Date(2025, 9, 17),
-];
-
-<Calendar
-  mode="single"
-  disabled={disabledDays}
-  selected={date}
-  onSelect={setDate}
-/>;
-```
-
-#### Rangos de Fechas
-
-```tsx
-const disabledRanges = [
-  { from: new Date(2025, 9, 20), to: new Date(2025, 9, 25) },
-  { from: new Date(2025, 10, 1), to: new Date(2025, 10, 7) },
-];
-
-<Calendar disabled={disabledRanges} />;
-```
-
-#### Función Dinámica
-
-```tsx
-// Deshabilitar fines de semana
-const isWeekend = (date: Date) => {
-  const day = date.getDay();
-  return day === 0 || day === 6;
-};
-
-<Calendar disabled={isWeekend} />;
-```
-
-#### Deshabilitar Pasado
-
-```tsx
-// Solo fechas futuras
-<Calendar
-  disabled={{ before: new Date() }}
-  mode="single"
-  selected={date}
-  onSelect={setDate}
-/>
-```
-
-#### Deshabilitar Futuro
-
-```tsx
-// Solo fechas pasadas
-<Calendar
-  disabled={{ after: new Date() }}
-  mode="single"
-  selected={date}
-  onSelect={setDate}
-/>
-```
-
-### Rango de Fechas Permitidas
-
-#### Con fromDate y toDate
-
-```tsx
-// Solo permitir 30 días hacia adelante
-<Calendar
-  mode="single"
-  fromDate={new Date()}
-  toDate={new Date(Date.now() + 30 * 24 * 60 * 60 * 1000)}
-  selected={date}
-  onSelect={setDate}
-/>
-```
-
-#### Con fromYear y toYear
-
-```tsx
-// Para fecha de nacimiento (mayores de 18)
-const currentYear = new Date().getFullYear();
-
-<Calendar
-  mode="single"
-  captionLayout="dropdown"
-  fromYear={1950}
-  toYear={currentYear - 18}
-  defaultMonth={new Date(2000, 0)}
-  selected={birthdate}
-  onSelect={setBirthdate}
-/>;
-```
-
-### Calendario en Card
-
-Integración perfecta con componente Card (background transparente automático).
-
-```tsx
-import {
-  Card,
-  CardContent,
-  CardDescription,
-  CardHeader,
-  CardTitle,
-} from "@adamosuiteservices/ui/card";
-
-<Card className="w-fit">
-  <CardHeader>
-    <CardTitle>Select Date</CardTitle>
-    <CardDescription>Choose a date for your appointment</CardDescription>
-  </CardHeader>
-  <CardContent>
-    <Calendar
-      mode="single"
-      selected={date}
-      onSelect={setDate}
-      captionLayout="dropdown"
-    />
-  </CardContent>
-</Card>;
-```
-
-### Calendario en Popover
-
-Para date pickers compactos.
-
-```tsx
-import {
-  Popover,
-  PopoverContent,
-  PopoverTrigger,
-} from "@adamosuiteservices/ui/popover";
-import { Button } from "@adamosuiteservices/ui/button";
-import { Icon } from "@adamosuiteservices/ui/icon";
-import { format } from "date-fns";
-
-function DatePickerPopover() {
-  const [date, setDate] = useState<Date>();
-
-  return (
-    <Popover>
-      <PopoverTrigger asChild>
-        <Button variant="outline">
-          <Icon symbol="calendar_today" />
-          {date ? format(date, "PPP") : "Pick a date"}
-        </Button>
-      </PopoverTrigger>
-      <PopoverContent className="w-auto p-0">
-        <Calendar
-          mode="single"
-          selected={date}
-          onSelect={setDate}
-          initialFocus
-        />
-      </PopoverContent>
-    </Popover>
-  );
-}
-```
-
-**Nota**: El background se vuelve transparente automáticamente dentro de PopoverContent.
-
-### Con Timezone
-
-```tsx
-import { useState } from "react";
-
-function TimezoneCalendar() {
-  const [date, setDate] = useState<Date>();
-  const [timeZone] = useState(Intl.DateTimeFormat().resolvedOptions().timeZone);
-
-  return (
-    <div className="space-y-2">
-      <p className="text-sm text-muted-foreground">Timezone: {timeZone}</p>
-      <Calendar
-        mode="single"
-        selected={date}
-        onSelect={setDate}
-        timeZone={timeZone}
-        className="rounded-md border"
-      />
-    </div>
-  );
-}
-```
-
-### Sin Días Externos (Outside Days)
-
-Oculta días de meses adyacentes para UI más limpia.
-
-```tsx
-<Calendar
-  mode="single"
-  selected={date}
-  onSelect={setDate}
-  showOutsideDays={false}
-  className="rounded-md border"
-/>
-```
-
-### Con Números de Semana
-
-Útil para reportes empresariales o planificación semanal.
-
-```tsx
-<Calendar
-  mode="single"
-  selected={date}
-  onSelect={setDate}
-  showWeekNumber
-  className="rounded-md border"
-/>
-```
-
-**Formato**: Números de semana según ISO 8601 (1-53).
-
-### Variantes de Botones de Navegación
-
-Personaliza la apariencia de los botones prev/next.
-
-```tsx
-<div className="space-y-4">
-  {/* Ghost (default) */}
-  <Calendar mode="single" buttonVariant="ghost" className="rounded-md border" />
-
-  {/* Outline */}
-  <Calendar
-    mode="single"
-    buttonVariant="outline"
-    className="rounded-md border"
-  />
-
-  {/* Secondary */}
-  <Calendar
-    mode="single"
-    buttonVariant="secondary"
-    className="rounded-md border"
-  />
-</div>
-```
-
-### Rango Preseleccionado (Últimos 7 Días)
-
-```tsx
-import { subDays } from "date-fns";
-
-function Last7DaysRange() {
-  const [range, setRange] = useState<DateRange>({
-    from: subDays(new Date(), 7),
-    to: new Date(),
-  });
-
-  return (
-    <Calendar
-      mode="range"
-      selected={range}
-      onSelect={setRange}
-      numberOfMonths={2}
-      className="rounded-md border"
-    />
-  );
-}
-```
-
-### Validación de Rango Máximo
-
-Limita la cantidad de días seleccionables en un rango.
-
-```tsx
-import { differenceInDays } from "date-fns";
-
-function MaxRangeCalendar() {
-  const [range, setRange] = useState<DateRange>();
-  const MAX_DAYS = 14;
-
-  const handleSelect = (selectedRange: DateRange | undefined) => {
-    if (!selectedRange?.from || !selectedRange?.to) {
-      setRange(selectedRange);
-      return;
-    }
-
-    const daysDiff = differenceInDays(selectedRange.to, selectedRange.from);
-
-    if (daysDiff > MAX_DAYS) {
-      alert(`Maximum range is ${MAX_DAYS} days`);
-      return;
-    }
-
-    setRange(selectedRange);
-  };
-
-  return (
-    <div className="space-y-2">
-      <p className="text-sm text-muted-foreground">
-        Maximum range: {MAX_DAYS} days
-      </p>
-      <Calendar
-        mode="range"
-        selected={range}
-        onSelect={handleSelect}
-        numberOfMonths={2}
-        className="rounded-md border"
-      />
-    </div>
-  );
-}
-```
-
-### Calendario con Presets de Rango
-
-Botones rápidos para rangos comunes.
-
-```tsx
-import {
-  startOfMonth,
-  endOfMonth,
-  subMonths,
-  startOfWeek,
-  endOfWeek,
-} from "date-fns";
-import { Button } from "@adamosuiteservices/ui/button";
-
-function CalendarWithPresets() {
-  const [range, setRange] = useState<DateRange>();
-
-  const presets = [
-    {
-      label: "Today",
-      range: { from: new Date(), to: new Date() },
-    },
-    {
-      label: "Last 7 days",
-      range: { from: subDays(new Date(), 7), to: new Date() },
-    },
-    {
-      label: "This week",
-      range: { from: startOfWeek(new Date()), to: endOfWeek(new Date()) },
-    },
-    {
-      label: "This month",
-      range: { from: startOfMonth(new Date()), to: endOfMonth(new Date()) },
-    },
-    {
-      label: "Last month",
-      range: {
-        from: startOfMonth(subMonths(new Date(), 1)),
-        to: endOfMonth(subMonths(new Date(), 1)),
-      },
-    },
-  ];
-
-  return (
-    <div className="flex gap-4">
-      <div className="flex flex-col gap-2">
-        {presets.map((preset) => (
-          <Button
-            key={preset.label}
-            variant="outline"
-            onClick={() => setRange(preset.range)}
-            className="justify-start"
-          >
-            {preset.label}
-          </Button>
-        ))}
-      </div>
-      <Calendar
-        mode="range"
-        selected={range}
-        onSelect={setRange}
-        numberOfMonths={2}
-        className="rounded-md border"
-      />
-    </div>
-  );
-}
-```
-
-### Formateo Custom de Meses
-
-```tsx
-<Calendar
-  mode="single"
-  captionLayout="dropdown"
-  formatters={{
-    formatMonthDropdown: (date) =>
-      date.toLocaleString("es-ES", { month: "long" }),
-  }}
-/>
-```
-
-### Internacionalización (i18n)
-
-```tsx
-import { es } from "date-fns/locale";
-
-<Calendar
-  mode="single"
-  locale={es}
-  weekStartsOn={1} // Lunes
-  selected={date}
-  onSelect={setDate}
-/>;
-```
-
-## Casos de Uso Comunes
-
-### Date Picker Simple
-
-```tsx
-import {
-  Popover,
-  PopoverContent,
-  PopoverTrigger,
-} from "@adamosuiteservices/ui/popover";
-import { Button } from "@adamosuiteservices/ui/button";
-import { Icon } from "@adamosuiteservices/ui/icon";
-import { format } from "date-fns";
-
-<Popover>
-  <PopoverTrigger asChild>
-    <Button variant="outline">
-      <Icon symbol="calendar_today" />
-      {date ? format(date, "PPP") : "Pick a date"}
-    </Button>
-  </PopoverTrigger>
-  <PopoverContent className="w-auto p-0">
-    <Calendar mode="single" selected={date} onSelect={setDate} />
-  </PopoverContent>
-</Popover>;
-```
-
-### Date Range Picker
-
-```tsx
-<Popover>
-  <PopoverTrigger asChild>
-    <Button variant="outline">
-      <Icon symbol="calendar_today" />
-      {range?.from
-        ? range.to
-          ? `${format(range.from, "LLL dd")} - ${format(range.to, "LLL dd, y")}`
-          : format(range.from, "LLL dd, y")
-        : "Pick a date range"}
-    </Button>
-  </PopoverTrigger>
-  <PopoverContent className="w-auto p-0">
-    <Calendar
-      mode="range"
-      selected={range}
-      onSelect={setRange}
-      numberOfMonths={2}
-    />
-  </PopoverContent>
-</Popover>
-```
-
-### Fecha de Nacimiento
-
-```tsx
-const currentYear = new Date().getFullYear();
-
-<Calendar
-  mode="single"
-  captionLayout="dropdown"
-  fromYear={1950}
-  toYear={currentYear - 18}
-  defaultMonth={new Date(2000, 0)}
-  selected={birthdate}
-  onSelect={setBirthdate}
-/>;
-```
-
-### Reserva de Hotel
-
-```tsx
-<Calendar
-  mode="range"
-  selected={reservation}
-  onSelect={setReservation}
-  disabled={[
-    // Fechas ya reservadas
-    { from: new Date(2025, 6, 10), to: new Date(2025, 6, 15) },
-    { from: new Date(2025, 6, 20), to: new Date(2025, 6, 25) },
-    // No permitir pasado
-    { before: new Date() },
-  ]}
-  numberOfMonths={2}
-  className="rounded-md border"
-/>
-```
-
-### Calendario de Disponibilidad (Solo Vista)
-
-```tsx
-const bookedDates = [
-  new Date(2025, 6, 10),
-  new Date(2025, 6, 15),
-  new Date(2025, 6, 20),
-];
-
-<Calendar
-  mode="default"
-  modifiers={{
-    booked: bookedDates,
-  }}
-  modifiersClassNames={{
-    booked: "bg-destructive/10 text-destructive",
-  }}
-  className="rounded-md border"
-/>;
-```
-
-### Filtro de Reportes
-
-```tsx
-import { startOfMonth, endOfMonth } from "date-fns";
-
-function ReportFilter() {
-  const [range, setRange] = useState<DateRange>({
-    from: startOfMonth(new Date()),
-    to: endOfMonth(new Date()),
-  });
-
-  return (
-    <div className="space-y-4">
-      <Calendar
-        mode="range"
-        selected={range}
-        onSelect={setRange}
-        numberOfMonths={2}
-        className="rounded-md border"
-      />
-      <Button onClick={() => fetchReport(range)}>Generate Report</Button>
-    </div>
-  );
-}
-```
-
-## Mejores Prácticas
-
-### Usa defaultMonth para Rangos
-
-```tsx
-{
-  /* ✅ Correcto - Muestra el mes de inicio del rango */
-}
-<Calendar
-  mode="range"
-  defaultMonth={range?.from}
-  selected={range}
-  onSelect={setRange}
-/>;
-
-{
-  /* ❌ Incorrecto - Puede mostrar mes actual sin datos */
-}
-<Calendar mode="range" selected={range} onSelect={setRange} />;
-```
-
-### Usa numberOfMonths con Rangos Largos
-
-```tsx
-{
-  /* ✅ Correcto - 2 meses para rangos */
-}
-<Calendar
-  mode="range"
-  numberOfMonths={2}
-  selected={range}
-  onSelect={setRange}
-/>;
-
-{
-  /* ⚠️ Aceptable - 1 mes para rangos cortos */
-}
-<Calendar mode="range" selected={range} onSelect={setRange} />;
-```
-
-### Usa captionLayout="dropdown" para Fechas Lejanas
-
-```tsx
-{
-  /* ✅ Correcto - Fecha de nacimiento con dropdowns */
-}
-<Calendar
-  mode="single"
-  captionLayout="dropdown"
-  fromYear={1950}
-  toYear={2010}
-  defaultMonth={new Date(1990, 0)}
-/>;
-
-{
-  /* ❌ Incorrecto - Navegación con flechas para 30+ años */
-}
-<Calendar mode="single" captionLayout="label" fromYear={1950} />;
-```
-
-### Deshabilita Pasado para Reservas
-
-```tsx
-{
-  /* ✅ Correcto - Solo futuro */
-}
-<Calendar
-  mode="range"
-  disabled={{ before: new Date() }}
-  selected={range}
-  onSelect={setRange}
-/>;
-```
-
-### Valida Rangos en onSelect
-
-```tsx
-{
-  /* ✅ Correcto - Valida antes de guardar */
-}
-const handleSelect = (selectedRange: DateRange | undefined) => {
-  if (!selectedRange?.from || !selectedRange?.to) {
-    setRange(selectedRange);
-    return;
-  }
-
-  const daysDiff = differenceInDays(selectedRange.to, selectedRange.from);
-
-  if (daysDiff > MAX_DAYS) {
-    toast.error(`Maximum range is ${MAX_DAYS} days`);
-    return;
-  }
-
-  setRange(selectedRange);
-};
-
-{
-  /* ❌ Incorrecto - Sin validación */
-}
-<Calendar mode="range" selected={range} onSelect={setRange} />;
-```
-
-### Usa initialFocus en Popovers
-
-```tsx
-{
-  /* ✅ Correcto - Focus automático al abrir */
-}
-<PopoverContent>
-  <Calendar mode="single" selected={date} onSelect={setDate} initialFocus />
-</PopoverContent>;
-
-{
-  /* ❌ Incorrecto - Sin initialFocus */
-}
-<PopoverContent>
-  <Calendar mode="single" selected={date} onSelect={setDate} />
-</PopoverContent>;
-```
-
-### Timezone para Aplicaciones Globales
-
-```tsx
-{
-  /* ✅ Correcto - Timezone explícito */
-}
-<Calendar
-  mode="single"
-  timeZone="America/New_York"
-  selected={date}
-  onSelect={setDate}
-/>;
-
-{
-  /* ⚠️ Cuidado - Usa timezone del navegador por defecto */
-}
-<Calendar mode="single" selected={date} onSelect={setDate} />;
-```
-
-## Notas de Implementación
-
-- **Basado en `react-day-picker` v9+**: Librería madura y accesible
-- **Wrapper con mejoras**: Agrega variantes de botones, RTL support, integración con Card/Popover
-- **CSS Variables**: Usa `--cell-size` para tamaño de celdas (default: `--spacing(8)` = 32px)
-- **Auto-transparencia**: Background transparente dentro de `[data-slot=card-content]` y `[data-slot=popover-content]`
-- **RTL Support**: Rotación automática de chevrons con `rtl:**:[.rdp-button_next>svg]:rotate-180`
-- **Grid Layout**: Usa CSS Grid internamente para layout del calendario
-- **Focus Management**: CalendarDayButton usa `useEffect` para foco automático en día con modifier `focused`
-- **Data Attributes**: Días usan `data-selected-single`, `data-range-start`, `data-range-end`, `data-range-middle` para estilos específicos
-- **Aspect Ratio**: Días tienen `aspect-square` para celdas perfectamente cuadradas
-- **Button Variants**: Navegación usa `buttonVariants()` de Button component para consistencia visual
-- **Dropdown con Overlay**: Dropdowns usan select nativo con overlay invisible (`opacity-0`) para accesibilidad
-- **Responsive**: Múltiples meses cambian de `flex-row` a `flex-col` en móviles con `md:flex-row`
-
-## Accesibilidad
-
-### Navegación por Teclado
-
-- ✅ **Arrow keys**: Navega entre días (↑ ↓ ← →)
-- ✅ **PageUp/PageDown**: Navega entre meses
-- ✅ **Home/End**: Primer/último día del mes
-- ✅ **Enter/Space**: Selecciona día enfocado
-- ✅ **Tab**: Navega entre controles (botones prev/next, dropdowns)
-
-### ARIA Labels
-
-```tsx
-{
-  /* ✅ Automático - react-day-picker agrega ARIA */
-}
-<Calendar mode="single" selected={date} onSelect={setDate} />;
-```
-
-**Atributos automáticos**:
-
-- `role="application"` en contenedor
-- `aria-label` en días (ej: "Monday, October 31, 2025")
-- `aria-selected="true"` en días seleccionados
-- `aria-disabled="true"` en días deshabilitados
-- `aria-current="date"` en día actual
-
-### Focus Visible
-
-Días enfocados muestran ring azul con `group-data-[focused=true]/day:ring-ring/50`.
-
-### Screen Readers
-
-- Anuncia mes y año actual
-- Anuncia días seleccionados
-- Anuncia rangos ("from ... to ...")
-- Anuncia días deshabilitados
-
-### Labels Personalizadas
-
-```tsx
-<Calendar
-  mode="single"
-  aria-label="Select appointment date"
-  selected={date}
-  onSelect={setDate}
-/>
-```
-
-## Troubleshooting
-
-### Calendario No Se Ve (Invisible)
-
-**Problema**: El calendario se renderiza pero no es visible.
-
-**Solución**:
-
-```tsx
-// ❌ Problema - Falta CSS de react-day-picker
-// Asegúrate de importar el CSS global
-
-// ✅ Solución - Importa en tu layout/app
-import "react-day-picker/style.css";
-```
-
-### Meses Múltiples No Se Alinean
-
-**Problema**: Con `numberOfMonths={2}`, los meses se apilan en desktop.
-
-**Solución**:
-
-```tsx
-// ✅ El componente usa md:flex-row automáticamente
-// Si sigue apilando, verifica que Tailwind tenga @media queries compiladas
-<Calendar numberOfMonths={2} className="rounded-md border" />
-```
-
-### Dropdowns No Funcionan
-
-**Problema**: Los dropdowns de mes/año no responden.
-
-**Solución**:
-
-```tsx
-// ❌ Problema - Sin fromYear/toYear
-<Calendar captionLayout="dropdown" />
-
-// ✅ Solución - Define rango de años
-<Calendar
-  captionLayout="dropdown"
-  fromYear={2020}
-  toYear={2030}
-/>
-```
-
-### Rango No Se Completa
-
-**Problema**: Al seleccionar segunda fecha, el rango se reinicia.
-
-**Solución**:
-
-```tsx
-// ✅ Verifica que el tipo sea DateRange
-const [range, setRange] = useState<DateRange | undefined>();
-
-// ✅ Usa defaultMonth para estabilidad
-<Calendar
-  mode="range"
-  defaultMonth={range?.from}
-  selected={range}
-  onSelect={setRange}
-/>;
-```
-
-### Días Deshabilitados Siguen Seleccionables
-
-**Problema**: Días con `disabled` aún se pueden clickear.
-
-**Solución**:
-
-```tsx
-// ❌ Problema - Sintaxis incorrecta
-<Calendar disabled={[new Date("2025-10-15")]} />  // String no funciona
-
-// ✅ Solución - Objetos Date válidos
-<Calendar disabled={[new Date(2025, 9, 15)]} />  // Mes 9 = Octubre
-```
-
-### Timezone Incorrecto
-
-**Problema**: Fechas se guardan en timezone diferente.
-
-**Solución**:
-
-```tsx
-// ✅ Especifica timezone explícito
-<Calendar mode="single" timeZone="UTC" selected={date} onSelect={setDate} />;
-
-// O convierte al guardar
-const handleSelect = (selectedDate: Date | undefined) => {
-  if (selectedDate) {
-    const utcDate = new Date(selectedDate.toISOString());
-    setDate(utcDate);
-  }
-};
-```
-
-### Popover Se Cierra al Seleccionar
-
-**Problema**: El popover se cierra inmediatamente al clickear un día.
-
-**Solución**:
-
-```tsx
-// ✅ Cierra manualmente después de selección
-function DatePickerWithControl() {
-  const [open, setOpen] = useState(false);
-  const [date, setDate] = useState<Date>();
-
-  return (
-    <Popover open={open} onOpenChange={setOpen}>
-      <PopoverTrigger asChild>
-        <Button variant="outline">
-          <Icon symbol="calendar_today" />
-          {date ? format(date, "PPP") : "Pick a date"}
-        </Button>
-      </PopoverTrigger>
-      <PopoverContent className="w-auto p-0">
-        <Calendar
-          mode="single"
-          selected={date}
-          onSelect={(newDate) => {
-            setDate(newDate);
-            setOpen(false); // Cierra manualmente
-          }}
-          initialFocus
-        />
-      </PopoverContent>
-    </Popover>
-  );
-}
-```
-
-## Referencias
-
-- **react-day-picker**: https://react-day-picker.js.org
-- **date-fns** (formateo): https://date-fns.org
-- **Radix UI Calendar** (inspiración): https://www.radix-ui.com/primitives/docs/components/calendar
-- **shadcn/ui Calendar**: https://ui.shadcn.com/docs/components/calendar
-- **ARIA Calendar Pattern**: https://www.w3.org/WAI/ARIA/apg/patterns/calendar/
+# Calendar
+
+Calendario interactivo altamente personalizable basado en `react-day-picker` para selección de fechas individuales, múltiples o rangos. Soporta navegación con dropdowns, múltiples meses, números de semana, timezones y fechas deshabilitadas.
+
+## Características Principales
+
+- **4 modos de selección**: Single (fecha única), Multiple (múltiples fechas), Range (rango de fechas), Default (sin selección)
+- **Navegación flexible**: Botones tradicionales o dropdowns mes/año para saltos rápidos
+- **Múltiples meses**: Visualización simultánea de 2+ meses para rangos amplios
+- **Números de semana**: Muestra semana del año (ISO 8601)
+- **Fechas deshabilitadas**: Bloquea fechas específicas o rangos completos
+- **Timezone awareness**: Soporte completo para zonas horarias
+- **Variantes de botones**: Personaliza navegación (ghost, outline, secondary, etc.)
+- **RTL support**: Rotación automática de chevrons en idiomas right-to-left
+- **Integración con Card/Popover**: Background transparente automático
+- **Accesibilidad**: Navegación por teclado, ARIA labels, focus visible
+
+## Importación
+
+```tsx
+import { Calendar } from "@adamosuiteservices/ui/calendar";
+import type { DateRange } from "react-day-picker";
+```
+
+```tsx
+import { Calendar } from "@adamosuiteservices/ui/calendar";
+import type { DateRange } from "react-day-picker";
+```
+
+## Uso Básico
+
+### Selección de Fecha Única
+
+El modo más común para seleccionar una sola fecha.
+
+```tsx
+import { useState } from "react";
+import { Calendar } from "@adamosuiteservices/ui/calendar";
+
+function DatePicker() {
+  const [date, setDate] = useState<Date | undefined>(new Date());
+
+  return (
+    <Calendar
+      mode="single"
+      selected={date}
+      onSelect={setDate}
+      className="rounded-md border"
+    />
+  );
+}
+```
+
+### Navegación con Dropdowns
+
+Para saltar rápidamente entre meses y años.
+
+```tsx
+const [date, setDate] = useState<Date | undefined>(new Date(2025, 5, 12));
+
+<Calendar
+  mode="single"
+  selected={date}
+  onSelect={setDate}
+  captionLayout="dropdown"
+  className="rounded-md border"
+/>;
+```
+
+**Ventaja**: Permite seleccionar fechas lejanas sin hacer múltiples clics en flechas.
+
+### Rango de Fechas
+
+Para seleccionar periodo entre dos fechas (ej: reservas de hotel).
+
+```tsx
+import type { DateRange } from "react-day-picker";
+
+function RangePicker() {
+  const [range, setRange] = useState<DateRange | undefined>({
+    from: new Date(2025, 5, 12),
+    to: new Date(2025, 5, 18),
+  });
+
+  return (
+    <Calendar
+      mode="range"
+      defaultMonth={range?.from}
+      selected={range}
+      onSelect={setRange}
+      className="rounded-md border"
+    />
+  );
+}
+```
+
+### Múltiples Meses
+
+Ideal para rangos largos o visualización amplia.
+
+```tsx
+const [range, setRange] = useState<DateRange | undefined>({
+  from: new Date(2025, 5, 12),
+  to: new Date(2025, 6, 15),
+});
+
+<Calendar
+  mode="range"
+  defaultMonth={range?.from}
+  selected={range}
+  onSelect={setRange}
+  numberOfMonths={2}
+  className="rounded-md border"
+/>;
+```
+
+**Nota**: En pantallas pequeñas, los meses se apilan verticalmente automáticamente.
+
+### Selección Múltiple
+
+Para seleccionar fechas no consecutivas (ej: días de entrenamiento).
+
+```tsx
+const [dates, setDates] = useState<Date[] | undefined>([
+  new Date(2025, 5, 12),
+  new Date(2025, 5, 15),
+  new Date(2025, 5, 20),
+]);
+
+<Calendar
+  mode="multiple"
+  selected={dates}
+  onSelect={setDates}
+  className="rounded-md border"
+/>;
+```
+
+## Componentes
+
+### Calendar
+
+El componente principal que renderiza el calendario completo.
+
+#### Props
+
+| Prop              | Tipo                                                             | Default       | Descripción                                 |
+| ----------------- | ---------------------------------------------------------------- | ------------- | ------------------------------------------- |
+| `mode`            | `"single" \| "multiple" \| "range" \| "default"`                 | `"default"`   | Modo de selección de fechas                 |
+| `selected`        | `Date \| Date[] \| DateRange \| undefined`                       | `undefined`   | Fecha(s) seleccionada(s) según modo         |
+| `onSelect`        | `(date) => void`                                                 | -             | Callback cuando cambia la selección         |
+| `defaultMonth`    | `Date`                                                           | Mes actual    | Mes inicial a mostrar                       |
+| `numberOfMonths`  | `number`                                                         | `1`           | Cantidad de meses a mostrar simultáneamente |
+| `captionLayout`   | `"label" \| "dropdown" \| "dropdown-months" \| "dropdown-years"` | `"label"`     | Tipo de navegación del header               |
+| `showOutsideDays` | `boolean`                                                        | `true`        | Mostrar días de meses adyacentes            |
+| `showWeekNumber`  | `boolean`                                                        | `false`       | Mostrar números de semana                   |
+| `disabled`        | `Date \| Date[] \| DateRange \| ((date: Date) => boolean)`       | -             | Fechas deshabilitadas                       |
+| `hidden`          | `Date \| Date[] \| DateRange \| ((date: Date) => boolean)`       | -             | Fechas ocultas completamente                |
+| `fromDate`        | `Date`                                                           | -             | Fecha mínima seleccionable                  |
+| `toDate`          | `Date`                                                           | -             | Fecha máxima seleccionable                  |
+| `fromMonth`       | `Date`                                                           | -             | Mes mínimo navegable                        |
+| `toMonth`         | `Date`                                                           | -             | Mes máximo navegable                        |
+| `fromYear`        | `number`                                                         | -             | Año mínimo navegable                        |
+| `toYear`          | `number`                                                         | -             | Año máximo navegable                        |
+| `timeZone`        | `string`                                                         | Sistema       | Zona horaria (ej: `"America/New_York"`)     |
+| `locale`          | `Locale`                                                         | Sistema       | Objeto Locale de `date-fns` para i18n       |
+| `weekStartsOn`    | `0 \| 1 \| 2 \| 3 \| 4 \| 5 \| 6`                                | `0`           | Día inicio de semana (0=Domingo, 1=Lunes)   |
+| `buttonVariant`   | `ButtonProps["variant"]`                                         | `"secondary"` | Variante para botones de navegación         |
+| `className`       | `string`                                                         | -             | Clases CSS adicionales para el contenedor   |
+| `classNames`      | `ClassNames`                                                     | -             | Objeto con clases para elementos internos   |
+| `components`      | `Components`                                                     | -             | Componentes custom para override            |
+| `formatters`      | `Formatters`                                                     | -             | Funciones de formateo custom                |
+
+### CalendarDayButton
+
+Componente interno que renderiza cada día del calendario. Raramente se usa directamente.
+
+## Modos de Selección
+
+### Mode: "single"
+
+Un solo día seleccionado a la vez.
+
+```tsx
+// Tipo de selected
+selected: Date | undefined
+
+// Callback
+onSelect: (date: Date | undefined) => void
+```
+
+**Uso común**: Fecha de nacimiento, vencimiento de documento, fecha límite.
+
+### Mode: "multiple"
+
+Array de días no consecutivos.
+
+```tsx
+// Tipo de selected
+selected: Date[] | undefined
+
+// Callback
+onSelect: (dates: Date[] | undefined) => void
+```
+
+**Uso común**: Días de entrenamiento, fechas de eventos recurrentes, días festivos.
+
+### Mode: "range"
+
+Rango continuo entre dos fechas.
+
+```tsx
+import type { DateRange } from "react-day-picker";
+
+// Tipo de selected
+selected: DateRange | undefined  // { from?: Date; to?: Date }
+
+// Callback
+onSelect: (range: DateRange | undefined) => void
+```
+
+**Uso común**: Reservas de hotel, filtros de reportes, periodos de vacaciones.
+
+### Mode: "default"
+
+Sin selección (solo visualización).
+
+```tsx
+<Calendar mode="default" />
+```
+
+**Uso común**: Mostrar calendario estático, vista de disponibilidad sin interacción.
+
+## Captionlayout (Navegación)
+
+### "label" (Default)
+
+Navegación tradicional con flechas.
+
+```tsx
+<Calendar captionLayout="label" />
+```
+
+**Ventaja**: UI simple, menos espacio vertical.
+
+### "dropdown"
+
+Dropdowns para mes Y año.
+
+```tsx
+<Calendar captionLayout="dropdown" fromYear={2020} toYear={2030} />
+```
+
+**Ventaja**: Saltos rápidos a fechas lejanas. Ideal para fecha de nacimiento.
+
+### "dropdown-months"
+
+Solo dropdown de meses, año con flechas.
+
+```tsx
+<Calendar captionLayout="dropdown-months" />
+```
+
+### "dropdown-years"
+
+Solo dropdown de años, mes con flechas.
+
+```tsx
+<Calendar captionLayout="dropdown-years" />
+```
+
+## Patrones Avanzados
+
+### Fechas Deshabilitadas (Múltiples Formas)
+
+#### Fechas Específicas
+
+```tsx
+const disabledDays = [
+  new Date(2025, 9, 15),
+  new Date(2025, 9, 16),
+  new Date(2025, 9, 17),
+];
+
+<Calendar
+  mode="single"
+  disabled={disabledDays}
+  selected={date}
+  onSelect={setDate}
+/>;
+```
+
+#### Rangos de Fechas
+
+```tsx
+const disabledRanges = [
+  { from: new Date(2025, 9, 20), to: new Date(2025, 9, 25) },
+  { from: new Date(2025, 10, 1), to: new Date(2025, 10, 7) },
+];
+
+<Calendar disabled={disabledRanges} />;
+```
+
+#### Función Dinámica
+
+```tsx
+// Deshabilitar fines de semana
+const isWeekend = (date: Date) => {
+  const day = date.getDay();
+  return day === 0 || day === 6;
+};
+
+<Calendar disabled={isWeekend} />;
+```
+
+#### Deshabilitar Pasado
+
+```tsx
+// Solo fechas futuras
+<Calendar
+  disabled={{ before: new Date() }}
+  mode="single"
+  selected={date}
+  onSelect={setDate}
+/>
+```
+
+#### Deshabilitar Futuro
+
+```tsx
+// Solo fechas pasadas
+<Calendar
+  disabled={{ after: new Date() }}
+  mode="single"
+  selected={date}
+  onSelect={setDate}
+/>
+```
+
+### Rango de Fechas Permitidas
+
+#### Con fromDate y toDate
+
+```tsx
+// Solo permitir 30 días hacia adelante
+<Calendar
+  mode="single"
+  fromDate={new Date()}
+  toDate={new Date(Date.now() + 30 * 24 * 60 * 60 * 1000)}
+  selected={date}
+  onSelect={setDate}
+/>
+```
+
+#### Con fromYear y toYear
+
+```tsx
+// Para fecha de nacimiento (mayores de 18)
+const currentYear = new Date().getFullYear();
+
+<Calendar
+  mode="single"
+  captionLayout="dropdown"
+  fromYear={1950}
+  toYear={currentYear - 18}
+  defaultMonth={new Date(2000, 0)}
+  selected={birthdate}
+  onSelect={setBirthdate}
+/>;
+```
+
+### Calendario en Card
+
+Integración perfecta con componente Card (background transparente automático).
+
+```tsx
+import {
+  Card,
+  CardContent,
+  CardDescription,
+  CardHeader,
+  CardTitle,
+} from "@adamosuiteservices/ui/card";
+
+<Card className="w-fit">
+  <CardHeader>
+    <CardTitle>Select Date</CardTitle>
+    <CardDescription>Choose a date for your appointment</CardDescription>
+  </CardHeader>
+  <CardContent>
+    <Calendar
+      mode="single"
+      selected={date}
+      onSelect={setDate}
+      captionLayout="dropdown"
+    />
+  </CardContent>
+</Card>;
+```
+
+### Calendario en Popover
+
+Para date pickers compactos.
+
+```tsx
+import {
+  Popover,
+  PopoverContent,
+  PopoverTrigger,
+} from "@adamosuiteservices/ui/popover";
+import { Button } from "@adamosuiteservices/ui/button";
+import { Icon } from "@adamosuiteservices/ui/icon";
+import { format } from "date-fns";
+
+function DatePickerPopover() {
+  const [date, setDate] = useState<Date>();
+
+  return (
+    <Popover>
+      <PopoverTrigger asChild>
+        <Button variant="outline">
+          <Icon symbol="calendar_today" />
+          {date ? format(date, "PPP") : "Pick a date"}
+        </Button>
+      </PopoverTrigger>
+      <PopoverContent className="w-auto p-0">
+        <Calendar
+          mode="single"
+          selected={date}
+          onSelect={setDate}
+          initialFocus
+        />
+      </PopoverContent>
+    </Popover>
+  );
+}
+```
+
+**Nota**: El background se vuelve transparente automáticamente dentro de PopoverContent.
+
+### Con Timezone
+
+```tsx
+import { useState } from "react";
+
+function TimezoneCalendar() {
+  const [date, setDate] = useState<Date>();
+  const [timeZone] = useState(Intl.DateTimeFormat().resolvedOptions().timeZone);
+
+  return (
+    <div className="space-y-2">
+      <p className="text-sm text-muted-foreground">Timezone: {timeZone}</p>
+      <Calendar
+        mode="single"
+        selected={date}
+        onSelect={setDate}
+        timeZone={timeZone}
+        className="rounded-md border"
+      />
+    </div>
+  );
+}
+```
+
+### Sin Días Externos (Outside Days)
+
+Oculta días de meses adyacentes para UI más limpia.
+
+```tsx
+<Calendar
+  mode="single"
+  selected={date}
+  onSelect={setDate}
+  showOutsideDays={false}
+  className="rounded-md border"
+/>
+```
+
+### Con Números de Semana
+
+Útil para reportes empresariales o planificación semanal.
+
+```tsx
+<Calendar
+  mode="single"
+  selected={date}
+  onSelect={setDate}
+  showWeekNumber
+  className="rounded-md border"
+/>
+```
+
+**Formato**: Números de semana según ISO 8601 (1-53).
+
+### Variantes de Botones de Navegación
+
+Personaliza la apariencia de los botones prev/next.
+
+```tsx
+<div className="space-y-4">
+  {/* Ghost (default) */}
+  <Calendar mode="single" buttonVariant="ghost" className="rounded-md border" />
+
+  {/* Outline */}
+  <Calendar
+    mode="single"
+    buttonVariant="outline"
+    className="rounded-md border"
+  />
+
+  {/* Secondary */}
+  <Calendar
+    mode="single"
+    buttonVariant="secondary"
+    className="rounded-md border"
+  />
+</div>
+```
+
+### Rango Preseleccionado (Últimos 7 Días)
+
+```tsx
+import { subDays } from "date-fns";
+
+function Last7DaysRange() {
+  const [range, setRange] = useState<DateRange>({
+    from: subDays(new Date(), 7),
+    to: new Date(),
+  });
+
+  return (
+    <Calendar
+      mode="range"
+      selected={range}
+      onSelect={setRange}
+      numberOfMonths={2}
+      className="rounded-md border"
+    />
+  );
+}
+```
+
+### Validación de Rango Máximo
+
+Limita la cantidad de días seleccionables en un rango.
+
+```tsx
+import { differenceInDays } from "date-fns";
+
+function MaxRangeCalendar() {
+  const [range, setRange] = useState<DateRange>();
+  const MAX_DAYS = 14;
+
+  const handleSelect = (selectedRange: DateRange | undefined) => {
+    if (!selectedRange?.from || !selectedRange?.to) {
+      setRange(selectedRange);
+      return;
+    }
+
+    const daysDiff = differenceInDays(selectedRange.to, selectedRange.from);
+
+    if (daysDiff > MAX_DAYS) {
+      alert(`Maximum range is ${MAX_DAYS} days`);
+      return;
+    }
+
+    setRange(selectedRange);
+  };
+
+  return (
+    <div className="space-y-2">
+      <p className="text-sm text-muted-foreground">
+        Maximum range: {MAX_DAYS} days
+      </p>
+      <Calendar
+        mode="range"
+        selected={range}
+        onSelect={handleSelect}
+        numberOfMonths={2}
+        className="rounded-md border"
+      />
+    </div>
+  );
+}
+```
+
+### Calendario con Presets de Rango
+
+Botones rápidos para rangos comunes.
+
+```tsx
+import {
+  startOfMonth,
+  endOfMonth,
+  subMonths,
+  startOfWeek,
+  endOfWeek,
+} from "date-fns";
+import { Button } from "@adamosuiteservices/ui/button";
+
+function CalendarWithPresets() {
+  const [range, setRange] = useState<DateRange>();
+
+  const presets = [
+    {
+      label: "Today",
+      range: { from: new Date(), to: new Date() },
+    },
+    {
+      label: "Last 7 days",
+      range: { from: subDays(new Date(), 7), to: new Date() },
+    },
+    {
+      label: "This week",
+      range: { from: startOfWeek(new Date()), to: endOfWeek(new Date()) },
+    },
+    {
+      label: "This month",
+      range: { from: startOfMonth(new Date()), to: endOfMonth(new Date()) },
+    },
+    {
+      label: "Last month",
+      range: {
+        from: startOfMonth(subMonths(new Date(), 1)),
+        to: endOfMonth(subMonths(new Date(), 1)),
+      },
+    },
+  ];
+
+  return (
+    <div className="flex gap-4">
+      <div className="flex flex-col gap-2">
+        {presets.map((preset) => (
+          <Button
+            key={preset.label}
+            variant="outline"
+            onClick={() => setRange(preset.range)}
+            className="justify-start"
+          >
+            {preset.label}
+          </Button>
+        ))}
+      </div>
+      <Calendar
+        mode="range"
+        selected={range}
+        onSelect={setRange}
+        numberOfMonths={2}
+        className="rounded-md border"
+      />
+    </div>
+  );
+}
+```
+
+### Formateo Custom de Meses
+
+```tsx
+<Calendar
+  mode="single"
+  captionLayout="dropdown"
+  formatters={{
+    formatMonthDropdown: (date) =>
+      date.toLocaleString("es-ES", { month: "long" }),
+  }}
+/>
+```
+
+### Internacionalización (i18n)
+
+```tsx
+import { es } from "date-fns/locale";
+
+<Calendar
+  mode="single"
+  locale={es}
+  weekStartsOn={1} // Lunes
+  selected={date}
+  onSelect={setDate}
+/>;
+```
+
+## Casos de Uso Comunes
+
+### Date Picker Simple
+
+```tsx
+import {
+  Popover,
+  PopoverContent,
+  PopoverTrigger,
+} from "@adamosuiteservices/ui/popover";
+import { Button } from "@adamosuiteservices/ui/button";
+import { Icon } from "@adamosuiteservices/ui/icon";
+import { format } from "date-fns";
+
+<Popover>
+  <PopoverTrigger asChild>
+    <Button variant="outline">
+      <Icon symbol="calendar_today" />
+      {date ? format(date, "PPP") : "Pick a date"}
+    </Button>
+  </PopoverTrigger>
+  <PopoverContent className="w-auto p-0">
+    <Calendar mode="single" selected={date} onSelect={setDate} />
+  </PopoverContent>
+</Popover>;
+```
+
+### Date Range Picker
+
+```tsx
+<Popover>
+  <PopoverTrigger asChild>
+    <Button variant="outline">
+      <Icon symbol="calendar_today" />
+      {range?.from
+        ? range.to
+          ? `${format(range.from, "LLL dd")} - ${format(range.to, "LLL dd, y")}`
+          : format(range.from, "LLL dd, y")
+        : "Pick a date range"}
+    </Button>
+  </PopoverTrigger>
+  <PopoverContent className="w-auto p-0">
+    <Calendar
+      mode="range"
+      selected={range}
+      onSelect={setRange}
+      numberOfMonths={2}
+    />
+  </PopoverContent>
+</Popover>
+```
+
+### Fecha de Nacimiento
+
+```tsx
+const currentYear = new Date().getFullYear();
+
+<Calendar
+  mode="single"
+  captionLayout="dropdown"
+  fromYear={1950}
+  toYear={currentYear - 18}
+  defaultMonth={new Date(2000, 0)}
+  selected={birthdate}
+  onSelect={setBirthdate}
+/>;
+```
+
+### Reserva de Hotel
+
+```tsx
+<Calendar
+  mode="range"
+  selected={reservation}
+  onSelect={setReservation}
+  disabled={[
+    // Fechas ya reservadas
+    { from: new Date(2025, 6, 10), to: new Date(2025, 6, 15) },
+    { from: new Date(2025, 6, 20), to: new Date(2025, 6, 25) },
+    // No permitir pasado
+    { before: new Date() },
+  ]}
+  numberOfMonths={2}
+  className="rounded-md border"
+/>
+```
+
+### Calendario de Disponibilidad (Solo Vista)
+
+```tsx
+const bookedDates = [
+  new Date(2025, 6, 10),
+  new Date(2025, 6, 15),
+  new Date(2025, 6, 20),
+];
+
+<Calendar
+  mode="default"
+  modifiers={{
+    booked: bookedDates,
+  }}
+  modifiersClassNames={{
+    booked: "bg-destructive/10 text-destructive",
+  }}
+  className="rounded-md border"
+/>;
+```
+
+### Filtro de Reportes
+
+```tsx
+import { startOfMonth, endOfMonth } from "date-fns";
+
+function ReportFilter() {
+  const [range, setRange] = useState<DateRange>({
+    from: startOfMonth(new Date()),
+    to: endOfMonth(new Date()),
+  });
+
+  return (
+    <div className="space-y-4">
+      <Calendar
+        mode="range"
+        selected={range}
+        onSelect={setRange}
+        numberOfMonths={2}
+        className="rounded-md border"
+      />
+      <Button onClick={() => fetchReport(range)}>Generate Report</Button>
+    </div>
+  );
+}
+```
+
+## Mejores Prácticas
+
+### Usa defaultMonth para Rangos
+
+```tsx
+{
+  /* ✅ Correcto - Muestra el mes de inicio del rango */
+}
+<Calendar
+  mode="range"
+  defaultMonth={range?.from}
+  selected={range}
+  onSelect={setRange}
+/>;
+
+{
+  /* ❌ Incorrecto - Puede mostrar mes actual sin datos */
+}
+<Calendar mode="range" selected={range} onSelect={setRange} />;
+```
+
+### Usa numberOfMonths con Rangos Largos
+
+```tsx
+{
+  /* ✅ Correcto - 2 meses para rangos */
+}
+<Calendar
+  mode="range"
+  numberOfMonths={2}
+  selected={range}
+  onSelect={setRange}
+/>;
+
+{
+  /* ⚠️ Aceptable - 1 mes para rangos cortos */
+}
+<Calendar mode="range" selected={range} onSelect={setRange} />;
+```
+
+### Usa captionLayout="dropdown" para Fechas Lejanas
+
+```tsx
+{
+  /* ✅ Correcto - Fecha de nacimiento con dropdowns */
+}
+<Calendar
+  mode="single"
+  captionLayout="dropdown"
+  fromYear={1950}
+  toYear={2010}
+  defaultMonth={new Date(1990, 0)}
+/>;
+
+{
+  /* ❌ Incorrecto - Navegación con flechas para 30+ años */
+}
+<Calendar mode="single" captionLayout="label" fromYear={1950} />;
+```
+
+### Deshabilita Pasado para Reservas
+
+```tsx
+{
+  /* ✅ Correcto - Solo futuro */
+}
+<Calendar
+  mode="range"
+  disabled={{ before: new Date() }}
+  selected={range}
+  onSelect={setRange}
+/>;
+```
+
+### Valida Rangos en onSelect
+
+```tsx
+{
+  /* ✅ Correcto - Valida antes de guardar */
+}
+const handleSelect = (selectedRange: DateRange | undefined) => {
+  if (!selectedRange?.from || !selectedRange?.to) {
+    setRange(selectedRange);
+    return;
+  }
+
+  const daysDiff = differenceInDays(selectedRange.to, selectedRange.from);
+
+  if (daysDiff > MAX_DAYS) {
+    toast.error(`Maximum range is ${MAX_DAYS} days`);
+    return;
+  }
+
+  setRange(selectedRange);
+};
+
+{
+  /* ❌ Incorrecto - Sin validación */
+}
+<Calendar mode="range" selected={range} onSelect={setRange} />;
+```
+
+### Usa initialFocus en Popovers
+
+```tsx
+{
+  /* ✅ Correcto - Focus automático al abrir */
+}
+<PopoverContent>
+  <Calendar mode="single" selected={date} onSelect={setDate} initialFocus />
+</PopoverContent>;
+
+{
+  /* ❌ Incorrecto - Sin initialFocus */
+}
+<PopoverContent>
+  <Calendar mode="single" selected={date} onSelect={setDate} />
+</PopoverContent>;
+```
+
+### Timezone para Aplicaciones Globales
+
+```tsx
+{
+  /* ✅ Correcto - Timezone explícito */
+}
+<Calendar
+  mode="single"
+  timeZone="America/New_York"
+  selected={date}
+  onSelect={setDate}
+/>;
+
+{
+  /* ⚠️ Cuidado - Usa timezone del navegador por defecto */
+}
+<Calendar mode="single" selected={date} onSelect={setDate} />;
+```
+
+## Notas de Implementación
+
+- **Basado en `react-day-picker` v9+**: Librería madura y accesible
+- **Wrapper con mejoras**: Agrega variantes de botones, RTL support, integración con Card/Popover
+- **CSS Variables**: Usa `--cell-size` para tamaño de celdas (default: `--spacing(8)` = 32px)
+- **Auto-transparencia**: Background transparente dentro de `[data-slot=card-content]` y `[data-slot=popover-content]`
+- **RTL Support**: Rotación automática de chevrons con `rtl:**:[.rdp-button_next>svg]:rotate-180`
+- **Grid Layout**: Usa CSS Grid internamente para layout del calendario
+- **Focus Management**: CalendarDayButton usa `useEffect` para foco automático en día con modifier `focused`
+- **Data Attributes**: Días usan `data-selected-single`, `data-range-start`, `data-range-end`, `data-range-middle` para estilos específicos
+- **Aspect Ratio**: Días tienen `aspect-square` para celdas perfectamente cuadradas
+- **Button Variants**: Navegación usa `buttonVariants()` de Button component para consistencia visual
+- **Dropdown con Overlay**: Dropdowns usan select nativo con overlay invisible (`opacity-0`) para accesibilidad
+- **Responsive**: Múltiples meses cambian de `flex-row` a `flex-col` en móviles con `md:flex-row`
+
+## Accesibilidad
+
+### Navegación por Teclado
+
+- ✅ **Arrow keys**: Navega entre días (↑ ↓ ← →)
+- ✅ **PageUp/PageDown**: Navega entre meses
+- ✅ **Home/End**: Primer/último día del mes
+- ✅ **Enter/Space**: Selecciona día enfocado
+- ✅ **Tab**: Navega entre controles (botones prev/next, dropdowns)
+
+### ARIA Labels
+
+```tsx
+{
+  /* ✅ Automático - react-day-picker agrega ARIA */
+}
+<Calendar mode="single" selected={date} onSelect={setDate} />;
+```
+
+**Atributos automáticos**:
+
+- `role="application"` en contenedor
+- `aria-label` en días (ej: "Monday, October 31, 2025")
+- `aria-selected="true"` en días seleccionados
+- `aria-disabled="true"` en días deshabilitados
+- `aria-current="date"` en día actual
+
+### Focus Visible
+
+Días enfocados muestran ring azul con `group-data-[focused=true]/day:ring-ring/50`.
+
+### Screen Readers
+
+- Anuncia mes y año actual
+- Anuncia días seleccionados
+- Anuncia rangos ("from ... to ...")
+- Anuncia días deshabilitados
+
+### Labels Personalizadas
+
+```tsx
+<Calendar
+  mode="single"
+  aria-label="Select appointment date"
+  selected={date}
+  onSelect={setDate}
+/>
+```
+
+## Troubleshooting
+
+### Calendario No Se Ve (Invisible)
+
+**Problema**: El calendario se renderiza pero no es visible.
+
+**Solución**:
+
+```tsx
+// ❌ Problema - Falta CSS de react-day-picker
+// Asegúrate de importar el CSS global
+
+// ✅ Solución - Importa en tu layout/app
+import "react-day-picker/style.css";
+```
+
+### Meses Múltiples No Se Alinean
+
+**Problema**: Con `numberOfMonths={2}`, los meses se apilan en desktop.
+
+**Solución**:
+
+```tsx
+// ✅ El componente usa md:flex-row automáticamente
+// Si sigue apilando, verifica que Tailwind tenga @media queries compiladas
+<Calendar numberOfMonths={2} className="rounded-md border" />
+```
+
+### Dropdowns No Funcionan
+
+**Problema**: Los dropdowns de mes/año no responden.
+
+**Solución**:
+
+```tsx
+// ❌ Problema - Sin fromYear/toYear
+<Calendar captionLayout="dropdown" />
+
+// ✅ Solución - Define rango de años
+<Calendar
+  captionLayout="dropdown"
+  fromYear={2020}
+  toYear={2030}
+/>
+```
+
+### Rango No Se Completa
+
+**Problema**: Al seleccionar segunda fecha, el rango se reinicia.
+
+**Solución**:
+
+```tsx
+// ✅ Verifica que el tipo sea DateRange
+const [range, setRange] = useState<DateRange | undefined>();
+
+// ✅ Usa defaultMonth para estabilidad
+<Calendar
+  mode="range"
+  defaultMonth={range?.from}
+  selected={range}
+  onSelect={setRange}
+/>;
+```
+
+### Días Deshabilitados Siguen Seleccionables
+
+**Problema**: Días con `disabled` aún se pueden clickear.
+
+**Solución**:
+
+```tsx
+// ❌ Problema - Sintaxis incorrecta
+<Calendar disabled={[new Date("2025-10-15")]} />  // String no funciona
+
+// ✅ Solución - Objetos Date válidos
+<Calendar disabled={[new Date(2025, 9, 15)]} />  // Mes 9 = Octubre
+```
+
+### Timezone Incorrecto
+
+**Problema**: Fechas se guardan en timezone diferente.
+
+**Solución**:
+
+```tsx
+// ✅ Especifica timezone explícito
+<Calendar mode="single" timeZone="UTC" selected={date} onSelect={setDate} />;
+
+// O convierte al guardar
+const handleSelect = (selectedDate: Date | undefined) => {
+  if (selectedDate) {
+    const utcDate = new Date(selectedDate.toISOString());
+    setDate(utcDate);
+  }
+};
+```
+
+### Popover Se Cierra al Seleccionar
+
+**Problema**: El popover se cierra inmediatamente al clickear un día.
+
+**Solución**:
+
+```tsx
+// ✅ Cierra manualmente después de selección
+function DatePickerWithControl() {
+  const [open, setOpen] = useState(false);
+  const [date, setDate] = useState<Date>();
+
+  return (
+    <Popover open={open} onOpenChange={setOpen}>
+      <PopoverTrigger asChild>
+        <Button variant="outline">
+          <Icon symbol="calendar_today" />
+          {date ? format(date, "PPP") : "Pick a date"}
+        </Button>
+      </PopoverTrigger>
+      <PopoverContent className="w-auto p-0">
+        <Calendar
+          mode="single"
+          selected={date}
+          onSelect={(newDate) => {
+            setDate(newDate);
+            setOpen(false); // Cierra manualmente
+          }}
+          initialFocus
+        />
+      </PopoverContent>
+    </Popover>
+  );
+}
+```
+
+## Referencias
+
+- **react-day-picker**: https://react-day-picker.js.org
+- **date-fns** (formateo): https://date-fns.org
+- **Radix UI Calendar** (inspiración): https://www.radix-ui.com/primitives/docs/components/calendar
+- **shadcn/ui Calendar**: https://ui.shadcn.com/docs/components/calendar
+- **ARIA Calendar Pattern**: https://www.w3.org/WAI/ARIA/apg/patterns/calendar/