Selection Controls

/**
 * Provides listbox behavior and accessibility
 * @param props - Listbox configuration
 * @param state - Selection state management
 * @param ref - Ref to the listbox element
 * @returns Listbox props and state
 */
function useListBox<T>(props: AriaListBoxProps<T>, state: ListState<T>, ref: RefObject<Element>): ListBoxAria;

/**
 * Provides listbox section behavior for grouping options
 * @param props - Section configuration
 * @param ref - Ref to the section element
 * @returns Section props
 */
function useListBoxSection<T>(props: AriaListBoxSectionProps<T>, ref: RefObject<Element>): ListBoxSectionAria;

/**
 * Provides individual option behavior within a listbox
 * @param props - Option configuration
 * @param state - Listbox state
 * @param ref - Ref to the option element
 * @returns Option props and state
 */
function useOption<T>(props: AriaOptionProps, state: ListState<T>, ref: RefObject<Element>): OptionAria;

interface AriaListBoxProps<T> {
  /** Item objects in the collection */
  items?: Iterable<T>;
  /** Selection mode */
  selectionMode?: 'none' | 'single' | 'multiple';
  /** Disable selection */
  disallowEmptySelection?: boolean;
  /** Currently selected keys */
  selectedKeys?: 'all' | Iterable<Key>;
  /** Default selected keys (uncontrolled) */
  defaultSelectedKeys?: 'all' | Iterable<Key>;
  /** Handler called when selection changes */
  onSelectionChange?: (keys: Selection) => void;
  /** Currently focused key */
  focusedKey?: Key;
  /** Default focused key (uncontrolled) */
  defaultFocusedKey?: Key;
  /** Handler called when focus changes */
  onFocusChange?: (key: Key) => void;
  /** Whether the listbox is disabled */
  isDisabled?: boolean;
  /** Handler called when an option is activated */
  onAction?: (key: Key) => void;
  /** Handler called when scrolling should occur */
  onScroll?: (e: UIEvent<Element>) => void;
  /** Whether to auto-focus the listbox */
  autoFocus?: boolean | FocusStrategy;
  /** Handler called when the listbox should scroll to an item */
  shouldFocusWrap?: boolean;
  /** Whether virtualized scrolling is used */
  isVirtualized?: boolean;
  /** Layout delegate for virtualized scrolling */
  layoutDelegate?: LayoutDelegate;
}

interface ListBoxAria {
  /** Props for the listbox element */
  listBoxProps: DOMAttributes<Element>;
}

/**
 * Provides combobox behavior and accessibility
 * @param props - Combobox configuration
 * @param state - Combobox state management
 * @param ref - Ref to the combobox element
 * @returns Combobox props and state
 */
function useComboBox<T>(props: AriaComboBoxProps<T>, state: ComboBoxState<T>, ref: RefObject<Element>): ComboBoxAria;

interface AriaComboBoxProps<T> extends AriaComboBoxOptions<T> {
  /** Current input value */
  inputValue?: string;
  /** Default input value (uncontrolled) */
  defaultInputValue?: string;
  /** Handler called when input value changes */
  onInputChange?: (value: string) => void;
  /** Whether the popup is open */
  isOpen?: boolean;
  /** Default open state (uncontrolled) */
  defaultOpen?: boolean;
  /** Handler called when open state changes */
  onOpenChange?: (isOpen: boolean) => void;
  /** Currently selected key */
  selectedKey?: Key | null;
  /** Default selected key (uncontrolled) */
  defaultSelectedKey?: Key | null;
  /** Handler called when selection changes */
  onSelectionChange?: (key: Key | null) => void;
  /** Disable selection */
  disallowEmptySelection?: boolean;
  /** Items in the collection */
  items?: Iterable<T>;
  /** Function to get display text for an item */
  itemText?: (item: T) => string;
  /** Handler called when an item is selected */
  onAction?: (key: Key) => void;
  /** Whether the combobox allows custom values */
  allowsCustomValue?: boolean;
  /** Menu trigger behavior */
  menuTrigger?: 'focus' | 'input' | 'manual';
  /** Whether the combobox is disabled */
  isDisabled?: boolean;
  /** Whether the combobox is read-only */
  isReadOnly?: boolean;
  /** Whether the combobox is required */
  isRequired?: boolean;
  /** Validation state */
  validationState?: 'valid' | 'invalid';
  /** Auto-complete behavior */
  completionMode?: 'complete' | 'list' | 'both';
}

interface ComboBoxAria {
  /** Props for the combobox label */
  labelProps: DOMAttributes<Element>;
  /** Props for the text input element */
  inputProps: InputHTMLAttributes<HTMLInputElement>;
  /** Props for the listbox element */
  listBoxProps: DOMAttributes<Element>;
  /** Props for the popup button */
  buttonProps: ButtonHTMLAttributes<HTMLButtonElement>;
  /** Props for the description element */
  descriptionProps: DOMAttributes<Element>;
  /** Props for the error message element */
  errorMessageProps: DOMAttributes<Element>;
}

