@neynar/ui 0.1.1 → 0.1.2

package/src/components/ui/badge.tsx

@@ -20,11 +20,10 @@ import { cn } from "@/lib/utils";
  * - 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
@@ -48,16 +47,12 @@ const badgeVariants = cva(
   {
     variants: {
       variant: {
-        /** Primary badge with brand colors - use for important status or primary actions */
         default:
           "border-transparent bg-primary text-primary-foreground [a&]:hover:bg-primary/90",
-        /** Secondary badge with muted colors - use for supplementary information */
         secondary:
           "border-transparent bg-secondary text-secondary-foreground [a&]:hover:bg-secondary/90",
-        /** Destructive badge for errors/warnings - use for critical states */
         destructive:
           "border-transparent bg-destructive text-white [a&]:hover:bg-destructive/90 focus-visible:ring-destructive/20 dark:focus-visible:ring-destructive/40 dark:bg-destructive/60",
-        /** Outline badge with border only - use for subtle labeling */
         outline:
           "text-foreground [a&]:hover:bg-accent [a&]:hover:text-accent-foreground",
       },
@@ -69,38 +64,39 @@ const badgeVariants = cva(
 );
 
 /**
- * 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
+ * Props for Badge component (Documentation only - NOT used in component implementation)
+ * This type is for documentation generation and should not replace CVA/Radix inferred types
+ */
+// eslint-disable-next-line unused-imports/no-unused-vars
+type BadgeDocsProps = {
+  /** The visual variant of the badge that determines its color scheme and emphasis level */
+  variant?: "default" | "secondary" | "destructive" | "outline";
+  /** Additional CSS classes to apply to the badge for custom styling */
+  className?: string;
+  /** Content to display inside the badge (text, icons, or React components) */
+  children?: React.ReactNode;
+  /**
+   * Renders the badge as its child element instead of a span element.
+   * Enables polymorphic behavior 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 badge styling and attributes via Radix UI Slot.
+   *
+   * @default false
+   */
+  asChild?: boolean;
+} & Omit<React.HTMLAttributes<HTMLSpanElement>, "children">;
+
+/**
+ * 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>
@@ -109,16 +105,16 @@ const badgeVariants = cva(
  *
  * @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>
  * ```
@@ -126,9 +122,9 @@ const badgeVariants = cva(
  * @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>
@@ -136,11 +132,11 @@ const badgeVariants = cva(
  *
  * @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>
@@ -148,17 +144,41 @@ const badgeVariants = cva(
  *
  * @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
  */
 function Badge({
@@ -166,29 +186,8 @@ function Badge({
   variant,
   asChild = false,
   ...props
-}: React.ComponentProps<"span"> &
+}: React.HTMLAttributes<HTMLSpanElement> &
   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>
-     * ```
-     */
     asChild?: boolean;
   }) {
   const Comp = asChild ? Slot : "span";