@neynar/ui 0.1.1 → 0.1.2

package/src/components/ui/dropdown-menu.tsx

@@ -4,6 +4,142 @@ import { CheckIcon, ChevronRightIcon, CircleIcon } from "lucide-react";
 
 import { cn } from "@/lib/utils";
 
+// ============================================================================
+// Documentation Props Types (Internal - Not exported)
+// ============================================================================
+
+/**
+ * Props for DropdownMenu (Documentation only - NOT used in component implementation)
+ * These types are for documentation generation and should not replace Radix inferred types
+ */
+// eslint-disable-next-line unused-imports/no-unused-vars
+type DropdownMenuDocsProps = {
+  /** Whether the dropdown is initially open (uncontrolled mode) @default false */
+  defaultOpen?: boolean;
+  /** Whether the dropdown is open (controlled mode) */
+  open?: boolean;
+  /** Callback fired when the open state changes */
+  onOpenChange?: (open: boolean) => void;
+  /** Whether the dropdown should be modal (blocks interaction with outside elements) @default true */
+  modal?: boolean;
+  /** The reading direction of the dropdown menu @default "ltr" */
+  dir?: "ltr" | "rtl";
+  /** Child elements - typically DropdownMenuTrigger and DropdownMenuContent */
+  children?: React.ReactNode;
+} & React.ComponentProps<typeof DropdownMenuPrimitive.Root>;
+
+/** Props for DropdownMenuTrigger (Documentation only) */
+// eslint-disable-next-line unused-imports/no-unused-vars
+type DropdownMenuTriggerDocsProps = {
+  /** Merge props onto the immediate child instead of rendering a wrapper element @default false */
+  asChild?: boolean;
+  /** Child element that will trigger the dropdown menu */
+  children?: React.ReactNode;
+} & React.ComponentProps<typeof DropdownMenuPrimitive.Trigger>;
+
+/** Props for DropdownMenuContent (Documentation only) */
+// eslint-disable-next-line unused-imports/no-unused-vars
+type DropdownMenuContentDocsProps = {
+  /** Merge props onto the immediate child instead of rendering a wrapper element @default false */
+  asChild?: boolean;
+  /** When true, keyboard navigation will loop from last to first item and vice versa @default false */
+  loop?: boolean;
+  /** The preferred side of the trigger to render against @default "bottom" */
+  side?: "top" | "right" | "bottom" | "left";
+  /** Distance in pixels from the trigger @default 4 */
+  sideOffset?: number;
+  /** The preferred alignment against the trigger @default "center" */
+  align?: "start" | "center" | "end";
+  /** Distance in pixels from the align point @default 0 */
+  alignOffset?: number;
+  /** Whether to avoid collisions with viewport boundaries @default true */
+  avoidCollisions?: boolean;
+  /** Element positioning behavior relative to the viewport */
+  sticky?: "partial" | "always";
+  /** Whether to hide the content when the reference element is fully occluded @default false */
+  hideWhenDetached?: boolean;
+  /** CSS class name for custom styling */
+  className?: string;
+  /** Child menu items, labels, separators, and groups */
+  children?: React.ReactNode;
+} & React.ComponentProps<typeof DropdownMenuPrimitive.Content>;
+
+/** Props for DropdownMenuItem (Documentation only) */
+// eslint-disable-next-line unused-imports/no-unused-vars
+type DropdownMenuItemDocsProps = {
+  /** Whether the item is disabled and cannot be selected @default false */
+  disabled?: boolean;
+  /** Callback fired when the item is selected via click or keyboard */
+  onSelect?: (event: Event) => void;
+  /** Optional text value used for typeahead search functionality */
+  textValue?: string;
+  /** Whether to add extra left padding to align with items that have icons @default false */
+  inset?: boolean;
+  /** Visual variant of the menu item for semantic distinction @default "default" */
+  variant?: "default" | "destructive";
+  /** CSS class name for custom styling */
+  className?: string;
+  /** Item content - text, icons, or other React elements */
+  children?: React.ReactNode;
+} & React.ComponentProps<typeof DropdownMenuPrimitive.Item>;
+
+/** Props for DropdownMenuCheckboxItem (Documentation only) */
+// eslint-disable-next-line unused-imports/no-unused-vars
+type DropdownMenuCheckboxItemDocsProps = {
+  /** The checked state of the checkbox item */
+  checked?: boolean | "indeterminate";
+  /** Callback fired when the checked state changes */
+  onCheckedChange?: (checked: boolean) => void;
+  /** Whether the item is disabled and cannot be interacted with @default false */
+  disabled?: boolean;
+  /** Callback fired when the item is selected via click or keyboard */
+  onSelect?: (event: Event) => void;
+  /** Optional text value used for typeahead search functionality */
+  textValue?: string;
+  /** Whether to add extra left padding to align with items that have icons @default false */
+  inset?: boolean;
+  /** CSS class name for custom styling */
+  className?: string;
+  /** Item content - automatically includes checkbox indicator */
+  children?: React.ReactNode;
+} & React.ComponentProps<typeof DropdownMenuPrimitive.CheckboxItem>;
+
+/** Props for DropdownMenuRadioGroup (Documentation only) */
+// eslint-disable-next-line unused-imports/no-unused-vars
+type DropdownMenuRadioGroupDocsProps = {
+  /** The currently selected value in the radio group */
+  value?: string;
+  /** Callback fired when the selection changes to a different value */
+  onValueChange?: (value: string) => void;
+  /** Whether the entire radio group is disabled @default false */
+  disabled?: boolean;
+  /** Radio item children within the group */
+  children?: React.ReactNode;
+} & React.ComponentProps<typeof DropdownMenuPrimitive.RadioGroup>;
+
+/** Props for DropdownMenuRadioItem (Documentation only) */
+// eslint-disable-next-line unused-imports/no-unused-vars
+type DropdownMenuRadioItemDocsProps = {
+  /** The unique value this radio item represents */
+  value: string;
+  /** Whether the item is disabled and cannot be selected @default false */
+  disabled?: boolean;
+  /** Callback fired when the item is selected via click or keyboard */
+  onSelect?: (event: Event) => void;
+  /** Optional text value used for typeahead search functionality */
+  textValue?: string;
+  /** Whether to add extra left padding to align with items that have icons @default false */
+  inset?: boolean;
+  /** CSS class name for custom styling */
+  className?: string;
+  /** Item content - automatically includes radio indicator */
+  children?: React.ReactNode;
+} & React.ComponentProps<typeof DropdownMenuPrimitive.RadioItem>;
+
+// ============================================================================
+// Main Component
+// ============================================================================
+
 /**
  * A versatile dropdown menu component built on Radix UI primitives
  *
@@ -11,10 +147,15 @@ import { cn } from "@/lib/utils";
  * 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
@@ -33,8 +174,10 @@ import { cn } from "@/lib/utils";
  *
  * @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 />
@@ -52,6 +195,9 @@ import { cn } from "@/lib/utils";
  * @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>
@@ -82,17 +228,19 @@ import { cn } from "@/lib/utils";
  * @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
  */
