@neynar/ui 0.3.0 → 0.3.1

package/.llm/alert-dialog-description.llm.md

@@ -0,0 +1,53 @@
+# AlertDialogDescription
+
+**Type**: component
+
+Description text of the alert dialog Provides additional context and explanation for the alert or action. Should clearly explain the consequences of the action being confirmed. Automatically provides proper ARIA description via aria-describedby for screen readers. Can be omitted if aria-describedby is provided to Content.
+
+## JSX Usage
+
+```jsx
+import { AlertDialogDescription } from '@neynar/ui';
+
+<AlertDialogDescription
+  asChild={true}
+  className="value"
+/>
+```
+
+## Component Props
+
+### asChild
+- **Type**: `boolean`
+- **Required**: No
+- **Description**: Render as child element, merging props and behavior
+
+### className
+- **Type**: `string`
+- **Required**: No
+- **Description**: Additional CSS classes for custom styling
+
+## Examples
+
+```tsx
+// Standard descriptions
+<AlertDialogDescription>
+  This action cannot be undone. This will permanently delete your
+  account and remove your data from our servers.
+</AlertDialogDescription>
+<AlertDialogDescription>
+  You will be signed out of all devices and will need to sign in again
+  to access your account.
+</AlertDialogDescription>
+// Custom styling
+<AlertDialogDescription className="text-center text-lg">
+  Are you sure you want to continue?
+</AlertDialogDescription>
+// Composition with custom element
+<AlertDialogDescription asChild>
+  <p className="custom-description">
+    Custom description element
+  </p>
+</AlertDialogDescription>
+```
+/

package/.llm/alert-dialog-footer.llm.md

@@ -0,0 +1,41 @@
+# AlertDialogFooter
+
+**Type**: component
+
+Footer section of the alert dialog Contains the action buttons (cancel and confirm). Uses responsive layout with stacked buttons on mobile (cancel on top) and horizontal layout on larger screens (cancel on left, action on right). Should contain AlertDialogCancel and AlertDialogAction for proper UX.
+
+## JSX Usage
+
+```jsx
+import { AlertDialogFooter } from '@neynar/ui';
+
+<AlertDialogFooter
+  className="value"
+/>
+```
+
+## Component Props
+
+### className
+- **Type**: `string`
+- **Required**: No
+- **Description**: Additional CSS classes for custom styling
+
+## Examples
+
+```tsx
+<AlertDialogFooter>
+  <AlertDialogCancel>Cancel</AlertDialogCancel>
+  <AlertDialogAction>Delete Account</AlertDialogAction>
+</AlertDialogFooter>
+// Custom button order
+<AlertDialogFooter className="flex-row">
+  <AlertDialogAction>Continue</AlertDialogAction>
+  <AlertDialogCancel>Go Back</AlertDialogCancel>
+</AlertDialogFooter>
+// Single action footer
+<AlertDialogFooter>
+  <AlertDialogAction>I Understand</AlertDialogAction>
+</AlertDialogFooter>
+```
+/

package/.llm/alert-dialog-header.llm.md

@@ -0,0 +1,39 @@
+# AlertDialogHeader
+
+**Type**: component
+
+Header section of the alert dialog Contains the title and description of the alert dialog. Provides consistent spacing and alignment, with responsive text alignment (centered on mobile, left-aligned on larger screens). Should contain AlertDialogTitle and optionally AlertDialogDescription for proper accessibility.
+
+## JSX Usage
+
+```jsx
+import { AlertDialogHeader } from '@neynar/ui';
+
+<AlertDialogHeader
+  className="value"
+/>
+```
+
+## Component Props
+
+### className
+- **Type**: `string`
+- **Required**: No
+- **Description**: Additional CSS classes for custom styling
+
+## Examples
+
+```tsx
+<AlertDialogHeader>
+  <AlertDialogTitle>Delete Account</AlertDialogTitle>
+  <AlertDialogDescription>
+    This will permanently delete your account and all associated data.
+    This action cannot be undone.
+  </AlertDialogDescription>
+</AlertDialogHeader>
+// Custom styling
+<AlertDialogHeader className="text-left">
+  <AlertDialogTitle>Custom Header</AlertDialogTitle>
+</AlertDialogHeader>
+```
+/

package/.llm/alert-dialog-overlay.llm.md

