@neynar/ui 0.3.0 → 0.4.0

package/.llm/combobox-option.llm.md

@@ -0,0 +1,53 @@
+# ComboboxOption
+
+**Type**: type
+
+Option structure for combobox items Defines the shape of each option that can be displayed and selected in the combobox dropdown list.
+
+## Type Definition
+
+```typescript
+import { ComboboxOption } from '@neynar/ui';
+
+type ComboboxOption = {
+  /**
+   * Unique identifier for this option
+   *
+   * Used for selection tracking and should be unique within the options array.
+   */
+  value: string;
+
+  /**
+   * Display text shown to users in the dropdown
+   *
+   * Should be descriptive and help users understand what this option represents.
+   */
+  label: string;
+
+  /**
+   * Whether this option is disabled and cannot be selected
+   *
+   * Disabled options remain visible but are not selectable and appear dimmed.
+   *
+   * @default false
+   */
+  disabled?: boolean;
+}
+```
+
+## Type Properties
+
+### value
+- **Type**: `string`
+- **Required**: Yes
+- **Description**: No description available
+
+### label
+- **Type**: `string`
+- **Required**: Yes
+- **Description**: No description available
+
+### disabled
+- **Type**: `boolean`
+- **Required**: No
+- **Description**: No description available

package/.llm/combobox.llm.md

@@ -0,0 +1,208 @@
+# Combobox
+
+**Type**: component
+
+Searchable dropdown selection component with typeahead functionality A versatile combobox that combines a button trigger with a searchable dropdown list. Ideal for selecting from moderate to large lists of options where search functionality improves user experience. Built on Radix UI Popover primitives for accessibility and CMDK for powerful command menu functionality with real-time filtering. **Technical Architecture:** - **Popover Container**: Radix UI Popover.Root provides modal/non-modal behavior, focus management, and positioning - **Trigger Button**: Uses Button component with proper ARIA attributes and visual states - **Command Menu**: CMDK provides keyboard navigation, filtering, and accessibility features - **State Management**: Controlled/uncontrolled modes with proper React patterns **Use Cases:** - Selecting from 10+ options that benefit from real-time filtering - User interfaces requiring quick option discovery through search - Forms needing better UX than basic select dropdowns - Applications with dynamic or large option sets **When Not to Use:** - Simple selection from few options (use Select component instead) - Multi-select scenarios (use Checkbox group or specialized multi-select) - Tree or hierarchical data (use TreeSelect or nested menus)
+
+## JSX Usage
+
+```jsx
+import { Combobox } from '@neynar/ui';
+
+<Combobox
+  options={[]}
+  value="value"
+  onValueChange={handleValueChange}
+  placeholder="value"
+  emptyText="value"
+  searchPlaceholder="value"
+  className="value"
+  disabled={true}
+  buttonClassName="value"
+  popoverClassName="value"
+/>
+```
+
+## Component Props
+
+### options
+- **Type**: `ComboboxOption[]`
+- **Required**: Yes
+- **Description**: No description available
+
+### value
+- **Type**: `string`
+- **Required**: No
+- **Description**: No description available
+
+### onValueChange
+- **Type**: `(value: string) => void`
+- **Required**: No
+- **Description**: No description available
+
+### placeholder
+- **Type**: `string`
+- **Required**: No
+- **Description**: No description available
+
+### emptyText
+- **Type**: `string`
+- **Required**: No
+- **Description**: No description available
+
+### searchPlaceholder
+- **Type**: `string`
+- **Required**: No
+- **Description**: No description available
+
+### className
+- **Type**: `string`
+- **Required**: No
+- **Description**: No description available
+
+### disabled
+- **Type**: `boolean`
+- **Required**: No
+- **Description**: No description available
+
+### buttonClassName
+- **Type**: `string`
+- **Required**: No
+- **Description**: No description available
+
+### popoverClassName
+- **Type**: `string`
+- **Required**: No
+- **Description**: No description available
+
+## Examples
+
+### Example 1
+Basic controlled combobox with framework selection
+```tsx
+const [framework, setFramework] = useState("")
+const frameworks = [
+  { value: "nextjs", label: "Next.js" },
+  { value: "remix", label: "Remix" },
+  { value: "sveltekit", label: "SvelteKit" },
+  { value: "nuxt", label: "Nuxt.js" },
+]
+<Combobox
+  options={frameworks}
+  value={framework}
+  onValueChange={setFramework}
+  placeholder="Select framework..."
+  searchPlaceholder="Search frameworks..."
+  buttonClassName="w-[300px]"
+  popoverClassName="w-[300px]"
+/>
+```
+### Example 2
+Advanced combobox with disabled options and custom styling
+```tsx
+const statusOptions = [
+  { value: "active", label: "Active" },
+  { value: "pending", label: "Pending" },
+  { value: "archived", label: "Archived (Read Only)", disabled: true },
+  { value: "deleted", label: "Deleted (Unavailable)", disabled: true },
+]
+<Combobox
+  options={statusOptions}
+  value={status}
+  onValueChange={(value) => {
+    setStatus(value)
+    // Track selection analytics
+    analytics.track('status_selected', { value })
+  }}
+  placeholder="Select status..."
+  emptyText="No matching status found."
+  searchPlaceholder="Filter statuses..."
+  buttonClassName="w-[250px] border-primary/50"
+  popoverClassName="w-[250px]"
+  disabled={isLoading}
+/>
+```
+### Example 3
+Form integration with validation and error handling
+```tsx
+import { Label } from "@/components/ui/label"
+import { useFormContext } from "react-hook-form"
+function CountryField() {
+  const { register, setValue, watch, formState: { errors } } = useFormContext()
+  const selectedCountry = watch("country")
+  return (
+    <div className="space-y-2">
+      <Label htmlFor="country" className={errors.country ? "text-destructive" : ""}>
+        Country {errors.country && "*"}
+      </Label>
+      <Combobox
+        options={countries}
+        value={selectedCountry}
+        onValueChange={(value) => setValue("country", value, { shouldValidate: true })}
+        placeholder="Choose your country..."
+        searchPlaceholder="Type to search countries..."
+        emptyText="Country not found. Try a different search."
+        buttonClassName={cn(
+          "w-full",
+          errors.country && "border-destructive focus-visible:ring-destructive"
+        )}
+        popoverClassName="w-full"
+        disabled={isSubmitting}
+      />
+      {errors.country && (
+        <p className="text-sm text-destructive" role="alert">
+          {errors.country.message}
+        </p>
+      )}
+    </div>
+  )
+}
+```
+### Example 4
+Responsive design with mobile optimization
+```tsx
+<Combobox
+  options={teamMembers}
+  value={assignedTo}
+  onValueChange={setAssignedTo}
+  placeholder="Assign to team member..."
+  searchPlaceholder="Search team members..."
+  emptyText="No team members found."
+  buttonClassName="w-full sm:w-[280px] md:w-[320px]"
+  popoverClassName="w-full sm:w-[280px] md:w-[320px]"
+  // Mobile: full width, Desktop: fixed width for consistent layout
+/>
+```
+### Example 5
+Async data loading with loading states
+```tsx
+function AsyncCombobox() {
+  const [options, setOptions] = useState([])
+  const [loading, setLoading] = useState(false)
+  const [searchTerm, setSearchTerm] = useState("")
+  // Debounced search effect
+  useEffect(() => {
+    if (!searchTerm) return
+    const timeoutId = setTimeout(async () => {
+      setLoading(true)
+      try {
+        const results = await searchAPI(searchTerm)
+        setOptions(results)
+      } finally {
+        setLoading(false)
+      }
+    }, 300)
+    return () => clearTimeout(timeoutId)
+  }, [searchTerm])
+  return (
+    <Combobox
+      options={options}
+      value={selectedValue}
+      onValueChange={setSelectedValue}
+      placeholder={loading ? "Searching..." : "Search items..."}
+      emptyText={loading ? "Loading..." : "No results found."}
+      disabled={loading}
+    />
+  )
+}
+```

