@neynar/ui 0.3.0 → 0.3.1

package/.llm/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/badge.llm.md

@@ -0,0 +1,117 @@
+# 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"
+    | "success"
+    | "warning"
+    | "info"
+    | "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="success">Success</Badge>
+<Badge variant="warning">Warning</Badge>
+<Badge variant="info">Info</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/blockquote.llm.md

@@ -0,0 +1,117 @@
+# 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**: `TypographyColor`
+- **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/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/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>
+```

package/.llm/breadcrumb-link.llm.md

@@ -0,0 +1,84 @@
+# BreadcrumbLink
+
+**Type**: component
+
+Navigable link within breadcrumb trail Represents a clickable parent page in the breadcrumb hierarchy with smooth hover effects and transition animations. Supports composition via the `asChild` prop for seamless integration with routing libraries like Next.js Link, React Router, or Reach Router using the Radix UI Slot primitive for prop merging. Built on Radix UI Slot primitive which enables the asChild pattern - when asChild is true, the component merges its props with the immediate child element instead of rendering its own anchor tag. This allows for flexible composition while maintaining consistent styling and behavior.
+
+## JSX Usage
+
+```jsx
+import { BreadcrumbLink } from '@neynar/ui';
+
+<BreadcrumbLink
+  asChild={true}
+  className="value"
+  href="value"
+  onClick={handleClick}
+>
+  {/* Your content here */}
+</BreadcrumbLink>
+```
+
+## Component Props
+
+### asChild
+- **Type**: `boolean`
+- **Required**: No
+- **Description**: When true, merges props with child element instead of rendering anchor. Enables composition with routing components
+
+### className
+- **Type**: `string`
+- **Required**: No
+- **Description**: Additional CSS classes to apply to the link element
+
+### href
+- **Type**: `string`
+- **Required**: No
+- **Description**: Link destination URL (when asChild is false)
+
+### children
+- **Type**: `React.ReactNode`
+- **Required**: No
+- **Description**: Link content to display (text, icons, etc.)
+
+### onClick
+- **Type**: `(event: React.MouseEvent<HTMLAnchorElement>) => void`
+- **Required**: No
+- **Description**: Click handler for the link interaction
+
+## Examples
+
+### Example 1
+```tsx
+// Standard anchor link
+<BreadcrumbLink href="/products">Products</BreadcrumbLink>
+```
+### Example 2
+```tsx
+// With Next.js Link using asChild
+import { Link } from "next/link"
+<BreadcrumbLink asChild>
+  <Link href="/products">Products</Link>
+</BreadcrumbLink>
+```
+### Example 3
+```tsx
+// With React Router Link
+import { Link } from "react-router-dom"
+<BreadcrumbLink asChild>
+  <Link to="/products">Products</Link>
+</BreadcrumbLink>
+```
+### Example 4
+```tsx
+// With click handler
+<BreadcrumbLink
+  href="/products"
+  onClick={(e) => {
+    e.preventDefault();
+    navigate('/products');
+  }}
+>
+  Products
+</BreadcrumbLink>
+```

package/.llm/breadcrumb-list.llm.md

@@ -0,0 +1,54 @@
+# BreadcrumbList
+
+**Type**: component
+
+Ordered list container for breadcrumb items Provides the structured list layout for breadcrumb navigation items with responsive spacing and text overflow handling. Uses semantic `ol` element for proper accessibility and screen reader navigation. Contains flexible layout with word breaking and responsive gap adjustments.
+
+## JSX Usage
+
+```jsx
+import { BreadcrumbList } from '@neynar/ui';
+
+<BreadcrumbList
+  className="value"
+>
+  {/* Your content here */}
+</BreadcrumbList>
+```
+
+## Component Props
+
+### className
+- **Type**: `string`
+- **Required**: No
+- **Description**: Additional CSS classes to apply to the ordered list element
+
+### children
+- **Type**: `React.ReactNode`
+- **Required**: No
+- **Description**: Child breadcrumb items (BreadcrumbItem elements)
+
+## Examples
+
+### Example 1
+```tsx
+// Basic list with multiple items
+<BreadcrumbList>
+  <BreadcrumbItem>
+    <BreadcrumbLink href="/">Home</BreadcrumbLink>
+  </BreadcrumbItem>
+  <BreadcrumbSeparator />
+  <BreadcrumbItem>
+    <BreadcrumbPage>Current</BreadcrumbPage>
+  </BreadcrumbItem>
+</BreadcrumbList>
+```
+### Example 2
+```tsx
+// With custom styling
+<BreadcrumbList className="gap-4 text-base">
+  <BreadcrumbItem>
+    <BreadcrumbLink href="/">Home</BreadcrumbLink>
+  </BreadcrumbItem>
+</BreadcrumbList>
+```

package/.llm/breadcrumb-page.llm.md

@@ -0,0 +1,52 @@
+# BreadcrumbPage
+
+**Type**: component
+
+Current page indicator in breadcrumb trail Represents the current page (non-clickable) at the end of the breadcrumb trail. Styled with prominent text color and marked with comprehensive accessibility attributes including `aria-current="page"` for precise screen reader identification of the user's current location within the site hierarchy. This component uses specific ARIA attributes to indicate it represents a link-like element that is disabled, providing semantic meaning while maintaining the visual breadcrumb structure. The `aria-current="page"` attribute is the standard way to identify the current page in navigation components.
+
+## JSX Usage
+
+```jsx
+import { BreadcrumbPage } from '@neynar/ui';
+
+<BreadcrumbPage
+  className="value"
+>
+  {/* Your content here */}
+</BreadcrumbPage>
+```
+
+## Component Props
+
+### className
+- **Type**: `string`
+- **Required**: No
+- **Description**: Additional CSS classes to apply to the span element
+
+### children
+- **Type**: `React.ReactNode`
+- **Required**: No
+- **Description**: Current page name or content to display
+
+## Examples
+
+### Example 1
+```tsx
+// Simple page name
+<BreadcrumbPage>Current Page Name</BreadcrumbPage>
+```
+### Example 2
+```tsx
+// With icon and text
+<BreadcrumbPage>
+  <FileIcon className="mr-1" />
+  Document.pdf
+</BreadcrumbPage>
+```
+### Example 3
+```tsx
+// With custom styling
+<BreadcrumbPage className="font-semibold text-primary">
+  Important Page
+</BreadcrumbPage>
+```

package/.llm/breadcrumb-separator.llm.md

@@ -0,0 +1,60 @@
+# BreadcrumbSeparator
+
+**Type**: component
+
+Visual separator between breadcrumb items Displays a separator icon (default: ChevronRight) between breadcrumb items to provide visual hierarchy and direction in the breadcrumb trail. Supports complete customization with any icon or content. Properly hidden from assistive technologies with accessibility attributes for clean screen reader navigation experience. The component uses CSS sizing constraints to ensure consistent icon sizing across different separator types and maintains visual alignment within the breadcrumb flow.
+
+## JSX Usage
+
+```jsx
+import { BreadcrumbSeparator } from '@neynar/ui';
+
+<BreadcrumbSeparator
+  className="value"
+>
+  {/* Your content here */}
+</BreadcrumbSeparator>
+```
+
+## Component Props
+
+### children
+- **Type**: `React.ReactNode`
+- **Required**: No
+- **Description**: Custom separator icon or content to display instead of default ChevronRight. Typically Lucide icons like Slash, ArrowRight, etc.
+
+### className
+- **Type**: `string`
+- **Required**: No
+- **Description**: Additional CSS classes to apply to the list item container
+
+## Examples
+
+### Example 1
+```tsx
+// Default ChevronRight separator
+<BreadcrumbSeparator />
+```
+### Example 2
+```tsx
+// Custom Slash separator
+import { Slash } from "lucide-react"
+<BreadcrumbSeparator>
+  <Slash />
+</BreadcrumbSeparator>
+```
+### Example 3
+```tsx
+// Arrow right separator
+import { ArrowRight } from "lucide-react"
+<BreadcrumbSeparator>
+  <ArrowRight />
+</BreadcrumbSeparator>
+```
+### Example 4
+```tsx
+// Text separator
+<BreadcrumbSeparator>
+  <span className="text-muted-foreground">/</span>
+</BreadcrumbSeparator>
+```