@neynar/ui 0.1.1 → 0.1.2

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

@@ -4,6 +4,386 @@ import { CheckIcon, ChevronRightIcon, CircleIcon } from "lucide-react";
 
 import { cn } from "@/lib/utils";
 
+// ============================================================================
+// INTERNAL DOCUMENTATION TYPES (NOT EXPORTED)
+// These are for TSDoc generation only - components use Radix inferred types
+// ============================================================================
+
+/**
+ * Props for ContextMenu (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 ContextMenuDocsProps = {
+  /**
+   * The reading direction of the context menu when applicable.
+   * If omitted, assumes LTR (left-to-right) reading mode.
+   * @default "ltr"
+   */
+  dir?: "ltr" | "rtl";
+  /**
+   * Event handler called when the open state of the context menu changes.
+   * Receives the new open state as a boolean parameter.
+   */
+  onOpenChange?: (open: boolean) => void;
+  /**
+   * The modality of the context menu. When set to `true`, interaction with
+   * outside elements will be disabled and only menu content will be visible
+   * to screen readers.
+   * @default true
+   */
+  modal?: boolean;
+  /** The content to render inside the context menu root */
+  children?: React.ReactNode;
+} & React.ComponentProps<typeof ContextMenuPrimitive.Root>;
+
+/** Props for ContextMenuTrigger (Documentation only) */
+// eslint-disable-next-line unused-imports/no-unused-vars
+type ContextMenuTriggerDocsProps = {
+  /**
+   * Change the default rendered element for the one passed as a child,
+   * merging their props and behavior. Useful for composition patterns.
+   * @default false
+   */
+  asChild?: boolean;
+  /**
+   * When `true`, prevents the user from interacting with the trigger.
+   * The context menu will not open when the trigger is right-clicked.
+   * @default false
+   */
+  disabled?: boolean;
+  /** The element that should trigger the context menu on right-click */
+  children: React.ReactNode;
+} & React.ComponentProps<typeof ContextMenuPrimitive.Trigger>;
+
+/** Props for ContextMenuContent (Documentation only) */
+// eslint-disable-next-line unused-imports/no-unused-vars
+type ContextMenuContentDocsProps = {
+  /**
+   * Change the default rendered element for the one passed as a child,
+   * merging their props and behavior.
+   * @default false
+   */
+  asChild?: boolean;
+  /**
+   * When `true`, keyboard navigation will loop from last item to first,
+   * and vice versa.
+   * @default false
+   */
+  loop?: boolean;
+  /**
+   * Event handler called when focus moves to the trigger after closing.
+   * Can be prevented by calling `event.preventDefault`.
+   */
+  onCloseAutoFocus?: (event: Event) => void;
+  /**
+   * Event handler called when the escape key is down.
+   * Can be prevented by calling `event.preventDefault`.
+   */
+  onEscapeKeyDown?: (event: KeyboardEvent) => void;
+  /**
+   * When `true`, overrides the side and align preferences to prevent
+   * collisions with boundary edges.
+   * @default true
+   */
+  avoidCollisions?: boolean;
+  /**
+   * The distance in pixels from the anchor (trigger point).
+   * @default 0
+   */
+  sideOffset?: number;
+  /** Custom CSS class name for styling */
+  className?: string;
+  /** The menu items, labels, separators, and sub-menus to display */
+  children: React.ReactNode;
+} & React.ComponentProps<typeof ContextMenuPrimitive.Content>;
+
+/** Props for ContextMenuItem (Documentation only) */
+// eslint-disable-next-line unused-imports/no-unused-vars
+type ContextMenuItemDocsProps = {
+  /**
+   * Change the default rendered element for the one passed as a child,
+   * merging their props and behavior.
+   * @default false
+   */
+  asChild?: boolean;
+  /**
+   * When `true`, prevents the user from interacting with the item.
+   * The item will appear dimmed and be skipped during keyboard navigation.
+   */
+  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.
+   */
+  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 content is complex,
+   * or you have non-textual content inside.
+   */
+  textValue?: string;
+  /**
+   * Whether to indent the item for proper alignment when mixing items with/without icons.
+   * Creates consistent visual alignment in mixed-content menus.
+   */
+  inset?: boolean;
+  /**
+   * Visual variant for the menu item appearance and behavior.
+   * - `default`: Standard menu item styling for normal actions
+   * - `destructive`: Red styling to indicate dangerous/destructive actions
+   * @default "default"
+   */
+  variant?: "default" | "destructive";
+  /** Custom CSS class name for additional styling */
+  className?: string;
+  /** The content of the menu item (text, icons, shortcuts, etc.) */
+  children: React.ReactNode;
+} & React.ComponentProps<typeof ContextMenuPrimitive.Item>;
+
+/** Props for ContextMenuCheckboxItem (Documentation only) */
+// eslint-disable-next-line unused-imports/no-unused-vars
+type ContextMenuCheckboxItemDocsProps = {
+  /**
+   * Change the default rendered element for the one passed as a child,
+   * merging their props and behavior.
+   * @default false
+   */
+  asChild?: boolean;
+  /**
+   * The controlled checked state of the item.
+   * - `true`: Item is checked
+   * - `false`: Item is unchecked
+   * - `"indeterminate"`: Item is in an indeterminate state
+   */
+  checked?: boolean | "indeterminate";
+  /**
+   * Event handler called when the checked state changes.
+   * Receives the new checked state as a boolean parameter.
+   */
+  onCheckedChange?: (checked: boolean) => void;
+  /**
+   * When `true`, prevents the user from interacting with the item.
+   */
+  disabled?: boolean;
+  /**
+   * Event handler called when the user selects the item.
+   * Called before `onCheckedChange`.
+   */
+  onSelect?: (event: Event) => void;
+  /**
+   * Optional text used for typeahead purposes. By default, the typeahead behavior
+   * will use the `.textContent` of the item.
+   */
+  textValue?: string;
+  /** Custom CSS class name for styling */
+  className?: string;
+  /** The content of the checkbox item (typically text) */
+  children: React.ReactNode;
+} & React.ComponentProps<typeof ContextMenuPrimitive.CheckboxItem>;
+
+/** Props for ContextMenuRadioGroup (Documentation only) */
+// eslint-disable-next-line unused-imports/no-unused-vars
+type ContextMenuRadioGroupDocsProps = {
+  /**
+   * The controlled value of the radio group. Should match the `value` prop
+   * of the selected ContextMenuRadioItem.
+   */
+  value?: string;
+  /**
+   * Event handler called when the value changes.
+   * Receives the new selected value as a string parameter.
+   */
+  onValueChange?: (value: string) => void;
+  /** Custom CSS class name for styling */
+  className?: string;
+  /** The radio items to group together */
+  children: React.ReactNode;
+} & React.ComponentProps<typeof ContextMenuPrimitive.RadioGroup>;
+
+/** Props for ContextMenuRadioItem (Documentation only) */
+// eslint-disable-next-line unused-imports/no-unused-vars
+type ContextMenuRadioItemDocsProps = {
+  /**
+   * The unique value of the item. This will be passed to the `onValueChange`
+   * callback of the parent RadioGroup when this item is selected.
+   */
+  value: string;
+  /**
+   * When `true`, prevents the user from interacting with the item.
+   */
+  disabled?: boolean;
+  /**
+   * Event handler called when the user selects the item.
+   * Called before the parent RadioGroup's `onValueChange`.
+   */
+  onSelect?: (event: Event) => void;
+  /**
+   * Optional text used for typeahead purposes. By default, the typeahead behavior
+   * will use the `.textContent` of the item.
+   */
+  textValue?: string;
+  /** Custom CSS class name for styling */
+  className?: string;
+  /** The content of the radio item (typically text) */
+  children: React.ReactNode;
+} & React.ComponentProps<typeof ContextMenuPrimitive.RadioItem>;
+
+/** Props for ContextMenuLabel (Documentation only) */
+// eslint-disable-next-line unused-imports/no-unused-vars
+type ContextMenuLabelDocsProps = {
+  /**
+   * Change the default rendered element for the one passed as a child,
+   * merging their props and behavior.
+   * @default false
+   */
+  asChild?: boolean;
+  /**
+   * Whether to indent the label to align with inset items.
+   * Use this when you have a mix of items with and without icons.
+   */
+  inset?: boolean;
+  /** Custom CSS class name for styling */
+  className?: string;
+  /** The text content of the label */
+  children: React.ReactNode;
+} & React.ComponentProps<typeof ContextMenuPrimitive.Label>;
+
+/** Props for ContextMenuSeparator (Documentation only) */
+// eslint-disable-next-line unused-imports/no-unused-vars
+type ContextMenuSeparatorDocsProps = {
+  /**
+   * Change the default rendered element for the one passed as a child,
+   * merging their props and behavior.
+   * @default false
+   */
+  asChild?: boolean;
+  /** Custom CSS class name for styling */
+  className?: string;
+} & React.ComponentProps<typeof ContextMenuPrimitive.Separator>;
+
+/** Props for ContextMenuGroup (Documentation only) */
+// eslint-disable-next-line unused-imports/no-unused-vars
+type ContextMenuGroupDocsProps = {
+  /**
+   * Change the default rendered element for the one passed as a child,
+   * merging their props and behavior.
+   * @default false
+   */
+  asChild?: boolean;
+  /** Custom CSS class name for styling */
+  className?: string;
+  /** The items to group together */
+  children: React.ReactNode;
+} & React.ComponentProps<typeof ContextMenuPrimitive.Group>;
+
+/** Props for ContextMenuPortal (Documentation only) */
+// eslint-disable-next-line unused-imports/no-unused-vars
+type ContextMenuPortalDocsProps = {
+  /**
+   * Specify a container element to portal the content into.
+   * If not provided, content will be portaled into the body.
+   */
+  container?: HTMLElement;
+  /** The content to render in the portal */
+  children: React.ReactNode;
+} & React.ComponentProps<typeof ContextMenuPrimitive.Portal>;
+
+/** Props for ContextMenuSub (Documentation only) */
+// eslint-disable-next-line unused-imports/no-unused-vars
+type ContextMenuSubDocsProps = {
+  /**
+   * The controlled open state of the sub menu.
+   * Must be used in conjunction with `onOpenChange`.
+   */
+  open?: boolean;
+  /**
+   * Event handler called when the open state of the sub menu changes.
+   */
+  onOpenChange?: (open: boolean) => void;
+  /** The sub-menu trigger and content components */
+  children: React.ReactNode;
+} & React.ComponentProps<typeof ContextMenuPrimitive.Sub>;
+
+/** Props for ContextMenuSubTrigger (Documentation only) */
+// eslint-disable-next-line unused-imports/no-unused-vars
+type ContextMenuSubTriggerDocsProps = {
+  /**
+   * Change the default rendered element for the one passed as a child,
+   * merging their props and behavior.
+   * @default false
+   */
+  asChild?: 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.
+   */
+  textValue?: string;
+  /**
+   * Whether to indent the trigger for proper alignment when mixing items with/without icons.
+   */
+  inset?: boolean;
+  /** Custom CSS class name for styling */
+  className?: string;
+  /** The content of the sub-trigger (text, icons, etc.) */
+  children: React.ReactNode;
+} & React.ComponentProps<typeof ContextMenuPrimitive.SubTrigger>;
+
+/** Props for ContextMenuSubContent (Documentation only) */
+// eslint-disable-next-line unused-imports/no-unused-vars
+type ContextMenuSubContentDocsProps = {
+  /**
+   * Change the default rendered element for the one passed as a child,
+   * merging their props and behavior.
+   * @default false
+   */
+  asChild?: boolean;
+  /**
+   * When `true`, keyboard navigation will loop from last item to first,
+   * and vice versa.
+   * @default false
+   */
+  loop?: boolean;
+  /**
+   * Event handler called when focus moves back to the trigger after closing.
+   * Can be prevented by calling `event.preventDefault`.
+   */
+  onCloseAutoFocus?: (event: Event) => void;
+  /**
+   * Event handler called when the escape key is down.
+   * Can be prevented by calling `event.preventDefault`.
+   */
+  onEscapeKeyDown?: (event: KeyboardEvent) => void;
+  /**
+   * When `true`, overrides the side and align preferences to prevent
+   * collisions with boundary edges.
+   * @default true
+   */
+  avoidCollisions?: boolean;
+  /**
+   * The distance in pixels from the anchor.
+   * @default 0
+   */
+  sideOffset?: number;
+  /** Custom CSS class name for styling */
+  className?: string;
+  /** The sub-menu items, separators, and labels */
+  children: React.ReactNode;
+} & React.ComponentProps<typeof ContextMenuPrimitive.SubContent>;
+
+/** Props for ContextMenuShortcut (Documentation only) */
+// eslint-disable-next-line unused-imports/no-unused-vars
+type ContextMenuShortcutDocsProps = {
+  /** Custom CSS class name for styling */
+  className?: string;
+  /** The keyboard shortcut text to display (e.g., "⌘C", "Ctrl+V") */
+  children: React.ReactNode;
+} & React.ComponentProps<"span">;
+
 /**
  * ContextMenu - A contextual menu that appears on right-click or long-press
  *
@@ -49,6 +429,30 @@ import { cn } from "@/lib/utils";
  * </ContextMenu>
  * ```
  *
+ * @example
+ * ```tsx
+ * // With checkboxes and radio groups
+ * <ContextMenu>
+ *   <ContextMenuTrigger>Settings Menu</ContextMenuTrigger>
+ *   <ContextMenuContent>
+ *     <ContextMenuLabel>Preferences</ContextMenuLabel>
+ *     <ContextMenuSeparator />
+ *     <ContextMenuCheckboxItem checked={showToolbar} onCheckedChange={setShowToolbar}>
+ *       Show Toolbar
+ *     </ContextMenuCheckboxItem>
+ *     <ContextMenuCheckboxItem checked={showSidebar} onCheckedChange={setShowSidebar}>
+ *       Show Sidebar
+ *     </ContextMenuCheckboxItem>
+ *     <ContextMenuSeparator />
+ *     <ContextMenuRadioGroup value={theme} onValueChange={setTheme}>
+ *       <ContextMenuRadioItem value="light">Light Theme</ContextMenuRadioItem>
+ *       <ContextMenuRadioItem value="dark">Dark Theme</ContextMenuRadioItem>
+ *       <ContextMenuRadioItem value="system">System Theme</ContextMenuRadioItem>
+ *     </ContextMenuRadioGroup>
+ *   </ContextMenuContent>
+ * </ContextMenu>
+ * ```
+ *
  * @accessibility
  * - Triggered by right-click, long-press, or Shift+F10
  * - Full keyboard navigation with arrow keys
@@ -57,14 +461,19 @@ import { cn } from "@/lib/utils";
  * - Tab moves focus outside the menu
  * - Proper ARIA roles and focus management
  * - Screen reader announcements for menu state changes
+ * - Supports typeahead navigation by first letter
+ * - Focus returns to trigger element when closed
  *
+ * @see {@link ContextMenuTrigger} Trigger element component
+ * @see {@link ContextMenuContent} Menu content container
+ * @see {@link ContextMenuItem} Individual menu items
  * @see {@link https://ui.shadcn.com/docs/components/context-menu} shadcn/ui docs
- * @since 1.0.0
  * @see {@link https://www.radix-ui.com/primitives/docs/components/context-menu} Radix UI docs
+ * @since 1.0.0
  */
