Date & Time

/**
 * Date picker with calendar popup and locale support
 * @param props - DatePicker configuration and value properties
 * @returns JSX element as date picker
 */
function DatePicker(props: SpectrumDatePickerProps): JSX.Element;

interface SpectrumDatePickerProps extends DOMProps, StyleProps {
  /** Date picker label */
  label?: React.ReactNode;
  /** Current date value */
  value?: DateValue;
  /** Default date value */
  defaultValue?: DateValue;
  /** Placeholder text */
  placeholder?: string;
  /** Description text */
  description?: React.ReactNode;
  /** Error message */
  errorMessage?: React.ReactNode;
  /** Minimum selectable date */
  minValue?: DateValue;
  /** Maximum selectable date */
  maxValue?: DateValue;
  /** Function to determine unavailable dates */
  isDateUnavailable?: (date: DateValue) => boolean;
  /** Whether date picker is disabled */
  isDisabled?: boolean;
  /** Whether date picker is required */
  isRequired?: boolean;
  /** Whether date picker is read-only */
  isReadOnly?: boolean;
  /** Auto-focus the input */
  autoFocus?: boolean;
  /** Date change handler */
  onChange?: (date: DateValue) => void;
  /** Focus change handler */
  onFocusChange?: (isFocused: boolean) => void;
  /** Open state change handler */
  onOpenChange?: (isOpen: boolean) => void;
}

/**
 * Date range picker for selecting start and end dates
 * @param props - DateRangePicker configuration and range properties
 * @returns JSX element as date range picker
 */
function DateRangePicker(props: SpectrumDateRangePickerProps): JSX.Element;

interface SpectrumDateRangePickerProps extends DOMProps, StyleProps {
  /** Date range picker label */
  label?: React.ReactNode;
  /** Current date range value */
  value?: DateRange;
  /** Default date range value */
  defaultValue?: DateRange;
  /** Placeholder text */
  placeholder?: string;
  /** Description text */
  description?: React.ReactNode;
  /** Error message */
  errorMessage?: React.ReactNode;
  /** Minimum selectable date */
  minValue?: DateValue;
  /** Maximum selectable date */
  maxValue?: DateValue;
  /** Function to determine unavailable dates */
  isDateUnavailable?: (date: DateValue) => boolean;
  /** Whether range picker is disabled */
  isDisabled?: boolean;
  /** Whether range picker is required */
  isRequired?: boolean;
  /** Whether range picker is read-only */
  isReadOnly?: boolean;
  /** Auto-focus the start input */
  autoFocus?: boolean;
  /** Allow selecting same date for start and end */
  allowsNonContiguousRanges?: boolean;
  /** Date range change handler */
  onChange?: (range: DateRange) => void;
  /** Focus change handler */
  onFocusChange?: (isFocused: boolean) => void;
  /** Open state change handler */
  onOpenChange?: (isOpen: boolean) => void;
}

/**
 * Text input for date entry with parsing and validation
 * @param props - DateField configuration and formatting properties
 * @returns JSX element as date text input
 */
function DateField(props: SpectrumDateFieldProps): JSX.Element;

interface SpectrumDateFieldProps extends DOMProps, StyleProps {
  /** Date field label */
  label?: React.ReactNode;
  /** Current date value */
  value?: DateValue;
  /** Default date value */
  defaultValue?: DateValue;
  /** Placeholder text */
  placeholder?: string;
  /** Description text */
  description?: React.ReactNode;
  /** Error message */
  errorMessage?: React.ReactNode;
  /** Minimum allowed date */
  minValue?: DateValue;
  /** Maximum allowed date */
  maxValue?: DateValue;
  /** Whether field is disabled */
  isDisabled?: boolean;
  /** Whether field is required */
  isRequired?: boolean;
  /** Whether field is read-only */
  isReadOnly?: boolean;
  /** Auto-focus the field */
  autoFocus?: boolean;
  /** Date change handler */
  onChange?: (date: DateValue) => void;
  /** Focus change handler */
  onFocusChange?: (isFocused: boolean) => void;
}

