Layout and Navigation

/**
 * Provides tab list behavior and accessibility
 * @param props - Tab list configuration
 * @param state - Tab list state
 * @param ref - Ref to the tab list element
 * @returns Tab list props and state
 */
function useTabList<T>(props: AriaTabListProps<T>, state: TabListState<T>, ref: RefObject<Element>): TabListAria;

/**
 * Provides individual tab behavior
 * @param props - Tab configuration
 * @param state - Tab list state
 * @param ref - Ref to the tab element
 * @returns Tab props and state
 */
function useTab(props: AriaTabProps, state: TabListState<T>, ref: RefObject<Element>): TabAria;

/**
 * Provides tab panel behavior for content areas
 * @param props - Tab panel configuration
 * @param state - Tab list state
 * @param ref - Ref to the panel element
 * @returns Tab panel props
 */
function useTabPanel(props: AriaTabPanelProps, state: TabListState<T>, ref: RefObject<Element>): TabPanelAria;

interface AriaTabListProps<T> extends AriaTabListOptions<T> {
  /** Items in the tab list */
  items?: Iterable<T>;
  /** Currently selected key */
  selectedKey?: Key | null;
  /** Default selected key (uncontrolled) */
  defaultSelectedKey?: Key | null;
  /** Handler called when selection changes */
  onSelectionChange?: (key: Key) => void;
  /** Orientation of the tab list */
  orientation?: Orientation;
  /** Whether tabs are disabled */
  isDisabled?: boolean;
  /** Keyboard activation mode */
  keyboardActivation?: 'automatic' | 'manual';
  /** Disabled keys */
  disabledKeys?: Iterable<Key>;
}

interface TabListAria {
  /** Props for the tab list element */
  tabListProps: DOMAttributes<Element>;
}

interface AriaTabProps {
  /** Key for the tab */
  key?: Key;
  /** Whether the tab is disabled */
  isDisabled?: boolean;
}

interface TabAria {
  /** Props for the tab element */
  tabProps: DOMAttributes<Element>;
  /** Whether the tab is selected */
  isSelected: boolean;
  /** Whether the tab is disabled */
  isDisabled: boolean;
  /** Whether the tab is pressed */
  isPressed: boolean;
}

interface AriaTabPanelProps {
  /** Key for the tab panel */
  key?: Key;
}

interface TabPanelAria {
  /** Props for the tab panel element */
  tabPanelProps: DOMAttributes<Element>;
}

/**
 * Provides breadcrumbs container behavior and accessibility
 * @param props - Breadcrumbs configuration
 * @param ref - Ref to the breadcrumbs element
 * @returns Breadcrumbs props
 */
function useBreadcrumbs(props: AriaBreadcrumbsProps, ref: RefObject<Element>): BreadcrumbsAria;

/**
 * Provides individual breadcrumb item behavior
 * @param props - Breadcrumb item configuration
 * @param ref - Ref to the breadcrumb element
 * @returns Breadcrumb item props
 */
function useBreadcrumbItem(props: AriaBreadcrumbItemProps, ref: RefObject<Element>): BreadcrumbItemAria;

interface AriaBreadcrumbsProps {
  /** Children breadcrumb items */
  children: ReactNode;
  /** Whether breadcrumbs are disabled */
  isDisabled?: boolean;
}

interface BreadcrumbsAria {
  /** Props for the breadcrumbs nav element */
  navProps: HTMLAttributes<HTMLElement>;
  /** Props for the breadcrumbs list element */
  listProps: HTMLAttributes<HTMLOListElement>;
}

interface AriaBreadcrumbItemProps {
  /** Children content */
  children: ReactNode;
  /** Whether this is the current page */
  isCurrent?: boolean;
  /** Whether the item is disabled */
  isDisabled?: boolean;
  /** Handler called when the item is activated */
  onAction?: () => void;
  /** Href for link behavior */
  href?: string;
  /** Target for link */
  target?: string;
  /** Rel for link */
  rel?: string;
}

interface BreadcrumbItemAria {
  /** Props for the breadcrumb item element */
  itemProps: HTMLAttributes<HTMLLIElement>;
  /** Props for the breadcrumb link element */
  linkProps: AnchorHTMLAttributes<HTMLAnchorElement> | ButtonHTMLAttributes<HTMLButtonElement>;
  /** Whether this is the current page */
  isCurrent: boolean;
  /** Whether the item is disabled */
  isDisabled: boolean;
}

