Core Functionality

/**
 * Main DatePicker component providing comprehensive date selection interface
 * Supports single dates, ranges, multiple selection, time picking, and extensive customization
 */
function DatePicker(props: DatePickerProps): React.ReactElement;

interface DatePickerProps {
  // Core date selection
  selected?: Date | null;
  onChange?: (
    date: Date | null | [Date | null, Date | null] | Date[], 
    event?: React.MouseEvent | React.KeyboardEvent
  ) => void;
  
  // Selection modes
  selectsRange?: boolean;
  selectsMultiple?: boolean;
  
  // Date range specific
  startDate?: Date | null;
  endDate?: Date | null;
  swapRange?: boolean;
  
  // Multiple selection specific  
  selectedDates?: Date[];
  
  // Date constraints
  minDate?: Date;
  maxDate?: Date;
  excludeDates?: Date[];
  includeDates?: Date[];
  excludeDateIntervals?: Array<{start: Date, end: Date}>;
  includeDateIntervals?: Array<{start: Date, end: Date}>;
  filterDate?: (date: Date) => boolean;
  
  // Display and formatting
  dateFormat?: string | string[];
  dateFormatCalendar?: string;
  locale?: Locale;
  inline?: boolean;
  fixedHeight?: boolean;
  
  // Time selection
  showTimeSelect?: boolean;
  showTimeSelectOnly?: boolean;
  showTimeInput?: boolean;
  timeFormat?: string;
  timeIntervals?: number;
  minTime?: Date;
  maxTime?: Date;
  excludeTimes?: Date[];
  includeTimes?: Date[];
  injectTimes?: Date[];
  filterTime?: (time: Date) => boolean;
  timeCaption?: string;
  timeInputLabel?: string;
  
  // Calendar display options
  showMonthDropdown?: boolean;
  showYearDropdown?: boolean;
  showMonthYearDropdown?: boolean;
  showFullMonthYearPicker?: boolean;
  showTwoColumnMonthYearPicker?: boolean;
  showFourColumnMonthYearPicker?: boolean;
  showYearPicker?: boolean;
  showQuarterYearPicker?: boolean;
  showWeekPicker?: boolean;
  showWeekNumbers?: boolean;
  weekLabel?: string;
  
  // Month/Year navigation
  monthsShown?: number;
  dropdownMode?: "scroll" | "select";
  yearItemNumber?: number;
  minYear?: number;
  maxYear?: number;
  
  // Highlighting and special dates
  highlightDates?: Array<Date | HighlightDate>;
  holidays?: Holiday[];
  
  // Interaction behavior
  shouldCloseOnSelect?: boolean;
  preventOpenOnFocus?: boolean;
  openToDate?: Date;
  startOpen?: boolean;
  allowSameDay?: boolean;
  selectsDisabledDaysInRange?: boolean;
  adjustDateOnChange?: boolean;
  
  // Accessibility
  ariaLabelledBy?: string;
  ariaDescribedBy?: string;
  ariaRequired?: string;
  ariaInvalid?: string;
  ariaLabelClose?: string;
  
  // Form integration
  id?: string;
  name?: string;
  required?: boolean;
  disabled?: boolean;
  readOnly?: boolean;
  autoComplete?: string;
  autoFocus?: boolean;
  tabIndex?: number;
  form?: string;
  title?: string;
  placeholderText?: string;
  value?: string;
  
  // Events
  onFocus?: (event: React.FocusEvent) => void;
  onBlur?: (event: React.FocusEvent) => void;
  onKeyDown?: (event: React.KeyboardEvent) => void;
  onClick?: () => void;
  onInputClick?: () => void;
  onSelect?: (date: Date | null, event?: React.SyntheticEvent) => void;
  onChangeRaw?: (event?: React.SyntheticEvent) => void;
  onCalendarOpen?: () => void;
  onCalendarClose?: () => void;
  onClickOutside?: (event: MouseEvent) => void;
  onInputError?: (error: {code: number, msg: string}) => void;
  
  // Styling and customization
  className?: string;
  wrapperClassName?: string;
  calendarClassName?: string;
  popperClassName?: string;
  dayClassName?: (date: Date) => string | null;
  weekDayClassName?: (date: Date) => string | null;
  monthClassName?: (date: Date) => string | null;
  timeClassName?: (time: Date) => string | null;
  