@@ -0,0 +1,44 @@
+# AlertDialogOverlay
+
+**Type**: component
+
+Overlay backdrop behind the alert dialog A semi-transparent backdrop that covers the entire viewport when the dialog is open. Provides visual separation and prevents interaction with background content. Includes smooth fade in/out animations and proper z-index stacking.
+
+## JSX Usage
+
+```jsx
+import { AlertDialogOverlay } from '@neynar/ui';
+
+<AlertDialogOverlay
+  asChild={true}
+  forceMount={true}
+  className="value"
+/>
+```
+
+## Component Props
+
+### asChild
+- **Type**: `boolean`
+- **Required**: No
+- **Description**: Render as child element, merging props and behavior
+
+### forceMount
+- **Type**: `boolean`
+- **Required**: No
+- **Description**: Force mount the component even when dialog is closed
+
+### className
+- **Type**: `string`
+- **Required**: No
+- **Description**: Additional CSS classes for custom styling
+
+## Examples
+
+```tsx
+// Custom overlay styling
+<AlertDialogOverlay className="bg-black/80" />
+// Force mounted overlay
+<AlertDialogOverlay forceMount className="custom-backdrop" />
+```
+/

package/.llm/alert-dialog-portal.llm.md

@@ -0,0 +1,41 @@
+# AlertDialogPortal
+
+**Type**: component
+
+Portal component for rendering dialog outside normal DOM tree Renders the alert dialog content into a portal, typically at the end of the document body. This ensures the dialog appears above other content and is properly accessible. Usually not used directly - AlertDialogContent includes this automatically.
+
+## JSX Usage
+
+```jsx
+import { AlertDialogPortal } from '@neynar/ui';
+
+<AlertDialogPortal
+  forceMount={true}
+  container={value}
+/>
+```
+
+## Component Props
+
+### forceMount
+- **Type**: `boolean`
+- **Required**: No
+- **Description**: Force mount the component even when dialog is closed
+
+### container
+- **Type**: `HTMLElement`
+- **Required**: No
+- **Description**: Container element to portal into (defaults to document.body)
+
+## Examples
+
+```tsx
+// Custom portal container
+<AlertDialogPortal container={customContainer}>
+  <AlertDialogOverlay />
+  <AlertDialogPrimitive.Content>
+    // content
+  </AlertDialogPrimitive.Content>
+</AlertDialogPortal>
+```
+/

package/.llm/alert-dialog-title.llm.md

@@ -0,0 +1,46 @@
+# AlertDialogTitle
+
+**Type**: component
+
+Title heading of the alert dialog The main heading that describes the alert or action being confirmed. Automatically provides proper ARIA labeling for screen readers via aria-labelledby. Should be concise and clearly state what the dialog is asking.
+
+## JSX Usage
+
+```jsx
+import { AlertDialogTitle } from '@neynar/ui';
+
+<AlertDialogTitle
+  asChild={true}
+  className="value"
+/>
+```
+
+## Component Props
+
+### asChild
+- **Type**: `boolean`
+- **Required**: No
+- **Description**: Render as child element, merging props and behavior
+
+### className
+- **Type**: `string`
+- **Required**: No
+- **Description**: Additional CSS classes for custom styling
+
+## Examples
+
+```tsx
+// Standard titles
+<AlertDialogTitle>Are you absolutely sure?</AlertDialogTitle>
+<AlertDialogTitle>Delete Account</AlertDialogTitle>
+<AlertDialogTitle>Confirm Sign Out</AlertDialogTitle>
+// Custom styling
+<AlertDialogTitle className="text-red-600 text-xl">
+  Destructive Action
+</AlertDialogTitle>
+// Composition with custom element
+<AlertDialogTitle asChild>
+  <h1 className="custom-title">Custom Title Element</h1>
+</AlertDialogTitle>
+```
+/

package/.llm/alert-dialog-trigger.llm.md

@@ -0,0 +1,40 @@
+# AlertDialogTrigger
+
+**Type**: component
+
+Trigger element that opens the alert dialog The element that opens the alert dialog when activated. Usually a button, but can be any interactive element through composition. When opened, the dialog will trap focus and require user interaction before continuing.
+
+## JSX Usage
+
+```jsx
+import { AlertDialogTrigger } from '@neynar/ui';
+
+<AlertDialogTrigger
+  asChild={true}
+/>
+```
+
+## Component Props
+
+### asChild
+- **Type**: `boolean`
+- **Required**: No
+- **Description**: Render as child element, merging props and behavior
+
+## Examples
+
+```tsx
+// Direct usage
+<AlertDialogTrigger>
+  Delete Account
+</AlertDialogTrigger>
+// Composition with Button component
+<AlertDialogTrigger asChild>
+  <Button variant="destructive">Delete Account</Button>
+</AlertDialogTrigger>
+// Composition with custom element
+<AlertDialogTrigger asChild>
+  <button className="custom-trigger">Custom Trigger</button>
+</AlertDialogTrigger>
+```
+/

