Form Controls

/**
 * Primary text input field with label and validation support
 * @param props - TextField configuration and content properties
 * @returns JSX element as text input field
 */
function TextField(props: SpectrumTextFieldProps): JSX.Element;

interface SpectrumTextFieldProps extends DOMProps, StyleProps {
  /** Input field label */
  label?: React.ReactNode;
  /** Input placeholder text */
  placeholder?: string;
  /** Current input value (controlled) */
  value?: string;
  /** Default input value (uncontrolled) */
  defaultValue?: string;
  /** Help description text */
  description?: React.ReactNode;
  /** Error message text */
  errorMessage?: React.ReactNode;
  /** Input field width */
  width?: DimensionValue;
  /** Label position relative to input */
  labelPosition?: "top" | "side";
  /** Label alignment */
  labelAlign?: "start" | "end";
  /** Input field size */
  size?: "S" | "M" | "L" | "XL";
  /** Whether field is required */
  isRequired?: boolean;
  /** Whether field is disabled */
  isDisabled?: boolean;
  /** Whether field is read-only */
  isReadOnly?: boolean;
  /** Whether to hide validation icons */
  validationBehavior?: "aria" | "native";
  /** Input type */
  type?: "text" | "search" | "url" | "tel" | "email" | "password";
  /** Input pattern for validation */
  pattern?: string;
  /** Minimum length */
  minLength?: number;
  /** Maximum length */
  maxLength?: number;
  /** Auto-focus the field */
  autoFocus?: boolean;
  /** Auto-complete behavior */
  autoComplete?: string;
  /** Value change handler */
  onChange?: (value: string) => void;
  /** Input event handler */
  onInput?: (e: React.FormEvent<HTMLInputElement>) => void;
  /** Focus change handler */
  onFocusChange?: (isFocused: boolean) => void;
  /** Validation state change handler */
  onValidate?: (value: string) => ValidationResult | true;
}

/**
 * Multi-line text input field for longer content
 * @param props - TextArea configuration and sizing properties
 * @returns JSX element as multi-line text input
 */
function TextArea(props: SpectrumTextAreaProps): JSX.Element;

interface SpectrumTextAreaProps extends Omit<SpectrumTextFieldProps, 'type'> {
  /** Number of visible text lines */
  rows?: number;
  /** Whether textarea can be resized */
  resize?: "none" | "both" | "horizontal" | "vertical";
}

/**
 * Numeric input field with increment/decrement controls
 * @param props - NumberField value and formatting properties
 * @returns JSX element as numeric input field
 */
function NumberField(props: SpectrumNumberFieldProps): JSX.Element;

interface SpectrumNumberFieldProps extends DOMProps, StyleProps {
  /** Field label */
  label?: React.ReactNode;
  /** Current numeric value */
  value?: number;
  /** Default numeric value */
  defaultValue?: number;
  /** Placeholder text */
  placeholder?: string;
  /** Help description */
  description?: React.ReactNode;
  /** Error message */
  errorMessage?: React.ReactNode;
  /** Minimum allowed value */
  minValue?: number;
  /** Maximum allowed value */
  maxValue?: number;
  /** Step increment/decrement amount */
  step?: number;
  /** Number formatting options */
  formatOptions?: Intl.NumberFormatOptions;
  /** Whether field is required */
  isRequired?: boolean;
  /** Whether field is disabled */
  isDisabled?: boolean;
  /** Whether field is read-only */
  isReadOnly?: boolean;
  /** Auto-focus the field */
  autoFocus?: boolean;
  /** Value change handler */
  onChange?: (value: number) => void;
  /** Focus change handler */
  onFocusChange?: (isFocused: boolean) => void;
}

/**
 * Search input field with clear button and search styling
 * @param props - SearchField configuration and search properties
 * @returns JSX element as search input field
 */
function SearchField(props: SpectrumSearchFieldProps): JSX.Element;

interface SpectrumSearchFieldProps extends Omit<SpectrumTextFieldProps, 'type'> {
  /** Search submit handler */
  onSubmit?: (value: string) => void;
  /** Clear button press handler */
  onClear?: () => void;
}

/**
 * Individual checkbox for boolean selections
 * @param props - Checkbox state and interaction properties  
 * @returns JSX element as checkbox input
 */
