@neynar/ui 0.3.0 → 0.4.0

package/.llm/popover.llm.md

@@ -0,0 +1,116 @@
+# Popover
+
+**Type**: component
+
+Popover displays rich content in a portal, triggered by a button A versatile floating panel component built on Radix UI primitives that displays interactive content without navigating away from the current context. Unlike tooltips, popovers support complex layouts, forms, and user interactions while maintaining proper focus management and accessibility standards.
+
+## JSX Usage
+
+```jsx
+import { Popover } from '@neynar/ui';
+
+<Popover
+  open={true}
+  onOpenChange={handleOpenChange}
+  defaultOpen={true}
+  modal={true}
+  dir={value}
+>
+  {/* Your content here */}
+</Popover>
+```
+
+## Component Props
+
+### open
+- **Type**: `boolean`
+- **Required**: No
+- **Description**: No description available
+
+### onOpenChange
+- **Type**: `(open: boolean) => void`
+- **Required**: No
+- **Description**: No description available
+
+### defaultOpen
+- **Type**: `boolean`
+- **Required**: No
+- **Description**: No description available
+
+### modal
+- **Type**: `boolean`
+- **Required**: No
+- **Description**: No description available
+
+### dir
+- **Type**: `"ltr" | "rtl"`
+- **Required**: No
+- **Description**: No description available
+
+### children
+- **Type**: `React.ReactNode`
+- **Required**: No
+- **Description**: No description available
+
+## Examples
+
+### Example 1
+```tsx
+// Basic popover with information
+<Popover>
+  <PopoverTrigger asChild>
+    <Button variant="outline">Open popover</Button>
+  </PopoverTrigger>
+  <PopoverContent>
+    <div className="grid gap-4">
+      <h4 className="font-medium leading-none">Dimensions</h4>
+      <p className="text-sm text-muted-foreground">
+        Set the dimensions for the layer.
+      </p>
+    </div>
+  </PopoverContent>
+</Popover>
+```
+### Example 2
+```tsx
+// Controlled popover with form interactions
+const [open, setOpen] = useState(false);
+<Popover open={open} onOpenChange={setOpen}>
+  <PopoverTrigger asChild>
+    <Button>Settings</Button>
+  </PopoverTrigger>
+  <PopoverContent className="w-80">
+    <div className="grid gap-4">
+      <div className="space-y-2">
+        <h4 className="font-medium leading-none">Settings</h4>
+        <p className="text-sm text-muted-foreground">
+          Configure your preferences
+        </p>
+      </div>
+      <div className="grid gap-2">
+        <Label htmlFor="width">Width</Label>
+        <Input id="width" defaultValue="100%" />
+      </div>
+    </div>
+  </PopoverContent>
+</Popover>
+```
+### Example 3
+```tsx
+// Positioned popover with custom alignment
+<Popover>
+  <PopoverTrigger asChild>
+    <Button variant="ghost" size="icon">
+      <HelpCircle className="h-4 w-4" />
+    </Button>
+  </PopoverTrigger>
+  <PopoverContent side="top" align="start" className="w-80">
+    <div className="space-y-2">
+      <h4 className="font-medium">Help Information</h4>
+      <p className="text-sm text-muted-foreground">
+        Additional context and helpful tips for this feature.
+      </p>
+    </div>
+  </PopoverContent>
+</Popover>
+```

package/.llm/progress.llm.md

@@ -0,0 +1,76 @@
+# Progress
+
+**Type**: component
+
+Progress - Visual progress indicator for tasks and operations A customizable progress bar component built on Radix UI Progress primitive that displays the completion status of tasks, file uploads, multi-step processes, and other operations requiring user feedback. Features smooth animations, accessibility support, and flexible styling options.
+
+## JSX Usage
+
+```jsx
+import { Progress } from '@neynar/ui';
+
+<Progress
+  value={value}
+  max={0}
+  getValueLabel={() => {}}
+  className="value"
+  asChild={true}
+  "aria-label"="value"
+  "aria-valuetext"="value"
+  "aria-describedby"="value"
+  "aria-labelledby"="value"
+  id="value"
+/>
+```
+
+## Component Props
+
+### value
+- **Type**: `number | null`
+- **Required**: No
+- **Description**: No description available
+
+### max
+- **Type**: `number`
+- **Required**: No
+- **Description**: No description available
+
+### getValueLabel
+- **Type**: `(value: number, max: number) => string`
+- **Required**: No
+- **Description**: No description available
+
+### className
+- **Type**: `string`
+- **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-valuetext"
+- **Type**: `string`
+- **Required**: No
+- **Description**: No description available
+
+### "aria-describedby"
+- **Type**: `string`
+- **Required**: No
+- **Description**: No description available
+
+### "aria-labelledby"
+- **Type**: `string`
+- **Required**: No
+- **Description**: No description available
+
+### id
+- **Type**: `string`
+- **Required**: No
+- **Description**: No description available