/**
 * Provides select behavior and accessibility
 * @param props - Select configuration
 * @param state - Select state management
 * @param ref - Ref to the select element
 * @returns Select props and state
 */
function useSelect<T>(props: AriaSelectProps<T>, state: SelectState<T>, ref: RefObject<Element>): SelectAria;

/**
 * Provides hidden select behavior for form integration
 * @param props - Hidden select configuration
 * @param ref - Ref to the select element
 * @returns Select element properties
 */
function useHiddenSelect<T>(props: AriaHiddenSelectProps, ref: RefObject<HTMLSelectElement>): HiddenSelectProps;

/**
 * Hidden select component for form integration
 * @param props - Hidden select configuration
 * @returns Hidden select element
 */
function HiddenSelect<T>(props: HiddenSelectProps): JSX.Element;

interface AriaSelectProps<T> extends AriaSelectOptions<T> {
  /** Currently selected key */
  selectedKey?: Key | null;
  /** Default selected key (uncontrolled) */
  defaultSelectedKey?: Key | null;
  /** Handler called when selection changes */
  onSelectionChange?: (key: Key | null) => void;
  /** Whether the select is open */
  isOpen?: boolean;
  /** Default open state (uncontrolled) */
  defaultOpen?: boolean;
  /** Handler called when open state changes */
  onOpenChange?: (isOpen: boolean) => void;
  /** Items in the collection */
  items?: Iterable<T>;
  /** Disable empty selection */
  disallowEmptySelection?: boolean;
  /** Whether the select is disabled */
  isDisabled?: boolean;
  /** Whether the select is required */
  isRequired?: boolean;
  /** Validation state */
  validationState?: 'valid' | 'invalid';
  /** Auto-focus behavior */
  autoFocus?: boolean;
  /** Name for form integration */
  name?: string;
}

interface SelectAria {
  /** Props for the select label */
  labelProps: DOMAttributes<Element>;
  /** Props for the trigger button */
  triggerProps: ButtonHTMLAttributes<HTMLButtonElement>;
  /** Props for the value element */
  valueProps: DOMAttributes<Element>;
  /** Props for the listbox */
  listBoxProps: DOMAttributes<Element>;
  /** Props for the description element */
  descriptionProps: DOMAttributes<Element>;
  /** Props for the error message element */
  errorMessageProps: DOMAttributes<Element>;
}

/**
 * Provides menu behavior and accessibility
 * @param props - Menu configuration
 * @param state - Menu state management
 * @param ref - Ref to the menu element
 * @returns Menu props and state
 */
function useMenu<T>(props: AriaMenuProps<T>, state: TreeState<T>, ref: RefObject<Element>): MenuAria;

/**
 * Provides menu trigger behavior for opening menus
 * @param props - Menu trigger configuration
 * @param state - Menu trigger state
 * @param ref - Ref to the trigger element
 * @returns Menu trigger props
 */
function useMenuTrigger<T>(props: AriaMenuTriggerProps, state: MenuTriggerState, ref: RefObject<Element>): MenuTriggerAria;

/**
 * Provides individual menu item behavior
 * @param props - Menu item configuration
 * @param state - Menu state
 * @param ref - Ref to the menu item element
 * @returns Menu item props and state
 */
function useMenuItem<T>(props: AriaMenuItemProps, state: TreeState<T>, ref: RefObject<Element>): MenuItemAria;

/**
 * Provides menu section behavior for grouping items
 * @param props - Section configuration
 * @param ref - Ref to the section element
 * @returns Section props
 */
function useMenuSection<T>(props: AriaMenuSectionProps<T>, ref: RefObject<Element>): MenuSectionAria;

/**
 * Provides submenu trigger behavior
 * @param props - Submenu trigger configuration
 * @param state - Menu state
 * @param ref - Ref to the trigger element
 * @returns Submenu trigger props
 */
function useSubmenuTrigger<T>(props: AriaSubmenuTriggerProps, state: TreeState<T>, ref: RefObject<Element>): SubmenuTriggerAria;

interface AriaMenuProps<T> extends AriaMenuOptions<T> {
  /** Items in the menu */
  items?: Iterable<T>;
  /** Disabled keys */
  disabledKeys?: Iterable<Key>;
  /** Handler called when an item is selected */
  onAction?: (key: Key) => void;
  /** Handler called when menu should close */
  onClose?: () => void;
  /** Auto-focus behavior */
  autoFocus?: boolean | FocusStrategy;
  /** Whether focus should wrap */
  shouldFocusWrap?: boolean;
}

interface MenuAria {
  /** Props for the menu element */
  menuProps: DOMAttributes<Element>;
}

interface AriaMenuTriggerProps {
  /** Type of menu trigger */
  type?: 'menu' | 'listbox' | 'tree' | 'grid' | 'dialog';
  /** Whether the menu is disabled */
  isDisabled?: boolean;
  /** Trigger on which events */
  trigger?: 'press' | 'longPress';
}

interface MenuTriggerAria {
  /** Props for the menu trigger element */
  menuTriggerProps: ButtonHTMLAttributes<HTMLButtonElement>;
  /** Props for the menu element */
  menuProps: DOMAttributes<Element>;
}

