Input Components

/**
 * Material Design button component with multiple variants and states
 * @param props - Button props
 * @returns Button React component
 */
function Button(props: ButtonProps): JSX.Element;

interface ButtonProps extends StandardProps<ButtonBaseProps, ButtonClassKey> {
  children: React.ReactNode;
  color?: 'default' | 'inherit' | 'primary' | 'secondary';
  component?: React.ElementType;
  disabled?: boolean;
  disableFocusRipple?: boolean;
  disableRipple?: boolean;
  endIcon?: React.ReactNode;
  fullWidth?: boolean;
  href?: string;
  mini?: boolean; // For fab variant mini styling
  size?: 'small' | 'medium' | 'large';
  startIcon?: React.ReactNode;
  type?: string;
  variant?: 'text' | 'outlined' | 'contained' | 'fab' | 'extendedFab' | 'flat' | 'raised'; // Note: 'flat' and 'raised' are deprecated
}

type ButtonClassKey = 'root' | 'label' | 'text' | 'textPrimary' | 'textSecondary' | 'outlined' | 'outlinedPrimary' | 'outlinedSecondary' | 'contained' | 'containedPrimary' | 'containedSecondary' | 'focusVisible' | 'disabled' | 'colorInherit' | 'textSizeSmall' | 'textSizeLarge' | 'outlinedSizeSmall' | 'outlinedSizeLarge' | 'containedSizeSmall' | 'containedSizeLarge' | 'sizeSmall' | 'sizeLarge' | 'fullWidth' | 'startIcon' | 'endIcon' | 'iconSizeSmall' | 'iconSizeMedium' | 'iconSizeLarge';

import { Button } from '@material-ui/core';
import { Save as SaveIcon } from '@material-ui/icons';

// Basic button variants
<Button>Default</Button>
<Button variant="contained" color="primary">Contained</Button>
<Button variant="outlined" color="secondary">Outlined</Button>

// Button with icons
<Button startIcon={<SaveIcon />} variant="contained" color="primary">
  Save
</Button>

// Full width button
<Button variant="contained" fullWidth>
  Full Width Button
</Button>

/**
 * Unstyled button component that serves as the foundation for other button components
 * @param props - Button base props
 * @returns Button base React component
 */
function ButtonBase(props: ButtonBaseProps): JSX.Element;

interface ButtonBaseProps extends StandardProps<React.ButtonHTMLAttributes<HTMLButtonElement>, ButtonBaseClassKey> {
  action?: React.Ref<ButtonBaseActions>;
  buttonRef?: React.Ref<any>;
  centerRipple?: boolean;
  children?: React.ReactNode;
  component?: React.ElementType;
  disableRipple?: boolean;
  disableTouchRipple?: boolean;
  focusRipple?: boolean;
  focusVisibleClassName?: string;
  onFocusVisible?: React.FocusEventHandler<any>;
  TouchRippleProps?: Partial<TouchRippleProps>;
  type?: 'submit' | 'reset' | 'button';
}

interface ButtonBaseActions {
  focusVisible(): void;
}

type ButtonBaseClassKey = 'root' | 'disabled' | 'focusVisible';

/**
 * Floating action button component for primary actions
 * @param props - Fab props
 * @returns Fab React component
 */
function Fab(props: FabProps): JSX.Element;

interface FabProps extends StandardProps<ButtonBaseProps, FabClassKey> {
  children: React.ReactNode;
  color?: 'default' | 'inherit' | 'primary' | 'secondary';
  component?: React.ElementType;
  disabled?: boolean;
  disableFocusRipple?: boolean;
  disableRipple?: boolean;
  href?: string;
  size?: 'small' | 'medium' | 'large';
  variant?: 'round' | 'extended';
}

type FabClassKey = 'root' | 'primary' | 'secondary' | 'extended' | 'focusVisible' | 'disabled' | 'colorInherit' | 'sizeSmall' | 'sizeMedium';

import { Fab } from '@material-ui/core';
import { Add as AddIcon, Edit as EditIcon } from '@material-ui/icons';

// Basic Fab
<Fab color="primary">
  <AddIcon />
</Fab>

// Extended Fab with text
<Fab variant="extended" color="secondary">
  <EditIcon />
  Edit
</Fab>

// Small Fab
<Fab size="small" color="primary">
  <AddIcon />
</Fab>

/**
 * Comprehensive text input component with Material Design styling
 * @param props - Text field props
 * @returns Text field React component
 */
function TextField(props: TextFieldProps): JSX.Element;

