@neynar/ui 0.3.0 → 0.3.1

package/.llm/select-content.llm.md

@@ -0,0 +1,139 @@
+# SelectContent
+
+**Type**: component
+
+SelectContent - Container for the dropdown content The dropdown panel that contains all selectable items, groups, and labels. Built on Radix UI Select.Content with Portal rendering for proper layering. Automatically handles scrolling for long lists, collision detection, and positioning relative to the trigger with smooth animations. **Positioning Strategy:** - `popper`: Uses Floating UI for precise positioning with collision detection - `item-aligned`: Aligns content with the selected item for natural feel
+
+## JSX Usage
+
+```jsx
+import { SelectContent } from '@neynar/ui';
+
+<SelectContent
+  asChild={true}
+  position={value}
+  side={value}
+  sideOffset={0}
+  align={value}
+  alignOffset={0}
+  avoidCollisions={true}
+  collisionBoundary={value}
+  collisionPadding={value}
+  arrowPadding={0}
+  sticky={value}
+  hideWhenDetached={true}
+>
+  {/* Your content here */}
+</SelectContent>
+```
+
+## Component Props
+
+### asChild
+- **Type**: `boolean`
+- **Required**: No
+- **Description**: No description available
+
+### position
+- **Type**: `"item-aligned" | "popper"`
+- **Required**: No
+- **Description**: No description available
+
+### side
+- **Type**: `"top" | "right" | "bottom" | "left"`
+- **Required**: No
+- **Description**: No description available
+
+### sideOffset
+- **Type**: `number`
+- **Required**: No
+- **Description**: No description available
+
+### align
+- **Type**: `"start" | "center" | "end"`
+- **Required**: No
+- **Description**: No description available
+
+### alignOffset
+- **Type**: `number`
+- **Required**: No
+- **Description**: No description available
+
+### avoidCollisions
+- **Type**: `boolean`
+- **Required**: No
+- **Description**: No description available
+
+### collisionBoundary
+- **Type**: `Element | null | Array<Element | null>`
+- **Required**: No
+- **Description**: No description available
+
+### collisionPadding
+- **Type**: `| number
+    | Partial<Record<"top" | "right" | "bottom" | "left", number>>`
+- **Required**: No
+- **Description**: No description available
+
+### arrowPadding
+- **Type**: `number`
+- **Required**: No
+- **Description**: No description available
+
+### sticky
+- **Type**: `"partial" | "always"`
+- **Required**: No
+- **Description**: No description available
+
+### hideWhenDetached
+- **Type**: `boolean`
+- **Required**: No
+- **Description**: No description available
+
+## Examples
+
+### Example 1
+```tsx
+// Basic content with multiple items
+<SelectContent>
+  <SelectItem value="1">Option 1</SelectItem>
+  <SelectItem value="2">Option 2</SelectItem>
+  <SelectItem value="3">Option 3</SelectItem>
+</SelectContent>
+```
+### Example 2
+```tsx
+// Item-aligned positioning (default behavior)
+<SelectContent position="item-aligned">
+  <SelectItem value="apple">Apple</SelectItem>
+  <SelectItem value="banana">Banana</SelectItem>
+</SelectContent>
+```
+### Example 3
+```tsx
+// Popper positioning with custom placement
+<SelectContent position="popper" side="top" align="end">
+  <SelectItem value="1">Option 1</SelectItem>
+  <SelectItem value="2">Option 2</SelectItem>
+</SelectContent>
+```
+### Example 4
+```tsx
+// Complex content with groups and scrolling
+<SelectContent>
+  <SelectGroup>
+    <SelectLabel>Recent Items</SelectLabel>
+    <SelectItem value="recent1">Recently Used 1</SelectItem>
+    <SelectItem value="recent2">Recently Used 2</SelectItem>
+  </SelectGroup>
+  <SelectSeparator />
+  <SelectGroup>
+    <SelectLabel>All Items</SelectLabel>
+    {items.map((item) => (
+      <SelectItem key={item.id} value={item.id}>
+        {item.label}
+      </SelectItem>
+    ))}
+  </SelectGroup>
+</SelectContent>
+```

package/.llm/select-group.llm.md

