Selection & Navigation

/**
 * Headless select dropdown component with single/multiple selection
 * @param props - Select properties including options, value, and event handlers
 * @returns Select element with dropdown functionality
 */
function Select<OptionValue, Multiple extends boolean = false>(
  props: SelectProps<OptionValue, Multiple>
): JSX.Element;

interface SelectProps<OptionValue, Multiple extends boolean = false>
  extends PolymorphicProps<SelectTypeMap<OptionValue, Multiple>, React.ElementType> {
  /** Whether to auto-focus on mount */
  autoFocus?: boolean;
  /** Default dropdown open state */
  defaultListboxOpen?: boolean;
  /** Default selected value(s) */
  defaultValue?: SelectValue<OptionValue, Multiple>;
  /** Whether select is disabled */
  disabled?: boolean;
  /** Function to serialize option values */
  getSerializedValue?: (option: string | OptionValue) => string;
  /** ID for the listbox element */
  listboxId?: string;
  /** Controlled dropdown open state */
  listboxOpen?: boolean;
  /** Whether multiple selection is allowed */
  multiple?: Multiple;
  /** Form input name */
  name?: string;
  /** Value change handler */
  onChange?: (event: React.MouseEvent | React.KeyboardEvent | React.FocusEvent | null, value: SelectValue<OptionValue, Multiple>) => void;
  /** Dropdown open state change handler */
  onListboxOpenChange?: (isOpen: boolean) => void;
  /** Placeholder content when no value selected */
  placeholder?: React.ReactNode;
  /** Whether select is required */
  required?: boolean;
  /** Current selected value(s) */
  value?: SelectValue<OptionValue, Multiple>;
  /** Props for customizing select slots */
  slotProps?: {
    root?: SlotComponentProps<SelectSlots["root"], {}, SelectOwnerState<OptionValue, Multiple>>;
    listbox?: SlotComponentProps<SelectSlots["listbox"], {}, SelectOwnerState<OptionValue, Multiple>>;
    popper?: SlotComponentProps<SelectSlots["popper"], {}, SelectOwnerState<OptionValue, Multiple>>;
  };
  /** Components used for select slots */
  slots?: SelectSlots;
  /** Select children (Option components) */
  children?: React.ReactNode;
}

interface SelectSlots {
  /** Root button element */
  root?: React.ElementType;
  /** Listbox popup element */
  listbox?: React.ElementType;
  /** Popper positioning element */
  popper?: React.ElementType;
}

type SelectValue<OptionValue, Multiple extends boolean> = 
  Multiple extends true 
    ? OptionValue[] 
    : OptionValue | null;

interface SelectOwnerState<OptionValue, Multiple extends boolean> {
  disabled: boolean;
  multiple: Multiple;
  open: boolean;
  value: SelectValue<OptionValue, Multiple>;
}

import { Select, Option } from "@mui/base";

// Basic select
<Select defaultValue="apple">
  <Option value="apple">Apple</Option>
  <Option value="banana">Banana</Option>
  <Option value="cherry">Cherry</Option>
</Select>

// Multiple selection
<Select multiple defaultValue={["apple", "banana"]}>
  <Option value="apple">Apple</Option>
  <Option value="banana">Banana</Option>
  <Option value="cherry">Cherry</Option>
</Select>

// Controlled select with change handler
<Select 
  value={selectedValue}
  onChange={(event, newValue) => setSelectedValue(newValue)}
>
  <Option value="option1">Option 1</Option>
  <Option value="option2">Option 2</Option>
</Select>

/**
 * Individual option within Select component
 * @param props - Option properties including value and label
 * @returns Option element with selection state
 */
function Option<OptionValue>(
  props: OptionProps<OptionValue>
): JSX.Element;

interface OptionProps<OptionValue>
  extends PolymorphicProps<OptionTypeMap<OptionValue>, React.ElementType> {
  /** Option content */
  children?: React.ReactNode;
  /** Whether option is disabled */
  disabled?: boolean;
  /** Human-readable text representing the option */
  label?: string;
  /** Value associated with the option */
  value: OptionValue;
}

interface OptionOwnerState<OptionValue> {
  disabled: boolean;
  highlighted: boolean;
  index: number;
  selected: boolean;
  value: OptionValue;
}

/**
 * Groups related options within Select component
 * @param props - Option group properties including label and children
 * @returns Option group element with proper ARIA labeling
 */
function OptionGroup(props: OptionGroupProps): JSX.Element;

interface OptionGroupProps
  extends PolymorphicProps<OptionGroupTypeMap, React.ElementType> {
  /** Option group content (Option components) */
  children?: React.ReactNode;
  /** Whether all options in group are disabled */
  disabled?: boolean;
  /** Label for the option group */
  label?: React.ReactNode;
}