package/.llm/radio-group-indicator.llm.md

@@ -0,0 +1,28 @@
+# RadioGroupIndicator
+
+**Type**: component
+
+Visual indicator shown when a RadioGroupItem is in the checked state RadioGroupIndicator automatically appears inside RadioGroupItem when that item is selected. It provides the visual feedback for the checked state using a filled circle icon. The indicator is automatically managed by the RadioGroupItem and only renders when checked. This component is typically not used directly but is included in RadioGroupItem. It can be customized or replaced using the asChild pattern if needed.
+
+## JSX Usage
+
+```jsx
+import { RadioGroupIndicator } from '@neynar/ui';
+
+<RadioGroupIndicator
+  forceMount={true}
+  asChild={true}
+/>
+```
+
+## Component Props
+
+### forceMount
+- **Type**: `boolean`
+- **Required**: No
+- **Description**: Used to force mounting when more control is needed. Useful when controlling animation with React animation libraries
+
+### asChild
+- **Type**: `boolean`
+- **Required**: No
+- **Description**: Change the default rendered element for the one passed as a child

package/.llm/radio-group-item.llm.md

@@ -0,0 +1,40 @@
+# RadioGroupItem
+
+**Type**: component
+
+Individual radio button item for use within RadioGroup RadioGroupItem represents a single selectable option in a radio group. Must be used within a RadioGroup component and should be paired with a Label for proper accessibility. The component automatically handles visual states including checked, unchecked, focused, and disabled. It includes a built-in indicator that displays when the item is selected. Each radio item requires a unique value prop that identifies it within the group. The component forwards all standard button attributes and supports custom styling via className.
+
+## JSX Usage
+
+```jsx
+import { RadioGroupItem } from '@neynar/ui';
+
+<RadioGroupItem
+  value="value"
+  disabled={true}
+  required={true}
+  asChild={true}
+/>
+```
+
+## Component Props
+
+### value
+- **Type**: `string`
+- **Required**: Yes
+- **Description**: The value given as data when submitted with a name (required)
+
+### disabled
+- **Type**: `boolean`
+- **Required**: No
+- **Description**: When true, prevents the user from interacting with the item
+
+### required
+- **Type**: `boolean`
+- **Required**: No
+- **Description**: When true, indicates that the user must check the item before the owning form can be submitted
+
+### asChild
+- **Type**: `boolean`
+- **Required**: No
+- **Description**: Change the default rendered element for the one passed as a child

package/.llm/radio-group.llm.md

@@ -0,0 +1,76 @@
+# RadioGroup
+
+**Type**: component
+
+A radio group component for single selection from multiple options RadioGroup allows users to select exactly one option from a set of mutually exclusive choices. Built on Radix UI RadioGroup primitives with enhanced accessibility and keyboard navigation. Each radio group should contain RadioGroupItem components paired with Labels for proper accessibility. The component follows the WAI-ARIA Radio Group design pattern and uses roving tabindex to manage focus movement among radio items. It provides comprehensive keyboard navigation with arrow keys and supports both controlled and uncontrolled usage patterns.
+
+## JSX Usage
+
+```jsx
+import { RadioGroup } from '@neynar/ui';
+
+<RadioGroup
+  defaultValue="value"
+  value="value"
+  onValueChange={handleValueChange}
+  disabled={true}
+  name="value"
+  required={true}
+  orientation={value}
+  dir={value}
+  loop={true}
+  asChild={true}
+/>
+```
+
+## Component Props
+
+### defaultValue
+- **Type**: `string`
+- **Required**: No
+- **Description**: The value of the radio item that should be checked when initially rendered. Use when you do not need to control the checked state
+
+### value
+- **Type**: `string`
+- **Required**: No
+- **Description**: The controlled value of the radio item to check. Should be used in conjunction with onValueChange
+
+### onValueChange
+- **Type**: `(value: string) => void`
+- **Required**: No
+- **Description**: Event handler called when the value changes
+
+### disabled
+- **Type**: `boolean`
+- **Required**: No
+- **Description**: When true, prevents the user from interacting with the radio group
+
+### name
+- **Type**: `string`
+- **Required**: No
+- **Description**: The name of the group. Submitted with its owning form as part of a name/value pair
+
+### required
+- **Type**: `boolean`
+- **Required**: No
+- **Description**: When true, indicates that the user must check a radio item before the owning form can be submitted
+
+### orientation
+- **Type**: `"horizontal" | "vertical"`
+- **Required**: No
+- **Description**: The orientation of the component, which determines how focus moves
+
+### dir
+- **Type**: `"ltr" | "rtl"`
+- **Required**: No
+- **Description**: The reading direction of the radio group. If omitted, assumes LTR reading mode
+
+### loop
+- **Type**: `boolean`
+- **Required**: No
+- **Description**: When true, keyboard navigation will loop from last item to first, and vice versa
+
+### asChild
+- **Type**: `boolean`
+- **Required**: No
+- **Description**: Change the default rendered element for the one passed as a child

