Form Components

/**
 * Text input field with validation and formatting
 * @param label - Field label text
 * @param value - Current input value
 * @param onChange - Value change handler
 * @param type - Input type specification
 * @param error - Validation error message
 * @param helpText - Helpful description text
 * @returns JSX element with text input field
 */
function TextField(props: TextFieldProps): JSX.Element;

type TextFieldProps = NonMutuallyExclusiveProps & MutuallyExclusiveInteractionProps & MutuallyExclusiveSelectionProps;

interface NonMutuallyExclusiveProps {
  /** Text to display before value */
  prefix?: React.ReactNode;
  /** Text to display after value */
  suffix?: React.ReactNode;
  /** Content to vertically display above the input value */
  verticalContent?: React.ReactNode;
  /** Hint text to display */
  placeholder?: string;
  /** Initial value for the input */
  value?: string;
  /** Additional hint text to display */
  helpText?: React.ReactNode;
  /** Label for the input */
  label: React.ReactNode;
  /** Adds an action to the label */
  labelAction?: LabelledProps['action'];
  /** Visually hide the label */
  labelHidden?: boolean;
  /** Disable the input */
  disabled?: boolean;
  /** Show a clear text button in the input */
  clearButton?: boolean;
  /** Indicates whether or not the entire value should be selected on focus */
  selectTextOnFocus?: boolean;
  /** An inline autocomplete suggestion containing the input value */
  suggestion?: string;
  /** Disable editing of the input */
  readOnly?: boolean;
  /** Automatically focus the input */
  autoFocus?: boolean;
  /** Force the focus state on the input */
  focused?: boolean;
  /** Allow for multiple lines of input */
  multiline?: boolean | number;
  /** Error to display beneath the label */
  error?: Error | boolean;
  /** An element connected to the right of the input */
  connectedRight?: React.ReactNode;
  /** An element connected to the left of the input */
  connectedLeft?: React.ReactNode;
  /** Determine type of input */
  type?: 'text' | 'email' | 'number' | 'integer' | 'password' | 'search' | 'tel' | 'url' | 'date' | 'datetime-local' | 'month' | 'time' | 'week' | 'currency';
  /** Name of the input */
  name?: string;
  /** ID for the input */
  id?: string;
  /** Defines a specific role attribute for the input */
  role?: string;
  /** Limit increment value for numeric and date-time inputs */
  step?: number;
  /** Increment value for numeric and date-time inputs when using Page Up or Page Down */
  largeStep?: number;
  /** Enable automatic completion by the browser. Set to "off" when you do not want the browser to fill in info (REQUIRED) */
  autoComplete: string;
  /** Mimics the behavior of the native HTML attribute, limiting the maximum value */
  max?: number | string;
  /** Maximum character length for an input */
  maxLength?: number;
  /** Maximum height of the input element. Only applies when `multiline` is `true` */
  maxHeight?: number | string;
  /** Mimics the behavior of the native HTML attribute, limiting the minimum value */
  min?: number | string;
  /** Minimum character length for an input */
  minLength?: number;
  /** A regular expression to check the value against */
  pattern?: string;
  /** Choose the keyboard that should be used on mobile devices */
  inputMode?: 'none' | 'text' | 'decimal' | 'numeric' | 'tel' | 'search' | 'email' | 'url';
  /** Indicate whether value should have spelling checked */
  spellCheck?: boolean;
  /** Indicates the id of a component owned by the input */
  ariaOwns?: string;
  /** Indicates whether or not a Popover is displayed */
  ariaExpanded?: boolean;
  /** Indicates the id of a component controlled by the input */
  ariaControls?: string;
  /** Indicates the id of a related component's visually focused element to the input */
  ariaActiveDescendant?: string;
  /** Indicates what kind of user input completion suggestions are provided */
  ariaAutocomplete?: string;
  /** Indicates whether or not the character count should be displayed */
  showCharacterCount?: boolean;
  /** Determines the alignment of the text in the input */
  align?: 'left' | 'center' | 'right';
  /** Visual required indicator, adds an asterisk to label */
  requiredIndicator?: boolean;
  /** Indicates whether or not a monospaced font should be used */
  monospaced?: boolean;
  /** Visual styling options for the TextField */
  variant?: 'inherit' | 'borderless';
  /** Changes the size of the input, giving it more or less padding */
  size?: 'slim' | 'medium';
  /** Callback fired when clear button is clicked */
  onClearButtonClick?(id: string): void;
  /** Callback fired when value is changed */
  onChange?(value: string, id: string): void;
  /** When provided, callback fired instead of onChange when value is changed via the number step control */
  onSpinnerChange?(value: string, id: string): void;
  /** Callback fired when input is focused */
  onFocus?: (event?: React.FocusEvent) => void;
  /** Callback fired when input is blurred */
  onBlur?(event?: React.FocusEvent): void;
  /** Indicates the tone of the text field */
  tone?: 'magic';
  /** Whether the TextField will grow as the text within the input changes */
  autoSize?: boolean;
  /** Indicates the loading state */
  loading?: boolean;
}

