@neynar/ui 0.1.1 → 0.1.3

package/dist/components/ui/dropdown-menu.d.ts

@@ -7,10 +7,15 @@ import * as DropdownMenuPrimitive from "@radix-ui/react-dropdown-menu";
  * They're typically triggered by a button and appear as a floating panel with full
  * keyboard navigation support, submenus, and various interactive item types.
  *
- * Based on the shadcn/ui dropdown-menu component with additional enhancements for
- * better integration with design systems and improved accessibility.
+ * Built on Radix UI's DropdownMenu primitive with enhanced styling and type safety.
+ * Follows the WAI-ARIA Menu Button pattern for accessibility compliance.
+ *
+ * @param defaultOpen - Whether the dropdown is initially open (uncontrolled mode)
+ * @param open - Whether the dropdown is open (controlled mode)
+ * @param onOpenChange - Callback fired when the open state changes
+ * @param modal - Whether the dropdown should be modal (blocks interaction with outside elements)
+ * @param dir - The reading direction of the dropdown menu
  *
- * @component
  * @example
  * ```tsx
  * // Basic dropdown menu
@@ -29,8 +34,10 @@ import * as DropdownMenuPrimitive from "@radix-ui/react-dropdown-menu";
  *
  * @example
  * ```tsx
- * // Context menu with alignment and destructive actions
- * <DropdownMenu>
+ * // Controlled dropdown with alignment
+ * const [open, setOpen] = useState(false);
+ *
+ * <DropdownMenu open={open} onOpenChange={setOpen}>
  *   <DropdownMenuTrigger asChild>
  *     <Button variant="ghost" size="icon">
  *       <MoreHorizontal />
@@ -48,6 +55,9 @@ import * as DropdownMenuPrimitive from "@radix-ui/react-dropdown-menu";
  * @example
  * ```tsx
  * // Complex menu with checkboxes, radio groups, and submenus
+ * const [showPanel, setShowPanel] = useState(true);
+ * const [position, setPosition] = useState("top");
+ *
  * <DropdownMenu>
  *   <DropdownMenuTrigger asChild>
  *     <Button>Advanced Menu</Button>
@@ -78,17 +88,19 @@ import * as DropdownMenuPrimitive from "@radix-ui/react-dropdown-menu";
  * @accessibility
  * - Full keyboard navigation with arrow keys (Up/Down for navigation)
  * - Enter/Space to activate items
- * - Escape key closes the menu and restores focus
+ * - Escape key closes the menu and restores focus to the trigger
  * - Home/End keys navigate to first/last item
  * - Type-ahead search to jump to items by first letter
  * - Left/Right arrow keys for submenu navigation
  * - Proper ARIA roles (menu, menuitem, menuitemcheckbox, menuitemradio)
  * - Focus management with focus trapping and restoration
  * - Screen reader announcements for state changes
+ * - Supports roving tabindex for focus movement
  *
  * @see {@link ContextMenu} - For right-click context menus
  * @see {@link Popover} - For rich content overlays
  * @see {@link Select} - For single selection dropdowns
+ * @see {@link https://www.radix-ui.com/primitives/docs/components/dropdown-menu} - Radix UI documentation
  * @see {@link https://ui.shadcn.com/docs/components/dropdown-menu} - shadcn/ui documentation
  * @since 1.0.0
  */
@@ -98,68 +110,168 @@ declare function DropdownMenu({ ...props }: React.ComponentProps<typeof Dropdown
  *
  * Renders dropdown content outside of the normal DOM hierarchy to avoid
  * z-index and overflow issues. Automatically used by DropdownMenuContent
- * but can be used explicitly for submenus.
+ * but can be used explicitly for advanced positioning scenarios.
+ *
+ * @param container - Optional container element for portal rendering. If not provided, portals to document.body
  *
- * @component
- * @param container - Optional container element for portal rendering
+ * @example
+ * ```tsx
+ * <DropdownMenuPortal container={customContainer}>
+ *   <DropdownMenuContent>
+ *     <DropdownMenuItem>Item</DropdownMenuItem>
+ *   </DropdownMenuContent>
+ * </DropdownMenuPortal>
+ * ```
  * @since 1.0.0
  */
 declare function DropdownMenuPortal({ ...props }: React.ComponentProps<typeof DropdownMenuPrimitive.Portal>): import("react/jsx-runtime").JSX.Element;
 /**
- * DropdownMenuTrigger - The element that triggers the dropdown menu
+ * The element that triggers the dropdown menu
+ *
+ * Renders the interactive element that opens and closes the dropdown menu.
+ * Typically wraps a button or other interactive element using the asChild prop.
+ * Automatically receives proper ARIA attributes and keyboard event handlers.
+ *
+ * @param asChild - Merge props onto the immediate child instead of rendering a wrapper element
  *
- * @component
  * @example
  * ```tsx
