@neynar/ui 0.3.0 → 0.4.0

package/.llm/command-list.llm.md

@@ -0,0 +1,53 @@
+# CommandList
+
+**Type**: component
+
+CommandList - Scrollable container for command items Contains and manages the list of command items with automatic scrolling, overflow handling, and dynamic height calculation. Provides the scrollable viewport for command items and groups with proper keyboard navigation. Uses CSS custom property `--cmdk-list-height` for smooth height transitions when items are filtered. Supports scroll padding for better item visibility.
+
+## JSX Usage
+
+```jsx
+import { CommandList } from '@neynar/ui';
+
+<CommandList
+  className="value"
+>
+  {/* Your content here */}
+</CommandList>
+```
+
+## Component Props
+
+### className
+- **Type**: `string`
+- **Required**: No
+- **Description**: Additional CSS classes
+
+### children
+- **Type**: `React.ReactNode`
+- **Required**: No
+- **Description**: No description available
+
+## Examples
+
+### Example 1
+```tsx
+<CommandList>
+  <CommandEmpty>No results found</CommandEmpty>
+  <CommandGroup heading="Actions">
+    <CommandItem>New File</CommandItem>
+    <CommandItem>Open File</CommandItem>
+  </CommandGroup>
+</CommandList>
+```
+### Example 2
+```tsx
+// With custom height and scroll behavior
+<CommandList className="max-h-[400px] scroll-py-2">
+  {items.map((item) => (
+    <CommandItem key={item.id} value={item.id}>
+      {item.name}
+    </CommandItem>
+  ))}
+</CommandList>
+```

package/.llm/command-loading.llm.md

@@ -0,0 +1,48 @@
+# CommandLoading
+
+**Type**: component
+
+CommandLoading - Loading state indicator for command menu Displays a loading message while command items are being fetched asynchronously. Should be conditionally rendered based on loading state. Shares the same styling and behavior as CommandEmpty but indicates active loading rather than empty state.
+
+## JSX Usage
+
+```jsx
+import { CommandLoading } from '@neynar/ui';
+
+<CommandLoading
+  ...props={value}
+/>
+```
+
+## Component Props
+
+### ...props
+- **Type**: `unknown`
+- **Required**: Yes
+- **Description**: No description available
+
+## Examples
+
+### Example 1
+```tsx
+const [loading, setLoading] = useState(false);
+const [items, setItems] = useState([]);
+<CommandList>
+  {loading && <CommandLoading>Fetching commands...</CommandLoading>}
+  {items.map(item => (
+    <CommandItem key={item.id} value={item.id}>
+      {item.name}
+    </CommandItem>
+  ))}
+</CommandList>
+```
+### Example 2
+```tsx
+// With custom loading indicator
+<CommandLoading>
+  <div className="flex items-center justify-center py-6">
+    <Spinner className="mr-2 h-4 w-4" />
+    <span>Loading commands...</span>
+  </div>
+</CommandLoading>
+```

package/.llm/command-separator.llm.md

@@ -0,0 +1,44 @@
+# CommandSeparator
+
+**Type**: component
+
+CommandSeparator - Visual separator between command groups Provides visual separation between different sections of commands. Purely decorative element that improves visual organization and hierarchy. Automatically hides when adjacent groups are filtered out. The separator will only render when it has visible content before and after it, unless `alwaysRender` is true.
+
+## JSX Usage
+
+```jsx
+import { CommandSeparator } from '@neynar/ui';
+
+<CommandSeparator
+  alwaysRender={true}
+  className="value"
+/>
+```
+
+## Component Props
+
+### alwaysRender
+- **Type**: `boolean`
+- **Required**: No
+- **Description**: Whether to always show separator regardless of context
+
+### className
+- **Type**: `string`
+- **Required**: No
+- **Description**: Additional CSS classes
+
+## Examples
+
+### Example 1
+```tsx
+<CommandGroup heading="Recent">...</CommandGroup>
+<CommandSeparator />
+<CommandGroup heading="Actions">...</CommandGroup>
+```
+### Example 2
+```tsx
+// Separator that always renders
+<CommandGroup heading="Primary">...</CommandGroup>
+<CommandSeparator alwaysRender />
+<CommandGroup heading="Secondary">...</CommandGroup>
+```

package/.llm/command-shortcut.llm.md

@@ -0,0 +1,63 @@
+# CommandShortcut
+
+**Type**: component
+
+CommandShortcut - Displays keyboard shortcut for command items Shows the keyboard shortcut associated with a command item, typically displayed on the right side with proper spacing. Supports platform-specific shortcuts and complex key combinations with consistent formatting. The component uses monospace-style formatting with appropriate opacity and spacing to clearly indicate keyboard shortcuts without overwhelming the item content.
+
+## JSX Usage
+
+```jsx
+import { CommandShortcut } from '@neynar/ui';
+
+<CommandShortcut
+  className="value"
+>
+  {/* Your content here */}
+</CommandShortcut>
+```
+
+## Component Props
+
+### className
+- **Type**: `string`
+- **Required**: No
+- **Description**: Additional CSS classes
+
+### children
+- **Type**: `React.ReactNode`
+- **Required**: No
+- **Description**: No description available
+
+## Examples
+
+### Example 1
+```tsx
+<CommandItem>
+  Save File
+  <CommandShortcut>⌘S</CommandShortcut>
+</CommandItem>
+```
+### Example 2
+```tsx
+// Multi-key shortcuts
+<CommandItem>
+  Redo
+  <CommandShortcut>⇧⌘Z</CommandShortcut>
+</CommandItem>
+```
+### Example 3
+```tsx
+// Platform-specific shortcuts
+<CommandItem>
+  Copy
+  <CommandShortcut>{isMac ? '⌘C' : 'Ctrl+C'}</CommandShortcut>
+</CommandItem>
+```
+### Example 4
+```tsx
+// Complex shortcuts with modifiers
+<CommandItem>
+  Open Command Palette
+  <CommandShortcut>⌘⇧P</CommandShortcut>
+</CommandItem>
+```

