Date and Time

/**
 * Provides date picker behavior and accessibility
 * @param props - Date picker configuration
 * @param state - Date picker state management
 * @param ref - Ref to the date picker element
 * @returns Date picker props and state
 */
function useDatePicker(props: AriaDatePickerProps, state: DatePickerState, ref: RefObject<Element>): DatePickerAria;

interface AriaDatePickerProps {
  /** Current date value */
  value?: DateValue | null;
  /** Default date value (uncontrolled) */
  defaultValue?: DateValue | null;
  /** Handler called when date changes */
  onChange?: (value: DateValue | null) => void;
  /** Minimum allowed date */
  minValue?: DateValue;
  /** Maximum allowed date */
  maxValue?: DateValue;
  /** Whether the picker is disabled */
  isDisabled?: boolean;
  /** Whether the picker is read-only */
  isReadOnly?: boolean;
  /** Whether the picker is required */
  isRequired?: boolean;
  /** Validation state */
  validationState?: 'valid' | 'invalid';
  /** Auto-focus behavior */
  autoFocus?: boolean;
  /** Date formatting options */
  granularity?: 'day' | 'hour' | 'minute' | 'second';
  /** Hide the time zone */
  hideTimeZone?: boolean;
  /** Hour cycle preference */
  hourCycle?: 12 | 24;
  /** Whether to show era for certain calendars */
  showEra?: boolean;
  /** Placeholder date to use when value is null */
  placeholderValue?: DateValue;
  /** Whether dates are disabled */
  isDateUnavailable?: (date: DateValue) => boolean;
}

interface DatePickerAria {
  /** Props for the date picker group element */
  groupProps: DOMAttributes<Element>;
  /** Props for the label element */
  labelProps: DOMAttributes<Element>;
  /** Props for the date field */
  fieldProps: DOMAttributes<Element>;
  /** Props for the calendar button */
  buttonProps: ButtonHTMLAttributes<HTMLButtonElement>;
  /** Props for the dialog element */
  dialogProps: DOMAttributes<Element>;
  /** Props for the calendar element */
  calendarProps: DOMAttributes<Element>;
  /** Props for the description element */
  descriptionProps: DOMAttributes<Element>;
  /** Props for the error message element */
  errorMessageProps: DOMAttributes<Element>;
  /** Whether the calendar is open */
  isOpen: boolean;
  /** Set the calendar open state */
  setOpen: (isOpen: boolean) => void;
}

/**
 * Provides date range picker behavior and accessibility
 * @param props - Date range picker configuration
 * @param state - Date range picker state
 * @param ref - Ref to the date range picker element
 * @returns Date range picker props and state
 */
function useDateRangePicker(props: AriaDateRangePickerProps, state: DateRangePickerState, ref: RefObject<Element>): DateRangePickerAria;

interface AriaDateRangePickerProps {
  /** Current date range value */
  value?: DateRange | null;
  /** Default date range value (uncontrolled) */
  defaultValue?: DateRange | null;
  /** Handler called when range changes */
  onChange?: (value: DateRange | null) => void;
  /** Minimum allowed date */
  minValue?: DateValue;
  /** Maximum allowed date */
  maxValue?: DateValue;
  /** Whether the picker is disabled */
  isDisabled?: boolean;
  /** Whether the picker is read-only */
  isReadOnly?: boolean;
  /** Whether the picker is required */
  isRequired?: boolean;
  /** Validation state */
  validationState?: 'valid' | 'invalid';
  /** Auto-focus behavior */
  autoFocus?: boolean;
  /** Whether dates are disabled */
  isDateUnavailable?: (date: DateValue) => boolean;
  /** Allow non-contiguous ranges */
  allowsNonContiguousRanges?: boolean;
}