function Checkbox(props: SpectrumCheckboxProps): JSX.Element;

interface SpectrumCheckboxProps extends DOMProps, StyleProps {
  /** Checkbox label content */
  children?: React.ReactNode;
  /** Whether checkbox is checked */
  isSelected?: boolean;
  /** Default checked state */
  defaultSelected?: boolean;
  /** Indeterminate state for partial selection */
  isIndeterminate?: boolean;
  /** Whether checkbox is disabled */
  isDisabled?: boolean;
  /** Whether checkbox is read-only */
  isReadOnly?: boolean;
  /** Whether checkbox is required */
  isRequired?: boolean;
  /** Auto-focus the checkbox */
  autoFocus?: boolean;
  /** Selection change handler */
  onChange?: (isSelected: boolean) => void;
  /** Focus change handler */
  onFocusChange?: (isFocused: boolean) => void;
}

/**
 * Container for multiple related checkboxes with group management
 * @param props - CheckboxGroup configuration and validation properties
 * @returns JSX element containing grouped checkboxes
 */
function CheckboxGroup(props: SpectrumCheckboxGroupProps): JSX.Element;

interface SpectrumCheckboxGroupProps extends DOMProps, StyleProps {
  /** Group label */
  label?: React.ReactNode;
  /** Checkbox elements */
  children: React.ReactElement<SpectrumCheckboxProps>[];
  /** Currently selected values */
  value?: string[];
  /** Default selected values */
  defaultValue?: string[];
  /** Help description */
  description?: React.ReactNode;
  /** Error message */
  errorMessage?: React.ReactNode;
  /** Layout orientation */
  orientation?: "horizontal" | "vertical";
  /** Whether group is disabled */
  isDisabled?: boolean;
  /** Whether group is read-only */
  isReadOnly?: boolean;
  /** Whether group is required */
  isRequired?: boolean;
  /** Value change handler */
  onChange?: (value: string[]) => void;
}

/**
 * Individual radio button for single selection
 * @param props - Radio button properties and content
 * @returns JSX element as radio button input
 */
function Radio(props: SpectrumRadioProps): JSX.Element;

/**
 * Container for radio buttons providing single selection behavior
 * @param props - RadioGroup configuration and selection properties
 * @returns JSX element containing grouped radio buttons
 */
function RadioGroup(props: SpectrumRadioGroupProps): JSX.Element;

interface SpectrumRadioProps extends DOMProps, StyleProps {
  /** Radio button label */
  children?: React.ReactNode;
  /** Radio button value */
  value: string;
  /** Whether radio is disabled */
  isDisabled?: boolean;
  /** Auto-focus the radio */
  autoFocus?: boolean;
}

interface SpectrumRadioGroupProps extends DOMProps, StyleProps {
  /** Group label */
  label?: React.ReactNode;
  /** Radio button elements */
  children: React.ReactElement<SpectrumRadioProps>[];
  /** Currently selected value */
  value?: string;
  /** Default selected value */
  defaultValue?: string;
  /** Help description */
  description?: React.ReactNode;
  /** Error message */
  errorMessage?: React.ReactNode;
  /** Layout orientation */
  orientation?: "horizontal" | "vertical";
  /** Whether group is disabled */
  isDisabled?: boolean;
  /** Whether group is read-only */
  isReadOnly?: boolean;
  /** Whether group is required */
  isRequired?: boolean;
  /** Value change handler */
  onChange?: (value: string) => void;
}

/**
 * Toggle switch for boolean settings and preferences
 * @param props - Switch state and interaction properties
 * @returns JSX element as toggle switch
 */
function Switch(props: SpectrumSwitchProps): JSX.Element;

interface SpectrumSwitchProps extends DOMProps, StyleProps {
  /** Switch label content */
  children?: React.ReactNode;
  /** Whether switch is on */
  isSelected?: boolean;
  /** Default switch state */
  defaultSelected?: boolean;
  /** Whether switch is disabled */
  isDisabled?: boolean;
  /** Whether switch is read-only */
  isReadOnly?: boolean;
  /** Auto-focus the switch */
  autoFocus?: boolean;
  /** Size of the switch */
  size?: "S" | "M" | "L";
  /** Switch state change handler */
  onChange?: (isSelected: boolean) => void;
  /** Focus change handler */
  onFocusChange?: (isFocused: boolean) => void;
}

