Date-Time Pickers

/**
 * Main responsive date-time picker component
 * @param props - DateTimePicker configuration properties
 * @returns JSX element for date-time picker
 */
function DateTimePicker<TDate>(props: DateTimePickerProps<TDate>): JSX.Element;

interface DateTimePickerProps<TDate> {
  /** Current date-time value */
  value?: TDate | null;
  /** Callback fired when date-time changes */
  onChange?: (value: TDate | null, context: PickerChangeContext) => void;
  /** Input label text */
  label?: React.ReactNode;
  /** If true, the picker is disabled */
  disabled?: boolean;
  /** If true, the picker is read-only */
  readOnly?: boolean;
  /** If true, disable dates after today */
  disableFuture?: boolean;
  /** If true, disable dates before today */
  disablePast?: boolean;
  /** Minimum selectable date */
  minDate?: TDate;
  /** Maximum selectable date */
  maxDate?: TDate;
  /** Minimum selectable time */
  minTime?: TDate;
  /** Maximum selectable time */
  maxTime?: TDate;
  /** Minimum selectable date-time */
  minDateTime?: TDate;
  /** Maximum selectable date-time */
  maxDateTime?: TDate;
  /** Function to disable specific dates */
  shouldDisableDate?: (day: TDate) => boolean;
  /** Function to disable specific times */
  shouldDisableTime?: (value: TDate, view: TimeView) => boolean;
  /** Available views for the picker */
  views?: readonly DateOrTimeView[];
  /** View to show when picker opens */
  openTo?: DateOrTimeView;
  /** Format string for date-time display */
  format?: string;
  /** Time step options for time views */
  timeSteps?: TimeStepOptions;
  /** If true, use 12-hour format with AM/PM */
  ampm?: boolean;
  /** Props passed to picker slots */
  slotProps?: DateTimePickerSlotProps<TDate>;
  /** Component slots for customization */
  slots?: DateTimePickerSlots<TDate>;
  /** Default calendar month when no value is set */
  defaultCalendarMonth?: TDate;
  /** Custom day rendering function */
  renderDay?: (day: TDate, selectedDays: TDate[], pickersDayProps: PickersDayProps<TDate>) => JSX.Element;
}

interface DateTimePickerSlots<TDate> {
  field?: React.ElementType;
  textField?: React.ElementType;
  openPickerIcon?: React.ElementType;
  switchViewButton?: React.ElementType;
  switchViewIcon?: React.ElementType;
  previousIconButton?: React.ElementType;
  nextIconButton?: React.ElementType;
  leftArrowIcon?: React.ElementType;
  rightArrowIcon?: React.ElementType;
  calendarHeader?: React.ElementType;
  day?: React.ElementType;
  toolbar?: React.ElementType;
  tabs?: React.ElementType;
  actionBar?: React.ElementType;
  shortcuts?: React.ElementType;
  layout?: React.ElementType;
}

interface DateTimePickerSlotProps<TDate> {
  field?: PickerFieldSlotProps<TDate>;
  textField?: BuiltInFieldTextFieldProps;
  openPickerIcon?: IconButtonProps;
  switchViewButton?: IconButtonProps;
  switchViewIcon?: SvgIconProps;
  previousIconButton?: IconButtonProps;
  nextIconButton?: IconButtonProps;
  leftArrowIcon?: SvgIconProps;
  rightArrowIcon?: SvgIconProps;
  calendarHeader?: PickersCalendarHeaderSlotProps<TDate>;
  day?: PickersDayProps<TDate>;
  toolbar?: DateTimePickerToolbarProps<TDate>;
  tabs?: DateTimePickerTabsProps;
  actionBar?: PickersActionBarProps;
  shortcuts?: PickersShortcutsProps<TDate>;
  layout?: PickersLayoutSlotProps<TDate>;
}

