@neynar/ui 0.1.1

package/src/components/ui/alert.tsx

@@ -0,0 +1,243 @@
+import * as React from "react";
+import { cva, type VariantProps } from "class-variance-authority";
+
+import { cn } from "@/lib/utils";
+
+const alertVariants = cva(
+  "relative w-full rounded-lg border px-4 py-3 text-sm grid has-[>svg]:grid-cols-[calc(var(--spacing)*4)_1fr] grid-cols-[0_1fr] has-[>svg]:gap-x-3 gap-y-0.5 items-start [&>svg]:size-4 [&>svg]:translate-y-0.5 [&>svg]:text-current",
+  {
+    variants: {
+      variant: {
+        default: "bg-card text-card-foreground",
+        destructive:
+          "text-destructive bg-card [&>svg]:text-current *:data-[slot=alert-description]:text-destructive/90",
+      },
+    },
+    defaultVariants: {
+      variant: "default",
+    },
+  },
+);
+
+/**
+ * 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.
+ *
+ * @example
+ * ```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
+ * ```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
+ * ```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
+ * ```tsx
+ * // Alert without icon
+ * <Alert>
+ *   <AlertTitle>Simple Notice</AlertTitle>
+ *   <AlertDescription>
+ *     This alert doesn't use an icon.
+ *   </AlertDescription>
+ * </Alert>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Alert with only description
+ * <Alert variant="destructive">
+ *   <AlertCircle className="size-4" />
+ *   <AlertDescription>
+ *     Something went wrong. Please try again.
+ *   </AlertDescription>
+ * </Alert>
+ * ```
+ *
+ * @param variant - Visual style variant determining colors and emphasis
+ * @param className - Additional CSS classes to merge with default styles
+ * @param children - Alert content including optional icon, title, and description
+ * @param props - Additional HTML div element props
+ *
+ * @accessibility
+ * - Uses `role="alert"` for immediate screen reader announcements
+ * - Supports keyboard navigation when containing interactive elements
+ * - WCAG AA color contrast compliance for all variants
+ * - Semantic HTML structure with proper heading hierarchy
+ * - Icon support with automatic grid layout and accessible sizing
+ * - Icons receive `text-current` color for proper contrast inheritance
+ *
+ * @see {@link AlertTitle} - Alert title component for headings
+ * @see {@link AlertDescription} - Alert description component for body text
+ * @see {@link https://ui.shadcn.com/docs/components/alert} - shadcn/ui Alert documentation
+ * @see {@link https://www.w3.org/WAI/ARIA/apg/patterns/alert/} - ARIA alert pattern
+ * @since 1.0.0
+ */
+function Alert({
+  className,
+  variant,
+  ...props
+}: React.ComponentProps<"div"> & VariantProps<typeof alertVariants>) {
+  return (
+    <div
+      data-slot="alert"
+      role="alert"
+      className={cn(alertVariants({ variant }), className)}
+      {...props}
+    />
+  );
+}
+
+/**
+ * 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
+ *
+ * @component
+ * @example
+ * ```tsx
+ * <Alert>
+ *   <Info className="size-4" />
+ *   <AlertTitle>Payment Successful</AlertTitle>
+ *   <AlertDescription>Your payment has been processed.</AlertDescription>
+ * </Alert>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Title-only alert (no description)
+ * <Alert variant="destructive">
+ *   <AlertCircle className="size-4" />
+ *   <AlertTitle>Connection Failed</AlertTitle>
+ * </Alert>
+ * ```
+ *
+ * @param className - Additional CSS classes to apply
+ * @param children - Title text content
+ *
+ * @accessibility
+ * - Semantically associated with the alert container via DOM structure
+ * - Proper visual hierarchy with medium font weight
+ * - Readable character spacing and line height
+ * - Works with screen readers as part of alert announcement
+ *
+ * @see {@link Alert} - Parent alert container component
+ * @see {@link AlertDescription} - Companion description component
+ * @since 1.0.0
+ */
+function AlertTitle({ className, ...props }: React.ComponentProps<"div">) {
+  return (
+    <div
+      data-slot="alert-title"
+      className={cn(
+        "col-start-2 line-clamp-1 min-h-4 font-medium tracking-tight",
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+
+/**
+ * AlertDescription - Detailed description text for an alert
+ *
+ * Provides additional context or instructions related to the alert.
+ * Supports multiple paragraphs and rich text content.
+ *
+ * @component
+ * @example
+ * ```tsx
+ * <Alert>
+ *   <AlertTitle>Note</AlertTitle>
+ *   <AlertDescription>
+ *     Your changes have been saved. You can continue editing or publish when ready.
+ *   </AlertDescription>
+ * </Alert>
+ * ```
+ *
+ * @accessibility
+ * - Uses appropriate text color for readability
+ * - Supports paragraph spacing for long content
+ *
+ * @since 1.0.0
+ */
+function AlertDescription({
+  className,
+  ...props
+}: React.ComponentProps<"div">) {
+  return (
+    <div
+      data-slot="alert-description"
+      className={cn(
+        "text-muted-foreground col-start-2 grid justify-items-start gap-1 text-sm [&_p]:leading-relaxed",
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+
+export { Alert, AlertTitle, AlertDescription };

package/src/components/ui/aspect-ratio.tsx

@@ -0,0 +1,99 @@
+import * as AspectRatioPrimitive from "@radix-ui/react-aspect-ratio";
+
+/**
+ * AspectRatio component for maintaining consistent width-to-height ratios
+ *
+ * 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.
+ *
+ * @example Basic image with 16:9 aspect ratio
+ * ```tsx
+ * <div className="w-[450px]">
+ *   <AspectRatio ratio={16 / 9}>
+ *     <img
+ *       src="landscape.jpg"
+ *       alt="Beautiful landscape"
+ *       className="w-full h-full object-cover rounded-md"
+ *     />
+ *   </AspectRatio>
+ * </div>
+ * ```
+ *
+ * @example Square avatar container (1:1 ratio)
+ * ```tsx
+ * <AspectRatio ratio={1}>
+ *   <img
+ *     src="avatar.jpg"
+ *     alt="User profile"
+ *     className="w-full h-full object-cover rounded-full"
+ *   />
+ * </AspectRatio>
+ * ```
+ *
+ * @example Video player container
+ * ```tsx
+ * <div className="w-full max-w-2xl">
+ *   <AspectRatio ratio={16 / 9}>
+ *     <video
+ *       src="video.mp4"
+ *       controls
+ *       className="w-full h-full object-cover rounded-lg"
+ *     />
+ *   </AspectRatio>
+ * </div>
+ * ```
+ *
+ * @example Responsive image gallery with portrait orientation
+ * ```tsx
+ * <div className="grid grid-cols-1 md:grid-cols-3 gap-4">
+ *   {images.map((image) => (
+ *     <AspectRatio key={image.id} ratio={3 / 4}>
+ *       <img
+ *         src={image.src}
+ *         alt={image.alt}
+ *         className="w-full h-full object-cover rounded-md"
+ *       />
+ *     </AspectRatio>
+ *   ))}
+ * </div>
+ * ```
+ *
+ * @example Placeholder content for loading states
+ * ```tsx
+ * <AspectRatio ratio={16 / 9}>
+ *   <div className="flex items-center justify-center bg-muted border-2 border-dashed border-muted-foreground/25 rounded-md">
+ *     <div className="text-center text-muted-foreground">
+ *       <ImageIcon className="h-12 w-12 mx-auto mb-2" />
+ *       <p className="text-sm">Loading image...</p>
+ *     </div>
+ *   </div>
+ * </AspectRatio>
+ * ```
+ *
+ * @param ratio - The desired aspect ratio as width/height (e.g., 16/9, 4/3, 1)
+ * @param children - Content to be constrained within the aspect ratio
+ * @param className - Additional CSS classes for styling
+ *
+ * @accessibility
+ * - Inherits all accessibility features from Radix UI AspectRatio primitive
+ * - Preserves semantic meaning of child content
+ * - Does not interfere with screen reader navigation
+ * - Maintains keyboard navigation for interactive child elements
+ *
+ * @see {@link https://ui.shadcn.com/docs/components/aspect-ratio} shadcn/ui documentation
+ * @since 1.0.0
+ * @see {@link https://www.radix-ui.com/primitives/docs/components/aspect-ratio} Radix UI AspectRatio
+ */
+function AspectRatio({
+  ...props
+}: React.ComponentProps<typeof AspectRatioPrimitive.Root>) {
+  return <AspectRatioPrimitive.Root data-slot="aspect-ratio" {...props} />;
+}
+
+export { AspectRatio };

package/src/components/ui/avatar.tsx

@@ -0,0 +1,288 @@
+import * as React from "react";
+import * as AvatarPrimitive from "@radix-ui/react-avatar";
+
+import { cn } from "@/lib/utils";
+
+/**
+ * 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
+ *
+ * ## 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
+ *
+ * @example Basic avatar with image and fallback
+ * ```tsx
+ * <Avatar>
+ *   <AvatarImage src="https://github.com/shadcn.png" alt="@shadcn" />
+ *   <AvatarFallback>CN</AvatarFallback>
+ * </Avatar>
+ * ```
+ *
+ * @example Custom sizing
+ * ```tsx
+ * <Avatar className="size-12">
+ *   <AvatarImage src="/profile.jpg" alt="John Doe" />
+ *   <AvatarFallback>JD</AvatarFallback>
+ * </Avatar>
+ * ```
+ *
+ * @example Avatar group with borders
+ * ```tsx
+ * <div className="flex -space-x-2">
+ *   <Avatar className="border-2 border-background">
+ *     <AvatarImage src="/user1.jpg" alt="User 1" />
+ *     <AvatarFallback>U1</AvatarFallback>
+ *   </Avatar>
+ *   <Avatar className="border-2 border-background">
+ *     <AvatarImage src="/user2.jpg" alt="User 2" />
+ *     <AvatarFallback>U2</AvatarFallback>
+ *   </Avatar>
+ *   <Avatar className="border-2 border-background">
+ *     <AvatarFallback>+3</AvatarFallback>
+ *   </Avatar>
+ * </div>
+ * ```
+ *
+ * @example Square avatar for logos
+ * ```tsx
+ * <Avatar className="rounded-lg">
+ *   <AvatarImage src="/company-logo.png" alt="Company" />
+ *   <AvatarFallback>CO</AvatarFallback>
+ * </Avatar>
+ * ```
+ *
+ * @example With status indicator
+ * ```tsx
+ * <div className="relative">
+ *   <Avatar>
+ *     <AvatarImage src="/user.jpg" alt="Online user" />
+ *     <AvatarFallback>OU</AvatarFallback>
+ *   </Avatar>
+ *   <div className="absolute bottom-0 right-0 size-3 bg-green-500 border-2 border-background rounded-full" />
+ * </div>
+ * ```
+ *
+ * @param className 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)
+ * @param children Should contain AvatarImage and AvatarFallback components for proper functionality
+ *
+ * @accessibility
+ * - Automatically manages focus and ARIA attributes through Radix UI
+ * - Always provide descriptive alt text for AvatarImage components
+ * - Fallback content should be meaningful (user initials, not generic placeholders)
+ * - Ensure sufficient color contrast for fallback text (minimum 4.5:1 ratio)
+ * - Component supports keyboard navigation and screen reader announcements
+ * - Status indicators should include appropriate ARIA labels
+ *
+ * @see {@link AvatarImage} The image component for displaying avatar pictures
+ * @see {@link AvatarFallback} The fallback component for displaying initials or icons when images fail
+ * @see {@link https://ui.shadcn.com/docs/components/avatar} shadcn/ui Avatar Documentation
+ * @see {@link https://www.radix-ui.com/docs/primitives/components/avatar} Radix UI Avatar Primitive
+ * @since 1.0.0
+ */
+function Avatar({
+  className,
+  ...props
+}: React.ComponentProps<typeof AvatarPrimitive.Root>) {
+  return (
+    <AvatarPrimitive.Root
+      data-slot="avatar"
+      className={cn(
+        "relative flex size-8 shrink-0 overflow-hidden rounded-full",
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+
+/**
+ * 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 image loading state management
+ * - Graceful error handling for broken image URLs
+ * - Proper aspect ratio maintenance (square by default)
+ * - Inherits parent Avatar's size and border radius
+ * - Accessible image implementation
+ *
+ * @component
+ * @example
+ * ```tsx
+ * // Basic usage with remote image
+ * <Avatar>
+ *   <AvatarImage
+ *     src="https://github.com/username.png"
+ *     alt="GitHub Profile Picture"
+ *   />
+ *   <AvatarFallback>GH</AvatarFallback>
+ * </Avatar>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Local image with descriptive alt text
+ * <Avatar>
+ *   <AvatarImage
+ *     src="/uploads/user-avatar.jpg"
+ *     alt="John Doe's profile picture"
+ *   />
+ *   <AvatarFallback>JD</AvatarFallback>
+ * </Avatar>
+ * ```
+ *
+ * @param src - The URL of the image to display. Can be relative or absolute URL
+ * @param alt - Descriptive alternative text for the image. Should describe the person or entity, not just "avatar" or "profile picture"
+ * @param className - Additional CSS classes to apply to the image element
+ * @param onLoadingStatusChange - Optional callback fired when the loading status changes
+ *
+ * @accessibility
+ * - Always provide descriptive alt text that identifies the person or entity
+ * - The image is automatically hidden from assistive technologies when loading or failed
+ * - Use meaningful descriptions like "John Doe's profile picture" rather than generic terms
+ * - The component handles ARIA attributes automatically via Radix UI
+ *
+ * @see {@link Avatar} - The parent container component
+ * @see {@link AvatarFallback} - The fallback component shown when image is unavailable
+ * @since 1.0.0
+ */
+function AvatarImage({
+  className,
+  ...props
+}: React.ComponentProps<typeof AvatarPrimitive.Image>) {
+  return (
+    <AvatarPrimitive.Image
+      data-slot="avatar-image"
+      className={cn("aspect-square size-full", className)}
+      {...props}
+    />
+  );
+}
+
+/**
+ * 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.
+ *
+ * ## Common Use Cases
+ * - User initials (most common pattern)
+ * - Generic user icons
+ * - Company/brand initials for organization avatars
+ * - Loading states with animations
+ * - Placeholder content for new users
+ *
+ * ## 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
+ *
+ * @component
+ * @example
+ * ```tsx
+ * // User initials (recommended pattern)
+ * <Avatar>
+ *   <AvatarImage src="/avatar.jpg" alt="John Doe" />
+ *   <AvatarFallback>JD</AvatarFallback>
+ * </Avatar>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Icon fallback for unknown users
+ * import { User } from "lucide-react";
+ *
+ * <Avatar>
+ *   <AvatarImage src="/unknown-user.jpg" alt="Anonymous User" />
+ *   <AvatarFallback>
+ *     <User className="size-4 text-muted-foreground" />
+ *   </AvatarFallback>
+ * </Avatar>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Custom colored fallback
+ * <Avatar>
+ *   <AvatarImage src="/user.jpg" alt="Jane Smith" />
+ *   <AvatarFallback className="bg-blue-500 text-white">
+ *     JS
+ *   </AvatarFallback>
+ * </Avatar>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Loading state with animation
+ * <Avatar>
+ *   <AvatarImage src="/loading-image.jpg" alt="Loading" />
+ *   <AvatarFallback className="animate-pulse">
+ *     <User className="size-4 text-muted-foreground" />
+ *   </AvatarFallback>
+ * </Avatar>
+ * ```
+ *
+ * @param children - The fallback content to display. Common patterns include user initials (2-3 characters), icons, or loading indicators
+ * @param className - Additional CSS classes. Use for custom background colors, text styling, or animations
+ * @param delayMs - Optional delay in milliseconds before showing the fallback (Radix UI feature)
+ *
+ * @accessibility
+ * - Content should be meaningful and descriptive
+ * - Ensure sufficient color contrast between text and background (minimum 4.5:1 ratio)
+ * - Keep text concise - typically 1-3 characters for initials
+ * - Icons should have appropriate sizing relative to the avatar
+ * - The component is automatically accessible via Radix UI implementation
+ *
+ * @see {@link Avatar} - The parent container component
+ * @see {@link AvatarImage} - The image component that this component provides fallback for
+ * @since 1.0.0
+ */
+function AvatarFallback({
+  className,
+  ...props
+}: React.ComponentProps<typeof AvatarPrimitive.Fallback>) {
+  return (
+    <AvatarPrimitive.Fallback
+      data-slot="avatar-fallback"
+      className={cn(
+        "bg-muted flex size-full items-center justify-center rounded-full",
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+
+export { Avatar, AvatarImage, AvatarFallback };