package/.llm/resizable-handle.llm.md

@@ -0,0 +1,156 @@
+# ResizableHandle
+
+**Type**: component
+
+Interactive handle for resizing panels with full keyboard and pointer support ResizableHandle provides the draggable area between panels that allows users to resize them via mouse, touch, or keyboard interaction. Supports optional visual grip indicators, custom hit areas, and comprehensive event callbacks for advanced interaction patterns. Automatically adapts styling based on panel group direction.
+
+## JSX Usage
+
+```jsx
+import { ResizableHandle } from '@neynar/ui';
+
+<ResizableHandle
+  withHandle={true}
+  id={value}
+  disabled={true}
+  hitAreaMargins={value}
+  onDragging={handleDragging}
+  onBlur={handleBlur}
+  onClick={handleClick}
+  onFocus={handleFocus}
+  onPointerDown={handlePointerDown}
+  onPointerUp={handlePointerUp}
+  tabIndex={0}
+  tagName={value}
+  className="value"
+  style={value}
+>
+  {/* Your content here */}
+</ResizableHandle>
+```
+
+## Component Props
+
+### withHandle
+- **Type**: `boolean`
+- **Required**: No
+- **Description**: Whether to display built-in visual grip indicator
+
+### id
+- **Type**: `string | null`
+- **Required**: No
+- **Description**: Unique identifier for the resize handle
+
+### disabled
+- **Type**: `boolean`
+- **Required**: No
+- **Description**: Whether handle is disabled and non-interactive
+
+### hitAreaMargins
+- **Type**: `{
+    coarse: number;
+    fine: number;
+  }`
+- **Required**: No
+- **Description**: Custom hit area margins for easier grabbing (coarse: touch devices, fine: mouse)
+
+### onDragging
+- **Type**: `(isDragging: boolean) => void`
+- **Required**: No
+- **Description**: Callback fired when drag state changes with boolean indicating if currently dragging
+
+### onBlur
+- **Type**: `() => void`
+- **Required**: No
+- **Description**: Callback fired when handle loses keyboard focus
+
+### onClick
+- **Type**: `() => void`
+- **Required**: No
+- **Description**: Callback fired when handle is clicked
+
+### onFocus
+- **Type**: `() => void`
+- **Required**: No
+- **Description**: Callback fired when handle receives keyboard focus
+
+### onPointerDown
+- **Type**: `() => void`
+- **Required**: No
+- **Description**: Callback fired when pointer/touch starts on handle
+
+### onPointerUp
+- **Type**: `() => void`
+- **Required**: No
+- **Description**: Callback fired when pointer/touch ends on handle
+
+### tabIndex
+- **Type**: `number`
+- **Required**: No
+- **Description**: Tab order for keyboard navigation (0 makes it focusable)
+
+### tagName
+- **Type**: `keyof React.JSX.IntrinsicElements`
+- **Required**: No
+- **Description**: No description available
+
+### className
+- **Type**: `string`
+- **Required**: No
+- **Description**: Additional CSS classes for custom styling
+
+### style
+- **Type**: `React.CSSProperties`
+- **Required**: No
+- **Description**: No description available
+
+### children
+- **Type**: `React.ReactNode`
+- **Required**: No
+- **Description**: Custom handle content (overrides withHandle prop)
+
+## Examples
+
+### Example 1
+```tsx
+// Basic invisible handle (common for clean designs)
+<ResizableHandle />
+```
+### Example 2
+```tsx
+// Handle with visual grip indicator
+<ResizableHandle withHandle />
+```
+### Example 3
+```tsx
+// Custom styled handle with interaction callbacks
+<ResizableHandle
+  withHandle
+  className="bg-blue-200 hover:bg-blue-300 transition-colors"
+  onDragging={(isDragging) => {
+    console.log(isDragging ? 'Started dragging' : 'Stopped dragging');
+  }}
+  hitAreaMargins={{ coarse: 20, fine: 10 }}
+/>
+```
+### Example 4
+```tsx
+// Disabled handle for non-interactive layouts
+<ResizableHandle
+  disabled
+  className="opacity-50 cursor-not-allowed"
+/>
+```
+### Example 5
+```tsx
+// Custom handle with event handling
+<ResizableHandle
+  id="main-handle"
+  onFocus={() => console.log('Handle focused')}
+  onBlur={() => console.log('Handle blurred')}
+  onClick={() => console.log('Handle clicked')}
+  tabIndex={0}
+>
+  <CustomGripIcon />
+</ResizableHandle>
+```