+ * // Basic trigger with button
  * <DropdownMenuTrigger asChild>
- *   <Button>Menu</Button>
+ *   <Button variant="outline">Open Menu</Button>
+ * </DropdownMenuTrigger>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Icon button trigger
+ * <DropdownMenuTrigger asChild>
+ *   <Button variant="ghost" size="icon" aria-label="More options">
+ *     <MoreVertical className="h-4 w-4" />
+ *   </Button>
  * </DropdownMenuTrigger>
  * ```
  * @since 1.0.0
  */
 declare function DropdownMenuTrigger({ ...props }: React.ComponentProps<typeof DropdownMenuPrimitive.Trigger>): import("react/jsx-runtime").JSX.Element;
 /**
- * DropdownMenuContent - The content container for dropdown menu items
+ * The content container for dropdown menu items
+ *
+ * Contains all menu items and handles positioning relative to the trigger.
+ * Automatically portals content to avoid z-index issues and includes sophisticated
+ * collision detection to keep the menu visible within viewport boundaries.
+ *
+ * @param side - The preferred side of the trigger to render against
+ * @param sideOffset - Distance in pixels from the trigger
+ * @param align - The preferred alignment against the trigger
+ * @param alignOffset - Distance in pixels from the align point
+ * @param avoidCollisions - Whether to avoid collisions with viewport boundaries
+ * @param loop - When true, keyboard navigation will loop from last to first item
+ * @param sticky - Element positioning behavior relative to the viewport
+ * @param hideWhenDetached - Whether to hide the content when the reference element is fully occluded
  *
- * @component
  * @example
  * ```tsx
- * <DropdownMenuContent align="end" sideOffset={5}>
- *   <DropdownMenuItem>Item 1</DropdownMenuItem>
+ * // Basic content with default positioning
+ * <DropdownMenuContent>
+ *   <DropdownMenuItem>Profile</DropdownMenuItem>
+ *   <DropdownMenuItem>Settings</DropdownMenuItem>
+ * </DropdownMenuContent>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Content with custom alignment and offset
+ * <DropdownMenuContent align="end" sideOffset={8}>
+ *   <DropdownMenuItem>Edit</DropdownMenuItem>
+ *   <DropdownMenuItem variant="destructive">Delete</DropdownMenuItem>
+ * </DropdownMenuContent>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Content with collision avoidance disabled
+ * <DropdownMenuContent avoidCollisions={false} side="top">
+ *   <DropdownMenuItem>Always above trigger</DropdownMenuItem>
  * </DropdownMenuContent>
  * ```
  * @since 1.0.0
  */
-declare function DropdownMenuContent({ className, sideOffset, ...props }: React.ComponentProps<typeof DropdownMenuPrimitive.Content>): import("react/jsx-runtime").JSX.Element;
+declare function DropdownMenuContent({ className, sideOffset, ...props }: React.ComponentProps<typeof DropdownMenuPrimitive.Content> & {
+    className?: string;
+}): import("react/jsx-runtime").JSX.Element;
 /**
  * Groups related dropdown menu items together
  *
  * Used to create logical groupings of menu items, typically separated by
  * DropdownMenuSeparator components. Helps with semantic organization and
- * keyboard navigation.
+ * improves accessibility by providing proper group semantics to screen readers.
+ *
+ * @param asChild - Merge props onto the immediate child instead of rendering a wrapper element
  *
- * @component
  * @example
  * ```tsx
