@neynar/ui 0.3.0 → 0.4.0

package/.llm/select.llm.md

@@ -0,0 +1,159 @@
+# Select
+
+**Type**: component
+
+Select - A dropdown selection component built on Radix UI primitives Provides a dropdown menu for selecting a single option from a list of choices. Features comprehensive keyboard navigation, grouping capabilities, accessibility compliance, and flexible styling options. Perfect for forms, filters, and configuration interfaces. Built on Radix UI Select.Root with enhanced styling.
+
+## JSX Usage
+
+```jsx
+import { Select } from '@neynar/ui';
+
+<Select
+  defaultValue="value"
+  value="value"
+  onValueChange={handleValueChange}
+  defaultOpen={true}
+  open={true}
+  onOpenChange={handleOpenChange}
+  dir={value}
+  name="value"
+  disabled={true}
+  required={true}
+/>
+```
+
+## Component Props
+
+### defaultValue
+- **Type**: `string`
+- **Required**: No
+- **Description**: No description available
+
+### value
+- **Type**: `string`
+- **Required**: No
+- **Description**: No description available
+
+### onValueChange
+- **Type**: `(value: string) => void`
+- **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
+
+### dir
+- **Type**: `"ltr" | "rtl"`
+- **Required**: No
+- **Description**: No description available
+
+### name
+- **Type**: `string`
+- **Required**: No
+- **Description**: No description available
+
+### disabled
+- **Type**: `boolean`
+- **Required**: No
+- **Description**: No description available
+
+### required
+- **Type**: `boolean`
+- **Required**: No
+- **Description**: No description available
+
+## Examples
+
+### Example 1
+```tsx
+// Basic uncontrolled select
+<Select defaultValue="apple">
+  <SelectTrigger className="w-[180px]">
+    <SelectValue placeholder="Select a fruit" />
+  </SelectTrigger>
+  <SelectContent>
+    <SelectItem value="apple">Apple</SelectItem>
+    <SelectItem value="banana">Banana</SelectItem>
+    <SelectItem value="orange">Orange</SelectItem>
+  </SelectContent>
+</Select>
+```
+### Example 2
+```tsx
+// Controlled select with state management
+const [value, setValue] = useState("");
+<Select value={value} onValueChange={setValue}>
+  <SelectTrigger>
+    <SelectValue placeholder="Choose an option" />
+  </SelectTrigger>
+  <SelectContent>
+    <SelectItem value="option1">Option 1</SelectItem>
+    <SelectItem value="option2">Option 2</SelectItem>
+  </SelectContent>
+</Select>
+```
+### Example 3
+```tsx
+// Grouped options with separators and labels
+<Select>
+  <SelectTrigger>
+    <SelectValue placeholder="Select a timezone" />
+  </SelectTrigger>
+  <SelectContent>
+    <SelectGroup>
+      <SelectLabel>North America</SelectLabel>
+      <SelectItem value="est">Eastern Time (EST)</SelectItem>
+      <SelectItem value="cst">Central Time (CST)</SelectItem>
+      <SelectItem value="pst">Pacific Time (PST)</SelectItem>
+    </SelectGroup>
+    <SelectSeparator />
+    <SelectGroup>
+      <SelectLabel>Europe</SelectLabel>
+      <SelectItem value="gmt">Greenwich Mean Time (GMT)</SelectItem>
+      <SelectItem value="cet">Central European Time (CET)</SelectItem>
+    </SelectGroup>
+  </SelectContent>
+</Select>
+```
+### Example 4
+```tsx
+// Form integration with validation and required state
+<form>
+  <Select name="userRole" required defaultValue="">
+    <SelectTrigger id="role" aria-describedby="role-error">
+      <SelectValue placeholder="Choose your role" />
+    </SelectTrigger>
+    <SelectContent>
+      <SelectItem value="admin">Administrator</SelectItem>
+      <SelectItem value="user">User</SelectItem>
+      <SelectItem value="guest">Guest</SelectItem>
+    </SelectContent>
+  </Select>
+</form>
+```
+### Example 5
+```tsx
+// Disabled states and interactions
+<Select disabled>
+  <SelectTrigger>
+    <SelectValue placeholder="Disabled select" />
+  </SelectTrigger>
+  <SelectContent>
+    <SelectItem value="1">Option 1</SelectItem>
+    <SelectItem value="2" disabled>Option 2 (disabled)</SelectItem>
+  </SelectContent>
+</Select>
+```

