Field Components

/**
 * Standalone date input field component
 * @param props - DateField configuration properties
 * @returns JSX element for date field
 */
function DateField<TDate>(props: DateFieldProps<TDate>): JSX.Element;

interface DateFieldProps<TDate> {
  /** Current date value */
  value?: TDate | null;
  /** Default date value for uncontrolled component */
  defaultValue?: TDate | null;
  /** Callback fired when date changes */
  onChange?: (value: TDate | null, context: FieldChangeContext<TDate>) => void;
  /** Format string for date display */
  format?: string;
  /** Input label text */
  label?: React.ReactNode;
  /** If true, the field is disabled */
  disabled?: boolean;
  /** If true, the field is read-only */
  readOnly?: boolean;
  /** If true, the field is required */
  required?: boolean;
  /** If true, respect leading zeros in format */
  shouldRespectLeadingZeros?: boolean;
  /** Selected sections */
  selectedSections?: FieldSelectedSections;
  /** Callback when selected sections change */
  onSelectedSectionsChange?: (selectedSections: FieldSelectedSections) => void;
  /** Reference to field methods */
  ref?: React.Ref<FieldRef<TDate>>;
  /** Input placeholder text */
  placeholder?: string;
  /** Helper text */
  helperText?: React.ReactNode;
  /** If true, field has error state */
  error?: boolean;
  /** Additional props for text field */
  InputProps?: Partial<InputProps>;
  /** Additional CSS classes */
  className?: string;
  /** Inline styles */
  sx?: SxProps<Theme>;
}

interface FieldChangeContext<TDate> {
  validationError: string | null;
}

type FieldSelectedSections = number | FieldSectionType | null | 'all';
type FieldSectionType = 'year' | 'month' | 'day' | 'weekDay' | 'hours' | 'minutes' | 'seconds' | 'meridiem' | 'empty';

/**
 * Standalone time input field component
 * @param props - TimeField configuration properties
 * @returns JSX element for time field
 */
function TimeField<TDate>(props: TimeFieldProps<TDate>): JSX.Element;

interface TimeFieldProps<TDate> {
  /** Current time value */
  value?: TDate | null;
  /** Default time value for uncontrolled component */
  defaultValue?: TDate | null;
  /** Callback fired when time changes */
  onChange?: (value: TDate | null, context: FieldChangeContext<TDate>) => void;
  /** Format string for time display */
  format?: string;
  /** Input label text */
  label?: React.ReactNode;
  /** If true, the field is disabled */
  disabled?: boolean;
  /** If true, the field is read-only */
  readOnly?: boolean;
  /** If true, the field is required */
  required?: boolean;
  /** If true, respect leading zeros in format */
  shouldRespectLeadingZeros?: boolean;
  /** Selected sections */
  selectedSections?: FieldSelectedSections;
  /** Callback when selected sections change */
  onSelectedSectionsChange?: (selectedSections: FieldSelectedSections) => void;
  /** If true, use 12-hour format with AM/PM */
  ampm?: boolean;
  /** Reference to field methods */
  ref?: React.Ref<FieldRef<TDate>>;
  /** Input placeholder text */
  placeholder?: string;
  /** Helper text */
  helperText?: React.ReactNode;
  /** If true, field has error state */
  error?: boolean;
  /** Additional props for text field */
  InputProps?: Partial<InputProps>;
  /** Additional CSS classes */
  className?: string;
  /** Inline styles */
  sx?: SxProps<Theme>;
}

/**
 * Standalone date-time input field component
 * @param props - DateTimeField configuration properties
 * @returns JSX element for date-time field
 */
function DateTimeField<TDate>(props: DateTimeFieldProps<TDate>): JSX.Element;