interface TextFieldProps extends StandardProps<FormControlProps, TextFieldClassKey> {
  autoComplete?: string;
  autoFocus?: boolean;
  children?: React.ReactNode;
  defaultValue?: unknown;
  disabled?: boolean;
  error?: boolean;
  FormHelperTextProps?: Partial<FormHelperTextProps>;
  fullWidth?: boolean;
  helperText?: React.ReactNode;
  id?: string;
  InputLabelProps?: Partial<InputLabelProps>;
  inputProps?: InputBaseComponentProps;
  InputProps?: Partial<InputProps>;
  inputRef?: React.Ref<any>;
  label?: React.ReactNode;
  margin?: 'none' | 'dense' | 'normal';
  multiline?: boolean;
  name?: string;
  onChange?: (event: React.ChangeEvent<HTMLInputElement>) => void;
  placeholder?: string;
  required?: boolean;
  rows?: string | number;
  rowsMax?: string | number;
  select?: boolean;
  SelectProps?: Partial<SelectProps>;
  type?: string;
  value?: unknown;
  variant?: 'standard' | 'outlined' | 'filled';
}

type TextFieldClassKey = 'root';

import { TextField } from '@material-ui/core';
import { useState } from 'react';

const [value, setValue] = useState('');

// Basic text field
<TextField
  label="Name"
  value={value}
  onChange={(e) => setValue(e.target.value)}
  margin="normal"
  fullWidth
/>

// Outlined variant with helper text
<TextField
  label="Email"
  type="email"
  variant="outlined"
  helperText="Enter your email address"
  required
  error={!value.includes('@')}
/>

// Multiline text field
<TextField
  label="Description"
  multiline
  rows={4}
  variant="filled"
  fullWidth
/>

/**
 * Checkbox input component for boolean selections
 * @param props - Checkbox props
 * @returns Checkbox React component
 */
function Checkbox(props: CheckboxProps): JSX.Element;

interface CheckboxProps extends StandardProps<IconButtonProps, CheckboxClassKey> {
  checked?: boolean;
  checkedIcon?: React.ReactNode;
  color?: 'default' | 'primary' | 'secondary';
  defaultChecked?: boolean;
  disabled?: boolean;
  disableRipple?: boolean;
  icon?: React.ReactNode;
  id?: string;
  indeterminate?: boolean;
  indeterminateIcon?: React.ReactNode;
  inputProps?: React.InputHTMLAttributes<HTMLInputElement>;
  inputRef?: React.Ref<HTMLInputElement>;
  onChange?: (event: React.ChangeEvent<HTMLInputElement>, checked: boolean) => void;
  required?: boolean;
  size?: 'small' | 'medium';
  value?: unknown;
}

type CheckboxClassKey = 'root' | 'checked' | 'disabled' | 'indeterminate' | 'colorPrimary' | 'colorSecondary';

/**
 * Radio button component for single selection from multiple options
 * @param props - Radio props
 * @returns Radio React component
 */
function Radio(props: RadioProps): JSX.Element;

interface RadioProps extends StandardProps<IconButtonProps, RadioClassKey> {
  checked?: boolean;
  checkedIcon?: React.ReactNode;
  color?: 'default' | 'primary' | 'secondary';
  disabled?: boolean;
  disableRipple?: boolean;
  icon?: React.ReactNode;
  id?: string;
  inputProps?: React.InputHTMLAttributes<HTMLInputElement>;
  inputRef?: React.Ref<HTMLInputElement>;
  name?: string;
  onChange?: (event: React.ChangeEvent<HTMLInputElement>) => void;
  required?: boolean;
  size?: 'small' | 'medium';
  value?: unknown;
}

type RadioClassKey = 'root' | 'checked' | 'disabled' | 'colorPrimary' | 'colorSecondary';

/**
 * Container for grouping radio buttons with shared name and value management
 * @param props - Radio group props
 * @returns Radio group React component
 */
function RadioGroup(props: RadioGroupProps): JSX.Element;

interface RadioGroupProps extends StandardProps<FormGroupProps, RadioGroupClassKey> {
  defaultValue?: unknown;
  name?: string;
  onChange?: (event: React.ChangeEvent<HTMLInputElement>, value: string) => void;
  value?: unknown;
}

type RadioGroupClassKey = 'root' | 'row';

/**
 * Toggle switch component for boolean state changes
 * @param props - Switch props
 * @returns Switch React component
 */
function Switch(props: SwitchProps): JSX.Element;

