@neynar/ui 0.3.0 → 0.4.0

package/.llm/context-menu-content.llm.md

@@ -0,0 +1,91 @@
+# ContextMenuContent
+
+**Type**: component
+
+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.
+
+## JSX Usage
+
+```jsx
+import { ContextMenuContent } from '@neynar/ui';
+
+<ContextMenuContent
+  asChild={true}
+  loop={true}
+  onCloseAutoFocus={handleCloseAutoFocus}
+  onEscapeKeyDown={handleEscapeKeyDown}
+  avoidCollisions={true}
+  sideOffset={0}
+  className="value"
+>
+  {/* Your content here */}
+</ContextMenuContent>
+```
+
+## Component Props
+
+### asChild
+- **Type**: `boolean`
+- **Required**: No
+- **Description**: Merges props with child element instead of rendering wrapper
+
+### loop
+- **Type**: `boolean`
+- **Required**: No
+- **Description**: Enable keyboard navigation looping from last to first item
+
+### onCloseAutoFocus
+- **Type**: `(event: Event) => void`
+- **Required**: No
+- **Description**: Handle focus return when menu closes
+
+### onEscapeKeyDown
+- **Type**: `(event: KeyboardEvent) => void`
+- **Required**: No
+- **Description**: Handle escape key presses
+
+### avoidCollisions
+- **Type**: `boolean`
+- **Required**: No
+- **Description**: Prevent collisions with viewport boundaries
+
+### sideOffset
+- **Type**: `number`
+- **Required**: No
+- **Description**: Distance in pixels from the cursor/trigger point
+
+### className
+- **Type**: `string`
+- **Required**: No
+- **Description**: Additional CSS classes for styling
+
+### children
+- **Type**: `React.ReactNode`
+- **Required**: Yes
+- **Description**: Menu items, labels, separators, and sub-menus to display
+
+## Examples
+
+### Example 1
+```tsx
+<ContextMenuContent className="w-56">
+  <ContextMenuLabel>Actions</ContextMenuLabel>
+  <ContextMenuSeparator />
+  <ContextMenuItem>Copy</ContextMenuItem>
+  <ContextMenuItem>Paste</ContextMenuItem>
+</ContextMenuContent>
+```
+### Example 2
+```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>
+```

package/.llm/context-menu-group.llm.md

@@ -0,0 +1,61 @@
+# ContextMenuGroup
+
+**Type**: component
+
+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.
+
+## JSX Usage
+
+```jsx
+import { ContextMenuGroup } from '@neynar/ui';
+
+<ContextMenuGroup
+  asChild={true}
+  className="value"
+>
+  {/* Your content here */}
+</ContextMenuGroup>
+```
+
+## Component Props
+
+### asChild
+- **Type**: `boolean`
+- **Required**: No
+- **Description**: Merges props with child element instead of rendering wrapper
+
+### className
+- **Type**: `string`
+- **Required**: No
+- **Description**: No description available
+
+### children
+- **Type**: `React.ReactNode`
+- **Required**: Yes
+- **Description**: The menu items to group together logically
+
+## Examples
+
+### Example 1
+```tsx
+<ContextMenuGroup>
+  <ContextMenuItem>Copy</ContextMenuItem>
+  <ContextMenuItem>Cut</ContextMenuItem>
+  <ContextMenuItem>Paste</ContextMenuItem>
+</ContextMenuGroup>
+```
+### Example 2
+```tsx
+// Multiple groups with separators
+<ContextMenuContent>
+  <ContextMenuGroup>
+    <ContextMenuItem>Undo</ContextMenuItem>
+    <ContextMenuItem>Redo</ContextMenuItem>
+  </ContextMenuGroup>
+  <ContextMenuSeparator />
+  <ContextMenuGroup>
+    <ContextMenuItem>Copy</ContextMenuItem>
+    <ContextMenuItem>Paste</ContextMenuItem>
+  </ContextMenuGroup>
+</ContextMenuContent>
+```

package/.llm/context-menu-item.llm.md