- * <DropdownMenuGroup>
- *   <DropdownMenuItem>Profile</DropdownMenuItem>
- *   <DropdownMenuItem>Settings</DropdownMenuItem>
- * </DropdownMenuGroup>
+ * <DropdownMenuContent>
+ *   <DropdownMenuGroup>
+ *     <DropdownMenuItem>Profile</DropdownMenuItem>
+ *     <DropdownMenuItem>Account Settings</DropdownMenuItem>
+ *   </DropdownMenuGroup>
+ *   <DropdownMenuSeparator />
+ *   <DropdownMenuGroup>
+ *     <DropdownMenuItem>Help</DropdownMenuItem>
+ *     <DropdownMenuItem>Support</DropdownMenuItem>
+ *   </DropdownMenuGroup>
+ * </DropdownMenuContent>
  * ```
  * @since 1.0.0
  */
 declare function DropdownMenuGroup({ ...props }: React.ComponentProps<typeof DropdownMenuPrimitive.Group>): import("react/jsx-runtime").JSX.Element;
 /**
- * DropdownMenuItem - A single item in the dropdown menu
+ * A single interactive item in the dropdown menu
+ *
+ * Renders a clickable menu item with proper focus management and keyboard navigation.
+ * Supports different visual variants for semantic meaning (e.g., destructive actions).
+ * Includes built-in styling for icons, disabled states, and focus indicators.
+ *
+ * @param disabled - Whether the item is disabled and cannot be selected
+ * @param onSelect - Callback fired when the item is selected via click or keyboard
+ * @param textValue - Optional text value used for typeahead search functionality
+ * @param inset - Whether to add extra left padding to align with items that have icons
+ * @param variant - Visual variant of the menu item for semantic distinction
+ *
+ * @example
+ * ```tsx
+ * // Basic menu item with click handler
+ * <DropdownMenuItem onSelect={() => console.log('Profile clicked')}>
+ *   <User className="mr-2 h-4 w-4" />
+ *   Profile
+ * </DropdownMenuItem>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Destructive action item
+ * <DropdownMenuItem variant="destructive" onSelect={handleDelete}>
+ *   <Trash className="mr-2 h-4 w-4" />
+ *   Delete Account
+ * </DropdownMenuItem>
+ * ```
  *
- * @component
  * @example
  * ```tsx
- * <DropdownMenuItem onClick={handleClick}>
- *   Edit
+ * // Disabled item
+ * <DropdownMenuItem disabled>
+ *   <Settings className="mr-2 h-4 w-4" />
+ *   Settings (Coming Soon)
  * </DropdownMenuItem>
- * <DropdownMenuItem variant="destructive">
- *   Delete
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Item with keyboard shortcut
+ * <DropdownMenuItem onSelect={handleSave}>
+ *   Save Document
+ *   <DropdownMenuShortcut>⌘S</DropdownMenuShortcut>
  * </DropdownMenuItem>
  * ```
  * @since 1.0.0
@@ -167,51 +279,117 @@ declare function DropdownMenuGroup({ ...props }: React.ComponentProps<typeof Dro
 declare function DropdownMenuItem({ className, inset, variant, ...props }: React.ComponentProps<typeof DropdownMenuPrimitive.Item> & {
     inset?: boolean;
     variant?: "default" | "destructive";
+    className?: string;
 }): import("react/jsx-runtime").JSX.Element;
 /**
  * A checkable menu item with visual state indication
  *
  * Displays a checkbox that can be toggled on/off. The checked state is
- * visually indicated with a checkmark icon. Useful for menu options that
- * represent toggleable settings or features.
+ * visually indicated with a checkmark icon. Supports indeterminate state
+ * for partial selections. Ideal for menu options that represent toggleable
+ * settings, features, or multi-selection scenarios.
  *
- * @component
- * @param checked - Whether the checkbox is checked
- * @param onCheckedChange - Callback when the checked state changes
- * @param disabled - Whether the item is disabled
+ * @param checked - The checked state of the checkbox item (boolean or "indeterminate")
+ * @param onCheckedChange - Callback fired when the checked state changes
+ * @param disabled - Whether the item is disabled and cannot be interacted with
+ * @param onSelect - Callback fired when the item is selected via click or keyboard
+ * @param textValue - Optional text value used for typeahead search functionality
+ * @param inset - Whether to add extra left padding to align with items that have icons
  *
  * @example
  * ```tsx
+ * // Basic checkbox item with state
  * const [showSidebar, setShowSidebar] = useState(true);
  *
  * <DropdownMenuCheckboxItem
  *   checked={showSidebar}
  *   onCheckedChange={setShowSidebar}
  * >