package/.llm/command.llm.md

@@ -0,0 +1,147 @@
+# Command
+
+**Type**: component
+
+Command - A fast, composable command menu for search and navigation Built on the cmdk primitive, this component provides a powerful command palette interface with search, filtering, and keyboard navigation. Perfect for creating search interfaces, command palettes, and action menus with full accessibility support. Features advanced filtering with fuzzy search, keyboard shortcuts, nested navigation, asynchronous loading states, and comprehensive accessibility patterns.
+
+## JSX Usage
+
+```jsx
+import { Command } from '@neynar/ui';
+
+<Command
+  label="value"
+  shouldFilter={true}
+  filter={[]}
+  value="value"
+  onValueChange={handleValueChange}
+  loop={true}
+  disablePointerSelection={true}
+  vimBindings={true}
+  className="value"
+>
+  {/* Your content here */}
+</Command>
+```
+
+## Component Props
+
+### label
+- **Type**: `string`
+- **Required**: No
+- **Description**: Accessibility label for screen readers and assistive technology
+
+### shouldFilter
+- **Type**: `boolean`
+- **Required**: No
+- **Description**: Controls automatic filtering and sorting
+
+### filter
+- **Type**: `(value: string, search: string, keywords?: string[]) => number`
+- **Required**: No
+- **Description**: Custom filter function for ranking items based on search
+
+### value
+- **Type**: `string`
+- **Required**: No
+- **Description**: Currently selected item value for controlled usage
+
+### onValueChange
+- **Type**: `(value: string) => void`
+- **Required**: No
+- **Description**: Callback fired when selected item changes
+
+### loop
+- **Type**: `boolean`
+- **Required**: No
+- **Description**: Enables circular navigation through items
+
+### disablePointerSelection
+- **Type**: `boolean`
+- **Required**: No
+- **Description**: Prevents mouse selection behavior
+
+### vimBindings
+- **Type**: `boolean`
+- **Required**: No
+- **Description**: Enables Vim-style navigation keybindings
+
+### className
+- **Type**: `string`
+- **Required**: No
+- **Description**: Additional CSS classes
+
+### children
+- **Type**: `React.ReactNode`
+- **Required**: No
+- **Description**: No description available
+
+## Examples
+
+### Example 1
+```tsx
+// Basic command menu
+<Command label="Main Menu">
+  <CommandInput placeholder="Type a command or search..." />
+  <CommandList>
+    <CommandEmpty>No results found.</CommandEmpty>
+    <CommandGroup heading="Suggestions">
+      <CommandItem>Calendar</CommandItem>
+      <CommandItem>Search Emoji</CommandItem>
+      <CommandItem>Calculator</CommandItem>
+    </CommandGroup>
+  </CommandList>
+</Command>
+```
+### Example 2
+```tsx
+// Controlled command menu with custom filtering
+const [value, setValue] = useState('');
+const [search, setSearch] = useState('');
+<Command
+  value={value}
+  onValueChange={setValue}
+  filter={(value, search, keywords) => {
+    const extended = value + ' ' + (keywords?.join(' ') || '');
+    return extended.toLowerCase().includes(search.toLowerCase()) ? 1 : 0;
+  }}
+  loop
+>
+  <CommandInput
+    value={search}
+    onValueChange={setSearch}
+    placeholder="Search..."
+  />
+  <CommandList>
+    <CommandItem value="apple" keywords={['fruit', 'red']}>
+      Apple
+    </CommandItem>
+  </CommandList>
+</Command>
+```
+### Example 3
+```tsx
+// Command dialog with keyboard shortcut
+const [open, setOpen] = useState(false);
+useEffect(() => {
+  const down = (e: KeyboardEvent) => {
+    if (e.key === "k" && (e.metaKey || e.ctrlKey)) {
+      e.preventDefault();
+      setOpen((open) => !open);
+    }
+  };
+  document.addEventListener("keydown", down);
+  return () => document.removeEventListener("keydown", down);
+}, []);
+<CommandDialog open={open} onOpenChange={setOpen}>
+  <CommandInput placeholder="Type a command..." />
+  <CommandList>
+    <CommandGroup heading="Actions">
+      <CommandItem onSelect={() => console.log("New file")}>
+        New File
+        <CommandShortcut>⌘N</CommandShortcut>
+      </CommandItem>
+    </CommandGroup>
+  </CommandList>
+</CommandDialog>
+```

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