Form Controls

/**
 * Headless button component with accessibility and polymorphic support
 * @param props - Button properties including styling slots and behavior options
 * @returns Button element with proper accessibility attributes
 */
function Button<RootComponentType extends React.ElementType = "button">(
  props: ButtonProps<RootComponentType>
): JSX.Element;

interface ButtonProps<RootComponentType extends React.ElementType = "button"> 
  extends PolymorphicProps<ButtonTypeMap, RootComponentType> {
  /** Ref for imperative actions like focusVisible() */
  action?: React.Ref<ButtonActions>;
  /** Button content */
  children?: React.ReactNode;
  /** Props for customizing button slots */
  slotProps?: {
    root?: SlotComponentProps<ButtonSlots["root"], {}, ButtonOwnerState>;
  };
  /** Components used for button slots */
  slots?: ButtonSlots;
  /** HTML element name for root (default: 'button') */
  rootElementName?: keyof HTMLElementTagNameMap;
  /** Whether button is disabled */
  disabled?: boolean;
  /** Whether button is focusable when disabled */
  focusableWhenDisabled?: boolean;
  /** Href for link-style buttons */
  href?: string;
  /** Tab index override */
  tabIndex?: number;
  /** Router link destination */
  to?: string;
  /** Button type attribute */
  type?: "button" | "submit" | "reset";
}

interface ButtonSlots {
  /** Root button element */
  root?: React.ElementType;
}

interface ButtonActions {
  /** Focus the button and show focus visible indicator */
  focusVisible(): void;
}

interface ButtonOwnerState {
  active: boolean;
  disabled: boolean;
  focusVisible: boolean;
}

import { Button } from "@mui/base/Button";

// Basic button
<Button onClick={() => console.log("clicked")}>
  Click me
</Button>

// Custom styled button
<Button 
  className="btn btn-primary"
  slotProps={{
    root: { className: "custom-root" }
  }}
>
  Styled Button
</Button>

// Link-style button
<Button href="/dashboard" component="a">
  Go to Dashboard
</Button>

// Disabled but focusable button
<Button disabled focusableWhenDisabled>
  Disabled but Focusable
</Button>

// CSS classes for Button component styling
interface ButtonClasses {
  /** Class name applied to the root element */
  root: string;
  /** State class applied if active={true} */
  active: string;
  /** State class applied if disabled={true} */
  disabled: string;
  /** State class applied if focusVisible={true} */
  focusVisible: string;
}

// Button classes object
declare const buttonClasses: ButtonClasses;

// Utility function for Button class generation
function getButtonUtilityClass(slot: string): string;

/**
 * Headless input component with form control integration
 * @param props - Input properties including value, validation, and styling
 * @returns Input element with proper form control integration
 */
function Input<RootComponentType extends React.ElementType = "div">(
  props: InputProps<RootComponentType>
): JSX.Element;

interface InputProps<RootComponentType extends React.ElementType = "div">
  extends PolymorphicProps<InputTypeMap, RootComponentType> {
  /** Default input value */
  defaultValue?: unknown;
  /** Whether input is disabled */
  disabled?: boolean;
  /** Whether input has validation error */
  error?: boolean;
  /** Change event handler */
  onChange?: React.ChangeEventHandler<HTMLInputElement>;
  /** Whether input is required */
  required?: boolean;
  /** Current input value */
  value?: unknown;
  /** Props for customizing input slots */
  slotProps?: {
    root?: SlotComponentProps<InputSlots["root"], {}, InputOwnerState>;
    input?: SlotComponentProps<InputSlots["input"], {}, InputOwnerState>;
  };
  /** Components used for input slots */
  slots?: InputSlots;
  /** Input placeholder text */
  placeholder?: string;
  /** Input type attribute */
  type?: string;
  /** Input name attribute */
  name?: string;
  /** Input id attribute */
  id?: string;
}

interface InputSlots {
  /** Root container element */
  root?: React.ElementType;
  /** Input element */
  input?: React.ElementType;
}

interface InputOwnerState {
  disabled: boolean;
  error: boolean;
  focused: boolean;
  required: boolean;
  value: unknown;
}

import { Input, FormControl } from "@mui/base";

// Basic input
<Input 
  placeholder="Enter your name"
  onChange={(e) => setName(e.target.value)}
/>

// Input with form control
<FormControl error={hasError}>
  <Input 
    value={email}
    onChange={(e) => setEmail(e.target.value)}
    type="email"
    required
  />
</FormControl>

// Custom styled input
<Input
  slotProps={{
    root: { className: "input-wrapper" },
    input: { className: "input-field" }
  }}