+ *   <Sidebar className="mr-2 h-4 w-4" />
  *   Show Sidebar
  * </DropdownMenuCheckboxItem>
  * ```
+ *
+ * @example
+ * ```tsx
+ * // Multiple checkbox items for feature toggles
+ * const [features, setFeatures] = useState({
+ *   notifications: true,
+ *   autoSave: false,
+ *   darkMode: true
+ * });
+ *
+ * <DropdownMenuCheckboxItem
+ *   checked={features.notifications}
+ *   onCheckedChange={(checked) => setFeatures(prev => ({ ...prev, notifications: checked }))}
+ * >
+ *   Enable Notifications
+ * </DropdownMenuCheckboxItem>
+ * <DropdownMenuCheckboxItem
+ *   checked={features.autoSave}
+ *   onCheckedChange={(checked) => setFeatures(prev => ({ ...prev, autoSave: checked }))}
+ * >
+ *   Auto-save Changes
+ * </DropdownMenuCheckboxItem>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Indeterminate state for partial selections
+ * <DropdownMenuCheckboxItem
+ *   checked="indeterminate"
+ *   onCheckedChange={handleSelectAll}
+ * >
+ *   Select All Items (Some selected)
+ * </DropdownMenuCheckboxItem>
+ * ```
  * @since 1.0.0
  */
-declare function DropdownMenuCheckboxItem({ className, children, checked, ...props }: React.ComponentProps<typeof DropdownMenuPrimitive.CheckboxItem>): import("react/jsx-runtime").JSX.Element;
+declare function DropdownMenuCheckboxItem({ className, children, checked, ...props }: React.ComponentProps<typeof DropdownMenuPrimitive.CheckboxItem> & {
+    className?: string;
+}): import("react/jsx-runtime").JSX.Element;
 /**
  * Groups radio items for single selection
  *
  * Creates a group where only one radio item can be selected at a time.
- * Use with DropdownMenuRadioItem components to create single-choice options.
+ * Manages the selection state and ensures mutual exclusivity between options.
+ * Use with DropdownMenuRadioItem components to create single-choice scenarios
+ * like theme selection, sorting options, or view modes.
  *
- * @component
- * @param value - Currently selected value
- * @param onValueChange - Callback when selection changes
+ * @param value - The currently selected value in the radio group
+ * @param onValueChange - Callback fired when the selection changes to a different value
+ * @param disabled - Whether the entire radio group is disabled
  *
  * @example
  * ```tsx
+ * // Theme selection with radio group
  * const [theme, setTheme] = useState("light");
  *
  * <DropdownMenuRadioGroup value={theme} onValueChange={setTheme}>
- *   <DropdownMenuRadioItem value="light">Light</DropdownMenuRadioItem>
- *   <DropdownMenuRadioItem value="dark">Dark</DropdownMenuRadioItem>
- *   <DropdownMenuRadioItem value="system">System</DropdownMenuRadioItem>
+ *   <DropdownMenuRadioItem value="light">
+ *     <Sun className="mr-2 h-4 w-4" />
+ *     Light Theme
+ *   </DropdownMenuRadioItem>
+ *   <DropdownMenuRadioItem value="dark">
+ *     <Moon className="mr-2 h-4 w-4" />
+ *     Dark Theme
+ *   </DropdownMenuRadioItem>
+ *   <DropdownMenuRadioItem value="system">
+ *     <Monitor className="mr-2 h-4 w-4" />
+ *     System Theme
+ *   </DropdownMenuRadioItem>
+ * </DropdownMenuRadioGroup>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Sorting options
+ * const [sortBy, setSortBy] = useState("name");
+ *
+ * <DropdownMenuRadioGroup value={sortBy} onValueChange={setSortBy}>
+ *   <DropdownMenuRadioItem value="name">Sort by Name</DropdownMenuRadioItem>
+ *   <DropdownMenuRadioItem value="date">Sort by Date</DropdownMenuRadioItem>
+ *   <DropdownMenuRadioItem value="size">Sort by Size</DropdownMenuRadioItem>
  * </DropdownMenuRadioGroup>
  * ```
  * @since 1.0.0
@@ -221,129 +399,398 @@ declare function DropdownMenuRadioGroup({ ...props }: React.ComponentProps<typeo
  * A radio button menu item for single selection within a group
  *
  * Must be used within a DropdownMenuRadioGroup. Shows a filled circle
- * indicator when selected. Only one radio item can be selected per group.
+ * indicator when selected. Only one radio item can be selected per group,
+ * ensuring mutually exclusive selection behavior.
  *
- * @component
- * @param value - The value this radio item represents
- * @param disabled - Whether the item is disabled
+ * @param value - The unique value this radio item represents
+ * @param disabled - Whether the item is disabled and cannot be selected
+ * @param onSelect - Callback fired when the item is selected via click or keyboard
+ * @param textValue - Optional text value used for typeahead search functionality
+ * @param inset - Whether to add extra left padding to align with items that have icons
  *
  * @example
  * ```tsx
+ * // Basic radio group for theme selection
  * <DropdownMenuRadioGroup value={selectedTheme} onValueChange={setSelectedTheme}>
  *   <DropdownMenuRadioItem value="light">
+ *     <Sun className="mr-2 h-4 w-4" />
  *     Light Theme
  *   </DropdownMenuRadioItem>
  *   <DropdownMenuRadioItem value="dark">
+ *     <Moon className="mr-2 h-4 w-4" />
  *     Dark Theme
  *   </DropdownMenuRadioItem>
