@neynar/ui 0.1.1

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

@@ -0,0 +1,578 @@
+import * as React from "react";
+import * as DropdownMenuPrimitive from "@radix-ui/react-dropdown-menu";
+import { CheckIcon, ChevronRightIcon, CircleIcon } from "lucide-react";
+
+import { cn } from "@/lib/utils";
+
+/**
+ * A versatile dropdown menu component built on Radix UI primitives
+ *
+ * Dropdown menus display a list of actions or options that a user can choose from.
+ * They're typically triggered by a button and appear as a floating panel with full
+ * keyboard navigation support, submenus, and various interactive item types.
+ *
+ * Based on the shadcn/ui dropdown-menu component with additional enhancements for
+ * better integration with design systems and improved accessibility.
+ *
+ * @component
+ * @example
+ * ```tsx
+ * // Basic dropdown menu
+ * <DropdownMenu>
+ *   <DropdownMenuTrigger asChild>
+ *     <Button variant="outline">Options</Button>
+ *   </DropdownMenuTrigger>
+ *   <DropdownMenuContent>
+ *     <DropdownMenuItem>Profile</DropdownMenuItem>
+ *     <DropdownMenuItem>Settings</DropdownMenuItem>
+ *     <DropdownMenuSeparator />
+ *     <DropdownMenuItem>Logout</DropdownMenuItem>
+ *   </DropdownMenuContent>
+ * </DropdownMenu>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Context menu with alignment and destructive actions
+ * <DropdownMenu>
+ *   <DropdownMenuTrigger asChild>
+ *     <Button variant="ghost" size="icon">
+ *       <MoreHorizontal />
+ *     </Button>
+ *   </DropdownMenuTrigger>
+ *   <DropdownMenuContent align="end">
+ *     <DropdownMenuItem>Edit</DropdownMenuItem>
+ *     <DropdownMenuItem>Duplicate</DropdownMenuItem>
+ *     <DropdownMenuSeparator />
+ *     <DropdownMenuItem variant="destructive">Delete</DropdownMenuItem>
+ *   </DropdownMenuContent>
+ * </DropdownMenu>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Complex menu with checkboxes, radio groups, and submenus
+ * <DropdownMenu>
+ *   <DropdownMenuTrigger asChild>
+ *     <Button>Advanced Menu</Button>
+ *   </DropdownMenuTrigger>
+ *   <DropdownMenuContent className="w-56">
+ *     <DropdownMenuLabel>View Options</DropdownMenuLabel>
+ *     <DropdownMenuSeparator />
+ *     <DropdownMenuCheckboxItem checked={showPanel} onCheckedChange={setShowPanel}>
+ *       Show Panel
+ *     </DropdownMenuCheckboxItem>
+ *     <DropdownMenuSeparator />
+ *     <DropdownMenuRadioGroup value={position} onValueChange={setPosition}>
+ *       <DropdownMenuRadioItem value="top">Top</DropdownMenuRadioItem>
+ *       <DropdownMenuRadioItem value="bottom">Bottom</DropdownMenuRadioItem>
+ *     </DropdownMenuRadioGroup>
+ *     <DropdownMenuSeparator />
+ *     <DropdownMenuSub>
+ *       <DropdownMenuSubTrigger>Share</DropdownMenuSubTrigger>
+ *       <DropdownMenuSubContent>
+ *         <DropdownMenuItem>Email</DropdownMenuItem>
+ *         <DropdownMenuItem>Copy Link</DropdownMenuItem>
+ *       </DropdownMenuSubContent>
+ *     </DropdownMenuSub>
+ *   </DropdownMenuContent>
+ * </DropdownMenu>
+ * ```
+ *
+ * @accessibility
+ * - Full keyboard navigation with arrow keys (Up/Down for navigation)
+ * - Enter/Space to activate items
+ * - Escape key closes the menu and restores focus
+ * - Home/End keys navigate to first/last item
+ * - Type-ahead search to jump to items by first letter
+ * - Left/Right arrow keys for submenu navigation
+ * - Proper ARIA roles (menu, menuitem, menuitemcheckbox, menuitemradio)
+ * - Focus management with focus trapping and restoration
+ * - Screen reader announcements for state changes
+ *
+ * @see {@link ContextMenu} - For right-click context menus
+ * @see {@link Popover} - For rich content overlays
+ * @see {@link Select} - For single selection dropdowns
+ * @see {@link https://ui.shadcn.com/docs/components/dropdown-menu} - shadcn/ui documentation
+ * @since 1.0.0
+ */
+function DropdownMenu({
+  ...props
+}: React.ComponentProps<typeof DropdownMenuPrimitive.Root>) {
+  return <DropdownMenuPrimitive.Root data-slot="dropdown-menu" {...props} />;
+}
+
+/**
+ * Portal component for rendering menu content in a different DOM location
+ *
+ * Renders dropdown content outside of the normal DOM hierarchy to avoid
+ * z-index and overflow issues. Automatically used by DropdownMenuContent
+ * but can be used explicitly for submenus.
+ *
+ * @component
+ * @param container - Optional container element for portal rendering
+ * @since 1.0.0
+ */
+function DropdownMenuPortal({
+  ...props
+}: React.ComponentProps<typeof DropdownMenuPrimitive.Portal>) {
+  return (
+    <DropdownMenuPrimitive.Portal data-slot="dropdown-menu-portal" {...props} />
+  );
+}
+
+/**
+ * DropdownMenuTrigger - The element that triggers the dropdown menu
+ *
+ * @component
+ * @example
+ * ```tsx
+ * <DropdownMenuTrigger asChild>
+ *   <Button>Menu</Button>
+ * </DropdownMenuTrigger>
+ * ```
+ * @since 1.0.0
+ */
+function DropdownMenuTrigger({
+  ...props
+}: React.ComponentProps<typeof DropdownMenuPrimitive.Trigger>) {
+  return (
+    <DropdownMenuPrimitive.Trigger
+      data-slot="dropdown-menu-trigger"
+      {...props}
+    />
+  );
+}
+
+/**
+ * DropdownMenuContent - The content container for dropdown menu items
+ *
+ * @component
+ * @example
+ * ```tsx
+ * <DropdownMenuContent align="end" sideOffset={5}>
+ *   <DropdownMenuItem>Item 1</DropdownMenuItem>
+ * </DropdownMenuContent>
+ * ```
+ * @since 1.0.0
+ */
+function DropdownMenuContent({
+  className,
+  sideOffset = 4,
+  ...props
+}: React.ComponentProps<typeof DropdownMenuPrimitive.Content>) {
+  return (
+    <DropdownMenuPrimitive.Portal>
+      <DropdownMenuPrimitive.Content
+        data-slot="dropdown-menu-content"
+        sideOffset={sideOffset}
+        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-dropdown-menu-content-available-height) min-w-[8rem] origin-(--radix-dropdown-menu-content-transform-origin) overflow-x-hidden overflow-y-auto rounded-md border p-1 shadow-md",
+          className,
+        )}
+        {...props}
+      />
+    </DropdownMenuPrimitive.Portal>
+  );
+}
+
+/**
+ * Groups related dropdown menu items together
+ *
+ * Used to create logical groupings of menu items, typically separated by
+ * DropdownMenuSeparator components. Helps with semantic organization and
+ * keyboard navigation.
+ *
+ * @component
+ * @example
+ * ```tsx
+ * <DropdownMenuGroup>
+ *   <DropdownMenuItem>Profile</DropdownMenuItem>
+ *   <DropdownMenuItem>Settings</DropdownMenuItem>
+ * </DropdownMenuGroup>
+ * ```
+ * @since 1.0.0
+ */
+function DropdownMenuGroup({
+  ...props
+}: React.ComponentProps<typeof DropdownMenuPrimitive.Group>) {
+  return (
+    <DropdownMenuPrimitive.Group data-slot="dropdown-menu-group" {...props} />
+  );
+}
+
+/**
+ * DropdownMenuItem - A single item in the dropdown menu
+ *
+ * @component
+ * @example
+ * ```tsx
+ * <DropdownMenuItem onClick={handleClick}>
+ *   Edit
+ * </DropdownMenuItem>
+ * <DropdownMenuItem variant="destructive">
+ *   Delete
+ * </DropdownMenuItem>
+ * ```
+ * @since 1.0.0
+ */
+function DropdownMenuItem({
+  className,
+  inset,
+  variant = "default",
+  ...props
+}: React.ComponentProps<typeof DropdownMenuPrimitive.Item> & {
+  inset?: boolean;
+  variant?: "default" | "destructive";
+}) {
+  return (
+    <DropdownMenuPrimitive.Item
+      data-slot="dropdown-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}
+    />
+  );
+}
+
+/**
+ * A checkable menu item with visual state indication
+ *
+ * Displays a checkbox that can be toggled on/off. The checked state is
+ * visually indicated with a checkmark icon. Useful for menu options that
+ * represent toggleable settings or features.
+ *
+ * @component
+ * @param checked - Whether the checkbox is checked
+ * @param onCheckedChange - Callback when the checked state changes
+ * @param disabled - Whether the item is disabled
+ *
+ * @example
+ * ```tsx
+ * const [showSidebar, setShowSidebar] = useState(true);
+ *
+ * <DropdownMenuCheckboxItem
+ *   checked={showSidebar}
+ *   onCheckedChange={setShowSidebar}
+ * >
+ *   Show Sidebar
+ * </DropdownMenuCheckboxItem>
+ * ```
+ * @since 1.0.0
+ */
+function DropdownMenuCheckboxItem({
+  className,
+  children,
+  checked,
+  ...props
+}: React.ComponentProps<typeof DropdownMenuPrimitive.CheckboxItem>) {
+  return (
+    <DropdownMenuPrimitive.CheckboxItem
+      data-slot="dropdown-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">
+        <DropdownMenuPrimitive.ItemIndicator>
+          <CheckIcon className="size-4" />
+        </DropdownMenuPrimitive.ItemIndicator>
+      </span>
+      {children}
+    </DropdownMenuPrimitive.CheckboxItem>
+  );
+}
+
+/**
+ * Groups radio items for single selection
+ *
+ * Creates a group where only one radio item can be selected at a time.
+ * Use with DropdownMenuRadioItem components to create single-choice options.
+ *
+ * @component
+ * @param value - Currently selected value
+ * @param onValueChange - Callback when selection changes
+ *
+ * @example
+ * ```tsx
+ * const [theme, setTheme] = useState("light");
+ *
+ * <DropdownMenuRadioGroup value={theme} onValueChange={setTheme}>
+ *   <DropdownMenuRadioItem value="light">Light</DropdownMenuRadioItem>
+ *   <DropdownMenuRadioItem value="dark">Dark</DropdownMenuRadioItem>
+ *   <DropdownMenuRadioItem value="system">System</DropdownMenuRadioItem>
+ * </DropdownMenuRadioGroup>
+ * ```
+ * @since 1.0.0
+ */
+function DropdownMenuRadioGroup({
+  ...props
+}: React.ComponentProps<typeof DropdownMenuPrimitive.RadioGroup>) {
+  return (
+    <DropdownMenuPrimitive.RadioGroup
+      data-slot="dropdown-menu-radio-group"
+      {...props}
+    />
+  );
+}
+
+/**
+ * A radio button menu item for single selection within a group
+ *
+ * Must be used within a DropdownMenuRadioGroup. Shows a filled circle
+ * indicator when selected. Only one radio item can be selected per group.
+ *
+ * @component
+ * @param value - The value this radio item represents
+ * @param disabled - Whether the item is disabled
+ *
+ * @example
+ * ```tsx
+ * <DropdownMenuRadioGroup value={selectedTheme} onValueChange={setSelectedTheme}>
+ *   <DropdownMenuRadioItem value="light">
+ *     Light Theme
+ *   </DropdownMenuRadioItem>
+ *   <DropdownMenuRadioItem value="dark">
+ *     Dark Theme
+ *   </DropdownMenuRadioItem>
+ * </DropdownMenuRadioGroup>
+ * ```
+ * @since 1.0.0
+ */
+function DropdownMenuRadioItem({
+  className,
+  children,
+  ...props
+}: React.ComponentProps<typeof DropdownMenuPrimitive.RadioItem>) {
+  return (
+    <DropdownMenuPrimitive.RadioItem
+      data-slot="dropdown-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">
+        <DropdownMenuPrimitive.ItemIndicator>
+          <CircleIcon className="size-2 fill-current" />
+        </DropdownMenuPrimitive.ItemIndicator>
+      </span>
+      {children}
+    </DropdownMenuPrimitive.RadioItem>
+  );
+}
+
+/**
+ * DropdownMenuLabel - A label for grouping menu items
+ *
+ * @component
+ * @example
+ * ```tsx
+ * <DropdownMenuLabel>Actions</DropdownMenuLabel>
+ * ```
+ * @since 1.0.0
+ */
+function DropdownMenuLabel({
+  className,
+  inset,
+  ...props
+}: React.ComponentProps<typeof DropdownMenuPrimitive.Label> & {
+  inset?: boolean;
+}) {
+  return (
+    <DropdownMenuPrimitive.Label
+      data-slot="dropdown-menu-label"
+      data-inset={inset}
+      className={cn(
+        "px-2 py-1.5 text-sm font-medium data-[inset]:pl-8",
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+
+/**
+ * DropdownMenuSeparator - A visual separator between menu items
+ *
+ * @component
+ * @since 1.0.0
+ */
+function DropdownMenuSeparator({
+  className,
+  ...props
+}: React.ComponentProps<typeof DropdownMenuPrimitive.Separator>) {
+  return (
+    <DropdownMenuPrimitive.Separator
+      data-slot="dropdown-menu-separator"
+      className={cn("bg-border -mx-1 my-1 h-px", className)}
+      {...props}
+    />
+  );
+}
+
+/**
+ * Displays keyboard shortcut hints in menu items
+ *
+ * Shows keyboard shortcut text aligned to the right side of menu items.
+ * Purely visual - does not implement the actual keyboard functionality.
+ * Use standard keyboard shortcut notation (⌘, ⌃, ⌥, ⇧).
+ *
+ * @component
+ * @example
+ * ```tsx
+ * <DropdownMenuItem>
+ *   Save Document
+ *   <DropdownMenuShortcut>⌘S</DropdownMenuShortcut>
+ * </DropdownMenuItem>
+ * ```
+ * @since 1.0.0
+ */
+function DropdownMenuShortcut({
+  className,
+  ...props
+}: React.ComponentProps<"span">) {
+  return (
+    <span
+      data-slot="dropdown-menu-shortcut"
+      className={cn(
+        "text-muted-foreground ml-auto text-xs tracking-widest",
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+
+/**
+ * Container for creating nested submenus
+ *
+ * Wraps a submenu trigger and content to create hierarchical menu structures.
+ * Use with DropdownMenuSubTrigger and DropdownMenuSubContent.
+ *
+ * @component
+ * @example
+ * ```tsx
+ * <DropdownMenuSub>
+ *   <DropdownMenuSubTrigger>Share</DropdownMenuSubTrigger>
+ *   <DropdownMenuSubContent>
+ *     <DropdownMenuItem>Email</DropdownMenuItem>
+ *     <DropdownMenuItem>Copy Link</DropdownMenuItem>
+ *   </DropdownMenuSubContent>
+ * </DropdownMenuSub>
+ * ```
+ * @since 1.0.0
+ */
+function DropdownMenuSub({
+  ...props
+}: React.ComponentProps<typeof DropdownMenuPrimitive.Sub>) {
+  return <DropdownMenuPrimitive.Sub data-slot="dropdown-menu-sub" {...props} />;
+}
+
+/**
+ * Trigger element for opening a submenu
+ *
+ * Displays an arrow indicator and opens the associated submenu on hover or click.
+ * Must be used within a DropdownMenuSub component.
+ *
+ * @component
+ * @param inset - Whether to add left padding to align with items that have icons
+ *
+ * @example
+ * ```tsx
+ * <DropdownMenuSub>
+ *   <DropdownMenuSubTrigger>
+ *     <Share className="mr-2 h-4 w-4" />
+ *     Share Options
+ *   </DropdownMenuSubTrigger>
+ *   <DropdownMenuSubContent>
+ *     <DropdownMenuItem>Email</DropdownMenuItem>
+ *     <DropdownMenuItem>Copy Link</DropdownMenuItem>
+ *   </DropdownMenuSubContent>
+ * </DropdownMenuSub>
+ * ```
+ * @since 1.0.0
+ */
+function DropdownMenuSubTrigger({
+  className,
+  inset,
+  children,
+  ...props
+}: React.ComponentProps<typeof DropdownMenuPrimitive.SubTrigger> & {
+  inset?: boolean;
+}) {
+  return (
+    <DropdownMenuPrimitive.SubTrigger
+      data-slot="dropdown-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",
+        className,
+      )}
+      {...props}
+    >
+      {children}
+      <ChevronRightIcon className="ml-auto size-4" />
+    </DropdownMenuPrimitive.SubTrigger>
+  );
+}
+
+/**
+ * Content container for submenu items
+ *
+ * Contains the items displayed when a submenu is opened. Positioned relative
+ * to the trigger and supports the same item types as the main menu.
+ *
+ * @component
+ * @example
+ * ```tsx
+ * <DropdownMenuSubContent>
+ *   <DropdownMenuItem>Submenu Item 1</DropdownMenuItem>
+ *   <DropdownMenuItem>Submenu Item 2</DropdownMenuItem>
+ *   <DropdownMenuSeparator />
+ *   <DropdownMenuItem>Submenu Item 3</DropdownMenuItem>
+ * </DropdownMenuSubContent>
+ * ```
+ * @since 1.0.0
+ */
+function DropdownMenuSubContent({
+  className,
+  ...props
+}: React.ComponentProps<typeof DropdownMenuPrimitive.SubContent>) {
+  return (
+    <DropdownMenuPrimitive.SubContent
+      data-slot="dropdown-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-dropdown-menu-content-transform-origin) overflow-hidden rounded-md border p-1 shadow-lg",
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+
+export {
+  DropdownMenu,
+  DropdownMenuPortal,
+  DropdownMenuTrigger,
+  DropdownMenuContent,
+  DropdownMenuGroup,
+  DropdownMenuLabel,
+  DropdownMenuItem,
+  DropdownMenuCheckboxItem,
+  DropdownMenuRadioGroup,
+  DropdownMenuRadioItem,
+  DropdownMenuSeparator,
+  DropdownMenuShortcut,
+  DropdownMenuSub,
+  DropdownMenuSubTrigger,
+  DropdownMenuSubContent,
+};