@neynar/ui 0.1.1 → 0.1.2

package/src/components/ui/alert.tsx

@@ -3,12 +3,20 @@ import { cva, type VariantProps } from "class-variance-authority";
 
 import { cn } from "@/lib/utils";
 
+/**
+ * Alert variant styles configuration with semantic color schemes
+ *
+ * @variant default - Standard informational alert with neutral colors
+ * @variant destructive - Error or warning alert with red color scheme for critical messages
+ */
 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: {
+        /** Standard informational alert with neutral card background and foreground colors */
         default: "bg-card text-card-foreground",
+        /** Error or destructive action alert with destructive color scheme and enhanced contrast */
         destructive:
           "text-destructive bg-card [&>svg]:text-current *:data-[slot=alert-description]:text-destructive/90",
       },
@@ -19,6 +27,42 @@ const alertVariants = cva(
   },
 );
 
+/**
+ * Props for Alert component (Documentation only - NOT used in component implementation)
+ * These types are for documentation generation and should not replace CVA/Radix inferred types
+ */
+// eslint-disable-next-line unused-imports/no-unused-vars
+type AlertDocsProps = {
+  /** Visual style variant determining colors and emphasis @default "default" */
+  variant?: "default" | "destructive";
+  /** Additional CSS classes to merge with default alert styles */
+  className?: string;
+  /** Alert content including optional icons, titles, and descriptions */
+  children?: React.ReactNode;
+} & React.HTMLAttributes<HTMLDivElement>;
+
+/**
+ * Props for AlertTitle component (Documentation only)
+ */
+// eslint-disable-next-line unused-imports/no-unused-vars
+type AlertTitleDocsProps = {
+  /** Additional CSS classes for custom styling */
+  className?: string;
+  /** Title text or rich content to display */
+  children?: React.ReactNode;
+} & React.HTMLAttributes<HTMLDivElement>;
+
+/**
+ * Props for AlertDescription component (Documentation only)
+ */
+// eslint-disable-next-line unused-imports/no-unused-vars
+type AlertDescriptionDocsProps = {
+  /** Additional CSS classes for custom styling */
+  className?: string;
+  /** Description text or rich content (supports paragraphs, links, etc.) */
+  children?: React.ReactNode;
+} & React.HTMLAttributes<HTMLDivElement>;
+
 /**
  * Alert - Display important messages and notifications to users
  *
@@ -131,7 +175,7 @@ function Alert({
   className,
   variant,
   ...props
-}: React.ComponentProps<"div"> & VariantProps<typeof alertVariants>) {
+}: React.HTMLAttributes<HTMLDivElement> & VariantProps<typeof alertVariants>) {
   return (
     <div
       data-slot="alert"
@@ -188,7 +232,10 @@ function Alert({
  * @see {@link AlertDescription} - Companion description component
  * @since 1.0.0
  */
