import { DropdownOptionProps } from '../DropdownOptions/types';
import { DropdownProps } from './types';
/**
 * Dropdown - Select-like dropdown component for single selection
 *
 * A flexible dropdown component that allows users to select one option from
 * a list of choices. Uses a compound component pattern with DropdownOption
 * children. Provides keyboard navigation, accessibility features, click-outside
 * to close functionality, and automatic viewport-aware placement of the options list.
 *
 * On every open the component measures available space below the toggle button
 * and flips the list upward when there is not enough room, preventing the list
 * from being clipped by the viewport edge. This behavior can be overridden via
 * dropdownProps.dropdownPosition.
 *
 * Component structure:
 * - Dropdown (root container with context)
 *   - DropdownToggle (button that opens/closes dropdown)
 *   - DropdownOptions (menu container that appears when open)
 *     - DropdownOption (individual selectable items)
 *
 * @category Form Controls
 * @subcategory Selection
 *
 * @example
 * ```tsx
 * const items = [
 *   { id: 1, value: 'Apple' },
 *   { id: 2, value: 'Banana' },
 *   { id: 3, value: 'Cherry' },
 * ];
 *
 * <Dropdown
 *   selectedItem={items[0]}
 *   onChange={(item) => handleSelection(item)}
 *   placeholder="Select a fruit"
 * >
 *   {items.map(item => (
 *     <DropdownOption key={item.id} value={item.id}>
 *       {item.value}
 *     </DropdownOption>
 *   ))}
 * </Dropdown>
 * ```
 *
 * @example
 * ```tsx
 * // Controlled open state
 * const [isOpen, setIsOpen] = useState(false);
 * <Dropdown
 *   isOpen={isOpen}
 *   onChange={handleChange}
 *   selectedItem={selected}
 * >
 *   {options.map(opt => (
 *     <DropdownOption key={opt.id} value={opt.id}>
 *       {opt.label}
 *     </DropdownOption>
 *   ))}
 * </Dropdown>
 * ```
 *
 * @example
 * ```tsx
 * // With custom props for sub-components and forced upward placement
 * <Dropdown
 *   selectedItem={selected}
 *   onChange={handleChange}
 *   dropdownProps={{
 *     base: { id: 'my-dropdown' },
 *     toggleButton: { 'data-testid': 'dropdown-toggle' },
 *     toggleButtonArrow: { className: 'custom-arrow' },
 *     dropdownPosition: DropdownPositions.top,
 *   }}
 * >
 *   {options.map(opt => (
 *     <DropdownOption key={opt.id} value={opt.id}>
 *       {opt.label}
 *     </DropdownOption>
 *   ))}
 * </Dropdown>
 * ```
 *
 * @see {@link DropdownOption} - Child component for individual options
 * @see {@link DropdownToggle} - Toggle button component
 * @see {@link DropdownOptions} - Options menu container
 *
 * @accessibility
 * - ARIA attributes set according to WAI-ARIA combobox pattern
 * - Keyboard navigation (Arrow keys, Enter, Escape)
 * - Click outside to close
 * - Screen reader friendly
 * - Focus management
 *
 * @see https://www.w3.org/WAI/ARIA/apg/example-index/combobox/combobox-select-only.html
 */
declare const Dropdown: <T extends DropdownOptionProps>({ selectedItem, isDisabled, isOpen: isInitOpen, children, onChange: handleChange, className, placeholder, maxHeight, avatarBorder, dropdownProps: componentProps, }: DropdownProps<T>) => import("@emotion/react/jsx-runtime").JSX.Element;
export default Dropdown;