interface SwitchProps extends StandardProps<IconButtonProps, SwitchClassKey> {
  checked?: boolean;
  checkedIcon?: React.ReactNode;
  color?: 'default' | 'primary' | 'secondary';
  defaultChecked?: boolean;
  disabled?: boolean;
  disableRipple?: boolean;
  edge?: 'start' | 'end' | false;
  icon?: React.ReactNode;
  id?: string;
  inputProps?: React.InputHTMLAttributes<HTMLInputElement>;
  inputRef?: React.Ref<HTMLInputElement>;
  onChange?: (event: React.ChangeEvent<HTMLInputElement>, checked: boolean) => void;
  required?: boolean;
  size?: 'small' | 'medium';
  value?: unknown;
}

type SwitchClassKey = 'root' | 'edgeStart' | 'edgeEnd' | 'switchBase' | 'colorPrimary' | 'colorSecondary' | 'sizeSmall' | 'checked' | 'disabled' | 'input' | 'thumb' | 'track';

/**
 * Dropdown selection component with native and enhanced variants
 * @param props - Select props
 * @returns Select React component
 */
function Select<T = unknown>(props: SelectProps<T>): JSX.Element;

interface SelectProps<T = unknown> extends StandardProps<InputProps, SelectClassKey> {
  autoWidth?: boolean;
  children?: React.ReactNode;
  defaultValue?: T;
  displayEmpty?: boolean;
  IconComponent?: React.ComponentType<{ className: string }>;
  id?: string;
  input?: React.ReactElement<any, any>;
  inputProps?: object;
  MenuProps?: Partial<MenuProps>;
  multiple?: boolean;
  native?: boolean;
  onChange?: (event: React.ChangeEvent<{ name?: string; value: T }>, child: React.ReactNode) => void;
  onClose?: (event: React.SyntheticEvent<Element, Event>) => void;
  onOpen?: (event: React.SyntheticEvent<Element, Event>) => void;
  open?: boolean;
  renderValue?: (value: T) => React.ReactNode;
  SelectDisplayProps?: React.HTMLAttributes<HTMLDivElement>;
  value?: T;
  variant?: 'standard' | 'outlined' | 'filled';
}

type SelectClassKey = 'root' | 'select' | 'filled' | 'outlined' | 'selectMenu' | 'disabled' | 'icon' | 'iconOpen' | 'iconFilled' | 'iconOutlined' | 'nativeInput';

/**
 * Native HTML select element with Material-UI styling
 * @param props - Native select props
 * @returns Native select React component
 */
function NativeSelect<T = unknown>(props: NativeSelectProps<T>): JSX.Element;

interface NativeSelectProps<T = unknown> extends StandardProps<InputProps, NativeSelectClassKey> {
  children?: React.ReactNode;
  IconComponent?: React.ComponentType<{ className: string }>;
  input?: React.ReactElement<any, any>;
  inputProps?: object;
  onChange?: (event: React.ChangeEvent<HTMLSelectElement>) => void;
  value?: T;
  variant?: 'standard' | 'outlined' | 'filled';
}

type NativeSelectClassKey = 'root' | 'select' | 'filled' | 'outlined' | 'selectMenu' | 'disabled' | 'icon' | 'nativeInput';

/**
 * Wrapper component providing context for form inputs
 * @param props - Form control props
 * @returns Form control React component
 */
function FormControl(props: FormControlProps): JSX.Element;

interface FormControlProps extends StandardProps<React.HTMLAttributes<HTMLDivElement>, FormControlClassKey> {
  children?: React.ReactNode;
  color?: 'primary' | 'secondary';
  component?: React.ElementType;
  disabled?: boolean;
  error?: boolean;
  focused?: boolean;
  fullWidth?: boolean;
  hiddenLabel?: boolean;
  margin?: 'none' | 'dense' | 'normal';
  required?: boolean;
  size?: 'small' | 'medium';
  variant?: 'standard' | 'outlined' | 'filled';
}

type FormControlClassKey = 'root' | 'marginNormal' | 'marginDense' | 'fullWidth';

/**
 * Associates a control with a caption
 * @param props - Form control label props
 * @returns Form control label React component
 */
function FormControlLabel(props: FormControlLabelProps): JSX.Element;

interface FormControlLabelProps extends StandardProps<React.LabelHTMLAttributes<HTMLLabelElement>, FormControlLabelClassKey> {
  checked?: boolean;
  control: React.ReactElement<any, any>;
  disabled?: boolean;
  inputRef?: React.Ref<any>;
  label: React.ReactNode;
  labelPlacement?: 'end' | 'start' | 'top' | 'bottom';
  name?: string;
  onChange?: (event: React.SyntheticEvent, checked: boolean) => void;
  value?: unknown;
}

type FormControlLabelClassKey = 'root' | 'labelPlacementStart' | 'labelPlacementTop' | 'labelPlacementBottom' | 'disabled' | 'label';