/**
 * Provides table behavior and accessibility
 * @param props - Table configuration
 * @param state - Table state
 * @param ref - Ref to the table element
 * @returns Table props and state
 */
function useTable<T>(props: AriaTableProps<T>, state: TableState<T>, ref: RefObject<Element>): GridAria;

/**
 * Provides table row behavior
 * @param props - Table row configuration
 * @param state - Table state
 * @param ref - Ref to the row element
 * @returns Table row props and state
 */
function useTableRow<T>(props: GridRowProps<T>, state: TableState<T>, ref: RefObject<Element>): GridRowAria;

/**
 * Provides table cell behavior
 * @param props - Table cell configuration
 * @param state - Table state
 * @param ref - Ref to the cell element
 * @returns Table cell props
 */
function useTableCell(props: AriaTableCellProps, state: TableState<T>, ref: RefObject<Element>): TableCellAria;

/**
 * Provides table column header behavior with sorting
 * @param props - Column header configuration
 * @param state - Table state
 * @param ref - Ref to the header element
 * @returns Column header props and state
 */
function useTableColumnHeader<T>(props: AriaTableColumnHeaderProps, state: TableState<T>, ref: RefObject<Element>): TableColumnHeaderAria;

/**
 * Provides table row group behavior (thead, tbody, tfoot)
 * @param ref - Ref to the row group element
 * @returns Row group props
 */
function useTableRowGroup(ref: RefObject<Element>): TableHeaderRowAria;

/**
 * Provides table header row behavior
 * @param props - Header row configuration
 * @param state - Table state
 * @param ref - Ref to the header row element
 * @returns Header row props
 */
function useTableHeaderRow<T>(props: {}, state: TableState<T>, ref: RefObject<Element>): TableHeaderRowAria;

/**
 * Provides select all checkbox behavior for tables
 * @param props - Select all checkbox configuration
 * @param state - Table state
 * @param ref - Ref to the checkbox element
 * @returns Select all checkbox props
 */
function useTableSelectAllCheckbox<T>(props: AriaTableSelectionCheckboxProps, state: TableState<T>, ref: RefObject<Element>): TableSelectAllCheckboxAria;

/**
 * Provides selection checkbox behavior for table rows
 * @param props - Selection checkbox configuration
 * @param state - Table state
 * @param ref - Ref to the checkbox element
 * @returns Selection checkbox props
 */
function useTableSelectionCheckbox<T>(props: AriaTableSelectionCheckboxProps, state: TableState<T>, ref: RefObject<Element>): TableSelectionCheckboxAria;

/**
 * Provides column resize behavior for table columns
 * @param props - Column resize configuration
 * @param state - Table state
 * @param ref - Ref to the resize handle element
 * @returns Column resize props and state
 */
function useTableColumnResize<T>(props: AriaTableColumnResizeProps, state: TableState<T>, ref: RefObject<Element>): TableColumnResizeAria;

interface AriaTableProps<T> {
  /** Items in the table */
  items?: Iterable<T>;
  /** Selection mode */
  selectionMode?: SelectionMode;
  /** 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>;
  /** Sort descriptor */
  sortDescriptor?: SortDescriptor;
  /** Handler called when sort changes */
  onSortChange?: (descriptor: SortDescriptor) => void;
  /** Handler called when a row is activated */
  onAction?: (key: Key) => void;
  /** Handler called on row expansion */
  onExpandedChange?: (keys: Set<Key>) => void;
  /** Whether rows can be resized */
  allowsResizing?: boolean;
  /** Whether column headers are sticky */
  stickyColumnHeaders?: boolean;
}

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

/**
 * Provides tree behavior and accessibility
 * @param props - Tree configuration
 * @param state - Tree state
 * @param ref - Ref to the tree element
 * @returns Tree props and state
 */
function useTree<T>(props: AriaTreeProps<T>, state: TreeState<T>, ref: RefObject<Element>): TreeAria;

/**
 * Provides tree item behavior with expansion and selection
 * @param props - Tree item configuration
 * @param state - Tree state
 * @param ref - Ref to the tree item element
 * @returns Tree item props and state
 */
function useTreeItem<T>(props: AriaTreeItemOptions<T>, state: TreeState<T>, ref: RefObject<Element>): TreeItemAria;

