@neynar/ui 0.1.2 → 0.2.0

package/llm-docs/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-docs/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-docs/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-docs/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-docs/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

package/llm-docs/avatar.llm.md

@@ -0,0 +1,35 @@
+# Avatar
+
+**Type**: component
+
+Avatar - A flexible container for displaying user profile images with graceful fallback support The Avatar component is built on Radix UI's Avatar primitive and provides a robust solution for displaying user profile pictures throughout your application. It automatically handles image loading states and displays fallback content when images fail to load or are unavailable. This component follows the shadcn/ui design system principles and provides a consistent approach to user representation across all applications. ## Features - **Automatic loading states**: Seamlessly handles image loading and error states - **Graceful fallbacks**: Shows fallback content when images are unavailable - **Flexible sizing**: Easy customization through Tailwind CSS size utilities - **Shape variants**: Circular by default with support for rounded corners - **Accessibility first**: Built-in ARIA attributes and keyboard navigation - **Composable design**: Works with AvatarImage and AvatarFallback sub-components - **Polymorphic rendering**: Supports asChild prop for custom element rendering ## Common Use Cases - User profile displays in headers and navigation - Comment sections and author attribution - Team member listings and directories - Avatar groups with overlapping layouts - Organization logos and brand representation - Loading states and placeholder content ## Size Variants - `size-6` (24px) - Small avatars for dense layouts - `size-8` (32px) - Default size for most use cases - `size-10` (40px) - Medium avatars for lists - `size-12` (48px) - Large avatars for profiles - `size-16` (64px) - Extra large for main profile displays
+
+## JSX Usage
+
+```jsx
+import { Avatar } from '@neynar/ui';
+
+<Avatar
+  className="value"
+  asChild={true}
+>
+  {/* Your content here */}
+</Avatar>
+```
+
+## Component Props
+
+### className
+- **Type**: `string`
+- **Required**: No
+- **Description**: Additional CSS classes for styling. Common patterns include size utilities (size-6, size-8, size-10, size-12, size-16) and border radius overrides (rounded-lg, rounded-md, rounded-none)
+
+### children
+- **Type**: `React.ReactNode`
+- **Required**: No
+- **Description**: Should contain AvatarImage and AvatarFallback components for proper functionality
+
+### 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-docs/badge.llm.md

@@ -0,0 +1,108 @@
+# Badge
+
+**Type**: component
+
+Badge - Versatile status indicator component for labels, counts, and notifications A small status descriptor component that provides visual feedback about state, category, or importance of content. Built on Radix UI Slot primitives with accessibility-first design and support for multiple semantic variants and interactive states.
+
+## JSX Usage
+
+```jsx
+import { Badge } from '@neynar/ui';
+
+<Badge
+  variant={value}
+  className="value"
+  asChild={true}
+>
+  {/* Your content here */}
+</Badge>
+```
+
+## Component Props
+
+### variant
+- **Type**: `"default" | "secondary" | "destructive" | "outline"`
+- **Required**: No
+- **Description**: No description available
+
+### className
+- **Type**: `string`
+- **Required**: No
+- **Description**: No description available
+
+### children
+- **Type**: `React.ReactNode`
+- **Required**: No
+- **Description**: No description available
+
+### asChild
+- **Type**: `boolean`
+- **Required**: No
+- **Description**: No description available
+
+## Examples
+
+### Example 1
+```tsx
+// Basic status badges
+<Badge>New</Badge>
+<Badge variant="secondary">Draft</Badge>
+<Badge variant="destructive">Error</Badge>
+<Badge variant="outline">Pending</Badge>
+```
+### Example 2
+```tsx
+// Badge with icon content
+import { Check, AlertTriangle } from "lucide-react";
+<Badge>
+  <Check className="mr-1" />
+  Completed
+</Badge>
+<Badge variant="destructive">
+  <AlertTriangle className="mr-1" />
+  Failed
+</Badge>
+```
+### Example 3
+```tsx
+// Notification count badge
+<div className="relative inline-block">
+  <Bell className="h-6 w-6" />
+  <Badge className="absolute -top-2 -right-2 h-5 w-5 p-0 text-xs flex items-center justify-center">
+    3
+  </Badge>
+</div>
+```
+### Example 4
+```tsx
+// Interactive badge as link using asChild
+import Link from "next/link";
+<Badge asChild>
+  <Link href="/notifications" className="cursor-pointer">
+    3 new messages
+  </Link>
+</Badge>
+```
+### Example 5
+```tsx
+// Interactive badge as button
+<Badge asChild>
+  <button onClick={handleDismiss} className="cursor-pointer">
+    Dismiss Alert
+  </button>
+</Badge>
+```
+### Example 6
+```tsx
+// Removable tag badge with close button
+<Badge className="pr-1 gap-1">
+  React
+  <button
+    onClick={handleRemove}
+    className="ml-1 hover:bg-primary-foreground/20 rounded-full p-0.5"
+    aria-label="Remove React tag"
+  >
+    <X className="h-3 w-3" />
+  </button>
+</Badge>
+```