package/.llm/separator.llm.md

@@ -0,0 +1,129 @@
+# Separator
+
+**Type**: component
+
+Separator component for visually and semantically dividing content sections A flexible, accessible separator component built on Radix UI primitives that creates visual or semantic divisions between content sections. Supports both horizontal and vertical orientations with full accessibility features including decorative and semantic separator modes for optimal screen reader compatibility. Built on Radix UI Separator primitive which automatically handles: - WAI-ARIA separator role compliance - Proper orientation data attributes - Screen reader visibility control via decorative prop - Keyboard navigation support for interactive separators - Semantic HTML structure with proper ARIA attributes
+
+## JSX Usage
+
+```jsx
+import { Separator } from '@neynar/ui';
+
+<Separator
+  className="value"
+  orientation={value}
+  decorative={true}
+  asChild={true}
+  "aria-label"="value"
+  "aria-labelledby"="value"
+  "aria-valuenow"={0}
+  "aria-valuemin"={0}
+  "aria-valuemax"={0}
+  "aria-valuetext"="value"
+/>
+```
+
+## Component Props
+
+### className
+- **Type**: `string`
+- **Required**: No
+- **Description**: No description available
+
+### orientation
+- **Type**: `"horizontal" | "vertical"`
+- **Required**: No
+- **Description**: No description available
+
+### decorative
+- **Type**: `boolean`
+- **Required**: No
+- **Description**: No description available
+
+### asChild
+- **Type**: `boolean`
+- **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-valuenow"
+- **Type**: `number`
+- **Required**: No
+- **Description**: No description available
+
+### "aria-valuemin"
+- **Type**: `number`
+- **Required**: No
+- **Description**: No description available
+
+### "aria-valuemax"
+- **Type**: `number`
+- **Required**: No
+- **Description**: No description available
+
+### "aria-valuetext"
+- **Type**: `string`
+- **Required**: No
+- **Description**: No description available
+
+## Examples
+
+### Example 1
+```tsx
+// Basic horizontal separator - decorative divider
+<div className="space-y-4">
+  <p>Content above</p>
+  <Separator />
+  <p>Content below</p>
+</div>
+```
+### Example 2
+```tsx
+// Vertical separator in toolbar layouts
+<div className="flex items-center space-x-2">
+  <button>Bold</button>
+  <button>Italic</button>
+  <Separator orientation="vertical" className="h-4" />
+  <button>Underline</button>
+  <button>Strike</button>
+</div>
+```
+### Example 3
+```tsx
+// Semantic separator with screen reader support
+<nav className="flex items-center space-x-2">
+  <a href="/dashboard">Dashboard</a>
+  <Separator
+    orientation="vertical"
+    decorative={false}
+    aria-label="Navigation separator"
+    className="h-4"
+  />
+  <a href="/settings">Settings</a>
+</nav>
+```
+### Example 4
+```tsx
+// Custom styled separator with gradient
+<Separator className="my-8 h-px bg-gradient-to-r from-transparent via-border to-transparent" />
+```
+### Example 5
+```tsx
+// Polymorphic separator using semantic HTML
+<article>
+  <section>First section content</section>
+  <Separator asChild decorative={false} aria-label="Section divider">
+    <hr className="my-6" />
+  </Separator>
+  <section>Second section content</section>
+</article>
+```

package/.llm/sheet-close.llm.md

