@neynar/ui 0.1.1 → 0.1.2

package/src/components/ui/breadcrumb.tsx

@@ -4,6 +4,109 @@ import { ChevronRight, MoreHorizontal } from "lucide-react";
 
 import { cn } from "@/lib/utils";
 
+/**
+ * Props for Breadcrumb component (Documentation only - NOT used in component implementation)
+ * These types are for documentation generation and should not replace inferred types
+ */
+// eslint-disable-next-line unused-imports/no-unused-vars
+type BreadcrumbDocsProps = {
+  /** Additional CSS classes to apply to the navigation element */
+  className?: string;
+  /** Child breadcrumb elements (typically BreadcrumbList) */
+  children?: React.ReactNode;
+} & Omit<React.ComponentProps<"nav">, "aria-label">;
+
+/**
+ * Props for BreadcrumbList component (Documentation only - NOT used in component implementation)
+ * These types are for documentation generation and should not replace inferred types
+ */
+// eslint-disable-next-line unused-imports/no-unused-vars
+type BreadcrumbListDocsProps = {
+  /** Additional CSS classes to apply to the ordered list element */
+  className?: string;
+  /** Child breadcrumb items (BreadcrumbItem elements) */
+  children?: React.ReactNode;
+} & React.ComponentProps<"ol">;
+
+/**
+ * Props for BreadcrumbItem component (Documentation only - NOT used in component implementation)
+ * These types are for documentation generation and should not replace inferred types
+ */
+// eslint-disable-next-line unused-imports/no-unused-vars
+type BreadcrumbItemDocsProps = {
+  /** Additional CSS classes to apply to the list item element */
+  className?: string;
+  /** Content to display within the item (links, pages, separators, etc.) */
+  children?: React.ReactNode;
+} & React.ComponentProps<"li">;
+
+/**
+ * Props for BreadcrumbLink component (Documentation only - NOT used in component implementation)
+ * These types are for documentation generation and should not replace inferred types
+ */
+// eslint-disable-next-line unused-imports/no-unused-vars
+type BreadcrumbLinkDocsProps = {
+  /**
+   * When true, renders the child element directly instead of an anchor tag.
+   * Enables composition with routing library components like Next.js Link.
+   * @default false
+   */
+  asChild?: boolean;
+  /** Additional CSS classes to apply to the link element */
+  className?: string;
+  /** Link destination URL (when asChild is false) */
+  href?: string;
+  /** Link content to display */
+  children?: React.ReactNode;
+  /**
+   * Click handler for the link
+   * @param event - Click event object
+   */
+  onClick?: (event: React.MouseEvent<HTMLAnchorElement>) => void;
+} & React.ComponentProps<"a">;
+
+/**
+ * Props for BreadcrumbPage component (Documentation only - NOT used in component implementation)
+ * These types are for documentation generation and should not replace inferred types
+ */
+// eslint-disable-next-line unused-imports/no-unused-vars
+type BreadcrumbPageDocsProps = {
+  /** Additional CSS classes to apply to the span element */
+  className?: string;
+  /** Current page name to display */
+  children?: React.ReactNode;
+} & React.ComponentProps<"span">;
+
+/**
+ * Props for BreadcrumbSeparator component (Documentation only - NOT used in component implementation)
+ * These types are for documentation generation and should not replace inferred types
+ */
+// eslint-disable-next-line unused-imports/no-unused-vars
+type BreadcrumbSeparatorDocsProps = {
+  /**
+   * Custom separator icon to display instead of the default ChevronRight.
+   * Typically a Lucide icon or similar SVG element.
+   */
+  children?: React.ReactNode;
+  /** Additional CSS classes to apply to the separator element */
+  className?: string;
+} & React.ComponentProps<"li">;
+
+/**
+ * Props for BreadcrumbEllipsis component (Documentation only - NOT used in component implementation)
+ * These types are for documentation generation and should not replace inferred types
+ */
+// eslint-disable-next-line unused-imports/no-unused-vars
+type BreadcrumbEllipsisDocsProps = {
+  /** Additional CSS classes to apply to the ellipsis container */
+  className?: string;
+  /**
+   * Custom content to display instead of the default MoreHorizontal icon.
+   * Rarely needed as the ellipsis has a standard appearance.
+   */
+  children?: React.ReactNode;
+} & React.ComponentProps<"span">;
+
 /**
  * Breadcrumb navigation component that displays hierarchical page location
  *
@@ -15,6 +118,10 @@ import { cn } from "@/lib/utils";
  * support for composition patterns including custom separators, ellipsis for long
  * paths, dropdown menus, and custom link components via the asChild prop.
  *
+ * @param className - Additional CSS classes to apply to the navigation element
+ * @param children - Child breadcrumb elements (typically BreadcrumbList)
+ * @param props - All standard HTML nav element props except aria-label (automatically set to "breadcrumb")
+ *
  * @example
  * ```tsx
  * // Basic breadcrumb navigation
@@ -61,7 +168,7 @@ import { cn } from "@/lib/utils";
  *
  * @example
  * ```tsx
- * // With Next.js Link integration
+ * // With Next.js Link integration using asChild
  * import { Link } from "next/link"
  *
  * <Breadcrumb>
@@ -100,13 +207,15 @@ import { cn } from "@/lib/utils";
  * ```
  *
  * @accessibility
- * - Uses semantic `nav` element with `aria-label="breadcrumb"`
- * - Current page marked with `aria-current="page"`
+ * - Uses semantic `nav` element with `aria-label="breadcrumb"` (automatically applied)
+ * - Current page marked with `aria-current="page"` (via BreadcrumbPage)
  * - Separators marked with `role="presentation"` and `aria-hidden="true"`
- * - Screen reader friendly navigation structure
- * - Supports keyboard navigation through links
+ * - Screen reader friendly navigation structure with proper list semantics
+ * - Supports keyboard navigation through links (Tab navigation)
+ * - Compatible with screen readers and assistive technologies
  *
  * @see {@link https://ui.shadcn.com/docs/components/breadcrumb} for design patterns
+ * @see {@link https://www.w3.org/WAI/ARIA/apg/patterns/breadcrumb/} for ARIA breadcrumb pattern
  * @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
@@ -115,7 +224,9 @@ import { cn } from "@/lib/utils";
  * @see {@link BreadcrumbEllipsis} - Ellipsis indicator for collapsed items
  * @since 1.0.0
  */