/**
 * Time input with hour, minute, and optional second fields
 * @param props - TimeField configuration and time properties
 * @returns JSX element as time input
 */
function TimeField(props: SpectrumTimeFieldProps): JSX.Element;

interface SpectrumTimeFieldProps extends DOMProps, StyleProps {
  /** Time field label */
  label?: React.ReactNode;
  /** Current time value */
  value?: TimeValue;
  /** Default time value */
  defaultValue?: TimeValue;
  /** Placeholder text */
  placeholder?: string;
  /** Description text */
  description?: React.ReactNode;
  /** Error message */
  errorMessage?: React.ReactNode;
  /** Minimum allowed time */
  minValue?: TimeValue;
  /** Maximum allowed time */
  maxValue?: TimeValue;
  /** Time granularity (hour, minute, second) */
  granularity?: "hour" | "minute" | "second";
  /** Hour cycle (12 or 24 hour) */
  hourCycle?: 12 | 24;
  /** Whether field is disabled */
  isDisabled?: boolean;
  /** Whether field is required */
  isRequired?: boolean;
  /** Whether field is read-only */
  isReadOnly?: boolean;
  /** Auto-focus the field */
  autoFocus?: boolean;
  /** Time change handler */
  onChange?: (time: TimeValue) => void;
  /** Focus change handler */
  onFocusChange?: (isFocused: boolean) => void;
}

/**
 * Calendar display for date visualization and selection
 * @param props - Calendar configuration and navigation properties
 * @returns JSX element as calendar display
 */
function Calendar(props: SpectrumCalendarProps): JSX.Element;

interface SpectrumCalendarProps extends DOMProps, StyleProps {
  /** Current date value */
  value?: DateValue;
  /** Default date value */
  defaultValue?: DateValue;
  /** Focused date for keyboard navigation */
  focusedValue?: DateValue;
  /** Default focused date */
  defaultFocusedValue?: DateValue;
  /** Minimum selectable date */
  minValue?: DateValue;
  /** Maximum selectable date */
  maxValue?: DateValue;
  /** Function to determine unavailable dates */
  isDateUnavailable?: (date: DateValue) => boolean;
  /** Whether calendar is disabled */
  isDisabled?: boolean;
  /** Whether calendar is read-only */
  isReadOnly?: boolean;
  /** Auto-focus the calendar */
  autoFocus?: boolean;
  /** Date selection handler */
  onChange?: (date: DateValue) => void;
  /** Focus change handler */
  onFocusChange?: (date: DateValue) => void;
}

/**
 * Calendar for selecting date ranges with start and end dates
 * @param props - RangeCalendar configuration and range properties
 * @returns JSX element as range calendar
 */
function RangeCalendar(props: SpectrumRangeCalendarProps): JSX.Element;

interface SpectrumRangeCalendarProps extends DOMProps, StyleProps {
  /** Current date range value */
  value?: DateRange;
  /** Default date range value */
  defaultValue?: DateRange;
  /** Focused date for keyboard navigation */
  focusedValue?: DateValue;
  /** Default focused date */
  defaultFocusedValue?: DateValue;
  /** Minimum selectable date */
  minValue?: DateValue;
  /** Maximum selectable date */
  maxValue?: DateValue;
  /** Function to determine unavailable dates */
  isDateUnavailable?: (date: DateValue) => boolean;
  /** Whether calendar is disabled */
  isDisabled?: boolean;
  /** Whether calendar is read-only */
  isReadOnly?: boolean;
  /** Auto-focus the calendar */
  autoFocus?: boolean;
  /** Allow non-contiguous date ranges */
  allowsNonContiguousRanges?: boolean;
  /** Date range selection handler */
  onChange?: (range: DateRange) => void;
  /** Focus change handler */
  onFocusChange?: (date: DateValue) => void;
}