@@ -0,0 +1,49 @@
+# SheetClose
+
+**Type**: component
+
+SheetClose - Button that closes the sheet A button that closes the sheet when clicked. Can be placed anywhere within the sheet content. Use the `asChild` prop to render as a different element while maintaining the close functionality. Multiple close buttons can be used throughout the sheet content.
+
+## JSX Usage
+
+```jsx
+import { SheetClose } from '@neynar/ui';
+
+<SheetClose
+  asChild={true}
+>
+  {/* Your content here */}
+</SheetClose>
+```
+
+## Component Props
+
+### asChild
+- **Type**: `boolean`
+- **Required**: No
+- **Description**: When true, merges props with child element instead of rendering a button
+
+### children
+- **Type**: `React.ReactNode`
+- **Required**: No
+- **Description**: Child element to render as the close button. Required when asChild is true
+
+## Examples
+
+```tsx
+// In footer with styled button
+<SheetFooter>
+  <SheetClose asChild>
+    <Button variant="outline">Cancel</Button>
+  </SheetClose>
+  <Button type="submit">Save</Button>
+</SheetFooter>
+// As simple text button
+<SheetClose>Close</SheetClose>
+// Custom close button in content
+<SheetClose asChild>
+  <Button variant="ghost" size="sm" className="ml-auto">
+    <XIcon className="h-4 w-4" />
+  </Button>
+</SheetClose>
+```

package/.llm/sheet-content.llm.md

@@ -0,0 +1,115 @@
+# SheetContent
+
+**Type**: component
+
+SheetContent - Main container for sheet content The primary content area of the sheet that slides in from the specified side. Includes automatic overlay, portal rendering, and close button. Contains smooth slide animations with responsive sizing and proper focus management. Features automatic positioning based on the side prop: - Right/Left: Full height, responsive width (3/4 on mobile, max 384px on desktop) - Top/Bottom: Full width, auto height based on content
+
+## JSX Usage
+
+```jsx
+import { SheetContent } from '@neynar/ui';
+
+<SheetContent
+  asChild={true}
+  forceMount={true}
+  onCloseAutoFocus={handleCloseAutoFocus}
+  onOpenAutoFocus={handleOpenAutoFocus}
+  onEscapeKeyDown={handleEscapeKeyDown}
+  onPointerDownOutside={handlePointerDownOutside}
+  onInteractOutside={handleInteractOutside}
+  side={value}
+  className="value"
+>
+  {/* Your content here */}
+</SheetContent>
+```
+
+## Component Props
+
+### asChild
+- **Type**: `boolean`
+- **Required**: No
+- **Description**: When true, merges props with child element instead of rendering a div
+
+### forceMount
+- **Type**: `boolean`
+- **Required**: No
+- **Description**: Forces mounting when true. Useful for controlling animations with external state
+
+### onCloseAutoFocus
+- **Type**: `(event: Event) => void`
+- **Required**: No
+- **Description**: Event handler called when focus moves to the trigger after closing
+
+### onOpenAutoFocus
+- **Type**: `(event: Event) => void`
+- **Required**: No
+- **Description**: Event handler called when focus moves into the component after opening
+
+### onEscapeKeyDown
+- **Type**: `(event: KeyboardEvent) => void`
+- **Required**: No
+- **Description**: Event handler called when the escape key is down. Can prevent default to disable escape key closing
+
+### onPointerDownOutside
+- **Type**: `(
+    event: CustomEvent<{ originalEvent: PointerEvent }>,
+  ) => void`
+- **Required**: No
+- **Description**: Event handler called when a pointer down event happens outside the component bounds
+
+### onInteractOutside
+- **Type**: `(
+    event: CustomEvent<{ originalEvent: PointerEvent | FocusEvent }>,
+  ) => void`
+- **Required**: No
+- **Description**: Event handler called when an interaction happens outside the component bounds
+
+### side
+- **Type**: `"top" | "right" | "bottom" | "left"`
+- **Required**: No
+- **Description**: Which side of the screen the sheet slides in from
+
+### className
+- **Type**: `string`
+- **Required**: No
+- **Description**: Additional CSS classes for styling customization
+
+### children
+- **Type**: `React.ReactNode`
+- **Required**: No
+- **Description**: Content to display inside the sheet
+
+## Examples
+
+```tsx
+// Default right-side sheet
+<SheetContent>
+  <SheetHeader>
+    <SheetTitle>Settings</SheetTitle>
+  </SheetHeader>
+  <div className="py-4">
+    Settings content here
+  </div>
+</SheetContent>
+// Left-side navigation sheet
+<SheetContent side="left">
+  <nav>
+    <Button variant="ghost">Dashboard</Button>
+    <Button variant="ghost">Profile</Button>
+  </nav>
+</SheetContent>
+// Top sheet with custom height
+<SheetContent side="top" className="h-[300px]">
+  <SheetHeader>
+    <SheetTitle>Notifications</SheetTitle>
+  </SheetHeader>
+</SheetContent>
+// Bottom sheet for mobile actions
+<SheetContent side="bottom" className="h-[400px]">
+  <div className="grid grid-cols-2 gap-4">
+    <Button>Action 1</Button>
+    <Button>Action 2</Button>
+  </div>
+</SheetContent>
+```

