@neynar/ui 0.1.1 → 0.1.2

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

@@ -10,6 +10,10 @@ import * as React from "react";
  * 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
@@ -56,7 +60,7 @@ import * as React from "react";
  *
  * @example
  * ```tsx
- * // With Next.js Link integration
+ * // With Next.js Link integration using asChild
  * import { Link } from "next/link"
  *
  * <Breadcrumb>
@@ -95,13 +99,15 @@ import * as React from "react";
  * ```
  *
  * @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
@@ -110,26 +116,49 @@ import * as React from "react";
  * @see {@link BreadcrumbEllipsis} - Ellipsis indicator for collapsed items
  * @since 1.0.0
  */
-declare function Breadcrumb({ ...props }: React.ComponentProps<"nav">): import("react/jsx-runtime").JSX.Element;
+declare function Breadcrumb({ ...props }: Omit<React.ComponentProps<"nav">, "aria-label">): import("react/jsx-runtime").JSX.Element;
 /**
  * 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.
+ * 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
  */
 declare function BreadcrumbList({ className, ...props }: React.ComponentProps<"ol">): import("react/jsx-runtime").JSX.Element;
@@ -137,102 +166,223 @@ declare function BreadcrumbList({ className, ...props }: React.ComponentProps<"o
  * 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
  */
 declare function BreadcrumbItem({ className, ...props }: React.ComponentProps<"li">): import("react/jsx-runtime").JSX.Element;
 /**
  * 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
  */
-declare function BreadcrumbLink({ asChild, className, ...props }: React.ComponentProps<"a"> & {
+declare function BreadcrumbLink({ asChild, className, ...props }: {
     asChild?: boolean;
-}): import("react/jsx-runtime").JSX.Element;
+} & React.ComponentProps<"a">): import("react/jsx-runtime").JSX.Element;
 /**
  * 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.
+ *
+ * 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
- * @param props - Standard HTML span props
+ * @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
  */
 declare function BreadcrumbPage({ className, ...props }: React.ComponentProps<"span">): import("react/jsx-runtime").JSX.Element;
 /**
  * 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.
+ *
+ * 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 to display instead of default ChevronRight
- * @param className - Additional CSS classes to apply
- * @param props - Standard HTML list item props
+ * @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
  */
@@ -241,39 +391,71 @@ declare function BreadcrumbSeparator({ children, className, ...props }: React.Co
  * 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
  */
 declare function BreadcrumbEllipsis({ className, ...props }: React.ComponentProps<"span">): import("react/jsx-runtime").JSX.Element;

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

@@ -1 +1 @@
-{"version":3,"file":"breadcrumb.d.ts","sourceRoot":"","sources":["../../../src/components/ui/breadcrumb.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAM/B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8GG;AACH,iBAAS,UAAU,CAAC,EAAE,GAAG,KAAK,EAAE,EAAE,KAAK,CAAC,cAAc,CAAC,KAAK,CAAC,2CAE5D;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,iBAAS,cAAc,CAAC,EAAE,SAAS,EAAE,GAAG,KAAK,EAAE,EAAE,KAAK,CAAC,cAAc,CAAC,IAAI,CAAC,2CAW1E;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,iBAAS,cAAc,CAAC,EAAE,SAAS,EAAE,GAAG,KAAK,EAAE,EAAE,KAAK,CAAC,cAAc,CAAC,IAAI,CAAC,2CAQ1E;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,iBAAS,cAAc,CAAC,EACtB,OAAO,EACP,SAAS,EACT,GAAG,KAAK,EACT,EAAE,KAAK,CAAC,cAAc,CAAC,GAAG,CAAC,GAAG;IAC7B,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB,2CAUA;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,iBAAS,cAAc,CAAC,EAAE,SAAS,EAAE,GAAG,KAAK,EAAE,EAAE,KAAK,CAAC,cAAc,CAAC,MAAM,CAAC,2CAW5E;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,iBAAS,mBAAmB,CAAC,EAC3B,QAAQ,EACR,SAAS,EACT,GAAG,KAAK,EACT,EAAE,KAAK,CAAC,cAAc,CAAC,IAAI,CAAC,2CAY5B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,iBAAS,kBAAkB,CAAC,EAC1B,SAAS,EACT,GAAG,KAAK,EACT,EAAE,KAAK,CAAC,cAAc,CAAC,MAAM,CAAC,2CAa9B;AAED,OAAO,EACL,UAAU,EACV,cAAc,EACd,cAAc,EACd,cAAc,EACd,cAAc,EACd,mBAAmB,EACnB,kBAAkB,GACnB,CAAC"}
+{"version":3,"file":"breadcrumb.d.ts","sourceRoot":"","sources":["../../../src/components/ui/breadcrumb.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AA6G/B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoHG;AACH,iBAAS,UAAU,CAAC,EAClB,GAAG,KAAK,EACT,EAAE,IAAI,CAAC,KAAK,CAAC,cAAc,CAAC,KAAK,CAAC,EAAE,YAAY,CAAC,2CAEjD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AACH,iBAAS,cAAc,CAAC,EAAE,SAAS,EAAE,GAAG,KAAK,EAAE,EAAE,KAAK,CAAC,cAAc,CAAC,IAAI,CAAC,2CAW1E;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AACH,iBAAS,cAAc,CAAC,EAAE,SAAS,EAAE,GAAG,KAAK,EAAE,EAAE,KAAK,CAAC,cAAc,CAAC,IAAI,CAAC,2CAQ1E;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqEG;AACH,iBAAS,cAAc,CAAC,EACtB,OAAO,EACP,SAAS,EACT,GAAG,KAAK,EACT,EAAE;IAAE,OAAO,CAAC,EAAE,OAAO,CAAA;CAAE,GAAG,KAAK,CAAC,cAAc,CAAC,GAAG,CAAC,2CAUnD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiDG;AACH,iBAAS,cAAc,CAAC,EAAE,SAAS,EAAE,GAAG,KAAK,EAAE,EAAE,KAAK,CAAC,cAAc,CAAC,MAAM,CAAC,2CAW5E;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuDG;AACH,iBAAS,mBAAmB,CAAC,EAC3B,QAAQ,EACR,SAAS,EACT,GAAG,KAAK,EACT,EAAE,KAAK,CAAC,cAAc,CAAC,IAAI,CAAC,2CAY5B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsEG;AACH,iBAAS,kBAAkB,CAAC,EAC1B,SAAS,EACT,GAAG,KAAK,EACT,EAAE,KAAK,CAAC,cAAc,CAAC,MAAM,CAAC,2CAa9B;AAED,OAAO,EACL,UAAU,EACV,cAAc,EACd,cAAc,EACd,cAAc,EACd,cAAc,EACd,mBAAmB,EACnB,kBAAkB,GACnB,CAAC"}