type MutuallyExclusiveSelectionProps = SelectSuggestion | SelectTextOnFocus;
type MutuallyExclusiveInteractionProps = Interactive | Readonly | Disabled;

interface SelectSuggestion {
  suggestion?: string;
}

interface SelectTextOnFocus {
  selectTextOnFocus?: true;
}

interface Readonly {
  readonly?: true;
}

interface Disabled {
  disabled?: true;
}

interface Interactive {
  onChange(value: string, id: string): void;
}

interface LabelAction {
  /** Action content */
  content: string;
  /** Action callback */
  onAction: () => void;
}

import React, { useState } from 'react';
import { TextField, FormLayout, Button } from '@shopify/polaris';

function ContactForm() {
  const [name, setName] = useState('');
  const [email, setEmail] = useState('');
  const [message, setMessage] = useState('');
  const [errors, setErrors] = useState<{[key: string]: string}>({});

  const validateEmail = (email: string) => {
    return /\S+@\S+\.\S+/.test(email);
  };

  const handleSubmit = () => {
    const newErrors: {[key: string]: string} = {};
    
    if (!name.trim()) newErrors.name = 'Name is required';
    if (!email.trim()) newErrors.email = 'Email is required';
    else if (!validateEmail(email)) newErrors.email = 'Enter a valid email';
    
    setErrors(newErrors);
  };

  return (
    <FormLayout>
      <TextField
        label="Full name"
        value={name}
        onChange={(value) => setName(value)}
        error={errors.name}
        autoComplete="name"
        requiredIndicator
      />
      <TextField
        label="Email address"
        type="email"
        value={email}
        onChange={(value) => setEmail(value)}
        error={errors.email}
        autoComplete="email"
        requiredIndicator
      />
      <TextField
        label="Message"
        value={message}
        onChange={(value) => setMessage(value)}
        multiline={4}
        autoComplete="off"
        helpText="Tell us how we can help you"
      />
      <Button primary onClick={handleSubmit}>
        Send message
      </Button>
    </FormLayout>
  );
}

/**
 * Checkbox input for boolean selection
 * @param label - Checkbox label content
 * @param checked - Current checked state
 * @param onChange - Change handler for checked state
 * @param disabled - Disabled state
 * @returns JSX element with checkbox input
 */
function Checkbox(props: CheckboxProps): JSX.Element;

interface CheckboxProps {
  /** Checkbox label content */
  label: React.ReactNode;
  /** Current checked state */
  checked: boolean | 'indeterminate';
  /** Callback when checked state changes */
  onChange: (newChecked: boolean, id: string) => void;
  /** Disabled state */
  disabled?: boolean;
  /** Validation error */
  error?: Error;
  /** Help text */
  helpText?: React.ReactNode;
  /** Checkbox ID */
  id?: string;
  /** Checkbox name attribute */
  name?: string;
  /** Checkbox value attribute */
  value?: string;
  /** Fill available space */
  fill?: boolean;
  /** Label hidden visually */
  labelHidden?: boolean;
  /** Blur event handler */
  onBlur?: () => void;
  /** Focus event handler */
  onFocus?: () => void;
}