package/.llm/alert-dialog.llm.md

@@ -0,0 +1,80 @@
+# AlertDialog
+
+**Type**: component
+
+Alert dialog component for critical confirmations and destructive actions A specialized modal dialog built on Radix UI Alert Dialog primitives that interrupts users with important information requiring immediate acknowledgment or decision. Unlike regular dialogs, alert dialogs cannot be dismissed by clicking outside and focus the action button by default for critical decisions. Based on the WAI-ARIA Alert Dialog design pattern, this component is specifically designed for destructive actions, confirmations, or critical warnings that need immediate attention before the user can continue.
+
+## JSX Usage
+
+```jsx
+import { AlertDialog } from '@neynar/ui';
+
+<AlertDialog
+  defaultOpen={true}
+  open={true}
+  onOpenChange={handleOpenChange}
+/>
+```
+
+## Component Props
+
+### 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
+
+## Examples
+
+### Example 1
+```tsx
+// Basic destructive confirmation
+<AlertDialog>
+  <AlertDialogTrigger asChild>
+    <Button variant="destructive">Delete Account</Button>
+  </AlertDialogTrigger>
+  <AlertDialogContent>
+    <AlertDialogHeader>
+      <AlertDialogTitle>Are you absolutely sure?</AlertDialogTitle>
+      <AlertDialogDescription>
+        This action cannot be undone. This will permanently delete
+        your account and remove your data from our servers.
+      </AlertDialogDescription>
+    </AlertDialogHeader>
+    <AlertDialogFooter>
+      <AlertDialogCancel>Cancel</AlertDialogCancel>
+      <AlertDialogAction>Delete Account</AlertDialogAction>
+    </AlertDialogFooter>
+  </AlertDialogContent>
+</AlertDialog>
+```
+### Example 2
+```tsx
+// Simple confirmation
+<AlertDialog>
+  <AlertDialogTrigger asChild>
+    <Button variant="outline">Sign Out</Button>
+  </AlertDialogTrigger>
+  <AlertDialogContent>
+    <AlertDialogHeader>
+      <AlertDialogTitle>Sign Out</AlertDialogTitle>
+      <AlertDialogDescription>
+        Are you sure you want to sign out of your account?
+      </AlertDialogDescription>
+    </AlertDialogHeader>
+    <AlertDialogFooter>
+      <AlertDialogCancel>Cancel</AlertDialogCancel>
+      <AlertDialogAction>Sign Out</AlertDialogAction>
+    </AlertDialogFooter>
+  </AlertDialogContent>
+</AlertDialog>
+```

package/.llm/alert-title.llm.md

@@ -0,0 +1,48 @@
+# AlertTitle
+
+**Type**: component
+
+AlertTitle - The title/heading component for alerts Provides a prominent title or heading for the alert message. Automatically styled with medium font weight, line clamping, and proper grid positioning. Used to give context and immediate recognition of the alert's purpose. ## Features - Medium font weight for visual hierarchy - Single line with overflow handling (line-clamp-1) - Consistent minimum height for layout stability - Proper grid positioning (col-start-2) for icon layout - Tight character spacing (tracking-tight) for readability
+
+## JSX Usage
+
+```jsx
+import { AlertTitle } from '@neynar/ui';
+
+<AlertTitle
+  className="value"
+>
+  {/* Your content here */}
+</AlertTitle>
+```
+
+## Component Props
+
+### className
+- **Type**: `string`
+- **Required**: No
+- **Description**: Additional CSS classes to apply
+
+### children
+- **Type**: `React.ReactNode`
+- **Required**: No
+- **Description**: Title text content
+
+## Examples
+
+### Example 1
+```tsx
+<Alert>
+  <Info className="size-4" />
+  <AlertTitle>Payment Successful</AlertTitle>
+  <AlertDescription>Your payment has been processed.</AlertDescription>
+</Alert>
+```
+### Example 2
+```tsx
+// Title-only alert (no description)
+<Alert variant="destructive">
+  <AlertCircle className="size-4" />
+  <AlertTitle>Connection Failed</AlertTitle>
+</Alert>
+```

package/.llm/alert.llm.md