interface DateRangePickerAria {
  /** Props for the date range picker group element */
  groupProps: DOMAttributes<Element>;
  /** Props for the label element */
  labelProps: DOMAttributes<Element>;
  /** Props for the start field */
  startFieldProps: DOMAttributes<Element>;
  /** Props for the end field */
  endFieldProps: DOMAttributes<Element>;
  /** Props for the calendar button */
  buttonProps: ButtonHTMLAttributes<HTMLButtonElement>;
  /** Props for the dialog element */
  dialogProps: DOMAttributes<Element>;
  /** Props for the range calendar element */
  calendarProps: DOMAttributes<Element>;
  /** Props for the description element */
  descriptionProps: DOMAttributes<Element>;
  /** Props for the error message element */
  errorMessageProps: DOMAttributes<Element>;
}

/**
 * Provides date field behavior and accessibility
 * @param props - Date field configuration
 * @param state - Date field state
 * @param ref - Ref to the date field element
 * @returns Date field props and state
 */
function useDateField(props: AriaDateFieldProps, state: DateFieldState, ref: RefObject<Element>): DateFieldAria;

/**
 * Provides date segment behavior for individual date parts
 * @param segment - Date segment information
 * @param state - Date field state
 * @param ref - Ref to the segment element
 * @returns Date segment props and state
 */
function useDateSegment(segment: DateSegment, state: DateFieldState, ref: RefObject<Element>): DateSegmentAria;

interface AriaDateFieldProps {
  /** Current date value */
  value?: DateValue | null;
  /** Default date value (uncontrolled) */
  defaultValue?: DateValue | null;
  /** Handler called when date changes */
  onChange?: (value: DateValue | null) => void;
  /** Minimum allowed date */
  minValue?: DateValue;
  /** Maximum allowed date */
  maxValue?: DateValue;
  /** Whether the field is disabled */
  isDisabled?: boolean;
  /** Whether the field is read-only */
  isReadOnly?: boolean;
  /** Whether the field is required */
  isRequired?: boolean;
  /** Validation state */
  validationState?: 'valid' | 'invalid';
  /** Auto-focus behavior */
  autoFocus?: boolean;
  /** Date formatting options */
  granularity?: 'day' | 'hour' | 'minute' | 'second';
  /** Hide the time zone */
  hideTimeZone?: boolean;
  /** Hour cycle preference */
  hourCycle?: 12 | 24;
  /** Whether to show era */
  showEra?: boolean;
  /** Placeholder date to use when value is null */
  placeholderValue?: DateValue;
  /** Locale for formatting */
  locale?: string;
  /** Date formatting options */
  formatOptions?: Intl.DateTimeFormatOptions;
}

interface DateFieldAria {
  /** Props for the label element */
  labelProps: DOMAttributes<Element>;
  /** Props for the field group element */
  fieldProps: DOMAttributes<Element>;
  /** Props for the description element */
  descriptionProps: DOMAttributes<Element>;
  /** Props for the error message element */
  errorMessageProps: DOMAttributes<Element>;
}

interface DateSegmentAria {
  /** Props for the segment element */
  segmentProps: DOMAttributes<Element>;
}

/**
 * Provides time field behavior and accessibility
 * @param props - Time field configuration
 * @param state - Time field state
 * @param ref - Ref to the time field element
 * @returns Time field props and state
 */
function useTimeField(props: AriaTimeFieldProps, state: TimeFieldState, ref: RefObject<Element>): TimeFieldAria;

interface AriaTimeFieldProps {
  /** Current time value */
  value?: TimeValue | null;
  /** Default time value (uncontrolled) */
  defaultValue?: TimeValue | null;
  /** Handler called when time changes */
  onChange?: (value: TimeValue | null) => void;
  /** Minimum allowed time */
  minValue?: TimeValue;
  /** Maximum allowed time */
  maxValue?: TimeValue;
  /** Whether the field is disabled */
  isDisabled?: boolean;
  /** Whether the field is read-only */
  isReadOnly?: boolean;
  /** Whether the field is required */
  isRequired?: boolean;
  /** Validation state */
  validationState?: 'valid' | 'invalid';
  /** Auto-focus behavior */
  autoFocus?: boolean;
  /** Time granularity */
  granularity?: 'hour' | 'minute' | 'second';
  /** Hide the time zone */
  hideTimeZone?: boolean;
  /** Hour cycle preference */
  hourCycle?: 12 | 24;
  /** Placeholder time to use when value is null */
  placeholderValue?: TimeValue;
}