@@ -0,0 +1,94 @@
+# ContextMenuItem
+
+**Type**: component
+
+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.
+
+## JSX Usage
+
+```jsx
+import { ContextMenuItem } from '@neynar/ui';
+
+<ContextMenuItem
+  asChild={true}
+  disabled={true}
+  onSelect={handleSelect}
+  textValue="value"
+  inset={true}
+  variant={value}
+  className="value"
+>
+  {/* Your content here */}
+</ContextMenuItem>
+```
+
+## Component Props
+
+### asChild
+- **Type**: `boolean`
+- **Required**: No
+- **Description**: Merges props with child element instead of rendering wrapper
+
+### disabled
+- **Type**: `boolean`
+- **Required**: No
+- **Description**: Prevents interaction and dims the item visually
+
+### onSelect
+- **Type**: `(event: Event) => void`
+- **Required**: No
+- **Description**: Callback fired when item is selected (via mouse or keyboard)
+
+### textValue
+- **Type**: `string`
+- **Required**: No
+- **Description**: Custom text for typeahead navigation when content is complex
+
+### inset
+- **Type**: `boolean`
+- **Required**: No
+- **Description**: Whether to indent the item for alignment with icon-based items
+
+### variant
+- **Type**: `"default" | "destructive"`
+- **Required**: No
+- **Description**: Visual variant ("default" for normal actions, "destructive" for dangerous actions)
+
+### className
+- **Type**: `string`
+- **Required**: No
+- **Description**: Additional CSS classes for custom styling
+
+### children
+- **Type**: `React.ReactNode`
+- **Required**: Yes
+- **Description**: Content of the menu item (text, icons, shortcuts, etc.)
+
+## Examples
+
+### Example 1
+```tsx
+<ContextMenuItem onSelect={() => console.log('Edit selected')}>
+  <Edit className="mr-2 h-4 w-4" />
+  Edit
+  <ContextMenuShortcut>⌘E</ContextMenuShortcut>
+</ContextMenuItem>
+```
+### Example 2
+```tsx
+<ContextMenuItem variant="destructive" onSelect={handleDelete}>
+  <Trash2 className="mr-2 h-4 w-4" />
+  Delete
+</ContextMenuItem>
+```
+### Example 3
+```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>
+```

package/.llm/context-menu-label.llm.md

@@ -0,0 +1,60 @@
+# ContextMenuLabel
+
+**Type**: component
+
+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.
+
+## JSX Usage
+
+```jsx
+import { ContextMenuLabel } from '@neynar/ui';
+
+<ContextMenuLabel
+  asChild={true}
+  inset={true}
+  className="value"
+>
+  {/* Your content here */}
+</ContextMenuLabel>
+```
+
+## Component Props
+
+### asChild
+- **Type**: `boolean`
+- **Required**: No
+- **Description**: Merges props with child element instead of rendering wrapper
+
+### inset
+- **Type**: `boolean`
+- **Required**: No
+- **Description**: Whether to indent the label to align with inset items
+
+### className
+- **Type**: `string`
+- **Required**: No
+- **Description**: Additional CSS classes for styling
+
+### children
+- **Type**: `React.ReactNode`
+- **Required**: Yes
+- **Description**: The text content of the label
+
+## Examples
+
+### Example 1
+```tsx
+<ContextMenuLabel>File Actions</ContextMenuLabel>
+<ContextMenuSeparator />
+<ContextMenuItem>Open</ContextMenuItem>
+<ContextMenuItem>Save</ContextMenuItem>
+```
+### Example 2
+```tsx
+// With inset alignment for consistency
+<ContextMenuContent>
+  <ContextMenuLabel inset>Edit Options</ContextMenuLabel>
+  <ContextMenuItem inset>Copy</ContextMenuItem>
+  <ContextMenuItem inset>Paste</ContextMenuItem>
+</ContextMenuContent>
+```

package/.llm/context-menu-portal.llm.md

