@neynar/ui 0.1.1

package/src/components/ui/menubar.tsx

@@ -0,0 +1,553 @@
+import * as React from "react";
+import * as MenubarPrimitive from "@radix-ui/react-menubar";
+import { CheckIcon, ChevronRightIcon, CircleIcon } from "lucide-react";
+
+import { cn } from "@/lib/utils";
+
+/**
+ * A visually persistent menu common in desktop applications that provides access to a consistent set of commands.
+ * 
+ * Menubar provides a horizontal navigation structure similar to desktop application menus
+ * like those found in VS Code, Figma, or native applications. Each menu contains dropdown
+ * content with actions, checkboxes, radio groups, and nested submenus.
+ * 
+ * Built on top of Radix UI Menubar primitive with full keyboard navigation and accessibility support.
+ * 
+ * @example
+ * ```tsx
+ * // Basic application menubar
+ * <Menubar>
+ *   <MenubarMenu>
+ *     <MenubarTrigger>File</MenubarTrigger>
+ *     <MenubarContent>
+ *       <MenubarItem>New File <MenubarShortcut>⌘N</MenubarShortcut></MenubarItem>
+ *       <MenubarItem>Open <MenubarShortcut>⌘O</MenubarShortcut></MenubarItem>
+ *       <MenubarSeparator />
+ *       <MenubarItem>Exit</MenubarItem>
+ *     </MenubarContent>
+ *   </MenubarMenu>
+ *   <MenubarMenu>
+ *     <MenubarTrigger>Edit</MenubarTrigger>
+ *     <MenubarContent>
+ *       <MenubarItem>Undo <MenubarShortcut>⌘Z</MenubarShortcut></MenubarItem>
+ *       <MenubarItem>Redo <MenubarShortcut>⇧⌘Z</MenubarShortcut></MenubarItem>
+ *     </MenubarContent>
+ *   </MenubarMenu>
+ * </Menubar>
+ * ```
+ * 
+ * @example
+ * ```tsx
+ * // With checkboxes and submenus
+ * <Menubar>
+ *   <MenubarMenu>
+ *     <MenubarTrigger>View</MenubarTrigger>
+ *     <MenubarContent>
+ *       <MenubarCheckboxItem checked={showToolbar} onCheckedChange={setShowToolbar}>
+ *         Show Toolbar
+ *       </MenubarCheckboxItem>
+ *       <MenubarSeparator />
+ *       <MenubarSub>
+ *         <MenubarSubTrigger>Panels</MenubarSubTrigger>
+ *         <MenubarSubContent>
+ *           <MenubarItem>Explorer</MenubarItem>
+ *           <MenubarItem>Terminal</MenubarItem>
+ *         </MenubarSubContent>
+ *       </MenubarSub>
+ *     </MenubarContent>
+ *   </MenubarMenu>
+ * </Menubar>
+ * ```
+ * 
+ * @example
+ * ```tsx
+ * // With radio groups for exclusive selections
+ * <Menubar>
+ *   <MenubarMenu>
+ *     <MenubarTrigger>Theme</MenubarTrigger>
+ *     <MenubarContent>
+ *       <MenubarRadioGroup value={theme} onValueChange={setTheme}>
+ *         <MenubarRadioItem value="light">Light</MenubarRadioItem>
+ *         <MenubarRadioItem value="dark">Dark</MenubarRadioItem>
+ *         <MenubarRadioItem value="system">System</MenubarRadioItem>
+ *       </MenubarRadioGroup>
+ *     </MenubarContent>
+ *   </MenubarMenu>
+ * </Menubar>
+ * ```
+ * 
+ * @accessibility
+ * - Follows WAI-ARIA menubar pattern
+ * - Left/Right arrow keys navigate between menu triggers
+ * - Up/Down arrow keys navigate within menu content
+ * - Enter or Space activates menu items
+ * - Escape closes open menus
+ * - Tab moves focus to next focusable element outside menubar
+ * - Full keyboard navigation with arrow keys, Enter, and Escape
+ * - Screen reader support with proper ARIA labels and roles
+ * 
+ * @see {@link https://www.w3.org/WAI/ARIA/apg/patterns/menubar/} ARIA Menubar Pattern
+ * @see {@link https://ui.shadcn.com/docs/components/menubar} shadcn/ui Menubar Documentation
+ * @since 1.0.0
+ */
+/**
+ * Root container for the menubar component.
+ * 
+ * @param className - Additional CSS classes to apply
+ * @param props - All props from Radix UI Menubar Root
+ */
+function Menubar({
+  className,
+  ...props
+}: React.ComponentProps<typeof MenubarPrimitive.Root>) {
+  return (
+    <MenubarPrimitive.Root
+      data-slot="menubar"
+      className={cn(
+        "bg-background flex h-9 items-center gap-1 rounded-md border p-1 shadow-xs",
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+
+/**
+ * Container for a single menu within the menubar.
+ *
+ * Each MenubarMenu represents one dropdown menu that can be triggered
+ * by its corresponding MenubarTrigger.
+ *
+ * @param props - All props from Radix UI Menubar Menu
+ */
+function MenubarMenu({
+  ...props
+}: React.ComponentProps<typeof MenubarPrimitive.Menu>) {
+  return <MenubarPrimitive.Menu data-slot="menubar-menu" {...props} />;
+}
+
+/**
+ * Groups related menu items together within MenubarContent.
+ *
+ * Used to create logical groupings of menu items, often separated
+ * by MenubarSeparator components.
+ *
+ * @param props - All props from Radix UI Menubar Group
+ */
+function MenubarGroup({
+  ...props
+}: React.ComponentProps<typeof MenubarPrimitive.Group>) {
+  return <MenubarPrimitive.Group data-slot="menubar-group" {...props} />;
+}
+
+/**
+ * Portal for rendering menu content outside the DOM hierarchy.
+ *
+ * Automatically used by MenubarContent to ensure proper layering
+ * and positioning of dropdown menus.
+ *
+ * @param props - All props from Radix UI Menubar Portal
+ */
+function MenubarPortal({
+  ...props
+}: React.ComponentProps<typeof MenubarPrimitive.Portal>) {
+  return <MenubarPrimitive.Portal data-slot="menubar-portal" {...props} />;
+}
+
+/**
+ * Container for mutually exclusive radio items.
+ *
+ * Use for single-selection scenarios like theme selection,
+ * view modes, or other settings where only one option can be active.
+ *
+ * @param props - All props from Radix UI Menubar RadioGroup
+ * @example
+ * ```tsx
+ * <MenubarRadioGroup value={theme} onValueChange={setTheme}>
+ *   <MenubarRadioItem value="light">Light</MenubarRadioItem>
+ *   <MenubarRadioItem value="dark">Dark</MenubarRadioItem>
+ * </MenubarRadioGroup>
+ * ```
+ */
+function MenubarRadioGroup({
+  ...props
+}: React.ComponentProps<typeof MenubarPrimitive.RadioGroup>) {
+  return (
+    <MenubarPrimitive.RadioGroup data-slot="menubar-radio-group" {...props} />
+  );
+}
+
+/**
+ * Button that opens a dropdown menu.
+ *
+ * The trigger text should be concise and descriptive of the menu contents.
+ * Common patterns include "File", "Edit", "View", "Tools", "Help".
+ *
+ * @param className - Additional CSS classes to apply
+ * @param props - All props from Radix UI Menubar Trigger
+ */
+function MenubarTrigger({
+  className,
+  ...props
+}: React.ComponentProps<typeof MenubarPrimitive.Trigger>) {
+  return (
+    <MenubarPrimitive.Trigger
+      data-slot="menubar-trigger"
+      className={cn(
+        "focus:bg-accent focus:text-accent-foreground data-[state=open]:bg-accent data-[state=open]:text-accent-foreground flex items-center rounded-sm px-2 py-1 text-sm font-medium outline-hidden select-none",
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+
+/**
+ * Dropdown content container for menu items.
+ *
+ * Contains the actual menu items, separators, and submenus that appear
+ * when a MenubarTrigger is activated.
+ *
+ * @param className - Additional CSS classes to apply
+ * @param align - Alignment relative to trigger (start, center, end)
+ * @param alignOffset - Offset from the aligned position
+ * @param sideOffset - Distance from the trigger
+ * @param props - All props from Radix UI Menubar Content
+ */
+function MenubarContent({
+  className,
+  align = "start",
+  alignOffset = -4,
+  sideOffset = 8,
+  ...props
+}: React.ComponentProps<typeof MenubarPrimitive.Content>) {
+  return (
+    <MenubarPortal>
+      <MenubarPrimitive.Content
+        data-slot="menubar-content"
+        align={align}
+        alignOffset={alignOffset}
+        sideOffset={sideOffset}
+        className={cn(
+          "bg-popover text-popover-foreground data-[state=open]:animate-in 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-[12rem] origin-(--radix-menubar-content-transform-origin) overflow-hidden rounded-md border p-1 shadow-md",
+          className,
+        )}
+        {...props}
+      />
+    </MenubarPortal>
+  );
+}
+
+/**
+ * A selectable menu item within MenubarContent.
+ *
+ * Can be enhanced with icons, keyboard shortcuts, and supports
+ * different variants including destructive actions.
+ *
+ * @param className - Additional CSS classes to apply
+ * @param inset - Whether to add left padding for alignment with items that have icons
+ * @param variant - Visual variant ("default" | "destructive")
+ * @param props - All props from Radix UI Menubar Item
+ * @example
+ * ```tsx
+ * <MenubarItem variant="destructive">
+ *   Delete File
+ *   <MenubarShortcut>⌫</MenubarShortcut>
+ * </MenubarItem>
+ * ```
+ */
+function MenubarItem({
+  className,
+  inset,
+  variant = "default",
+  ...props
+}: React.ComponentProps<typeof MenubarPrimitive.Item> & {
+  inset?: boolean;
+  variant?: "default" | "destructive";
+}) {
+  return (
+    <MenubarPrimitive.Item
+      data-slot="menubar-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 menu item that can be checked/unchecked.
+ *
+ * Perfect for toggle options like "Show Toolbar", "Enable Feature",
+ * or any binary setting that can be turned on/off.
+ *
+ * @param className - Additional CSS classes to apply
+ * @param children - The content of the checkbox item
+ * @param checked - Whether the item is checked
+ * @param props - All props from Radix UI Menubar CheckboxItem including onCheckedChange
+ * @example
+ * ```tsx
+ * <MenubarCheckboxItem checked={showToolbar} onCheckedChange={setShowToolbar}>
+ *   Show Toolbar
+ * </MenubarCheckboxItem>
+ * ```
+ */
+function MenubarCheckboxItem({
+  className,
+  children,
+  checked,
+  ...props
+}: React.ComponentProps<typeof MenubarPrimitive.CheckboxItem>) {
+  return (
+    <MenubarPrimitive.CheckboxItem
+      data-slot="menubar-checkbox-item"
+      className={cn(
+        "focus:bg-accent focus:text-accent-foreground relative flex cursor-default items-center gap-2 rounded-xs 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">
+        <MenubarPrimitive.ItemIndicator>
+          <CheckIcon className="size-4" />
+        </MenubarPrimitive.ItemIndicator>
+      </span>
+      {children}
+    </MenubarPrimitive.CheckboxItem>
+  );
+}
+
+/**
+ * A menu item for single selection within a MenubarRadioGroup.
+ *
+ * Use within MenubarRadioGroup for mutually exclusive options.
+ * Only one radio item can be selected at a time within the group.
+ *
+ * @param className - Additional CSS classes to apply
+ * @param children - The content of the radio item
+ * @param props - All props from Radix UI Menubar RadioItem including value
+ * @example
+ * ```tsx
+ * <MenubarRadioItem value="dark">Dark Theme</MenubarRadioItem>
+ * ```
+ */
+function MenubarRadioItem({
+  className,
+  children,
+  ...props
+}: React.ComponentProps<typeof MenubarPrimitive.RadioItem>) {
+  return (
+    <MenubarPrimitive.RadioItem
+      data-slot="menubar-radio-item"
+      className={cn(
+        "focus:bg-accent focus:text-accent-foreground relative flex cursor-default items-center gap-2 rounded-xs 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">
+        <MenubarPrimitive.ItemIndicator>
+          <CircleIcon className="size-2 fill-current" />
+        </MenubarPrimitive.ItemIndicator>
+      </span>
+      {children}
+    </MenubarPrimitive.RadioItem>
+  );
+}
+
+/**
+ * A non-interactive label for grouping menu items.
+ *
+ * Used to provide section headings within menu content,
+ * helping users understand the organization of menu items.
+ *
+ * @param className - Additional CSS classes to apply
+ * @param inset - Whether to add left padding for alignment with items that have icons
+ * @param props - All props from Radix UI Menubar Label
+ * @example
+ * ```tsx
+ * <MenubarLabel>Recent Files</MenubarLabel>
+ * <MenubarSeparator />
+ * ```
+ */
+function MenubarLabel({
+  className,
+  inset,
+  ...props
+}: React.ComponentProps<typeof MenubarPrimitive.Label> & {
+  inset?: boolean;
+}) {
+  return (
+    <MenubarPrimitive.Label
+      data-slot="menubar-label"
+      data-inset={inset}
+      className={cn(
+        "px-2 py-1.5 text-sm font-medium data-[inset]:pl-8",
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+
+/**
+ * A visual divider between menu items.
+ *
+ * Use to create logical groupings and improve visual hierarchy
+ * within menu content.
+ *
+ * @param className - Additional CSS classes to apply
+ * @param props - All props from Radix UI Menubar Separator
+ */
+function MenubarSeparator({
+  className,
+  ...props
+}: React.ComponentProps<typeof MenubarPrimitive.Separator>) {
+  return (
+    <MenubarPrimitive.Separator
+      data-slot="menubar-separator"
+      className={cn("bg-border -mx-1 my-1 h-px", className)}
+      {...props}
+    />
+  );
+}
+
+/**
+ * Displays keyboard shortcut for a menu item.
+ *
+ * Shows keyboard shortcuts aligned to the right of menu items.
+ * Use standard platform conventions (⌘ for Mac, Ctrl+ for Windows/Linux).
+ *
+ * @param className - Additional CSS classes to apply
+ * @param props - All props from HTML span element
+ * @example
+ * ```tsx
+ * <MenubarItem>
+ *   Save File
+ *   <MenubarShortcut>⌘S</MenubarShortcut>
+ * </MenubarItem>
+ * ```
+ */
+function MenubarShortcut({
+  className,
+  ...props
+}: React.ComponentProps<"span">) {
+  return (
+    <span
+      data-slot="menubar-shortcut"
+      className={cn(
+        "text-muted-foreground ml-auto text-xs tracking-widest",
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+
+/**
+ * Container for a submenu.
+ *
+ * Wraps MenubarSubTrigger and MenubarSubContent to create
+ * nested menu structures.
+ *
+ * @param props - All props from Radix UI Menubar Sub
+ * @example
+ * ```tsx
+ * <MenubarSub>
+ *   <MenubarSubTrigger>Export</MenubarSubTrigger>
+ *   <MenubarSubContent>
+ *     <MenubarItem>Export as PDF</MenubarItem>
+ *     <MenubarItem>Export as CSV</MenubarItem>
+ *   </MenubarSubContent>
+ * </MenubarSub>
+ * ```
+ */
+function MenubarSub({
+  ...props
+}: React.ComponentProps<typeof MenubarPrimitive.Sub>) {
+  return <MenubarPrimitive.Sub data-slot="menubar-sub" {...props} />;
+}
+
+/**
+ * Menu item that opens a submenu.
+ *
+ * Automatically includes a right arrow indicator to show
+ * that it opens a submenu when hovered or focused.
+ *
+ * @param className - Additional CSS classes to apply
+ * @param inset - Whether to add left padding for alignment with items that have icons
+ * @param children - The content of the sub-trigger
+ * @param props - All props from Radix UI Menubar SubTrigger
+ */
+function MenubarSubTrigger({
+  className,
+  inset,
+  children,
+  ...props
+}: React.ComponentProps<typeof MenubarPrimitive.SubTrigger> & {
+  inset?: boolean;
+}) {
+  return (
+    <MenubarPrimitive.SubTrigger
+      data-slot="menubar-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-none select-none data-[inset]:pl-8",
+        className,
+      )}
+      {...props}
+    >
+      {children}
+      <ChevronRightIcon className="ml-auto h-4 w-4" />
+    </MenubarPrimitive.SubTrigger>
+  );
+}
+
+/**
+ * Content container for a submenu.
+ *
+ * Contains the menu items that appear when a MenubarSubTrigger
+ * is hovered or focused. Supports all the same content as MenubarContent.
+ *
+ * @param className - Additional CSS classes to apply
+ * @param props - All props from Radix UI Menubar SubContent
+ */
+function MenubarSubContent({
+  className,
+  ...props
+}: React.ComponentProps<typeof MenubarPrimitive.SubContent>) {
+  return (
+    <MenubarPrimitive.SubContent
+      data-slot="menubar-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-menubar-content-transform-origin) overflow-hidden rounded-md border p-1 shadow-lg",
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+
+export {
+  Menubar,
+  MenubarPortal,
+  MenubarMenu,
+  MenubarTrigger,
+  MenubarContent,
+  MenubarGroup,
+  MenubarSeparator,
+  MenubarLabel,
+  MenubarItem,
+  MenubarShortcut,
+  MenubarCheckboxItem,
+  MenubarRadioGroup,
+  MenubarRadioItem,
+  MenubarSub,
+  MenubarSubTrigger,
+  MenubarSubContent,
+};