@neynar/ui 0.1.1 → 0.1.2

package/src/components/ui/menubar.tsx

@@ -4,15 +4,306 @@ import { CheckIcon, ChevronRightIcon, CircleIcon } from "lucide-react";
 
 import { cn } from "@/lib/utils";
 
+// ============================================================================
+// DOCUMENTATION-ONLY PROP TYPES (Internal - not exported)
+// These types are for documentation generation and should not replace Radix inferred types
+// ============================================================================
+
+/**
+ * Props for Menubar component (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 MenubarDocsProps = {
+  /** Additional CSS classes to apply to the menubar container */
+  className?: string;
+  /** The value of the menu that should be open when initially rendered. Use when you do not need to control the state */
+  defaultValue?: string;
+  /** The controlled value of the menu to open. Should be used in conjunction with onValueChange */
+  value?: string;
+  /** Event handler called when the value changes */
+  onValueChange?: (value: string) => void;
+  /** The reading direction of the menubar. If omitted, inherits globally from DirectionProvider or assumes LTR */
+  dir?: "ltr" | "rtl";
+  /** Whether keyboard navigation should loop from last item to first, and vice versa @default false */
+  loop?: boolean;
+} & React.ComponentProps<typeof MenubarPrimitive.Root>;
+
+/**
+ * Props for MenubarMenu component (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 MenubarMenuDocsProps = {
+  /** The unique value of the menu */
+  value?: string;
+} & React.ComponentProps<typeof MenubarPrimitive.Menu>;
+
+/**
+ * Props for MenubarGroup component (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 MenubarGroupDocsProps = React.ComponentProps<
+  typeof MenubarPrimitive.Group
+>;
+
+/**
+ * Props for MenubarPortal component (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 MenubarPortalDocsProps = {
+  /** Used to force mounting when more control is needed. Useful when controlling animation with React animation libraries */
+  forceMount?: true;
+  /** Specify a container element to portal the content into @default document.body */
+  container?: HTMLElement;
+} & React.ComponentProps<typeof MenubarPrimitive.Portal>;
+
+/**
+ * Props for MenubarRadioGroup component (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 MenubarRadioGroupDocsProps = {
+  /** The controlled value of the radio item to check. Should be used in conjunction with onValueChange */
+  value?: string;
+  /** Event handler called when the value changes */
+  onValueChange?: (value: string) => void;
+} & React.ComponentProps<typeof MenubarPrimitive.RadioGroup>;
+
+/**
+ * Props for MenubarTrigger component (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 MenubarTriggerDocsProps = {
+  /** Additional CSS classes to apply to the trigger button */
+  className?: string;
+  /** Change the default rendered element for the one passed as a child, merging their props and behavior */
+  asChild?: boolean;
+} & React.ComponentProps<typeof MenubarPrimitive.Trigger>;
+
+/**
+ * Props for MenubarContent component (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 MenubarContentDocsProps = {
+  /** Additional CSS classes to apply to the content container */
+  className?: string;
+  /** The preferred alignment against the trigger. May change when collisions occur @default "start" */
+  align?: "start" | "center" | "end";
+  /** An offset in pixels from the "start" or "end" alignment options @default -4 */
+  alignOffset?: number;
+  /** The distance in pixels from the trigger @default 8 */
+  sideOffset?: number;
+  /** The preferred side of the trigger to render against when open. Will be reversed when collisions occur and avoidCollisions is enabled @default "bottom" */
+  side?: "top" | "right" | "bottom" | "left";
+  /** When true, overrides the side and align preferences to prevent collisions with viewport edges @default true */
+  avoidCollisions?: boolean;
+  /** The element used as the collision boundary. By default this is the viewport, though you can provide additional element(s) to be included in this check */
+  collisionBoundary?: Element | null | Array<Element | null>;
+  /** The padding between the arrow and the edges of the content. If your content has border-radius, this will prevent it from overflowing the corners @default 5 */
+  arrowPadding?: number;
+  /** The sticky behavior on the align axis. "partial" will keep the content in bounds as long as the trigger is at least partially in bounds whilst "always" will keep the content in bounds regardless @default "partial" */
+  sticky?: "partial" | "always";
+  /** Whether to hide the content when the trigger becomes fully occluded @default false */
+  hideWhenDetached?: boolean;
+  /** When true, keyboard navigation will loop from last item to first, and vice versa @default false */
+  loop?: boolean;
+  /** Event handler called when the escape key is down. Can be prevented by calling event.preventDefault */
+  onEscapeKeyDown?: (event: KeyboardEvent) => void;
+  /** Event handler called when the a pointerdown event happens outside of the component. Can be prevented by calling event.preventDefault */
+  onPointerDownOutside?: (
+    event: CustomEvent<{ originalEvent: PointerEvent }>,
+  ) => void;
+  /** Event handler called when focus moves outside of the component. Can be prevented by calling event.preventDefault */
+  onFocusOutside?: (event: CustomEvent<{ originalEvent: FocusEvent }>) => void;
+  /** Event handler called when an interaction happens outside the component. Specifically, when a pointerdown event happens outside or focus moves outside of it. Can be prevented by calling event.preventDefault */
+  onInteractOutside?: (
+    event: CustomEvent<{ originalEvent: PointerEvent | FocusEvent }>,
+  ) => void;
+  /** Used to force mounting when more control is needed. Useful when controlling animation with React animation libraries */
+  forceMount?: true;
+} & React.ComponentProps<typeof MenubarPrimitive.Content>;
+
+/**
+ * Props for MenubarItem component (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 MenubarItemDocsProps = {
+  /** Additional CSS classes to apply to the menu item */
+  className?: string;
+  /** Whether to add left padding for alignment with items that have icons */
+  inset?: boolean;
+  /** Visual variant of the menu item */
+  variant?: "default" | "destructive";
+  /** When true, prevents the user from interacting with the item */
+  disabled?: boolean;
+  /** Event handler called when the user selects an item (via mouse or keyboard). Calling event.preventDefault in this handler will prevent the menu from closing when selecting that item */
+  onSelect?: (event: Event) => void;
+  /** Optional text used for typeahead purposes. By default the typeahead behavior will use the .textContent of the item. Use this when the content is complex, or you have non-textual content inside */
+  textValue?: string;
+} & React.ComponentProps<typeof MenubarPrimitive.Item>;
+
+/**
+ * Props for MenubarCheckboxItem component (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 MenubarCheckboxItemDocsProps = {
+  /** Additional CSS classes to apply to the checkbox item */
+  className?: string;
+  /** The controlled checked state of the item. Must be used in conjunction with onCheckedChange */
+  checked?: boolean | "indeterminate";
+  /** Event handler called when the checked state changes */
+  onCheckedChange?: (checked: boolean) => void;
+  /** When true, prevents the user from interacting with the item */
+  disabled?: boolean;
+  /** Event handler called when the user selects an item (via mouse or keyboard). Calling event.preventDefault in this handler will prevent the menu from closing when selecting that item */
+  onSelect?: (event: Event) => void;
+  /** Optional text used for typeahead purposes. By default the typeahead behavior will use the .textContent of the item. Use this when the content is complex, or you have non-textual content inside */
+  textValue?: string;
+} & Omit<
+  React.ComponentProps<typeof MenubarPrimitive.CheckboxItem>,
+  "checked" | "onCheckedChange"
+>;
+
+/**
+ * Props for MenubarRadioItem component (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 MenubarRadioItemDocsProps = {
+  /** Additional CSS classes to apply to the radio item */
+  className?: string;
+  /** The unique value of the item */
+  value: string;
+  /** When true, prevents the user from interacting with the item */
+  disabled?: boolean;
+  /** Event handler called when the user selects an item (via mouse or keyboard). Calling event.preventDefault in this handler will prevent the menu from closing when selecting that item */
+  onSelect?: (event: Event) => void;
+  /** Optional text used for typeahead purposes. By default the typeahead behavior will use the .textContent of the item. Use this when the content is complex, or you have non-textual content inside */
+  textValue?: string;
+} & React.ComponentProps<typeof MenubarPrimitive.RadioItem>;
+
+/**
+ * Props for MenubarLabel component (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 MenubarLabelDocsProps = {
+  /** Additional CSS classes to apply to the label */
+  className?: string;
+  /** Whether to add left padding for alignment with items that have icons */
+  inset?: boolean;
+} & React.ComponentProps<typeof MenubarPrimitive.Label>;
+
+/**
+ * Props for MenubarSeparator component (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 MenubarSeparatorDocsProps = {
+  /** Additional CSS classes to apply to the separator */
+  className?: string;
+} & React.ComponentProps<typeof MenubarPrimitive.Separator>;
+
+/**
+ * Props for MenubarShortcut component (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 MenubarShortcutDocsProps = {
+  /** Additional CSS classes to apply to the shortcut text */
+  className?: string;
+} & React.ComponentProps<"span">;
+
+/**
+ * Props for MenubarSub component (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 MenubarSubDocsProps = {
+  /** The controlled open state of the sub menu. Must be used in conjunction with onOpenChange */
+  open?: boolean;
+  /** The open state of the submenu when it is initially rendered. Use when you do not need to control its open state */
+  defaultOpen?: boolean;
+  /** Event handler called when the open state of the submenu changes */
+  onOpenChange?: (open: boolean) => void;
+} & React.ComponentProps<typeof MenubarPrimitive.Sub>;
+
+/**
+ * Props for MenubarSubTrigger component (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 MenubarSubTriggerDocsProps = {
+  /** Additional CSS classes to apply to the sub-trigger */
+  className?: string;
+  /** Whether to add left padding for alignment with items that have icons */
+  inset?: boolean;
+  /** When true, prevents the user from interacting with the item */
+  disabled?: boolean;
+  /** Optional text used for typeahead purposes. By default the typeahead behavior will use the .textContent of the item. Use this when the content is complex, or you have non-textual content inside */
+  textValue?: string;
+} & React.ComponentProps<typeof MenubarPrimitive.SubTrigger>;
+
+/**
+ * Props for MenubarSubContent component (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 MenubarSubContentDocsProps = {
+  /** Additional CSS classes to apply to the sub-content container */
+  className?: string;
+  /** The preferred alignment against the trigger. May change when collisions occur @default "start" */
+  align?: "start" | "center" | "end";
+  /** An offset in pixels from the "start" or "end" alignment options @default 0 */
+  alignOffset?: number;
+  /** The distance in pixels from the trigger @default 0 */
+  sideOffset?: number;
+  /** The preferred side of the trigger to render against when open. Will be reversed when collisions occur and avoidCollisions is enabled @default "right" */
+  side?: "top" | "right" | "bottom" | "left";
+  /** When true, overrides the side and align preferences to prevent collisions with viewport edges @default true */
+  avoidCollisions?: boolean;
+  /** The element used as the collision boundary. By default this is the viewport, though you can provide additional element(s) to be included in this check */
+  collisionBoundary?: Element | null | Array<Element | null>;
+  /** The padding between the arrow and the edges of the content. If your content has border-radius, this will prevent it from overflowing the corners @default 5 */
+  arrowPadding?: number;
+  /** The sticky behavior on the align axis. "partial" will keep the content in bounds as long as the trigger is at least partially in bounds whilst "always" will keep the content in bounds regardless @default "partial" */
+  sticky?: "partial" | "always";
+  /** Whether to hide the content when the trigger becomes fully occluded @default false */
+  hideWhenDetached?: boolean;
+  /** When true, keyboard navigation will loop from last item to first, and vice versa @default false */
+  loop?: boolean;
+  /** Event handler called when the escape key is down. Can be prevented by calling event.preventDefault */
+  onEscapeKeyDown?: (event: KeyboardEvent) => void;
+  /** Event handler called when the a pointerdown event happens outside of the component. Can be prevented by calling event.preventDefault */
+  onPointerDownOutside?: (
+    event: CustomEvent<{ originalEvent: PointerEvent }>,
+  ) => void;
+  /** Event handler called when focus moves outside of the component. Can be prevented by calling event.preventDefault */
+  onFocusOutside?: (event: CustomEvent<{ originalEvent: FocusEvent }>) => void;
+  /** Event handler called when an interaction happens outside the component. Specifically, when a pointerdown event happens outside or focus moves outside of it. Can be prevented by calling event.preventDefault */
+  onInteractOutside?: (
+    event: CustomEvent<{ originalEvent: PointerEvent | FocusEvent }>,
+  ) => void;
+  /** Used to force mounting when more control is needed. Useful when controlling animation with React animation libraries */
+  forceMount?: true;
+} & React.ComponentProps<typeof MenubarPrimitive.SubContent>;
+
 /**
  * A visually persistent menu common in desktop applications that provides access to a consistent set of commands.
- * 
+ *
  * Menubar provides a horizontal navigation structure similar to desktop application menus
  * like those found in VS Code, Figma, or native applications. Each menu contains dropdown
  * content with actions, checkboxes, radio groups, and nested submenus.
- * 
+ *
  * Built on top of Radix UI Menubar primitive with full keyboard navigation and accessibility support.
- * 
+ *
  * @example
  * ```tsx
  * // Basic application menubar
@@ -35,7 +326,7 @@ import { cn } from "@/lib/utils";
  *   </MenubarMenu>
  * </Menubar>
  * ```
- * 
+ *
  * @example
  * ```tsx
  * // With checkboxes and submenus
@@ -58,7 +349,7 @@ import { cn } from "@/lib/utils";
  *   </MenubarMenu>
  * </Menubar>
  * ```
- * 
+ *
  * @example
  * ```tsx
  * // With radio groups for exclusive selections
@@ -75,7 +366,7 @@ import { cn } from "@/lib/utils";
  *   </MenubarMenu>
  * </Menubar>
  * ```
- * 
+ *
  * @accessibility
  * - Follows WAI-ARIA menubar pattern
  * - Left/Right arrow keys navigate between menu triggers
@@ -85,16 +376,35 @@ import { cn } from "@/lib/utils";
  * - Tab moves focus to next focusable element outside menubar
  * - Full keyboard navigation with arrow keys, Enter, and Escape
  * - Screen reader support with proper ARIA labels and roles
- * 
+ *
  * @see {@link https://www.w3.org/WAI/ARIA/apg/patterns/menubar/} ARIA Menubar Pattern
  * @see {@link https://ui.shadcn.com/docs/components/menubar} shadcn/ui Menubar Documentation
  * @since 1.0.0
  */
 /**
  * Root container for the menubar component.
- * 
- * @param className - Additional CSS classes to apply
- * @param props - All props from Radix UI Menubar Root
+ *
+ * Creates a persistent horizontal menu bar that provides access to application commands.
+ * Supports keyboard navigation, controlled and uncontrolled states, and directional reading.
+ *
+ * @param className - Additional CSS classes to apply to the menubar container
+ * @param defaultValue - The value of the menu that should be open when initially rendered. Use when you do not need to control the state
+ * @param value - The controlled value of the menu to open. Should be used in conjunction with onValueChange
+ * @param onValueChange - Event handler called when the value changes
+ * @param dir - The reading direction of the menubar. If omitted, inherits globally from DirectionProvider or assumes LTR
+ * @param loop - Whether keyboard navigation should loop from last item to first, and vice versa
+ * @param props - Additional props from Radix UI Menubar Root
+ *
+ * @example
+ * ```tsx
+ * // Controlled menubar
+ * <Menubar value={activeMenu} onValueChange={setActiveMenu}>
+ *   <MenubarMenu value="file">
+ *     <MenubarTrigger>File</MenubarTrigger>
+ *     <MenubarContent>...</MenubarContent>
+ *   </MenubarMenu>
+ * </Menubar>
+ * ```
  */
 function Menubar({
   className,
@@ -116,9 +426,18 @@ function Menubar({
  * Container for a single menu within the menubar.
  *
  * Each MenubarMenu represents one dropdown menu that can be triggered
- * by its corresponding MenubarTrigger.
+ * by its corresponding MenubarTrigger. Must be used within a Menubar root.
+ *
+ * @param value - The unique value of the menu for controlled state management
+ * @param props - Additional props from Radix UI Menubar Menu
  *
- * @param props - All props from Radix UI Menubar Menu
+ * @example
+ * ```tsx
+ * <MenubarMenu value="edit">
+ *   <MenubarTrigger>Edit</MenubarTrigger>
+ *   <MenubarContent>...</MenubarContent>
+ * </MenubarMenu>
+ * ```
  */
 function MenubarMenu({
   ...props
@@ -130,9 +449,25 @@ function MenubarMenu({
  * Groups related menu items together within MenubarContent.
  *
  * Used to create logical groupings of menu items, often separated
- * by MenubarSeparator components.
+ * by MenubarSeparator components. Helps organize complex menus.
  *
  * @param props - All props from Radix UI Menubar Group
+ *
+ * @example
+ * ```tsx
+ * <MenubarContent>
+ *   <MenubarGroup>
+ *     <MenubarItem>Cut</MenubarItem>
+ *     <MenubarItem>Copy</MenubarItem>
+ *     <MenubarItem>Paste</MenubarItem>
+ *   </MenubarGroup>
+ *   <MenubarSeparator />
+ *   <MenubarGroup>
+ *     <MenubarItem>Find</MenubarItem>
+ *     <MenubarItem>Replace</MenubarItem>
+ *   </MenubarGroup>
+ * </MenubarContent>
+ * ```
  */
 function MenubarGroup({
   ...props
@@ -144,9 +479,19 @@ function MenubarGroup({
  * Portal for rendering menu content outside the DOM hierarchy.
  *
  * Automatically used by MenubarContent to ensure proper layering
- * and positioning of dropdown menus.
+ * and positioning of dropdown menus. Prevents z-index conflicts.
  *
- * @param props - All props from Radix UI Menubar Portal
+ * @param forceMount - Used to force mounting when more control is needed. Useful when controlling animation with React animation libraries
+ * @param container - Specify a container element to portal the content into
+ * @param props - Additional props from Radix UI Menubar Portal
+ *
+ * @example
+ * ```tsx
+ * // Usually used automatically by MenubarContent
+ * <MenubarPortal container={customContainer}>
+ *   <MenubarPrimitive.Content>...</MenubarPrimitive.Content>
+ * </MenubarPortal>
+ * ```
  */
 function MenubarPortal({
   ...props
@@ -159,13 +504,18 @@ function MenubarPortal({
  *
  * Use for single-selection scenarios like theme selection,
  * view modes, or other settings where only one option can be active.
+ * Only one RadioItem can be selected at a time within the group.
+ *
+ * @param value - The controlled value of the radio item to check. Should be used in conjunction with onValueChange
+ * @param onValueChange - Event handler called when the value changes
+ * @param props - Additional props from Radix UI Menubar RadioGroup
  *
- * @param props - All props from Radix UI Menubar RadioGroup
  * @example
  * ```tsx
  * <MenubarRadioGroup value={theme} onValueChange={setTheme}>
  *   <MenubarRadioItem value="light">Light</MenubarRadioItem>
  *   <MenubarRadioItem value="dark">Dark</MenubarRadioItem>
+ *   <MenubarRadioItem value="system">System</MenubarRadioItem>
  * </MenubarRadioGroup>
  * ```
  */
@@ -182,9 +532,24 @@ function MenubarRadioGroup({
  *
  * The trigger text should be concise and descriptive of the menu contents.
  * Common patterns include "File", "Edit", "View", "Tools", "Help".
+ * Automatically receives focus management and keyboard navigation.
  *
- * @param className - Additional CSS classes to apply
- * @param props - All props from Radix UI Menubar Trigger
+ * @param className - Additional CSS classes to apply to the trigger button
+ * @param asChild - Change the default rendered element for the one passed as a child, merging their props and behavior
+ * @param props - Additional props from Radix UI Menubar Trigger
+ *
+ * @accessibility
+ * - Receives focus with Tab key
+ * - Opens menu with Enter, Space, or Arrow Down
+ * - Left/Right arrows navigate between triggers
+ * - Includes proper ARIA attributes for screen readers
+ *
+ * @example
+ * ```tsx
+ * <MenubarTrigger>
+ *   File
+ * </MenubarTrigger>
+ * ```
  */
 function MenubarTrigger({
   className,
@@ -206,13 +571,37 @@ function MenubarTrigger({
  * Dropdown content container for menu items.
  *
  * Contains the actual menu items, separators, and submenus that appear
- * when a MenubarTrigger is activated.
+ * when a MenubarTrigger is activated. Automatically portaled and positioned.
  *
- * @param className - Additional CSS classes to apply
- * @param align - Alignment relative to trigger (start, center, end)
- * @param alignOffset - Offset from the aligned position
- * @param sideOffset - Distance from the trigger
- * @param props - All props from Radix UI Menubar Content
+ * @param className - Additional CSS classes to apply to the content container
+ * @param align - The preferred alignment against the trigger. May change when collisions occur
+ * @param alignOffset - An offset in pixels from the "start" or "end" alignment options
+ * @param sideOffset - The distance in pixels from the trigger
+ * @param side - The preferred side of the trigger to render against when open
+ * @param avoidCollisions - When true, overrides the side and align preferences to prevent collisions with viewport edges
+ * @param collisionBoundary - The element used as the collision boundary for positioning
+ * @param loop - Whether keyboard navigation should loop from last item to first, and vice versa
+ * @param onEscapeKeyDown - Event handler called when the escape key is down
+ * @param onPointerDownOutside - Event handler called when a pointerdown event happens outside of the component
+ * @param onFocusOutside - Event handler called when focus moves outside of the component
+ * @param onInteractOutside - Event handler called when an interaction happens outside the component
+ * @param props - Additional props from Radix UI Menubar Content
+ *
+ * @accessibility
+ * - Focus is automatically managed within the content
+ * - Arrow keys navigate between items
+ * - Escape key closes the menu
+ * - Click outside closes the menu
+ *
+ * @example
+ * ```tsx
+ * <MenubarContent align="center" sideOffset={12}>
+ *   <MenubarItem>New File</MenubarItem>
+ *   <MenubarItem>Open File</MenubarItem>
+ *   <MenubarSeparator />
+ *   <MenubarItem>Exit</MenubarItem>
+ * </MenubarContent>
+ * ```
  */
 function MenubarContent({
   className,
@@ -242,15 +631,29 @@ function MenubarContent({
  * A selectable menu item within MenubarContent.
  *
  * Can be enhanced with icons, keyboard shortcuts, and supports
- * different variants including destructive actions.
+ * different variants including destructive actions. Automatically
+ * handles selection events and keyboard navigation.
  *
- * @param className - Additional CSS classes to apply
+ * @param className - Additional CSS classes to apply to the menu item
  * @param inset - Whether to add left padding for alignment with items that have icons
- * @param variant - Visual variant ("default" | "destructive")
- * @param props - All props from Radix UI Menubar Item
+ * @param variant - Visual variant of the menu item
+ * @param disabled - When true, prevents the user from interacting with the item
+ * @param onSelect - Event handler called when the user selects an item (via mouse or keyboard)
+ * @param textValue - Optional text used for typeahead purposes when content is complex
+ * @param props - Additional props from Radix UI Menubar Item
+ *
+ * @variant default - Standard menu item appearance with neutral colors
+ * @variant destructive - Red-tinted appearance for dangerous actions like delete or remove
+ *
+ * @accessibility
+ * - Focusable with keyboard navigation
+ * - Activatable with Enter or Space keys
+ * - Supports typeahead search within menu
+ * - Properly labeled for screen readers
+ *
  * @example
  * ```tsx
- * <MenubarItem variant="destructive">
+ * <MenubarItem onSelect={() => deleteFile()} variant="destructive">
  *   Delete File
  *   <MenubarShortcut>⌫</MenubarShortcut>
  * </MenubarItem>
@@ -283,16 +686,31 @@ function MenubarItem({
  * A menu item that can be checked/unchecked.
  *
  * Perfect for toggle options like "Show Toolbar", "Enable Feature",
- * or any binary setting that can be turned on/off.
+ * or any binary setting that can be turned on/off. Displays a
+ * checkmark icon when checked.
  *
- * @param className - Additional CSS classes to apply
+ * @param className - Additional CSS classes to apply to the checkbox item
  * @param children - The content of the checkbox item
- * @param checked - Whether the item is checked
- * @param props - All props from Radix UI Menubar CheckboxItem including onCheckedChange
+ * @param checked - The controlled checked state of the item. Must be used in conjunction with onCheckedChange
+ * @param onCheckedChange - Event handler called when the checked state changes
+ * @param disabled - When true, prevents the user from interacting with the item
+ * @param onSelect - Event handler called when the user selects an item (via mouse or keyboard)
+ * @param textValue - Optional text used for typeahead purposes when content is complex
+ * @param props - Additional props from Radix UI Menubar CheckboxItem
+ *
+ * @accessibility
+ * - Proper ARIA checkbox role and state
+ * - Keyboard activatable with Enter or Space
+ * - Visual indicator shows checked/unchecked state
+ * - Screen reader announces state changes
+ *
  * @example
  * ```tsx
- * <MenubarCheckboxItem checked={showToolbar} onCheckedChange={setShowToolbar}>
- *   Show Toolbar
+ * <MenubarCheckboxItem
+ *   checked={showLineNumbers}
+ *   onCheckedChange={setShowLineNumbers}
+ * >
+ *   Show Line Numbers
  * </MenubarCheckboxItem>
  * ```
  */
@@ -327,13 +745,29 @@ function MenubarCheckboxItem({
  *
  * Use within MenubarRadioGroup for mutually exclusive options.
  * Only one radio item can be selected at a time within the group.
+ * Displays a filled circle icon when selected.
  *
- * @param className - Additional CSS classes to apply
+ * @param className - Additional CSS classes to apply to the radio item
  * @param children - The content of the radio item
- * @param props - All props from Radix UI Menubar RadioItem including value
+ * @param value - The unique value of the item (required)
+ * @param disabled - When true, prevents the user from interacting with the item
+ * @param onSelect - Event handler called when the user selects an item (via mouse or keyboard)
+ * @param textValue - Optional text used for typeahead purposes when content is complex
+ * @param props - Additional props from Radix UI Menubar RadioItem
+ *
+ * @accessibility
+ * - Proper ARIA radio role and state
+ * - Keyboard activatable with Enter or Space
+ * - Visual indicator shows selected state
+ * - Screen reader announces selection changes
+ *
  * @example
  * ```tsx
- * <MenubarRadioItem value="dark">Dark Theme</MenubarRadioItem>
+ * <MenubarRadioGroup value={theme} onValueChange={setTheme}>
+ *   <MenubarRadioItem value="light">Light Theme</MenubarRadioItem>
+ *   <MenubarRadioItem value="dark">Dark Theme</MenubarRadioItem>
+ *   <MenubarRadioItem value="system">System Theme</MenubarRadioItem>
+ * </MenubarRadioGroup>
  * ```
  */
 function MenubarRadioItem({
@@ -365,14 +799,25 @@ function MenubarRadioItem({
  *
  * Used to provide section headings within menu content,
  * helping users understand the organization of menu items.
+ * Cannot be focused or selected.
  *
- * @param className - Additional CSS classes to apply
+ * @param className - Additional CSS classes to apply to the label
  * @param inset - Whether to add left padding for alignment with items that have icons
- * @param props - All props from Radix UI Menubar Label
+ * @param props - Additional props from Radix UI Menubar Label
+ *
+ * @accessibility
+ * - Not focusable via keyboard navigation
+ * - Provides semantic grouping information
+ * - Screen readers announce as a label
+ *
  * @example
  * ```tsx
- * <MenubarLabel>Recent Files</MenubarLabel>
- * <MenubarSeparator />
+ * <MenubarContent>
+ *   <MenubarLabel>Recent Files</MenubarLabel>
+ *   <MenubarSeparator />
+ *   <MenubarItem>document.txt</MenubarItem>
+ *   <MenubarItem>photo.jpg</MenubarItem>
+ * </MenubarContent>
  * ```
  */
 function MenubarLabel({
@@ -399,10 +844,26 @@ function MenubarLabel({
  * A visual divider between menu items.
  *
  * Use to create logical groupings and improve visual hierarchy
- * within menu content.
+ * within menu content. Creates clear sections for related items.
+ *
+ * @param className - Additional CSS classes to apply to the separator
+ * @param props - Additional props from Radix UI Menubar Separator
  *
- * @param className - Additional CSS classes to apply
- * @param props - All props from Radix UI Menubar Separator
+ * @accessibility
+ * - Not focusable via keyboard navigation
+ * - Provides visual separation for screen reader users
+ * - Helps organize menu content logically
+ *
+ * @example
+ * ```tsx
+ * <MenubarContent>
+ *   <MenubarItem>New</MenubarItem>
+ *   <MenubarItem>Open</MenubarItem>
+ *   <MenubarSeparator />
+ *   <MenubarItem>Save</MenubarItem>
+ *   <MenubarItem>Save As</MenubarItem>
+ * </MenubarContent>
+ * ```
  */
 function MenubarSeparator({
   className,
@@ -422,15 +883,28 @@ function MenubarSeparator({
  *
  * Shows keyboard shortcuts aligned to the right of menu items.
  * Use standard platform conventions (⌘ for Mac, Ctrl+ for Windows/Linux).
+ * Purely visual - does not implement the actual keyboard functionality.
+ *
+ * @param className - Additional CSS classes to apply to the shortcut text
+ * @param props - Additional props from HTML span element
+ *
+ * @accessibility
+ * - Provides keyboard shortcut information to all users
+ * - Screen readers announce shortcut along with menu item
+ * - Does not interfere with keyboard navigation
  *
- * @param className - Additional CSS classes to apply
- * @param props - All props from HTML span element
  * @example
  * ```tsx
- * <MenubarItem>
+ * <MenubarItem onSelect={() => save()}>
  *   Save File
  *   <MenubarShortcut>⌘S</MenubarShortcut>
  * </MenubarItem>
+ *
+ * // Platform-specific shortcuts
+ * <MenubarItem>
+ *   Copy
+ *   <MenubarShortcut>{isMac ? '⌘C' : 'Ctrl+C'}</MenubarShortcut>
+ * </MenubarItem>
  * ```
  */
 function MenubarShortcut({
@@ -453,9 +927,18 @@ function MenubarShortcut({
  * Container for a submenu.
  *
  * Wraps MenubarSubTrigger and MenubarSubContent to create
- * nested menu structures.
+ * nested menu structures. Supports controlled and uncontrolled states.
+ *
+ * @param open - The controlled open state of the sub menu. Must be used in conjunction with onOpenChange
+ * @param defaultOpen - The open state of the submenu when it is initially rendered. Use when you do not need to control its open state
+ * @param onOpenChange - Event handler called when the open state of the submenu changes
+ * @param props - Additional props from Radix UI Menubar Sub
+ *
+ * @accessibility
+ * - Right arrow key opens submenu from trigger
+ * - Left arrow key closes submenu and returns focus to trigger
+ * - Focus is managed automatically between parent and child menus
  *
- * @param props - All props from Radix UI Menubar Sub
  * @example
  * ```tsx
  * <MenubarSub>
@@ -463,8 +946,15 @@ function MenubarShortcut({
  *   <MenubarSubContent>
  *     <MenubarItem>Export as PDF</MenubarItem>
  *     <MenubarItem>Export as CSV</MenubarItem>
+ *     <MenubarItem>Export as JSON</MenubarItem>
  *   </MenubarSubContent>
  * </MenubarSub>
+ *
+ * // Controlled submenu
+ * <MenubarSub open={exportOpen} onOpenChange={setExportOpen}>
+ *   <MenubarSubTrigger>Export</MenubarSubTrigger>
+ *   <MenubarSubContent>...</MenubarSubContent>
+ * </MenubarSub>
  * ```
  */
 function MenubarSub({
@@ -478,11 +968,27 @@ function MenubarSub({
  *
  * Automatically includes a right arrow indicator to show
  * that it opens a submenu when hovered or focused.
+ * Opens submenu on hover or right arrow key press.
  *
- * @param className - Additional CSS classes to apply
+ * @param className - Additional CSS classes to apply to the sub-trigger
  * @param inset - Whether to add left padding for alignment with items that have icons
  * @param children - The content of the sub-trigger
- * @param props - All props from Radix UI Menubar SubTrigger
+ * @param disabled - When true, prevents the user from interacting with the item
+ * @param textValue - Optional text used for typeahead purposes when content is complex
+ * @param props - Additional props from Radix UI Menubar SubTrigger
+ *
+ * @accessibility
+ * - Right arrow key opens the submenu
+ * - Enter or Space also opens the submenu
+ * - Focus moves to first item in submenu when opened
+ * - Visual arrow indicator shows submenu availability
+ *
+ * @example
+ * ```tsx
+ * <MenubarSubTrigger>
+ *   Recent Files
+ * </MenubarSubTrigger>
+ * ```
  */
 function MenubarSubTrigger({
   className,
@@ -513,9 +1019,36 @@ function MenubarSubTrigger({
  *
  * Contains the menu items that appear when a MenubarSubTrigger
  * is hovered or focused. Supports all the same content as MenubarContent.
+ * Automatically positioned to avoid viewport collisions.
+ *
+ * @param className - Additional CSS classes to apply to the sub-content container
+ * @param align - The preferred alignment against the trigger. May change when collisions occur
+ * @param alignOffset - An offset in pixels from the "start" or "end" alignment options
+ * @param sideOffset - The distance in pixels from the trigger
+ * @param side - The preferred side of the trigger to render against when open
+ * @param avoidCollisions - When true, overrides the side and align preferences to prevent collisions with viewport edges
+ * @param collisionBoundary - The element used as the collision boundary for positioning
+ * @param loop - Whether keyboard navigation should loop from last item to first, and vice versa
+ * @param onEscapeKeyDown - Event handler called when the escape key is down
+ * @param onPointerDownOutside - Event handler called when a pointerdown event happens outside of the component
+ * @param onFocusOutside - Event handler called when focus moves outside of the component
+ * @param onInteractOutside - Event handler called when an interaction happens outside the component
+ * @param props - Additional props from Radix UI Menubar SubContent
+ *
+ * @accessibility
+ * - Left arrow key closes submenu and returns focus to trigger
+ * - Arrow keys navigate within submenu items
+ * - Escape key closes entire menu hierarchy
+ * - Focus is trapped within submenu when open
  *
- * @param className - Additional CSS classes to apply
- * @param props - All props from Radix UI Menubar SubContent
+ * @example
+ * ```tsx
+ * <MenubarSubContent>
+ *   <MenubarItem>document1.txt</MenubarItem>
+ *   <MenubarItem>document2.txt</MenubarItem>
+ *   <MenubarItem>document3.txt</MenubarItem>
+ * </MenubarSubContent>
+ * ```
  */
 function MenubarSubContent({
   className,