@neynar/ui 0.3.0 → 0.3.1

package/.llm/container.llm.md

@@ -0,0 +1,236 @@
+# Container
+
+**Type**: component
+
+Container - A responsive layout wrapper with flexible width constraints and consistent padding A fundamental layout component built with class-variance-authority (CVA) that provides consistent horizontal centering, responsive padding, and flexible max-width constraints. Designed to be the primary content wrapper for pages, sections, and layout regions throughout the application. The component automatically applies responsive horizontal padding (px-4 on mobile, px-6 on small screens, px-8 on large screens) and centers content using mx-auto. Five size variants accommodate different content types from optimal reading widths to full-width layouts. Built following shadcn/ui and Tailwind UI patterns for maximum compatibility and consistency with modern React applications and design systems.
+
+## JSX Usage
+
+```jsx
+import { Container } from '@neynar/ui';
+
+<Container
+  size={value}
+  className="value"
+  id="value"
+  role="value"
+  "aria-label"="value"
+  "aria-labelledby"="value"
+  "aria-describedby"="value"
+  "aria-live"={value}
+  tabIndex={0}
+  onClick={handleClick}
+  onFocus={handleFocus}
+  onBlur={handleBlur}
+  onKeyDown={handleKeyDown}
+  onMouseEnter={handleMouseEnter}
+  onMouseLeave={handleMouseLeave}
+>
+  {/* Your content here */}
+</Container>
+```
+
+## Component Props
+
+### size
+- **Type**: `"sm" | "md" | "lg" | "xl" | "full"`
+- **Required**: No
+- **Description**: No description available
+
+### children
+- **Type**: `React.ReactNode`
+- **Required**: No
+- **Description**: No description available
+
+### className
+- **Type**: `string`
+- **Required**: No
+- **Description**: No description available
+
+### id
+- **Type**: `string`
+- **Required**: No
+- **Description**: No description available
+
+### role
+- **Type**: `string`
+- **Required**: No
+- **Description**: No description available
+
+### "aria-label"
+- **Type**: `string`
+- **Required**: No
+- **Description**: No description available
+
+### "aria-labelledby"
+- **Type**: `string`
+- **Required**: No
+- **Description**: No description available
+
+### "aria-describedby"
+- **Type**: `string`
+- **Required**: No
+- **Description**: No description available
+
+### "aria-live"
+- **Type**: `"off" | "polite" | "assertive"`
+- **Required**: No
+- **Description**: No description available
+
+### tabIndex
+- **Type**: `number`
+- **Required**: No
+- **Description**: No description available
+
+### onClick
+- **Type**: `React.MouseEventHandler<HTMLDivElement>`
+- **Required**: No
+- **Description**: No description available
+
+### onFocus
+- **Type**: `React.FocusEventHandler<HTMLDivElement>`
+- **Required**: No
+- **Description**: No description available
+
+### onBlur
+- **Type**: `React.FocusEventHandler<HTMLDivElement>`
+- **Required**: No
+- **Description**: No description available
+
+### onKeyDown
+- **Type**: `React.KeyboardEventHandler<HTMLDivElement>`
+- **Required**: No
+- **Description**: No description available
+
+### onMouseEnter
+- **Type**: `React.MouseEventHandler<HTMLDivElement>`
+- **Required**: No
+- **Description**: No description available
+
+### onMouseLeave
+- **Type**: `React.MouseEventHandler<HTMLDivElement>`
+- **Required**: No
+- **Description**: No description available
+
+## Examples
+
+### Example 1
+```tsx
+// Basic usage with default large size (80rem max-width)
+<Container>
+  <h1>Dashboard Overview</h1>
+  <p>Main application content with balanced width constraints</p>
+  <div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-6">
+    <Card>Dashboard Widget</Card>
+    <Card>Analytics Panel</Card>
+    <Card>Recent Activity</Card>
+  </div>
+</Container>
+```
+### Example 2
+```tsx
+// Reading-optimized container for articles and blog posts
+<Container size="sm">
+  <article className="prose prose-lg max-w-none">
+    <h1>The Future of Web Development</h1>
+    <p>
+      Long-form content with line lengths optimized for readability
+      and comfortable reading experience across all device sizes.
+    </p>
+    <p>
+      The small container (48rem) provides the ideal measure for
+      typography-focused content and sustained reading.
+    </p>
+  </article>
+</Container>
+```
+### Example 3
+```tsx
+// Medium container for forms and structured layouts
+<Container size="md">
+  <div className="space-y-8">
+    <div className="text-center">
+      <h2>Account Settings</h2>
+      <p>Manage your account preferences and profile information</p>
+    </div>
+    <form className="space-y-6">
+      <div className="grid grid-cols-1 md:grid-cols-2 gap-6">
+        <Input label="First Name" />
+        <Input label="Last Name" />
+      </div>
+      <Input label="Email Address" type="email" />
+      <Button type="submit" className="w-full">Update Profile</Button>
+    </form>
+  </div>
+</Container>
+```
+### Example 4
+```tsx
+// Full-width container for complex layouts and hero sections
+<Container size="full">
+  <div className="bg-gradient-to-r from-blue-600 to-purple-600 text-white py-20">
+    <div className="text-center space-y-6">
+      <h1 className="text-4xl md:text-6xl font-bold">
+        Welcome to Our Platform
+      </h1>
+      <p className="text-xl md:text-2xl opacity-90 max-w-3xl mx-auto">
+        Edge-to-edge hero section with full viewport width
+      </p>
+      <Button size="lg" variant="secondary">
+        Get Started
+      </Button>
+    </div>
+  </div>
+</Container>
+```
+### Example 5
+```tsx
+// Extra-large container for data-heavy interfaces
+<Container size="xl" className="py-8">
+  <div className="space-y-6">
+    <div className="flex justify-between items-center">
+      <h1 className="text-3xl font-bold">Analytics Dashboard</h1>
+      <Button variant="outline">Export Data</Button>
+    </div>
+    // Wide data table that needs maximum available width
+    <DataTable
+      columns={analyticsColumns}
+      data={analyticsData}
+      className="min-w-[1200px]"
+    />
+    <div className="grid grid-cols-1 lg:grid-cols-4 gap-6">
+      <MetricCard />
+      <MetricCard />
+      <MetricCard />
+      <MetricCard />
+    </div>
+  </div>
+</Container>
+```
+### Example 6
+```tsx
+// Advanced usage with custom styling and ARIA landmarks
+<Container
+  size="lg"
+  className="min-h-screen py-12 bg-gray-50 dark:bg-gray-900"
+  role="main"
+  aria-label="Application content"
+>
+  <div className="space-y-10">
+    <header className="text-center space-y-4">
+      <Badge variant="secondary">New Feature</Badge>
+      <h1 className="text-4xl font-bold tracking-tight">
+        Product Announcement
+      </h1>
+      <p className="text-lg text-muted-foreground max-w-2xl mx-auto">
+        Discover the latest improvements to our platform
+      </p>
+    </header>
+    <div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-8">
+      <FeatureCard />
+      <FeatureCard />
+      <FeatureCard />
+    </div>
+  </div>
+</Container>
+```

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