/**
 * Single value slider for numeric range selection
 * @param props - Slider configuration and value properties
 * @returns JSX element as single value slider
 */
function Slider(props: SpectrumSliderProps): JSX.Element;

/**
 * Range slider for selecting min/max numeric values
 * @param props - RangeSlider configuration and range properties
 * @returns JSX element as range value slider
 */
function RangeSlider(props: SpectrumRangeSliderProps): JSX.Element;

interface SpectrumSliderProps extends DOMProps, StyleProps {
  /** Slider label */
  label?: React.ReactNode;
  /** Current value */
  value?: number;
  /** Default value */
  defaultValue?: number;
  /** Minimum value */
  minValue?: number;
  /** Maximum value */
  maxValue?: number;
  /** Step increment */
  step?: number;
  /** Number formatting options */
  formatOptions?: Intl.NumberFormatOptions;
  /** Layout orientation */
  orientation?: "horizontal" | "vertical";
  /** Whether to show value label */
  showValueLabel?: boolean;
  /** Whether slider is disabled */
  isDisabled?: boolean;
  /** Value change handler */
  onChange?: (value: number) => void;
  /** Value change start handler */
  onChangeStart?: (value: number) => void;
  /** Value change end handler */
  onChangeEnd?: (value: number) => void;
}

interface SpectrumRangeSliderProps extends Omit<SpectrumSliderProps, 'value' | 'defaultValue' | 'onChange' | 'onChangeStart' | 'onChangeEnd'> {
  /** Current range value */
  value?: { start: number; end: number };
  /** Default range value */
  defaultValue?: { start: number; end: number };
  /** Range change handler */
  onChange?: (value: { start: number; end: number }) => void;
  /** Range change start handler */
  onChangeStart?: (value: { start: number; end: number }) => void;
  /** Range change end handler */
  onChangeEnd?: (value: { start: number; end: number }) => void;
}

/**
 * Form container for grouping fields with validation and submission
 * @param props - Form configuration and submission properties
 * @returns JSX element as form container
 */
function Form(props: SpectrumFormProps): JSX.Element;

interface SpectrumFormProps extends DOMProps, StyleProps {
  /** Form field elements */
  children: React.ReactNode;
  /** Form submission handler */
  onSubmit?: (e: React.FormEvent<HTMLFormElement>) => void;
  /** Form reset handler */
  onReset?: (e: React.FormEvent<HTMLFormElement>) => void;
  /** Whether form validation should be performed */
  validationBehavior?: "aria" | "native";
  /** Auto-complete behavior for the form */
  autoComplete?: "on" | "off";
  /** Form encoding type */
  encType?: "application/x-www-form-urlencoded" | "multipart/form-data" | "text/plain";
  /** Form submission method */
  method?: "get" | "post";
  /** Form action URL */
  action?: string;
  /** Form target */
  target?: string;
  /** Whether form fields should not be validated */
  noValidate?: boolean;
}

import {
  Form,
  TextField,
  TextArea,
  NumberField,
  CheckboxGroup,
  Checkbox,
  RadioGroup,
  Radio,
  Switch,
  Button,
  ButtonGroup
} from "@adobe/react-spectrum";