/**
 * Headless menu container component with keyboard navigation
 * @param props - Menu properties including anchor element and open state
 * @returns Menu element with proper accessibility
 */
function Menu<RootComponentType extends React.ElementType = "div">(
  props: MenuProps<RootComponentType>
): JSX.Element;

interface MenuProps<RootComponentType extends React.ElementType = "div">
  extends PolymorphicProps<MenuTypeMap, RootComponentType> {
  /** Ref for imperative menu actions */
  actions?: React.Ref<MenuActions>;
  /** Anchor element for menu positioning */
  anchor?: VirtualElement | (() => VirtualElement) | null;
  /** Menu content (MenuItem components) */
  children?: React.ReactNode;
  /** Default menu open state */
  defaultOpen?: boolean;
  /** ID for the listbox element */
  listboxId?: string;
  /** Open state change handler */
  onOpenChange?: (open: boolean) => void;
  /** Controlled menu open state */
  open?: boolean;
  /** Props for customizing menu slots */
  slotProps?: {
    root?: SlotComponentProps<MenuSlots["root"], {}, MenuOwnerState>;
    listbox?: SlotComponentProps<MenuSlots["listbox"], {}, MenuOwnerState>;
  };
  /** Components used for menu slots */
  slots?: MenuSlots;
}

interface MenuSlots {
  /** Root container element */
  root?: React.ElementType;
  /** Listbox element containing menu items */
  listbox?: React.ElementType;
}

interface MenuActions {
  /** Close the menu */
  close: () => void;
}

/**
 * Button that triggers menu open/close state
 * @param props - Menu button properties including disabled state
 * @returns Button element that controls menu visibility
 */
function MenuButton<RootComponentType extends React.ElementType = "button">(
  props: MenuButtonProps<RootComponentType>
): JSX.Element;

interface MenuButtonProps<RootComponentType extends React.ElementType = "button">
  extends PolymorphicProps<MenuButtonTypeMap, RootComponentType> {
  /** Button content */
  children?: React.ReactNode;
  /** Whether button is disabled */
  disabled?: boolean;
  /** Whether button is focusable when disabled */
  focusableWhenDisabled?: boolean;
  /** Accessible label for the button */
  label?: string;
}

/**
 * Individual menu item component with selection handling
 * @param props - Menu item properties including click handlers
 * @returns Menu item element with proper accessibility
 */
function MenuItem<RootComponentType extends React.ElementType = "li">(
  props: MenuItemProps<RootComponentType>
): JSX.Element;

interface MenuItemProps<RootComponentType extends React.ElementType = "li">
  extends PolymorphicProps<MenuItemTypeMap, RootComponentType> {
  /** Menu item content */
  children?: React.ReactNode;
  /** Whether to close menu on item click (default: true) */
  closeOnClick?: boolean;
  /** Whether menu item is disabled */
  disabled?: boolean;
  /** Menu item ID */
  id?: string;
  /** Accessible label for the menu item */
  label?: string;
  /** Click event handler */
  onClick?: React.MouseEventHandler<any>;
}

/**
 * Context provider for dropdown state management
 * @param props - Dropdown properties including open state
 * @returns Context provider for dropdown state
 */
function Dropdown(props: DropdownProps): JSX.Element;

interface DropdownProps {
  /** Dropdown children components */
  children?: React.ReactNode;
  /** Default open state (default: false) */
  defaultOpen?: boolean;
  /** Open state change handler */
  onOpenChange?: (open: boolean, event?: Event) => void;
  /** Controlled open state */
  open?: boolean;
}

/**
 * Tab container with selection state management and keyboard navigation
 * @param props - Tabs properties including value and orientation
 * @returns Tabs container with proper ARIA attributes
 */
function Tabs<RootComponentType extends React.ElementType = "div">(
  props: TabsProps<RootComponentType>
): JSX.Element;

interface TabsProps<RootComponentType extends React.ElementType = "div">
  extends PolymorphicProps<TabsTypeMap, RootComponentType> {
  /** Tab content (TabsList and TabPanel components) */
  children?: React.ReactNode;
  /** Default selected tab value */
  defaultValue?: string | number | null;
  /** Text direction affecting keyboard navigation */
  direction?: 'ltr' | 'rtl';
  /** Selection change handler */
  onChange?: (event: React.SyntheticEvent, value: string | number) => void;
  /** Tab list orientation (default: 'horizontal') */
  orientation?: 'horizontal' | 'vertical';
  /** Whether selection follows focus (default: false) */
  selectionFollowsFocus?: boolean;
  /** Currently selected tab value */
  value?: string | number | null;
}