package/.llm/sheet-description.llm.md

@@ -0,0 +1,62 @@
+# SheetDescription
+
+**Type**: component
+
+SheetDescription - Description text for the sheet Provides additional context about the sheet's purpose or instructions. Appears below the title with muted styling. Should be used within SheetHeader. While optional, it's recommended for better accessibility and user understanding.
+
+## JSX Usage
+
+```jsx
+import { SheetDescription } from '@neynar/ui';
+
+<SheetDescription
+  asChild={true}
+  className="value"
+>
+  {/* Your content here */}
+</SheetDescription>
+```
+
+## Component Props
+
+### asChild
+- **Type**: `boolean`
+- **Required**: No
+- **Description**: When true, merges props with child element instead of rendering a p element
+
+### className
+- **Type**: `string`
+- **Required**: No
+- **Description**: Additional CSS classes for styling customization
+
+### children
+- **Type**: `React.ReactNode`
+- **Required**: No
+- **Description**: Description text content
+
+## Examples
+
+```tsx
+// Standard usage with instructional text
+<SheetHeader>
+  <SheetTitle>Edit Profile</SheetTitle>
+  <SheetDescription>
+    Make changes to your profile here. Click save when you're done.
+  </SheetDescription>
+</SheetHeader>
+// Warning or important information
+<SheetDescription className="text-orange-600">
+  This action cannot be undone.
+</SheetDescription>
+// Custom styled description
+<SheetDescription asChild>
+  <p className="text-sm text-gray-600 italic">
+    Changes will be saved automatically.
+  </p>
+</SheetDescription>
+// Contextual help description
+<SheetDescription>
+  Use this form to update your notification preferences.
+  Changes take effect immediately.
+</SheetDescription>
+```

package/.llm/sheet-footer.llm.md

@@ -0,0 +1,64 @@
+# SheetFooter
+
+**Type**: component
+
+SheetFooter - Footer section for sheet actions A container for action buttons positioned at the bottom of the sheet content. Uses `mt-auto` to stick to the bottom and provides consistent spacing for buttons. Ideal for primary and secondary actions like Save/Cancel button pairs.
+
+## JSX Usage
+
+```jsx
+import { SheetFooter } from '@neynar/ui';
+
+<SheetFooter
+  className="value"
+>
+  {/* Your content here */}
+</SheetFooter>
+```
+
+## Component Props
+
+### className
+- **Type**: `string`
+- **Required**: No
+- **Description**: Additional CSS classes for styling customization
+
+### children
+- **Type**: `React.ReactNode`
+- **Required**: No
+- **Description**: Footer content (typically action buttons)
+
+## Examples
+
+```tsx
+// Standard save/cancel footer
+<SheetFooter>
+  <SheetClose asChild>
+    <Button variant="outline">Cancel</Button>
+  </SheetClose>
+  <Button type="submit">Save Changes</Button>
+</SheetFooter>
+// Single action footer
+<SheetFooter>
+  <SheetClose asChild>
+    <Button className="w-full">Done</Button>
+  </SheetClose>
+</SheetFooter>
+// Custom layout with multiple action groups
+<SheetFooter className="flex-row justify-between">
+  <Button variant="ghost">Reset</Button>
+  <div className="flex gap-2">
+    <SheetClose asChild>
+      <Button variant="outline">Cancel</Button>
+    </SheetClose>
+    <Button>Save</Button>
+  </div>
+</SheetFooter>
+// Footer with destructive action
+<SheetFooter>
+  <Button variant="destructive">Delete Account</Button>
+  <SheetClose asChild>
+    <Button variant="outline">Keep Account</Button>
+  </SheetClose>
+</SheetFooter>
+```

