@neynar/ui 0.1.1 → 0.1.2

package/dist/components/ui/aspect-ratio.d.ts

@@ -1,6 +1,7 @@
+import * as React from "react";
 import * as AspectRatioPrimitive from "@radix-ui/react-aspect-ratio";
 /**
- * AspectRatio component for maintaining consistent width-to-height ratios
+ * 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
@@ -9,7 +10,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
@@ -35,7 +37,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}>
@@ -48,7 +50,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) => (
@@ -75,20 +77,52 @@ 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
  */
-declare function AspectRatio({ ...props }: React.ComponentProps<typeof AspectRatioPrimitive.Root>): import("react/jsx-runtime").JSX.Element;
+declare const AspectRatio: React.ForwardRefExoticComponent<Omit<AspectRatioPrimitive.AspectRatioProps & React.RefAttributes<HTMLDivElement>, "ref"> & React.RefAttributes<HTMLDivElement>>;
 export { AspectRatio };
 //# sourceMappingURL=aspect-ratio.d.ts.map

package/dist/components/ui/aspect-ratio.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"aspect-ratio.d.ts","sourceRoot":"","sources":["../../../src/components/ui/aspect-ratio.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,oBAAoB,MAAM,8BAA8B,CAAC;AAErE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyFG;AACH,iBAAS,WAAW,CAAC,EACnB,GAAG,KAAK,EACT,EAAE,KAAK,CAAC,cAAc,CAAC,OAAO,oBAAoB,CAAC,IAAI,CAAC,2CAExD;AAED,OAAO,EAAE,WAAW,EAAE,CAAC"}
+{"version":3,"file":"aspect-ratio.d.ts","sourceRoot":"","sources":["../../../src/components/ui/aspect-ratio.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAC/B,OAAO,KAAK,oBAAoB,MAAM,8BAA8B,CAAC;AAkBrE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0HG;AACH,QAAA,MAAM,WAAW,iKAOf,CAAC;AAIH,OAAO,EAAE,WAAW,EAAE,CAAC"}

package/dist/components/ui/avatar.d.ts

@@ -17,6 +17,7 @@ import * as AvatarPrimitive from "@radix-ui/react-avatar";
  * - **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
@@ -85,8 +86,20 @@ import * as AvatarPrimitive from "@radix-ui/react-avatar";
  * </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
@@ -95,6 +108,7 @@ import * as AvatarPrimitive from "@radix-ui/react-avatar";
  * - 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
@@ -112,16 +126,23 @@ declare function Avatar({ className, ...props }: React.ComponentProps<typeof Ava
  * 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"
@@ -131,9 +152,8 @@ declare function Avatar({ className, ...props }: React.ComponentProps<typeof Ava
  * </Avatar>
  * ```
  *
- * @example
+ * @example Local image with descriptive alt text
  * ```tsx
- * // Local image with descriptive alt text
  * <Avatar>
  *   <AvatarImage
  *     src="/uploads/user-avatar.jpg"
@@ -143,19 +163,51 @@ declare function Avatar({ className, ...props }: React.ComponentProps<typeof Ava
  * </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
  */
 declare function AvatarImage({ className, ...props }: React.ComponentProps<typeof AvatarPrimitive.Image>): import("react/jsx-runtime").JSX.Element;
@@ -166,32 +218,39 @@ declare function AvatarImage({ className, ...props }: React.ComponentProps<typeo
  * 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>
@@ -202,9 +261,8 @@ declare function AvatarImage({ className, ...props }: React.ComponentProps<typeo
  * </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">
@@ -213,9 +271,8 @@ declare function AvatarImage({ className, ...props }: React.ComponentProps<typeo
  * </Avatar>
  * ```
  *
- * @example
+ * @example Loading state with animation
  * ```tsx
- * // Loading state with animation
  * <Avatar>
  *   <AvatarImage src="/loading-image.jpg" alt="Loading" />
  *   <AvatarFallback className="animate-pulse">
@@ -224,9 +281,34 @@ declare function AvatarImage({ className, ...props }: React.ComponentProps<typeo
  * </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
@@ -234,9 +316,11 @@ declare function AvatarImage({ className, ...props }: React.ComponentProps<typeo
  * - 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
  */
 declare function AvatarFallback({ className, ...props }: React.ComponentProps<typeof AvatarPrimitive.Fallback>): import("react/jsx-runtime").JSX.Element;

package/dist/components/ui/avatar.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"avatar.d.ts","sourceRoot":"","sources":["../../../src/components/ui/avatar.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAC/B,OAAO,KAAK,eAAe,MAAM,wBAAwB,CAAC;AAI1D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqGG;AACH,iBAAS,MAAM,CAAC,EACd,SAAS,EACT,GAAG,KAAK,EACT,EAAE,KAAK,CAAC,cAAc,CAAC,OAAO,eAAe,CAAC,IAAI,CAAC,2CAWnD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsDG;AACH,iBAAS,WAAW,CAAC,EACnB,SAAS,EACT,GAAG,KAAK,EACT,EAAE,KAAK,CAAC,cAAc,CAAC,OAAO,eAAe,CAAC,KAAK,CAAC,2CAQpD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+EG;AACH,iBAAS,cAAc,CAAC,EACtB,SAAS,EACT,GAAG,KAAK,EACT,EAAE,KAAK,CAAC,cAAc,CAAC,OAAO,eAAe,CAAC,QAAQ,CAAC,2CAWvD;AAED,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,cAAc,EAAE,CAAC"}
+{"version":3,"file":"avatar.d.ts","sourceRoot":"","sources":["../../../src/components/ui/avatar.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAC/B,OAAO,KAAK,eAAe,MAAM,wBAAwB,CAAC;AAkE1D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmHG;AACH,iBAAS,MAAM,CAAC,EACd,SAAS,EACT,GAAG,KAAK,EACT,EAAE,KAAK,CAAC,cAAc,CAAC,OAAO,eAAe,CAAC,IAAI,CAAC,2CAWnD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4FG;AACH,iBAAS,WAAW,CAAC,EACnB,SAAS,EACT,GAAG,KAAK,EACT,EAAE,KAAK,CAAC,cAAc,CAAC,OAAO,eAAe,CAAC,KAAK,CAAC,2CAQpD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+GG;AACH,iBAAS,cAAc,CAAC,EACtB,SAAS,EACT,GAAG,KAAK,EACT,EAAE,KAAK,CAAC,cAAc,CAAC,OAAO,eAAe,CAAC,QAAQ,CAAC,2CAWvD;AAED,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,cAAc,EAAE,CAAC"}

package/dist/components/ui/badge.d.ts

@@ -16,11 +16,10 @@ import { type VariantProps } from "class-variance-authority";
  * - Accessibility features (focus rings, error states)
  * - Smooth transitions for interactive states
  *
- * ## Variants
- * - **default**: Primary brand color, high emphasis
- * - **secondary**: Muted background, medium emphasis
- * - **destructive**: Error/warning states, urgent attention
- * - **outline**: Subtle border-only style, low emphasis
+ * @variant default - Primary brand color badge for important status indicators and primary actions
+ * @variant secondary - Muted background badge for supplementary information and low-priority labels
+ * @variant destructive - Error/warning badge for critical states, failures, and urgent attention
+ * @variant outline - Subtle border-only badge for minimal emphasis and subtle labeling
  *
  * @param props - Variant configuration object
  * @param props.variant - The visual variant to apply
@@ -43,38 +42,15 @@ declare const badgeVariants: (props?: ({
     variant?: "default" | "destructive" | "outline" | "secondary" | null | undefined;
 } & import("class-variance-authority/types").ClassProp) | undefined) => string;
 /**
- * A versatile badge component for displaying status indicators, labels, counts, and notifications.
- *
- * Badges are small status descriptors for UI elements. They provide visual feedback about the state,
- * category, or importance of content. The component is built with accessibility in mind and supports
- * multiple visual variants for different semantic meanings.
- *
- * ## Key Features
- * - Multiple semantic variants (default, secondary, destructive, outline)
- * - Icon support with proper sizing and spacing
- * - Polymorphic rendering via `asChild` prop
- * - Accessibility-first design with proper focus management
- * - Support for interactive states (hover, focus, invalid)
- * - Built-in responsive behavior
- *
- * ## When to Use
- * - Status indicators (active, pending, error)
- * - Notification counts and badges
- * - Category labels and tags
- * - Priority indicators
- * - Quick action buttons (when used with asChild)
- *
- * ## Accessibility Features
- * - Keyboard navigation support with focus-visible ring
- * - High contrast colors for all variants
- * - Support for `aria-invalid` state with visual feedback
- * - Semantic color mapping (destructive = error, etc.)
- * - Screen reader friendly content structure
- *
- * @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.
+ *
  * @example
  * ```tsx
- * // Basic status badge
+ * // Basic status badges
  * <Badge>New</Badge>
  * <Badge variant="secondary">Draft</Badge>
  * <Badge variant="destructive">Error</Badge>
@@ -83,16 +59,16 @@ declare const badgeVariants: (props?: ({
  *
  * @example
  * ```tsx
- * // Badge with icon
+ * // Badge with icon content
  * import { Check, AlertTriangle } from "lucide-react";
  *
  * <Badge>
- *   <Check />
+ *   <Check className="mr-1" />
  *   Completed
  * </Badge>
  *
  * <Badge variant="destructive">
- *   <AlertTriangle />
+ *   <AlertTriangle className="mr-1" />
  *   Failed
  * </Badge>
  * ```
@@ -100,9 +76,9 @@ declare const badgeVariants: (props?: ({
  * @example
  * ```tsx
  * // Notification count badge
- * <div className="relative">
- *   <Bell />
- *   <Badge className="absolute -top-2 -right-2 size-5 p-0 text-xs">
+ * <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>
@@ -110,11 +86,11 @@ declare const badgeVariants: (props?: ({
  *
  * @example
  * ```tsx
- * // Interactive badge as link
+ * // Interactive badge as link using asChild
  * import Link from "next/link";
  *
  * <Badge asChild>
- *   <Link href="/notifications">
+ *   <Link href="/notifications" className="cursor-pointer">
  *     3 new messages
  *   </Link>
  * </Badge>
@@ -122,41 +98,44 @@ declare const badgeVariants: (props?: ({
  *
  * @example
  * ```tsx
- * // Removable tag badge
- * <Badge className="pr-1">
+ * // Interactive badge as button
+ * <Badge asChild>
+ *   <button onClick={handleDismiss} className="cursor-pointer">
+ *     Dismiss Alert
+ *   </button>
+ * </Badge>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Removable tag badge with close button
+ * <Badge className="pr-1 gap-1">
  *   React
- *   <button className="ml-1 hover:bg-primary-foreground/20 rounded-full p-0.5">
- *     <X className="size-3" />
+ *   <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>
  * ```
  *
- * @see {@link Button} - For primary actionable elements
- * @see [shadcn/ui Badge Documentation](https://ui.shadcn.com/docs/components/badge)
+ * @accessibility
+ * - Full keyboard navigation support with focus-visible ring indicators
+ * - High contrast colors across all variants for WCAG AA compliance
+ * - Support for aria-invalid state with visual feedback for form validation
+ * - Semantic color mapping (destructive variant indicates errors)
+ * - Screen reader friendly content structure and labeling
+ * - When used with asChild, inherits accessibility properties of child element
+ * - Focus management handled by underlying Radix UI Slot primitive
+ *
+ * @see {@link Button} For primary interactive elements and calls-to-action
+ * @see {@link https://ui.shadcn.com/docs/components/badge} shadcn/ui Badge Documentation
+ * @see {@link https://www.radix-ui.com/primitives/docs/utilities/slot} Radix UI Slot Documentation
  * @since 1.0.0
  */
-declare function Badge({ className, variant, asChild, ...props }: React.ComponentProps<"span"> & VariantProps<typeof badgeVariants> & {
-    /**
-     * If true, the badge will render its child element instead of a span element.
-     * Useful for creating badge-styled links, buttons, or other interactive elements.
-     *
-     * When true, you must provide exactly one child element that can receive props.
-     * The child element will receive all the badge styling and attributes.
-     *
-     * @default false
-     * @example
-     * ```tsx
-     * // Badge as a link
-     * <Badge asChild>
-     *   <Link href="/profile">Profile</Link>
-     * </Badge>
-     *
-     * // Badge as a button
-     * <Badge asChild>
-     *   <button onClick={handleClick}>Click me</button>
-     * </Badge>
-     * ```
-     */
+declare function Badge({ className, variant, asChild, ...props }: React.HTMLAttributes<HTMLSpanElement> & VariantProps<typeof badgeVariants> & {
     asChild?: boolean;
 }): import("react/jsx-runtime").JSX.Element;
 export { Badge, badgeVariants };

package/dist/components/ui/badge.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"badge.d.ts","sourceRoot":"","sources":["../../../src/components/ui/badge.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAE/B,OAAO,EAAO,KAAK,YAAY,EAAE,MAAM,0BAA0B,CAAC;AAIlE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,QAAA,MAAM,aAAa;;8EAuBlB,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4FG;AACH,iBAAS,KAAK,CAAC,EACb,SAAS,EACT,OAAO,EACP,OAAe,EACf,GAAG,KAAK,EACT,EAAE,KAAK,CAAC,cAAc,CAAC,MAAM,CAAC,GAC7B,YAAY,CAAC,OAAO,aAAa,CAAC,GAAG;IACnC;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB,2CAUF;AAED,OAAO,EAAE,KAAK,EAAE,aAAa,EAAE,CAAC"}
+{"version":3,"file":"badge.d.ts","sourceRoot":"","sources":["../../../src/components/ui/badge.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAE/B,OAAO,EAAO,KAAK,YAAY,EAAE,MAAM,0BAA0B,CAAC;AAIlE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,QAAA,MAAM,aAAa;;8EAmBlB,CAAC;AA0BF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6FG;AACH,iBAAS,KAAK,CAAC,EACb,SAAS,EACT,OAAO,EACP,OAAe,EACf,GAAG,KAAK,EACT,EAAE,KAAK,CAAC,cAAc,CAAC,eAAe,CAAC,GACtC,YAAY,CAAC,OAAO,aAAa,CAAC,GAAG;IACnC,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB,2CAUF;AAED,OAAO,EAAE,KAAK,EAAE,aAAa,EAAE,CAAC"}