/**
 * Provides grid list behavior and accessibility
 * @param props - Grid list configuration
 * @param state - Grid list state
 * @param ref - Ref to the grid element
 * @returns Grid list props and state
 */
function useGridList<T>(props: AriaGridListProps<T>, state: ListState<T>, ref: RefObject<Element>): GridListAria;

/**
 * Provides grid list item behavior
 * @param props - Grid list item configuration
 * @param state - Grid list state
 * @param ref - Ref to the item element
 * @returns Grid list item props and state
 */
function useGridListItem<T>(props: AriaGridListItemOptions<T>, state: ListState<T>, ref: RefObject<Element>): GridListItemAria;

/**
 * Provides selection checkbox behavior for grid list items
 * @param props - Selection checkbox configuration
 * @param state - Grid list state
 * @param ref - Ref to the checkbox element
 * @returns Selection checkbox props
 */
function useGridListSelectionCheckbox<T>(props: AriaGridSelectionCheckboxProps, state: ListState<T>, ref: RefObject<Element>): GridSelectionCheckboxAria;

interface AriaGridListProps<T> extends AriaGridListOptions<T> {
  /** Items in the grid */
  items?: Iterable<T>;
  /** Selection mode */
  selectionMode?: 'none' | 'single' | 'multiple';
  /** Selected keys */
  selectedKeys?: 'all' | Iterable<Key>;
  /** Default selected keys (uncontrolled) */
  defaultSelectedKeys?: 'all' | Iterable<Key>;
  /** Handler called when selection changes */
  onSelectionChange?: (keys: Selection) => void;
  /** Disabled keys */
  disabledKeys?: Iterable<Key>;
  /** Handler called when an item is activated */
  onAction?: (key: Key) => void;
  /** Whether the grid is disabled */
  isDisabled?: boolean;
  /** Auto-focus behavior */
  autoFocus?: boolean | FocusStrategy;
}

interface GridListAria {
  /** Props for the grid list element */
  gridProps: DOMAttributes<Element>;
}

/**
 * Keyboard navigation delegate for list components
 */
class ListKeyboardDelegate {
  /** Get the key above the current key */
  getKeyAbove(key: Key): Key | null;
  /** Get the key below the current key */
  getKeyBelow(key: Key): Key | null;
  /** Get the key to the left of the current key */
  getKeyLeftOf(key: Key): Key | null;
  /** Get the key to the right of the current key */
  getKeyRightOf(key: Key): Key | null;
  /** Get the first key */
  getFirstKey(): Key | null;
  /** Get the last key */
  getLastKey(): Key | null;
  /** Get the key for a character */
  getKeyForSearch(search: string, fromKey?: Key): Key | null;
}

type Selection = 'all' | Set<Key>;

type SelectionMode = 'none' | 'single' | 'multiple';

type FocusStrategy = 'first' | 'last';

interface ListState<T> {
  /** Collection of items */
  collection: Collection<Node<T>>;
  /** Set of selected keys */
  selectedKeys: Selection;
  /** Currently focused key */
  focusedKey: Key | null;
  /** Whether the collection allows empty selection */
  disallowEmptySelection: boolean;
  /** Selection mode */
  selectionMode: SelectionMode;
  /** Set of disabled keys */
  disabledKeys: Set<Key>;
  /** Select an item */
  setSelectedKeys(keys: Selection): void;
  /** Toggle selection of an item */
  toggleSelection(key: Key): void;
  /** Replace selection with a single item */
  replaceSelection(key: Key): void;
  /** Select all items */
  selectAll(): void;
  /** Clear all selection */
  clearSelection(): void;
  /** Set the focused key */
  setFocusedKey(key: Key): void;
}

interface ComboBoxState<T> extends ListState<T> {
  /** Current input value */
  inputValue: string;
  /** Set the input value */
  setInputValue(value: string): void;
  /** Currently selected item */
  selectedItem: Node<T> | null;
  /** Currently selected key */
  selectedKey: Key | null;
  /** Set the selected key */
  setSelectedKey(key: Key | null): void;
  /** Whether the popup is open */
  isOpen: boolean;
  /** Set the open state */
  setOpen(isOpen: boolean): void;
  /** Toggle the open state */
  toggle(): void;
  /** Open the popup */
  open(): void;
  /** Close the popup */
  close(): void;
  /** Commit the current input value */
  commit(): void;
  /** Revert to the selected item's text */
  revert(): void;
}

interface SelectState<T> {
  /** Whether the select is open */
  isOpen: boolean;
  /** Set the open state */
  setOpen(isOpen: boolean): void;
  /** Currently selected key */
  selectedKey: Key | null;
  /** Set the selected key */
  setSelectedKey(key: Key | null): void;
  /** Currently selected item */
  selectedItem: Node<T> | null;
  /** Collection of items */
  collection: Collection<Node<T>>;
  /** Toggle the open state */
  toggle(): void;
  /** Open the select */
  open(): void;
  /** Close the select */
  close(): void;
}