@@ -107,10 +255,18 @@ function DropdownMenu({
  *
  * 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
  */
 function DropdownMenuPortal({
@@ -122,13 +278,29 @@ function DropdownMenuPortal({
 }
 
 /**
- * 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
+ *
+ * @example
+ * ```tsx
+ * // Basic trigger with button
+ * <DropdownMenuTrigger asChild>
+ *   <Button variant="outline">Open Menu</Button>
+ * </DropdownMenuTrigger>
+ * ```
  *
- * @component
  * @example
  * ```tsx
+ * // Icon button trigger
  * <DropdownMenuTrigger asChild>
- *   <Button>Menu</Button>
+ *   <Button variant="ghost" size="icon" aria-label="More options">
+ *     <MoreVertical className="h-4 w-4" />
+ *   </Button>
  * </DropdownMenuTrigger>
  * ```
  * @since 1.0.0
@@ -145,13 +317,44 @@ function DropdownMenuTrigger({
 }
 
 /**
- * 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
@@ -160,7 +363,9 @@ function DropdownMenuContent({
   className,
   sideOffset = 4,
   ...props
-}: React.ComponentProps<typeof DropdownMenuPrimitive.Content>) {
+}: React.ComponentProps<typeof DropdownMenuPrimitive.Content> & {
+  className?: string;
+}) {
   return (
     <DropdownMenuPrimitive.Portal>
       <DropdownMenuPrimitive.Content
@@ -181,15 +386,23 @@ function DropdownMenuContent({
  *
  * 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
  */
@@ -202,16 +415,51 @@ function DropdownMenuGroup({
 }
 
 /**
- * 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
@@ -224,6 +472,7 @@ function DropdownMenuItem({
 }: React.ComponentProps<typeof DropdownMenuPrimitive.Item> & {
   inset?: boolean;
   variant?: "default" | "destructive";
+  className?: string;
 }) {
   return (
     <DropdownMenuPrimitive.Item
@@ -243,25 +492,64 @@ function DropdownMenuItem({
  * 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
  */
 function DropdownMenuCheckboxItem({
@@ -269,7 +557,9 @@ function DropdownMenuCheckboxItem({
   children,
   checked,
   ...props
-}: React.ComponentProps<typeof DropdownMenuPrimitive.CheckboxItem>) {
+}: React.ComponentProps<typeof DropdownMenuPrimitive.CheckboxItem> & {
+  className?: string;
+}) {
   return (
     <DropdownMenuPrimitive.CheckboxItem
       data-slot="dropdown-menu-checkbox-item"
@@ -294,20 +584,44 @@ function DropdownMenuCheckboxItem({
  * 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
@@ -327,21 +641,44 @@ function DropdownMenuRadioGroup({
  * 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
@@ -350,7 +687,9 @@ function DropdownMenuRadioItem({
   className,
   children,
   ...props
-}: React.ComponentProps<typeof DropdownMenuPrimitive.RadioItem>) {
+}: React.ComponentProps<typeof DropdownMenuPrimitive.RadioItem> & {
+  className?: string;
+}) {
   return (
     <DropdownMenuPrimitive.RadioItem
       data-slot="dropdown-menu-radio-item"
@@ -371,12 +710,45 @@ function DropdownMenuRadioItem({
 }
 
 /**
- * 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
  */
@@ -386,6 +758,7 @@ function DropdownMenuLabel({
   ...props
 }: React.ComponentProps<typeof DropdownMenuPrimitive.Label> & {
   inset?: boolean;
+  className?: string;
 }) {
   return (
     <DropdownMenuPrimitive.Label
@@ -401,15 +774,49 @@ function DropdownMenuLabel({
 }
 
 /**
- * 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
  *
- * @component
+ * @example
+ * ```tsx
+ * // Separating different action groups
+ * <DropdownMenuContent>
+ *   <DropdownMenuItem>View</DropdownMenuItem>
+ *   <DropdownMenuItem>Edit</DropdownMenuItem>
+ *   <DropdownMenuSeparator />
+ *   <DropdownMenuItem variant="destructive">Delete</DropdownMenuItem>
+ * </DropdownMenuContent>
+ * ```
+ *
+ * @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
  */
 function DropdownMenuSeparator({
   className,
   ...props
-}: React.ComponentProps<typeof DropdownMenuPrimitive.Separator>) {
+}: React.ComponentProps<typeof DropdownMenuPrimitive.Separator> & {
+  className?: string;
+}) {
   return (
     <DropdownMenuPrimitive.Separator
       data-slot="dropdown-menu-separator"
@@ -423,23 +830,64 @@ function DropdownMenuSeparator({
  * 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
  */
 function DropdownMenuShortcut({
   className,
   ...props
-}: React.ComponentProps<"span">) {
+}: React.ComponentProps<"span"> & {
+  className?: string;
+}) {
   return (
     <span
       data-slot="dropdown-menu-shortcut"
@@ -456,19 +904,66 @@ function DropdownMenuShortcut({
  * 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
  */
 function DropdownMenuSub({
@@ -480,25 +975,57 @@ function DropdownMenuSub({
 /**
  * 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
  */
 function DropdownMenuSubTrigger({
@@ -508,6 +1035,7 @@ function DropdownMenuSubTrigger({
   ...props
 }: React.ComponentProps<typeof DropdownMenuPrimitive.SubTrigger> & {
   inset?: boolean;
+  className?: string;
 }) {
   return (
     <DropdownMenuPrimitive.SubTrigger
@@ -529,16 +1057,69 @@ function DropdownMenuSubTrigger({
  * 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
@@ -546,7 +1127,9 @@ function DropdownMenuSubTrigger({
 function DropdownMenuSubContent({
   className,
   ...props
-}: React.ComponentProps<typeof DropdownMenuPrimitive.SubContent>) {
+}: React.ComponentProps<typeof DropdownMenuPrimitive.SubContent> & {
+  className?: string;
+}) {
   return (
     <DropdownMenuPrimitive.SubContent
       data-slot="dropdown-menu-sub-content"