@@ -0,0 +1,49 @@
+# ContextMenuPortal
+
+**Type**: component
+
+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.
+
+## JSX Usage
+
+```jsx
+import { ContextMenuPortal } from '@neynar/ui';
+
+<ContextMenuPortal
+  container={value}
+>
+  {/* Your content here */}
+</ContextMenuPortal>
+```
+
+## Component Props
+
+### container
+- **Type**: `HTMLElement`
+- **Required**: No
+- **Description**: Custom container element to portal content into
+
+### children
+- **Type**: `React.ReactNode`
+- **Required**: Yes
+- **Description**: The menu content to render in the portal
+
+## Examples
+
+### Example 1
+```tsx
+<ContextMenuPortal>
+  <ContextMenuSubContent>
+    <ContextMenuItem>Portal Item</ContextMenuItem>
+  </ContextMenuSubContent>
+</ContextMenuPortal>
+```
+### Example 2
+```tsx
+// Portal into specific container
+<ContextMenuPortal container={document.getElementById('menu-container')}>
+  <ContextMenuContent>
+    <ContextMenuItem>Custom Portal Item</ContextMenuItem>
+  </ContextMenuContent>
+</ContextMenuPortal>
+```

package/.llm/context-menu-radio-group.llm.md

@@ -0,0 +1,66 @@
+# ContextMenuRadioGroup
+
+**Type**: component
+
+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.
+
+## JSX Usage
+
+```jsx
+import { ContextMenuRadioGroup } from '@neynar/ui';
+
+<ContextMenuRadioGroup
+  value="value"
+  onValueChange={handleValueChange}
+  className="value"
+>
+  {/* Your content here */}
+</ContextMenuRadioGroup>
+```
+
+## Component Props
+
+### value
+- **Type**: `string`
+- **Required**: No
+- **Description**: The currently selected value that matches a RadioItem's value
+
+### onValueChange
+- **Type**: `(value: string) => void`
+- **Required**: No
+- **Description**: Callback fired when selection changes, receives new value
+
+### className
+- **Type**: `string`
+- **Required**: No
+- **Description**: No description available
+
+### children
+- **Type**: `React.ReactNode`
+- **Required**: Yes
+- **Description**: ContextMenuRadioItem components to group together
+
+## Examples
+
+### Example 1
+```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 2
+```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>
+```

package/.llm/context-menu-radio-item.llm.md

@@ -0,0 +1,76 @@
+# ContextMenuRadioItem
+
+**Type**: component
+
+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.
+
+## JSX Usage
+
+```jsx
+import { ContextMenuRadioItem } from '@neynar/ui';
+
+<ContextMenuRadioItem
+  value="value"
+  disabled={true}
+  onSelect={handleSelect}
+  textValue="value"
+  className="value"
+>
+  {/* Your content here */}
+</ContextMenuRadioItem>
+```
+
+## Component Props
+
+### value
+- **Type**: `string`
+- **Required**: Yes
+- **Description**: The unique value for this radio item (required)
+
+### disabled
+- **Type**: `boolean`
+- **Required**: No
+- **Description**: Whether the item is disabled and non-interactive
+
+### onSelect
+- **Type**: `(event: Event) => void`
+- **Required**: No
+- **Description**: Callback fired when the item is selected (before parent's onValueChange)
+
+### textValue
+- **Type**: `string`
+- **Required**: No
+- **Description**: Custom text for typeahead navigation
+
+### className
+- **Type**: `string`
+- **Required**: No
+- **Description**: Additional CSS classes for styling
+
+### children
+- **Type**: `React.ReactNode`
+- **Required**: Yes
+- **Description**: Content of the radio item (typically text)
+
+## Examples
+
+### Example 1
+```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 2
+```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>
+```

package/.llm/context-menu-separator.llm.md

@@ -0,0 +1,51 @@
+# ContextMenuSeparator
+
+**Type**: component
+
+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.
+
+## JSX Usage
+
+```jsx
+import { ContextMenuSeparator } from '@neynar/ui';
+
+<ContextMenuSeparator
+  asChild={true}
+  className="value"
+/>
+```
+
+## Component Props
+
+### asChild
+- **Type**: `boolean`
+- **Required**: No
+- **Description**: Merges props with child element instead of rendering wrapper
+
+### className
+- **Type**: `string`
+- **Required**: No
+- **Description**: Additional CSS classes for styling
+
+## Examples
+
+### Example 1
+```tsx
+<ContextMenuItem>Copy</ContextMenuItem>
+<ContextMenuItem>Paste</ContextMenuItem>
+<ContextMenuSeparator />
+<ContextMenuItem variant="destructive">Delete</ContextMenuItem>
+```
+### Example 2
+```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>
+```

