@neynar/ui 1.0.0 → 1.0.2

package/llm/components/menubar.llm.md

@@ -0,0 +1,378 @@
+# Menubar
+
+Horizontal menubar for application-level navigation and actions, commonly seen in desktop applications with File, Edit, View, and Help menus.
+
+## Import
+
+```tsx
+import {
+  Menubar,
+  MenubarMenu,
+  MenubarTrigger,
+  MenubarContent,
+  MenubarItem,
+  MenubarSeparator,
+  MenubarShortcut,
+  MenubarCheckboxItem,
+  MenubarRadioGroup,
+  MenubarRadioItem,
+  MenubarSub,
+  MenubarSubTrigger,
+  MenubarSubContent,
+  MenubarLabel,
+  MenubarGroup,
+} from "@neynar/ui/menubar"
+```
+
+## Anatomy
+
+```tsx
+<Menubar>
+  <MenubarMenu>
+    <MenubarTrigger>File</MenubarTrigger>
+    <MenubarContent>
+      <MenubarItem>New</MenubarItem>
+      <MenubarItem>Open</MenubarItem>
+      <MenubarSeparator />
+      <MenubarSub>
+        <MenubarSubTrigger>Export</MenubarSubTrigger>
+        <MenubarSubContent>
+          <MenubarItem>PDF</MenubarItem>
+          <MenubarItem>CSV</MenubarItem>
+        </MenubarSubContent>
+      </MenubarSub>
+    </MenubarContent>
+  </MenubarMenu>
+  <MenubarMenu>
+    <MenubarTrigger>Edit</MenubarTrigger>
+    <MenubarContent>
+      <MenubarItem>Undo</MenubarItem>
+      <MenubarItem>Redo</MenubarItem>
+    </MenubarContent>
+  </MenubarMenu>
+</Menubar>
+```
+
+## Components
+
+| Component | Description |
+|-----------|-------------|
+| Menubar | Root container for the horizontal menubar |
+| MenubarMenu | Individual menu within the menubar (manages open/close state) |
+| MenubarTrigger | Button that opens the menu dropdown |
+| MenubarContent | Dropdown panel containing menu items (auto-portals) |
+| MenubarItem | Interactive menu item with optional variants |
+| MenubarCheckboxItem | Menu item with checkbox for toggles |
+| MenubarRadioGroup | Container for mutually exclusive radio items |
+| MenubarRadioItem | Radio button menu item (use inside MenubarRadioGroup) |
+| MenubarSub | Container for nested submenu |
+| MenubarSubTrigger | Menu item that opens a submenu |
+| MenubarSubContent | Dropdown panel for submenu items |
+| MenubarGroup | Logical grouping of menu items |
+| MenubarLabel | Non-interactive section label |
+| MenubarSeparator | Visual divider between items |
+| MenubarShortcut | Keyboard shortcut hint (display only) |
+
+## Props
+
+### Menubar
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| loopFocus | boolean | true | Loop keyboard focus back to first item at end of list |
+| modal | boolean | true | Whether menubar is modal |
+| disabled | boolean | false | Disable entire menubar |
+| orientation | "horizontal" \| "vertical" | "horizontal" | Menubar orientation |
+| className | string | - | Additional CSS classes |
+
+### MenubarMenu
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| open | boolean | - | Controlled open state |
+| defaultOpen | boolean | - | Default open state (uncontrolled) |
+| onOpenChange | (open: boolean) => void | - | Callback when open state changes |
+
+### MenubarContent
+
+Automatically renders in a portal with backdrop blur (frosted glass effect).
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| align | "start" \| "center" \| "end" | "start" | Alignment relative to trigger |
+| alignOffset | number | -4 | Offset along alignment axis |
+| side | "top" \| "right" \| "bottom" \| "left" | "bottom" | Preferred side of trigger |
+| sideOffset | number | 8 | Distance from trigger |
+
+### MenubarItem
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| disabled | boolean | false | Disable item |
+| onClick | MouseEventHandler | - | Click handler |
+| closeOnClick | boolean | true | Close menu on click |
+| variant | "default" \| "destructive" \| "success" \| "warning" \| "info" | "default" | Visual variant |
+| inset | boolean | false | Add left padding for alignment with icons/checkboxes |
+
+### MenubarCheckboxItem
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| checked | boolean | - | Controlled checked state |
+| defaultChecked | boolean | - | Default checked state (uncontrolled) |
+| onCheckedChange | (checked: boolean) => void | - | Callback when checked state changes |
+| disabled | boolean | false | Disable item |
+
+### MenubarRadioGroup
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| value | any | - | Controlled selected value |
+| defaultValue | any | - | Default selected value (uncontrolled) |
+| onValueChange | (value: any) => void | - | Callback when value changes |
+
+### MenubarRadioItem
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| value | any | **required** | Value when this item is selected |
+| disabled | boolean | false | Disable item |
+
+### MenubarSubTrigger
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| disabled | boolean | false | Disable submenu trigger |
+| inset | boolean | false | Add left padding for alignment |
+
+## Data Attributes
+
+### MenubarTrigger
+- `aria-expanded` - Present when menu is open
+
+### MenubarItem
+- `data-highlighted` - Present when item is highlighted
+- `data-disabled` - Present when item is disabled
+
+### MenubarCheckboxItem
+- `data-checked` - Present when checked
+- `data-disabled` - Present when disabled
+
+### MenubarRadioItem
+- `data-checked` - Present when selected
+- `data-disabled` - Present when disabled
+
+## Variants
+
+MenubarItem supports semantic variants:
+
+| Variant | Use Case |
+|---------|----------|
+| default | Standard menu actions |
+| destructive | Dangerous actions (delete, sign out) |
+| success | Positive actions (approve, confirm) |
+| warning | Caution actions (mark for review) |
+| info | Informational actions (view details) |
+
+## Examples
+
+### Basic Menubar
+
+```tsx
+<Menubar>
+  <MenubarMenu>
+    <MenubarTrigger>File</MenubarTrigger>
+    <MenubarContent>
+      <MenubarItem>New</MenubarItem>
+      <MenubarItem>Open</MenubarItem>
+      <MenubarItem>Save</MenubarItem>
+    </MenubarContent>
+  </MenubarMenu>
+
+  <MenubarMenu>
+    <MenubarTrigger>Edit</MenubarTrigger>
+    <MenubarContent>
+      <MenubarItem>Undo</MenubarItem>
+      <MenubarItem>Redo</MenubarItem>
+    </MenubarContent>
+  </MenubarMenu>
+</Menubar>
+```
+
+### With Icons and Shortcuts
+
+```tsx
+<Menubar>
+  <MenubarMenu>
+    <MenubarTrigger>File</MenubarTrigger>
+    <MenubarContent>
+      <MenubarItem>
+        <FileIcon />
+        New File
+        <MenubarShortcut>⌘N</MenubarShortcut>
+      </MenubarItem>
+      <MenubarItem>
+        <FolderOpenIcon />
+        Open
+        <MenubarShortcut>⌘O</MenubarShortcut>
+      </MenubarItem>
+      <MenubarSeparator />
+      <MenubarItem>
+        <SaveIcon />
+        Save
+        <MenubarShortcut>⌘S</MenubarShortcut>
+      </MenubarItem>
+    </MenubarContent>
+  </MenubarMenu>
+</Menubar>
+```
+
+### Checkbox Items (View Settings)
+
+```tsx
+function ViewMenu() {
+  const [showSidebar, setShowSidebar] = useState(true)
+  const [showToolbar, setShowToolbar] = useState(true)
+
+  return (
+    <MenubarMenu>
+      <MenubarTrigger>View</MenubarTrigger>
+      <MenubarContent>
+        <MenubarGroup>
+          <MenubarLabel>Panels</MenubarLabel>
+          <MenubarCheckboxItem
+            checked={showSidebar}
+            onCheckedChange={setShowSidebar}
+          >
+            Sidebar
+          </MenubarCheckboxItem>
+          <MenubarCheckboxItem
+            checked={showToolbar}
+            onCheckedChange={setShowToolbar}
+          >
+            Toolbar
+          </MenubarCheckboxItem>
+        </MenubarGroup>
+      </MenubarContent>
+    </MenubarMenu>
+  )
+}
+```
+
+### Radio Group (Theme Selection)
+
+```tsx
+function ThemeMenu() {
+  const [theme, setTheme] = useState("system")
+
+  return (
+    <MenubarSub>
+      <MenubarSubTrigger>
+        <SunIcon />
+        Theme
+      </MenubarSubTrigger>
+      <MenubarSubContent>
+        <MenubarRadioGroup value={theme} onValueChange={setTheme}>
+          <MenubarRadioItem value="light">
+            <SunIcon />
+            Light
+          </MenubarRadioItem>
+          <MenubarRadioItem value="dark">
+            <MoonIcon />
+            Dark
+          </MenubarRadioItem>
+          <MenubarRadioItem value="system">
+            <MonitorIcon />
+            System
+          </MenubarRadioItem>
+        </MenubarRadioGroup>
+      </MenubarSubContent>
+    </MenubarSub>
+  )
+}
+```
+
+### Nested Submenus
+
+```tsx
+<MenubarMenu>
+  <MenubarTrigger>File</MenubarTrigger>
+  <MenubarContent>
+    <MenubarItem>New File</MenubarItem>
+    <MenubarSub>
+      <MenubarSubTrigger>
+        <DownloadIcon />
+        Export
+      </MenubarSubTrigger>
+      <MenubarSubContent>
+        <MenubarItem>Export as JSON</MenubarItem>
+        <MenubarItem>Export as CSV</MenubarItem>
+        <MenubarSeparator />
+        <MenubarSub>
+          <MenubarSubTrigger>More Formats</MenubarSubTrigger>
+          <MenubarSubContent>
+            <MenubarItem>YAML</MenubarItem>
+            <MenubarItem>TOML</MenubarItem>
+          </MenubarSubContent>
+        </MenubarSub>
+      </MenubarSubContent>
+    </MenubarSub>
+  </MenubarContent>
+</MenubarMenu>
+```
+
+### Item Variants
+
+```tsx
+<MenubarMenu>
+  <MenubarTrigger>Actions</MenubarTrigger>
+  <MenubarContent>
+    <MenubarItem variant="success">
+      <CheckCircleIcon />
+      Approve
+    </MenubarItem>
+    <MenubarItem variant="warning">
+      <AlertTriangleIcon />
+      Mark for Review
+    </MenubarItem>
+    <MenubarItem variant="info">
+      <InfoIcon />
+      View Details
+    </MenubarItem>
+    <MenubarSeparator />
+    <MenubarItem variant="destructive">
+      <LogOutIcon />
+      Sign Out
+    </MenubarItem>
+  </MenubarContent>
+</MenubarMenu>
+```
+
+## Keyboard Navigation
+
+| Key | Action |
+|-----|--------|
+| Tab | Move focus to next menubar trigger |
+| Shift+Tab | Move focus to previous menubar trigger |
+| Enter/Space | Open menu or activate item |
+| Arrow Down | Open menu or move to next item |
+| Arrow Up | Move to previous item |
+| Arrow Right | Move to next menubar trigger (or open submenu) |
+| Arrow Left | Move to previous menubar trigger (or close submenu) |
+| Escape | Close open menu |
+| Home | Focus first item |
+| End | Focus last item |
+
+## Accessibility
+
+- Full keyboard navigation with arrow keys and Tab
+- ARIA attributes automatically managed (aria-expanded, aria-haspopup, role="menubar")
+- Focus management with automatic focus trapping in open menus
+- Screen reader announcements for menu state changes
+- Supports `disabled` state with proper ARIA attributes
+
+## Related
+
+- [DropdownMenu](./dropdown-menu.llm.md) - For single-menu dropdowns
+- [ContextMenu](./context-menu.llm.md) - For right-click menus
+- [NavigationMenu](./navigation-menu.llm.md) - For site navigation with links