@@ -0,0 +1,97 @@
+# ContextMenuCheckboxItem
+
+**Type**: component
+
+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 with indeterminate state for partially selected collections.
+
+## JSX Usage
+
+```jsx
+import { ContextMenuCheckboxItem } from '@neynar/ui';
+
+<ContextMenuCheckboxItem
+  asChild={true}
+  checked={value}
+  onCheckedChange={handleCheckedChange}
+  disabled={true}
+  onSelect={handleSelect}
+  textValue="value"
+  className="value"
+>
+  {/* Your content here */}
+</ContextMenuCheckboxItem>
+```
+
+## Component Props
+
+### asChild
+- **Type**: `boolean`
+- **Required**: No
+- **Description**: Merges props with child element instead of rendering wrapper
+
+### checked
+- **Type**: `boolean | "indeterminate"`
+- **Required**: No
+- **Description**: The checked state (true, false, or "indeterminate")
+
+### onCheckedChange
+- **Type**: `(checked: boolean) => void`
+- **Required**: No
+- **Description**: Callback fired when the checked state changes
+
+### 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 onCheckedChange)
+
+### 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 checkbox item (typically text)
+
+## Examples
+
+### Example 1
+```tsx
+const [showGrid, setShowGrid] = useState(true)
+<ContextMenuCheckboxItem
+  checked={showGrid}
+  onCheckedChange={setShowGrid}
+>
+  Show Grid
+</ContextMenuCheckboxItem>
+```
+### Example 2
+```tsx
+// With indeterminate state
+const [selectedItems, setSelectedItems] = useState(['item1'])
+const allItems = ['item1', 'item2', 'item3']
+const checkedState = selectedItems.length === 0
+  ? false
+  : selectedItems.length === allItems.length
+    ? true
+    : "indeterminate"
+<ContextMenuCheckboxItem
+  checked={checkedState}
+  onCheckedChange={(checked) =>
+    setSelectedItems(checked ? allItems : [])
+  }
+>
+  Select All
+</ContextMenuCheckboxItem>
+```

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>
+```