-function Breadcrumb({ ...props }: React.ComponentProps<"nav">) {
+function Breadcrumb({
+  ...props
+}: Omit<React.ComponentProps<"nav">, "aria-label">) {
   return <nav aria-label="breadcrumb" data-slot="breadcrumb" {...props} />;
 }
 
@@ -124,20 +235,43 @@ function Breadcrumb({ ...props }: React.ComponentProps<"nav">) {
  *
  * 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.
+ * for proper accessibility and screen reader navigation. Contains flexible
+ * layout with word breaking and responsive gap adjustments.
  *
- * @param className - Additional CSS classes to apply
- * @param props - Standard HTML ordered list props
+ * @param className - Additional CSS classes to apply to the ordered list element
+ * @param children - Child breadcrumb items (BreadcrumbItem elements)
+ * @param props - All standard HTML ordered list element props (id, role, data-*, etc.)
  *
  * @example
  * ```tsx
+ * // Basic list with multiple items
  * <BreadcrumbList>
  *   <BreadcrumbItem>
  *     <BreadcrumbLink href="/">Home</BreadcrumbLink>
  *   </BreadcrumbItem>
+ *   <BreadcrumbSeparator />
+ *   <BreadcrumbItem>
+ *     <BreadcrumbPage>Current</BreadcrumbPage>
+ *   </BreadcrumbItem>
+ * </BreadcrumbList>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // With custom styling
+ * <BreadcrumbList className="gap-4 text-base">
+ *   <BreadcrumbItem>
+ *     <BreadcrumbLink href="/">Home</BreadcrumbLink>
+ *   </BreadcrumbItem>
  * </BreadcrumbList>
  * ```
  *
+ * @accessibility
+ * - Uses semantic `ol` element for proper list structure
+ * - Maintains reading order for screen readers
+ * - Supports list navigation shortcuts in screen readers
+ * - Flexible text wrapping for long breadcrumb trails
+ *
  * @since 1.0.0
  */
 function BreadcrumbList({ className, ...props }: React.ComponentProps<"ol">) {
@@ -157,18 +291,43 @@ function BreadcrumbList({ className, ...props }: React.ComponentProps<"ol">) {
  * Individual breadcrumb list item container
  *
  * Wraps breadcrumb content (links, pages, separators) in a semantic list item.
- * Provides consistent alignment and spacing for breadcrumb elements.
+ * Provides consistent alignment and spacing for breadcrumb elements with inline
+ * flex layout for proper icon and text alignment.
  *
- * @param className - Additional CSS classes to apply
- * @param props - Standard HTML list item props
+ * @param className - Additional CSS classes to apply to the list item element
+ * @param children - Content to display within the item (links, pages, separators, ellipsis)
+ * @param props - All standard HTML list item element props (id, role, data-*, etc.)
  *
  * @example
  * ```tsx
+ * // With link
  * <BreadcrumbItem>
  *   <BreadcrumbLink href="/products">Products</BreadcrumbLink>
  * </BreadcrumbItem>
  * ```
  *
+ * @example
+ * ```tsx
+ * // With current page
+ * <BreadcrumbItem>
+ *   <BreadcrumbPage>Current Page</BreadcrumbPage>
+ * </BreadcrumbItem>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // With separator
+ * <BreadcrumbItem>
+ *   <BreadcrumbSeparator />
+ * </BreadcrumbItem>
+ * ```
+ *
+ * @accessibility
+ * - Uses semantic `li` element for proper list structure
+ * - Maintains proper DOM hierarchy within breadcrumb list
+ * - Supports assistive technology list navigation
+ * - Inline flex layout ensures proper alignment of icons and text
+ *
  * @since 1.0.0
  */
 function BreadcrumbItem({ className, ...props }: React.ComponentProps<"li">) {
@@ -184,37 +343,78 @@ function BreadcrumbItem({ className, ...props }: React.ComponentProps<"li">) {
 /**
  * Navigable link within breadcrumb trail
  *
- * Represents a clickable parent page in the breadcrumb hierarchy with hover
+ * Represents a clickable parent page in the breadcrumb hierarchy with smooth hover
  * effects and transition animations. Supports composition via the `asChild` prop
- * for integration with routing libraries like Next.js Link or React Router.
+ * for seamless integration with routing libraries like Next.js Link, React Router,
+ * or Reach Router using the Radix UI Slot primitive for prop merging.
+ *
+ * Built on Radix UI Slot primitive which enables the asChild pattern - when asChild
+ * is true, the component merges its props with the immediate child element instead
+ * of rendering its own anchor tag. This allows for flexible composition while
+ * maintaining consistent styling and behavior.
  *
- * @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
+ * @param asChild - When true, merges props with child element instead of rendering anchor. Enables composition with routing components @default false
+ * @param className - Additional CSS classes to apply to the link element
+ * @param href - Link destination URL (when asChild is false)
+ * @param children - Link content to display (text, icons, etc.)
+ * @param onClick - Click handler for the link interaction
+ * @param props - All standard HTML anchor element props (target, rel, download, etc.)
  *
  * @example
  * ```tsx
- * // Standard link
+ * // Standard anchor link
  * <BreadcrumbLink href="/products">Products</BreadcrumbLink>
  * ```
  *
  * @example
  * ```tsx
- * // With Next.js Link
+ * // With Next.js Link using asChild
+ * import { Link } from "next/link"
+ *
  * <BreadcrumbLink asChild>
  *   <Link href="/products">Products</Link>
  * </BreadcrumbLink>
  * ```
  *
+ * @example
+ * ```tsx
+ * // With React Router Link
+ * import { Link } from "react-router-dom"
+ *
+ * <BreadcrumbLink asChild>
+ *   <Link to="/products">Products</Link>
+ * </BreadcrumbLink>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // With click handler
+ * <BreadcrumbLink
+ *   href="/products"
+ *   onClick={(e) => {
+ *     e.preventDefault();
+ *     navigate('/products');
+ *   }}
+ * >
+ *   Products
+ * </BreadcrumbLink>
+ * ```
+ *
+ * @accessibility
+ * - Uses semantic anchor element with proper link role
+ * - Supports keyboard navigation (Enter key activation)
+ * - Compatible with screen reader link navigation
+ * - Maintains focus management when used with asChild
+ * - Preserves all accessibility attributes when composed
+ *
+ * @see {@link https://www.radix-ui.com/primitives/docs/utilities/slot} for asChild pattern details
  * @since 1.0.0
  */
 function BreadcrumbLink({
   asChild,
   className,
   ...props
-}: React.ComponentProps<"a"> & {
-  asChild?: boolean;
-}) {
+}: { asChild?: boolean } & React.ComponentProps<"a">) {
   const Comp = asChild ? Slot : "a";
 
   return (
@@ -230,21 +430,50 @@ function BreadcrumbLink({
  * 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.
+ * Styled with prominent text color and marked with comprehensive accessibility
+ * attributes including `aria-current="page"` for precise screen reader identification
+ * of the user's current location within the site hierarchy.
  *
- * @param className - Additional CSS classes to apply
- * @param props - Standard HTML span props
+ * This component uses specific ARIA attributes to indicate it represents a link-like
+ * element that is disabled, providing semantic meaning while maintaining the visual
+ * breadcrumb structure. The `aria-current="page"` attribute is the standard way to
+ * identify the current page in navigation components.
+ *
+ * @param className - Additional CSS classes to apply to the span element
+ * @param children - Current page name or content to display
+ * @param props - All standard HTML span element props (id, data-*, style, etc.)
  *
  * @example
  * ```tsx
+ * // Simple page name
  * <BreadcrumbPage>Current Page Name</BreadcrumbPage>
  * ```
  *
+ * @example
+ * ```tsx
+ * // With icon and text
+ * <BreadcrumbPage>
+ *   <FileIcon className="mr-1" />
+ *   Document.pdf
+ * </BreadcrumbPage>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // With custom styling
+ * <BreadcrumbPage className="font-semibold text-primary">
+ *   Important Page
+ * </BreadcrumbPage>
+ * ```
+ *
  * @accessibility
- * - Uses `role="link"` with `aria-disabled="true"` for semantic meaning
- * - Marked with `aria-current="page"` to indicate current location
+ * - Uses `role="link"` with `aria-disabled="true"` to indicate link-like but non-interactive element
+ * - Marked with `aria-current="page"` to indicate current location (WCAG 2.1 standard)
+ * - Provides semantic meaning for assistive technologies
+ * - Screen readers will announce this as the current page in the breadcrumb trail
+ * - Non-focusable as it represents the current location, not a navigation target
  *
+ * @see {@link https://www.w3.org/WAI/WCAG21/Techniques/aria/ARIA02} for aria-current usage
  * @since 1.0.0
  */
 function BreadcrumbPage({ className, ...props }: React.ComponentProps<"span">) {
@@ -263,32 +492,56 @@ function BreadcrumbPage({ className, ...props }: React.ComponentProps<"span">) {
 /**
  * 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.
+ * Displays a separator icon (default: ChevronRight) between breadcrumb items to
+ * provide visual hierarchy and direction in the breadcrumb trail. Supports complete
+ * customization with any icon or content. Properly hidden from assistive technologies
+ * with accessibility attributes for clean screen reader 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
+ * The component uses CSS sizing constraints to ensure consistent icon sizing across
+ * different separator types and maintains visual alignment within the breadcrumb flow.
+ *
+ * @param children - Custom separator icon or content to display instead of default ChevronRight. Typically Lucide icons like Slash, ArrowRight, etc.
+ * @param className - Additional CSS classes to apply to the list item container
+ * @param props - All standard HTML list item element props (id, data-*, style, etc.)
  *
  * @example
  * ```tsx
- * // Default separator
+ * // Default ChevronRight separator
  * <BreadcrumbSeparator />
  * ```
  *
  * @example
  * ```tsx
- * // Custom separator
+ * // Custom Slash separator
  * import { Slash } from "lucide-react"
  * <BreadcrumbSeparator>
  *   <Slash />
  * </BreadcrumbSeparator>
  * ```
  *
+ * @example
+ * ```tsx
+ * // Arrow right separator
+ * import { ArrowRight } from "lucide-react"
+ * <BreadcrumbSeparator>
+ *   <ArrowRight />
+ * </BreadcrumbSeparator>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Text separator
+ * <BreadcrumbSeparator>
+ *   <span className="text-muted-foreground">/</span>
+ * </BreadcrumbSeparator>
+ * ```
+ *
  * @accessibility
- * - Uses `role="presentation"` to indicate decorative content
+ * - Uses `role="presentation"` to indicate purely decorative content
  * - Hidden from screen readers with `aria-hidden="true"`
+ * - Does not interfere with keyboard navigation flow
+ * - Screen readers skip over separator and focus on actual navigation links
+ * - Maintains visual structure without adding semantic noise
  *
  * @since 1.0.0
  */
@@ -314,39 +567,71 @@ function BreadcrumbSeparator({
  * 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.
+ * collapsed middle items in a long breadcrumb trail. Essential for deep navigation
+ * hierarchies where space is limited or mobile responsive design. Commonly used
+ * in combination with dropdown menus, popovers, or expandable sections to reveal
+ * the collapsed breadcrumb items on user interaction.
+ *
+ * The component provides a consistent 36px (9 × 4px) clickable area for better
+ * touch interaction when used as a trigger for dropdown menus. Includes hidden
+ * screen reader text to provide context about the collapsed content.
  *
- * @param className - Additional CSS classes to apply
- * @param props - Standard HTML span props
+ * @param className - Additional CSS classes to apply to the ellipsis container
+ * @param children - Custom content to display instead of the default MoreHorizontal icon (rarely needed)
+ * @param props - All standard HTML span element props (id, data-*, style, onClick for dropdown triggers, etc.)
  *
  * @example
  * ```tsx
- * // Simple ellipsis
+ * // Simple static ellipsis
  * <BreadcrumbEllipsis />
  * ```
  *
  * @example
  * ```tsx
- * // With dropdown menu for collapsed items
+ * // Interactive ellipsis with dropdown menu
  * <BreadcrumbItem>
  *   <DropdownMenu>
- *     <DropdownMenuTrigger>
- *       <BreadcrumbEllipsis />
+ *     <DropdownMenuTrigger asChild>
+ *       <BreadcrumbEllipsis className="hover:bg-muted cursor-pointer" />
  *     </DropdownMenuTrigger>
  *     <DropdownMenuContent>
- *       <DropdownMenuItem>Hidden Item 1</DropdownMenuItem>
- *       <DropdownMenuItem>Hidden Item 2</DropdownMenuItem>
+ *       <DropdownMenuItem>
+ *         <BreadcrumbLink href="/level1">Level 1</BreadcrumbLink>
+ *       </DropdownMenuItem>
+ *       <DropdownMenuItem>
+ *         <BreadcrumbLink href="/level1/level2">Level 2</BreadcrumbLink>
+ *       </DropdownMenuItem>
  *     </DropdownMenuContent>
  *   </DropdownMenu>
  * </BreadcrumbItem>
  * ```
  *
+ * @example
+ * ```tsx
+ * // With popover for collapsed items
+ * <BreadcrumbItem>
+ *   <Popover>
+ *     <PopoverTrigger asChild>
+ *       <BreadcrumbEllipsis className="hover:bg-accent" />
+ *     </PopoverTrigger>
+ *     <PopoverContent>
+ *       <div className="space-y-2">
+ *         <BreadcrumbLink href="/hidden1">Hidden Item 1</BreadcrumbLink>
+ *         <BreadcrumbLink href="/hidden2">Hidden Item 2</BreadcrumbLink>
+ *       </div>
+ *     </PopoverContent>
+ *   </Popover>
+ * </BreadcrumbItem>
+ * ```
+ *
  * @accessibility
- * - Uses `role="presentation"` and `aria-hidden="true"` for decorative content
- * - Includes screen reader text "More" for context
+ * - Uses `role="presentation"` and `aria-hidden="true"` for the visual ellipsis
+ * - Includes hidden screen reader text "More" to provide context
+ * - When used as dropdown trigger, ensure proper ARIA attributes on parent trigger
+ * - Maintains 36px minimum touch target size for mobile accessibility
+ * - Screen readers will announce "More" when focused (if used as interactive element)
  *
+ * @see {@link https://www.w3.org/WAI/WCAG21/Understanding/target-size.html} for touch target guidelines
  * @since 1.0.0
  */
 function BreadcrumbEllipsis({