interface AriaTreeProps<T> extends TreeProps<T> {
  /** Items in the tree */
  items?: Iterable<T>;
  /** Selection mode */
  selectionMode?: SelectionMode;
  /** Selected keys */
  selectedKeys?: 'all' | Iterable<Key>;
  /** Default selected keys (uncontrolled) */
  defaultSelectedKeys?: 'all' | Iterable<Key>;
  /** Handler called when selection changes */
  onSelectionChange?: (keys: Selection) => void;
  /** Expanded keys */
  expandedKeys?: Iterable<Key>;
  /** Default expanded keys (uncontrolled) */
  defaultExpandedKeys?: Iterable<Key>;
  /** Handler called when expansion changes */
  onExpandedChange?: (keys: Set<Key>) => void;
  /** Disabled keys */
  disabledKeys?: Iterable<Key>;
  /** Handler called when an item is activated */
  onAction?: (key: Key) => void;
  /** Whether the tree is disabled */
  isDisabled?: boolean;
  /** Auto-focus behavior */
  autoFocus?: boolean | FocusStrategy;
  /** Whether focus should wrap */
  shouldFocusWrap?: boolean;
}

interface TreeAria {
  /** Props for the tree element */
  treeProps: DOMAttributes<Element>;
}

interface AriaTreeItemOptions<T> {
  /** Key for the tree item */
  key: Key;
  /** Whether the item is disabled */
  isDisabled?: boolean;
  /** Whether the item should be focused */
  shouldSelectOnPressUp?: boolean;
  /** Whether the item should use virtual focus */
  shouldUseVirtualFocus?: boolean;
  /** Ref for the tree item */
  ref?: RefObject<Element>;
}

interface TreeItemAria {
  /** Props for the tree item element */
  rowProps: DOMAttributes<Element>;
  /** Props for the tree item content */
  gridCellProps: DOMAttributes<Element>;
  /** Props for the expand button */
  buttonProps: ButtonHTMLAttributes<HTMLButtonElement>;
  /** Props for the checkbox */
  checkboxProps: InputHTMLAttributes<HTMLInputElement>;
  /** Whether the item is selected */
  isSelected: boolean;
  /** Whether the item is expanded */
  isExpanded: boolean;
  /** Whether the item is disabled */
  isDisabled: boolean;
  /** Whether the item is pressed */
  isPressed: boolean;
  /** Level of the item in the tree */
  level: number;
  /** Whether the item has child items */
  hasChildRows: boolean;
}

/**
 * Provides link behavior and accessibility
 * @param props - Link configuration
 * @param ref - Ref to the link element
 * @returns Link props and state
 */
function useLink(props: AriaLinkOptions, ref: RefObject<Element>): LinkAria;

interface AriaLinkOptions {
  /** Whether the link is disabled */
  isDisabled?: boolean;
  /** Handler called when the link is activated */
  onPress?: (e: PressEvent) => void;
  /** Element type to render as */
  elementType?: React.ElementType;
}

interface LinkAria {
  /** Props for the link element */
  linkProps: AnchorHTMLAttributes<HTMLAnchorElement>;
  /** Whether the link is pressed */
  isPressed: boolean;
}

/**
 * Provides tag group behavior and accessibility
 * @param props - Tag group configuration
 * @param state - Tag group state
 * @param ref - Ref to the tag group element
 * @returns Tag group props and state
 */
function useTagGroup<T>(props: AriaTagGroupProps<T>, state: ListState<T>, ref: RefObject<Element>): TagGroupAria;

/**
 * Provides individual tag behavior
 * @param props - Tag configuration
 * @param state - Tag group state
 * @param ref - Ref to the tag element
 * @returns Tag props and state
 */
function useTag<T>(props: AriaTagProps, state: ListState<T>, ref: RefObject<Element>): TagAria;

interface AriaTagGroupProps<T> {
  /** Items in the tag group */
  items?: Iterable<T>;
  /** Selected keys */
  selectedKeys?: 'all' | Iterable<Key>;
  /** Default selected keys (uncontrolled) */
  defaultSelectedKeys?: 'all' | Iterable<Key>;
  /** Handler called when selection changes */
  onSelectionChange?: (keys: Selection) => void;
  /** Handler called when a tag is removed */
  onRemove?: (keys: Set<Key>) => void;
  /** Whether tags can be removed */
  allowsRemoving?: boolean;
  /** Whether the tag group is disabled */
  isDisabled?: boolean;
  /** Label for the tag group */
  label?: ReactNode;
  /** Description for the tag group */
  description?: ReactNode;
  /** Error message for the tag group */
  errorMessage?: ReactNode;
}