/**
 * Container for tab buttons with keyboard navigation
 * @param props - Tabs list properties
 * @returns Tab list element with arrow key navigation
 */
function TabsList<RootComponentType extends React.ElementType = "div">(
  props: TabsListProps<RootComponentType>
): JSX.Element;

interface TabsListProps<RootComponentType extends React.ElementType = "div">
  extends PolymorphicProps<TabsListTypeMap, RootComponentType> {
  /** Tab buttons (Tab components) */
  children?: React.ReactNode;
}

/**
 * Individual tab button component
 * @param props - Tab properties including value and disabled state
 * @returns Tab button element with selection state
 */
function Tab<RootComponentType extends React.ElementType = "button">(
  props: TabProps<RootComponentType>
): JSX.Element;

interface TabProps<RootComponentType extends React.ElementType = "button">
  extends PolymorphicProps<TabTypeMap, RootComponentType> {
  /** Ref for imperative tab actions */
  action?: React.Ref<TabActions>;
  /** Tab content */
  children?: React.ReactNode;
  /** Whether tab is disabled */
  disabled?: boolean;
  /** Selection change handler */
  onChange?: (event: React.SyntheticEvent, value: string | number) => void;
  /** Tab identifier value */
  value?: string | number;
}

interface TabActions {
  /** Focus the tab */
  focus(): void;
}

/**
 * Content panel associated with tab
 * @param props - Tab panel properties including value and keepMounted
 * @returns Tab panel element with conditional visibility
 */
function TabPanel<RootComponentType extends React.ElementType = "div">(
  props: TabPanelProps<RootComponentType>
): JSX.Element;

interface TabPanelProps<RootComponentType extends React.ElementType = "div">
  extends PolymorphicProps<TabPanelTypeMap, RootComponentType> {
  /** Panel content */
  children?: React.ReactNode;
  /** Whether to keep content mounted when not active */
  keepMounted?: boolean;
  /** Panel identifier value matching tab value */
  value: string | number;
}

import { Tabs, TabsList, Tab, TabPanel } from "@mui/base";

// Basic tabs
<Tabs defaultValue="tab1">
  <TabsList>
    <Tab value="tab1">Tab 1</Tab>
    <Tab value="tab2">Tab 2</Tab>
    <Tab value="tab3">Tab 3</Tab>
  </TabsList>
  
  <TabPanel value="tab1">Content for Tab 1</TabPanel>
  <TabPanel value="tab2">Content for Tab 2</TabPanel>
  <TabPanel value="tab3">Content for Tab 3</TabPanel>
</Tabs>

// Vertical tabs with controlled selection
<Tabs 
  orientation="vertical"
  value={activeTab}
  onChange={(event, newValue) => setActiveTab(newValue)}
>
  <TabsList>
    <Tab value="profile">Profile</Tab>
    <Tab value="settings">Settings</Tab>
    <Tab value="billing">Billing</Tab>
  </TabsList>
  
  <TabPanel value="profile">Profile settings...</TabPanel>
  <TabPanel value="settings">General settings...</TabPanel>
  <TabPanel value="billing">Billing information...</TabPanel>
</Tabs>

// Select behavior hook
function useSelect<OptionValue, Multiple extends boolean>(
  props: UseSelectParameters<OptionValue, Multiple>
): UseSelectReturnValue<OptionValue, Multiple>;

// Option behavior hook
function useOption<OptionValue>(
  props: UseOptionParameters<OptionValue>
): UseOptionReturnValue;

// Autocomplete functionality hook
function useAutocomplete<Value, Multiple, DisableClearable, FreeSolo>(
  props: UseAutocompleteProps<Value, Multiple, DisableClearable, FreeSolo>
): UseAutocompleteReturnValue<Value, Multiple, DisableClearable, FreeSolo>;

// Menu behavior hooks
function useMenu(props: UseMenuParameters): UseMenuReturnValue;
function useMenuButton(props: UseMenuButtonParameters): UseMenuButtonReturnValue;
function useMenuItem(props: UseMenuItemParameters): UseMenuItemReturnValue;

// Dropdown behavior hook
function useDropdown(props: UseDropdownParameters): UseDropdownReturnValue;

// Tab behavior hooks
function useTabs(props: UseTabsParameters): UseTabsReturnValue;
function useTabsList(props: UseTabsListParameters): UseTabsListReturnValue;
function useTab(props: UseTabParameters): UseTabReturnValue;
function useTabPanel(props: UseTabPanelParameters): UseTabPanelReturnValue;