interface TimeFieldAria {
  /** Props for the label element */
  labelProps: DOMAttributes<Element>;
  /** Props for the field group element */
  fieldProps: DOMAttributes<Element>;
  /** Props for the description element */
  descriptionProps: DOMAttributes<Element>;
  /** Props for the error message element */
  errorMessageProps: DOMAttributes<Element>;
}

/**
 * Provides calendar behavior and accessibility
 * @param props - Calendar configuration
 * @param state - Calendar state
 * @param ref - Ref to the calendar element
 * @returns Calendar props and state
 */
function useCalendar(props: AriaCalendarProps, state: CalendarState, ref: RefObject<Element>): CalendarAria;

/**
 * Provides calendar grid behavior for the days grid
 * @param props - Calendar grid configuration
 * @param state - Calendar state
 * @param ref - Ref to the grid element
 * @returns Calendar grid props
 */
function useCalendarGrid(props: AriaCalendarGridProps, state: CalendarState, ref: RefObject<Element>): CalendarGridAria;

/**
 * Provides calendar cell behavior for individual date cells
 * @param props - Calendar cell configuration
 * @param state - Calendar state
 * @param ref - Ref to the cell element
 * @returns Calendar cell props and state
 */
function useCalendarCell(props: AriaCalendarCellProps, state: CalendarState, ref: RefObject<Element>): CalendarCellAria;

interface AriaCalendarProps extends CalendarProps {
  /** Current selected date(s) */
  value?: DateValue | DateRange | null;
  /** Default selected date(s) (uncontrolled) */
  defaultValue?: DateValue | DateRange | null;
  /** Handler called when selection changes */
  onChange?: (value: DateValue | DateRange | null) => void;
  /** Currently focused date */
  focusedValue?: DateValue;
  /** Default focused date (uncontrolled) */
  defaultFocusedValue?: DateValue;
  /** Handler called when focus changes */
  onFocusChange?: (value: DateValue) => void;
  /** Minimum allowed date */
  minValue?: DateValue;
  /** Maximum allowed date */
  maxValue?: DateValue;
  /** Whether the calendar is disabled */
  isDisabled?: boolean;
  /** Whether the calendar is read-only */
  isReadOnly?: boolean;
  /** Auto-focus behavior */
  autoFocus?: boolean;
  /** Whether dates are unavailable */
  isDateUnavailable?: (date: DateValue) => boolean;
  /** Validation state */
  validationState?: 'valid' | 'invalid';
  /** Error message */
  errorMessage?: ReactNode;
}

interface CalendarAria {
  /** Props for the calendar element */
  calendarProps: DOMAttributes<Element>;
  /** Props for the title element */
  titleProps: DOMAttributes<Element>;
  /** Props for the previous button */
  prevButtonProps: ButtonHTMLAttributes<HTMLButtonElement>;
  /** Props for the next button */
  nextButtonProps: ButtonHTMLAttributes<HTMLButtonElement>;
  /** Props for the error message element */
  errorMessageProps: DOMAttributes<Element>;
}

/**
 * Provides range calendar behavior and accessibility
 * @param props - Range calendar configuration
 * @param state - Range calendar state
 * @param ref - Ref to the calendar element
 * @returns Range calendar props and state
 */
function useRangeCalendar(props: AriaRangeCalendarProps, state: RangeCalendarState, ref: RefObject<Element>): CalendarAria;