interface TagGroupAria {
  /** Props for the tag group element */
  gridProps: DOMAttributes<Element>;
  /** Props for the label element */
  labelProps: DOMAttributes<Element>;
  /** Props for the description element */
  descriptionProps: DOMAttributes<Element>;
  /** Props for the error message element */
  errorMessageProps: DOMAttributes<Element>;
}

interface AriaTagProps {
  /** Key for the tag */
  key?: Key;
  /** Whether the tag is disabled */
  isDisabled?: boolean;
  /** Text content of the tag */
  textContent?: string;
  /** Whether the tag can be removed */
  allowsRemoving?: boolean;
}

interface TagAria {
  /** Props for the tag row element */
  rowProps: DOMAttributes<Element>;
  /** Props for the tag content element */
  gridCellProps: DOMAttributes<Element>;
  /** Props for the remove button */
  removeButtonProps: ButtonHTMLAttributes<HTMLButtonElement>;
  /** Props for the tag description */
  descriptionProps: DOMAttributes<Element>;
  /** Whether the tag is selected */
  isSelected: boolean;
  /** Whether the tag is disabled */
  isDisabled: boolean;
  /** Whether the tag is pressed */
  isPressed: boolean;
  /** Whether the remove button is pressed */
  isRemoveButtonPressed: boolean;
  /** Allow removing the tag */
  allowsRemoving: boolean;
}

/**
 * Provides separator behavior and accessibility
 * @param props - Separator configuration
 * @param ref - Ref to the separator element
 * @returns Separator props
 */
function useSeparator(props: SeparatorProps, ref: RefObject<Element>): SeparatorAria;

interface SeparatorProps {
  /** Orientation of the separator */
  orientation?: Orientation;
  /** Element type to render */
  elementType?: string;
}

interface SeparatorAria {
  /** Props for the separator element */
  separatorProps: DOMAttributes<Element>;
}

/**
 * Provides landmark behavior and accessibility
 * @param props - Landmark configuration
 * @param ref - Ref to the landmark element
 * @returns Landmark props and controller
 */
function useLandmark(props: AriaLandmarkProps, ref: RefObject<Element>): LandmarkAria;

interface AriaLandmarkProps {
  /** ARIA landmark role */
  role?: AriaLandmarkRole;
  /** Accessible name for the landmark */
  'aria-label'?: string;
  /** ID of element that labels the landmark */
  'aria-labelledby'?: string;
}

interface LandmarkAria {
  /** Props for the landmark element */
  landmarkProps: DOMAttributes<Element>;
  /** Landmark controller for managing focus */
  landmarkController: LandmarkController;
}

type AriaLandmarkRole = 
  | 'banner'
  | 'complementary'
  | 'contentinfo'
  | 'form'
  | 'main'
  | 'navigation'
  | 'region'
  | 'search';

interface LandmarkController {
  /** Navigate to the next landmark */
  nextLandmark(): void;
  /** Navigate to the previous landmark */
  previousLandmark(): void;
  /** Get all landmarks on the page */
  getLandmarks(): Element[];
}

interface TabListState<T> {
  /** Collection of tab items */
  collection: Collection<Node<T>>;
  /** Currently selected key */
  selectedKey: Key | null;
  /** Set the selected key */
  setSelectedKey(key: Key): void;
  /** Selected item */
  selectedItem: Node<T> | null;
}

interface TableState<T> {
  /** Collection of table items */
  collection: Collection<Node<T>>;
  /** Set of selected keys */
  selectedKeys: Selection;
  /** Set the selected keys */
  setSelectedKeys(keys: Selection): void;
  /** Sort descriptor */
  sortDescriptor: SortDescriptor | null;
  /** Set the sort descriptor */
  setSortDescriptor(descriptor: SortDescriptor): void;
  /** Set of expanded keys */
  expandedKeys: Set<Key>;
  /** Toggle expansion of a key */
  toggleExpanded(key: Key): void;
}

interface TreeState<T> {
  /** Collection of tree items */
  collection: Collection<Node<T>>;
  /** Set of selected keys */
  selectedKeys: Selection;
  /** Set the selected keys */
  setSelectedKeys(keys: Selection): void;
  /** Set of expanded keys */
  expandedKeys: Set<Key>;
  /** Toggle expansion of a key */
  toggleExpanded(key: Key): void;
  /** Currently focused key */
  focusedKey: Key | null;
  /** Set the focused key */
  setFocusedKey(key: Key): void;
}

interface SortDescriptor {
  /** Column key to sort by */
  column: Key;
  /** Sort direction */
  direction: 'ascending' | 'descending';
}