+ *   <DropdownMenuRadioItem value="system">
+ *     <Monitor className="mr-2 h-4 w-4" />
+ *     System Theme
+ *   </DropdownMenuRadioItem>
+ * </DropdownMenuRadioGroup>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Priority selection with disabled option
+ * <DropdownMenuRadioGroup value={priority} onValueChange={setPriority}>
+ *   <DropdownMenuRadioItem value="low">Low Priority</DropdownMenuRadioItem>
+ *   <DropdownMenuRadioItem value="medium">Medium Priority</DropdownMenuRadioItem>
+ *   <DropdownMenuRadioItem value="high">High Priority</DropdownMenuRadioItem>
+ *   <DropdownMenuRadioItem value="urgent" disabled>
+ *     Urgent (Premium Only)
+ *   </DropdownMenuRadioItem>
  * </DropdownMenuRadioGroup>
  * ```
  * @since 1.0.0
  */
-declare function DropdownMenuRadioItem({ className, children, ...props }: React.ComponentProps<typeof DropdownMenuPrimitive.RadioItem>): import("react/jsx-runtime").JSX.Element;
+declare function DropdownMenuRadioItem({ className, children, ...props }: React.ComponentProps<typeof DropdownMenuPrimitive.RadioItem> & {
+    className?: string;
+}): import("react/jsx-runtime").JSX.Element;
 /**
- * DropdownMenuLabel - A label for grouping menu items
+ * A non-interactive label for grouping and organizing menu items
+ *
+ * Used to provide semantic headers for groups of related menu items.
+ * Labels are not focusable and serve as visual and accessibility landmarks
+ * within the menu structure. Helps users understand the organization of menu options.
+ *
+ * @param asChild - Merge props onto the immediate child instead of rendering a wrapper element
+ * @param inset - Whether to add extra left padding to align with items that have icons
+ *
+ * @example
+ * ```tsx
+ * // Basic label for menu section
+ * <DropdownMenuContent>
+ *   <DropdownMenuLabel>Account Actions</DropdownMenuLabel>
+ *   <DropdownMenuSeparator />
+ *   <DropdownMenuItem>View Profile</DropdownMenuItem>
+ *   <DropdownMenuItem>Account Settings</DropdownMenuItem>
+ *
+ *   <DropdownMenuSeparator />
+ *   <DropdownMenuLabel>Preferences</DropdownMenuLabel>
+ *   <DropdownMenuItem>Theme Settings</DropdownMenuItem>
+ *   <DropdownMenuItem>Notification Settings</DropdownMenuItem>
+ * </DropdownMenuContent>
+ * ```
  *
- * @component
  * @example
  * ```tsx
- * <DropdownMenuLabel>Actions</DropdownMenuLabel>
+ * // Label with inset alignment
+ * <DropdownMenuContent>
+ *   <DropdownMenuLabel inset>File Operations</DropdownMenuLabel>
+ *   <DropdownMenuItem>
+ *     <Download className="mr-2 h-4 w-4" />
+ *     Download
+ *   </DropdownMenuItem>
+ *   <DropdownMenuItem>
+ *     <Upload className="mr-2 h-4 w-4" />
+ *     Upload
+ *   </DropdownMenuItem>
+ * </DropdownMenuContent>
  * ```
  * @since 1.0.0
  */
 declare function DropdownMenuLabel({ className, inset, ...props }: React.ComponentProps<typeof DropdownMenuPrimitive.Label> & {
     inset?: boolean;
+    className?: string;
 }): import("react/jsx-runtime").JSX.Element;
 /**
- * DropdownMenuSeparator - A visual separator between menu items
+ * A visual separator between menu items or groups
+ *
+ * Renders a thin horizontal line to visually separate different sections
+ * of menu items. Improves visual hierarchy and helps users understand
+ * the logical grouping of menu options. Commonly used after labels
+ * or between different types of actions.
+ *
+ * @param asChild - Merge props onto the immediate child instead of rendering a wrapper element
+ *
+ * @example
+ * ```tsx
+ * // Separating different action groups
+ * <DropdownMenuContent>
+ *   <DropdownMenuItem>View</DropdownMenuItem>
+ *   <DropdownMenuItem>Edit</DropdownMenuItem>
+ *   <DropdownMenuSeparator />
+ *   <DropdownMenuItem variant="destructive">Delete</DropdownMenuItem>
+ * </DropdownMenuContent>
+ * ```
  *
- * @component
+ * @example
+ * ```tsx
+ * // Separating sections with labels
+ * <DropdownMenuContent>
+ *   <DropdownMenuLabel>User Actions</DropdownMenuLabel>
+ *   <DropdownMenuSeparator />
+ *   <DropdownMenuItem>Profile</DropdownMenuItem>
+ *   <DropdownMenuItem>Settings</DropdownMenuItem>
+ *
+ *   <DropdownMenuSeparator />
+ *   <DropdownMenuLabel>System</DropdownMenuLabel>
+ *   <DropdownMenuSeparator />
+ *   <DropdownMenuItem>Logout</DropdownMenuItem>
+ * </DropdownMenuContent>
+ * ```
  * @since 1.0.0
  */
-declare function DropdownMenuSeparator({ className, ...props }: React.ComponentProps<typeof DropdownMenuPrimitive.Separator>): import("react/jsx-runtime").JSX.Element;
+declare function DropdownMenuSeparator({ className, ...props }: React.ComponentProps<typeof DropdownMenuPrimitive.Separator> & {
+    className?: string;
+}): import("react/jsx-runtime").JSX.Element;
 /**
  * Displays keyboard shortcut hints in menu items
  *
  * Shows keyboard shortcut text aligned to the right side of menu items.
- * Purely visual - does not implement the actual keyboard functionality.
- * Use standard keyboard shortcut notation (⌘, ⌃, ⌥, ⇧).
+ * Purely visual component - does not implement the actual keyboard functionality.
+ * Use standard keyboard shortcut notation and symbols (⌘, ⌃, ⌥, ⇧, Ctrl, Alt, Shift).
+ * Helps users discover and remember keyboard shortcuts for menu actions.
  *
- * @component
  * @example
  * ```tsx