interface DateTimeFieldProps<TDate> {
  /** Current date-time value */
  value?: TDate | null;
  /** Default date-time value for uncontrolled component */
  defaultValue?: TDate | null;
  /** Callback fired when date-time changes */
  onChange?: (value: TDate | null, context: FieldChangeContext<TDate>) => void;
  /** Format string for date-time display */
  format?: string;
  /** Input label text */
  label?: React.ReactNode;
  /** If true, the field is disabled */
  disabled?: boolean;
  /** If true, the field is read-only */
  readOnly?: boolean;
  /** If true, the field is required */
  required?: boolean;
  /** If true, respect leading zeros in format */
  shouldRespectLeadingZeros?: boolean;
  /** Selected sections */
  selectedSections?: FieldSelectedSections;
  /** Callback when selected sections change */
  onSelectedSectionsChange?: (selectedSections: FieldSelectedSections) => void;
  /** If true, use 12-hour format with AM/PM */
  ampm?: boolean;
  /** Reference to field methods */
  ref?: React.Ref<FieldRef<TDate>>;
  /** Input placeholder text */
  placeholder?: string;
  /** Helper text */
  helperText?: React.ReactNode;
  /** If true, field has error state */
  error?: boolean;
  /** Additional props for text field */
  InputProps?: Partial<InputProps>;
  /** Additional CSS classes */
  className?: string;
  /** Inline styles */
  sx?: SxProps<Theme>;
}

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

// Basic field usage
function BasicFields() {
  const [dateValue, setDateValue] = React.useState<Dayjs | null>(null);
  const [timeValue, setTimeValue] = React.useState<Dayjs | null>(null);
  const [dateTimeValue, setDateTimeValue] = React.useState<Dayjs | null>(null);
  
  return (
    <LocalizationProvider dateAdapter={AdapterDayjs}>
      <DateField
        label="Date"
        value={dateValue}
        onChange={(newValue) => setDateValue(newValue)}
        format="MM/DD/YYYY"
      />
      <TimeField
        label="Time"
        value={timeValue}
        onChange={(newValue) => setTimeValue(newValue)}
        format="HH:mm:ss"
        ampm={false}
      />
      <DateTimeField
        label="Date & Time"
        value={dateTimeValue}
        onChange={(newValue) => setDateTimeValue(newValue)}
        format="MM/DD/YYYY HH:mm"
      />
    </LocalizationProvider>
  );
}

// Field with validation
function ValidatedField() {
  const [value, setValue] = React.useState<Dayjs | null>(null);
  const [error, setError] = React.useState<string | null>(null);
  
  const handleChange = (newValue: Dayjs | null, context: FieldChangeContext<Dayjs>) => {
    setValue(newValue);
    setError(context.validationError);
  };
  
  return (
    <LocalizationProvider dateAdapter={AdapterDayjs}>
      <DateField
        label="Required Date"
        value={value}
        onChange={handleChange}
        required
        error={!!error}
        helperText={error || 'Please enter a date'}
      />
    </LocalizationProvider>
  );
}

/**
 * Hook for date field functionality
 * @param props - UseDateField configuration properties
 * @returns Field state and handlers
 */
function unstable_useDateField<TDate>(props: UseDateFieldProps<TDate>): UseFieldReturnValue<TDate>;

interface UseDateFieldProps<TDate> {
  value?: TDate | null;
  defaultValue?: TDate | null;
  onChange?: (value: TDate | null, context: FieldChangeContext<TDate>) => void;
  format?: string;
  disabled?: boolean;
  readOnly?: boolean;
  shouldRespectLeadingZeros?: boolean;
  selectedSections?: FieldSelectedSections;
  onSelectedSectionsChange?: (selectedSections: FieldSelectedSections) => void;
}

/**
 * Hook for time field functionality
 * @param props - UseTimeField configuration properties
 * @returns Field state and handlers
 */
function unstable_useTimeField<TDate>(props: UseTimeFieldProps<TDate>): UseFieldReturnValue<TDate>;

