@neynar/ui 0.1.1 → 0.1.3

package/src/components/ui/calendar.tsx

@@ -4,11 +4,671 @@ import {
   ChevronLeftIcon,
   ChevronRightIcon,
 } from "lucide-react";
-import { DayButton, DayPicker, getDefaultClassNames } from "react-day-picker";
+import {
+  DayButton,
+  DayPicker,
+  getDefaultClassNames,
+  type DateRange,
+  type Matcher,
+} from "react-day-picker";
+import type { Locale } from "date-fns";
 
 import { cn } from "@/lib/utils";
 import { Button, buttonVariants } from "@/components/ui/button";
 
+/**
+ * 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";
+};
+
 /**
  * Calendar - A comprehensive date selection calendar component
  *
@@ -16,6 +676,10 @@ import { Button, buttonVariants } from "@/components/ui/button";
  * 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
@@ -43,7 +707,7 @@ import { Button, buttonVariants } from "@/components/ui/button";
  * />
  * ```
  *
- * @example Multiple date selection
+ * @example Multiple date selection with limits
  * ```tsx
  * const [dates, setDates] = useState<Date[] | undefined>()
  *
@@ -51,6 +715,8 @@ import { Button, buttonVariants } from "@/components/ui/button";
  *   mode="multiple"
  *   selected={dates}
  *   onSelect={setDates}
+ *   min={2} // Minimum 2 dates required
+ *   max={5} // Maximum 5 dates allowed
  *   className="rounded-md border"
  * />
  * ```
@@ -70,7 +736,7 @@ import { Button, buttonVariants } from "@/components/ui/button";
  * />
  * ```
  *
- * @example Calendar with month/year dropdowns
+ * @example Calendar with month/year dropdowns and navigation limits
  * ```tsx
  * <Calendar
  *   mode="single"
@@ -79,36 +745,194 @@ import { Button, buttonVariants } from "@/components/ui/button";
  *   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
- * - **Navigation**: Month/year navigation with keyboard support
- * - **Validation**: Flexible date disabling and validation rules
- * - **Customization**: Multiple caption layouts, button variants, styling
- * - **Internationalization**: Built-in locale support via react-day-picker
- * - **Accessibility**: Full WCAG compliance with keyboard navigation
+ * - **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 for date navigation, Page Up/Down for months
- * - **Screen Reader Support**: Comprehensive ARIA labels and announcements
- * - **Focus Management**: Proper focus handling and restoration
- * - **Standards Compliance**: WCAG 2.1 AA compliant
- * - **RTL Support**: Right-to-left language support
+ * - **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
- * The component is optimized for performance with minimal re-renders and efficient
- * DOM updates. Large date ranges and multiple months are handled efficiently.
+ * - **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
- * Fully customizable with Tailwind CSS classes. Supports CSS custom properties
- * for cell sizing (`--cell-size`) and integrates with the design system theme.
+ * - **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
- * @see [react-day-picker docs](https://react-day-picker.js.org/) for advanced configuration
- * @see {@link https://ui.shadcn.com/docs/components/calendar} - shadcn/ui Calendar documentation
+ * @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
  */
 function Calendar({
@@ -120,25 +944,7 @@ function Calendar({
   formatters,
   components,
   ...props
-}: React.ComponentProps<typeof DayPicker> & {
-  /**
-   * 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?: React.ComponentProps<typeof Button>["variant"];
-}) {
+}: CalendarProps) {
   const defaultClassNames = getDefaultClassNames();
 
   return (
@@ -241,7 +1047,14 @@ function Calendar({
         ...classNames,
       }}
       components={{
-        Root: ({ className, rootRef, ...props }: { className?: string; rootRef?: React.Ref<HTMLDivElement> } & React.ComponentProps<"div">) => {
+        Root: ({
+          className,
+          rootRef,
+          ...props
+        }: {
+          className?: string;
+          rootRef?: React.Ref<HTMLDivElement>;
+        } & React.ComponentProps<"div">) => {
           return (
             <div
               data-slot="calendar"
@@ -251,7 +1064,14 @@ function Calendar({
             />
           );
         },
-        Chevron: ({ className, orientation, ...props }: { className?: string; orientation?: "left" | "right" | "up" | "down" } & React.ComponentProps<"svg">) => {
+        Chevron: ({
+          className,
+          orientation,
+          ...props
+        }: {
+          className?: string;
+          orientation?: "left" | "right" | "up" | "down";
+        } & React.ComponentProps<"svg">) => {
           if (orientation === "left") {
             return (
               <ChevronLeftIcon className={cn("size-4", className)} {...props} />
@@ -272,7 +1092,10 @@ function Calendar({
           );
         },
         DayButton: CalendarDayButton,
-        WeekNumber: ({ children, ...props }) => {
+        WeekNumber: ({
+          children,
+          ...props
+        }: React.ComponentProps<"td"> & { children?: React.ReactNode }) => {
           return (
             <td {...props}>
               <div className="flex size-(--cell-size) items-center justify-center text-center">
@@ -369,3 +1192,4 @@ function CalendarDayButton({
 }
 
 export { Calendar, CalendarDayButton };
+export type { CalendarProps };