/**
 * Groups form controls like checkboxes and radio buttons
 * @param props - Form group props
 * @returns Form group React component
 */
function FormGroup(props: FormGroupProps): JSX.Element;

interface FormGroupProps extends StandardProps<React.HTMLAttributes<HTMLDivElement>, FormGroupClassKey> {
  children?: React.ReactNode;
  row?: boolean;
}

type FormGroupClassKey = 'root' | 'row';

/**
 * Helper text for form inputs providing additional information or validation messages
 * @param props - Form helper text props
 * @returns Form helper text React component
 */
function FormHelperText(props: FormHelperTextProps): JSX.Element;

interface FormHelperTextProps extends StandardProps<React.HTMLAttributes<HTMLParagraphElement>, FormHelperTextClassKey> {
  children?: React.ReactNode;
  component?: React.ElementType;
  disabled?: boolean;
  error?: boolean;
  filled?: boolean;
  focused?: boolean;
  margin?: 'dense';
  required?: boolean;
  variant?: 'standard' | 'outlined' | 'filled';
}

type FormHelperTextClassKey = 'root' | 'error' | 'disabled' | 'marginDense' | 'focused' | 'filled' | 'contained' | 'required';

/**
 * Label component for form controls
 * @param props - Form label props
 * @returns Form label React component
 */
function FormLabel(props: FormLabelProps): JSX.Element;

interface FormLabelProps extends StandardProps<React.LabelHTMLAttributes<HTMLLabelElement>, FormLabelClassKey> {
  children?: React.ReactNode;
  color?: 'primary' | 'secondary';
  component?: React.ElementType;
  disabled?: boolean;
  error?: boolean;
  filled?: boolean;
  focused?: boolean;
  required?: boolean;
}

type FormLabelClassKey = 'root' | 'colorSecondary' | 'focused' | 'disabled' | 'error' | 'filled' | 'required' | 'asterisk';

/**
 * Unstyled input component that serves as the foundation for other input components
 * @param props - Input base props
 * @returns Input base React component
 */
function InputBase(props: InputBaseProps): JSX.Element;

interface InputBaseProps extends StandardProps<React.HTMLAttributes<HTMLDivElement>, InputBaseClassKey> {
  autoComplete?: string;
  autoFocus?: boolean;
  color?: 'primary' | 'secondary';
  defaultValue?: unknown;
  disabled?: boolean;
  endAdornment?: React.ReactNode;
  error?: boolean;
  fullWidth?: boolean;
  id?: string;
  inputComponent?: React.ElementType;
  inputProps?: React.InputHTMLAttributes<HTMLInputElement>;
  inputRef?: React.Ref<any>;
  margin?: 'dense';
  multiline?: boolean;
  name?: string;
  onChange?: React.ChangeEventHandler<HTMLTextAreaElement | HTMLInputElement>;
  placeholder?: string;
  readOnly?: boolean;
  required?: boolean;
  rows?: string | number;
  rowsMax?: string | number;
  rowsMin?: string | number;
  startAdornment?: React.ReactNode;
  type?: string;
  value?: unknown;
}

type InputBaseClassKey = 'root' | 'formControl' | 'focused' | 'disabled' | 'adornedStart' | 'adornedEnd' | 'error' | 'marginDense' | 'multiline' | 'colorSecondary' | 'fullWidth' | 'input' | 'inputMarginDense' | 'inputMultiline' | 'inputTypeSearch' | 'inputAdornedStart' | 'inputAdornedEnd' | 'inputHiddenLabel';

/**
 * Standard input component with Material Design styling
 * @param props - Input props
 * @returns Input React component
 */
function Input(props: InputProps): JSX.Element;

interface InputProps extends StandardProps<InputBaseProps, InputClassKey> {
  disableUnderline?: boolean;
}

type InputClassKey = 'root' | 'formControl' | 'focused' | 'disabled' | 'colorSecondary' | 'underline' | 'error' | 'marginDense' | 'multiline' | 'fullWidth' | 'input' | 'inputMarginDense' | 'inputMultiline' | 'inputTypeSearch' | 'inputAdornedStart' | 'inputAdornedEnd' | 'inputHiddenLabel';

/**
 * Filled variant input component
 * @param props - Filled input props
 * @returns Filled input React component
 */
function FilledInput(props: FilledInputProps): JSX.Element;

interface FilledInputProps extends StandardProps<InputBaseProps, FilledInputClassKey> {
  disableUnderline?: boolean;
}