/>

/**
 * Toggle switch component for boolean values
 * @param props - Switch properties including checked state and styling
 * @returns Switch element with proper accessibility attributes
 */
function Switch<RootComponentType extends React.ElementType = "span">(
  props: SwitchProps<RootComponentType>
): JSX.Element;

interface SwitchProps<RootComponentType extends React.ElementType = "span">
  extends PolymorphicProps<SwitchTypeMap, RootComponentType> {
  /** Whether switch is checked */
  checked?: boolean;
  /** Default checked state */
  defaultChecked?: boolean;
  /** Whether switch is disabled */
  disabled?: boolean;
  /** Change event handler */
  onChange?: React.ChangeEventHandler<HTMLInputElement>;
  /** Whether switch is read-only */
  readOnly?: boolean;
  /** Whether switch is required */
  required?: boolean;
  /** Props for customizing switch slots */
  slotProps?: {
    root?: SlotComponentProps<SwitchSlots["root"], {}, SwitchOwnerState>;
    thumb?: SlotComponentProps<SwitchSlots["thumb"], {}, SwitchOwnerState>;
    input?: SlotComponentProps<SwitchSlots["input"], {}, SwitchOwnerState>;
    track?: SlotComponentProps<SwitchSlots["track"], {}, SwitchOwnerState>;
  };
  /** Components used for switch slots */
  slots?: SwitchSlots;
}

interface SwitchSlots {
  /** Root container element */
  root?: React.ElementType;
  /** Switch thumb element */
  thumb?: React.ElementType;
  /** Hidden input element */
  input?: React.ElementType;
  /** Switch track element */
  track?: React.ElementType;
}

interface SwitchOwnerState {
  checked: boolean;
  disabled: boolean;
  focusVisible: boolean;
  readOnly: boolean;
}

/**
 * Range slider component for numeric value selection
 * @param props - Slider properties including value range and styling
 * @returns Slider element with proper accessibility and keyboard support
 */
function Slider<RootComponentType extends React.ElementType = "span">(
  props: SliderProps<RootComponentType>
): JSX.Element;

interface SliderProps<RootComponentType extends React.ElementType = "span">
  extends PolymorphicProps<SliderTypeMap, RootComponentType> {
  /** Current slider value or array of values */
  value?: number | number[];
  /** Default slider value */
  defaultValue?: number | number[];
  /** Minimum slider value */
  min?: number;
  /** Maximum slider value */
  max?: number;
  /** Step increment */
  step?: number | null;
  /** Whether slider is disabled */
  disabled?: boolean;
  /** Marks on the slider */
  marks?: boolean | SliderMark[];
  /** Change event handler */
  onChange?: (event: Event, value: number | number[]) => void;
  /** Change committed event handler */
  onChangeCommitted?: (event: React.SyntheticEvent | Event, value: number | number[]) => void;
  /** Props for customizing slider slots */
  slotProps?: {
    root?: SlotComponentProps<SliderSlots["root"], {}, SliderOwnerState>;
    rail?: SlotComponentProps<SliderSlots["rail"], {}, SliderOwnerState>;
    track?: SlotComponentProps<SliderSlots["track"], {}, SliderOwnerState>;
    thumb?: SlotComponentProps<SliderSlots["thumb"], {}, SliderOwnerState>;
    mark?: SlotComponentProps<SliderSlots["mark"], {}, SliderOwnerState>;
    markLabel?: SlotComponentProps<SliderSlots["markLabel"], {}, SliderOwnerState>;
    valueLabel?: SlotComponentProps<SliderSlots["valueLabel"], {}, SliderOwnerState>;
    input?: SlotComponentProps<SliderSlots["input"], {}, SliderOwnerState>;
  };
  /** Components used for slider slots */
  slots?: SliderSlots;
}

interface SliderSlots {
  root?: React.ElementType;
  rail?: React.ElementType;
  track?: React.ElementType;
  thumb?: React.ElementType;
  mark?: React.ElementType;
  markLabel?: React.ElementType;
  valueLabel?: React.ElementType;
  input?: React.ElementType;
}

interface SliderMark {
  value: number;
  label?: React.ReactNode;
}

/**
 * Badge component for status indicators and counts
 * @param props - Badge properties including content and visibility
 * @returns Badge element positioned relative to children
 */
function Badge<RootComponentType extends React.ElementType = "span">(
  props: BadgeProps<RootComponentType>
): JSX.Element;