package/.llm/sheet-header.llm.md

@@ -0,0 +1,52 @@
+# SheetHeader
+
+**Type**: component
+
+SheetHeader - Header section for sheet content A container for the sheet's title and description, positioned at the top of the sheet content. Provides consistent spacing and layout for sheet headers. Should contain SheetTitle and optionally SheetDescription for proper accessibility and semantic structure.
+
+## JSX Usage
+
+```jsx
+import { SheetHeader } from '@neynar/ui';
+
+<SheetHeader
+  className="value"
+>
+  {/* Your content here */}
+</SheetHeader>
+```
+
+## Component Props
+
+### className
+- **Type**: `string`
+- **Required**: No
+- **Description**: Additional CSS classes for styling customization
+
+### children
+- **Type**: `React.ReactNode`
+- **Required**: No
+- **Description**: Header content (typically SheetTitle and SheetDescription)
+
+## Examples
+
+```tsx
+// Complete header with title and description
+<SheetHeader>
+  <SheetTitle>Edit Profile</SheetTitle>
+  <SheetDescription>
+    Make changes to your profile information.
+  </SheetDescription>
+</SheetHeader>
+// Header with title only
+<SheetHeader>
+  <SheetTitle>Quick Actions</SheetTitle>
+</SheetHeader>
+// With custom styling and border
+<SheetHeader className="border-b pb-4 mb-4">
+  <SheetTitle>Advanced Settings</SheetTitle>
+  <SheetDescription>
+    Configure advanced options for your account.
+  </SheetDescription>
+</SheetHeader>
+```

package/.llm/sheet-title.llm.md

@@ -0,0 +1,53 @@
+# SheetTitle
+
+**Type**: component
+
+SheetTitle - Title element for the sheet The main heading for the sheet content. Provides proper semantic heading and accessibility labeling for screen readers. Should be used within SheetHeader. This component is required for proper accessibility - every sheet must have a title.
+
+## JSX Usage
+
+```jsx
+import { SheetTitle } from '@neynar/ui';
+
+<SheetTitle
+  asChild={true}
+  className="value"
+>
+  {/* Your content here */}
+</SheetTitle>
+```
+
+## Component Props
+
+### asChild
+- **Type**: `boolean`
+- **Required**: No
+- **Description**: When true, merges props with child element instead of rendering an h2
+
+### className
+- **Type**: `string`
+- **Required**: No
+- **Description**: Additional CSS classes for styling customization
+
+### children
+- **Type**: `React.ReactNode`
+- **Required**: No
+- **Description**: Title text content
+
+## Examples
+
+```tsx
+// Standard usage in header
+<SheetHeader>
+  <SheetTitle>Edit Profile</SheetTitle>
+  <SheetDescription>Update your profile information.</SheetDescription>
+</SheetHeader>
+// With custom styling
+<SheetTitle className="text-lg text-blue-600">Settings</SheetTitle>
+// As a custom heading level
+<SheetTitle asChild>
+  <h1 className="text-2xl font-bold">Important Notice</h1>
+</SheetTitle>
+// Dynamic title content
+<SheetTitle>Edit {selectedUser?.name || 'User'}</SheetTitle>
+```