package/llm/components/navigation-menu.llm.md

@@ -0,0 +1,320 @@
+# NavigationMenu
+
+Horizontal navigation menu with mega menu support for main site navigation and dashboard headers.
+
+## Import
+
+```tsx
+import {
+  NavigationMenu,
+  NavigationMenuList,
+  NavigationMenuItem,
+  NavigationMenuTrigger,
+  NavigationMenuContent,
+  NavigationMenuLink,
+} from "@neynar/ui/navigation-menu"
+```
+
+## Anatomy
+
+```tsx
+<NavigationMenu>
+  <NavigationMenuList>
+    <NavigationMenuItem value="item-1">
+      <NavigationMenuTrigger>Products</NavigationMenuTrigger>
+      <NavigationMenuContent>
+        {/* Mega menu content */}
+      </NavigationMenuContent>
+    </NavigationMenuItem>
+
+    <NavigationMenuItem value="item-2">
+      <NavigationMenuLink href="/pricing">Pricing</NavigationMenuLink>
+    </NavigationMenuItem>
+  </NavigationMenuList>
+</NavigationMenu>
+```
+
+## Components
+
+| Component | Description |
+|-----------|-------------|
+| NavigationMenu | Root container, manages active state and keyboard navigation |
+| NavigationMenuList | Container for navigation items, renders as horizontal list |
+| NavigationMenuItem | Individual item, can contain Link or Trigger + Content |
+| NavigationMenuTrigger | Button that opens content panel, includes chevron icon |
+| NavigationMenuContent | Mega menu content panel with smooth transitions |
+| NavigationMenuLink | Clickable link for direct navigation or panel content |
+| NavigationMenuIndicator | Optional visual indicator (rarely used) |
+
+## Props
+
+### NavigationMenu
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| value | string | - | Controlled active item value |
+| defaultValue | string | - | Default active item (uncontrolled) |
+| onValueChange | (value: string) => void | - | Called when active item changes |
+| orientation | "horizontal" \| "vertical" | "horizontal" | Menu orientation |
+| className | string | - | Additional CSS classes |
+
+### NavigationMenuItem
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| value | string | - | Unique identifier for controlled state |
+| className | string | - | Additional CSS classes |
+
+### NavigationMenuTrigger
+
+Automatically includes a rotating chevron icon that animates on open/close.
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| className | string | - | Additional CSS classes |
+| render | ReactElement | - | Custom render element |
+
+### NavigationMenuContent
+
+Automatically renders in a positioned portal with backdrop and smooth transitions.
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| className | string | - | Additional CSS classes |
+
+### NavigationMenuLink
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| href | string | - | Link destination |
+| active | boolean | false | Highlights link as active/current page |
+| closeOnClick | boolean | true | Whether to close menu on click |
+| className | string | - | Additional CSS classes |
+
+### NavigationMenuList
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| className | string | - | Additional CSS classes |
+
+## Data Attributes
+
+### NavigationMenuTrigger
+
+| Attribute | When Present |
+|-----------|--------------|
+| data-open | Content panel is open |
+| data-popup-open | Content panel is open |
+| data-pressed | Trigger is pressed |
+
+### NavigationMenuContent
+
+| Attribute | When Present |
+|-----------|--------------|
+| data-open | Content is visible |
+| data-closed | Content is hidden |
+| data-starting-style | During opening animation |
+| data-ending-style | During closing animation |
+
+### NavigationMenuLink
+
+| Attribute | When Present |
+|-----------|--------------|
+| data-active | Link is active/current page |
+
+## Examples
+
+### Basic Link Navigation
+
+```tsx
+<NavigationMenu>
+  <NavigationMenuList>
+    <NavigationMenuItem value="home">
+      <NavigationMenuLink href="/">Home</NavigationMenuLink>
+    </NavigationMenuItem>
+    <NavigationMenuItem value="about">
+      <NavigationMenuLink href="/about">About</NavigationMenuLink>
+    </NavigationMenuItem>
+    <NavigationMenuItem value="contact">
+      <NavigationMenuLink href="/contact">Contact</NavigationMenuLink>
+    </NavigationMenuItem>
+  </NavigationMenuList>
+</NavigationMenu>
+```
+
+### Mega Menu with Product Showcase
+
+```tsx
+<NavigationMenu>
+  <NavigationMenuList>
+    <NavigationMenuItem value="products">
+      <NavigationMenuTrigger>Products</NavigationMenuTrigger>
+      <NavigationMenuContent>
+        <div className="w-[600px] p-4">
+          <div className="mb-4">
+            <h4 className="font-semibold">Our Products</h4>
+            <p className="text-muted-foreground text-sm">
+              Everything you need to build on Farcaster
+            </p>
+          </div>
+          <div className="grid grid-cols-2 gap-4">
+            <NavigationMenuLink href="/api" className="block rounded-md">
+              <div className="flex items-start gap-3">
+                <div className="bg-primary/10 text-primary rounded-md p-2">
+                  <CodeIcon className="size-5" />
+                </div>
+                <div>
+                  <div className="font-medium">Farcaster API</div>
+                  <div className="text-muted-foreground text-xs">
+                    REST APIs for casts, users, and feeds
+                  </div>
+                </div>
+              </div>
+            </NavigationMenuLink>
+            {/* More product cards */}
+          </div>
+        </div>
+      </NavigationMenuContent>
+    </NavigationMenuItem>
+  </NavigationMenuList>
+</NavigationMenu>
+```
+
+### Grouped Content Panels
+
+```tsx
+<NavigationMenu>
+  <NavigationMenuList>
+    <NavigationMenuItem value="resources">
+      <NavigationMenuTrigger>Resources</NavigationMenuTrigger>
+      <NavigationMenuContent>
+        <div className="grid w-[400px] grid-cols-2 gap-4 p-4">
+          <div className="space-y-3">
+            <h4 className="text-muted-foreground text-xs font-semibold uppercase">
+              Documentation
+            </h4>
+            <div className="space-y-2">
+              <NavigationMenuLink href="/docs" className="block">
+                Getting Started
+              </NavigationMenuLink>
+              <NavigationMenuLink href="/api-reference" className="block">
+                API Reference
+              </NavigationMenuLink>
+            </div>
+          </div>
+          <div className="space-y-3">
+            <h4 className="text-muted-foreground text-xs font-semibold uppercase">
+              Community
+            </h4>
+            <div className="space-y-2">
+              <NavigationMenuLink href="/discord" className="block">
+                Discord
+              </NavigationMenuLink>
+              <NavigationMenuLink href="/github" className="block">
+                GitHub
+              </NavigationMenuLink>
+            </div>
+          </div>
+        </div>
+      </NavigationMenuContent>
+    </NavigationMenuItem>
+  </NavigationMenuList>
+</NavigationMenu>
+```
+
+### With Icons
+
+```tsx
+<NavigationMenu>
+  <NavigationMenuList>
+    <NavigationMenuItem value="home">
+      <NavigationMenuLink href="/" className="flex items-center gap-2">
+        <HomeIcon className="size-4" />
+        Home
+      </NavigationMenuLink>
+    </NavigationMenuItem>
+    <NavigationMenuItem value="apps">
+      <NavigationMenuTrigger>
+        <LayoutDashboardIcon className="mr-2 size-4" />
+        Apps
+      </NavigationMenuTrigger>
+      <NavigationMenuContent>
+        <div className="w-[280px] space-y-2 p-4">
+          <NavigationMenuLink href="/my-apps" className="flex items-center gap-2">
+            <RocketIcon className="size-4" />
+            My Apps
+          </NavigationMenuLink>
+          <NavigationMenuLink href="/templates" className="flex items-center gap-2">
+            <PackageIcon className="size-4" />
+            Templates
+          </NavigationMenuLink>
+        </div>
+      </NavigationMenuContent>
+    </NavigationMenuItem>
+  </NavigationMenuList>
+</NavigationMenu>
+```
+
+### Active State
+
+```tsx
+function Nav({ currentPath }: { currentPath: string }) {
+  return (
+    <NavigationMenu>
+      <NavigationMenuList>
+        <NavigationMenuItem value="dashboard">
+          <NavigationMenuLink
+            href="/dashboard"
+            active={currentPath === "/dashboard"}
+          >
+            Dashboard
+          </NavigationMenuLink>
+        </NavigationMenuItem>
+        <NavigationMenuItem value="analytics">
+          <NavigationMenuLink
+            href="/analytics"
+            active={currentPath === "/analytics"}
+          >
+            Analytics
+          </NavigationMenuLink>
+        </NavigationMenuItem>
+      </NavigationMenuList>
+    </NavigationMenu>
+  )
+}
+```
+
+## Keyboard Navigation
+
+| Key | Action |
+|-----|--------|
+| Tab | Move focus to next item |
+| Shift + Tab | Move focus to previous item |
+| Arrow Right | Focus next item (horizontal) |
+| Arrow Left | Focus previous item (horizontal) |
+| Enter / Space | Activate trigger or link |
+| Escape | Close open content panel |
+| Home | Focus first item |
+| End | Focus last item |
+
+## Accessibility
+
+- Implements ARIA navigation menu pattern with proper roles and states
+- Keyboard navigation follows WAI-ARIA authoring practices
+- Focus management automatically moves between items and panels
+- Screen readers announce active states and panel open/close
+
+## Styling Notes
+
+- Content panel width is controlled by content wrapper (e.g., `w-[600px]`)
+- Use grid layouts for multi-column mega menus
+- Icons automatically size to `size-4` when not explicitly sized
+- Active links receive muted background by default
+- Smooth transitions use cubic-bezier easing for polish
+
+## Related
+
+- [Tabs](/components/tabs) - For tabbed content switching
+- [DropdownMenu](/components/dropdown-menu) - For action menus
+- [Command](/components/command) - For command palettes
+- [Breadcrumb](/components/breadcrumb) - For hierarchical navigation