Core Components

/**
 * Root container managing dropdown menu state
 * @param children - Child components (typically Trigger and Portal)
 * @param dir - Reading direction for layout
 * @param open - Controlled open state
 * @param defaultOpen - Default open state (uncontrolled)
 * @param onOpenChange - Callback when open state changes
 * @param modal - Whether menu should be modal (default: true)
 */
interface DropdownMenuProps {
  children?: React.ReactNode;
  dir?: 'ltr' | 'rtl';
  open?: boolean;
  defaultOpen?: boolean;
  onOpenChange?(open: boolean): void;
  modal?: boolean;
}

const DropdownMenu: React.FC<DropdownMenuProps>;

import * as DropdownMenu from "@radix-ui/react-dropdown-menu";

// Uncontrolled dropdown
<DropdownMenu.Root defaultOpen={false}>
  {/* trigger and content */}
</DropdownMenu.Root>

// Controlled dropdown
const [open, setOpen] = React.useState(false);
<DropdownMenu.Root open={open} onOpenChange={setOpen}>
  {/* trigger and content */}
</DropdownMenu.Root>

// Non-modal dropdown (allows interaction outside)
<DropdownMenu.Root modal={false}>
  {/* trigger and content */}
</DropdownMenu.Root>

/**
 * Trigger button component that opens/closes the dropdown
 * Extends all HTML button attributes and props
 * @param disabled - Whether the trigger is disabled
 * @param asChild - Compose with child element instead of rendering button
 */
interface DropdownMenuTriggerProps extends React.ComponentPropsWithoutRef<'button'> {
  disabled?: boolean;
  asChild?: boolean;
}

const DropdownMenuTrigger: React.ForwardRefExoticComponent<DropdownMenuTriggerProps>;

// Basic trigger
<DropdownMenu.Trigger>
  Menu
</DropdownMenu.Trigger>

// Custom trigger using asChild
<DropdownMenu.Trigger asChild>
  <button className="custom-button">
    <MenuIcon />
    Options
  </button>
</DropdownMenu.Trigger>

// Disabled trigger
<DropdownMenu.Trigger disabled>
  Unavailable
</DropdownMenu.Trigger>

/**
 * Content container for menu items, rendered as an overlay
 * @param align - Alignment relative to trigger ('start' | 'center' | 'end')
 * @param side - Preferred side to render on ('top' | 'right' | 'bottom' | 'left')
 * @param sideOffset - Distance from trigger in pixels
 * @param alignOffset - Offset from alignment position
 * @param avoidCollisions - Whether to avoid viewport collisions
 * @param collisionBoundary - Element(s) to avoid collisions with
 * @param collisionPadding - Padding from collision boundary
 * @param sticky - Sticky behavior ('partial' | 'always')
 * @param hideWhenDetached - Hide when trigger becomes fully obscured
 * @param onEscapeKeyDown - Callback when Escape key is pressed
 * @param onPointerDownOutside - Callback when pointer down occurs outside
 * @param onFocusOutside - Callback when focus moves outside
 * @param onInteractOutside - Callback when interaction occurs outside
 */
interface DropdownMenuContentProps {
  align?: 'start' | 'center' | 'end';
  side?: 'top' | 'right' | 'bottom' | 'left';
  sideOffset?: number;
  alignOffset?: number;
  avoidCollisions?: boolean;
  collisionBoundary?: Element | null | Array<Element | null>;
  collisionPadding?: number | Partial<Record<'top' | 'right' | 'bottom' | 'left', number>>;
  sticky?: 'partial' | 'always';
  hideWhenDetached?: boolean;
  onEscapeKeyDown?: (event: KeyboardEvent) => void;
  onPointerDownOutside?: (event: CustomEvent<{ originalEvent: PointerEvent }>) => void;
  onFocusOutside?: (event: CustomEvent<{ originalEvent: FocusEvent }>) => void;
  onInteractOutside?: (event: CustomEvent<{ originalEvent: PointerEvent | FocusEvent }>) => void;
  children?: React.ReactNode;
}

const DropdownMenuContent: React.ForwardRefExoticComponent<DropdownMenuContentProps>;

// Basic content
<DropdownMenu.Content>
  <DropdownMenu.Item>Option 1</DropdownMenu.Item>
  <DropdownMenu.Item>Option 2</DropdownMenu.Item>
</DropdownMenu.Content>

// Positioned content
<DropdownMenu.Content 
  side="right" 
  align="start" 
  sideOffset={5}
>
  <DropdownMenu.Item>Right-aligned menu</DropdownMenu.Item>
</DropdownMenu.Content>

// Content with collision avoidance
<DropdownMenu.Content
  avoidCollisions={true}
  collisionPadding={10}
  sticky="partial"
>
  <DropdownMenu.Item>Auto-positioned</DropdownMenu.Item>
</DropdownMenu.Content>

// Content with custom event handlers
<DropdownMenu.Content
  onEscapeKeyDown={(e) => console.log('Escape pressed')}
  onInteractOutside={(e) => console.log('Clicked outside')}
>
  <DropdownMenu.Item>Menu item</DropdownMenu.Item>
</DropdownMenu.Content>

// Short aliases for composition patterns
const Root = DropdownMenu;
const Trigger = DropdownMenuTrigger;
const Content = DropdownMenuContent;