@neynar/ui 1.0.0 → 1.0.2

package/llm/components/alert.llm.md

@@ -0,0 +1,310 @@
+# Alert
+
+Displays contextual messages with optional icons and actions for notifications, warnings, errors, and informational content.
+
+## Import
+
+```tsx
+import { Alert, AlertTitle, AlertDescription, AlertAction } from "@neynar/ui/alert"
+```
+
+## Anatomy
+
+```tsx
+<Alert variant="default">
+  <InfoIcon />
+  <AlertTitle>Title</AlertTitle>
+  <AlertDescription>Description with optional links.</AlertDescription>
+  <AlertAction>
+    <Button size="xs">Action</Button>
+  </AlertAction>
+</Alert>
+```
+
+## Components
+
+| Component | Description |
+|-----------|-------------|
+| Alert | Root container with variant styling and grid layout |
+| AlertTitle | Title heading, auto-positions next to icon |
+| AlertDescription | Description content with muted foreground color |
+| AlertAction | Action area positioned in top-right corner |
+
+## Props
+
+### Alert
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| variant | "default" \| "destructive" \| "success" \| "warning" \| "info" | "default" | Visual style variant for different message types |
+| className | string | - | Additional CSS classes |
+| children | ReactNode | - | Alert content (icon, title, description, action) |
+
+All standard HTML div props are supported.
+
+### AlertTitle
+
+Standard HTML div props. Automatically positions next to icon when present using CSS grid. Supports inline links with underline styling on hover.
+
+### AlertDescription
+
+Standard HTML div props. Uses muted foreground color that adapts to the alert variant. Supports paragraph spacing and inline links.
+
+### AlertAction
+
+Standard HTML div props. Absolutely positioned in top-right corner (top-2.5, right-3). Use for dismiss buttons or action CTAs.
+
+## Data Attributes
+
+| Attribute | Element | When Present |
+|-----------|---------|--------------|
+| data-slot="alert" | Alert | Always on root alert element |
+| data-slot="alert-title" | AlertTitle | Always on title element |
+| data-slot="alert-description" | AlertDescription | Always on description element |
+| data-slot="alert-action" | AlertAction | Always on action element |
+
+The Alert uses `has-data-[slot=alert-action]:pr-18` to add right padding when an action is present, preventing content overlap.
+
+## Variants
+
+| Variant | Usage |
+|---------|-------|
+| default | General information, updates, neutral notifications |
+| destructive | Errors, critical information requiring immediate attention |
+| success | Successful actions, positive outcomes, confirmations |
+| warning | Important warnings requiring attention but not critical |
+| info | Informational messages, tips, helpful context |
+
+## Icon Handling
+
+When an SVG icon is included as a direct child:
+- Alert switches to 2-column grid layout (`has-[>svg]:grid-cols-[auto_1fr]`)
+- Icon is auto-sized to 16px (`*:[svg:not([class*='size-'])]:size-4`)
+- Icon color matches variant text color
+- Icon spans both rows and translates slightly down for alignment
+- Title and description automatically position in second column
+
+## Examples
+
+### Basic Alert
+
+```tsx
+<Alert>
+  <InfoIcon />
+  <AlertTitle>Heads up!</AlertTitle>
+  <AlertDescription>
+    You can add components to your app using the CLI.
+  </AlertDescription>
+</Alert>
+```
+
+### Destructive/Error Alert
+
+```tsx
+<Alert variant="destructive">
+  <AlertTriangleIcon />
+  <AlertTitle>Authentication Error</AlertTitle>
+  <AlertDescription>
+    Your API key has expired or is invalid. Please generate a new key or check
+    your credentials in the <a href="#settings">API settings</a> page.
+  </AlertDescription>
+</Alert>
+```
+
+### Success Alert
+
+```tsx
+<Alert variant="success">
+  <CheckCircle2Icon />
+  <AlertTitle>Plan Upgrade Successful</AlertTitle>
+  <AlertDescription>
+    Your account has been upgraded to the Pro plan. Your new rate limits and
+    features are now active.
+  </AlertDescription>
+</Alert>
+```
+
+### With Dismiss Action
+
+```tsx
+<Alert variant="destructive">
+  <AlertTriangleIcon />
+  <AlertTitle>Rate Limit Warning</AlertTitle>
+  <AlertDescription>
+    You've used 95% of your API rate limit for this billing period. Your requests
+    may be throttled. Consider <a href="#upgrade">upgrading your plan</a> to
+    increase your limit.
+  </AlertDescription>
+  <AlertAction>
+    <Button variant="ghost" size="icon-xs" aria-label="Dismiss">
+      <XIcon />
+    </Button>
+  </AlertAction>
+</Alert>
+```
+
+### With Primary Action Button
+
+```tsx
+<Alert>
+  <InfoIcon />
+  <AlertTitle>API v1 Deprecation Notice</AlertTitle>
+  <AlertDescription>
+    The v1 API endpoints will be deprecated on March 31, 2025. Please migrate to
+    <a href="#migration">v2 endpoints</a> to avoid service disruption.
+  </AlertDescription>
+  <AlertAction>
+    <Button size="xs" variant="outline">
+      View Migration Guide
+    </Button>
+  </AlertAction>
+</Alert>
+```
+
+### Description Only (No Title)
+
+```tsx
+<Alert>
+  <InfoIcon />
+  <AlertDescription>
+    Your changes have been saved automatically.
+  </AlertDescription>
+</Alert>
+```
+
+### Without Icon
+
+```tsx
+<Alert>
+  <AlertTitle>Simple Alert</AlertTitle>
+  <AlertDescription>
+    This alert doesn't have an icon, useful for less critical information.
+  </AlertDescription>
+</Alert>
+```
+
+### Warning Alert
+
+```tsx
+<Alert variant="warning">
+  <AlertTriangleIcon />
+  <AlertTitle>Webhook Configuration Required</AlertTitle>
+  <AlertDescription>
+    Set up webhooks to receive real-time notifications for cast events, reactions,
+    and follows. <a href="#webhooks">Configure webhooks</a> in your dashboard settings.
+  </AlertDescription>
+</Alert>
+```
+
+### Info Alert
+
+```tsx
+<Alert variant="info">
+  <BellIcon />
+  <AlertTitle>Update Available</AlertTitle>
+  <AlertDescription>
+    A new version of the API is available with improved performance.
+  </AlertDescription>
+  <AlertAction>
+    <Button size="xs">Learn More</Button>
+  </AlertAction>
+</Alert>
+```
+
+## Styling
+
+### Custom Variants
+
+Use the `alertVariants` function to extend or create custom variants:
+
+```tsx
+import { alertVariants } from "@neynar/ui/alert"
+
+<Alert className={alertVariants({ variant: "success" })}>
+  {/* ... */}
+</Alert>
+```
+
+### Custom Styling
+
+Override styles using className:
+
+```tsx
+<Alert className="border-2 shadow-lg">
+  <AlertTitle className="text-lg">Custom Styled</AlertTitle>
+  <AlertDescription className="text-base">
+    With larger text and border.
+  </AlertDescription>
+</Alert>
+```
+
+## Accessibility
+
+- Uses `role="alert"` for screen reader announcements
+- Alert content is announced immediately when rendered
+- Interactive elements (links, buttons) are keyboard accessible
+- Link underlines and hover states provide clear affordance
+- Variant colors provide additional visual context beyond text
+
+## Layout Behavior
+
+The Alert uses CSS Grid for flexible layout:
+- **Without icon**: Single column layout
+- **With icon**: Two-column grid with icon in first column
+- **With action**: Adds right padding to prevent overlap
+- **Responsive text**: Uses `text-balance` on mobile and `text-pretty` on desktop for optimal readability
+
+## Common Patterns
+
+### API Dashboard Notifications
+
+```tsx
+<div className="space-y-4">
+  <Alert variant="destructive">
+    <AlertTriangleIcon />
+    <AlertTitle>Rate Limit Warning</AlertTitle>
+    <AlertDescription>
+      You've used 95% of your API rate limit for this billing period.
+    </AlertDescription>
+    <AlertAction>
+      <Button variant="ghost" size="icon-xs">
+        <XIcon />
+      </Button>
+    </AlertAction>
+  </Alert>
+
+  <Alert>
+    <InfoIcon />
+    <AlertTitle>API v1 Deprecation Notice</AlertTitle>
+    <AlertDescription>
+      The v1 API endpoints will be deprecated on March 31, 2025.
+    </AlertDescription>
+    <AlertAction>
+      <Button size="xs" variant="outline">
+        Learn More
+      </Button>
+    </AlertAction>
+  </Alert>
+</div>
+```
+
+### Inline Links
+
+Alert descriptions automatically style links with underlines and hover states:
+
+```tsx
+<Alert>
+  <InfoIcon />
+  <AlertTitle>Documentation Updated</AlertTitle>
+  <AlertDescription>
+    We've updated our API documentation with new examples and best practices.
+    <a href="#docs">View the updated docs</a> or <a href="#changelog">read the changelog</a>.
+  </AlertDescription>
+</Alert>
+```
+
+## Related
+
+- **Toast** - For temporary notifications that auto-dismiss
+- **Banner** - For persistent site-wide announcements
+- **Dialog** - For alerts requiring user confirmation

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

