import { ComponentPropsWithoutRef, Dispatch, SetStateAction, ReactNode, Ref } from 'react';
import { LayoutUtilProps } from '../../types';
/**
 * Represents an item in the listbox with a label and optional disabled state.
 * @template T - The type of additional properties for the item
 */
export type ItemType<T> = T & {
    /** The display label for the item */
    label: string;
    /** Whether the item is disabled and cannot be selected */
    disabled?: boolean;
};
/**
 * Props for single selection mode without items array
 */
type SingleWithoutItems = {
    /** Selection mode for single item selection */
    selectionMode?: "single";
    /** Whether to disable automatic selection when focusing on an option */
    disableAutoSelectOnFocus?: boolean;
    /** Currently selected item (controlled) */
    selected?: string;
    /** Default selected item (uncontrolled) */
    defaultSelected?: string;
    /** Callback when selection changes */
    onSelectionChange?: (selected: string | undefined) => void;
    /** Items array - not allowed in this mode */
    items?: never;
    /** Child elements to render */
    children: ReactNode;
};
/**
 * Props for multiple selection mode without items array
 */
type MultipleWithoutItems = {
    /** Selection mode for multiple item selection */
    selectionMode: "multiple";
    /** Auto-select on focus is not available in multiple mode */
    disableAutoSelectOnFocus?: never;
    /** Currently selected items (controlled) */
    selected?: string[];
    /** Default selected items (uncontrolled) */
    defaultSelected?: string[];
    /** Callback when selection changes */
    onSelectionChange?: (selected: string[] | undefined) => void;
    /** Items array - not allowed in this mode */
    items?: never;
    /** Child elements to render */
    children: ReactNode;
};
/**
 * Props for single selection mode with items array
 * @template T - The type of additional properties for items
 */
type SingleWithItems<T> = {
    /** Selection mode for single item selection */
    selectionMode?: "single";
    /** Whether to disable automatic selection when focusing on an option */
    disableAutoSelectOnFocus?: boolean;
    /** Currently selected item (controlled) */
    selected?: ItemType<T>;
    /** Default selected item (uncontrolled) */
    defaultSelected?: ItemType<T>;
    /** Callback when selection changes */
    onSelectionChange?: (selected: ItemType<T> | undefined) => void;
    /** Array of items to render */
    items: ItemType<T>[];
    /** Optional render function for items */
    children?: ({ items }: {
        items: ItemType<T>[];
    }) => ReactNode;
};
/**
 * Props for multiple selection mode with items array
 * @template T - The type of additional properties for items
 */
type MultipleWithItems<T> = {
    /** Selection mode for multiple item selection */
    selectionMode?: "multiple";
    /** Auto-select on focus is not available in multiple mode */
    disableAutoSelectOnFocus?: never;
    /** Currently selected items (controlled) */
    selected?: ItemType<T>[];
    /** Default selected items (uncontrolled) */
    defaultSelected?: ItemType<T>[];
    /** Callback when selection changes */
    onSelectionChange?: (selected: ItemType<T>[] | undefined) => void;
    /** Array of items to render */
    items: ItemType<T>[];
    /** Optional render function for items */
    children?: ({ items }: {
        items: ItemType<T>[];
    }) => ReactNode;
};
/**
 * Props for the Listbox component
 * @template T - The type of additional properties for items
 * @extends ComponentPropsWithoutRef<"ul">
 * @extends LayoutUtilProps
 */
export type ListboxProps<T> = Omit<ComponentPropsWithoutRef<"ul">, "children"> & LayoutUtilProps & (SingleWithoutItems | MultipleWithoutItems | SingleWithItems<T> | MultipleWithItems<T>);
/**
 * Context properties for the Listbox component
 * @template T - The type of additional properties for items
 */
export type ListboxContextProps<T> = {
    /** ID of the currently focused option */
    currentFocus?: string;
    /** Function to set the currently focused option */
    setCurrentFocus: Dispatch<SetStateAction<ListboxContextProps<T>["currentFocus"]>>;
    /** Currently selected option(s) */
    selected: ListboxProps<T>["defaultSelected"];
    /** Function to set the selected option(s) */
    setSelected: Dispatch<SetStateAction<ListboxContextProps<T>["selected"]>>;
    /** List of available option elements */
    options: NodeListOf<HTMLElement> | undefined;
    /** Current selection mode */
    selectionMode: Exclude<ListboxProps<T>["selectionMode"], undefined>;
    /** Callback when selection changes */
    onSelectionChange: ListboxProps<T>["onSelectionChange"];
    /** Whether auto-select on focus is disabled */
    disableAutoSelectOnFocus: boolean;
    /** Array of items if using items prop */
    items?: unknown[];
    /** Whether the component is controlled */
    controlled?: boolean;
};
/**
 * Context for sharing listbox state between components
 */
export declare const ListboxContext: import('react').Context<ListboxContextProps<any> | null>;
declare const ListboxElement: {
    <T>(props: ListboxProps<T>, ref: Ref<HTMLUListElement>): import("react/jsx-runtime").JSX.Element;
    displayName: string;
};
/**
 * Hook to access the listbox context
 * @returns The listbox context
 * @throws Error if used outside of a Listbox component
 */
export declare const useListbox: () => ListboxContextProps<any>;
/**
 * Listbox component for selecting one or more items from a list
 *
 * Features:
 * - Supports single and multiple selection modes
 * - Keyboard navigation with arrow keys and type-ahead
 * - Optional auto-selection on focus
 * - Controlled and uncontrolled modes
 * - Accessible with proper ARIA attributes
 * - Supports custom item rendering
 * - Option grouping for organization
 * - Layout utilities for positioning and spacing
 *
 * @template T - The type of additional properties for items
 * @example
 * <Listbox selectionMode="single" onSelectionChange={handleSelection}>
 *   <Listbox.Option value="option1">Option 1</Listbox.Option>
 *   <Listbox.Option value="option2">Option 2</Listbox.Option>
 * </Listbox>
 */
export declare const Listbox: (<T>(props: ListboxProps<T> & {
    ref?: React.ForwardedRef<HTMLUListElement>;
}) => ReturnType<typeof ListboxElement>) & {
    /**
     * ListboxOption component for individual selectable items within a listbox.
     *
     * Features:
     * - Displays selectable options with proper ARIA attributes
     * - Supports disabled state for non-selectable options
     * - Keyboard navigation support
     * - Accessible with screen reader support
     *
     * @example
     * <Listbox.Option value="option1" label="Option 1" />
     */
    Option: import('react').ForwardRefExoticComponent<import('./ListboxOption').ListboxOptionProps & import('react').RefAttributes<HTMLLIElement>>;
    /**
     * ListboxOptionGroup component for grouping related options within a listbox.
     *
     * Features:
     * - Groups related options with a descriptive label
     * - Maintains proper ARIA structure for accessibility
     * - Supports keyboard navigation within groups
     * - Visual separation of option categories
     *
     * @example
     * <Listbox.OptionGroup label="Fruits">
     *   <Listbox.Option value="apple">Apple</Listbox.Option>
     *   <Listbox.Option value="banana">Banana</Listbox.Option>
     * </Listbox.OptionGroup>
     */
    OptionGroup: import('react').ForwardRefExoticComponent<Omit<import('react').DetailedHTMLProps<import('react').HTMLAttributes<HTMLDivElement>, HTMLDivElement>, "ref"> & {
        disabled?: boolean;
        label: string;
    } & import('react').RefAttributes<HTMLDivElement>>;
};
export {};