- * <DropdownMenuItem>
+ * // macOS style shortcuts
+ * <DropdownMenuItem onSelect={handleSave}>
  *   Save Document
  *   <DropdownMenuShortcut>⌘S</DropdownMenuShortcut>
  * </DropdownMenuItem>
  * ```
+ *
+ * @example
+ * ```tsx
+ * // Windows/Linux style shortcuts
+ * <DropdownMenuItem onSelect={handleCopy}>
+ *   Copy
+ *   <DropdownMenuShortcut>Ctrl+C</DropdownMenuShortcut>
+ * </DropdownMenuItem>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Complex shortcuts with multiple modifiers
+ * <DropdownMenuItem onSelect={handleForceRefresh}>
+ *   Force Refresh
+ *   <DropdownMenuShortcut>⌘⇧R</DropdownMenuShortcut>
+ * </DropdownMenuItem>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Multiple menu items with shortcuts
+ * <DropdownMenuContent>
+ *   <DropdownMenuItem>
+ *     New File <DropdownMenuShortcut>⌘N</DropdownMenuShortcut>
+ *   </DropdownMenuItem>
+ *   <DropdownMenuItem>
+ *     Open File <DropdownMenuShortcut>⌘O</DropdownMenuShortcut>
+ *   </DropdownMenuItem>
+ *   <DropdownMenuSeparator />
+ *   <DropdownMenuItem>
+ *     Save <DropdownMenuShortcut>⌘S</DropdownMenuShortcut>
+ *   </DropdownMenuItem>
+ *   <DropdownMenuItem>
+ *     Save As <DropdownMenuShortcut>⌘⇧S</DropdownMenuShortcut>
+ *   </DropdownMenuItem>
+ * </DropdownMenuContent>
+ * ```
  * @since 1.0.0
  */
-declare function DropdownMenuShortcut({ className, ...props }: React.ComponentProps<"span">): import("react/jsx-runtime").JSX.Element;
+declare function DropdownMenuShortcut({ className, ...props }: React.ComponentProps<"span"> & {
+    className?: string;
+}): import("react/jsx-runtime").JSX.Element;
 /**
  * Container for creating nested submenus
  *
  * Wraps a submenu trigger and content to create hierarchical menu structures.
- * Use with DropdownMenuSubTrigger and DropdownMenuSubContent.
+ * Enables multi-level navigation within dropdown menus. Use with
+ * DropdownMenuSubTrigger and DropdownMenuSubContent to build complex
+ * menu hierarchies with proper focus management and keyboard navigation.
+ *
+ * @param defaultOpen - Whether the submenu is initially open (uncontrolled mode)
+ * @param open - Whether the submenu is open (controlled mode)
+ * @param onOpenChange - Callback fired when the submenu open state changes
  *
- * @component
  * @example
  * ```tsx
+ * // Basic submenu structure
  * <DropdownMenuSub>
+ *   <DropdownMenuSubTrigger>
+ *     <Share className="mr-2 h-4 w-4" />
+ *     Share Options
+ *   </DropdownMenuSubTrigger>
+ *   <DropdownMenuSubContent>
+ *     <DropdownMenuItem>Email Link</DropdownMenuItem>
+ *     <DropdownMenuItem>Copy to Clipboard</DropdownMenuItem>
+ *     <DropdownMenuItem>Generate QR Code</DropdownMenuItem>
+ *   </DropdownMenuSubContent>
+ * </DropdownMenuSub>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Controlled submenu with state management
+ * const [isShareOpen, setIsShareOpen] = useState(false);
+ *
+ * <DropdownMenuSub open={isShareOpen} onOpenChange={setIsShareOpen}>
  *   <DropdownMenuSubTrigger>Share</DropdownMenuSubTrigger>
  *   <DropdownMenuSubContent>
