@neynar/ui 0.3.1 → 0.5.0

package/src/components/ui/calendar.tsx

@@ -1,939 +1,28 @@
+"use client";
+
 import * as React from "react";
 import {
-  ChevronDownIcon,
-  ChevronLeftIcon,
-  ChevronRightIcon,
-} from "lucide-react";
-import {
-  DayButton,
   DayPicker,
   getDefaultClassNames,
-  type DateRange,
-  type Matcher,
+  type DayButton,
 } from "react-day-picker";
-import type { Locale } from "date-fns";
 
 import { cn } from "@/lib/utils";
 import { Button, buttonVariants } from "@/components/ui/button";
+import {
+  ChevronLeftIcon,
+  ChevronRightIcon,
+  ChevronDownIcon,
+} from "lucide-react";
 
-/**
- * Props for Calendar component (Documentation only - NOT used in component implementation)
- *
- * These types are for documentation generation and should not replace react-day-picker inferred types.
- * Extends react-day-picker's DayPicker props with additional customization options.
- * Provides comprehensive type safety and documentation for all available props.
- */
-// eslint-disable-next-line unused-imports/no-unused-vars
-type CalendarDocsProps = {
-  /**
-   * Selection mode that determines how dates can be selected
-   *
-   * @default "none"
-   * @example
-   * ```tsx
-   * // Single date selection
-   * <Calendar mode="single" selected={date} onSelect={setDate} />
-   *
-   * // Date range selection
-   * <Calendar mode="range" selected={range} onSelect={setRange} />
-   *
-   * // Multiple dates selection
-   * <Calendar mode="multiple" selected={dates} onSelect={setDates} />
-   * ```
-   */
-  mode?: "single" | "multiple" | "range" | "none";
-
-  /**
-   * The selected date(s) - type varies based on selection mode
-   *
-   * - Single mode: `Date | undefined`
-   * - Multiple mode: `Date[] | undefined`
-   * - Range mode: `DateRange | undefined`
-   * - None mode: Not applicable
-   *
-   * @example
-   * ```tsx
-   * const [date, setDate] = useState<Date>()
-   * <Calendar mode="single" selected={date} />
-   *
-   * const [dates, setDates] = useState<Date[]>()
-   * <Calendar mode="multiple" selected={dates} />
-   *
-   * const [range, setRange] = useState<DateRange>()
-   * <Calendar mode="range" selected={range} />
-   * ```
-   */
-  selected?: Date | Date[] | DateRange | undefined;
-
-  /**
-   * Event handler called when date selection changes
-   *
-   * The handler signature varies based on the selection mode:
-   * - Single: `(date: Date | undefined) => void`
-   * - Multiple: `(dates: Date[] | undefined) => void`
-   * - Range: `(range: DateRange | undefined) => void`
-   *
-   * @param value - The new selected value(s)
-   */
-  onSelect?: (value: Date | Date[] | DateRange | undefined) => void;
-
-  /**
-   * Button variant for navigation arrows and interactive elements
-   *
-   * Controls the visual style of the previous/next month navigation buttons.
-   * Choose from shadcn/ui button variants to match your design system.
-   *
-   * @default "ghost"
-   * @example
-   * ```tsx
-   * // Outline style navigation buttons
-   * <Calendar buttonVariant="outline" />
-   *
-   * // Secondary style for subtle navigation
-   * <Calendar buttonVariant="secondary" />
-   * ```
-   */
-  buttonVariant?:
-    | "default"
-    | "destructive"
-    | "outline"
-    | "secondary"
-    | "ghost"
-    | "link";
-
-  /**
-   * Layout style for the month caption area
-   *
-   * - `"buttons"`: Navigation buttons on either side of the month/year label
-   * - `"dropdown"`: Interactive dropdowns for month and year selection
-   * - `"dropdown-buttons"`: Combines dropdowns with navigation buttons
-   *
-   * @default "buttons"
-   * @example
-   * ```tsx
-   * // Enable month/year dropdowns
-   * <Calendar captionLayout="dropdown" fromYear={2020} toYear={2030} />
-   * ```
-   */
-  captionLayout?: "buttons" | "dropdown" | "dropdown-buttons";
-
-  /**
-   * Whether to show days from adjacent months (outside days)
-   *
-   * When true, displays grayed-out days from the previous and next months
-   * to fill the calendar grid. Useful for maintaining consistent layout.
-   *
-   * @default true
-   */
-  showOutsideDays?: boolean;
-
-  /**
-   * The number of months to display simultaneously
-   *
-   * Useful for date range selection or providing more calendar context.
-   * Months are displayed side by side on larger screens.
-   *
-   * @default 1
-   * @example
-   * ```tsx
-   * // Show two months for range selection
-   * <Calendar numberOfMonths={2} mode="range" />
-   * ```
-   */
-  numberOfMonths?: number;
-
-  /**
-   * Whether to display a column showing week numbers
-   *
-   * Week numbers are calculated according to the locale settings.
-   * Use `ISOWeek` prop for ISO 8601 week numbering.
-   *
-   * @default false
-   * @see {@link ISOWeek} For ISO week date format
-   * @see {@link firstWeekContainsDate} For first week configuration
-   */
-  showWeekNumber?: boolean;
-
-  /**
-   * Use ISO 8601 week dates instead of locale-based week numbering
-   *
-   * When true, weeks start on Monday and the first week contains January 4th.
-   * This standardizes week numbering across different locales.
-   *
-   * @default false
-   * @see {@link showWeekNumber} To display week numbers
-   */
-  ISOWeek?: boolean;
-
-  /**
-   * Always display exactly 6 weeks per month
-   *
-   * Prevents calendar height changes during navigation by ensuring
-   * a consistent 6-week grid. Empty cells are filled with outside days.
-   *
-   * @default false
-   */
-  fixedWeeks?: boolean;
-
-  /**
-   * Dates or date ranges that cannot be selected
-   *
-   * Accepts various matcher formats:
-   * - Single date: `new Date(2024, 0, 15)`
-   * - Date range: `{ from: new Date(2024, 0, 1), to: new Date(2024, 0, 31) }`
-   * - Days of week: `{ dayOfWeek: [0, 6] }` (Sunday, Saturday)
-   * - Before/after: `{ before: new Date() }`, `{ after: new Date(2024, 11, 31) }`
-   * - Array of matchers: `[date1, { dayOfWeek: [0] }, { before: new Date() }]`
-   *
-   * @example
-   * ```tsx
-   * <Calendar disabled={[
-   *   { before: new Date() }, // Past dates
-   *   { dayOfWeek: [0, 6] }, // Weekends
-   *   new Date(2024, 11, 25), // Christmas
-   *   { from: new Date(2024, 6, 1), to: new Date(2024, 6, 7) } // Vacation week
-   * ]} />
-   * ```
-   */
-  disabled?: Matcher | Matcher[];
-
-  /**
-   * Dates or date ranges to visually highlight with special styling
-   *
-   * Similar to disabled prop but for positive highlighting.
-   * Useful for marking holidays, events, or available dates.
-   *
-   * @example
-   * ```tsx
-   * <Calendar highlighted={[
-   *   new Date(2024, 11, 25), // Christmas
-   *   { from: new Date(2024, 5, 1), to: new Date(2024, 5, 7) } // Special week
-   * ]} />
-   * ```
-   */
-  highlighted?: Matcher | Matcher[];
-
-  /**
-   * The initially displayed month when the calendar first renders
-   *
-   * Useful for starting the calendar on a specific month rather than
-   * the current month or selected date.
-   *
-   * @example
-   * ```tsx
-   * // Start calendar in June 2024
-   * <Calendar defaultMonth={new Date(2024, 5)} />
-   * ```
-   */
-  defaultMonth?: Date;
-
-  /**
-   * Controlled month display (use with onMonthChange)
-   *
-   * When provided, the calendar will display this specific month.
-   * Use with onMonthChange for programmatic month control.
-   *
-   * @example
-   * ```tsx
-   * const [month, setMonth] = useState(new Date(2024, 5))
-   * <Calendar month={month} onMonthChange={setMonth} />
-   * ```
-   */
-  month?: Date;
-
-  /**
-   * Event handler called when the displayed month changes
-   *
-   * Called when user navigates to a different month via buttons,
-   * dropdowns, or keyboard navigation.
-   *
-   * @param month - The new month being displayed
-   */
-  onMonthChange?: (month: Date) => void;
-
-  /**
-   * Earliest month that can be navigated to
-   *
-   * Restricts backward navigation beyond this month.
-   * Navigation buttons are disabled when reaching this limit.
-   *
-   * @example
-   * ```tsx
-   * // Don't allow navigation before January 2024
-   * <Calendar startMonth={new Date(2024, 0)} />
-   * ```
-   */
-  startMonth?: Date;
-
-  /**
-   * Latest month that can be navigated to
-   *
-   * Restricts forward navigation beyond this month.
-   * Navigation buttons are disabled when reaching this limit.
-   *
-   * @example
-   * ```tsx
-   * // Don't allow navigation past December 2025
-   * <Calendar endMonth={new Date(2025, 11)} />
-   * ```
-   */
-  endMonth?: Date;
-
-  /**
-   * Earliest year for dropdown navigation (when using captionLayout="dropdown")
-   *
-   * Only relevant when using dropdown caption layout.
-   * Limits the earliest selectable year in the year dropdown.
-   *
-   * @default Current year - 100
-   */
-  fromYear?: number;
-
-  /**
-   * Latest year for dropdown navigation (when using captionLayout="dropdown")
-   *
-   * Only relevant when using dropdown caption layout.
-   * Limits the latest selectable year in the year dropdown.
-   *
-   * @default Current year + 100
-   */
-  toYear?: number;
-
-  /**
-   * Completely disable all month navigation
-   *
-   * When true, removes navigation buttons and prevents month changes.
-   * Useful for static calendar displays.
-   *
-   * @default false
-   */
-  disableNavigation?: boolean;
-
-  /**
-   * Hide the navigation buttons while keeping programmatic navigation possible
-   *
-   * Unlike disableNavigation, this only hides the UI buttons but allows
-   * navigation via onMonthChange and other programmatic methods.
-   *
-   * @default false
-   */
-  hideNavigation?: boolean;
-
-  /**
-   * Enable smooth month transition animations
-   *
-   * Adds CSS transitions when navigating between months.
-   * Customize animation duration and timing with CSS variables.
-   *
-   * @default false
-   * @example
-   * ```tsx
-   * // Enable with custom animation
-   * <Calendar
-   *   animate
-   *   className="[--rdp-animation_duration:0.3s] [--rdp-animation_timing:ease-in-out]"
-   * />
-   * ```
-   */
-  animate?: boolean;
-
-  /**
-   * The first day of the week (0 = Sunday, 1 = Monday, etc.)
-   *
-   * Overrides the locale's default first day of week setting.
-   * Affects both the weekday header display and week calculations.
-   *
-   * @default Locale default
-   * @example
-   * ```tsx
-   * // Start weeks on Monday
-   * <Calendar weekStartsOn={1} />
-   * ```
-   */
-  weekStartsOn?: 0 | 1 | 2 | 3 | 4 | 5 | 6;
-
-  /**
-   * Configuration for the first week of the year
-   *
-   * - `1`: First week contains January 1st
-   * - `4`: First week contains January 4th (ISO 8601 standard)
-   *
-   * Affects week number calculations when showWeekNumber is enabled.
-   *
-   * @default 1
-   * @see {@link showWeekNumber}
-   * @see {@link ISOWeek}
-   */
-  firstWeekContainsDate?: 1 | 4;
-
-  /**
-   * Locale for date formatting and localization
-   *
-   * Uses date-fns locale objects for internationalization.
-   * Affects month names, weekday names, and date formatting.
-   *
-   * @default date-fns English locale
-   * @example
-   * ```tsx
-   * import { es } from 'date-fns/locale'
-   * <Calendar locale={es} />
-   * ```
-   */
-  locale?: Locale;
-
-  /**
-   * Text direction for right-to-left languages
-   *
-   * @default "ltr"
-   * @example
-   * ```tsx
-   * // For Arabic or Hebrew
-   * <Calendar dir="rtl" />
-   * ```
-   */
-  dir?: "ltr" | "rtl";
-
-  /**
-   * Event handler for day click events
-   *
-   * Called when any day is clicked, regardless of selection mode.
-   * Provides the clicked date and any active modifiers.
-   *
-   * @param day - The clicked date
-   * @param modifiers - Object containing modifier states (selected, disabled, etc.)
-   */
-  onDayClick?: (day: Date, modifiers: Record<string, boolean>) => void;
-
-  /**
-   * Event handler for day hover events
-   *
-   * Called when the mouse enters a day cell.
-   *
-   * @param day - The hovered date
-   * @param modifiers - Object containing modifier states
-   */
-  onDayMouseEnter?: (day: Date, modifiers: Record<string, boolean>) => void;
-
-  /**
-   * Event handler for day hover leave events
-   *
-   * Called when the mouse leaves a day cell.
-   *
-   * @param day - The unhovered date
-   * @param modifiers - Object containing modifier states
-   */
-  onDayMouseLeave?: (day: Date, modifiers: Record<string, boolean>) => void;
-
-  /**
-   * Event handler for day keyboard events
-   *
-   * Called when a key is pressed while a day has focus.
-   * Useful for custom keyboard shortcuts or interactions.
-   *
-   * @param day - The focused date
-   * @param key - The pressed key
-   * @param modifiers - Object containing modifier states
-   */
-  onDayKeyDown?: (
-    day: Date,
-    key: string,
-    modifiers: Record<string, boolean>,
-  ) => void;
-
-  /**
-   * Event handler for week number clicks
-   *
-   * Called when a week number is clicked (when showWeekNumber is true).
-   * Useful for selecting entire weeks or custom week-based interactions.
-   *
-   * @param weekNumber - The clicked week number
-   * @param dates - Array of all dates in that week
-   */
-  onWeekNumberClick?: (weekNumber: number, dates: Date[]) => void;
-
-  /**
-   * Custom formatters for date display
-   *
-   * Override default formatting for various calendar elements.
-   * All formatters receive the date and locale options.
-   *
-   * @example
-   * ```tsx
-   * <Calendar formatters={{
-   *   formatDay: (date) => date.getDate().toString(),
-   *   formatMonthCaption: (date) => date.toLocaleDateString('en', { month: 'long', year: 'numeric' }),
-   *   formatWeekNumber: (weekNumber) => `W${weekNumber}`
-   * }} />
-   * ```
-   */
-  formatters?: {
-    /** Format individual day numbers */
-    formatDay?: (date: Date) => string;
-    /** Format month caption (header) */
-    formatMonthCaption?: (date: Date) => string;
-    /** Format week numbers */
-    formatWeekNumber?: (weekNumber: number) => string;
-    /** Format weekday names in header */
-    formatWeekdayName?: (date: Date) => string;
-    /** Format year in dropdown */
-    formatYearDropdown?: (date: Date) => string;
-    /** Format month in dropdown */
-    formatMonthDropdown?: (date: Date) => string;
-  };
-
-  /**
-   * Custom class names for calendar elements
-   *
-   * Override default styling for specific parts of the calendar.
-   * Useful for theming or custom styling without affecting the entire component.
-   *
-   * @example
-   * ```tsx
-   * <Calendar classNames={{
-   *   day: "hover:bg-blue-100",
-   *   selected: "bg-blue-500 text-white",
-   *   disabled: "opacity-30",
-   *   range_middle: "bg-blue-100"
-   * }} />
-   * ```
-   */
-  classNames?: {
-    /** Root calendar container */
-    root?: string;
-    /** Months container */
-    months?: string;
-    /** Individual month container */
-    month?: string;
-    /** Month caption/header */
-    month_caption?: string;
-    /** Navigation container */
-    nav?: string;
-    /** Previous month button */
-    button_previous?: string;
-    /** Next month button */
-    button_next?: string;
-    /** Month/year dropdowns container */
-    dropdowns?: string;
-    /** Individual dropdown */
-    dropdown?: string;
-    /** Weekdays header row */
-    weekdays?: string;
-    /** Individual weekday header */
-    weekday?: string;
-    /** Week row container */
-    week?: string;
-    /** Week number cell */
-    week_number?: string;
-    /** Individual day cell */
-    day?: string;
-    /** Selected day(s) */
-    selected?: string;
-    /** Today's date */
-    today?: string;
-    /** Disabled days */
-    disabled?: string;
-    /** Days outside current month */
-    outside?: string;
-    /** Range start day */
-    range_start?: string;
-    /** Range end day */
-    range_end?: string;
-    /** Days in middle of range */
-    range_middle?: string;
-    /** Hidden days */
-    hidden?: string;
-  };
-
-  /**
-   * Custom React components to replace default calendar parts
-   *
-   * Allows complete customization of calendar rendering by replacing
-   * internal components with your own implementations.
-   *
-   * @example
-   * ```tsx
-   * <Calendar components={{
-   *   DayContent: ({ date }) => (
-   *     <span>{date.getDate()}{date.getDate() === 1 && '🎉'}</span>
-   *   ),
-   *   MonthCaption: ({ displayMonth }) => (
-   *     <h2 className="text-lg font-bold">{displayMonth.toLocaleDateString()}</h2>
-   *   )
-   * }} />
-   * ```
-   */
-  components?: {
-    /** Root calendar container component */
-    Root?: React.ComponentType<
-      React.ComponentProps<"div"> & { rootRef?: React.Ref<HTMLDivElement> }
-    >;
-    /** Month caption component */
-    MonthCaption?: React.ComponentType<{ displayMonth: Date }>;
-    /** Navigation chevron icons */
-    Chevron?: React.ComponentType<
-      React.ComponentProps<"svg"> & {
-        orientation?: "left" | "right" | "up" | "down";
-      }
-    >;
-    /** Individual day button */
-    DayButton?: React.ComponentType<React.ComponentProps<typeof DayButton>>;
-    /** Day content (number/text inside day) */
-    DayContent?: React.ComponentType<{ date: Date }>;
-    /** Dropdown select components */
-    Dropdown?: React.ComponentType<React.ComponentProps<"select">>;
-    /** Week number component */
-    WeekNumber?: React.ComponentType<
-      React.ComponentProps<"td"> & { children: React.ReactNode }
-    >;
-    /** Footer component */
-    Footer?: React.ComponentType<{ children: React.ReactNode }>;
-    /** Weekdays header */
-    Weekdays?: React.ComponentType<React.ComponentProps<"tr">>;
-    /** Week row component */
-    Week?: React.ComponentType<React.ComponentProps<"tr">>;
-  };
-
-  /**
-   * Footer content displayed below the calendar
-   *
-   * Can be any React node - text, components, or complex elements.
-   * Commonly used to show selected date(s) or provide additional context.
-   *
-   * @example
-   * ```tsx
-   * <Calendar footer={
-   *   selected ? (
-   *     <p>Selected: {selected.toLocaleDateString()}</p>
-   *   ) : (
-   *     <p>Please select a date</p>
-   *   )
-   * } />
-   * ```
-   */
-  footer?: React.ReactNode;
-
-  /**
-   * Custom modifiers for advanced styling and behavior
-   *
-   * Define custom rules for styling or highlighting specific dates.
-   * Each modifier can be a date, date range, or function that returns boolean.
-   *
-   * @example
-   * ```tsx
-   * <Calendar modifiers={{
-   *   weekend: { dayOfWeek: [0, 6] },
-   *   holiday: [new Date(2024, 11, 25), new Date(2024, 0, 1)],
-   *   booked: (date) => bookedDates.includes(date.toDateString())
-   * }} />
-   * ```
-   */
-  modifiers?: Record<string, Matcher | Matcher[]>;
-
-  /**
-   * Additional CSS classes to apply to the calendar root
-   *
-   * Standard className prop for styling the entire calendar container.
-   */
-  className?: string;
-
-  /**
-   * Inline styles for the calendar root
-   *
-   * React CSSProperties object for inline styling.
-   */
-  style?: React.CSSProperties;
-
-  /**
-   * HTML data attributes and other props
-   *
-   * Any additional HTML attributes will be forwarded to the root element.
-   */
-  [key: string]: unknown;
-} & Omit<React.ComponentProps<typeof DayPicker>, "buttonVariant">;
-
-/**
- * Actual props type used by the Calendar component implementation
- * Uses react-day-picker's inferred types for perfect compatibility
- */
 type CalendarProps = React.ComponentProps<typeof DayPicker> & {
-  /**
-   * Button variant for navigation arrows and interactive elements
-   * @default "ghost"
-   */
-  buttonVariant?:
-    | "default"
-    | "destructive"
-    | "outline"
-    | "secondary"
-    | "ghost"
-    | "link";
+  /** Visual style variant for navigation buttons. @default "ghost" */
+  buttonVariant?: React.ComponentProps<typeof Button>["variant"];
 };
 
 /**
- * Calendar - A comprehensive date selection calendar component
- *
- * A fully-featured calendar component built on react-day-picker that provides intuitive
- * date selection with extensive customization options. Supports single dates, date ranges,
- * multiple dates, and custom validation rules with built-in accessibility features.
- *
- * Built on the powerful react-day-picker library, this component provides a complete
- * calendar interface with advanced features like custom formatters, modifiers, disabled
- * dates, localization, and extensive styling options.
- *
- * @component
- *
- * @example Basic single date selection
- * ```tsx
- * const [date, setDate] = useState<Date | undefined>()
- *
- * <Calendar
- *   mode="single"
- *   selected={date}
- *   onSelect={setDate}
- *   className="rounded-md border"
- * />
- * ```
- *
- * @example Date range selection with two months
- * ```tsx
- * const [dateRange, setDateRange] = useState<DateRange | undefined>()
- *
- * <Calendar
- *   mode="range"
- *   selected={dateRange}
- *   onSelect={setDateRange}
- *   numberOfMonths={2}
- *   className="rounded-md border"
- * />
- * ```
- *
- * @example Multiple date selection with limits
- * ```tsx
- * const [dates, setDates] = useState<Date[] | undefined>()
- *
- * <Calendar
- *   mode="multiple"
- *   selected={dates}
- *   onSelect={setDates}
- *   min={2} // Minimum 2 dates required
- *   max={5} // Maximum 5 dates allowed
- *   className="rounded-md border"
- * />
- * ```
- *
- * @example Calendar with disabled dates and custom validation
- * ```tsx
- * <Calendar
- *   mode="single"
- *   selected={date}
- *   onSelect={setDate}
- *   disabled={[
- *     { before: new Date() }, // Disable past dates
- *     { dayOfWeek: [0, 6] }, // Disable weekends
- *     { from: new Date(2024, 0, 15), to: new Date(2024, 0, 20) } // Disable range
- *   ]}
- *   className="rounded-md border"
- * />
- * ```
- *
- * @example Calendar with month/year dropdowns and navigation limits
- * ```tsx
- * <Calendar
- *   mode="single"
- *   captionLayout="dropdown"
- *   selected={date}
- *   onSelect={setDate}
- *   fromYear={2020}
- *   toYear={2030}
- *   startMonth={new Date(2023, 0)} // Don't go before Jan 2023
- *   endMonth={new Date(2025, 11)} // Don't go past Dec 2025
- *   className="rounded-md border"
- * />
- * ```
- *
- * @example International calendar with custom locale
- * ```tsx
- * import { es } from 'date-fns/locale'
- *
- * <Calendar
- *   mode="single"
- *   selected={date}
- *   onSelect={setDate}
- *   locale={es} // Spanish locale
- *   weekStartsOn={1} // Start weeks on Monday
- *   dir="ltr"
- *   className="rounded-md border"
- * />
- * ```
- *
- * @example Calendar with custom formatters and styling
- * ```tsx
- * <Calendar
- *   mode="single"
- *   showWeekNumber
- *   formatters={{
- *     formatDay: (date) => date.getDate().toString(),
- *     formatWeekNumber: (weekNumber) => `W${weekNumber}`,
- *     formatMonthCaption: (date) =>
- *       date.toLocaleDateString('en', { month: 'long', year: 'numeric' })
- *   }}
- *   classNames={{
- *     day: "hover:bg-blue-100 transition-colors",
- *     selected: "bg-blue-500 text-white font-semibold",
- *     today: "bg-blue-100 font-bold"
- *   }}
- *   className="rounded-lg border-2 shadow-lg"
- * />
- * ```
- *
- * @example Calendar with custom modifiers and event handling
- * ```tsx
- * const holidays = [new Date(2024, 11, 25), new Date(2024, 0, 1)]
- * const weekends = { dayOfWeek: [0, 6] }
- *
- * <Calendar
- *   mode="single"
- *   modifiers={{
- *     holiday: holidays,
- *     weekend: weekends,
- *     available: (date) => availableDates.includes(date.toDateString())
- *   }}
- *   onDayClick={(day, modifiers) => {
- *     if (modifiers.holiday) {
- *       alert('Holiday selected!')
- *     }
- *   }}
- *   onWeekNumberClick={(weekNumber, dates) => {
- *     console.log(`Week ${weekNumber} contains:`, dates)
- *   }}
- *   classNames={{
- *     holiday: "bg-red-100 text-red-800",
- *     weekend: "bg-gray-100 text-gray-600",
- *     available: "bg-green-100 text-green-800"
- *   }}
- * />
- * ```
- *
- * @example Calendar with custom components
- * ```tsx
- * <Calendar
- *   mode="single"
- *   components={{
- *     DayContent: ({ date }) => (
- *       <div className="relative">
- *         {date.getDate()}
- *         {date.getDate() === 1 && (
- *           <span className="absolute -top-1 -right-1 text-xs">🎉</span>
- *         )}
- *       </div>
- *     ),
- *     MonthCaption: ({ displayMonth }) => (
- *       <div className="flex items-center justify-center py-2">
- *         <h2 className="text-lg font-bold text-blue-600">
- *           {displayMonth.toLocaleDateString('en', {
- *             month: 'long',
- *             year: 'numeric'
- *           })}
- *         </h2>
- *       </div>
- *     )
- *   }}
- * />
- * ```
- *
- * @example Advanced range selection with custom styling
- * ```tsx
- * const [dateRange, setDateRange] = useState<DateRange>()
- *
- * <Calendar
- *   mode="range"
- *   selected={dateRange}
- *   onSelect={setDateRange}
- *   numberOfMonths={2}
- *   showOutsideDays={false}
- *   fixedWeeks
- *   classNames={{
- *     range_start: "bg-blue-500 text-white rounded-l-md",
- *     range_end: "bg-blue-500 text-white rounded-r-md",
- *     range_middle: "bg-blue-100 text-blue-900",
- *     selected: "bg-blue-500 text-white"
- *   }}
- *   footer={dateRange && (
- *     <div className="p-3 border-t">
- *       <p className="text-sm text-gray-600">
- *         {dateRange.from && `From: ${dateRange.from.toLocaleDateString()}`}
- *         {dateRange.to && ` • To: ${dateRange.to.toLocaleDateString()}`}
- *         {dateRange.from && dateRange.to && (
- *           ` • ${Math.ceil((dateRange.to.getTime() - dateRange.from.getTime()) / (1000 * 60 * 60 * 24) + 1)} days`
- *         )}
- *       </p>
- *     </div>
- *   )}
- * />
- * ```
- *
- * @features
- * - **Selection Modes**: Single date, date ranges, multiple dates, or no selection
- * - **Navigation**: Month/year navigation with buttons or dropdowns, keyboard support
- * - **Validation**: Flexible date disabling, custom matchers, min/max constraints
- * - **Customization**: Custom formatters, modifiers, components, styling
- * - **Internationalization**: Full locale support, RTL languages, custom week start
- * - **Accessibility**: WCAG 2.1 AA compliant, screen reader support, keyboard navigation
- * - **Performance**: Optimized rendering, minimal re-renders, efficient DOM updates
- *
- * @accessibility
- * - **Keyboard Navigation**:
- *   - Arrow keys navigate between dates
- *   - Page Up/Down navigate months
- *   - Home/End navigate to start/end of week
- *   - Ctrl+Page Up/Down navigate years
- *   - Enter/Space select dates
- *   - Escape closes popover/dropdown states
- * - **Screen Reader Support**:
- *   - Comprehensive ARIA labels and descriptions
- *   - Live region announcements for month changes
- *   - Proper role and state management
- *   - Selected dates and ranges announced clearly
- * - **Focus Management**:
- *   - Visible focus indicators with 3px ring
- *   - Focus restoration after month navigation
- *   - Logical tab order through interactive elements
- *   - Trapped focus in dropdown modes
- * - **Standards Compliance**:
- *   - WCAG 2.1 AA color contrast requirements
- *   - Proper heading structure and landmarks
- *   - Compatible with screen readers and assistive technology
- * - **RTL Support**:
- *   - Right-to-left text direction support
- *   - Mirrored navigation button orientation
- *   - Locale-aware date formatting
- *
- * @performance
- * - **Optimized Rendering**: Minimal re-renders through memoization and efficient state management
- * - **Large Date Ranges**: Efficiently handles calendars spanning multiple months and years
- * - **Event Handling**: Debounced and optimized event handlers for smooth interactions
- * - **Memory Management**: Proper cleanup and garbage collection for long-running applications
- * - **Bundle Size**: Tree-shakeable with minimal runtime overhead
- *
- * @styling
- * - **Design System Integration**: Built with shadcn/ui design tokens and Tailwind CSS
- * - **CSS Custom Properties**: Supports `--cell-size` and other CSS variables for sizing
- * - **Theming**: Dark mode support and custom theme integration
- * - **Responsive**: Mobile-friendly with touch interactions and responsive layouts
- * - **Customizable**: Override any visual aspect through classNames, components, or CSS
- *
- * @browser-support
- * - **Modern Browsers**: Chrome 91+, Firefox 90+, Safari 15+, Edge 91+
- * - **Mobile**: iOS Safari 15+, Android Chrome 91+
- * - **Accessibility**: Compatible with NVDA, JAWS, VoiceOver screen readers
- *
- * @see {@link CalendarDayButton} Individual day button component with custom styling
- * @see {@link CalendarProps} Complete props interface with TypeScript definitions
- * @see {@link https://react-day-picker.js.org/} react-day-picker documentation for advanced configuration
- * @see {@link https://ui.shadcn.com/docs/components/calendar} shadcn/ui Calendar documentation
- * @see {@link https://date-fns.org/docs/I18n} date-fns internationalization guide
- * @see {@link https://www.w3.org/WAI/ARIA/apg/patterns/} WAI-ARIA Authoring Practices Guide
- * @since 1.0.0
+ * Calendar component for date selection with single, range, or multiple modes.
+ * Built on react-day-picker with customizable appearance and navigation.
  */
 function Calendar({
   className,
@@ -951,7 +40,7 @@ function Calendar({
     <DayPicker
       showOutsideDays={showOutsideDays}
       className={cn(
-        "bg-background group/calendar p-3 [--cell-size:--spacing(8)] [[data-slot=card-content]_&]:bg-transparent [[data-slot=popover-content]_&]:bg-transparent",
+        "p-3 [--cell-radius:var(--radius-md)] [--cell-size:--spacing(8)] bg-background group/calendar [[data-slot=card-content]_&]:bg-transparent [[data-slot=popover-content]_&]:bg-transparent",
         String.raw`rtl:**:[.rdp-button\_next>svg]:rotate-180`,
         String.raw`rtl:**:[.rdp-button\_previous>svg]:rotate-180`,
         className,
@@ -992,7 +81,7 @@ function Calendar({
           defaultClassNames.dropdowns,
         ),
         dropdown_root: cn(
-          "relative has-focus:border-ring border border-input shadow-xs has-focus:ring-ring/50 has-focus:ring-[3px] rounded-md",
+          "relative cn-calendar-dropdown-root rounded-(--cell-radius)",
           defaultClassNames.dropdown_root,
         ),
         dropdown: cn(
@@ -1003,13 +92,13 @@ function Calendar({
           "select-none font-medium",
           captionLayout === "label"
             ? "text-sm"
-            : "rounded-md pl-2 pr-1 flex items-center gap-1 text-sm h-8 [&>svg]:text-muted-foreground [&>svg]:size-3.5",
+            : "cn-calendar-caption-label rounded-(--cell-radius) flex items-center gap-1 text-sm  [&>svg]:text-muted-foreground [&>svg]:size-3.5",
           defaultClassNames.caption_label,
         ),
         table: "w-full border-collapse",
         weekdays: cn("flex", defaultClassNames.weekdays),
         weekday: cn(
-          "text-muted-foreground rounded-md flex-1 font-normal text-[0.8rem] select-none",
+          "text-muted-foreground rounded-(--cell-radius) flex-1 font-normal text-[0.8rem] select-none",
           defaultClassNames.weekday,
         ),
         week: cn("flex w-full mt-2", defaultClassNames.week),
@@ -1022,17 +111,23 @@ function Calendar({
           defaultClassNames.week_number,
         ),
         day: cn(
-          "relative w-full h-full p-0 text-center [&:first-child[data-selected=true]_button]:rounded-l-md [&:last-child[data-selected=true]_button]:rounded-r-md group/day aspect-square select-none",
+          "relative w-full rounded-(--cell-radius) h-full p-0 text-center [&:last-child[data-selected=true]_button]:rounded-r-(--cell-radius) group/day aspect-square select-none",
+          props.showWeekNumber
+            ? "[&:nth-child(2)[data-selected=true]_button]:rounded-l-(--cell-radius)"
+            : "[&:first-child[data-selected=true]_button]:rounded-l-(--cell-radius)",
           defaultClassNames.day,
         ),
         range_start: cn(
-          "rounded-l-md bg-accent",
+          "rounded-l-(--cell-radius) bg-muted elative after:bg-muted after:absolute after:inset-y-0 after:w-4 after:right-0 -z-0 isolate",
           defaultClassNames.range_start,
         ),
         range_middle: cn("rounded-none", defaultClassNames.range_middle),
-        range_end: cn("rounded-r-md bg-accent", defaultClassNames.range_end),
+        range_end: cn(
+          "rounded-r-(--cell-radius) bg-muted relative after:bg-muted after:absolute after:inset-y-0 after:w-4 after:left-0 -z-0 isolate",
+          defaultClassNames.range_end,
+        ),
         today: cn(
-          "bg-accent text-accent-foreground rounded-md data-[selected=true]:rounded-none",
+          "bg-muted text-foreground rounded-(--cell-radius) data-[selected=true]:rounded-none",
           defaultClassNames.today,
         ),
         outside: cn(
@@ -1047,14 +142,7 @@ function Calendar({
         ...classNames,
       }}
       components={{
-        Root: ({
-          className,
-          rootRef,
-          ...props
-        }: {
-          className?: string;
-          rootRef?: React.Ref<HTMLDivElement>;
-        } & React.ComponentProps<"div">) => {
+        Root: ({ className, rootRef, ...props }) => {
           return (
             <div
               data-slot="calendar"
@@ -1064,14 +152,7 @@ function Calendar({
             />
           );
         },
-        Chevron: ({
-          className,
-          orientation,
-          ...props
-        }: {
-          className?: string;
-          orientation?: "left" | "right" | "up" | "down";
-        } & React.ComponentProps<"svg">) => {
+        Chevron: ({ className, orientation, ...props }) => {
           if (orientation === "left") {
             return (
               <ChevronLeftIcon className={cn("size-4", className)} {...props} />
@@ -1092,10 +173,7 @@ function Calendar({
           );
         },
         DayButton: CalendarDayButton,
-        WeekNumber: ({
-          children,
-          ...props
-        }: React.ComponentProps<"td"> & { children?: React.ReactNode }) => {
+        WeekNumber: ({ children, ...props }) => {
           return (
             <td {...props}>
               <div className="flex size-(--cell-size) items-center justify-center text-center">
@@ -1111,54 +189,18 @@ function Calendar({
   );
 }
 
+type CalendarDayButtonProps = React.ComponentProps<typeof DayButton>;
+
 /**
- * CalendarDayButton - Individual day button component for calendar dates
- *
- * Renders a single interactive day button with appropriate styling for different states
- * including selected, today, disabled, and range selection indicators. This component
- * is used internally by the Calendar component but can be customized if needed.
- *
- * @component
- * @example
- * ```tsx
- * // Used internally by Calendar component
- * <CalendarDayButton
- *   day={dayObject}
- *   modifiers={{
- *     selected: true,
- *     today: false,
- *     disabled: false,
- *     range_start: false,
- *     range_end: false,
- *     range_middle: false
- *   }}
- * />
- * ```
- *
- * @param day - The day object containing date information from react-day-picker
- * @param modifiers - State modifiers object controlling appearance and behavior
- * @param modifiers.selected - Whether this day is currently selected
- * @param modifiers.today - Whether this day represents today's date
- * @param modifiers.disabled - Whether this day is disabled for selection
- * @param modifiers.range_start - Whether this day is the start of a date range
- * @param modifiers.range_end - Whether this day is the end of a date range
- * @param modifiers.range_middle - Whether this day is in the middle of a date range
- * @param modifiers.focused - Whether this day currently has keyboard focus
- *
- * @accessibility
- * - **Keyboard Navigation**: Fully keyboard accessible with arrow key support
- * - **Screen Reader Support**: Announces date and selection state to assistive technology
- * - **Focus Management**: Proper focus indicators and focus restoration
- * - **State Announcement**: Clear visual and auditory feedback for selection states
- *
- * @since 1.0.0
+ * Internal day button component with range and selection state styling.
+ * Handles focus management and applies appropriate styles for single, range, and multiple selection modes.
  */
 function CalendarDayButton({
   className,
   day,
   modifiers,
   ...props
-}: React.ComponentProps<typeof DayButton>) {
+}: CalendarDayButtonProps) {
   const defaultClassNames = getDefaultClassNames();
 
   const ref = React.useRef<HTMLButtonElement>(null);
@@ -1168,7 +210,6 @@ function CalendarDayButton({
 
   return (
     <Button
-      ref={ref}
       variant="ghost"
       size="icon"
       data-day={day.date.toLocaleDateString()}
@@ -1182,7 +223,7 @@ function CalendarDayButton({
       data-range-end={modifiers.range_end}
       data-range-middle={modifiers.range_middle}
       className={cn(
-        "data-[selected-single=true]:bg-primary data-[selected-single=true]:text-primary-foreground data-[range-middle=true]:bg-accent data-[range-middle=true]:text-accent-foreground data-[range-start=true]:bg-primary data-[range-start=true]:text-primary-foreground data-[range-end=true]:bg-primary data-[range-end=true]:text-primary-foreground group-data-[focused=true]/day:border-ring group-data-[focused=true]/day:ring-ring/50 dark:hover:text-accent-foreground flex aspect-square size-auto w-full min-w-(--cell-size) flex-col gap-1 leading-none font-normal group-data-[focused=true]/day:relative group-data-[focused=true]/day:z-10 group-data-[focused=true]/day:ring-[3px] data-[range-end=true]:rounded-md data-[range-end=true]:rounded-r-md data-[range-middle=true]:rounded-none data-[range-start=true]:rounded-md data-[range-start=true]:rounded-l-md [&>span]:text-xs [&>span]:opacity-70",
+        "data-[selected-single=true]:bg-primary data-[selected-single=true]:text-primary-foreground data-[range-middle=true]:bg-muted data-[range-middle=true]:text-foreground data-[range-start=true]:bg-primary data-[range-start=true]:text-primary-foreground data-[range-end=true]:bg-primary data-[range-end=true]:text-primary-foreground group-data-[focused=true]/day:border-ring group-data-[focused=true]/day:ring-ring/50 dark:hover:text-foreground relative isolate z-10 flex aspect-square size-auto w-full min-w-(--cell-size) flex-col gap-1 border-0 leading-none font-normal group-data-[focused=true]/day:relative group-data-[focused=true]/day:z-10 group-data-[focused=true]/day:ring-[3px] data-[range-end=true]:rounded-(--cell-radius) data-[range-end=true]:rounded-r-(--cell-radius) data-[range-middle=true]:rounded-none data-[range-start=true]:rounded-(--cell-radius) data-[range-start=true]:rounded-l-(--cell-radius) [&>span]:text-xs [&>span]:opacity-70",
         defaultClassNames.day,
         className,
       )}
@@ -1191,5 +232,9 @@ function CalendarDayButton({
   );
 }
 
-export { Calendar, CalendarDayButton };
-export type { CalendarProps };
+export {
+  Calendar,
+  CalendarDayButton,
+  type CalendarProps,
+  type CalendarDayButtonProps,
+};