  // Custom components
  customInput?: React.ReactElement;
  customInputRef?: string;
  calendarContainer?: React.ComponentType;
  customTimeInput?: React.ComponentType;
  renderCustomHeader?: (params: ReactDatePickerCustomHeaderProps) => React.ReactNode;
  renderDayContents?: (dayOfMonth: number, date: Date) => React.ReactNode;
  
  // Portal and positioning
  withPortal?: boolean;
  portalId?: string;
  popperContainer?: React.ComponentType;
  popperPlacement?: string;
  popperModifiers?: object[];
  hidePopper?: boolean;
  showPopperArrow?: boolean;
  
  // Icon and clearing
  showIcon?: boolean;
  icon?: React.ReactNode;
  calendarIconClassName?: string;
  toggleCalendarOnIconClick?: boolean;
  isClearable?: boolean;
  clearButtonTitle?: string;
  clearButtonClassName?: string;
  
  // Advanced options
  closeOnScroll?: boolean | ((event: Event) => boolean);
  enableTabLoop?: boolean;
  disabledKeyboardNavigation?: boolean;
  calendarStartDay?: number;
  usePointerEvent?: boolean;
  excludeScrollbar?: boolean;
  useWeekdaysShort?: boolean;
  formatWeekDay?: (day: string) => string;
  strictParsing?: boolean;
  monthSelectedIn?: number;
  focusSelectedMonth?: boolean;
  showPreviousMonths?: boolean;
  
  // Navigation labels (for accessibility)
  previousMonthAriaLabel?: string;
  previousMonthButtonLabel?: string;
  nextMonthAriaLabel?: string;
  nextMonthButtonLabel?: string;
  previousYearAriaLabel?: string;
  previousYearButtonLabel?: string;
  nextYearAriaLabel?: string;
  nextYearButtonLabel?: string;
  
  // Children (for calendar content)
  children?: React.ReactNode;
}

import React, { useState } from "react";
import DatePicker from "react-datepicker";
import "react-datepicker/dist/react-datepicker.css";

// Basic single date picker
function BasicDatePicker() {
  const [startDate, setStartDate] = useState<Date | null>(new Date());
  
  return (
    <DatePicker
      selected={startDate}
      onChange={(date) => setStartDate(date)}
      dateFormat="MM/dd/yyyy"
      placeholderText="Select a date"
    />
  );
}

// Date range picker
function DateRangePicker() {
  const [startDate, setStartDate] = useState<Date | null>(null);
  const [endDate, setEndDate] = useState<Date | null>(null);

  return (
    <DatePicker
      selected={startDate}
      onChange={(dates: [Date | null, Date | null]) => {
        const [start, end] = dates;
        setStartDate(start);
        setEndDate(end);
      }}
      startDate={startDate}
      endDate={endDate}
      selectsRange
      placeholderText="Select date range"
    />
  );
}

// Multiple date selection
function MultipleDatePicker() {
  const [selectedDates, setSelectedDates] = useState<Date[]>([]);

  return (
    <DatePicker
      selectedDates={selectedDates}
      onChange={(dates: Date[]) => setSelectedDates(dates)}
      selectsMultiple
      shouldCloseOnSelect={false}
      placeholderText="Select multiple dates"
    />
  );
}

// Date and time picker
function DateTimePicker() {
  const [startDate, setStartDate] = useState<Date | null>(new Date());

  return (
    <DatePicker
      selected={startDate}
      onChange={(date) => setStartDate(date)}
      showTimeSelect
      timeFormat="HH:mm"
      timeIntervals={15}
      timeCaption="Time"
      dateFormat="MM/dd/yyyy HH:mm"
    />
  );
}

// Inline calendar
function InlineCalendar() {
  const [startDate, setStartDate] = useState<Date | null>(new Date());

  return (
    <DatePicker
      selected={startDate}
      onChange={(date) => setStartDate(date)}
      inline
    />
  );
}

// Custom input
function CustomInputExample() {
  const [startDate, setStartDate] = useState<Date | null>(null);
  
  const CustomInput = React.forwardRef<HTMLButtonElement, any>(
    ({ value, onClick }, ref) => (
      <button className="custom-input" onClick={onClick} ref={ref}>
        {value || "Click to select date"}
      </button>
    )
  );

  return (
    <DatePicker
      selected={startDate}
      onChange={(date) => setStartDate(date)}
      customInput={<CustomInput />}
    />
  );
}

