@neynar/ui 0.4.0 → 0.5.0

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

@@ -1,793 +1,132 @@
 import * as React from "react";
-import * as ContextMenuPrimitive from "@radix-ui/react-context-menu";
-import { CheckIcon, ChevronRightIcon, CircleIcon } from "lucide-react";
+import { ContextMenu as ContextMenuPrimitive } from "@base-ui/react/context-menu";
 
 import { cn } from "@/lib/utils";
+import { menuItemVariants, type MenuItemVariant } from "@/lib/variants";
+import { ChevronRightIcon, CheckIcon } from "lucide-react";
 
-// ============================================================================
-// INTERNAL DOCUMENTATION TYPES (NOT EXPORTED)
-// These are for TSDoc generation only - components use Radix inferred types
-// ============================================================================
+type ContextMenuProps = ContextMenuPrimitive.Root.Props;
 
-/**
- * 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
- *
- * Context menus provide contextual actions for specific elements or areas.
- * Built on Radix UI primitives, they appear when users right-click (or long-press
- * on touch devices) and offer actions relevant to the clicked item or region.
- *
- * @example
- * ```tsx
- * // Basic context menu with items
- * <ContextMenu>
- *   <ContextMenuTrigger>
- *     <div className="border rounded p-4">
- *       Right-click here
- *     </div>
- *   </ContextMenuTrigger>
- *   <ContextMenuContent>
- *     <ContextMenuItem>Copy</ContextMenuItem>
- *     <ContextMenuItem>Paste</ContextMenuItem>
- *     <ContextMenuSeparator />
- *     <ContextMenuItem variant="destructive">Delete</ContextMenuItem>
- *   </ContextMenuContent>
- * </ContextMenu>
- * ```
- *
- * @example
- * ```tsx
- * // With sub-menus and shortcuts
- * <ContextMenu>
- *   <ContextMenuTrigger>Right-click me</ContextMenuTrigger>
- *   <ContextMenuContent>
- *     <ContextMenuItem>
- *       Edit <ContextMenuShortcut>⌘E</ContextMenuShortcut>
- *     </ContextMenuItem>
- *     <ContextMenuSub>
- *       <ContextMenuSubTrigger>Share</ContextMenuSubTrigger>
- *       <ContextMenuSubContent>
- *         <ContextMenuItem>Email</ContextMenuItem>
- *         <ContextMenuItem>Copy Link</ContextMenuItem>
- *       </ContextMenuSubContent>
- *     </ContextMenuSub>
- *   </ContextMenuContent>
- * </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
- * - Escape key closes the menu and sub-menus
- * - Enter/Space activates menu items
- * - 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
- * @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>,
-) {
+/** Root context menu component. Manages state and handles right-click trigger. */
+function ContextMenu({ ...props }: ContextMenuProps) {
   return <ContextMenuPrimitive.Root data-slot="context-menu" {...props} />;
 }
 
-/**
- * ContextMenuTrigger - The element that triggers the context menu
- *
- * 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
- * <ContextMenuTrigger>
- *   <Button variant="outline">Right-click me</Button>
- * </ContextMenuTrigger>
- * ```
- *
- * @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>,
-) {
+type ContextMenuPortalProps = ContextMenuPrimitive.Portal.Props;
+
+/** Portal container for context menu content. Renders content in document body. */
+function ContextMenuPortal({ ...props }: ContextMenuPortalProps) {
   return (
-    <ContextMenuPrimitive.Trigger data-slot="context-menu-trigger" {...props} />
+    <ContextMenuPrimitive.Portal data-slot="context-menu-portal" {...props} />
   );
 }
 