package/.llm/command-dialog.llm.md

@@ -0,0 +1,112 @@
+# CommandDialog
+
+**Type**: component
+
+CommandDialog - Modal dialog wrapper for command menu Presents the command menu in a modal dialog overlay, perfect for application-wide command palettes triggered by keyboard shortcuts like Cmd+K or Ctrl+K. Built on Radix UI Dialog with proper focus management, portal rendering, and accessibility. The dialog automatically handles focus trapping, scroll locking, and provides screen reader announcements. Use `container` prop to specify custom portal target.
+
+## JSX Usage
+
+```jsx
+import { CommandDialog } from '@neynar/ui';
+
+<CommandDialog
+  open={true}
+  onOpenChange={handleOpenChange}
+  title="value"
+  description="value"
+  showCloseButton={true}
+  container={value}
+  className="value"
+>
+  {/* Your content here */}
+</CommandDialog>
+```
+
+## Component Props
+
+### open
+- **Type**: `boolean`
+- **Required**: No
+- **Description**: Controls dialog visibility state
+
+### onOpenChange
+- **Type**: `(open: boolean) => void`
+- **Required**: No
+- **Description**: Callback when dialog open state changes
+
+### title
+- **Type**: `string`
+- **Required**: No
+- **Description**: Screen reader accessible title
+
+### description
+- **Type**: `string`
+- **Required**: No
+- **Description**: Screen reader description
+
+### showCloseButton
+- **Type**: `boolean`
+- **Required**: No
+- **Description**: Whether to show the X close button
+
+### container
+- **Type**: `HTMLElement | null`
+- **Required**: No
+- **Description**: Custom portal container element for rendering
+
+### className
+- **Type**: `string`
+- **Required**: No
+- **Description**: Additional CSS classes for dialog content
+
+### children
+- **Type**: `React.ReactNode`
+- **Required**: No
+- **Description**: No description available
+
+## Examples
+
+### Example 1
+```tsx
+// Command palette 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>Create New File</CommandItem>
+      <CommandItem>Open Settings</CommandItem>
+    </CommandGroup>
+  </CommandList>
+</CommandDialog>
+```
+### Example 2
+```tsx
+// Custom portal container
+const containerRef = useRef<HTMLDivElement>(null);
+<>
+  <CommandDialog
+    open={open}
+    onOpenChange={setOpen}
+    container={containerRef.current}
+    title="Quick Actions"
+    description="Find and run commands quickly"
+  >
+    <CommandInput />
+    <CommandList>
+      <CommandItem>Action 1</CommandItem>
+    </CommandList>
+  </CommandDialog>
+  <div ref={containerRef} />
+</>
+```