// Advanced filtering
function FilteredDatePicker() {
  const [startDate, setStartDate] = useState<Date | null>(null);
  
  // Only allow weekdays
  const isWeekday = (date: Date) => {
    const day = date.getDay();
    return day !== 0 && day !== 6;
  };

  return (
    <DatePicker
      selected={startDate}
      onChange={(date) => setStartDate(date)}
      filterDate={isWeekday}
      placeholderText="Select a weekday"
    />
  );
}

/**
 * Container component for calendar with accessibility support
 * Provides proper ARIA roles and labels for screen reader compatibility
 */
function CalendarContainer(props: CalendarContainerProps): React.ReactElement;

interface CalendarContainerProps extends React.HTMLAttributes<HTMLDivElement> {
  showTimeSelectOnly?: boolean;
  showTime?: boolean;
  children?: React.ReactNode;
}

import { CalendarContainer } from "react-datepicker";

function CustomCalendarContainer({ className, children, ...props }) {
  return (
    <div className={`custom-calendar-wrapper ${className}`}>
      <CalendarContainer {...props}>
        <div className="calendar-header">Custom Header</div>
        {children}
        <div className="calendar-footer">Custom Footer</div>
      </CalendarContainer>
    </div>
  );
}

// Use with DatePicker
function DatePickerWithCustomContainer() {
  const [date, setDate] = useState<Date | null>(null);
  
  return (
    <DatePicker
      selected={date}
      onChange={setDate}
      calendarContainer={CustomCalendarContainer}
    />
  );
}

/**
 * Props interface for custom calendar header components
 * Provides access to calendar state and navigation functions
 */
interface ReactDatePickerCustomHeaderProps {
  /** Current calendar date */
  date: Date;
  /** Number of custom headers (for multi-month displays) */
  customHeaderCount: number;  
  /** Current month date */
  monthDate: Date;
  /** Function to change month (0-11) */
  changeMonth: (month: number) => void;
  /** Function to change year */
  changeYear: (year: number) => void;
  /** Function to go to previous month */
  decreaseMonth: () => void;
  /** Function to go to next month */
  increaseMonth: () => void;
  /** Function to go to previous year */
  decreaseYear: () => void;
  /** Function to go to next year */
  increaseYear: () => void;
  /** Whether previous month navigation is disabled */
  prevMonthButtonDisabled: boolean;
  /** Whether next month navigation is disabled */
  nextMonthButtonDisabled: boolean;
  /** Whether previous year navigation is disabled */
  prevYearButtonDisabled: boolean;
  /** Whether next year navigation is disabled */
  nextYearButtonDisabled: boolean;
  /** Visible years range for year picker */
  visibleYearsRange?: {
    startYear: number;
    endYear: number;
  };
}

function CustomHeader({
  date,
  changeYear,
  changeMonth,
  decreaseMonth,
  increaseMonth,
  prevMonthButtonDisabled,
  nextMonthButtonDisabled,
}: ReactDatePickerCustomHeaderProps) {
  return (
    <div className="custom-header">
      <button onClick={decreaseMonth} disabled={prevMonthButtonDisabled}>
        {"<"}
      </button>
      <select
        value={date.getFullYear()}
        onChange={({ target: { value } }) => changeYear(parseInt(value))}
      >
        {Array.from({ length: 10 }, (_, i) => (
          <option key={i} value={date.getFullYear() - 5 + i}>
            {date.getFullYear() - 5 + i}
          </option>
        ))}
      </select>
      <select
        value={date.getMonth()}
        onChange={({ target: { value } }) => changeMonth(parseInt(value))}
      >
        {Array.from({ length: 12 }, (_, i) => (
          <option key={i} value={i}>
            {new Date(0, i).toLocaleDateString("en", { month: "long" })}
          </option>
        ))}
      </select>
      <button onClick={increaseMonth} disabled={nextMonthButtonDisabled}>
        {">"}
      </button>
    </div>
  );
}

// Use with DatePicker
function DatePickerWithCustomHeader() {
  const [date, setDate] = useState<Date | null>(new Date());
  
  return (
    <DatePicker
      selected={date}
      onChange={setDate}
      renderCustomHeader={CustomHeader}
    />
  );
}