interface CheckboxHandles {
  /** Focus the checkbox */
  focus(): void;
}

/**
 * Radio button input for single selection
 * @param label - Radio button label
 * @param checked - Current selection state
 * @param onChange - Selection change handler
 * @returns JSX element with radio button
 */
function RadioButton(props: RadioButtonProps): JSX.Element;

interface RadioButtonProps {
  /** Radio button label */
  label: React.ReactNode;
  /** Current checked state */
  checked: boolean;
  /** Callback when selection changes */
  onChange: (newChecked: boolean, id: string) => void;
  /** Radio button ID */
  id?: string;
  /** Radio button name (for grouping) */
  name?: string;
  /** Radio button value */
  value?: string;
  /** Disabled state */
  disabled?: boolean;
  /** Help text */
  helpText?: React.ReactNode;
  /** Fill available space */
  fill?: boolean;
  /** Label hidden visually */
  labelHidden?: boolean;
  /** Blur event handler */
  onBlur?: () => void;
  /** Focus event handler */
  onFocus?: () => void;
}

/**
 * Dropdown select for choosing from options
 * @param options - Available options or option groups
 * @param value - Currently selected value
 * @param onChange - Selection change handler
 * @returns JSX element with select dropdown
 */
function Select(props: SelectProps): JSX.Element;

interface SelectProps {
  /** Available select options */
  options: (SelectOption | SelectGroup)[];
  /** Currently selected value */
  value: string;
  /** Callback when selection changes */
  onChange: (value: string, id: string) => void;
  /** Select field label */
  label: string;
  /** Disabled state */
  disabled?: boolean;
  /** Help text */
  helpText?: React.ReactNode;
  /** Placeholder text */
  placeholder?: string;
  /** Validation error */
  error?: Error;
  /** Required field */
  required?: boolean;
  /** Label action */
  labelAction?: LabelAction;
  /** Label hidden visually */
  labelHidden?: boolean;
  /** Select ID */
  id?: string;
  /** Select name attribute */
  name?: string;
  /** Blur event handler */
  onBlur?: () => void;
  /** Focus event handler */
  onFocus?: () => void;
}

interface SelectOption {
  /** Option label */
  label: string;
  /** Option value */
  value: string;
  /** Disabled option */
  disabled?: boolean;
  /** Option prefix content */
  prefix?: React.ReactNode;
}

interface SelectGroup {
  /** Group title */
  title: string;
  /** Options in the group */
  options: SelectOption[];
}

/**
 * Multiple choice selection component
 * @param title - Choice list title
 * @param choices - Available choices
 * @param selected - Currently selected choices
 * @param onChange - Selection change handler
 * @returns JSX element with choice list
 */
function ChoiceList(props: ChoiceListProps): JSX.Element;

interface ChoiceListProps {
  /** Choice list title */
  title?: string;
  /** Available choices */
  choices: Choice[];
  /** Currently selected choice values */
  selected: string[];
  /** Callback when selection changes */
  onChange: (selected: string[]) => void;
  /** Allow multiple selections */
  allowMultiple?: boolean;
  /** Disabled state */
  disabled?: boolean;
  /** Validation error */
  error?: Error;
  /** Title hidden visually */
  titleHidden?: boolean;
  /** Name attribute for form submission */
  name?: string;
}

interface Choice {
  /** Choice label */
  label: React.ReactNode;
  /** Choice value */
  value: string;
  /** Disabled choice */
  disabled?: boolean;
  /** Help text for this choice */
  helpText?: React.ReactNode;
  /** Additional content below the choice */
  renderChildren?: (isSelected: boolean) => React.ReactNode;
}

/**
 * Form wrapper with validation and submission
 * @param children - Form content
 * @param onSubmit - Form submission handler
 * @returns JSX element with form wrapper
 */
function Form(props: FormProps): JSX.Element;