interface AriaRangeCalendarProps extends RangeCalendarProps {
  /** Current selected range */
  value?: DateRange | null;
  /** Default selected range (uncontrolled) */
  defaultValue?: DateRange | null;
  /** Handler called when range changes */
  onChange?: (value: DateRange | null) => void;
  /** Currently focused date */
  focusedValue?: DateValue;
  /** Default focused date (uncontrolled) */
  defaultFocusedValue?: DateValue;
  /** Handler called when focus changes */
  onFocusChange?: (value: DateValue) => void;
  /** Minimum allowed date */
  minValue?: DateValue;
  /** Maximum allowed date */
  maxValue?: DateValue;
  /** Whether the calendar is disabled */
  isDisabled?: boolean;
  /** Whether the calendar is read-only */
  isReadOnly?: boolean;
  /** Auto-focus behavior */
  autoFocus?: boolean;
  /** Whether dates are unavailable */
  isDateUnavailable?: (date: DateValue) => boolean;
  /** Allow non-contiguous ranges */
  allowsNonContiguousRanges?: boolean;
  /** Validation state */
  validationState?: 'valid' | 'invalid';
}

interface DateValue {
  /** Calendar system */
  calendar: Calendar;
  /** Era */
  era?: string;
  /** Year */
  year: number;
  /** Month (1-based) */
  month: number;
  /** Day */
  day: number;
  /** Convert to native Date object */
  toDate(timeZone: string): Date;
  /** Get formatted string */
  toString(): string;
  /** Compare to another date */
  compare(other: DateValue): number;
}

interface TimeValue {
  /** Hour (24-hour format) */
  hour: number;
  /** Minute */
  minute: number;
  /** Second */
  second?: number;
  /** Millisecond */
  millisecond?: number;
  /** Convert to string */
  toString(): string;
  /** Compare to another time */
  compare(other: TimeValue): number;
}

interface DateRange {
  /** Start date */
  start: DateValue;
  /** End date */
  end: DateValue;
}

interface DateSegment {
  /** Type of segment */
  type: 'literal' | 'year' | 'month' | 'day' | 'hour' | 'minute' | 'second' | 'dayPeriod' | 'era' | 'timeZoneName';
  /** Display text */
  text: string;
  /** Current value */
  value?: number;
  /** Minimum value */
  minValue?: number;
  /** Maximum value */
  maxValue?: number;
  /** Whether segment is placeholder */
  isPlaceholder: boolean;
  /** Whether segment is editable */
  isEditable: boolean;
}

interface DateFieldState {
  /** Current date value */
  value: DateValue | null;
  /** Set the date value */
  setValue(value: DateValue | null): void;
  /** Date segments */
  segments: DateSegment[];
  /** Currently focused segment */
  focusedSegment: number | null;
  /** Set the focused segment */
  setFocusedSegment(index: number | null): void;
  /** Increment a segment */
  increment(index: number): void;
  /** Decrement a segment */
  decrement(index: number): void;
  /** Set segment value */
  setSegment(index: number, value: number): void;
  /** Clear the value */
  clearSegment(index: number): void;
  /** Whether the field is invalid */
  isInvalid: boolean;
  /** Validation state */
  validationState: 'valid' | 'invalid';
}

interface CalendarState {
  /** Current date value */
  value: DateValue | DateRange | null;
  /** Set the date value */
  setValue(value: DateValue | DateRange | null): void;
  /** Currently focused date */
  focusedDate: DateValue;
  /** Set the focused date */
  setFocusedDate(date: DateValue): void;
  /** Navigate to previous month */
  focusPreviousPage(): void;
  /** Navigate to next month */
  focusNextPage(): void;
  /** Navigate to previous year */
  focusPreviousYear(): void;
  /** Navigate to next year */
  focusNextYear(): void;
  /** Select a date */
  selectDate(date: DateValue): void;
  /** Whether a date is selected */
  isSelected(date: DateValue): boolean;
  /** Whether a date is focused */
  isFocused(date: DateValue): boolean;
  /** Whether a date is disabled */
  isDisabled(date: DateValue): boolean;
  /** Whether a date is unavailable */
  isUnavailable(date: DateValue): boolean;
}