interface BadgeProps<RootComponentType extends React.ElementType = "span">
  extends PolymorphicProps<BadgeTypeMap, RootComponentType> {
  /** Content rendered within the badge */
  badgeContent?: React.ReactNode;
  /** The badge will be added relative to this node */
  children?: React.ReactNode;
  /** If true, the badge is invisible */
  invisible?: boolean;
  /** Max count to show (default: 99) */
  max?: number;
  /** Controls whether badge is hidden when badgeContent is zero */
  showZero?: boolean;
  /** Props for customizing badge slots */
  slotProps?: {
    root?: SlotComponentProps<BadgeSlots["root"], {}, BadgeOwnerState>;
    badge?: SlotComponentProps<BadgeSlots["badge"], {}, BadgeOwnerState>;
  };
  /** Components used for badge slots */
  slots?: BadgeSlots;
}

interface BadgeSlots {
  /** Root container element */
  root?: React.ElementType;
  /** Badge indicator element */
  badge?: React.ElementType;
}

interface BadgeOwnerState {
  badgeContent: React.ReactNode;
  invisible: boolean;
  max: number;
  showZero: boolean;
}

/**
 * Form control context provider for coordinated form state
 * @param props - Form control properties including value and validation state
 * @returns Context provider for form control state
 */
function FormControl<RootComponentType extends React.ElementType = "div">(
  props: FormControlProps<RootComponentType>
): JSX.Element;

interface FormControlProps<RootComponentType extends React.ElementType = "div">
  extends PolymorphicProps<FormControlTypeMap, RootComponentType> {
  /** Default form control value */
  defaultValue?: unknown;
  /** Whether form control is disabled */
  disabled?: boolean;
  /** Whether form control is in error state */
  error?: boolean;
  /** Change handler for form control */
  onChange?: (event: React.SyntheticEvent) => void;
  /** Whether form control is required */
  required?: boolean;
  /** Current form control value */
  value?: unknown;
  /** Form control children */
  children?: React.ReactNode;
}

// Hook for accessing form control context
function useFormControlContext(): FormControlState | undefined;

interface FormControlState {
  disabled: boolean;
  error: boolean;
  required: boolean;
  value: unknown;
  onChange: (event: React.SyntheticEvent) => void;
}

/**
 * Number input component with increment/decrement controls
 * @param props - Number input properties including min/max bounds and step
 * @returns Number input element with stepper controls
 */
function Unstable_NumberInput<RootComponentType extends React.ElementType = "div">(
  props: NumberInputProps<RootComponentType>
): JSX.Element;

interface NumberInputProps<RootComponentType extends React.ElementType = "div">
  extends PolymorphicProps<NumberInputTypeMap, RootComponentType> {
  /** Current number value */
  value?: number;
  /** Default number value */
  defaultValue?: number;
  /** Minimum allowed value */
  min?: number;
  /** Maximum allowed value */
  max?: number;
  /** Step increment for stepper controls */
  step?: number;
  /** Whether input is disabled */
  disabled?: boolean;
  /** Whether input has validation error */
  error?: boolean;
  /** Whether input is required */
  required?: boolean;
  /** Change event handler */
  onChange?: (event: React.FocusEvent<HTMLInputElement> | React.PointerEvent | React.KeyboardEvent, value: number | null) => void;
  /** Props for customizing number input slots */
  slotProps?: {
    root?: SlotComponentProps<NumberInputSlots["root"], {}, NumberInputOwnerState>;
    input?: SlotComponentProps<NumberInputSlots["input"], {}, NumberInputOwnerState>;
    incrementButton?: SlotComponentProps<NumberInputSlots["incrementButton"], {}, NumberInputOwnerState>;
    decrementButton?: SlotComponentProps<NumberInputSlots["decrementButton"], {}, NumberInputOwnerState>;
  };
  /** Components used for number input slots */
  slots?: NumberInputSlots;
}

interface NumberInputSlots {
  root?: React.ElementType;
  input?: React.ElementType;
  incrementButton?: React.ElementType;
  decrementButton?: React.ElementType;
}

// Button behavior hook
function useButton(parameters: UseButtonParameters): UseButtonReturnValue;

// Input behavior hook  
function useInput(parameters: UseInputParameters): UseInputReturnValue;

// Switch behavior hook
function useSwitch(parameters: UseSwitchParameters): UseSwitchReturnValue;

// Slider behavior hook
function useSlider(parameters: UseSliderParameters): UseSliderReturnValue;

// Badge display logic hook
function useBadge(parameters: UseBadgeParameters): UseBadgeReturnValue;

// Number input behavior hook
function unstable_useNumberInput(parameters: UseNumberInputParameters): UseNumberInputReturnValue;