type FilledInputClassKey = 'root' | 'colorSecondary' | 'underline' | 'focused' | 'disabled' | 'adornedStart' | 'adornedEnd' | 'error' | 'marginDense' | 'multiline' | 'input' | 'inputMarginDense' | 'inputHiddenLabel' | 'inputMultiline' | 'inputAdornedStart' | 'inputAdornedEnd';

/**
 * Outlined variant input component
 * @param props - Outlined input props
 * @returns Outlined input React component
 */
function OutlinedInput(props: OutlinedInputProps): JSX.Element;

interface OutlinedInputProps extends StandardProps<InputBaseProps, OutlinedInputClassKey> {
  labelWidth?: number;
  notched?: boolean;
}

type OutlinedInputClassKey = 'root' | 'colorSecondary' | 'focused' | 'disabled' | 'adornedStart' | 'adornedEnd' | 'error' | 'marginDense' | 'multiline' | 'notchedOutline' | 'input' | 'inputMarginDense' | 'inputMultiline' | 'inputAdornedStart' | 'inputAdornedEnd';

/**
 * Circular button component designed for icons
 * @param props - IconButton props
 * @returns IconButton React component
 */
function IconButton(props: IconButtonProps): JSX.Element;

interface IconButtonProps extends StandardProps<ButtonBaseProps, IconButtonClassKey> {
  children: React.ReactNode;
  color?: 'default' | 'inherit' | 'primary' | 'secondary';
  disabled?: boolean;
  disableRipple?: boolean;
  size?: 'small' | 'medium';
}

type IconButtonClassKey = 'root' | 'colorInherit' | 'colorPrimary' | 'colorSecondary' | 'disabled' | 'sizeSmall' | 'label';

import { IconButton } from '@material-ui/core';
import { Delete as DeleteIcon, Edit as EditIcon } from '@material-ui/icons';

// Basic icon button
<IconButton>
  <DeleteIcon />
</IconButton>

// Colored icon button
<IconButton color="primary">
  <EditIcon />
</IconButton>

// Small icon button in toolbar
<IconButton size="small" color="secondary">
  <DeleteIcon />
</IconButton>

/**
 * Component for adding icons or text to input components
 * @param props - InputAdornment props
 * @returns InputAdornment React component
 */
function InputAdornment(props: InputAdornmentProps): JSX.Element;

interface InputAdornmentProps extends StandardProps<React.HTMLAttributes<HTMLDivElement>, InputAdornmentClassKey> {
  children: React.ReactNode;
  component?: React.ElementType;
  disablePointerEvents?: boolean;
  disableTypography?: boolean;
  position: 'start' | 'end';
  variant?: 'standard' | 'outlined' | 'filled';
}

type InputAdornmentClassKey = 'root' | 'filled' | 'positionStart' | 'positionEnd' | 'disablePointerEvents';

import { TextField, InputAdornment, IconButton } from '@material-ui/core';
import { Search as SearchIcon, Visibility, VisibilityOff } from '@material-ui/icons';

// Text field with search icon
<TextField
  placeholder="Search..."
  InputProps={{
    startAdornment: (
      <InputAdornment position="start">
        <SearchIcon />
      </InputAdornment>
    ),
  }}
/>

// Password field with toggle visibility
<TextField
  type={showPassword ? 'text' : 'password'}
  InputProps={{
    endAdornment: (
      <InputAdornment position="end">
        <IconButton onClick={handleTogglePassword}>
          {showPassword ? <VisibilityOff /> : <Visibility />}
        </IconButton>
      </InputAdornment>
    ),
  }}
/>

/**
 * Component for providing accessible labels to input components
 * @param props - InputLabel props
 * @returns InputLabel React component
 */
function InputLabel(props: InputLabelProps): JSX.Element;

interface InputLabelProps extends StandardProps<FormLabelProps, InputLabelClassKey> {
  children?: React.ReactNode;
  disableAnimation?: boolean;
  focused?: boolean;
  margin?: 'dense';
  required?: boolean;
  shrink?: boolean;
  variant?: 'standard' | 'outlined' | 'filled';
}

type InputLabelClassKey = 'root' | 'focused' | 'disabled' | 'error' | 'required' | 'asterisk' | 'formControl' | 'marginDense' | 'shrink' | 'animated' | 'filled' | 'outlined';

import { FormControl, InputLabel, Input } from '@material-ui/core';

// Basic labeled input
<FormControl>
  <InputLabel htmlFor="email-input">Email Address</InputLabel>
  <Input id="email-input" type="email" />
</FormControl>

// Outlined variant with shrinking label
<FormControl variant="outlined">
  <InputLabel shrink htmlFor="name-input">
    Full Name
  </InputLabel>
  <OutlinedInput id="name-input" labelWidth={80} />
</FormControl>