interface FormProps {
  /** Form content */
  children: React.ReactNode;
  /** Form submission handler */
  onSubmit: (event: React.FormEvent<HTMLFormElement>) => void;
  /** Implicit form submission */
  implicitSubmit?: boolean;
  /** Prevent default form submission */
  preventDefault?: boolean;
  /** Disable native form validation */
  noValidate?: boolean;
  /** Accepted character set */
  acceptCharset?: string;
  /** Form action URL */
  action?: string;
  /** Form submission method */
  method?: 'get' | 'post';
  /** Form name attribute */
  name?: string;
  /** Form target */
  target?: string;
}

/**
 * Layout component for organizing form fields
 * @param children - Form fields and content
 * @returns JSX element with form layout
 */
function FormLayout(props: FormLayoutProps): JSX.Element;

interface FormLayoutProps {
  /** Form fields and content */
  children?: React.ReactNode;
}

/**
 * Form layout group for related fields
 * @param children - Grouped form fields
 * @param title - Group title
 * @param condensed - Condensed spacing
 * @returns JSX element with form group
 */
function FormLayoutGroup(props: FormLayoutGroupProps): JSX.Element;

interface FormLayoutGroupProps {
  /** Grouped form fields */
  children?: React.ReactNode;
  /** Group title */
  title?: string;
  /** Condensed spacing */
  condensed?: boolean;
  /** Help text for the group */
  helpText?: React.ReactNode;
}

/**
 * Dual-handle range input for value ranges
 * @param label - Range slider label
 * @param value - Current range values
 * @param onChange - Range change handler
 * @param min - Minimum value
 * @param max - Maximum value
 * @returns JSX element with range slider
 */
function RangeSlider(props: RangeSliderProps): JSX.Element;

interface RangeSliderProps {
  /** Range slider label */
  label: string;
  /** Current range values [min, max] */
  value: [number, number];
  /** Callback when range changes */
  onChange: (value: [number, number], id: string) => void;
  /** Minimum allowed value */
  min?: number;
  /** Maximum allowed value */
  max?: number;
  /** Step increment */
  step?: number;
  /** Disabled state */
  disabled?: boolean;
  /** Output configuration */
  output?: boolean;
  /** Prefix for displayed values */
  prefix?: React.ReactNode;
  /** Suffix for displayed values */
  suffix?: React.ReactNode;
  /** Help text */
  helpText?: React.ReactNode;
  /** Validation error */
  error?: Error;
  /** Label action */
  labelAction?: LabelAction;
  /** Label hidden visually */
  labelHidden?: boolean;
  /** Range slider ID */
  id?: string;
  /** Dual thumb mode */
  dualThumb?: boolean;
  /** Blur event handler */
  onBlur?: () => void;
  /** Focus event handler */
  onFocus?: () => void;
}

/** Union type for validation error content */
type Error = string | React.ReactNode | (string | React.ReactNode)[];

interface LabelAction {
  /** Action content/label */
  content: string;
  /** Action callback */
  onAction: () => void;
}

interface FormFieldProps {
  /** Field label */
  label?: string;
  /** Field ID */
  id?: string;
  /** Field name */
  name?: string;
  /** Disabled state */
  disabled?: boolean;
  /** Required field */
  required?: boolean;
  /** Validation error */
  error?: Error;
  /** Help text */
  helpText?: React.ReactNode;
  /** Label action */
  labelAction?: LabelAction;
  /** Label hidden visually */
  labelHidden?: boolean;
}

/**
 * Searchable dropdown with options filtering
 * @param options - Collection of available options
 * @param selected - Currently selected option values
 * @param textField - Text field component for input
 * @param onSelect - Selection change handler
 * @returns JSX element with autocomplete functionality
 */
function Autocomplete(props: AutocompleteProps): JSX.Element;

