@neynar/ui 0.1.1

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

@@ -0,0 +1,563 @@
+import * as React from "react";
+import * as ContextMenuPrimitive from "@radix-ui/react-context-menu";
+import { CheckIcon, ChevronRightIcon, CircleIcon } from "lucide-react";
+
+import { cn } from "@/lib/utils";
+
+/**
+ * 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>
+ * ```
+ *
+ * @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
+ *
+ * @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
+ */
+function ContextMenu({
+  ...props
+}: React.ComponentProps<typeof ContextMenuPrimitive.Root>) {
+  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.
+ *
+ * @example
+ * ```tsx
+ * <ContextMenuTrigger>
+ *   <Button variant="outline">Right-click me</Button>
+ * </ContextMenuTrigger>
+ * ```
+ *
+ * @param children - Any React element that should trigger the context menu
+ */
+function ContextMenuTrigger({
+  ...props
+}: React.ComponentProps<typeof ContextMenuPrimitive.Trigger>) {
+  return (
+    <ContextMenuPrimitive.Trigger data-slot="context-menu-trigger" {...props} />
+  );
+}
+
+/**
+ * ContextMenuGroup - Logical grouping for menu items
+ *
+ * Groups related menu items together for better organization and accessibility.
+ * Provides semantic structure without visual changes.
+ *
+ * @example
+ * ```tsx
+ * <ContextMenuGroup>
+ *   <ContextMenuItem>Copy</ContextMenuItem>
+ *   <ContextMenuItem>Cut</ContextMenuItem>
+ *   <ContextMenuItem>Paste</ContextMenuItem>
+ * </ContextMenuGroup>
+ * ```
+ */
+function ContextMenuGroup({
+  ...props
+}: React.ComponentProps<typeof ContextMenuPrimitive.Group>) {
+  return (
+    <ContextMenuPrimitive.Group data-slot="context-menu-group" {...props} />
+  );
+}
+
+/**
+ * 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.
+ *
+ * @example
+ * ```tsx
+ * <ContextMenuPortal>
+ *   <ContextMenuSubContent>
+ *     <ContextMenuItem>Portal Item</ContextMenuItem>
+ *   </ContextMenuSubContent>
+ * </ContextMenuPortal>
+ * ```
+ *
+ * @param container - Custom container element for the portal
+ */
+function ContextMenuPortal({
+  ...props
+}: React.ComponentProps<typeof ContextMenuPrimitive.Portal>) {
+  return (
+    <ContextMenuPrimitive.Portal data-slot="context-menu-portal" {...props} />
+  );
+}
+
+/**
+ * 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.
+ *
+ * @example
+ * ```tsx
+ * <ContextMenuSub>
+ *   <ContextMenuSubTrigger>Share</ContextMenuSubTrigger>
+ *   <ContextMenuSubContent>
+ *     <ContextMenuItem>Email</ContextMenuItem>
+ *     <ContextMenuItem>Copy Link</ContextMenuItem>
+ *   </ContextMenuSubContent>
+ * </ContextMenuSub>
+ * ```
+ */
+function ContextMenuSub({
+  ...props
+}: React.ComponentProps<typeof ContextMenuPrimitive.Sub>) {
+  return <ContextMenuPrimitive.Sub data-slot="context-menu-sub" {...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.
+ *
+ * @example
+ * ```tsx
+ * <ContextMenuRadioGroup value={theme} onValueChange={setTheme}>
+ *   <ContextMenuRadioItem value="light">Light</ContextMenuRadioItem>
+ *   <ContextMenuRadioItem value="dark">Dark</ContextMenuRadioItem>
+ *   <ContextMenuRadioItem value="system">System</ContextMenuRadioItem>
+ * </ContextMenuRadioGroup>
+ * ```
+ *
+ * @param value - The currently selected value
+ * @param onValueChange - Callback fired when selection changes
+ */
+function ContextMenuRadioGroup({
+  ...props
+}: React.ComponentProps<typeof ContextMenuPrimitive.RadioGroup>) {
+  return (
+    <ContextMenuPrimitive.RadioGroup
+      data-slot="context-menu-radio-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.
+ *
+ * @example
+ * ```tsx
+ * <ContextMenuSubTrigger>
+ *   <Share className="mr-2 h-4 w-4" />
+ *   Share Options
+ * </ContextMenuSubTrigger>
+ * ```
+ *
+ * @param inset - Whether to indent the trigger for proper alignment
+ * @param children - Content of the trigger (text, icons, etc.)
+ */
+function ContextMenuSubTrigger({
+  className,
+  inset,
+  children,
+  ...props
+}: React.ComponentProps<typeof ContextMenuPrimitive.SubTrigger> & {
+  /** Whether to indent the trigger for proper alignment */
+  inset?: boolean;
+}) {
+  return (
+    <ContextMenuPrimitive.SubTrigger
+      data-slot="context-menu-sub-trigger"
+      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",
+        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.
+ *
+ * @example
+ * ```tsx
+ * <ContextMenuSubContent>
+ *   <ContextMenuItem>Option 1</ContextMenuItem>
+ *   <ContextMenuItem>Option 2</ContextMenuItem>
+ *   <ContextMenuSeparator />
+ *   <ContextMenuItem>Option 3</ContextMenuItem>
+ * </ContextMenuSubContent>
+ * ```
+ *
+ * @param className - Additional CSS classes for styling
+ * @param children - Sub-menu items, separators, and labels
+ */
+function ContextMenuSubContent({
+  className,
+  ...props
+}: React.ComponentProps<typeof ContextMenuPrimitive.SubContent>) {
+  return (
+    <ContextMenuPrimitive.SubContent
+      data-slot="context-menu-sub-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 min-w-[8rem] origin-(--radix-context-menu-content-transform-origin) overflow-hidden rounded-md border p-1 shadow-lg",
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+
+/**
+ * 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.
+ *
+ * @example
+ * ```tsx
+ * <ContextMenuContent className="w-56">
+ *   <ContextMenuLabel>Actions</ContextMenuLabel>
+ *   <ContextMenuSeparator />
+ *   <ContextMenuItem>Copy</ContextMenuItem>
+ *   <ContextMenuItem>Paste</ContextMenuItem>
+ * </ContextMenuContent>
+ * ```
+ *
+ * @param className - Additional CSS classes for styling
+ * @param children - Menu items, separators, labels, and sub-menus
+ */
+function ContextMenuContent({
+  className,
+  ...props
+}: React.ComponentProps<typeof ContextMenuPrimitive.Content>) {
+  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>
+  );
+}
+
+/**
+ * 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.
+ *
+ * @example
+ * ```tsx
+ * <ContextMenuItem>
+ *   <Edit className="mr-2 h-4 w-4" />
+ *   Edit
+ *   <ContextMenuShortcut>⌘E</ContextMenuShortcut>
+ * </ContextMenuItem>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * <ContextMenuItem variant="destructive">
+ *   <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
+ */
+function ContextMenuItem({
+  className,
+  inset,
+  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 (
+    <ContextMenuPrimitive.Item
+      data-slot="context-menu-item"
+      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",
+        className,
+      )}
+      {...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.
+ *
+ * @example
+ * ```tsx
+ * const [showGrid, setShowGrid] = useState(true)
+ *
+ * <ContextMenuCheckboxItem
+ *   checked={showGrid}
+ *   onCheckedChange={setShowGrid}
+ * >
+ *   Show Grid
+ * </ContextMenuCheckboxItem>
+ * ```
+ *
+ * @param checked - Whether the checkbox is checked
+ * @param onCheckedChange - Callback fired when the checked state changes
+ * @param disabled - Whether the item is disabled
+ */
+function ContextMenuCheckboxItem({
+  className,
+  children,
+  checked,
+  ...props
+}: React.ComponentProps<typeof ContextMenuPrimitive.CheckboxItem>) {
+  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",
+        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>
+      {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.
+ *
+ * @example
+ * ```tsx
+ * <ContextMenuRadioGroup value={theme} onValueChange={setTheme}>
+ *   <ContextMenuRadioItem value="light">Light</ContextMenuRadioItem>
+ *   <ContextMenuRadioItem value="dark">Dark</ContextMenuRadioItem>
+ *   <ContextMenuRadioItem value="system">System</ContextMenuRadioItem>
+ * </ContextMenuRadioGroup>
+ * ```
+ *
+ * @param value - The value of this radio item
+ * @param disabled - Whether the item is disabled
+ */
+function ContextMenuRadioItem({
+  className,
+  children,
+  ...props
+}: React.ComponentProps<typeof ContextMenuPrimitive.RadioItem>) {
+  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",
+        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>
+      {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.
+ *
+ * @example
+ * ```tsx
+ * <ContextMenuLabel>File Actions</ContextMenuLabel>
+ * <ContextMenuSeparator />
+ * <ContextMenuItem>Open</ContextMenuItem>
+ * <ContextMenuItem>Save</ContextMenuItem>
+ * ```
+ *
+ * @param inset - Whether to indent the label to align with inset items
+ */
+function ContextMenuLabel({
+  className,
+  inset,
+  ...props
+}: React.ComponentProps<typeof ContextMenuPrimitive.Label> & {
+  /** Whether to indent the label for proper alignment */
+  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}
+    />
+  );
+}
+
+/**
+ * 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.
+ *
+ * @example
+ * ```tsx
+ * <ContextMenuItem>Copy</ContextMenuItem>
+ * <ContextMenuItem>Paste</ContextMenuItem>
+ * <ContextMenuSeparator />
+ * <ContextMenuItem variant="destructive">Delete</ContextMenuItem>
+ * ```
+ */
+function ContextMenuSeparator({
+  className,
+  ...props
+}: React.ComponentProps<typeof ContextMenuPrimitive.Separator>) {
+  return (
+    <ContextMenuPrimitive.Separator
+      data-slot="context-menu-separator"
+      className={cn("bg-border -mx-1 my-1 h-px", className)}
+      {...props}
+    />
+  );
+}
+
+/**
+ * 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.
+ *
+ * @example
+ * ```tsx
+ * <ContextMenuItem>
+ *   Copy
+ *   <ContextMenuShortcut>⌘C</ContextMenuShortcut>
+ * </ContextMenuItem>
+ * ```
+ *
+ * @param children - The shortcut text (e.g., "⌘C", "Ctrl+V")
+ */
+function ContextMenuShortcut({
+  className,
+  ...props
+}: React.ComponentProps<"span">) {
+  return (
+    <span
+      data-slot="context-menu-shortcut"
+      className={cn(
+        "text-muted-foreground ml-auto text-xs tracking-widest",
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+
+export {
+  ContextMenu,
+  ContextMenuTrigger,
+  ContextMenuContent,
+  ContextMenuItem,
+  ContextMenuCheckboxItem,
+  ContextMenuRadioItem,
+  ContextMenuLabel,
+  ContextMenuSeparator,
+  ContextMenuShortcut,
+  ContextMenuGroup,
+  ContextMenuPortal,
+  ContextMenuSub,
+  ContextMenuSubContent,
+  ContextMenuSubTrigger,
+  ContextMenuRadioGroup,
+};