@neynar/ui 0.1.1

package/src/components/ui/badge.tsx

@@ -0,0 +1,205 @@
+import * as React from "react";
+import { Slot } from "@radix-ui/react-slot";
+import { cva, type VariantProps } from "class-variance-authority";
+
+import { cn } from "@/lib/utils";
+
+/**
+ * Badge variant styles using class-variance-authority (CVA).
+ *
+ * This function generates type-safe CSS classes for different badge variants.
+ * Each variant is designed with specific semantic meaning and appropriate
+ * color schemes for both light and dark themes.
+ *
+ * ## Base Styles
+ * - Inline flex layout with center alignment
+ * - Fixed height with responsive padding
+ * - Rounded corners and border
+ * - Typography: small, medium weight, no wrap
+ * - Icon support with consistent sizing
+ * - 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
+ *
+ * @param props - Variant configuration object
+ * @param props.variant - The visual variant to apply
+ * @returns CSS class string for the specified variant
+ *
+ * @example
+ * ```tsx
+ * // Use directly with className
+ * <span className={badgeVariants({ variant: "destructive" })}>
+ *   Error
+ * </span>
+ *
+ * // Combine with additional classes
+ * <span className={cn(badgeVariants({ variant: "outline" }), "custom-class")}>
+ *   Custom Badge
+ * </span>
+ * ```
+ */
+const badgeVariants = cva(
+  "inline-flex items-center justify-center rounded-md border px-2 py-0.5 text-xs font-medium w-fit whitespace-nowrap shrink-0 [&>svg]:size-3 gap-1 [&>svg]:pointer-events-none focus-visible:border-ring focus-visible:ring-ring/50 focus-visible:ring-[3px] aria-invalid:ring-destructive/20 dark:aria-invalid:ring-destructive/40 aria-invalid:border-destructive transition-[color,box-shadow] overflow-hidden",
+  {
+    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",
+      },
+    },
+    defaultVariants: {
+      variant: "default",
+    },
+  },
+);
+
+/**
+ * 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
+ * @example
+ * ```tsx
+ * // Basic status badge
+ * <Badge>New</Badge>
+ * <Badge variant="secondary">Draft</Badge>
+ * <Badge variant="destructive">Error</Badge>
+ * <Badge variant="outline">Pending</Badge>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Badge with icon
+ * import { Check, AlertTriangle } from "lucide-react";
+ *
+ * <Badge>
+ *   <Check />
+ *   Completed
+ * </Badge>
+ *
+ * <Badge variant="destructive">
+ *   <AlertTriangle />
+ *   Failed
+ * </Badge>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Notification count badge
+ * <div className="relative">
+ *   <Bell />
+ *   <Badge className="absolute -top-2 -right-2 size-5 p-0 text-xs">
+ *     3
+ *   </Badge>
+ * </div>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Interactive badge as link
+ * import Link from "next/link";
+ *
+ * <Badge asChild>
+ *   <Link href="/notifications">
+ *     3 new messages
+ *   </Link>
+ * </Badge>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Removable tag badge
+ * <Badge className="pr-1">
+ *   React
+ *   <button className="ml-1 hover:bg-primary-foreground/20 rounded-full p-0.5">
+ *     <X className="size-3" />
+ *   </button>
+ * </Badge>
+ * ```
+ *
+ * @see {@link Button} - For primary actionable elements
+ * @see [shadcn/ui Badge Documentation](https://ui.shadcn.com/docs/components/badge)
+ * @since 1.0.0
+ */
+function Badge({
+  className,
+  variant,
+  asChild = false,
+  ...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>
+     * ```
+     */
+    asChild?: boolean;
+  }) {
+  const Comp = asChild ? Slot : "span";
+
+  return (
+    <Comp
+      data-slot="badge"
+      className={cn(badgeVariants({ variant }), className)}
+      {...props}
+    />
+  );
+}
+
+export { Badge, badgeVariants };

package/src/components/ui/breadcrumb.tsx

@@ -0,0 +1,378 @@
+import * as React from "react";
+import { Slot } from "@radix-ui/react-slot";
+import { ChevronRight, MoreHorizontal } from "lucide-react";
+
+import { cn } from "@/lib/utils";
+
+/**
+ * Breadcrumb navigation component that displays hierarchical page location
+ *
+ * A breadcrumb navigation component built on semantic HTML that shows the current page
+ * location within a navigational hierarchy. Provides users with contextual awareness
+ * of their position in the site structure and enables easy navigation to parent pages.
+ *
+ * Based on the shadcn/ui Breadcrumb component with accessibility features and
+ * support for composition patterns including custom separators, ellipsis for long
+ * paths, dropdown menus, and custom link components via the asChild prop.
+ *
+ * @example
+ * ```tsx
+ * // Basic breadcrumb navigation
+ * <Breadcrumb>
+ *   <BreadcrumbList>
+ *     <BreadcrumbItem>
+ *       <BreadcrumbLink href="/">Home</BreadcrumbLink>
+ *     </BreadcrumbItem>
+ *     <BreadcrumbSeparator />
+ *     <BreadcrumbItem>
+ *       <BreadcrumbLink href="/products">Products</BreadcrumbLink>
+ *     </BreadcrumbItem>
+ *     <BreadcrumbSeparator />
+ *     <BreadcrumbItem>
+ *       <BreadcrumbPage>Laptop</BreadcrumbPage>
+ *     </BreadcrumbItem>
+ *   </BreadcrumbList>
+ * </Breadcrumb>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // With ellipsis for long paths
+ * <Breadcrumb>
+ *   <BreadcrumbList>
+ *     <BreadcrumbItem>
+ *       <BreadcrumbLink href="/">Home</BreadcrumbLink>
+ *     </BreadcrumbItem>
+ *     <BreadcrumbSeparator />
+ *     <BreadcrumbItem>
+ *       <BreadcrumbEllipsis />
+ *     </BreadcrumbItem>
+ *     <BreadcrumbSeparator />
+ *     <BreadcrumbItem>
+ *       <BreadcrumbLink href="/products/laptops">Laptops</BreadcrumbLink>
+ *     </BreadcrumbItem>
+ *     <BreadcrumbSeparator />
+ *     <BreadcrumbItem>
+ *       <BreadcrumbPage>Gaming Laptop</BreadcrumbPage>
+ *     </BreadcrumbItem>
+ *   </BreadcrumbList>
+ * </Breadcrumb>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // With Next.js Link integration
+ * import { Link } from "next/link"
+ *
+ * <Breadcrumb>
+ *   <BreadcrumbList>
+ *     <BreadcrumbItem>
+ *       <BreadcrumbLink asChild>
+ *         <Link href="/">Home</Link>
+ *       </BreadcrumbLink>
+ *     </BreadcrumbItem>
+ *     <BreadcrumbSeparator />
+ *     <BreadcrumbItem>
+ *       <BreadcrumbPage>Current Page</BreadcrumbPage>
+ *     </BreadcrumbItem>
+ *   </BreadcrumbList>
+ * </Breadcrumb>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // With custom separator
+ * import { Slash } from "lucide-react"
+ *
+ * <Breadcrumb>
+ *   <BreadcrumbList>
+ *     <BreadcrumbItem>
+ *       <BreadcrumbLink href="/">Home</BreadcrumbLink>
+ *     </BreadcrumbItem>
+ *     <BreadcrumbSeparator>
+ *       <Slash />
+ *     </BreadcrumbSeparator>
+ *     <BreadcrumbItem>
+ *       <BreadcrumbPage>Current Page</BreadcrumbPage>
+ *     </BreadcrumbItem>
+ *   </BreadcrumbList>
+ * </Breadcrumb>
+ * ```
+ *
+ * @accessibility
+ * - Uses semantic `nav` element with `aria-label="breadcrumb"`
+ * - Current page marked with `aria-current="page"`
+ * - Separators marked with `role="presentation"` and `aria-hidden="true"`
+ * - Screen reader friendly navigation structure
+ * - Supports keyboard navigation through links
+ *
+ * @see {@link https://ui.shadcn.com/docs/components/breadcrumb} for design patterns
+ * @see {@link BreadcrumbList} - Ordered list container for breadcrumb items
+ * @see {@link BreadcrumbItem} - Individual breadcrumb list item
+ * @see {@link BreadcrumbLink} - Navigable breadcrumb link with asChild support
+ * @see {@link BreadcrumbPage} - Current page indicator (non-clickable)
+ * @see {@link BreadcrumbSeparator} - Visual separator between items
+ * @see {@link BreadcrumbEllipsis} - Ellipsis indicator for collapsed items
+ * @since 1.0.0
+ */
+function Breadcrumb({ ...props }: React.ComponentProps<"nav">) {
+  return <nav aria-label="breadcrumb" data-slot="breadcrumb" {...props} />;
+}
+
+/**
+ * Ordered list container for breadcrumb items
+ *
+ * Provides the structured list layout for breadcrumb navigation items with
+ * responsive spacing and text overflow handling. Uses semantic `ol` element
+ * for proper accessibility and screen reader navigation.
+ *
+ * @param className - Additional CSS classes to apply
+ * @param props - Standard HTML ordered list props
+ *
+ * @example
+ * ```tsx
+ * <BreadcrumbList>
+ *   <BreadcrumbItem>
+ *     <BreadcrumbLink href="/">Home</BreadcrumbLink>
+ *   </BreadcrumbItem>
+ * </BreadcrumbList>
+ * ```
+ *
+ * @since 1.0.0
+ */
+function BreadcrumbList({ className, ...props }: React.ComponentProps<"ol">) {
+  return (
+    <ol
+      data-slot="breadcrumb-list"
+      className={cn(
+        "text-muted-foreground flex flex-wrap items-center gap-1.5 text-sm break-words sm:gap-2.5",
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+
+/**
+ * Individual breadcrumb list item container
+ *
+ * Wraps breadcrumb content (links, pages, separators) in a semantic list item.
+ * Provides consistent alignment and spacing for breadcrumb elements.
+ *
+ * @param className - Additional CSS classes to apply
+ * @param props - Standard HTML list item props
+ *
+ * @example
+ * ```tsx
+ * <BreadcrumbItem>
+ *   <BreadcrumbLink href="/products">Products</BreadcrumbLink>
+ * </BreadcrumbItem>
+ * ```
+ *
+ * @since 1.0.0
+ */
+function BreadcrumbItem({ className, ...props }: React.ComponentProps<"li">) {
+  return (
+    <li
+      data-slot="breadcrumb-item"
+      className={cn("inline-flex items-center gap-1.5", className)}
+      {...props}
+    />
+  );
+}
+
+/**
+ * Navigable link within breadcrumb trail
+ *
+ * Represents a clickable parent page in the breadcrumb hierarchy with hover
+ * effects and transition animations. Supports composition via the `asChild` prop
+ * for integration with routing libraries like Next.js Link or React Router.
+ *
+ * @param asChild - When true, renders children directly instead of an anchor element
+ * @param className - Additional CSS classes to apply
+ * @param props - Standard HTML anchor props when asChild is false
+ *
+ * @example
+ * ```tsx
+ * // Standard link
+ * <BreadcrumbLink href="/products">Products</BreadcrumbLink>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // With Next.js Link
+ * <BreadcrumbLink asChild>
+ *   <Link href="/products">Products</Link>
+ * </BreadcrumbLink>
+ * ```
+ *
+ * @since 1.0.0
+ */
+function BreadcrumbLink({
+  asChild,
+  className,
+  ...props
+}: React.ComponentProps<"a"> & {
+  asChild?: boolean;
+}) {
+  const Comp = asChild ? Slot : "a";
+
+  return (
+    <Comp
+      data-slot="breadcrumb-link"
+      className={cn("hover:text-foreground transition-colors", className)}
+      {...props}
+    />
+  );
+}
+
+/**
+ * Current page indicator in breadcrumb trail
+ *
+ * Represents the current page (non-clickable) at the end of the breadcrumb trail.
+ * Styled with prominent text color and marked with accessibility attributes
+ * including `aria-current="page"` for screen reader identification.
+ *
+ * @param className - Additional CSS classes to apply
+ * @param props - Standard HTML span props
+ *
+ * @example
+ * ```tsx
+ * <BreadcrumbPage>Current Page Name</BreadcrumbPage>
+ * ```
+ *
+ * @accessibility
+ * - Uses `role="link"` with `aria-disabled="true"` for semantic meaning
+ * - Marked with `aria-current="page"` to indicate current location
+ *
+ * @since 1.0.0
+ */
+function BreadcrumbPage({ className, ...props }: React.ComponentProps<"span">) {
+  return (
+    <span
+      data-slot="breadcrumb-page"
+      role="link"
+      aria-disabled="true"
+      aria-current="page"
+      className={cn("text-foreground font-normal", className)}
+      {...props}
+    />
+  );
+}
+
+/**
+ * Visual separator between breadcrumb items
+ *
+ * Displays a separator icon (default: ChevronRight) between breadcrumb items.
+ * Supports custom separator icons by passing them as children. Hidden from
+ * screen readers with accessibility attributes for clean navigation experience.
+ *
+ * @param children - Custom separator icon to display instead of default ChevronRight
+ * @param className - Additional CSS classes to apply
+ * @param props - Standard HTML list item props
+ *
+ * @example
+ * ```tsx
+ * // Default separator
+ * <BreadcrumbSeparator />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Custom separator
+ * import { Slash } from "lucide-react"
+ * <BreadcrumbSeparator>
+ *   <Slash />
+ * </BreadcrumbSeparator>
+ * ```
+ *
+ * @accessibility
+ * - Uses `role="presentation"` to indicate decorative content
+ * - Hidden from screen readers with `aria-hidden="true"`
+ *
+ * @since 1.0.0
+ */
+function BreadcrumbSeparator({
+  children,
+  className,
+  ...props
+}: React.ComponentProps<"li">) {
+  return (
+    <li
+      data-slot="breadcrumb-separator"
+      role="presentation"
+      aria-hidden="true"
+      className={cn("[&>svg]:size-3.5", className)}
+      {...props}
+    >
+      {children ?? <ChevronRight />}
+    </li>
+  );
+}
+
+/**
+ * Ellipsis indicator for collapsed breadcrumb items
+ *
+ * Shows a horizontal ellipsis icon (MoreHorizontal) to indicate hidden or
+ * collapsed middle items in a long breadcrumb trail. Useful for deep navigation
+ * hierarchies where space is limited. Often used in combination with dropdown
+ * menus to reveal the collapsed items.
+ *
+ * @param className - Additional CSS classes to apply
+ * @param props - Standard HTML span props
+ *
+ * @example
+ * ```tsx
+ * // Simple ellipsis
+ * <BreadcrumbEllipsis />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // With dropdown menu for collapsed items
+ * <BreadcrumbItem>
+ *   <DropdownMenu>
+ *     <DropdownMenuTrigger>
+ *       <BreadcrumbEllipsis />
+ *     </DropdownMenuTrigger>
+ *     <DropdownMenuContent>
+ *       <DropdownMenuItem>Hidden Item 1</DropdownMenuItem>
+ *       <DropdownMenuItem>Hidden Item 2</DropdownMenuItem>
+ *     </DropdownMenuContent>
+ *   </DropdownMenu>
+ * </BreadcrumbItem>
+ * ```
+ *
+ * @accessibility
+ * - Uses `role="presentation"` and `aria-hidden="true"` for decorative content
+ * - Includes screen reader text "More" for context
+ *
+ * @since 1.0.0
+ */
+function BreadcrumbEllipsis({
+  className,
+  ...props
+}: React.ComponentProps<"span">) {
+  return (
+    <span
+      data-slot="breadcrumb-ellipsis"
+      role="presentation"
+      aria-hidden="true"
+      className={cn("flex size-9 items-center justify-center", className)}
+      {...props}
+    >
+      <MoreHorizontal className="size-4" />
+      <span className="sr-only">More</span>
+    </span>
+  );
+}
+
+export {
+  Breadcrumb,
+  BreadcrumbList,
+  BreadcrumbItem,
+  BreadcrumbLink,
+  BreadcrumbPage,
+  BreadcrumbSeparator,
+  BreadcrumbEllipsis,
+};