interface UseTimeFieldProps<TDate> {
  value?: TDate | null;
  defaultValue?: TDate | null;
  onChange?: (value: TDate | null, context: FieldChangeContext<TDate>) => void;
  format?: string;
  disabled?: boolean;
  readOnly?: boolean;
  shouldRespectLeadingZeros?: boolean;
  selectedSections?: FieldSelectedSections;
  onSelectedSectionsChange?: (selectedSections: FieldSelectedSections) => void;
  ampm?: boolean;
}

/**
 * Hook for date-time field functionality
 * @param props - UseDateTimeField configuration properties
 * @returns Field state and handlers
 */
function unstable_useDateTimeField<TDate>(props: UseDateTimeFieldProps<TDate>): UseFieldReturnValue<TDate>;

interface UseDateTimeFieldProps<TDate> {
  value?: TDate | null;
  defaultValue?: TDate | null;
  onChange?: (value: TDate | null, context: FieldChangeContext<TDate>) => void;
  format?: string;
  disabled?: boolean;
  readOnly?: boolean;
  shouldRespectLeadingZeros?: boolean;
  selectedSections?: FieldSelectedSections;
  onSelectedSectionsChange?: (selectedSections: FieldSelectedSections) => void;
  ampm?: boolean;
}

interface FieldRef<TDate> {
  /**
   * Returns the sections of the current value
   * @returns Array of field sections
   */
  getSections(): FieldSection[];
  /**
   * Returns the index of the active section (the first focused section)
   * @returns Index of active section or null if none active
   */
  getActiveSectionIndex(): number | null;
  /**
   * Updates the selected sections
   * @param selectedSections - Sections to select
   */
  setSelectedSections(selectedSections: FieldSelectedSections): void;
  /**
   * Focuses the field
   * @param newSelectedSection - Section to select once focused
   */
  focusField(newSelectedSection?: number | FieldSectionType): void;
  /**
   * Returns true if the field is focused
   * @returns Boolean indicating focus state
   */
  isFieldFocused(): boolean;
}

interface FieldSection {
  /** Value of the section as rendered in input */
  value: string;
  /** Format token used to parse this section */
  format: string;
  /** Maximum length of the value for digit sections */
  maxLength: number | null;
  /** Placeholder when section value is empty */
  placeholder: string;
  /** Type of the section */
  type: FieldSectionType;
  /** Content type determining editing behavior */
  contentType: FieldSectionContentType;
  /** If true, format expects leading zeros */
  hasLeadingZerosInFormat: boolean;
  /** If true, input should show leading zeros */
  hasLeadingZerosInInput: boolean;
  /** If true, section has been modified */
  modified: boolean;
  /** Separator displayed before section value */
  startSeparator: string;
  /** Separator displayed after section value */
  endSeparator: string;
  /** If true, end separator is a format separator */
  isEndFormatSeparator?: boolean;
}

type FieldSectionContentType = 'digit' | 'digit-with-letter' | 'letter';

interface UseFieldReturnValue<TDate> {
  /** Input value for controlled text field */
  value: string;
  /** Input change handler */
  onChange: (event: React.ChangeEvent<HTMLInputElement>) => void;
  /** Input focus handler */
  onFocus: (event: React.FocusEvent<HTMLInputElement>) => void;
  /** Input blur handler */
  onBlur: (event: React.FocusEvent<HTMLInputElement>) => void;
  /** Key down event handler */
  onKeyDown: (event: React.KeyboardEvent<HTMLInputElement>) => void;
  /** Click event handler */
  onClick: (event: React.MouseEvent<HTMLInputElement>) => void;
  /** Paste event handler */
  onPaste: (event: React.ClipboardEvent<HTMLInputElement>) => void;
  /** Input selection start */
  selectionStart: number | null;
  /** Input selection end */
  selectionEnd: number | null;
  /** Current field sections */
  sections: FieldSection[];
  /** Active section index */
  activeSectionIndex: number | null;
  /** Parsed field value */
  parsedValue: TDate | null;
  /** Validation error message */
  validationError: string | null;
}