-function ContextMenu({
-  ...props
-}: React.ComponentProps<typeof ContextMenuPrimitive.Root>) {
+function ContextMenu(
+  props: React.ComponentProps<typeof ContextMenuPrimitive.Root>,
+) {
   return <ContextMenuPrimitive.Root data-slot="context-menu" {...props} />;
 }
 
@@ -73,6 +482,7 @@ function ContextMenu({
  *
  * Wraps any element to make it respond to right-click or long-press events.
  * The trigger element should provide visual feedback about its interactive nature.
+ * Uses the `asChild` pattern to merge props with child elements for composition.
  *
  * @example
  * ```tsx
@@ -81,11 +491,23 @@ function ContextMenu({
  * </ContextMenuTrigger>
  * ```
  *
- * @param children - Any React element that should trigger the context menu
+ * @example
+ * ```tsx
+ * // With asChild for direct prop merging
+ * <ContextMenuTrigger asChild>
+ *   <div className="p-4 border rounded cursor-pointer">
+ *     Right-click target area
+ *   </div>
+ * </ContextMenuTrigger>
+ * ```
+ *
+ * @param asChild - Merges props with child element instead of rendering wrapper
+ * @param disabled - Prevents context menu from opening when trigger is activated
+ * @param children - The element that should respond to right-click events
  */
-function ContextMenuTrigger({
-  ...props
-}: React.ComponentProps<typeof ContextMenuPrimitive.Trigger>) {
+function ContextMenuTrigger(
+  props: React.ComponentProps<typeof ContextMenuPrimitive.Trigger>,
+) {
   return (
     <ContextMenuPrimitive.Trigger data-slot="context-menu-trigger" {...props} />
   );
@@ -95,7 +517,8 @@ function ContextMenuTrigger({
  * ContextMenuGroup - Logical grouping for menu items
  *
  * Groups related menu items together for better organization and accessibility.
- * Provides semantic structure without visual changes.
+ * Provides semantic structure without visual changes but improves screen reader
+ * navigation by grouping related actions.
  *
  * @example
  * ```tsx
@@ -105,10 +528,29 @@ function ContextMenuTrigger({
  *   <ContextMenuItem>Paste</ContextMenuItem>
  * </ContextMenuGroup>
  * ```
+ *
+ * @example
+ * ```tsx
+ * // Multiple groups with separators
+ * <ContextMenuContent>
+ *   <ContextMenuGroup>
+ *     <ContextMenuItem>Undo</ContextMenuItem>
+ *     <ContextMenuItem>Redo</ContextMenuItem>
+ *   </ContextMenuGroup>
+ *   <ContextMenuSeparator />
+ *   <ContextMenuGroup>
+ *     <ContextMenuItem>Copy</ContextMenuItem>
+ *     <ContextMenuItem>Paste</ContextMenuItem>
+ *   </ContextMenuGroup>
+ * </ContextMenuContent>
+ * ```
+ *
+ * @param asChild - Merges props with child element instead of rendering wrapper
+ * @param children - The menu items to group together logically
  */
-function ContextMenuGroup({
-  ...props
-}: React.ComponentProps<typeof ContextMenuPrimitive.Group>) {
+function ContextMenuGroup(
+  props: React.ComponentProps<typeof ContextMenuPrimitive.Group>,
+) {
   return (
     <ContextMenuPrimitive.Group data-slot="context-menu-group" {...props} />
   );
@@ -118,7 +560,8 @@ function ContextMenuGroup({
  * ContextMenuPortal - Portal container for menu content
  *
  * Renders menu content in a portal to ensure proper layering and positioning.
- * Typically used with sub-menus to control rendering context.
+ * Useful for controlling where menu content is rendered in the DOM tree,
+ * especially important for sub-menus and complex layouts.
  *
  * @example
  * ```tsx
@@ -129,11 +572,22 @@ function ContextMenuGroup({
  * </ContextMenuPortal>
  * ```
  *
- * @param container - Custom container element for the portal
+ * @example
+ * ```tsx
+ * // Portal into specific container
+ * <ContextMenuPortal container={document.getElementById('menu-container')}>
+ *   <ContextMenuContent>
+ *     <ContextMenuItem>Custom Portal Item</ContextMenuItem>
+ *   </ContextMenuContent>
+ * </ContextMenuPortal>
+ * ```
+ *
+ * @param container - Custom container element to portal content into
+ * @param children - The menu content to render in the portal
  */
-function ContextMenuPortal({
-  ...props
-}: React.ComponentProps<typeof ContextMenuPrimitive.Portal>) {
+function ContextMenuPortal(
+  props: React.ComponentProps<typeof ContextMenuPrimitive.Portal>,
+) {
   return (
     <ContextMenuPrimitive.Portal data-slot="context-menu-portal" {...props} />
   );
@@ -143,7 +597,8 @@ function ContextMenuPortal({
  * ContextMenuSub - Container for sub-menu functionality
  *
  * Wraps a sub-menu trigger and its content to create nested menu structures.
- * Enables hierarchical organization of menu items.
+ * Enables hierarchical organization of menu items with proper state management
+ * for opening and closing sub-menus.
  *
  * @example
  * ```tsx
@@ -155,10 +610,29 @@ function ContextMenuPortal({
  *   </ContextMenuSubContent>
  * </ContextMenuSub>
  * ```
+ *
+ * @example
+ * ```tsx
+ * // Controlled sub-menu
+ * const [subOpen, setSubOpen] = useState(false)
+ *
+ * <ContextMenuSub open={subOpen} onOpenChange={setSubOpen}>
+ *   <ContextMenuSubTrigger>More Actions</ContextMenuSubTrigger>
+ *   <ContextMenuSubContent>
+ *     <ContextMenuItem onClick={() => setSubOpen(false)}>
+ *       Archive
+ *     </ContextMenuItem>
+ *   </ContextMenuSubContent>
+ * </ContextMenuSub>
+ * ```
+ *
+ * @param open - Controlled open state of the sub-menu
+ * @param onOpenChange - Callback fired when sub-menu open state changes
+ * @param children - Sub-menu trigger and content components
  */
-function ContextMenuSub({
-  ...props
-}: React.ComponentProps<typeof ContextMenuPrimitive.Sub>) {
+function ContextMenuSub(
+  props: React.ComponentProps<typeof ContextMenuPrimitive.Sub>,
+) {
   return <ContextMenuPrimitive.Sub data-slot="context-menu-sub" {...props} />;
 }
 
@@ -166,10 +640,13 @@ function ContextMenuSub({
  * ContextMenuRadioGroup - Container for radio button items
  *
  * Groups radio items together to allow single selection from multiple options.
- * Manages the selected state and ensures only one item can be selected.
+ * Manages the selected state and ensures only one item can be selected at a time.
+ * Provides controlled state management for radio selections within menus.
  *
  * @example
  * ```tsx
+ * const [theme, setTheme] = useState("light")
+ *
  * <ContextMenuRadioGroup value={theme} onValueChange={setTheme}>
  *   <ContextMenuRadioItem value="light">Light</ContextMenuRadioItem>
  *   <ContextMenuRadioItem value="dark">Dark</ContextMenuRadioItem>
@@ -177,12 +654,27 @@ function ContextMenuSub({
  * </ContextMenuRadioGroup>
  * ```
  *
- * @param value - The currently selected value
- * @param onValueChange - Callback fired when selection changes
+ * @example
+ * ```tsx
+ * // With label and separator
+ * <ContextMenuContent>
+ *   <ContextMenuLabel>Theme Selection</ContextMenuLabel>
+ *   <ContextMenuSeparator />
+ *   <ContextMenuRadioGroup value={currentTheme} onValueChange={handleThemeChange}>
+ *     <ContextMenuRadioItem value="light">Light Mode</ContextMenuRadioItem>
+ *     <ContextMenuRadioItem value="dark">Dark Mode</ContextMenuRadioItem>
+ *     <ContextMenuRadioItem value="auto">Auto</ContextMenuRadioItem>
+ *   </ContextMenuRadioGroup>
+ * </ContextMenuContent>
+ * ```
+ *
+ * @param value - The currently selected value that matches a RadioItem's value
+ * @param onValueChange - Callback fired when selection changes, receives new value
+ * @param children - ContextMenuRadioItem components to group together
  */
-function ContextMenuRadioGroup({
-  ...props
-}: React.ComponentProps<typeof ContextMenuPrimitive.RadioGroup>) {
+function ContextMenuRadioGroup(
+  props: React.ComponentProps<typeof ContextMenuPrimitive.RadioGroup>,
+) {
   return (
     <ContextMenuPrimitive.RadioGroup
       data-slot="context-menu-radio-group"
@@ -195,7 +687,8 @@ function ContextMenuRadioGroup({
  * ContextMenuSubTrigger - Trigger element for opening sub-menus
  *
  * Menu item that opens a sub-menu on hover or focus. Automatically includes
- * a chevron icon to indicate the presence of a sub-menu.
+ * a chevron icon to indicate the presence of a sub-menu. Supports the same
+ * interaction patterns as regular menu items with additional sub-menu behavior.
  *
  * @example
  * ```tsx
@@ -205,7 +698,21 @@ function ContextMenuRadioGroup({
  * </ContextMenuSubTrigger>
  * ```
  *
- * @param inset - Whether to indent the trigger for proper alignment
+ * @example
+ * ```tsx
+ * // With inset alignment for icon consistency
+ * <ContextMenuContent>
+ *   <ContextMenuItem inset>Regular Item</ContextMenuItem>
+ *   <ContextMenuSubTrigger inset>
+ *     More Actions
+ *   </ContextMenuSubTrigger>
+ * </ContextMenuContent>
+ * ```
+ *
+ * @param asChild - Merges props with child element instead of rendering wrapper
+ * @param disabled - Prevents interaction and sub-menu opening
+ * @param textValue - Custom text for typeahead navigation
+ * @param inset - Whether to indent the trigger for proper visual alignment
  * @param children - Content of the trigger (text, icons, etc.)
  */
 function ContextMenuSubTrigger({
@@ -214,7 +721,6 @@ function ContextMenuSubTrigger({
   children,
   ...props
 }: React.ComponentProps<typeof ContextMenuPrimitive.SubTrigger> & {
-  /** Whether to indent the trigger for proper alignment */
   inset?: boolean;
 }) {
   return (
@@ -237,7 +743,8 @@ function ContextMenuSubTrigger({
  * ContextMenuSubContent - Container for sub-menu items
  *
  * Contains the items within a sub-menu. Automatically positioned relative
- * to its trigger with collision detection and smooth animations.
+ * to its trigger with collision detection and smooth animations. Supports
+ * all the same features as main menu content including keyboard navigation.
  *
  * @example
  * ```tsx
@@ -249,6 +756,26 @@ function ContextMenuSubTrigger({
  * </ContextMenuSubContent>
  * ```
  *
+ * @example
+ * ```tsx
+ * // With portal and collision avoidance
+ * <ContextMenuSubContent
+ *   avoidCollisions={true}
+ *   sideOffset={8}
+ *   className="min-w-[200px]"
+ * >
+ *   <ContextMenuLabel>Sub Options</ContextMenuLabel>
+ *   <ContextMenuItem>Action A</ContextMenuItem>
+ *   <ContextMenuItem>Action B</ContextMenuItem>
+ * </ContextMenuSubContent>
+ * ```
+ *
+ * @param asChild - Merges props with child element instead of rendering wrapper
+ * @param loop - Enable keyboard navigation looping from last to first item
+ * @param onCloseAutoFocus - Handle focus return when sub-menu closes
+ * @param onEscapeKeyDown - Handle escape key presses
+ * @param avoidCollisions - Prevent collisions with viewport boundaries
+ * @param sideOffset - Distance in pixels from the trigger anchor
  * @param className - Additional CSS classes for styling
  * @param children - Sub-menu items, separators, and labels
  */
@@ -272,7 +799,8 @@ function ContextMenuSubContent({
  * ContextMenuContent - The container for context menu items
  *
  * Contains all menu items, separators, labels, and sub-menus. Automatically
- * positioned relative to the trigger point with collision detection.
+ * positioned relative to the trigger point with collision detection and smooth
+ * animations. Renders in a portal by default for proper layering.
  *
  * @example
  * ```tsx
@@ -284,8 +812,29 @@ function ContextMenuSubContent({
  * </ContextMenuContent>
  * ```
  *
+ * @example
+ * ```tsx
+ * // With event handlers and positioning
+ * <ContextMenuContent
+ *   onCloseAutoFocus={(e) => e.preventDefault()}
+ *   onEscapeKeyDown={(e) => console.log('Escape pressed')}
+ *   avoidCollisions={true}
+ *   sideOffset={4}
+ *   loop={true}
+ * >
+ *   <ContextMenuItem>Item 1</ContextMenuItem>
+ *   <ContextMenuItem>Item 2</ContextMenuItem>
+ * </ContextMenuContent>
+ * ```
+ *
+ * @param asChild - Merges props with child element instead of rendering wrapper
+ * @param loop - Enable keyboard navigation looping from last to first item
+ * @param onCloseAutoFocus - Handle focus return when menu closes
+ * @param onEscapeKeyDown - Handle escape key presses
+ * @param avoidCollisions - Prevent collisions with viewport boundaries
+ * @param sideOffset - Distance in pixels from the cursor/trigger point
  * @param className - Additional CSS classes for styling
- * @param children - Menu items, separators, labels, and sub-menus
+ * @param children - Menu items, labels, separators, and sub-menus to display
  */
 function ContextMenuContent({
   className,
@@ -310,10 +859,11 @@ function ContextMenuContent({
  *
  * Individual menu items that users can interact with. Supports different
  * variants for visual hierarchy and includes automatic icon styling.
+ * Items can be clicked, selected via keyboard, and support custom styling.
  *
  * @example
  * ```tsx
- * <ContextMenuItem>
+ * <ContextMenuItem onSelect={() => console.log('Edit selected')}>
  *   <Edit className="mr-2 h-4 w-4" />
  *   Edit
  *   <ContextMenuShortcut>⌘E</ContextMenuShortcut>
@@ -322,16 +872,32 @@ function ContextMenuContent({
  *
  * @example
  * ```tsx
- * <ContextMenuItem variant="destructive">
+ * <ContextMenuItem variant="destructive" onSelect={handleDelete}>
  *   <Trash2 className="mr-2 h-4 w-4" />
  *   Delete
  * </ContextMenuItem>
  * ```
  *
- * @param inset - Whether to indent the item (useful when mixing items with/without icons)
- * @param variant - Visual variant: "default" for normal actions, "destructive" for dangerous actions
- * @param disabled - Whether the item is disabled and non-interactive
- * @param onSelect - Callback fired when the item is selected
+ * @example
+ * ```tsx
+ * // With custom text value for typeahead
+ * <ContextMenuItem
+ *   textValue="Copy to clipboard"
+ *   onSelect={handleCopy}
+ * >
+ *   <Copy className="mr-2 h-4 w-4" />
+ *   Copy <span className="text-muted-foreground">to clipboard</span>
+ * </ContextMenuItem>
+ * ```
+ *
+ * @param asChild - Merges props with child element instead of rendering wrapper
+ * @param disabled - Prevents interaction and dims the item visually
+ * @param onSelect - Callback fired when item is selected (via mouse or keyboard)
+ * @param textValue - Custom text for typeahead navigation when content is complex
+ * @param inset - Whether to indent the item for alignment with icon-based items
+ * @param variant - Visual variant ("default" for normal actions, "destructive" for dangerous actions)
+ * @param className - Additional CSS classes for custom styling
+ * @param children - Content of the menu item (text, icons, shortcuts, etc.)
  */
 function ContextMenuItem({
   className,
@@ -339,9 +905,7 @@ function ContextMenuItem({
   variant = "default",
   ...props
 }: React.ComponentProps<typeof ContextMenuPrimitive.Item> & {
-  /** Whether to indent the item for proper alignment */
   inset?: boolean;
-  /** Visual variant for the menu item */
   variant?: "default" | "destructive";
 }) {
   return (
@@ -362,7 +926,8 @@ function ContextMenuItem({
  * ContextMenuCheckboxItem - A menu item with checkbox functionality
  *
  * Menu items that can be toggled on/off, useful for binary settings or options.
- * Displays a check mark when selected and supports controlled state management.
+ * Displays a check mark when selected and supports controlled state management
+ * with indeterminate state for partially selected collections.
  *
  * @example
  * ```tsx
@@ -376,9 +941,35 @@ function ContextMenuItem({
  * </ContextMenuCheckboxItem>
  * ```
  *
- * @param checked - Whether the checkbox is checked
+ * @example
+ * ```tsx
+ * // With indeterminate state
+ * const [selectedItems, setSelectedItems] = useState(['item1'])
+ * const allItems = ['item1', 'item2', 'item3']
+ * const checkedState = selectedItems.length === 0
+ *   ? false
+ *   : selectedItems.length === allItems.length
+ *     ? true
+ *     : "indeterminate"
+ *
+ * <ContextMenuCheckboxItem
+ *   checked={checkedState}
+ *   onCheckedChange={(checked) =>
+ *     setSelectedItems(checked ? allItems : [])
+ *   }
+ * >
+ *   Select All
+ * </ContextMenuCheckboxItem>
+ * ```
+ *
+ * @param asChild - Merges props with child element instead of rendering wrapper
+ * @param checked - The checked state (true, false, or "indeterminate")
  * @param onCheckedChange - Callback fired when the checked state changes
- * @param disabled - Whether the item is disabled
+ * @param disabled - Whether the item is disabled and non-interactive
+ * @param onSelect - Callback fired when the item is selected (before onCheckedChange)
+ * @param textValue - Custom text for typeahead navigation
+ * @param className - Additional CSS classes for styling
+ * @param children - Content of the checkbox item (typically text)
  */
 function ContextMenuCheckboxItem({
   className,
@@ -411,18 +1002,36 @@ function ContextMenuCheckboxItem({
  *
  * Menu items that allow single selection from a group of options.
  * Must be used within a ContextMenuRadioGroup for proper functionality.
+ * Displays a filled circle indicator when selected.
  *
  * @example
  * ```tsx
  * <ContextMenuRadioGroup value={theme} onValueChange={setTheme}>
- *   <ContextMenuRadioItem value="light">Light</ContextMenuRadioItem>
- *   <ContextMenuRadioItem value="dark">Dark</ContextMenuRadioItem>
- *   <ContextMenuRadioItem value="system">System</ContextMenuRadioItem>
+ *   <ContextMenuRadioItem value="light">Light Theme</ContextMenuRadioItem>
+ *   <ContextMenuRadioItem value="dark">Dark Theme</ContextMenuRadioItem>
+ *   <ContextMenuRadioItem value="system">System Theme</ContextMenuRadioItem>
+ * </ContextMenuRadioGroup>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // With disabled state and custom text
+ * <ContextMenuRadioGroup value={quality} onValueChange={setQuality}>
+ *   <ContextMenuRadioItem value="low">Low Quality</ContextMenuRadioItem>
+ *   <ContextMenuRadioItem value="medium">Medium Quality</ContextMenuRadioItem>
+ *   <ContextMenuRadioItem value="high">High Quality</ContextMenuRadioItem>
+ *   <ContextMenuRadioItem value="ultra" disabled>
+ *     Ultra Quality (Premium)
+ *   </ContextMenuRadioItem>
  * </ContextMenuRadioGroup>
  * ```
  *
- * @param value - The value of this radio item
- * @param disabled - Whether the item is disabled
+ * @param value - The unique value for this radio item (required)
+ * @param disabled - Whether the item is disabled and non-interactive
+ * @param onSelect - Callback fired when the item is selected (before parent's onValueChange)
+ * @param textValue - Custom text for typeahead navigation
+ * @param className - Additional CSS classes for styling
+ * @param children - Content of the radio item (typically text)
  */
 function ContextMenuRadioItem({
   className,
@@ -453,6 +1062,7 @@ function ContextMenuRadioItem({
  *
  * Used to group related menu items and provide context. Labels are not
  * focusable and serve as visual section headers within the menu.
+ * Helps organize menu content and improve accessibility.
  *
  * @example
  * ```tsx
@@ -462,14 +1072,26 @@ function ContextMenuRadioItem({
  * <ContextMenuItem>Save</ContextMenuItem>
  * ```
  *
+ * @example
+ * ```tsx
+ * // With inset alignment for consistency
+ * <ContextMenuContent>
+ *   <ContextMenuLabel inset>Edit Options</ContextMenuLabel>
+ *   <ContextMenuItem inset>Copy</ContextMenuItem>
+ *   <ContextMenuItem inset>Paste</ContextMenuItem>
+ * </ContextMenuContent>
+ * ```
+ *
+ * @param asChild - Merges props with child element instead of rendering wrapper
  * @param inset - Whether to indent the label to align with inset items
+ * @param className - Additional CSS classes for styling
+ * @param children - The text content of the label
  */
 function ContextMenuLabel({
   className,
   inset,
   ...props
 }: React.ComponentProps<typeof ContextMenuPrimitive.Label> & {
-  /** Whether to indent the label for proper alignment */
   inset?: boolean;
 }) {
   return (
@@ -490,6 +1112,7 @@ function ContextMenuLabel({
  *
  * Creates visual separation between groups of related menu items.
  * Typically used after labels or to separate different types of actions.
+ * Improves visual hierarchy and content organization in menus.
  *
  * @example
  * ```tsx
@@ -498,6 +1121,23 @@ function ContextMenuLabel({
  * <ContextMenuSeparator />
  * <ContextMenuItem variant="destructive">Delete</ContextMenuItem>
  * ```
+ *
+ * @example
+ * ```tsx
+ * // Organizing menu sections
+ * <ContextMenuContent>
+ *   <ContextMenuLabel>Edit</ContextMenuLabel>
+ *   <ContextMenuItem>Copy</ContextMenuItem>
+ *   <ContextMenuItem>Paste</ContextMenuItem>
+ *   <ContextMenuSeparator />
+ *   <ContextMenuLabel>View</ContextMenuLabel>
+ *   <ContextMenuItem>Zoom In</ContextMenuItem>
+ *   <ContextMenuItem>Zoom Out</ContextMenuItem>
+ * </ContextMenuContent>
+ * ```
+ *
+ * @param asChild - Merges props with child element instead of rendering wrapper
+ * @param className - Additional CSS classes for styling
  */
 function ContextMenuSeparator({
   className,
@@ -517,6 +1157,7 @@ function ContextMenuSeparator({
  *
  * Shows keyboard shortcuts aligned to the right side of menu items.
  * Provides visual indication of available keyboard shortcuts for actions.
+ * Improves discoverability of keyboard navigation options.
  *
  * @example
  * ```tsx
@@ -526,7 +1167,28 @@ function ContextMenuSeparator({
  * </ContextMenuItem>
  * ```
  *
- * @param children - The shortcut text (e.g., "⌘C", "Ctrl+V")
+ * @example
+ * ```tsx
+ * // Multiple shortcuts for different platforms
+ * <ContextMenuItem>
+ *   Save
+ *   <ContextMenuShortcut>
+ *     {isMac ? '⌘S' : 'Ctrl+S'}
+ *   </ContextMenuShortcut>
+ * </ContextMenuItem>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Complex shortcuts
+ * <ContextMenuItem>
+ *   Find and Replace
+ *   <ContextMenuShortcut>⌘⌥F</ContextMenuShortcut>
+ * </ContextMenuItem>
+ * ```
+ *
+ * @param className - Additional CSS classes for styling
+ * @param children - The keyboard shortcut text to display (e.g., "⌘C", "Ctrl+V")
  */
 function ContextMenuShortcut({
   className,
@@ -561,3 +1223,6 @@ export {
   ContextMenuSubTrigger,
   ContextMenuRadioGroup,
 };
+
+// NOTE: Internal documentation types are NOT exported
+// Components use Radix UI inferred types for implementation