- *     <DropdownMenuItem>Email</DropdownMenuItem>
- *     <DropdownMenuItem>Copy Link</DropdownMenuItem>
+ *     <DropdownMenuItem onSelect={() => handleShare('email')}>Email</DropdownMenuItem>
+ *     <DropdownMenuItem onSelect={() => handleShare('link')}>Copy Link</DropdownMenuItem>
  *   </DropdownMenuSubContent>
  * </DropdownMenuSub>
  * ```
+ *
+ * @example
+ * ```tsx
+ * // Complex nested menu structure
+ * <DropdownMenuContent>
+ *   <DropdownMenuItem>Edit</DropdownMenuItem>
+ *   <DropdownMenuSeparator />
+ *   <DropdownMenuSub>
+ *     <DropdownMenuSubTrigger>Export</DropdownMenuSubTrigger>
+ *     <DropdownMenuSubContent>
+ *       <DropdownMenuItem>Export as PDF</DropdownMenuItem>
+ *       <DropdownMenuItem>Export as PNG</DropdownMenuItem>
+ *       <DropdownMenuSub>
+ *         <DropdownMenuSubTrigger>Advanced Export</DropdownMenuSubTrigger>
+ *         <DropdownMenuSubContent>
+ *           <DropdownMenuItem>Custom Resolution</DropdownMenuItem>
+ *           <DropdownMenuItem>Batch Export</DropdownMenuItem>
+ *         </DropdownMenuSubContent>
+ *       </DropdownMenuSub>
+ *     </DropdownMenuSubContent>
+ *   </DropdownMenuSub>
+ * </DropdownMenuContent>
+ * ```
  * @since 1.0.0
  */
 declare function DropdownMenuSub({ ...props }: React.ComponentProps<typeof DropdownMenuPrimitive.Sub>): import("react/jsx-runtime").JSX.Element;
 /**
  * Trigger element for opening a submenu
  *
- * Displays an arrow indicator and opens the associated submenu on hover or click.
- * Must be used within a DropdownMenuSub component.
+ * Displays an arrow indicator and opens the associated submenu on hover or keyboard
+ * navigation. Must be used within a DropdownMenuSub component. Automatically
+ * includes a chevron icon to indicate submenu availability and handles focus states.
  *
- * @component
+ * @param asChild - Merge props onto the immediate child instead of rendering a wrapper element
+ * @param disabled - Whether the trigger is disabled and cannot open the submenu
+ * @param textValue - Optional text value used for typeahead search functionality
  * @param inset - Whether to add left padding to align with items that have icons
  *
  * @example
  * ```tsx
+ * // Basic submenu trigger with icon
  * <DropdownMenuSub>
  *   <DropdownMenuSubTrigger>
  *     <Share className="mr-2 h-4 w-4" />
  *     Share Options
  *   </DropdownMenuSubTrigger>
  *   <DropdownMenuSubContent>