function ContactForm() {
  const [formData, setFormData] = useState({
    name: "",
    email: "",
    age: 0,
    message: "",
    interests: [],
    contactMethod: "email",
    newsletter: false
  });

  return (
    <Form onSubmit={handleSubmit}>
      <TextField
        label="Full Name"
        isRequired
        value={formData.name}
        onChange={(name) => setFormData({ ...formData, name })}
      />
      
      <TextField
        label="Email Address"
        type="email"
        isRequired
        value={formData.email}
        onChange={(email) => setFormData({ ...formData, email })}
      />
      
      <NumberField
        label="Age"  
        minValue={0}
        maxValue={120}
        value={formData.age}
        onChange={(age) => setFormData({ ...formData, age })}
      />
      
      <TextArea
        label="Message"
        placeholder="Tell us about yourself..."
        rows={4}
        value={formData.message}
        onChange={(message) => setFormData({ ...formData, message })}
      />
      
      <CheckboxGroup
        label="Interests"
        value={formData.interests}
        onChange={(interests) => setFormData({ ...formData, interests })}
      >
        <Checkbox value="technology">Technology</Checkbox>
        <Checkbox value="design">Design</Checkbox>
        <Checkbox value="marketing">Marketing</Checkbox>
      </CheckboxGroup>
      
      <RadioGroup
        label="Preferred Contact Method"
        value={formData.contactMethod}
        onChange={(contactMethod) => setFormData({ ...formData, contactMethod })}
      >
        <Radio value="email">Email</Radio>
        <Radio value="phone">Phone</Radio>
        <Radio value="mail">Mail</Radio>
      </RadioGroup>
      
      <Switch
        isSelected={formData.newsletter}
        onChange={(newsletter) => setFormData({ ...formData, newsletter })}
      >
        Subscribe to newsletter
      </Switch>
      
      <ButtonGroup>
        <Button variant="secondary" type="reset">Reset</Button>
        <Button variant="accent" type="submit">Submit</Button>
      </ButtonGroup>
    </Form>
  );
}

/** Validation result interface */
interface ValidationResult {
  /** Whether validation passed */
  isValid: boolean;
  /** Validation error messages */
  errorMessage?: string;
}

/** Validation behavior options */
type ValidationBehavior = "aria" | "native";

/** Base properties for form fields */
interface FieldProps {
  /** Field label */
  label?: React.ReactNode;
  /** Help description text */
  description?: React.ReactNode;
  /** Error message text */
  errorMessage?: React.ReactNode;
  /** Whether field is required */
  isRequired?: boolean;
  /** Whether field is disabled */
  isDisabled?: boolean;
  /** Whether field is read-only */
  isReadOnly?: boolean;
  /** Validation behavior */
  validationBehavior?: "aria" | "native";
}

/** Label positioning options */
type LabelPosition = "top" | "side";

/** Label alignment options */
type LabelAlign = "start" | "end";

/** Field size options */
type FieldSize = "S" | "M" | "L" | "XL";

/**
 * A drop zone area for dragging and dropping files or objects
 * @param props - DropZone configuration and content properties
 * @returns JSX element as drop zone area
 */
function DropZone(props: SpectrumDropZoneProps): JSX.Element;

interface SpectrumDropZoneProps {
  /** The content to display in the drop zone */
  children: React.ReactNode;
  /** Whether the drop zone has been filled */
  isFilled?: boolean;
  /** Custom message when drop zone is filled */
  replaceMessage?: string;
  /** Handler when items are dropped */
  onDrop?: (e: DropEvent) => void;
  /** Accepted file types */
  acceptedDragTypes?: string[];
  /** Whether drop zone is disabled */
  isDisabled?: boolean;
}

/**
 * Button component that opens file selection dialog
 * @param props - FileTrigger configuration and behavior properties
 * @returns JSX element as file selection trigger
 */
function FileTrigger(props: FileTriggerProps): JSX.Element;

interface FileTriggerProps {
  /** Trigger element (typically a Button) */
  children: React.ReactElement;
  /** Accepted file types */
  acceptedFileTypes?: string[];
  /** Whether to allow multiple file selection */
  allowsMultiple?: boolean;
  /** Default camera for media capture */
  defaultCamera?: "user" | "environment";
  /** Directory selection mode */
  acceptDirectory?: boolean;
  /** Handler when files are selected */
  onSelect?: (files: FileList | null) => void;
}

/**
 * Container component for grouping form fields with validation
 * @param props - Form configuration and content properties
 * @returns JSX element as form container
 */
function Form(props: SpectrumFormProps): JSX.Element;

interface SpectrumFormProps {
  /** Form fields and content */
  children: React.ReactNode;
  /** Form submission handler */
  onSubmit?: (e: FormEvent) => void;
  /** Form validation mode */
  validationBehavior?: "aria" | "native";
  /** Whether form fields are disabled */
  isDisabled?: boolean;
  /** Whether form fields are read-only */
  isReadOnly?: boolean;
  /** Whether form fields are required */
  isRequired?: boolean;
}