@@ -0,0 +1,60 @@
+# SelectGroup
+
+**Type**: component
+
+SelectGroup - Container for grouping related select items Groups related options together with an optional label for better organization and improved user experience when dealing with many options. Built on Radix UI Select.Group with semantic grouping that enhances screen reader navigation.
+
+## JSX Usage
+
+```jsx
+import { SelectGroup } from '@neynar/ui';
+
+<SelectGroup
+  asChild={true}
+/>
+```
+
+## Component Props
+
+### asChild
+- **Type**: `boolean`
+- **Required**: No
+- **Description**: No description available
+
+## Examples
+
+### Example 1
+```tsx
+// Basic group with label
+<SelectGroup>
+  <SelectLabel>Fruits</SelectLabel>
+  <SelectItem value="apple">Apple</SelectItem>
+  <SelectItem value="banana">Banana</SelectItem>
+  <SelectItem value="orange">Orange</SelectItem>
+</SelectGroup>
+```
+### Example 2
+```tsx
+// Multiple groups with separators
+<SelectContent>
+  <SelectGroup>
+    <SelectLabel>Popular Choices</SelectLabel>
+    <SelectItem value="most-popular">Most Popular</SelectItem>
+    <SelectItem value="trending">Trending</SelectItem>
+  </SelectGroup>
+  <SelectSeparator />
+  <SelectGroup>
+    <SelectLabel>All Options</SelectLabel>
+    <SelectItem value="option1">Option 1</SelectItem>
+    <SelectItem value="option2">Option 2</SelectItem>
+  </SelectGroup>
+</SelectContent>
+```
+### Example 3
+```tsx
+// Group without label for simple separation
+<SelectGroup>
+  <SelectItem value="item1">Item 1</SelectItem>
+  <SelectItem value="item2">Item 2</SelectItem>
+</SelectGroup>
+```

package/.llm/select-item.llm.md