interface AutocompleteProps {
  /** Unique identifier for the autocomplete */
  id?: string;
  /** Collection of options to be listed */
  options: SectionDescriptor[] | OptionDescriptor[];
  /** The selected options */
  selected: string[];
  /** The text field component attached to the list of options */
  textField: React.ReactElement;
  /** The preferred direction to open the popover */
  preferredPosition?: PopoverProps['preferredPosition'];
  /** Title of the list of options */
  listTitle?: string;
  /** Allow more than one option to be selected */
  allowMultiple?: boolean;
  /** An action to render above the list of options */
  actionBefore?: ActionListItemDescriptor & {
    wrapOverflow?: boolean;
  };
  /** Display loading state */
  loading?: boolean;
  /** Indicates if more results will load dynamically */
  willLoadMoreResults?: boolean;
  /** Is rendered when there are no options */
  emptyState?: React.ReactNode;
  /** Callback when the selection of options is changed */
  onSelect(selected: string[]): void;
  /** Callback when the end of the list is reached */
  onLoadMoreResults?(): void;
}

/**
 * Color selection interface with HSB and alpha controls
 * @param color - Current color value
 * @param onChange - Color change handler
 * @param allowAlpha - Enable alpha channel selection
 * @returns JSX element with color picker interface
 */
function ColorPicker(props: ColorPickerProps): JSX.Element;

interface ColorPickerProps {
  /** ID for the element */
  id?: string;
  /** The currently selected color */
  color: HSBColor & { alpha?: number };
  /** Allow user to select an alpha value */
  allowAlpha?: boolean;
  /** Allow HuePicker to take the full width */
  fullWidth?: boolean;
  /** Callback when color is selected */
  onChange(color: HSBAColor): void;
}

/**
 * Combined text input and dropdown with custom content
 * @param activator - Text field component to activate popover
 * @param children - Content to display in the dropdown
 * @param onClose - Close handler for the dropdown
 * @returns JSX element with combobox functionality
 */
function Combobox(props: ComboboxProps): JSX.Element;

interface ComboboxProps {
  /** The text field component to activate the Popover */
  activator: React.ReactElement<TextFieldProps>;
  /** Allows more than one option to be selected */
  allowMultiple?: boolean;
  /** The content to display inside the popover */
  children?: React.ReactNode;
  /** The preferred direction to open the popover */
  preferredPosition?: PopoverProps['preferredPosition'];
  /** Whether or not more results will load dynamically */
  willLoadMoreResults?: boolean;
  /** Height to set on the Popover Pane */
  height?: string;
  /** Callback when the popover is closed */
  onClose?(): void;
  /** Callback when the end of the list is reached */
  onLoadMoreResults?(): void;
  /** Callback when the popover is scrolled to the bottom */
  onScrolledToBottom?(): void;
}

/**
 * Calendar date picker with range selection
 * @param selected - Currently selected date or range
 * @param onChange - Date selection handler
 * @param month - Displayed month and year
 * @param onMonthChange - Month navigation handler
 * @returns JSX element with date picker interface
 */
function DatePicker(props: DatePickerProps): JSX.Element;

interface DatePickerProps {
  /** ID for the element */
  id?: string;
  /** The selected date or range of dates */
  selected?: Date | Range;
  /** Allow a range of dates to be selected */
  allowRange?: boolean;
  /** Disable selecting dates before this. */
  disableDatesBefore?: Date;
  /** Disable selecting dates after this. */
  disableDatesAfter?: Date;
  /** The month to show. */
  month: number;
  /** The year to show. */
  year: number;
  /** Callback when date selection changes */
  onChange?(date: Range): void;
  /** Callback when month or year changes */
  onMonthChange?(month: number, year: number): void;
  /** Disable selecting specific dates */
  disableSpecificDates?: Date[];
  /** Allow selecting multiple dates */
  multiMonth?: boolean;
  /** Number of months to display */
  monthCount?: number;
  /** Start week on Monday instead of Sunday */
  weekStartsOn?: 0 | 1;
}

interface Range {
  start: Date;
  end: Date;
}

/**
 * File upload zone with drag and drop support
 * @param onDrop - File drop handler
 * @param children - Content to display in the drop zone
 * @param accept - Accepted file types
 * @returns JSX element with file drop zone
 */
function DropZone(props: DropZoneProps): JSX.Element;