package/.llm/command-empty.llm.md

@@ -0,0 +1,63 @@
+# CommandEmpty
+
+**Type**: component
+
+CommandEmpty - Empty state message for command menu Displays when no command items match the current search query. Can contain custom content beyond simple text messages. Automatically shows/hides based on filtered results and announces changes to screen readers. Supports dynamic content using the `useCommandState` hook to access current search term and create contextual empty messages.
+
+## JSX Usage
+
+```jsx
+import { CommandEmpty } from '@neynar/ui';
+
+<CommandEmpty
+  className="value"
+>
+  {/* Your content here */}
+</CommandEmpty>
+```
+
+## 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 commands found.</CommandEmpty>
+</CommandList>
+```
+### Example 2
+```tsx
+// Custom empty state with icon and helpful text
+<CommandEmpty>
+  <div className="py-6 text-center">
+    <SearchIcon className="mx-auto h-10 w-10 text-muted-foreground/50" />
+    <h3 className="mt-2 text-sm font-medium">No results found</h3>
+    <p className="mt-1 text-sm text-muted-foreground">
+      Try adjusting your search terms.
+    </p>
+  </div>
+</CommandEmpty>
+```
+### Example 3
+```tsx
+// Dynamic empty message with search term
+function DynamicEmpty() {
+  const search = useCommandState((state) => state.search);
+  return (
+    <CommandEmpty>
+      {search ? `No results found for "${search}".` : 'Start typing to search...'}
+    </CommandEmpty>
+  );
+}
+```

package/.llm/command-group.llm.md

@@ -0,0 +1,83 @@
+# CommandGroup
+
+**Type**: component
+
+CommandGroup - Groups related command items under a heading Organizes command items into labeled sections with optional headings for better organization and navigation. Groups provide semantic structure for screen readers and can be hidden/shown based on whether they contain matching items. Groups automatically manage their visibility - if all contained items are filtered out, the entire group is hidden. Use `forceMount` to override this behavior.
+
+## JSX Usage
+
+```jsx
+import { CommandGroup } from '@neynar/ui';
+
+<CommandGroup
+  heading={value}
+  value="value"
+  forceMount={true}
+  className="value"
+>
+  {/* Your content here */}
+</CommandGroup>
+```
+
+## Component Props
+
+### heading
+- **Type**: `React.ReactNode`
+- **Required**: No
+- **Description**: The group heading text or component displayed above items
+
+### value
+- **Type**: `string`
+- **Required**: No
+- **Description**: Group identifier for programmatic control
+
+### forceMount
+- **Type**: `boolean`
+- **Required**: No
+- **Description**: Whether to always render the group even when hidden
+
+### className
+- **Type**: `string`
+- **Required**: No
+- **Description**: Additional CSS classes
+
+### children
+- **Type**: `React.ReactNode`
+- **Required**: No
+- **Description**: No description available
+
+## Examples
+
+### Example 1
+```tsx
+<CommandGroup heading="Recent Files">
+  <CommandItem>document.pdf</CommandItem>
+  <CommandItem>presentation.pptx</CommandItem>
+</CommandGroup>
+<CommandGroup heading="Actions">
+  <CommandItem>New File</CommandItem>
+  <CommandItem>Open File</CommandItem>
+</CommandGroup>
+```
+### Example 2
+```tsx
+// Group with custom heading component
+<CommandGroup
+  heading={
+    <div className="flex items-center gap-2">
+      <FolderIcon className="h-4 w-4" />
+      <span>Projects</span>
+    </div>
+  }
+>
+  <CommandItem>Project A</CommandItem>
+  <CommandItem>Project B</CommandItem>
+</CommandGroup>
+```
+### Example 3
+```tsx
+// Group that always shows even when filtered
+<CommandGroup heading="Important" forceMount>
+  <CommandItem>Critical Action</CommandItem>
+</CommandGroup>
+```

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