@neynar/ui 0.3.0 → 0.3.1

package/.llm/command-input.llm.md

@@ -0,0 +1,82 @@
+# CommandInput
+
+**Type**: component
+
+CommandInput - Search input for command menu filtering Provides a search input with search icon for filtering command menu items. Automatically filters items as the user types and triggers live region announcements for screen readers. Supports both controlled and uncontrolled usage patterns. The input integrates with the Command context to provide real-time filtering, search highlighting, and result announcements. Includes built-in search icon and proper focus management.
+
+## JSX Usage
+
+```jsx
+import { CommandInput } from '@neynar/ui';
+
+<CommandInput
+  value="value"
+  onValueChange={handleValueChange}
+  placeholder="value"
+  disabled={true}
+  autoFocus={true}
+  className="value"
+/>
+```
+
+## Component Props
+
+### value
+- **Type**: `string`
+- **Required**: No
+- **Description**: Controlled input value for managing search state externally
+
+### onValueChange
+- **Type**: `(search: string) => void`
+- **Required**: No
+- **Description**: Callback fired when input value changes
+
+### placeholder
+- **Type**: `string`
+- **Required**: No
+- **Description**: Placeholder text displayed when input is empty
+
+### disabled
+- **Type**: `boolean`
+- **Required**: No
+- **Description**: Disables the input and prevents interaction
+
+### autoFocus
+- **Type**: `boolean`
+- **Required**: No
+- **Description**: Auto-focus the input when rendered
+
+### className
+- **Type**: `string`
+- **Required**: No
+- **Description**: Additional CSS classes
+
+## Examples
+
+### Example 1
+```tsx
+// Basic uncontrolled input
+<Command>
+  <CommandInput placeholder="Search commands..." />
+  <CommandList>...</CommandList>
+</Command>
+```
+### Example 2
+```tsx
+// Controlled input with external state
+const [search, setSearch] = useState('');
+<CommandInput
+  value={search}
+  onValueChange={setSearch}
+  placeholder="Type a command or search..."
+  autoFocus
+/>
+```
+### Example 3
+```tsx
+// With disabled state
+<CommandInput
+  placeholder="Loading..."
+  disabled={isLoading}
+/>
+```

package/.llm/command-item.llm.md

@@ -0,0 +1,97 @@
+# CommandItem
+
+**Type**: component
+
+CommandItem - Individual selectable command item Represents a single command or action that can be selected via keyboard or mouse interaction. Supports icons, text, shortcuts, and advanced filtering with keywords. Items can be disabled, have custom values for filtering, and trigger callbacks on selection. The item's value is used for filtering - if not provided, it defaults to the text content. Keywords can be added to improve search matching without affecting the display.
+
+## JSX Usage
+
+```jsx
+import { CommandItem } from '@neynar/ui';
+
+<CommandItem
+  value="value"
+  keywords={[]}
+  disabled={true}
+  onSelect={handleSelect}
+  forceMount={true}
+  className="value"
+>
+  {/* Your content here */}
+</CommandItem>
+```
+
+## Component Props
+
+### value
+- **Type**: `string`
+- **Required**: No
+- **Description**: Unique identifier for filtering and selection (defaults to text content)
+
+### keywords
+- **Type**: `string[]`
+- **Required**: No
+- **Description**: Additional search terms for improved filtering
+
+### disabled
+- **Type**: `boolean`
+- **Required**: No
+- **Description**: Disables interaction and selection
+
+### onSelect
+- **Type**: `(value: string) => void`
+- **Required**: No
+- **Description**: Callback fired when item is selected with Enter or click
+
+### forceMount
+- **Type**: `boolean`
+- **Required**: No
+- **Description**: Always render even when filtered out
+
+### 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 item
+<CommandItem onSelect={() => console.log("File opened")}>
+  Open File
+</CommandItem>
+```
+### Example 2
+```tsx
+// Command item with icon and shortcut
+<CommandItem value="new-document" onSelect={handleCreateDocument}>
+  <FileIcon className="mr-2 h-4 w-4" />
+  New Document
+  <CommandShortcut>⌘N</CommandShortcut>
+</CommandItem>
+```
+### Example 3
+```tsx
+// Item with keywords for better search
+<CommandItem
+  value="apple"
+  keywords={['fruit', 'red', 'healthy']}
+  onSelect={() => selectFruit('apple')}
+>
+  🍎 Apple
+</CommandItem>
+```
+### Example 4
+```tsx
+// Disabled item that shows but cannot be selected
+<CommandItem disabled>
+  <LockIcon className="mr-2 h-4 w-4" />
+  Premium Feature
+</CommandItem>
+```

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