package/llm-docs/blockquote.llm.md

@@ -0,0 +1,122 @@
+# Blockquote
+
+**Type**: component
+
+Blockquote - Quoted text component for citations and excerpts Semantic blockquote element for extended quotations, testimonials, and excerpts. Features italic styling and left border for visual distinction.
+
+## JSX Usage
+
+```jsx
+import { Blockquote } from '@neynar/ui';
+
+<Blockquote
+  color={value}
+  align={value}
+  transform={value}
+  weight={value}
+  htmlFor="value"
+  asChild={true}
+  italic={true}
+  underline={true}
+  strikethrough={true}
+  truncate={true}
+  srOnly={true}
+  className="value"
+>
+  {/* Your content here */}
+</Blockquote>
+```
+
+## Component Props
+
+### color
+- **Type**: `| "default"
+    | "muted"
+    | "accent"
+    | "destructive"
+    | "success"
+    | "warning"`
+- **Required**: No
+- **Description**: No description available
+
+### align
+- **Type**: `"left" | "center" | "right" | "justify"`
+- **Required**: No
+- **Description**: No description available
+
+### transform
+- **Type**: `"uppercase" | "lowercase" | "capitalize"`
+- **Required**: No
+- **Description**: No description available
+
+### weight
+- **Type**: `"normal" | "medium" | "semibold" | "bold"`
+- **Required**: No
+- **Description**: No description available
+
+### htmlFor
+- **Type**: `string`
+- **Required**: No
+- **Description**: No description available
+
+### asChild
+- **Type**: `boolean`
+- **Required**: No
+- **Description**: No description available
+
+### italic
+- **Type**: `boolean`
+- **Required**: No
+- **Description**: No description available
+
+### underline
+- **Type**: `boolean`
+- **Required**: No
+- **Description**: No description available
+
+### strikethrough
+- **Type**: `boolean`
+- **Required**: No
+- **Description**: No description available
+
+### truncate
+- **Type**: `boolean`
+- **Required**: No
+- **Description**: No description available
+
+### srOnly
+- **Type**: `boolean`
+- **Required**: No
+- **Description**: No description available
+
+### className
+- **Type**: `string`
+- **Required**: No
+- **Description**: No description available
+
+### children
+- **Type**: `React.ReactNode`
+- **Required**: No
+- **Description**: No description available
+
+## Examples
+
+```tsx
+// Simple quote
+<Blockquote>
+  "The best way to predict the future is to invent it."
+</Blockquote>
+// With attribution
+<div>
+  <Blockquote className="mb-2">
+    "Building great products requires deep understanding of user needs
+    and technical excellence in equal measure."
+  </Blockquote>
+  <Small>— Product Engineering Team</Small>
+</div>
+// Customer testimonial
+<Blockquote color="muted" className="bg-muted/50 p-4 rounded-lg">
+  "Neynar's APIs have transformed how we build social features.
+  The developer experience is exceptional."
+</Blockquote>
+```

package/llm-docs/breadcrumb-ellipsis.llm.md