@@ -0,0 +1,92 @@
+# Alert
+
+**Type**: component
+
+Alert - Display important messages and notifications to users A flexible alert component for displaying important messages, notifications, and status updates. Built with shadcn/ui design patterns and Tailwind CSS. Alerts are used to communicate critical information that requires user attention and potentially action. ## When to use - System-wide notifications and announcements - Form validation errors and success messages - Important warnings that need persistent visibility - Status updates that don't require immediate action - Progress indicators and completion messages ## Features - Two built-in variants: `default` and `destructive` - Automatic icon grid layout with proper spacing using CSS Grid - Semantic HTML with proper ARIA attributes (`role="alert"`) - Responsive design with consistent spacing - Dark mode support via CSS custom properties - Composition pattern with AlertTitle and AlertDescription - Support for custom styling through className prop - Icon-aware layout that adapts to presence of SVG icons ## Design Philosophy Follows the shadcn/ui principle of providing unstyled, accessible components that can be easily customized. The alert uses CSS Grid for intelligent layout that automatically adjusts based on whether an icon is present.
+
+## JSX Usage
+
+```jsx
+import { Alert } from '@neynar/ui';
+
+<Alert
+  variant={value}
+  className="value"
+>
+  {/* Your content here */}
+</Alert>
+```
+
+## Component Props
+
+### variant
+- **Type**: `"default" | "destructive"`
+- **Required**: No
+- **Description**: Visual style variant determining colors and emphasis
+
+### className
+- **Type**: `string`
+- **Required**: No
+- **Description**: Additional CSS classes to merge with default styles
+
+### children
+- **Type**: `React.ReactNode`
+- **Required**: No
+- **Description**: Alert content including optional icon, title, and description
+
+## Examples
+
+### Example 1
+```tsx
+// Basic informational alert
+<Alert>
+  <Info className="size-4" />
+  <AlertTitle>Heads up!</AlertTitle>
+  <AlertDescription>
+    You can add components to your app using the cli.
+  </AlertDescription>
+</Alert>
+```
+### Example 2
+```tsx
+// Destructive error alert
+import { AlertCircle } from "lucide-react";
+<Alert variant="destructive">
+  <AlertCircle className="size-4" />
+  <AlertTitle>Error</AlertTitle>
+  <AlertDescription>
+    Your session has expired. Please log in again.
+  </AlertDescription>
+</Alert>
+```
+### Example 3
+```tsx
+// Custom styled success alert
+<Alert className="border-green-200 bg-green-50 text-green-800 dark:border-green-800 dark:bg-green-950 dark:text-green-200">
+  <CheckCircle className="size-4" />
+  <AlertTitle>Success</AlertTitle>
+  <AlertDescription>
+    Your changes have been saved successfully.
+  </AlertDescription>
+</Alert>
+```
+### Example 4
+```tsx
+// Alert without icon
+<Alert>
+  <AlertTitle>Simple Notice</AlertTitle>
+  <AlertDescription>
+    This alert doesn't use an icon.
+  </AlertDescription>
+</Alert>
+```
+### Example 5
+```tsx
+// Alert with only description
+<Alert variant="destructive">
+  <AlertCircle className="size-4" />
+  <AlertDescription>
+    Something went wrong. Please try again.
+  </AlertDescription>
+</Alert>
+```

package/.llm/aspect-ratio.llm.md

@@ -0,0 +1,41 @@
+# AspectRatio
+
+**Type**: component
+
+AspectRatio - Maintains consistent width-to-height ratios for content A foundational layout component that preserves specific aspect ratios regardless of container size. Essential for responsive images, videos, and media content that needs consistent proportions across different screen sizes. Built on Radix UI primitives with zero JavaScript runtime overhead. This component creates a CSS-based aspect ratio container using the modern `aspect-ratio` property, ensuring content maintains its intended proportions without layout shifts or JavaScript calculations. The component acts as a constraint wrapper that forces its children to maintain the specified ratio.
+
+## JSX Usage
+
+```jsx
+import { AspectRatio } from '@neynar/ui';
+
+<AspectRatio
+  ratio={0}
+  className="value"
+  asChild={true}
+>
+  {/* Your content here */}
+</AspectRatio>
+```
+
+## Component Props
+
+### ratio
+- **Type**: `number`
+- **Required**: No
+- **Description**: The desired aspect ratio as width/height (e.g., 16/9, 4/3, 1)
+
+### children
+- **Type**: `React.ReactNode`
+- **Required**: No
+- **Description**: Content to be constrained within the aspect ratio
+
+### className
+- **Type**: `string`
+- **Required**: No
+- **Description**: Additional CSS classes for styling
+
+### asChild
+- **Type**: `boolean`
+- **Required**: No
+- **Description**: Merge props with child element instead of wrapping