interface DropZoneProps {
  /** Allowed file types */
  accept?: string;
  /** Whether or not the drop zone allows multiple files */
  allowMultiple?: boolean;
  /** Sets an active state */
  active?: boolean;
  /** Sets an error state */
  error?: boolean;
  /** Displayed when no files are uploaded */
  children?: React.ReactNode;
  /** Sets a disabled state */
  disabled?: boolean;
  /** Text that appears in the drop zone */
  label?: React.ReactNode;
  /** Text that appears in the drop zone when files are being dragged over it */
  labelAction?: React.ReactNode;
  /** Text that appears in the drop zone when files are being dragged over it */
  labelHidden?: boolean;
  /** Adds an outline to the drop zone */
  outline?: boolean;
  /** Overlays will cover the entire drop zone */
  overlay?: boolean;
  /** Sets the drop zone size */
  size?: 'extraLarge' | 'large' | 'medium' | 'small';
  /** Callback triggered on drop */
  onDrop?(files: File[], acceptedFiles: File[], rejectedFiles: File[]): void;
  /** Callback triggered when one or more files are dragged over the drop zone */
  onDropAccepted?(acceptedFiles: File[]): void;
  /** Callback triggered when one or more files are rejected */
  onDropRejected?(rejectedFiles: File[]): void;
  /** Callback triggered when files are dragged over the drop zone */
  onDragEnter?(): void;
  /** Callback triggered when files are no longer being dragged over the drop zone */
  onDragLeave?(): void;
  /** Callback triggered when files start being dragged over the drop zone */
  onDragOver?(): void;
  /** Callback triggered when the file dialog opens */
  onFileDialogClose?(): void;
  /** Callback triggered when the file dialog is canceled */
  onFileDialogCancel?(): void;
}

/**
 * Advanced filtering interface with multiple filter types
 * @param filters - Available filter definitions
 * @param appliedFilters - Currently applied filters
 * @param onFiltersChange - Filter change handler
 * @returns JSX element with filtering interface
 */
function Filters(props: FiltersProps): JSX.Element;

interface FiltersProps {
  /** Available filters */
  filters: FilterInterface[];
  /** Currently applied filters */
  appliedFilters?: AppliedFilterInterface[];
  /** Query value */
  queryValue?: string;
  /** Placeholder text for the query field */
  queryPlaceholder?: string;
  /** Whether the query field is focused */
  focused?: boolean;
  /** Additional search field filters */
  searchFieldFilters?: React.ReactNode;
  /** Disable the query field */
  disabled?: boolean;
  /** Whether to hide the query field */
  hideQueryField?: boolean;
  /** Hide the filters */
  hideFilters?: boolean;
  /** Callback when the query changes */
  onQueryChange?(queryValue: string): void;
  /** Callback when the query field is cleared */
  onQueryClear?(): void;
  /** Callback when the query field is focused */
  onQueryFocus?(): void;
  /** Callback when the query field is blurred */
  onQueryBlur?(): void;
  /** Callback when filters are applied */
  onFiltersChange?(appliedFilters: AppliedFilterInterface[]): void;
  /** Callback when the clear all button is clicked */
  onClearAll?(): void;
}

/**
 * Label wrapper for form controls with help text and error handling
 * @param label - Label text for the form control
 * @param children - Form control to be labeled
 * @param error - Error message to display
 * @returns JSX element with labeled form control
 */
function Labelled(props: LabelledProps): JSX.Element;

interface LabelledProps {
  /** A unique identifier for the label */
  id: string;
  /** Text for the label */
  label: React.ReactNode;
  /** Error to display beneath the label */
  error?: Error;
  /** An action to make the label actionable */
  action?: Action;
  /** Additional help text to display */
  helpText?: React.ReactNode;
  /** Content to display inside the connected */
  children?: React.ReactNode;
  /** Visually hide the label */
  labelHidden?: boolean;
  /** Mark the form control as required */
  required?: boolean;
  /** Disable the label and the connected field */
  disabled?: boolean;
  /** Mark the label as read only */
  readOnly?: boolean;
}