@neynar/ui 0.3.0 → 0.3.1

package/.llm/collapsible.llm.md

@@ -0,0 +1,109 @@
+# Collapsible
+
+**Type**: component
+
+An interactive component which expands/collapses a panel A flexible container component built on Radix UI Collapsible primitives that allows users to toggle the visibility of content sections. Unlike Accordion, Collapsible provides more flexibility without enforcing specific visual structures or mutual exclusivity. Perfect for FAQ sections, expandable details, settings panels, sidebar navigation, and any content that should be conditionally visible. Built on `@radix-ui/react-collapsible` with enhanced TypeScript support and comprehensive prop documentation.
+
+## JSX Usage
+
+```jsx
+import { Collapsible } from '@neynar/ui';
+
+<Collapsible
+  asChild={true}
+  defaultOpen={true}
+  open={true}
+  onOpenChange={handleOpenChange}
+  disabled={true}
+/>
+```
+
+## Component Props
+
+### asChild
+- **Type**: `boolean`
+- **Required**: No
+- **Description**: No description available
+
+### defaultOpen
+- **Type**: `boolean`
+- **Required**: No
+- **Description**: No description available
+
+### open
+- **Type**: `boolean`
+- **Required**: No
+- **Description**: No description available
+
+### onOpenChange
+- **Type**: `(open: boolean) => void`
+- **Required**: No
+- **Description**: No description available
+
+### disabled
+- **Type**: `boolean`
+- **Required**: No
+- **Description**: No description available
+
+## Examples
+
+### Example 1
+```tsx
+// Basic controlled collapsible with state management
+const [isOpen, setIsOpen] = React.useState(false)
+<Collapsible open={isOpen} onOpenChange={setIsOpen}>
+  <CollapsibleTrigger asChild>
+    <Button variant="outline" className="w-full justify-between">
+      Can I use this in my project?
+      <ChevronDown className={cn(
+        "h-4 w-4 transition-transform duration-200",
+        isOpen && "rotate-180"
+      )} />
+    </Button>
+  </CollapsibleTrigger>
+  <CollapsibleContent className="overflow-hidden data-[state=closed]:animate-collapsible-up data-[state=open]:animate-collapsible-down">
+    <div className="p-4 border rounded-md bg-muted/50 mt-2">
+      Yes. Free to use for personal and commercial projects.
+      No attribution required.
+    </div>
+  </CollapsibleContent>
+</Collapsible>
+```
+### Example 2
+```tsx
+// Uncontrolled collapsible with default state
+<Collapsible defaultOpen={true} className="w-full space-y-2">
+  <div className="flex items-center justify-between">
+    <h4 className="text-sm font-semibold">
+### Example 3
+```tsx
+// FAQ-style implementation with custom animations
+<Collapsible className="group" data-orientation="vertical">
+  <CollapsibleTrigger className="flex w-full items-center justify-between py-4 text-sm font-medium transition-all hover:underline focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring">
+    How do I get started?
+    <ChevronDown className="h-4 w-4 shrink-0 transition-transform duration-200 group-data-[state=open]:rotate-180" />
+  </CollapsibleTrigger>
+  <CollapsibleContent className="overflow-hidden text-sm transition-all data-[state=closed]:animate-collapsible-up data-[state=open]:animate-collapsible-down">
+    <div className="pb-4 pt-0">
+      Getting started is easy! Simply follow our quick setup guide,
+      install the required dependencies, and begin building your application.
+      Check out our documentation for detailed instructions.
+    </div>
+  </CollapsibleContent>
+</Collapsible>
+```
+### Example 4
+```tsx
+// Disabled collapsible state
+<Collapsible disabled className="opacity-50 cursor-not-allowed">
+  <CollapsibleTrigger className="flex w-full items-center justify-between py-4 text-sm font-medium">
+    This section is temporarily unavailable
+    <ChevronDown className="h-4 w-4" />
+  </CollapsibleTrigger>
+  <CollapsibleContent>
+    <div className="pb-4 pt-0 text-sm text-muted-foreground">
+      This content is currently disabled and cannot be accessed.
+    </div>
+  </CollapsibleContent>
+</Collapsible>
+```

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