package/.llm/avatar-fallback.llm.md

@@ -0,0 +1,41 @@
+# AvatarFallback
+
+**Type**: component
+
+AvatarFallback - Fallback content displayed when the avatar image is unavailable This component renders alternative content when the AvatarImage is loading, fails to load, or is not provided. It's built on Radix UI's Avatar.Fallback primitive and provides a visually appealing placeholder that maintains the avatar's design consistency. ## When AvatarFallback is Shown The fallback is automatically displayed in these scenarios: - **Image loading**: While the AvatarImage is being loaded - **Image error**: When the AvatarImage fails to load (broken URL, network error) - **No image**: When no AvatarImage component is provided - **Empty src**: When AvatarImage has no src prop or empty src ## Common Use Cases - **User initials**: Most common pattern (2-3 characters) - **Generic icons**: User, person, or company icons - **Brand initials**: For organization avatars - **Loading states**: With animations or loading indicators - **Placeholder content**: For new or anonymous users - **Custom graphics**: SVG icons or other visual elements ## Design Considerations - Uses muted background color for subtle appearance - Automatically centers content both horizontally and vertically - Inherits size and border radius from parent Avatar - Should complement the overall design system - Supports delay to prevent flash during fast image loads
+
+## JSX Usage
+
+```jsx
+import { AvatarFallback } from '@neynar/ui';
+
+<AvatarFallback
+  className="value"
+  delayMs={0}
+  asChild={true}
+>
+  {/* Your content here */}
+</AvatarFallback>
+```
+
+## Component Props
+
+### children
+- **Type**: `React.ReactNode`
+- **Required**: No
+- **Description**: The fallback content to display. Common patterns include user initials (2-3 characters), icons, or loading indicators
+
+### className
+- **Type**: `string`
+- **Required**: No
+- **Description**: Additional CSS classes. Use for custom background colors, text styling, or animations
+
+### delayMs
+- **Type**: `number`
+- **Required**: No
+- **Description**: Optional delay in milliseconds before showing the fallback. Useful for delaying rendering so it only appears for those with slower connections
+
+### asChild
+- **Type**: `boolean`
+- **Required**: No
+- **Description**: Change the default rendered element for the one passed as a child, merging their props and behavior

package/.llm/avatar-image.llm.md

@@ -0,0 +1,48 @@
+# AvatarImage
+
+**Type**: component
+
+AvatarImage - The image element component for displaying avatar pictures This component renders the actual avatar image and automatically handles loading states. It's built on Radix UI's Avatar.Image primitive which provides robust image loading behavior - when the image fails to load or is still loading, it remains hidden and the AvatarFallback will be displayed instead. ## Key Features - **Automatic loading state management**: Handles "idle", "loading", "loaded", and "error" states - **Graceful error handling**: Automatically falls back when images fail to load - **Proper aspect ratio maintenance**: Square aspect ratio maintained by default - **Flexible rendering**: Supports asChild for custom element composition - **Loading status callbacks**: Provides onLoadingStatusChange for custom loading logic - **Accessible implementation**: Proper alt text handling and ARIA support ## Loading States The component automatically manages these states: - **idle**: Initial state before loading begins - **loading**: Image is currently being loaded - **loaded**: Image has loaded successfully and is displayed - **error**: Image failed to load, fallback will be shown
+
+## JSX Usage
+
+```jsx
+import { AvatarImage } from '@neynar/ui';
+
+<AvatarImage
+  src="value"
+  alt="value"
+  className="value"
+  onLoadingStatusChange={handleLoadingStatusChange}
+  asChild={true}
+/>
+```
+
+## Component Props
+
+### src
+- **Type**: `string`
+- **Required**: No
+- **Description**: The URL of the image to display. Can be relative or absolute URL. When src changes, loading will restart
+
+### alt
+- **Type**: `string`
+- **Required**: No
+- **Description**: Descriptive alternative text for the image. Should describe the person or entity, not just "avatar" or "profile picture"
+
+### className
+- **Type**: `string`
+- **Required**: No
+- **Description**: Additional CSS classes to apply to the image element. Applied to the img element or asChild component
+
+### onLoadingStatusChange
+- **Type**: `(
+    status: "idle" | "loading" | "loaded" | "error",
+  ) => void`
+- **Required**: No
+- **Description**: Optional callback fired when the loading status changes. Receives status: "idle" | "loading" | "loaded" | "error"
+
+### asChild
+- **Type**: `boolean`
+- **Required**: No
+- **Description**: Change the default rendered element for the one passed as a child, merging their props and behavior