@@ -0,0 +1,73 @@
+# BreadcrumbEllipsis
+
+**Type**: component
+
+Ellipsis indicator for collapsed breadcrumb items Shows a horizontal ellipsis icon (MoreHorizontal) to indicate hidden or collapsed middle items in a long breadcrumb trail. Essential for deep navigation hierarchies where space is limited or mobile responsive design. Commonly used in combination with dropdown menus, popovers, or expandable sections to reveal the collapsed breadcrumb items on user interaction. The component provides a consistent 36px (9 × 4px) clickable area for better touch interaction when used as a trigger for dropdown menus. Includes hidden screen reader text to provide context about the collapsed content.
+
+## JSX Usage
+
+```jsx
+import { BreadcrumbEllipsis } from '@neynar/ui';
+
+<BreadcrumbEllipsis
+  className="value"
+>
+  {/* Your content here */}
+</BreadcrumbEllipsis>
+```
+
+## Component Props
+
+### className
+- **Type**: `string`
+- **Required**: No
+- **Description**: Additional CSS classes to apply to the ellipsis container
+
+### children
+- **Type**: `React.ReactNode`
+- **Required**: No
+- **Description**: Custom content to display instead of the default MoreHorizontal icon (rarely needed)
+
+## Examples
+
+### Example 1
+```tsx
+// Simple static ellipsis
+<BreadcrumbEllipsis />
+```
+### Example 2
+```tsx
+// Interactive ellipsis with dropdown menu
+<BreadcrumbItem>
+  <DropdownMenu>
+    <DropdownMenuTrigger asChild>
+      <BreadcrumbEllipsis className="hover:bg-muted cursor-pointer" />
+    </DropdownMenuTrigger>
+    <DropdownMenuContent>
+      <DropdownMenuItem>
+        <BreadcrumbLink href="/level1">Level 1</BreadcrumbLink>
+      </DropdownMenuItem>
+      <DropdownMenuItem>
+        <BreadcrumbLink href="/level1/level2">Level 2</BreadcrumbLink>
+      </DropdownMenuItem>
+    </DropdownMenuContent>
+  </DropdownMenu>
+</BreadcrumbItem>
+```
+### Example 3
+```tsx
+// With popover for collapsed items
+<BreadcrumbItem>
+  <Popover>
+    <PopoverTrigger asChild>
+      <BreadcrumbEllipsis className="hover:bg-accent" />
+    </PopoverTrigger>
+    <PopoverContent>
+      <div className="space-y-2">
+        <BreadcrumbLink href="/hidden1">Hidden Item 1</BreadcrumbLink>
+        <BreadcrumbLink href="/hidden2">Hidden Item 2</BreadcrumbLink>
+      </div>
+    </PopoverContent>
+  </Popover>
+</BreadcrumbItem>
+```

package/llm-docs/breadcrumb-item.llm.md

@@ -0,0 +1,53 @@
+# BreadcrumbItem
+
+**Type**: component
+
+Individual breadcrumb list item container Wraps breadcrumb content (links, pages, separators) in a semantic list item. Provides consistent alignment and spacing for breadcrumb elements with inline flex layout for proper icon and text alignment.
+
+## JSX Usage
+
+```jsx
+import { BreadcrumbItem } from '@neynar/ui';
+
+<BreadcrumbItem
+  className="value"
+>
+  {/* Your content here */}
+</BreadcrumbItem>
+```
+
+## Component Props
+
+### className
+- **Type**: `string`
+- **Required**: No
+- **Description**: Additional CSS classes to apply to the list item element
+
+### children
+- **Type**: `React.ReactNode`
+- **Required**: No
+- **Description**: Content to display within the item (links, pages, separators, ellipsis)
+
+## Examples
+
+### Example 1
+```tsx
+// With link
+<BreadcrumbItem>
+  <BreadcrumbLink href="/products">Products</BreadcrumbLink>
+</BreadcrumbItem>
+```
+### Example 2
+```tsx
+// With current page
+<BreadcrumbItem>
+  <BreadcrumbPage>Current Page</BreadcrumbPage>
+</BreadcrumbItem>
+```
+### Example 3
+```tsx
+// With separator
+<BreadcrumbItem>
+  <BreadcrumbSeparator />
+</BreadcrumbItem>
+```