- *     <DropdownMenuItem>Email</DropdownMenuItem>
- *     <DropdownMenuItem>Copy Link</DropdownMenuItem>
+ *     <DropdownMenuItem>Email Link</DropdownMenuItem>
+ *     <DropdownMenuItem>Copy to Clipboard</DropdownMenuItem>
  *   </DropdownMenuSubContent>
  * </DropdownMenuSub>
  * ```
+ *
+ * @example
+ * ```tsx
+ * // Submenu trigger with inset alignment
+ * <DropdownMenuContent>
+ *   <DropdownMenuItem>
+ *     <FileText className="mr-2 h-4 w-4" />
+ *     Open File
+ *   </DropdownMenuItem>
+ *   <DropdownMenuSub>
+ *     <DropdownMenuSubTrigger inset>
+ *       Recent Files
+ *     </DropdownMenuSubTrigger>
+ *     <DropdownMenuSubContent>
+ *       <DropdownMenuItem>Document.pdf</DropdownMenuItem>
+ *       <DropdownMenuItem>Presentation.pptx</DropdownMenuItem>
+ *     </DropdownMenuSubContent>
+ *   </DropdownMenuSub>
+ * </DropdownMenuContent>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Disabled submenu trigger
+ * <DropdownMenuSubTrigger disabled>
+ *   Advanced Options (Pro Only)
+ * </DropdownMenuSubTrigger>
+ * ```
  * @since 1.0.0
  */
 declare function DropdownMenuSubTrigger({ className, inset, children, ...props }: React.ComponentProps<typeof DropdownMenuPrimitive.SubTrigger> & {
     inset?: boolean;
+    className?: string;
 }): import("react/jsx-runtime").JSX.Element;
 /**
  * Content container for submenu items
  *
  * Contains the items displayed when a submenu is opened. Positioned relative
- * to the trigger and supports the same item types as the main menu.
+ * to the submenu trigger with intelligent collision detection. Supports all
+ * the same item types as the main menu content, enabling complex nested
+ * menu structures with consistent behavior and styling.
+ *
+ * @param asChild - Merge props onto the immediate child instead of rendering a wrapper element
+ * @param loop - When true, keyboard navigation will loop from last to first item
+ * @param side - The preferred side of the trigger to render against
+ * @param sideOffset - Distance in pixels from the trigger
+ * @param align - The preferred alignment against the trigger
+ * @param alignOffset - Distance in pixels from the align point
+ * @param avoidCollisions - Whether to avoid collisions with viewport boundaries
+ * @param sticky - Element positioning behavior relative to the viewport
+ * @param hideWhenDetached - Whether to hide content when reference element is occluded
  *
- * @component
  * @example
  * ```tsx
+ * // Basic submenu content with various item types
  * <DropdownMenuSubContent>
- *   <DropdownMenuItem>Submenu Item 1</DropdownMenuItem>
- *   <DropdownMenuItem>Submenu Item 2</DropdownMenuItem>
+ *   <DropdownMenuItem>
+ *     <Mail className="mr-2 h-4 w-4" />
+ *     Send via Email
+ *   </DropdownMenuItem>
+ *   <DropdownMenuItem>
+ *     <Link className="mr-2 h-4 w-4" />
+ *     Copy Share Link
+ *   </DropdownMenuItem>
  *   <DropdownMenuSeparator />
- *   <DropdownMenuItem>Submenu Item 3</DropdownMenuItem>
+ *   <DropdownMenuItem>
+ *     <QrCode className="mr-2 h-4 w-4" />
+ *     Generate QR Code
+ *   </DropdownMenuItem>
+ * </DropdownMenuSubContent>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Submenu with checkbox items for multi-selection
+ * <DropdownMenuSubContent>
+ *   <DropdownMenuLabel>Export Options</DropdownMenuLabel>
+ *   <DropdownMenuSeparator />
+ *   <DropdownMenuCheckboxItem checked={includeMetadata} onCheckedChange={setIncludeMetadata}>
+ *     Include Metadata
+ *   </DropdownMenuCheckboxItem>
+ *   <DropdownMenuCheckboxItem checked={compressFile} onCheckedChange={setCompressFile}>
+ *     Compress File
+ *   </DropdownMenuCheckboxItem>
+ *   <DropdownMenuSeparator />
+ *   <DropdownMenuItem>Export Now</DropdownMenuItem>
+ * </DropdownMenuSubContent>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Nested submenu structure
+ * <DropdownMenuSubContent>
+ *   <DropdownMenuItem>Basic Export</DropdownMenuItem>
+ *   <DropdownMenuSub>
+ *     <DropdownMenuSubTrigger>Advanced Settings</DropdownMenuSubTrigger>
+ *     <DropdownMenuSubContent>
+ *       <DropdownMenuItem>High Quality</DropdownMenuItem>
+ *       <DropdownMenuItem>Custom Resolution</DropdownMenuItem>
+ *     </DropdownMenuSubContent>
+ *   </DropdownMenuSub>
  * </DropdownMenuSubContent>
  * ```
  * @since 1.0.0
  */
-declare function DropdownMenuSubContent({ className, ...props }: React.ComponentProps<typeof DropdownMenuPrimitive.SubContent>): import("react/jsx-runtime").JSX.Element;
+declare function DropdownMenuSubContent({ className, ...props }: React.ComponentProps<typeof DropdownMenuPrimitive.SubContent> & {
+    className?: string;
+}): import("react/jsx-runtime").JSX.Element;
 export { DropdownMenu, DropdownMenuPortal, DropdownMenuTrigger, DropdownMenuContent, DropdownMenuGroup, DropdownMenuLabel, DropdownMenuItem, DropdownMenuCheckboxItem, DropdownMenuRadioGroup, DropdownMenuRadioItem, DropdownMenuSeparator, DropdownMenuShortcut, DropdownMenuSub, DropdownMenuSubTrigger, DropdownMenuSubContent, };
 //# sourceMappingURL=dropdown-menu.d.ts.map