@@ -0,0 +1,110 @@
+# AspectRatio
+
+Container that maintains a consistent aspect ratio, automatically adjusting height based on width.
+
+## Import
+
+```tsx
+import { AspectRatio } from "@neynar/ui/aspect-ratio"
+```
+
+## Anatomy
+
+```tsx
+<AspectRatio ratio={16 / 9}>
+  <img src="..." alt="..." />
+</AspectRatio>
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| ratio | number | - | Aspect ratio as width/height (e.g., 16/9, 1, 4/3) |
+| className | string | - | Additional CSS classes |
+| children | ReactNode | - | Content to display within aspect ratio container |
+
+All standard `div` props are supported.
+
+## Common Aspect Ratios
+
+| Ratio | Value | Use Case |
+|-------|-------|----------|
+| 16:9 | 16/9 | Video content, YouTube thumbnails, widescreen |
+| 4:3 | 4/3 | Traditional displays, some photography |
+| 1:1 | 1 | Square images, Instagram posts, NFTs, profile pictures |
+| 21:9 | 21/9 | Ultrawide/cinematic content, hero banners |
+| 9:16 | 9/16 | Vertical video (stories, reels) |
+| 2:1 | 2/1 | Panoramic images, Twitter banners |
+
+## Examples
+
+### Video Thumbnail
+
+```tsx
+<AspectRatio ratio={16 / 9} className="overflow-hidden rounded-md">
+  <img
+    src="/video-thumbnail.jpg"
+    alt="Video thumbnail"
+    className="size-full object-cover"
+  />
+  <div className="absolute inset-0 flex items-center justify-center bg-black/30">
+    <PlayIcon className="size-12" />
+  </div>
+</AspectRatio>
+```
+
+### NFT Gallery
+
+```tsx
+<div className="grid grid-cols-4 gap-4">
+  {nfts.map((nft) => (
+    <AspectRatio key={nft.id} ratio={1} className="overflow-hidden rounded-md">
+      <img
+        src={nft.image}
+        alt={nft.name}
+        className="size-full object-cover hover:scale-110 transition-transform"
+      />
+    </AspectRatio>
+  ))}
+</div>
+```
+
+### Profile Banner
+
+```tsx
+<AspectRatio ratio={21 / 9} className="overflow-hidden">
+  <img
+    src="/banner.jpg"
+    alt="Profile banner"
+    className="size-full object-cover"
+  />
+  <div className="absolute inset-0 bg-gradient-to-t from-black/60 to-transparent" />
+  <div className="absolute bottom-6 left-6 text-white">
+    <h3 className="text-2xl font-bold">Channel Name</h3>
+  </div>
+</AspectRatio>
+```
+
+### Placeholder Content
+
+```tsx
+<AspectRatio ratio={16 / 9} className="bg-muted flex items-center justify-center rounded-md">
+  <div className="text-center">
+    <ImageIcon className="size-12 text-muted-foreground" />
+    <p className="text-sm">Upload Image</p>
+  </div>
+</AspectRatio>
+```
+
+## Usage Notes
+
+- Always use `overflow-hidden` with images to prevent content overflow
+- Combine with `object-cover` for images that fill the container
+- Use `object-contain` to fit entire image with possible letterboxing
+- Container width is flexible; height is calculated automatically
+- Works with any content type: images, video, gradients, custom elements
+
+## Related
+
+- [Card](./card.llm.md) - Often used together for media cards

package/llm/components/avatar.llm.md

@@ -0,0 +1,282 @@
+# Avatar
+
+Display user profile images with automatic fallback support, status badges, and grouping.
+
+## Import
+
+```tsx
+import {
+  Avatar,
+  AvatarImage,
+  AvatarFallback,
+  AvatarBadge,
+  AvatarGroup,
+  AvatarGroupCount,
+} from "@neynar/ui/avatar"
+```
+
+## Anatomy
+
+```tsx
+<Avatar size="default">
+  <AvatarImage src="/user.jpg" alt="Username" />
+  <AvatarFallback>UN</AvatarFallback>
+  <AvatarBadge>
+    <CheckIcon />
+  </AvatarBadge>
+</Avatar>
+
+<AvatarGroup>
+  <Avatar>...</Avatar>
+  <Avatar>...</Avatar>
+  <AvatarGroupCount>+5</AvatarGroupCount>
+</AvatarGroup>
+```
+
+## Components
+
+| Component | Description |
+|-----------|-------------|
+| Avatar | Root container with size variants |
+| AvatarImage | Image element with automatic fallback |
+| AvatarFallback | Fallback content (initials or icon) shown when image unavailable |
+| AvatarBadge | Status indicator positioned at bottom-right |
+| AvatarGroup | Container for stacked avatars with ring borders |
+| AvatarGroupCount | Counter badge showing overflow count ("+N") |
+
+## Props
+
+### Avatar
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| size | "sm" \| "default" \| "lg" | "default" | Avatar size variant |
+
+Extends all Base UI Avatar.Root props.
+
+### AvatarImage
+
+Standard `img` element props via Base UI Avatar.Image.
+
+| Prop | Type | Description |
+|------|------|-------------|
+| src | string | Image source URL |
+| alt | string | Alternative text for accessibility |
+
+### AvatarFallback
+
+Extends Base UI Avatar.Fallback props. Accepts text content (typically initials) or icon elements.
+
+### AvatarBadge
+
+Standard `span` element props. Can contain icons or be used as colored dot.
+
+### AvatarGroup
+
+Standard `div` element props. Automatically applies ring borders and negative spacing to child avatars.
+
+### AvatarGroupCount
+
+Standard `div` element props. Display text like "+12" or icons.
+
+## Sizes
+
+| Size | Dimensions | Use Case |
+|------|------------|----------|
+| sm | 24px | Compact lists, inline mentions |
+| default | 32px | Standard UI, activity feeds |
+| lg | 40px | Profile headers, featured users |
+
+## Data Attributes
+
+| Attribute | Value | Applied To |
+|-----------|-------|------------|
+| data-slot | "avatar" | Avatar root |
+| data-slot | "avatar-image" | AvatarImage |
+| data-slot | "avatar-fallback" | AvatarFallback |
+| data-slot | "avatar-badge" | AvatarBadge |
+| data-slot | "avatar-group" | AvatarGroup |
+| data-slot | "avatar-group-count" | AvatarGroupCount |
+| data-size | "sm" \| "default" \| "lg" | Avatar root (for size styling) |
+
+## Examples
+
+### Basic Usage
+
+```tsx
+<Avatar>
+  <AvatarImage src="https://i.imgur.com/xIe7Wlb.png" alt="@dwr.eth" />
+  <AvatarFallback>DW</AvatarFallback>
+</Avatar>
+```
+
+### With Sizes
+
+```tsx
+<Avatar size="sm">
+  <AvatarImage src="/user.jpg" alt="User" />
+  <AvatarFallback>AB</AvatarFallback>
+</Avatar>
+
+<Avatar size="default">
+  <AvatarImage src="/user.jpg" alt="User" />
+  <AvatarFallback>AB</AvatarFallback>
+</Avatar>
+
+<Avatar size="lg">
+  <AvatarImage src="/user.jpg" alt="User" />
+  <AvatarFallback>AB</AvatarFallback>
+</Avatar>
+```
+
+### Fallback States
+
+```tsx
+{/* Initials fallback */}
+<Avatar>
+  <AvatarFallback>JD</AvatarFallback>
+</Avatar>
+
+{/* Icon fallback */}
+<Avatar>
+  <AvatarFallback>
+    <UserIcon className="size-4" />
+  </AvatarFallback>
+</Avatar>
+```
+
+### With Status Badge
+
+```tsx
+{/* Verification badge */}
+<Avatar>
+  <AvatarImage src="/user.jpg" alt="Verified user" />
+  <AvatarFallback>VU</AvatarFallback>
+  <AvatarBadge>
+    <CheckIcon />
+  </AvatarBadge>
+</Avatar>
+
+{/* Online status dot */}
+<Avatar>
+  <AvatarImage src="/user.jpg" alt="Online user" />
+  <AvatarFallback>OU</AvatarFallback>
+  <AvatarBadge className="bg-green-500" />
+</Avatar>
+
+{/* Custom status */}
+<Avatar>
+  <AvatarFallback>PU</AvatarFallback>
+  <AvatarBadge className="bg-yellow-500">
+    <ZapIcon />
+  </AvatarBadge>
+</Avatar>
+```
+
+### Avatar Group
+
+```tsx
+{/* Basic group */}
+<AvatarGroup>
+  <Avatar>
+    <AvatarImage src="/user1.jpg" alt="User 1" />
+    <AvatarFallback>U1</AvatarFallback>
+  </Avatar>
+  <Avatar>
+    <AvatarImage src="/user2.jpg" alt="User 2" />
+    <AvatarFallback>U2</AvatarFallback>
+  </Avatar>
+  <Avatar>
+    <AvatarFallback>U3</AvatarFallback>
+  </Avatar>
+</AvatarGroup>
+
+{/* With overflow count */}
+<AvatarGroup>
+  <Avatar size="sm">
+    <AvatarImage src="/user1.jpg" alt="User 1" />
+    <AvatarFallback>U1</AvatarFallback>
+  </Avatar>
+  <Avatar size="sm">
+    <AvatarImage src="/user2.jpg" alt="User 2" />
+    <AvatarFallback>U2</AvatarFallback>
+  </Avatar>
+  <Avatar size="sm">
+    <AvatarFallback>U3</AvatarFallback>
+  </Avatar>
+  <AvatarGroupCount>+8</AvatarGroupCount>
+</AvatarGroup>
+
+{/* Icon with count */}
+<AvatarGroup>
+  <Avatar>
+    <AvatarFallback>
+      <UsersIcon className="size-4" />
+    </AvatarFallback>
+  </Avatar>
+  <AvatarGroupCount>24</AvatarGroupCount>
+</AvatarGroup>
+```
+
+### User Profile
+
+```tsx
+<div className="flex items-center gap-4">
+  <Avatar size="lg">
+    <AvatarImage
+      src="https://i.imgur.com/xIe7Wlb.png"
+      alt="@dwr.eth"
+    />
+    <AvatarFallback>DW</AvatarFallback>
+    <AvatarBadge>
+      <CheckIcon />
+    </AvatarBadge>
+  </Avatar>
+  <div>
+    <p className="font-semibold">Dan Romero</p>
+    <p className="text-muted-foreground text-sm">@dwr.eth</p>
+  </div>
+</div>
+```
+
+### Activity Feed
+
+```tsx
+<div className="flex items-start gap-3">
+  <Avatar>
+    <AvatarImage src="/user.jpg" alt="@username" />
+    <AvatarFallback>UN</AvatarFallback>
+    <AvatarBadge className="bg-green-500">
+      <ZapIcon />
+    </AvatarBadge>
+  </Avatar>
+  <div className="flex-1">
+    <p className="text-sm">
+      <span className="font-medium">@username</span> cast a new post
+    </p>
+    <p className="text-muted-foreground text-xs">2 minutes ago</p>
+  </div>
+</div>
+```
+
+## Accessibility
+
+- AvatarImage includes `alt` attribute for screen readers
+- AvatarFallback provides text alternative when images fail to load
+- Proper semantic HTML with appropriate ARIA attributes via Base UI
+- Badge icons should be decorative; status communicated through other means
+
+## Technical Notes
+
+- Image loading handled automatically by Base UI Avatar primitive
+- Fallback displays only when image fails to load or src is missing
+- Badge automatically scales with avatar size (sm shows no icon, default/lg show icons)
+- AvatarGroup applies negative spacing (`-space-x-2`) and ring borders automatically
+- Uses `data-size` attribute for responsive badge sizing
+- Group uses `/avatar` and `/avatar-group` context for nested styling
+
+## Related
+
+- [Button](./button.llm.md) - For clickable avatar actions
+- [Card](./card.llm.md) - For profile cards with avatars
+- [Dialog](./dialog.llm.md) - For profile modals