function EventDatePicker() {
  const [eventDate, setEventDate] = useState(null);
  
  return (
    <DatePicker
      label="Event Date"
      value={eventDate}
      onChange={setEventDate}
      minValue={today(getLocalTimeZone())}
      description="Select a future date for your event"
    />
  );
}

function BookingDateRange() {
  const [dateRange, setDateRange] = useState({
    start: today(getLocalTimeZone()),
    end: today(getLocalTimeZone()).add({ days: 7 })
  });

  return (
    <DateRangePicker
      label="Booking Period"
      value={dateRange}
      onChange={setDateRange}
      minValue={today(getLocalTimeZone())}
      isDateUnavailable={(date) => {
        // Block weekends
        const dayOfWeek = date.toDate(getLocalTimeZone()).getDay();
        return dayOfWeek === 0 || dayOfWeek === 6;
      }}
    />
  );
}

function MeetingScheduler() {
  const [startTime, setStartTime] = useState(new Time(9, 0));
  const [endTime, setEndTime] = useState(new Time(10, 0));

  return (
    <Flex direction="column" gap="size-200">
      <TimeField
        label="Start Time"
        value={startTime}
        onChange={setStartTime}
        hourCycle={24}
      />
      <TimeField
        label="End Time"
        value={endTime}
        onChange={setEndTime}
        minValue={startTime}
        hourCycle={24}
      />
    </Flex>
  );
}

function AppointmentForm() {
  const [date, setDate] = useState(null);
  const [time, setTime] = useState(null);
  const [duration, setDuration] = useState(60);

  return (
    <Form>
      <DatePicker
        label="Appointment Date"
        value={date}
        onChange={setDate}
        minValue={today(getLocalTimeZone())}
        isRequired
      />
      
      <TimeField
        label="Start Time"
        value={time}
        onChange={setTime}
        granularity="minute"
        isRequired
      />
      
      <NumberField
        label="Duration (minutes)"
        value={duration}
        onChange={setDuration}
        minValue={15}
        maxValue={240}
        step={15}
      />
      
      <Button type="submit" variant="accent">
        Schedule Appointment
      </Button>
    </Form>
  );
}

/** Base date value interface */
interface DateValue {
  /** Calendar system */
  calendar: Calendar;
  /** Year */
  year: number;
  /** Month (1-12) */
  month: number;
  /** Day of month */
  day: number;
  /** Convert to JavaScript Date */
  toDate(timeZone: string): Date;
  /** Add duration */
  add(duration: DateDuration): DateValue;
  /** Subtract duration */
  subtract(duration: DateDuration): DateValue;
  /** Compare dates */
  compare(other: DateValue): number;
}

/** Time value interface */
interface TimeValue {
  /** Hour (0-23) */
  hour: number;
  /** Minute (0-59) */
  minute: number;
  /** Second (0-59) */
  second?: number;
  /** Millisecond (0-999) */
  millisecond?: number;
}

/** Date range interface */
interface DateRange {
  /** Range start date */
  start: DateValue;
  /** Range end date */
  end: DateValue;
}

/** Date duration for calculations */
interface DateDuration {
  /** Years to add/subtract */
  years?: number;
  /** Months to add/subtract */
  months?: number;
  /** Weeks to add/subtract */
  weeks?: number;
  /** Days to add/subtract */
  days?: number;
}

/** Calendar system types */
type CalendarSystem = "gregory" | "japanese" | "buddhist" | "roc" | "persian" | "indian" | "islamic-umalqura" | "islamic-tabular" | "islamic-civil" | "islamic-rgsa" | "iso8601" | "hebrew" | "coptic" | "ethiopic";

/** Time granularity options */
type TimeGranularity = "hour" | "minute" | "second";

/** Hour cycle options */
type HourCycle = 12 | 24;