-function AlertTitle({ className, ...props }: React.ComponentProps<"div">) {
+function AlertTitle({
+  className,
+  ...props
+}: React.HTMLAttributes<HTMLDivElement>) {
   return (
     <div
       data-slot="alert-title"
@@ -202,32 +249,88 @@ function AlertTitle({ className, ...props }: React.ComponentProps<"div">) {
 }
 
 /**
- * AlertDescription - Detailed description text for an alert
+ * AlertDescription - Detailed description text content for alerts
  *
- * Provides additional context or instructions related to the alert.
- * Supports multiple paragraphs and rich text content.
+ * The body content area of an alert that provides detailed information, context,
+ * or instructions related to the alert message. Automatically styled with muted
+ * text color and proper grid positioning. Supports rich content including
+ * paragraphs, links, and inline formatting.
+ *
+ * ## Features
+ * - Muted foreground color for visual hierarchy
+ * - Proper grid positioning (col-start-2) for icon layout compatibility
+ * - Support for multiple paragraphs with relaxed line height
+ * - Grid layout with start justification for text alignment
+ * - Semantic HTML structure with data-slot attribute
+ * - Small text size (text-sm) for readability
+ * - Responsive gap spacing between content elements
+ *
+ * @example
+ * ```tsx
+ * // Basic description with simple text
+ * <Alert>
+ *   <AlertTitle>Success</AlertTitle>
+ *   <AlertDescription>
+ *     Your account has been created successfully.
+ *   </AlertDescription>
+ * </Alert>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Description with multiple paragraphs
+ * <Alert variant="destructive">
+ *   <AlertCircle className="size-4" />
+ *   <AlertTitle>Connection Error</AlertTitle>
+ *   <AlertDescription>
+ *     <p>Unable to connect to the server. This could be due to:</p>
+ *     <p>• Network connectivity issues</p>
+ *     <p>• Server maintenance</p>
+ *     <p>Please try again in a few minutes.</p>
+ *   </AlertDescription>
+ * </Alert>
+ * ```
  *
- * @component
  * @example
  * ```tsx
+ * // Description with links and rich content
  * <Alert>
- *   <AlertTitle>Note</AlertTitle>
+ *   <Info className="size-4" />
+ *   <AlertTitle>Update Available</AlertTitle>
  *   <AlertDescription>
- *     Your changes have been saved. You can continue editing or publish when ready.
+ *     A new version is available. <a href="/changelog" className="underline">View changelog</a> or
+ *     <button className="ml-1 underline">update now</button>.
+ *   </AlertDescription>
+ * </Alert>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Custom styled description
+ * <Alert>
+ *   <AlertTitle>Custom Alert</AlertTitle>
+ *   <AlertDescription className="text-sm font-medium text-foreground">
+ *     This description uses custom styling to override the default muted appearance.
  *   </AlertDescription>
  * </Alert>
  * ```
  *
  * @accessibility
- * - Uses appropriate text color for readability
- * - Supports paragraph spacing for long content
+ * - Properly associated with the alert container via DOM structure
+ * - Uses muted text color while maintaining sufficient contrast ratios
+ * - Supports paragraph spacing and line height for readability
+ * - Screen readers announce description content as part of the alert
+ * - Rich content like links and buttons remain keyboard accessible
+ * - Works with dark mode via CSS custom properties
  *
+ * @see {@link Alert} - Parent alert container component
+ * @see {@link AlertTitle} - Companion title component for headers
  * @since 1.0.0
  */
 function AlertDescription({
   className,
   ...props
-}: React.ComponentProps<"div">) {
+}: React.HTMLAttributes<HTMLDivElement>) {
   return (
     <div
       data-slot="alert-description"

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

@@ -1,7 +1,24 @@
+import * as React from "react";
 import * as AspectRatioPrimitive from "@radix-ui/react-aspect-ratio";
 
 /**
- * AspectRatio component for maintaining consistent width-to-height ratios
+ * Props for AspectRatio (Documentation only - NOT used in component implementation)
+ * These types are for documentation generation and should not replace Radix inferred types
+ */
+// eslint-disable-next-line unused-imports/no-unused-vars
+type AspectRatioDocsProps = {
+  /** The desired aspect ratio as width divided by height (e.g., 16/9, 4/3, 1) @default 1 */
+  ratio?: number;
+  /** Child elements to be constrained within the aspect ratio container */
+  children?: React.ReactNode;
+  /** Additional CSS class names for custom styling */
+  className?: string;
+  /** Change the default rendered element for the one passed as a child, merging their props and behavior @default false */
+  asChild?: boolean;
+} & React.HTMLAttributes<HTMLDivElement>;
+
+/**
+ * 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
@@ -10,7 +27,8 @@ import * as AspectRatioPrimitive from "@radix-ui/react-aspect-ratio";
  *
  * 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.
+ * without layout shifts or JavaScript calculations. The component acts as a
+ * constraint wrapper that forces its children to maintain the specified ratio.
  *
  * @example Basic image with 16:9 aspect ratio
  * ```tsx
@@ -36,7 +54,7 @@ import * as AspectRatioPrimitive from "@radix-ui/react-aspect-ratio";
  * </AspectRatio>
  * ```
  *
- * @example Video player container
+ * @example Video player with 16:9 widescreen ratio
  * ```tsx
  * <div className="w-full max-w-2xl">
  *   <AspectRatio ratio={16 / 9}>
@@ -49,7 +67,7 @@ import * as AspectRatioPrimitive from "@radix-ui/react-aspect-ratio";
  * </div>
  * ```
  *
- * @example Responsive image gallery with portrait orientation
+ * @example Portrait orientation for image galleries
  * ```tsx
  * <div className="grid grid-cols-1 md:grid-cols-3 gap-4">
  *   {images.map((image) => (
@@ -76,24 +94,61 @@ import * as AspectRatioPrimitive from "@radix-ui/react-aspect-ratio";
  * </AspectRatio>
  * ```
  *
+ * @example Using asChild for composition
+ * ```tsx
+ * <AspectRatio ratio={16 / 9} asChild>
+ *   <div className="bg-gradient-to-br from-blue-400 to-purple-600 rounded-lg p-6">
+ *     <h3 className="text-white text-xl font-bold">Custom Content</h3>
+ *   </div>
+ * </AspectRatio>
+ * ```
+ *
+ * @example Common aspect ratios for different use cases
+ * ```tsx
+ * // Square (social media posts, avatars)
+ * <AspectRatio ratio={1}>Content</AspectRatio>
+ *
+ * // 16:9 (videos, hero images, banners)
+ * <AspectRatio ratio={16 / 9}>Content</AspectRatio>
+ *
+ * // 4:3 (traditional photos, tablets)
+ * <AspectRatio ratio={4 / 3}>Content</AspectRatio>
+ *
+ * // 3:2 (35mm photos, DSLR images)
+ * <AspectRatio ratio={3 / 2}>Content</AspectRatio>
+ *
+ * // 9:16 (mobile stories, vertical videos)
+ * <AspectRatio ratio={9 / 16}>Content</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
+ * @param asChild - Merge props with child element instead of wrapping
+ * @param ref - React ref forwarded to the container element
  *
  * @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
+ * - Preserves semantic meaning and structure of child content
+ * - Does not interfere with screen reader navigation or content reading
+ * - Maintains proper keyboard navigation for interactive child elements
+ * - Supports ARIA attributes passed through props
+ * - Container is semantically neutral and doesn't affect focus management
  *
- * @see {@link https://ui.shadcn.com/docs/components/aspect-ratio} shadcn/ui documentation
- * @since 1.0.0
+ * @see {@link https://ui.shadcn.com/docs/components/aspect-ratio} shadcn/ui AspectRatio
  * @see {@link https://www.radix-ui.com/primitives/docs/components/aspect-ratio} Radix UI AspectRatio
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/CSS/aspect-ratio} CSS aspect-ratio property
+ * @since 1.0.0
  */
-function AspectRatio({
-  ...props
-}: React.ComponentProps<typeof AspectRatioPrimitive.Root>) {
-  return <AspectRatioPrimitive.Root data-slot="aspect-ratio" {...props} />;
-}
+const AspectRatio = React.forwardRef<
+  React.ElementRef<typeof AspectRatioPrimitive.Root>,
+  React.ComponentPropsWithoutRef<typeof AspectRatioPrimitive.Root>
+>((props, ref) => {
+  return (
+    <AspectRatioPrimitive.Root ref={ref} data-slot="aspect-ratio" {...props} />
+  );
+});
+
+AspectRatio.displayName = "AspectRatio";
 
 export { AspectRatio };

package/src/components/ui/avatar.tsx

@@ -3,6 +3,68 @@ import * as AvatarPrimitive from "@radix-ui/react-avatar";
 
 import { cn } from "@/lib/utils";
 
+// ============================================================================
+// DOCUMENTATION-ONLY PROP TYPES (Internal - Not exported)
+// ============================================================================
+
+/**
+ * Props for Avatar (Documentation only - NOT used in component implementation)
+ * These types are for documentation generation and should not replace Radix inferred types
+ */
+// eslint-disable-next-line unused-imports/no-unused-vars
+type AvatarDocsProps = {
+  /** 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) */
+  className?: string;
+  /** Should contain AvatarImage and AvatarFallback components for proper functionality */
+  children?: React.ReactNode;
+  /** Change the default rendered element for the one passed as a child, merging their props and behavior
+   * @default false
+   */
+  asChild?: boolean;
+} & React.HTMLAttributes<HTMLSpanElement>;
+
+/**
+ * Props for AvatarImage (Documentation only - NOT used in component implementation)
+ * These types are for documentation generation and should not replace Radix inferred types
+ */
+// eslint-disable-next-line unused-imports/no-unused-vars
+type AvatarImageDocsProps = {
+  /** The URL of the image to display. Can be relative or absolute URL */
+  src?: string;
+  /** Descriptive alternative text for the image. Should describe the person or entity, not just "avatar" or "profile picture" */
+  alt?: string;
+  /** Additional CSS classes to apply to the image element */
+  className?: string;
+  /** Optional callback fired when the loading status changes
+   * @param status The current loading status: "idle" | "loading" | "loaded" | "error"
+   */
+  onLoadingStatusChange?: (
+    status: "idle" | "loading" | "loaded" | "error",
+  ) => void;
+  /** Change the default rendered element for the one passed as a child, merging their props and behavior
+   * @default false
+   */
+  asChild?: boolean;
+} & React.ImgHTMLAttributes<HTMLImageElement>;
+
+/**
+ * Props for AvatarFallback (Documentation only - NOT used in component implementation)
+ * These types are for documentation generation and should not replace Radix inferred types
+ */
+// eslint-disable-next-line unused-imports/no-unused-vars
+type AvatarFallbackDocsProps = {
+  /** The fallback content to display. Common patterns include user initials (2-3 characters), icons, or loading indicators */
+  children?: React.ReactNode;
+  /** Additional CSS classes. Use for custom background colors, text styling, or animations */
+  className?: string;
+  /** Optional delay in milliseconds before showing the fallback (Radix UI feature). Useful for delaying rendering so it only appears for those with slower connections */
+  delayMs?: number;
+  /** Change the default rendered element for the one passed as a child, merging their props and behavior
+   * @default false
+   */
+  asChild?: boolean;
+} & React.HTMLAttributes<HTMLSpanElement>;
+
 /**
  * Avatar - A flexible container for displaying user profile images with graceful fallback support
  *
@@ -20,6 +82,7 @@ import { cn } from "@/lib/utils";
  * - **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
@@ -88,8 +151,20 @@ import { cn } from "@/lib/utils";
  * </div>
  * ```
  *
+ * @example Using asChild for custom elements
+ * ```tsx
+ * <Avatar asChild>
+ *   <button onClick={handleClick}>
+ *     <AvatarImage src="/user.jpg" alt="User Profile" />
+ *     <AvatarFallback>UP</AvatarFallback>
+ *   </button>
+ * </Avatar>
+ * ```
+ *
  * @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
+ * @param asChild Change the default rendered element for the one passed as a child, merging their props and behavior
+ *   @default false
  *
  * @accessibility
  * - Automatically manages focus and ARIA attributes through Radix UI
@@ -98,6 +173,7 @@ import { cn } from "@/lib/utils";
  * - 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
+ * - When using asChild with interactive elements, ensure proper focus management
  *
  * @see {@link AvatarImage} The image component for displaying avatar pictures
  * @see {@link AvatarFallback} The fallback component for displaying initials or icons when images fail
@@ -130,16 +206,23 @@ function Avatar({
  * 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
+ * - **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
  *
  * @component
- * @example
+ * @example Basic usage with remote image
  * ```tsx
- * // Basic usage with remote image
  * <Avatar>
  *   <AvatarImage
  *     src="https://github.com/username.png"
@@ -149,9 +232,8 @@ function Avatar({
  * </Avatar>
  * ```
  *
- * @example
+ * @example Local image with descriptive alt text
  * ```tsx
- * // Local image with descriptive alt text
  * <Avatar>
  *   <AvatarImage
  *     src="/uploads/user-avatar.jpg"
@@ -161,19 +243,51 @@ function Avatar({
  * </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
+ * @example With loading status callback
+ * ```tsx
+ * <Avatar>
+ *   <AvatarImage
+ *     src="/large-image.jpg"
+ *     alt="High resolution avatar"
+ *     onLoadingStatusChange={(status) => {
+ *       if (status === 'loading') {
+ *         console.log('Image is loading...');
+ *       } else if (status === 'error') {
+ *         console.log('Failed to load image');
+ *       }
+ *     }}
+ *   />
+ *   <AvatarFallback>HR</AvatarFallback>
+ * </Avatar>
+ * ```
+ *
+ * @example Using asChild for custom image elements
+ * ```tsx
+ * <Avatar>
+ *   <AvatarImage src="/user.jpg" alt="User" asChild>
+ *     <img loading="lazy" decoding="async" />
+ *   </AvatarImage>
+ *   <AvatarFallback>U</AvatarFallback>
+ * </Avatar>
+ * ```
+ *
+ * @param src The URL of the image to display. Can be relative or absolute URL. When src changes, loading will restart
+ * @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. Applied to the img element or asChild component
+ * @param onLoadingStatusChange Optional callback fired when the loading status changes. Receives status: "idle" | "loading" | "loaded" | "error"
+ * @param asChild Change the default rendered element for the one passed as a child, merging their props and behavior
+ *   @default false
  *
  * @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
+ * - Loading and error states are communicated to screen readers appropriately
  *
- * @see {@link Avatar} - The parent container component
- * @see {@link AvatarFallback} - The fallback component shown when image is unavailable
+ * @see {@link Avatar} The parent container component
+ * @see {@link AvatarFallback} The fallback component shown when image is unavailable
+ * @see {@link https://www.radix-ui.com/docs/primitives/components/avatar#image} Radix UI Avatar.Image API
  * @since 1.0.0
  */
 function AvatarImage({
@@ -196,32 +310,39 @@ function AvatarImage({
  * 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)
- * - Generic user icons
- * - Company/brand initials for organization avatars
- * - Loading states with animations
- * - Placeholder content for new users
+ * - **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
  *
  * @component
- * @example
+ * @example User initials (recommended pattern)
  * ```tsx
- * // User initials (recommended pattern)
  * <Avatar>
  *   <AvatarImage src="/avatar.jpg" alt="John Doe" />
  *   <AvatarFallback>JD</AvatarFallback>
  * </Avatar>
  * ```
  *
- * @example
+ * @example Icon fallback for unknown users
  * ```tsx
- * // Icon fallback for unknown users
  * import { User } from "lucide-react";
  *
  * <Avatar>
@@ -232,9 +353,8 @@ function AvatarImage({
  * </Avatar>
  * ```
  *
- * @example
+ * @example Custom colored fallback
  * ```tsx
- * // Custom colored fallback
  * <Avatar>
  *   <AvatarImage src="/user.jpg" alt="Jane Smith" />
  *   <AvatarFallback className="bg-blue-500 text-white">
@@ -243,9 +363,8 @@ function AvatarImage({
  * </Avatar>
  * ```
  *
- * @example
+ * @example Loading state with animation
  * ```tsx
- * // Loading state with animation
  * <Avatar>
  *   <AvatarImage src="/loading-image.jpg" alt="Loading" />
  *   <AvatarFallback className="animate-pulse">
@@ -254,9 +373,34 @@ function AvatarImage({
  * </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)
+ * @example With delay to prevent flash
+ * ```tsx
+ * <Avatar>
+ *   <AvatarImage src="/slow-loading-image.jpg" alt="User" />
+ *   <AvatarFallback delayMs={600}>
+ *     UN
+ *   </AvatarFallback>
+ * </Avatar>
+ * ```
+ *
+ * @example Using asChild for custom elements
+ * ```tsx
+ * <Avatar>
+ *   <AvatarImage src="/user.jpg" alt="User" />
+ *   <AvatarFallback asChild>
+ *     <div className="bg-gradient-to-br from-blue-400 to-purple-600">
+ *       <span className="text-white font-semibold">UN</span>
+ *     </div>
+ *   </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. Useful for delaying rendering so it only appears for those with slower connections
+ *   @default undefined
+ * @param asChild Change the default rendered element for the one passed as a child, merging their props and behavior
+ *   @default false
  *
  * @accessibility
  * - Content should be meaningful and descriptive
@@ -264,9 +408,11 @@ function AvatarImage({
  * - 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
+ * - Consider adding aria-label for complex fallback content
  *
- * @see {@link Avatar} - The parent container component
- * @see {@link AvatarImage} - The image component that this component provides fallback for
+ * @see {@link Avatar} The parent container component
+ * @see {@link AvatarImage} The image component that this component provides fallback for
+ * @see {@link https://www.radix-ui.com/docs/primitives/components/avatar#fallback} Radix UI Avatar.Fallback API
  * @since 1.0.0
  */
 function AvatarFallback({