type DateOrTimeView = DateView | TimeView;
type DateView = 'year' | 'month' | 'day';
type TimeView = 'hours' | 'minutes' | 'seconds';

import { DateTimePicker } from '@mui/x-date-pickers/DateTimePicker';
import { LocalizationProvider } from '@mui/x-date-pickers/LocalizationProvider';
import { AdapterDayjs } from '@mui/x-date-pickers/AdapterDayjs';
import dayjs, { Dayjs } from 'dayjs';

// Basic date-time picker
function BasicDateTimePicker() {
  const [value, setValue] = React.useState<Dayjs | null>(null);
  
  return (
    <LocalizationProvider dateAdapter={AdapterDayjs}>
      <DateTimePicker
        label="Select date and time"
        value={value}
        onChange={(newValue) => setValue(newValue)}
      />
    </LocalizationProvider>
  );
}

// Date-time picker with validation
function AppointmentDateTimePicker() {
  const [value, setValue] = React.useState<Dayjs | null>(null);
  
  return (
    <LocalizationProvider dateAdapter={AdapterDayjs}>
      <DateTimePicker
        label="Appointment date & time"
        value={value}
        onChange={(newValue) => setValue(newValue)}
        disablePast
        minDateTime={dayjs()}
        maxDateTime={dayjs().add(3, 'month')}
        shouldDisableTime={(time, view) => {
          // Disable times outside business hours
          if (view === 'hours') {
            return time.hour() < 9 || time.hour() > 17;
          }
          return false;
        }}
        views={['year', 'month', 'day', 'hours', 'minutes']}
        timeSteps={{ minutes: 30 }}
        ampm={false}
      />
    </LocalizationProvider>
  );
}

/**
 * Desktop-optimized date-time picker with popover interface
 * @param props - DesktopDateTimePicker configuration properties
 * @returns JSX element for desktop date-time picker
 */
function DesktopDateTimePicker<TDate>(props: DesktopDateTimePickerProps<TDate>): JSX.Element;

interface DesktopDateTimePickerProps<TDate> extends Omit<DateTimePickerProps<TDate>, 'slots' | 'slotProps'> {
  /** Component slots for desktop customization */
  slots?: DesktopDateTimePickerSlots<TDate>;
  /** Props passed to desktop-specific slots */
  slotProps?: DesktopDateTimePickerSlotProps<TDate>;
}

interface DesktopDateTimePickerSlots<TDate> extends DateTimePickerSlots<TDate> {
  desktopPaper?: React.ElementType;
  popper?: React.ElementType;
}

interface DesktopDateTimePickerSlotProps<TDate> extends DateTimePickerSlotProps<TDate> {
  desktopPaper?: PaperProps;
  popper?: PopperProps;
}

/**
 * Mobile-optimized date-time picker with modal interface
 * @param props - MobileDateTimePicker configuration properties
 * @returns JSX element for mobile date-time picker
 */
function MobileDateTimePicker<TDate>(props: MobileDateTimePickerProps<TDate>): JSX.Element;

interface MobileDateTimePickerProps<TDate> extends Omit<DateTimePickerProps<TDate>, 'slots' | 'slotProps'> {
  /** Component slots for mobile customization */
  slots?: MobileDateTimePickerSlots<TDate>;
  /** Props passed to mobile-specific slots */
  slotProps?: MobileDateTimePickerSlotProps<TDate>;
}

interface MobileDateTimePickerSlots<TDate> extends DateTimePickerSlots<TDate> {
  mobilePaper?: React.ElementType;
  dialog?: React.ElementType;
}

interface MobileDateTimePickerSlotProps<TDate> extends DateTimePickerSlotProps<TDate> {
  mobilePaper?: PaperProps;
  dialog?: DialogProps;
}

/**
 * Always-visible date-time picker without input field
 * @param props - StaticDateTimePicker configuration properties
 * @returns JSX element for static date-time picker
 */