-/**
- * ContextMenuGroup - Logical grouping for menu items
- *
- * Groups related menu items together for better organization and accessibility.
- * Provides semantic structure without visual changes but improves screen reader
- * navigation by grouping related actions.
- *
- * @example
- * ```tsx
- * <ContextMenuGroup>
- *   <ContextMenuItem>Copy</ContextMenuItem>
- *   <ContextMenuItem>Cut</ContextMenuItem>
- *   <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>,
-) {
+type ContextMenuTriggerProps = ContextMenuPrimitive.Trigger.Props;
+
+/** Element that triggers the context menu on right-click. */
+function ContextMenuTrigger({ className, ...props }: ContextMenuTriggerProps) {
   return (
-    <ContextMenuPrimitive.Group data-slot="context-menu-group" {...props} />
+    <ContextMenuPrimitive.Trigger
+      data-slot="context-menu-trigger"
+      className={cn("select-none", className)}
+      {...props}
+    />
   );
 }
 
+type ContextMenuContentProps = ContextMenuPrimitive.Popup.Props &
+  Pick<
+    ContextMenuPrimitive.Positioner.Props,
+    "align" | "alignOffset" | "side" | "sideOffset"
+  >;
+
 /**
- * ContextMenuPortal - Portal container for menu content
- *
- * Renders menu content in a portal to ensure proper layering and positioning.
- * Useful for controlling where menu content is rendered in the DOM tree,
- * especially important for sub-menus and complex layouts.
- *
- * @example
- * ```tsx
- * <ContextMenuPortal>
- *   <ContextMenuSubContent>
- *     <ContextMenuItem>Portal Item</ContextMenuItem>
- *   </ContextMenuSubContent>
- * </ContextMenuPortal>
- * ```
- *
- * @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
+ * Context menu content with automatic portal and positioning.
+ * Includes animations, shadows, and overflow handling.
  */
-function ContextMenuPortal(
-  props: React.ComponentProps<typeof ContextMenuPrimitive.Portal>,
-) {
+function ContextMenuContent({
+  className,
+  align = "start",
+  alignOffset = 4,
+  side = "right",
+  sideOffset = 0,
+  ...props
+}: ContextMenuContentProps) {
   return (
-    <ContextMenuPrimitive.Portal data-slot="context-menu-portal" {...props} />
+    <ContextMenuPrimitive.Portal>
+      <ContextMenuPrimitive.Positioner
+        className="isolate z-50 outline-none"
+        align={align}
+        alignOffset={alignOffset}
+        side={side}
+        sideOffset={sideOffset}
+      >
+        <ContextMenuPrimitive.Popup
+          data-slot="context-menu-content"
+          className={cn(
+            "data-open:animate-in data-closed:animate-out data-closed:fade-out-0 data-open:fade-in-0 data-closed:zoom-out-95 data-open:zoom-in-95 data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2 ring-foreground/10 bg-popover text-popover-foreground min-w-36 rounded-md p-1 shadow-md ring-1 duration-100 z-50 max-h-(--available-height) origin-(--transform-origin) overflow-x-hidden overflow-y-auto outline-none",
+            className,
+          )}
+          {...props}
+        />
+      </ContextMenuPrimitive.Positioner>
+    </ContextMenuPrimitive.Portal>
   );
 }
 
-/**
- * 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 with proper state management
- * for opening and closing sub-menus.
- *
- * @example
- * ```tsx
- * <ContextMenuSub>
- *   <ContextMenuSubTrigger>Share</ContextMenuSubTrigger>
- *   <ContextMenuSubContent>
- *     <ContextMenuItem>Email</ContextMenuItem>
- *     <ContextMenuItem>Copy Link</ContextMenuItem>
- *   </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>,
-) {
-  return <ContextMenuPrimitive.Sub data-slot="context-menu-sub" {...props} />;
-}
+type ContextMenuGroupProps = ContextMenuPrimitive.Group.Props;
 
-/**
- * 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 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>
- *   <ContextMenuRadioItem value="system">System</ContextMenuRadioItem>
- * </ContextMenuRadioGroup>
- * ```
- *
- * @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>,
-) {
+/** Groups related menu items together. Use with ContextMenuLabel. */
+function ContextMenuGroup({ ...props }: ContextMenuGroupProps) {
   return (
-    <ContextMenuPrimitive.RadioGroup
-      data-slot="context-menu-radio-group"
-      {...props}
-    />
+    <ContextMenuPrimitive.Group data-slot="context-menu-group" {...props} />
   );
 }
 
-/**
- * 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. Supports the same
- * interaction patterns as regular menu items with additional sub-menu behavior.
- *
- * @example
- * ```tsx
- * <ContextMenuSubTrigger>
- *   <Share className="mr-2 h-4 w-4" />
- *   Share Options
- * </ContextMenuSubTrigger>
- * ```
- *
- * @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({
+type ContextMenuLabelProps = ContextMenuPrimitive.GroupLabel.Props & {
+  /** Adds extra left padding to align with items that have icons. */
+  inset?: boolean;
+};
+
+/** Label for a group of context menu items. */
+function ContextMenuLabel({
   className,
   inset,
-  children,
   ...props
-}: React.ComponentProps<typeof ContextMenuPrimitive.SubTrigger> & {
-  inset?: boolean;
-}) {
+}: ContextMenuLabelProps) {
   return (
-    <ContextMenuPrimitive.SubTrigger
-      data-slot="context-menu-sub-trigger"
+    <ContextMenuPrimitive.GroupLabel
+      data-slot="context-menu-label"
       data-inset={inset}
       className={cn(
-        "focus:bg-accent focus:text-accent-foreground data-[state=open]:bg-accent data-[state=open]:text-accent-foreground flex cursor-default items-center rounded-sm px-2 py-1.5 text-sm outline-hidden select-none data-[inset]:pl-8 [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4",
+        "text-muted-foreground px-2 py-1.5 text-xs font-medium data-[inset]:pl-8",
         className,
       )}
       {...props}
-    >
-      {children}
-      <ChevronRightIcon className="ml-auto" />
-    </ContextMenuPrimitive.SubTrigger>
+    />
   );
 }
 