package/.llm/context-menu-shortcut.llm.md

@@ -0,0 +1,57 @@
+# ContextMenuShortcut
+
+**Type**: component
+
+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.
+
+## JSX Usage
+
+```jsx
+import { ContextMenuShortcut } from '@neynar/ui';
+
+<ContextMenuShortcut
+  className="value"
+>
+  {/* Your content here */}
+</ContextMenuShortcut>
+```
+
+## Component Props
+
+### className
+- **Type**: `string`
+- **Required**: No
+- **Description**: Additional CSS classes for styling
+
+### children
+- **Type**: `React.ReactNode`
+- **Required**: Yes
+- **Description**: The keyboard shortcut text to display (e.g., "⌘C", "Ctrl+V")
+
+## Examples
+
+### Example 1
+```tsx
+<ContextMenuItem>
+  Copy
+  <ContextMenuShortcut>⌘C</ContextMenuShortcut>
+</ContextMenuItem>
+```
+### Example 2
+```tsx
+// Multiple shortcuts for different platforms
+<ContextMenuItem>
+  Save
+  <ContextMenuShortcut>
+    {isMac ? '⌘S' : 'Ctrl+S'}
+  </ContextMenuShortcut>
+</ContextMenuItem>
+```
+### Example 3
+```tsx
+// Complex shortcuts
+<ContextMenuItem>
+  Find and Replace
+  <ContextMenuShortcut>⌘⌥F</ContextMenuShortcut>
+</ContextMenuItem>
+```

package/.llm/context-menu-sub-content.llm.md

@@ -0,0 +1,90 @@
+# ContextMenuSubContent
+
+**Type**: component
+
+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.
+
+## JSX Usage
+
+```jsx
+import { ContextMenuSubContent } from '@neynar/ui';
+
+<ContextMenuSubContent
+  asChild={true}
+  loop={true}
+  onCloseAutoFocus={handleCloseAutoFocus}
+  onEscapeKeyDown={handleEscapeKeyDown}
+  avoidCollisions={true}
+  sideOffset={0}
+  className="value"
+>
+  {/* Your content here */}
+</ContextMenuSubContent>
+```
+
+## Component Props
+
+### asChild
+- **Type**: `boolean`
+- **Required**: No
+- **Description**: Merges props with child element instead of rendering wrapper
+
+### loop
+- **Type**: `boolean`
+- **Required**: No
+- **Description**: Enable keyboard navigation looping from last to first item
+
+### onCloseAutoFocus
+- **Type**: `(event: Event) => void`
+- **Required**: No
+- **Description**: Handle focus return when sub-menu closes
+
+### onEscapeKeyDown
+- **Type**: `(event: KeyboardEvent) => void`
+- **Required**: No
+- **Description**: Handle escape key presses
+
+### avoidCollisions
+- **Type**: `boolean`
+- **Required**: No
+- **Description**: Prevent collisions with viewport boundaries
+
+### sideOffset
+- **Type**: `number`
+- **Required**: No
+- **Description**: Distance in pixels from the trigger anchor
+
+### className
+- **Type**: `string`
+- **Required**: No
+- **Description**: Additional CSS classes for styling
+
+### children
+- **Type**: `React.ReactNode`
+- **Required**: Yes
+- **Description**: Sub-menu items, separators, and labels
+
+## Examples
+
+### Example 1
+```tsx
+<ContextMenuSubContent>
+  <ContextMenuItem>Option 1</ContextMenuItem>
+  <ContextMenuItem>Option 2</ContextMenuItem>
+  <ContextMenuSeparator />
+  <ContextMenuItem>Option 3</ContextMenuItem>
+</ContextMenuSubContent>
+```
+### Example 2
+```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>
+```