package/.llm/resizable-panel-group.llm.md

@@ -0,0 +1,149 @@
+# ResizablePanelGroup
+
+**Type**: component
+
+Container for creating resizable panel groups with full keyboard accessibility ResizablePanelGroup provides a flexible container for organizing multiple resizable panels that can be resized by dragging handles between them or using keyboard navigation. Built on react-resizable-panels with enhanced styling, accessibility, and persistence features. Supports both horizontal and vertical layouts with automatic layout saving and restoration.
+
+## JSX Usage
+
+```jsx
+import { ResizablePanelGroup } from '@neynar/ui';
+
+<ResizablePanelGroup
+  direction={value}
+  autoSaveId={value}
+  id={value}
+  keyboardResizeBy={value}
+  onLayout={handleLayout}
+  storage={value}
+  dir={value}
+  tagName={value}
+  className="value"
+  style={value}
+>
+  {/* Your content here */}
+</ResizablePanelGroup>
+```
+
+## Component Props
+
+### direction
+- **Type**: `"horizontal" | "vertical"`
+- **Required**: Yes
+- **Description**: Layout direction: "horizontal" for side-by-side, "vertical" for top-to-bottom
+
+### autoSaveId
+- **Type**: `string | null`
+- **Required**: No
+- **Description**: Unique identifier for automatically saving/restoring panel layouts
+
+### id
+- **Type**: `string | null`
+- **Required**: No
+- **Description**: No description available
+
+### keyboardResizeBy
+- **Type**: `number | null`
+- **Required**: No
+- **Description**: Increment in percentage points for keyboard-based resizing
+
+### onLayout
+- **Type**: `(layout: number[]) => void`
+- **Required**: No
+- **Description**: Callback fired when panel sizes change, receives array of percentages
+
+### storage
+- **Type**: `{
+    getItem(name: string): string | null;
+    setItem(name: string, value: string): void;
+  }`
+- **Required**: No
+- **Description**: Custom storage implementation for layout persistence (defaults to localStorage)
+
+### dir
+- **Type**: `"auto" | "ltr" | "rtl"`
+- **Required**: No
+- **Description**: Text direction for RTL/LTR layout support
+
+### tagName
+- **Type**: `keyof React.JSX.IntrinsicElements`
+- **Required**: No
+- **Description**: No description available
+
+### className
+- **Type**: `string`
+- **Required**: No
+- **Description**: Additional CSS classes for custom styling
+
+### style
+- **Type**: `React.CSSProperties`
+- **Required**: No
+- **Description**: No description available
+
+### children
+- **Type**: `React.ReactNode`
+- **Required**: No
+- **Description**: ResizablePanel and ResizableHandle components
+
+## Examples
+
+### Example 1
+```tsx
+// Basic horizontal layout
+<ResizablePanelGroup direction="horizontal" className="h-full">
+  <ResizablePanel defaultSize={50}>
+    <div className="p-4">Left panel content</div>
+  </ResizablePanel>
+  <ResizableHandle />
+  <ResizablePanel defaultSize={50}>
+    <div className="p-4">Right panel content</div>
+  </ResizablePanel>
+</ResizablePanelGroup>
+```
+### Example 2
+```tsx
+// Vertical layout with visual handles
+<ResizablePanelGroup direction="vertical" className="min-h-[400px]">
+  <ResizablePanel defaultSize={30}>
+    <header className="p-4">Header content</header>
+  </ResizablePanel>
+  <ResizableHandle withHandle />
+  <ResizablePanel defaultSize={70}>
+    <main className="p-4">Main content area</main>
+  </ResizablePanel>
+</ResizablePanelGroup>
+```
+### Example 3
+```tsx
+// Persistent layout with auto-save
+<ResizablePanelGroup
+  direction="horizontal"
+  autoSaveId="main-layout"
+  onLayout={(sizes) => console.log('Layout changed:', sizes)}
+>
+  <ResizablePanel defaultSize={25} minSize={20} maxSize={40}>
+    <nav>Sidebar (20-40%)</nav>
+  </ResizablePanel>
+  <ResizableHandle withHandle />
+  <ResizablePanel defaultSize={75} minSize={60}>
+    <main>Content area (min 60%)</main>
+  </ResizablePanel>
+</ResizablePanelGroup>
+```
+### Example 4
+```tsx
+// Custom keyboard resize increment
+<ResizablePanelGroup
+  direction="horizontal"
+  keyboardResizeBy={5}
+  dir="ltr"
+>
+  <ResizablePanel defaultSize={50} id="left-panel">
+    <div>Panel content</div>
+  </ResizablePanel>
+  <ResizableHandle />
+  <ResizablePanel defaultSize={50} id="right-panel">
+    <div>Panel content</div>
+  </ResizablePanel>
+</ResizablePanelGroup>
+```