@@ -0,0 +1,75 @@
+# SelectItem
+
+**Type**: component
+
+SelectItem - Individual selectable option in the dropdown Represents a single option that users can select. Built on Radix UI Select.Item with enhanced styling including hover states, selection indicators, and proper spacing. Shows a checkmark when selected and supports keyboard navigation with proper focus management.
+
+## JSX Usage
+
+```jsx
+import { SelectItem } from '@neynar/ui';
+
+<SelectItem
+  asChild={true}
+  value="value"
+  disabled={true}
+  textValue="value"
+>
+  {/* Your content here */}
+</SelectItem>
+```
+
+## Component Props
+
+### asChild
+- **Type**: `boolean`
+- **Required**: No
+- **Description**: No description available
+
+### value
+- **Type**: `string`
+- **Required**: Yes
+- **Description**: No description available
+
+### disabled
+- **Type**: `boolean`
+- **Required**: No
+- **Description**: No description available
+
+### textValue
+- **Type**: `string`
+- **Required**: No
+- **Description**: No description available
+
+## Examples
+
+### Example 1
+```tsx
+// Basic item
+<SelectItem value="apple">Apple</SelectItem>
+```
+### Example 2
+```tsx
+// Disabled item that cannot be selected
+<SelectItem value="sold-out" disabled>
+  Sold Out - Unavailable
+</SelectItem>
+```
+### Example 3
+```tsx
+// Complex item content with custom text value for typeahead
+<SelectItem value="user-123" textValue="John Doe">
+  <div className="flex items-center gap-2">
+    <Avatar size="sm" />
+    <div>
+      <div>John Doe</div>
+      <div className="text-xs text-muted-foreground">john
+### Example 4
+```tsx
+// Using asChild for custom item composition
+<SelectItem value="custom" asChild>
+  <div className="custom-item-styles">
+    Custom item content
+  </div>
+</SelectItem>
+```

package/.llm/select-label.llm.md

@@ -0,0 +1,62 @@
+# SelectLabel
+
+**Type**: component
+
+SelectLabel - Label for a group of select items Provides a non-selectable label for categorizing groups of options. Built on Radix UI Select.Label with muted styling and proper typography. Helps users understand the context of the options below and improves navigation for screen reader users.
+
+## JSX Usage
+
+```jsx
+import { SelectLabel } from '@neynar/ui';
+
+<SelectLabel
+  asChild={true}
+/>
+```
+
+## Component Props
+
+### asChild
+- **Type**: `boolean`
+- **Required**: No
+- **Description**: No description available
+
+## Examples
+
+### Example 1
+```tsx
+// Basic group label
+<SelectGroup>
+  <SelectLabel>Countries</SelectLabel>
+  <SelectItem value="us">United States</SelectItem>
+  <SelectItem value="uk">United Kingdom</SelectItem>
+  <SelectItem value="ca">Canada</SelectItem>
+</SelectGroup>
+```
+### Example 2
+```tsx
+// Multiple labeled groups
+<SelectContent>
+  <SelectGroup>
+    <SelectLabel>Primary Options</SelectLabel>
+    <SelectItem value="primary1">Primary Choice 1</SelectItem>
+    <SelectItem value="primary2">Primary Choice 2</SelectItem>
+  </SelectGroup>
+  <SelectSeparator />
+  <SelectGroup>
+    <SelectLabel>Advanced Options</SelectLabel>
+    <SelectItem value="advanced1">Advanced Choice 1</SelectItem>
+    <SelectItem value="advanced2">Advanced Choice 2</SelectItem>
+  </SelectGroup>
+</SelectContent>
+```
+### Example 3
+```tsx
+// Custom styling with asChild
+<SelectLabel asChild>
+  <div className="flex items-center gap-1 px-2 py-1 font-semibold">
+    <Icon className="size-3" />
+    <span>Categories</span>
+  </div>
+</SelectLabel>
+```

package/.llm/select-scroll-down-button.llm.md

@@ -0,0 +1,45 @@
+# SelectScrollDownButton
+
+**Type**: component
+
+SelectScrollDownButton - Scroll button for navigating down in long lists Appears at the bottom of the dropdown when there are more items below the visible area. Built on Radix UI Select.ScrollDownButton with chevron icon and hover states. Automatically shows/hides based on scroll position.
+
+## JSX Usage
+
+```jsx
+import { SelectScrollDownButton } from '@neynar/ui';
+
+<SelectScrollDownButton
+  asChild={true}
+/>
+```
+
+## Component Props
+
+### asChild
+- **Type**: `boolean`
+- **Required**: No
+- **Description**: No description available
+
+## Examples
+
+### Example 1
+```tsx
+// Automatically included in SelectContent
+<SelectContent>
+  // ScrollUpButton appears here when needed
+  <SelectItem value="1">Item 1</SelectItem>
+  // ... many items ...
+  <SelectItem value="100">Item 100</SelectItem>
+  // ScrollDownButton appears here when needed
+</SelectContent>
+```
+### Example 2
+```tsx
+// Custom scroll button using asChild
+<SelectScrollDownButton asChild>
+  <button className="custom-scroll-styles">
+    <CustomDownIcon />
+  </button>
+</SelectScrollDownButton>
+```

package/.llm/select-scroll-up-button.llm.md

@@ -0,0 +1,45 @@
+# SelectScrollUpButton
+
+**Type**: component
+
+SelectScrollUpButton - Scroll button for navigating up in long lists Appears at the top of the dropdown when there are more items above the visible area. Built on Radix UI Select.ScrollUpButton with chevron icon and hover states. Automatically shows/hides based on scroll position.
+
+## JSX Usage
+
+```jsx
+import { SelectScrollUpButton } from '@neynar/ui';
+
+<SelectScrollUpButton
+  asChild={true}
+/>
+```
+
+## Component Props
+
+### asChild
+- **Type**: `boolean`
+- **Required**: No
+- **Description**: No description available
+
+## Examples
+
+### Example 1
+```tsx
+// Automatically included in SelectContent
+<SelectContent>
+  // ScrollUpButton appears here when needed
+  <SelectItem value="1">Item 1</SelectItem>
+  // ... many items ...
+  <SelectItem value="100">Item 100</SelectItem>
+  // ScrollDownButton appears here when needed
+</SelectContent>
+```
+### Example 2
+```tsx
+// Custom scroll button using asChild
+<SelectScrollUpButton asChild>
+  <button className="custom-scroll-styles">
+    <CustomUpIcon />
+  </button>
+</SelectScrollUpButton>
+```

package/.llm/select-separator.llm.md

@@ -0,0 +1,59 @@
+# SelectSeparator
+
+**Type**: component
+
+SelectSeparator - Visual divider between select groups A horizontal line that visually separates groups of options for better organization and clarity. Built on Radix UI Select.Separator with subtle border styling that adapts to the current theme.
+
+## JSX Usage
+
+```jsx
+import { SelectSeparator } from '@neynar/ui';
+
+<SelectSeparator
+  asChild={true}
+/>
+```
+
+## Component Props
+
+### asChild
+- **Type**: `boolean`
+- **Required**: No
+- **Description**: No description available
+
+## Examples
+
+### Example 1
+```tsx
+// Basic separation between groups
+<SelectContent>
+  <SelectGroup>
+    <SelectLabel>Group 1</SelectLabel>
+    <SelectItem value="1">Option 1</SelectItem>
+  </SelectGroup>
+  <SelectSeparator />
+  <SelectGroup>
+    <SelectLabel>Group 2</SelectLabel>
+    <SelectItem value="2">Option 2</SelectItem>
+  </SelectGroup>
+</SelectContent>
+```
+### Example 2
+```tsx
+// Multiple separators in complex layouts
+<SelectContent>
+  <SelectGroup>
+    <SelectItem value="recent">Recent Items</SelectItem>
+  </SelectGroup>
+  <SelectSeparator />
+  <SelectGroup>
+    <SelectItem value="favorite">Favorites</SelectItem>
+  </SelectGroup>
+  <SelectSeparator />
+  <SelectGroup>
+    <SelectLabel>All Items</SelectLabel>
+    <SelectItem value="all1">Item 1</SelectItem>
+    <SelectItem value="all2">Item 2</SelectItem>
+  </SelectGroup>
+</SelectContent>
+```

package/.llm/select-trigger.llm.md

@@ -0,0 +1,66 @@
+# SelectTrigger
+
+**Type**: component
+
+SelectTrigger - The button that opens the select dropdown A styled button that displays the current value and triggers the dropdown menu. Built on Radix UI Select.Trigger with enhanced styling including focus states, size variants, and proper hover interactions. Includes a chevron icon to indicate dropdown functionality and supports different size variants for various UI contexts. **Size Variants:** - `default`: Standard height (36px) suitable for most forms and interfaces - `sm`: Compact height (32px) ideal for dense layouts and table interfaces
+
+## JSX Usage
+
+```jsx
+import { SelectTrigger } from '@neynar/ui';
+
+<SelectTrigger
+  asChild={true}
+  size={value}
+>
+  {/* Your content here */}
+</SelectTrigger>
+```
+
+## Component Props
+
+### asChild
+- **Type**: `boolean`
+- **Required**: No
+- **Description**: No description available
+
+### size
+- **Type**: `"sm" | "default"`
+- **Required**: No
+- **Description**: No description available
+
+## Examples
+
+### Example 1
+```tsx
+// Basic trigger with custom width
+<SelectTrigger className="w-[200px]">
+  <SelectValue placeholder="Select an option" />
+</SelectTrigger>
+```
+### Example 2
+```tsx
+// Small size variant for compact layouts
+<SelectTrigger size="sm" className="w-[150px]">
+  <SelectValue placeholder="Compact select" />
+</SelectTrigger>
+```
+### Example 3
+```tsx
+// Form integration with accessibility attributes
+<label htmlFor="user-role">User Role</label>
+<SelectTrigger id="user-role" aria-describedby="role-help">
+  <SelectValue placeholder="Choose role" />
+</SelectTrigger>
+<div id="role-help">Select the appropriate role for this user</div>
+```
+### Example 4
+```tsx
+// Custom composition using asChild
+<SelectTrigger asChild>
+  <button className="custom-trigger-styles">
+    <SelectValue />
+    <CustomChevronIcon />
+  </button>
+</SelectTrigger>
+```

package/.llm/select-value.llm.md

@@ -0,0 +1,67 @@
+# SelectValue
+
+**Type**: component
+
+SelectValue - Displays the selected value or placeholder Renders the currently selected option's text or a placeholder when no option is selected. Built on Radix UI Select.Value with proper text truncation and styling. Must be used inside SelectTrigger to display the current selection state.
+
+## JSX Usage
+
+```jsx
+import { SelectValue } from '@neynar/ui';
+
+<SelectValue
+  asChild={true}
+  placeholder={value}
+/>
+```
+
+## Component Props
+
+### asChild
+- **Type**: `boolean`
+- **Required**: No
+- **Description**: No description available
+
+### placeholder
+- **Type**: `React.ReactNode`
+- **Required**: No
+- **Description**: No description available
+
+## Examples
+
+### Example 1
+```tsx
+// Basic usage with placeholder
+<SelectTrigger>
+  <SelectValue placeholder="Choose an option" />
+</SelectTrigger>
+```
+### Example 2
+```tsx
+// Custom placeholder styling
+<SelectTrigger>
+  <SelectValue
+    placeholder={
+      <span className="text-muted-foreground italic">
+        No selection made
+      </span>
+    }
+  />
+</SelectTrigger>
+```
+### Example 3
+```tsx
+// Using asChild for complete custom rendering
+<SelectValue asChild>
+  <div className="flex items-center gap-2">
+    {selectedItem ? (
+      <>
+        <ItemIcon />
+        <span>{selectedItem.label}</span>
+      </>
+    ) : (
+      <span className="text-muted-foreground">Select item...</span>
+    )}
+  </div>
+</SelectValue>
+```