-/**
- * 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. Supports
- * all the same features as main menu content including keyboard navigation.
- *
- * @example
- * ```tsx
- * <ContextMenuSubContent>
- *   <ContextMenuItem>Option 1</ContextMenuItem>
- *   <ContextMenuItem>Option 2</ContextMenuItem>
- *   <ContextMenuSeparator />
- *   <ContextMenuItem>Option 3</ContextMenuItem>
- * </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
- */
-function ContextMenuSubContent({
+type ContextMenuItemProps = ContextMenuPrimitive.Item.Props & {
+  /** Adds extra left padding to align with items that have icons. */
+  inset?: boolean;
+  /** Visual style variant. @default "default" */
+  variant?: MenuItemVariant;
+};
+
+/** Interactive menu item. Closes menu on click by default. */
+function ContextMenuItem({
   className,
+  inset = false,
+  variant = "default",
   ...props
-}: React.ComponentProps<typeof ContextMenuPrimitive.SubContent>) {
+}: ContextMenuItemProps) {
   return (
-    <ContextMenuPrimitive.SubContent
-      data-slot="context-menu-sub-content"
+    <ContextMenuPrimitive.Item
+      data-slot="context-menu-item"
       className={cn(
-        "bg-popover text-popover-foreground data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0 data-[state=closed]:zoom-out-95 data-[state=open]:zoom-in-95 data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2 z-50 min-w-[8rem] origin-(--radix-context-menu-content-transform-origin) overflow-hidden rounded-md border p-1 shadow-lg",
+        menuItemVariants({ variant, inset }),
+        "group/context-menu-item",
         className,
       )}
       {...props}
@@ -795,354 +134,134 @@ 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 and smooth
- * animations. Renders in a portal by default for proper layering.
- *
- * @example
- * ```tsx
- * <ContextMenuContent className="w-56">
- *   <ContextMenuLabel>Actions</ContextMenuLabel>
- *   <ContextMenuSeparator />
- *   <ContextMenuItem>Copy</ContextMenuItem>
- *   <ContextMenuItem>Paste</ContextMenuItem>
- * </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, labels, separators, and sub-menus to display
- */
-function ContextMenuContent({
-  className,
-  ...props
-}: React.ComponentProps<typeof ContextMenuPrimitive.Content>) {
+type ContextMenuSubProps = ContextMenuPrimitive.SubmenuRoot.Props;
+
+/** Root component for a nested submenu. */
+function ContextMenuSub({ ...props }: ContextMenuSubProps) {
   return (
-    <ContextMenuPrimitive.Portal>
-      <ContextMenuPrimitive.Content
-        data-slot="context-menu-content"
-        className={cn(
-          "bg-popover text-popover-foreground data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0 data-[state=closed]:zoom-out-95 data-[state=open]:zoom-in-95 data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2 z-50 max-h-(--radix-context-menu-content-available-height) min-w-[8rem] origin-(--radix-context-menu-content-transform-origin) overflow-x-hidden overflow-y-auto rounded-md border p-1 shadow-md",
-          className,
-        )}
-        {...props}
-      />
-    </ContextMenuPrimitive.Portal>
+    <ContextMenuPrimitive.SubmenuRoot data-slot="context-menu-sub" {...props} />
   );
 }
 
-/**
- * ContextMenuItem - An actionable item within the context menu
- *
- * 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 onSelect={() => console.log('Edit selected')}>
- *   <Edit className="mr-2 h-4 w-4" />
- *   Edit
- *   <ContextMenuShortcut>⌘E</ContextMenuShortcut>
- * </ContextMenuItem>
- * ```
- *
- * @example
- * ```tsx
- * <ContextMenuItem variant="destructive" onSelect={handleDelete}>
- *   <Trash2 className="mr-2 h-4 w-4" />
- *   Delete
- * </ContextMenuItem>
- * ```
- *
- * @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({
+type ContextMenuSubTriggerProps = ContextMenuPrimitive.SubmenuTrigger.Props & {
+  /** Adds extra left padding to align with items that have icons. */
+  inset?: boolean;
+};
+
+/** Menu item that opens a submenu. Automatically includes chevron icon. */
+function ContextMenuSubTrigger({
   className,
   inset,
-  variant = "default",
+  children,
   ...props
-}: React.ComponentProps<typeof ContextMenuPrimitive.Item> & {
-  inset?: boolean;
-  variant?: "default" | "destructive";
-}) {
+}: ContextMenuSubTriggerProps) {
   return (
-    <ContextMenuPrimitive.Item
-      data-slot="context-menu-item"
+    <ContextMenuPrimitive.SubmenuTrigger
+      data-slot="context-menu-sub-trigger"
       data-inset={inset}
-      data-variant={variant}
       className={cn(
-        "focus:bg-accent focus:text-accent-foreground data-[variant=destructive]:text-destructive data-[variant=destructive]:focus:bg-destructive/10 dark:data-[variant=destructive]:focus:bg-destructive/20 data-[variant=destructive]:focus:text-destructive data-[variant=destructive]:*:[svg]:!text-destructive [&_svg:not([class*='text-'])]:text-muted-foreground relative flex cursor-default items-center gap-2 rounded-sm px-2 py-1.5 text-sm outline-hidden select-none data-[disabled]:pointer-events-none data-[disabled]:opacity-50 data-[inset]:pl-8 [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4",
+        "focus:bg-accent focus:text-accent-foreground data-open:bg-accent data-open:text-accent-foreground rounded-sm px-2 py-1.5 text-sm [&_svg:not([class*='size-'])]:size-4 flex cursor-default items-center outline-hidden select-none data-[inset]:pl-8 [&_svg]:pointer-events-none [&_svg]:shrink-0",
         className,
       )}
       {...props}
+    >
+      {children}
+      <ChevronRightIcon className="ml-auto" />
+    </ContextMenuPrimitive.SubmenuTrigger>
+  );
+}
+
+type ContextMenuSubContentProps = React.ComponentProps<
+  typeof ContextMenuContent
+>;
+
+/** Content container for a submenu. Opens to the right by default. */
+function ContextMenuSubContent({ ...props }: ContextMenuSubContentProps) {
+  return (
+    <ContextMenuContent
+      data-slot="context-menu-sub-content"
+      className="shadow-lg"
+      side="right"
+      {...props}
     />
   );
 }
 
-/**
- * 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
- * with indeterminate state for partially selected collections.
- *
- * @example
- * ```tsx
- * const [showGrid, setShowGrid] = useState(true)
- *
- * <ContextMenuCheckboxItem
- *   checked={showGrid}
- *   onCheckedChange={setShowGrid}
- * >
- *   Show Grid
- * </ContextMenuCheckboxItem>
- * ```
- *
- * @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 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)
- */
+type ContextMenuCheckboxItemProps = ContextMenuPrimitive.CheckboxItem.Props;
+
+/** Menu item with checkbox. Shows check icon when selected. */
 function ContextMenuCheckboxItem({
   className,
   children,
   checked,
   ...props
-}: React.ComponentProps<typeof ContextMenuPrimitive.CheckboxItem>) {
+}: ContextMenuCheckboxItemProps) {
   return (
     <ContextMenuPrimitive.CheckboxItem
       data-slot="context-menu-checkbox-item"
       className={cn(
-        "focus:bg-accent focus:text-accent-foreground relative flex cursor-default items-center gap-2 rounded-sm py-1.5 pr-2 pl-8 text-sm outline-hidden select-none data-[disabled]:pointer-events-none data-[disabled]:opacity-50 [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4",
+        "focus:bg-accent focus:text-accent-foreground gap-2 rounded-sm py-1.5 pr-8 pl-2 text-sm [&_svg:not([class*='size-'])]:size-4 relative flex cursor-default items-center outline-hidden select-none data-[disabled]:pointer-events-none data-[disabled]:opacity-50 [&_svg]:pointer-events-none [&_svg]:shrink-0",
         className,
       )}
       checked={checked}
       {...props}
     >
-      <span className="pointer-events-none absolute left-2 flex size-3.5 items-center justify-center">
-        <ContextMenuPrimitive.ItemIndicator>
-          <CheckIcon className="size-4" />
-        </ContextMenuPrimitive.ItemIndicator>
+      <span className="absolute right-2 pointer-events-none">
+        <ContextMenuPrimitive.CheckboxItemIndicator>
+          <CheckIcon />
+        </ContextMenuPrimitive.CheckboxItemIndicator>
       </span>
       {children}
     </ContextMenuPrimitive.CheckboxItem>
   );
 }
 
-/**
- * ContextMenuRadioItem - A radio button item within a radio group
- *
- * 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 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 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)
- */
+type ContextMenuRadioGroupProps = ContextMenuPrimitive.RadioGroup.Props;
+
+/** Container for mutually exclusive radio items. */
+function ContextMenuRadioGroup({ ...props }: ContextMenuRadioGroupProps) {
+  return (
+    <ContextMenuPrimitive.RadioGroup
+      data-slot="context-menu-radio-group"
+      {...props}
+    />
+  );
+}
+
+type ContextMenuRadioItemProps = ContextMenuPrimitive.RadioItem.Props;
+
+/** Radio button menu item. Shows check icon when selected. */
 function ContextMenuRadioItem({
   className,
   children,
   ...props
-}: React.ComponentProps<typeof ContextMenuPrimitive.RadioItem>) {
+}: ContextMenuRadioItemProps) {
   return (
     <ContextMenuPrimitive.RadioItem
       data-slot="context-menu-radio-item"
       className={cn(
-        "focus:bg-accent focus:text-accent-foreground relative flex cursor-default items-center gap-2 rounded-sm py-1.5 pr-2 pl-8 text-sm outline-hidden select-none data-[disabled]:pointer-events-none data-[disabled]:opacity-50 [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4",
+        "focus:bg-accent focus:text-accent-foreground gap-2 rounded-sm py-1.5 pr-8 pl-2 text-sm [&_svg:not([class*='size-'])]:size-4 relative flex cursor-default items-center outline-hidden select-none data-[disabled]:pointer-events-none data-[disabled]:opacity-50 [&_svg]:pointer-events-none [&_svg]:shrink-0",
         className,
       )}
       {...props}
     >
-      <span className="pointer-events-none absolute left-2 flex size-3.5 items-center justify-center">
-        <ContextMenuPrimitive.ItemIndicator>
-          <CircleIcon className="size-2 fill-current" />
-        </ContextMenuPrimitive.ItemIndicator>
+      <span className="absolute right-2 pointer-events-none">
+        <ContextMenuPrimitive.RadioItemIndicator>
+          <CheckIcon />
+        </ContextMenuPrimitive.RadioItemIndicator>
       </span>
       {children}
     </ContextMenuPrimitive.RadioItem>
   );
 }
 
-/**
- * ContextMenuLabel - A non-interactive label for menu sections
- *
- * 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
- * <ContextMenuLabel>File Actions</ContextMenuLabel>
- * <ContextMenuSeparator />
- * <ContextMenuItem>Open</ContextMenuItem>
- * <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> & {
-  inset?: boolean;
-}) {
-  return (
-    <ContextMenuPrimitive.Label
-      data-slot="context-menu-label"
-      data-inset={inset}
-      className={cn(
-        "text-foreground px-2 py-1.5 text-sm font-medium data-[inset]:pl-8",
-        className,
-      )}
-      {...props}
-    />
-  );
-}
+type ContextMenuSeparatorProps = ContextMenuPrimitive.Separator.Props;
 
-/**
- * ContextMenuSeparator - A visual divider between menu items
- *
- * 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
- * <ContextMenuItem>Copy</ContextMenuItem>
- * <ContextMenuItem>Paste</ContextMenuItem>
- * <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
- */
+/** Visual separator between menu items or groups. */
 function ContextMenuSeparator({
   className,
   ...props
-}: React.ComponentProps<typeof ContextMenuPrimitive.Separator>) {
+}: ContextMenuSeparatorProps) {
   return (
     <ContextMenuPrimitive.Separator
       data-slot="context-menu-separator"
@@ -1152,53 +271,18 @@ function ContextMenuSeparator({
   );
 }
 
-/**
- * ContextMenuShortcut - Displays keyboard shortcuts within menu items
- *
- * 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
- * <ContextMenuItem>
- *   Copy
- *   <ContextMenuShortcut>⌘C</ContextMenuShortcut>
- * </ContextMenuItem>
- * ```
- *
- * @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")
- */
+type ContextMenuShortcutProps = React.ComponentProps<"span">;
+
+/** Displays keyboard shortcut hint aligned to the right of menu item. */
 function ContextMenuShortcut({
   className,
   ...props
-}: React.ComponentProps<"span">) {
+}: ContextMenuShortcutProps) {
   return (
     <span
       data-slot="context-menu-shortcut"
       className={cn(
-        "text-muted-foreground ml-auto text-xs tracking-widest",
+        "text-muted-foreground group-focus/context-menu-item:text-accent-foreground ml-auto text-xs tracking-widest",
         className,
       )}
       {...props}
@@ -1222,7 +306,19 @@ export {
   ContextMenuSubContent,
   ContextMenuSubTrigger,
   ContextMenuRadioGroup,
+  type ContextMenuProps,
+  type ContextMenuTriggerProps,
+  type ContextMenuContentProps,
+  type ContextMenuItemProps,
+  type ContextMenuCheckboxItemProps,
+  type ContextMenuRadioItemProps,
+  type ContextMenuLabelProps,
+  type ContextMenuSeparatorProps,
+  type ContextMenuShortcutProps,
+  type ContextMenuGroupProps,
+  type ContextMenuPortalProps,
+  type ContextMenuSubProps,
+  type ContextMenuSubContentProps,
+  type ContextMenuSubTriggerProps,
+  type ContextMenuRadioGroupProps,
 };
-
-// NOTE: Internal documentation types are NOT exported
-// Components use Radix UI inferred types for implementation