function StaticDateTimePicker<TDate>(props: StaticDateTimePickerProps<TDate>): JSX.Element;

interface StaticDateTimePickerProps<TDate> extends Omit<DateTimePickerProps<TDate>, 'open' | 'onClose' | 'slots' | 'slotProps'> {
  /** Component slots for static customization */
  slots?: StaticDateTimePickerSlots<TDate>;
  /** Props passed to static-specific slots */
  slotProps?: StaticDateTimePickerSlotProps<TDate>;
  /** Display orientation */
  orientation?: 'landscape' | 'portrait';
}

interface StaticDateTimePickerSlots<TDate> extends Omit<DateTimePickerSlots<TDate>, 'field' | 'textField' | 'openPickerIcon'> {
  staticWrapperInner?: React.ElementType;
}

interface StaticDateTimePickerSlotProps<TDate> extends Omit<DateTimePickerSlotProps<TDate>, 'field' | 'textField' | 'openPickerIcon'> {
  staticWrapperInner?: React.HTMLAttributes<HTMLDivElement>;
}

/**
 * Tab component for date-time picker view switching
 * @param props - DateTimePickerTabs configuration properties
 * @returns JSX element for date-time picker tabs
 */
function DateTimePickerTabs(props: DateTimePickerTabsProps): JSX.Element;

interface DateTimePickerTabsProps {
  /** Currently active view */
  view: DateOrTimeView;
  /** Callback when view changes */
  onViewChange: (view: DateOrTimeView) => void;
  /** If true, date tab is hidden */
  hideDateTab?: boolean;
  /** If true, time tab is hidden */
  hideTimeTab?: boolean;
  /** Icon for date tab */
  dateIcon?: React.ReactNode;
  /** Icon for time tab */
  timeIcon?: React.ReactNode;
  /** Additional CSS classes */
  className?: string;
  /** Inline styles */
  sx?: SxProps<Theme>;
}

/**
 * Toolbar component for date-time pickers
 * @param props - DateTimePickerToolbar configuration properties
 * @returns JSX element for date-time picker toolbar
 */
function DateTimePickerToolbar<TDate>(props: DateTimePickerToolbarProps<TDate>): JSX.Element;

interface DateTimePickerToolbarProps<TDate> {
  /** Current date-time value */
  value?: TDate | null;
  /** Currently active view */
  view: DateOrTimeView;
  /** Available views */
  views: readonly DateOrTimeView[];
  /** Callback when view changes */
  onViewChange: (view: DateOrTimeView) => void;
  /** Date adapter instance */
  adapter: MuiPickersAdapter<TDate>;
  /** Timezone for date-time operations */
  timezone: PickersTimezone;
  /** If true, use 12-hour format */
  ampm?: boolean;
  /** If true, toolbar is hidden */
  hidden?: boolean;
  /** Additional CSS classes */
  className?: string;
  /** Inline styles */
  sx?: SxProps<Theme>;
}

const dateTimePickerTabsClasses: {
  root: string;
};

type DateTimePickerTabsClassKey = keyof typeof dateTimePickerTabsClasses;
interface DateTimePickerTabsClasses extends Record<DateTimePickerTabsClassKey, string> {}

const dateTimePickerToolbarClasses: {
  root: string;
  dateContainer: string;
  timeContainer: string;
  timeDigitsContainer: string;
  separator: string;
  ampmSelection: string;
  ampmLandscape: string;
  ampmLabel: string;
};

type DateTimePickerToolbarClassKey = keyof typeof dateTimePickerToolbarClasses;
interface DateTimePickerToolbarClasses extends Record<DateTimePickerToolbarClassKey, string> {}

interface DateTimePickerFieldProps<TDate> {
  value?: TDate | null;
  onChange?: (value: TDate | null, context: FieldChangeContext<TDate>) => void;
  format?: string;
  disabled?: boolean;
  readOnly?: boolean;
  ampm?: boolean;
}