import { Ref, ReactNode, ComponentPropsWithoutRef } 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 ListboxItemType<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?: ListboxItemType<T>;
    /** Default selected item (uncontrolled) */
    defaultSelected?: ListboxItemType<T>;
    /** Callback when selection changes */
    onSelectionChange?: (selected: ListboxItemType<T> | undefined) => void;
    /** Array of items to render */
    items: ListboxItemType<T>[];
    /** Optional render function for items */
    children?: ({ items }: {
        items: ListboxItemType<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?: ListboxItemType<T>[];
    /** Default selected items (uncontrolled) */
    defaultSelected?: ListboxItemType<T>[];
    /** Callback when selection changes */
    onSelectionChange?: (selected: ListboxItemType<T>[] | undefined) => void;
    /** Array of items to render */
    items: ListboxItemType<T>[];
    /** Optional render function for items */
    children?: ({ items }: {
        items: ListboxItemType<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>);
declare function ListboxInner<T>(props: ListboxProps<T>, ref: Ref<HTMLUListElement>): import("react/jsx-runtime").JSX.Element;
declare namespace ListboxInner {
    var displayName: string;
}
/**
 * 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
 * - Automatic tracking ID generation for analytics
 *
 * @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 ListboxInner>) & {
    /**
     * 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
     * - Automatic tracking ID generation for analytics
     * - 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 {};