@neynar/ui 0.1.1 → 0.1.2

package/src/components/ui/hover-card.tsx

@@ -4,13 +4,86 @@ import * as HoverCardPrimitive from "@radix-ui/react-hover-card";
 import { cn } from "@/lib/utils";
 
 /**
- * HoverCard component for previewing content available behind a link
+ * Props for HoverCard component (Documentation only - NOT used in component implementation)
+ * These types are for documentation generation and should not replace Radix inferred types
+ */
+// eslint-disable-next-line unused-imports/no-unused-vars
+type HoverCardDocsProps = {
+  /** Whether the hover card is initially open in uncontrolled mode */
+  defaultOpen?: boolean;
+  /** Controlled open state of the hover card */
+  open?: boolean;
+  /** Callback fired when the open state changes */
+  onValueChange?: (open: boolean) => void;
+  /** Delay in milliseconds before the hover card opens @default 700 */
+  openDelay?: number;
+  /** Delay in milliseconds before the hover card closes @default 300 */
+  closeDelay?: number;
+  /** Child components (HoverCardTrigger and HoverCardContent) */
+  children?: React.ReactNode;
+} & React.ComponentProps<typeof HoverCardPrimitive.Root>;
+
+/**
+ * Props for HoverCardTrigger component (Documentation only - NOT used in component implementation)
+ * These types are for documentation generation and should not replace Radix inferred types
+ */
+// eslint-disable-next-line unused-imports/no-unused-vars
+type HoverCardTriggerDocsProps = {
+  /** Render the trigger as its child element, merging props */
+  asChild?: boolean;
+  /** Child element that will trigger the hover card on hover */
+  children?: React.ReactNode;
+  /** Additional CSS classes for custom styling */
+  className?: string;
+} & React.ComponentProps<typeof HoverCardPrimitive.Trigger>;
+
+/**
+ * Props for HoverCardContent component (Documentation only - NOT used in component implementation)
+ * These types are for documentation generation and should not replace Radix inferred types
+ */
+// eslint-disable-next-line unused-imports/no-unused-vars
+type HoverCardContentDocsProps = {
+  /** Side of the trigger to position content @default "bottom" */
+  side?: "top" | "right" | "bottom" | "left";
+  /** Distance in pixels from the trigger @default 4 */
+  sideOffset?: number;
+  /** Alignment of content relative to trigger @default "center" */
+  align?: "start" | "center" | "end";
+  /** Offset in pixels along the alignment axis */
+  alignOffset?: number;
+  /** Whether to prevent collision with viewport boundaries @default true */
+  avoidCollisions?: boolean;
+  /** Boundary element for collision detection @default viewport */
+  collisionBoundary?: Element | null | Array<Element | null>;
+  /** Padding from the collision boundary @default 10 */
+  collisionPadding?:
+    | number
+    | Partial<Record<"top" | "right" | "bottom" | "left", number>>;
+  /** Whether the content should stick to the viewport when overflowing @default "partial" */
+  sticky?: "partial" | "always";
+  /** Whether to hide the content when trigger becomes fully occluded @default false */
+  hideWhenDetached?: boolean;
+  /** Force content to stay mounted even when closed (for animations) */
+  forceMount?: true;
+  /** Render content as its child element */
+  asChild?: boolean;
+  /** Additional CSS classes for custom styling */
+  className?: string;
+  /** Content to display in the hover card */
+  children?: React.ReactNode;
+} & React.ComponentProps<typeof HoverCardPrimitive.Content>;
+
+/**
+ * HoverCard - Preview content that appears on hover for rich contextual information
  *
- * For sighted users to preview content available behind a link. Displays rich content
- * when users hover over a trigger element. Ideal for showing previews, user profiles,
- * repository information, or contextual details without requiring navigation.
+ * A floating card component that reveals rich content when users hover over a trigger element.
+ * Designed specifically for sighted users to preview content available behind links without
+ * requiring navigation. Built on Radix UI primitives with smooth animations and intelligent
+ * positioning to avoid viewport boundaries.
  *
- * Built on Radix UI Hover Card primitive with custom styling and animations.
+ * Perfect for user profiles, repository information, link previews, tooltips with complex
+ * content, and any contextual details that enhance the user experience without interrupting
+ * their current workflow.
  *
  * @example
  * ```tsx
@@ -54,70 +127,286 @@ import { cn } from "@/lib/utils";
  *
  * @example
  * ```tsx
- * // Interactive content
+ * // Interactive hover card with buttons
  * <HoverCard>
  *   <HoverCardTrigger asChild>
- *     <Button>Settings</Button>
+ *     <Button variant="ghost">Quick Actions</Button>
  *   </HoverCardTrigger>
  *   <HoverCardContent>
  *     <div className="space-y-2">
- *       <h4 className="font-semibold">Quick Actions</h4>
- *       <Button size="sm">Manage Team</Button>
- *       <Button size="sm">View Reports</Button>
+ *       <h4 className="font-semibold">Available Actions</h4>
+ *       <div className="flex flex-col gap-1">
+ *         <Button size="sm" variant="ghost">Edit Profile</Button>
+ *         <Button size="sm" variant="ghost">View Analytics</Button>
+ *         <Button size="sm" variant="ghost">Manage Settings</Button>
+ *       </div>
+ *     </div>
+ *   </HoverCardContent>
+ * </HoverCard>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Link preview with rich content
+ * <HoverCard openDelay={300}>
+ *   <HoverCardTrigger asChild>
+ *     <a href="/article/123" className="text-blue-600 hover:underline">
+ *       Advanced React Patterns
+ *     </a>
+ *   </HoverCardTrigger>
+ *   <HoverCardContent className="w-96">
+ *     <div className="space-y-3">
+ *       <img src="/article-thumbnail.jpg" className="rounded w-full h-32 object-cover" />
+ *       <div>
+ *         <h4 className="font-semibold">Advanced React Patterns</h4>
+ *         <p className="text-sm text-muted-foreground">
+ *           Learn modern React patterns including render props, compound components,
+ *           and advanced hook compositions for scalable applications.
+ *         </p>
+ *         <div className="flex items-center gap-2 mt-2 text-xs text-muted-foreground">
+ *           <span>12 min read</span>
+ *           <span>•</span>
+ *           <span>Published Mar 15, 2024</span>
+ *         </div>
+ *       </div>
  *     </div>
  *   </HoverCardContent>
  * </HoverCard>
  * ```
  *
  * @accessibility
- * **Important**: Hover cards are intended for sighted users only. The content will be
- * inaccessible to keyboard users. Consider providing alternative access methods.
+ * **Important Limitations**: Hover cards are intended for sighted users only and present
+ * significant accessibility challenges. The content is inaccessible to keyboard-only users
+ * and screen reader users who cannot hover. Consider these alternatives:
  *
- * - Opens on hover with configurable `openDelay`
- * - Stays open when hovering over content
- * - Closes with configurable `closeDelay`
- * - Auto-positions to avoid viewport overflow
- * - Supports focus-based interactions for some accessibility
+ * - Provide keyboard-accessible alternatives (buttons, modals, expanded sections)
+ * - Ensure all essential information is available through other means
+ * - Use hover cards only for supplementary, non-critical content
+ * - Consider implementing focus-based triggers for keyboard users
  *
- * @see {@link https://ui.shadcn.com/docs/components/hover-card} shadcn/ui documentation
+ * **Current Accessibility Features**:
+ * - Opens on mouse hover with configurable delay
+ * - Stays open when hovering over the content area
+ * - Closes automatically when mouse leaves with configurable delay
+ * - Intelligent positioning to avoid viewport overflow
+ * - Smooth animations that respect prefers-reduced-motion
+ * - Proper focus management within interactive content
+ *
+ * @see {@link HoverCardTrigger} Element that triggers the hover card on hover
+ * @see {@link HoverCardContent} Container for the hover card content and positioning
+ * @see {@link https://ui.shadcn.com/docs/components/hover-card} shadcn/ui Hover Card Documentation
+ * @see {@link https://www.radix-ui.com/primitives/docs/components/hover-card} Radix UI Hover Card Primitive
+ * @see {@link https://www.w3.org/WAI/ARIA/apg/patterns/tooltip/} WAI-ARIA Tooltip Pattern (for accessibility considerations)
  * @since 1.0.0
- * @see {@link https://www.radix-ui.com/primitives/docs/components/hover-card} Radix UI Hover Card
  */
 /**
- * Root container for the hover card component
+ * HoverCard - Root container that manages hover card state and timing
+ *
+ * The main wrapper component that provides context to all hover card subcomponents.
+ * Controls the opening and closing behavior, timing delays, and overall state management.
+ * Must contain HoverCardTrigger and HoverCardContent as children.
  *
- * @param openDelay - Delay in milliseconds before the hover card opens (default: 700)
- * @param closeDelay - Delay in milliseconds before the hover card closes (default: 300)
- * @param open - Controlled open state
- * @param onOpenChange - Callback when open state changes
+ * @example
+ * ```tsx
+ * // Basic usage with default timing
+ * <HoverCard>
+ *   <HoverCardTrigger>Hover me</HoverCardTrigger>
+ *   <HoverCardContent>Content appears here</HoverCardContent>
+ * </HoverCard>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Custom timing and controlled state
+ * <HoverCard
+ *   openDelay={200}
+ *   closeDelay={500}
+ *   open={isOpen}
+ *   onValueChange={setIsOpen}
+ * >
+ *   <HoverCardTrigger>Controlled hover card</HoverCardTrigger>
+ *   <HoverCardContent>This hover card is controlled externally</HoverCardContent>
+ * </HoverCard>
+ * ```
+ *
+ * @see {@link HoverCardTrigger} The element that triggers the hover behavior
+ * @see {@link HoverCardContent} The content container with positioning logic
  */
-function HoverCard({
-  ...props
-}: React.ComponentProps<typeof HoverCardPrimitive.Root>) {
+function HoverCard(
+  props: React.ComponentProps<typeof HoverCardPrimitive.Root>,
+) {
   return <HoverCardPrimitive.Root data-slot="hover-card" {...props} />;
 }
 
 /**
- * Trigger element that opens the hover card on hover
+ * HoverCardTrigger - Interactive element that activates the hover card on mouse hover
+ *
+ * The trigger component that users hover over to reveal the hover card content.
+ * Can wrap any element or render as its child using the asChild prop. Automatically
+ * manages hover detection and integrates with the parent HoverCard's timing configuration.
+ *
+ * When using asChild, the trigger merges its props with the immediate child element,
+ * allowing for seamless integration with buttons, links, or any other interactive elements.
+ *
+ * @example
+ * ```tsx
+ * // Basic trigger with text
+ * <HoverCardTrigger>
+ *   <span className="text-blue-600 cursor-pointer">Hover for details</span>
+ * </HoverCardTrigger>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Using asChild with a button
+ * <HoverCardTrigger asChild>
+ *   <Button variant="outline">User Profile</Button>
+ * </HoverCardTrigger>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // With a link element
+ * <HoverCardTrigger asChild>
+ *   <a href="/profile/john" className="font-medium hover:underline">
+ *     @johndoe
+ *   </a>
+ * </HoverCardTrigger>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Complex trigger with icon
+ * <HoverCardTrigger className="inline-flex items-center gap-2">
+ *   <UserIcon className="h-4 w-4" />
+ *   <span>View Profile</span>
+ * </HoverCardTrigger>
+ * ```
  *
- * @param asChild - When true, merges props with immediate child element
+ * @accessibility
+ * - Responds to mouse hover events to show/hide content
+ * - Maintains keyboard focus when asChild is used with focusable elements
+ * - Does not provide keyboard-only access to hover card content
+ * - Consider providing alternative access methods for keyboard users
+ *
+ * @see {@link HoverCardContent} The content that appears when this trigger is hovered
  */
-function HoverCardTrigger({
-  ...props
-}: React.ComponentProps<typeof HoverCardPrimitive.Trigger>) {
+function HoverCardTrigger(
+  props: React.ComponentProps<typeof HoverCardPrimitive.Trigger>,
+) {
   return (
     <HoverCardPrimitive.Trigger data-slot="hover-card-trigger" {...props} />
   );
 }
 
 /**
- * Content container with built-in styling and animations
+ * HoverCardContent - Floating content container with intelligent positioning and animations
+ *
+ * The content area that appears when the trigger is hovered. Features built-in animations,
+ * intelligent positioning to avoid viewport boundaries, and customizable alignment options.
+ * Automatically portaled to prevent z-index and overflow issues, with smooth fade and scale
+ * transitions that respect user motion preferences.
+ *
+ * The content supports rich layouts including text, images, buttons, and complex components.
+ * Positioning is automatically calculated based on available space, with collision detection
+ * to ensure the content remains visible within the viewport.
+ *
+ * @example
+ * ```tsx
+ * // Simple text content
+ * <HoverCardContent>
+ *   <p>This is a simple hover card with text content.</p>
+ * </HoverCardContent>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Positioned above the trigger with custom alignment
+ * <HoverCardContent side="top" align="start" sideOffset={8}>
+ *   <div className="text-sm">
+ *     Content appears above the trigger, aligned to the start edge
+ *   </div>
+ * </HoverCardContent>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Rich content with custom width and complex layout
+ * <HoverCardContent className="w-80">
+ *   <div className="space-y-3">
+ *     <div className="flex items-center gap-3">
+ *       <Avatar className="h-12 w-12">
+ *         <AvatarImage src="/avatar.jpg" />
+ *         <AvatarFallback>JD</AvatarFallback>
+ *       </Avatar>
+ *       <div>
+ *         <h4 className="font-semibold">John Doe</h4>
+ *         <p className="text-sm text-muted-foreground">Software Engineer</p>
+ *       </div>
+ *     </div>
+ *     <Separator />
+ *     <div className="grid grid-cols-2 gap-4 text-sm">
+ *       <div>
+ *         <p className="font-medium">Repositories</p>
+ *         <p className="text-muted-foreground">42</p>
+ *       </div>
+ *       <div>
+ *         <p className="font-medium">Followers</p>
+ *         <p className="text-muted-foreground">1.2k</p>
+ *       </div>
+ *     </div>
+ *   </div>
+ * </HoverCardContent>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Interactive content with buttons
+ * <HoverCardContent>
+ *   <div className="space-y-3">
+ *     <h4 className="font-semibold">Quick Actions</h4>
+ *     <div className="flex flex-col gap-2">
+ *       <Button size="sm" variant="ghost" className="justify-start">
+ *         <EditIcon className="mr-2 h-4 w-4" />
+ *         Edit Details
+ *       </Button>
+ *       <Button size="sm" variant="ghost" className="justify-start">
+ *         <ShareIcon className="mr-2 h-4 w-4" />
+ *         Share Profile
+ *       </Button>
+ *       <Button size="sm" variant="ghost" className="justify-start">
+ *         <SettingsIcon className="mr-2 h-4 w-4" />
+ *         Settings
+ *       </Button>
+ *     </div>
+ *   </div>
+ * </HoverCardContent>
+ * ```
+ *
+ * @accessibility
+ * - Content is rendered in a portal to avoid z-index conflicts
+ * - Smooth animations that respect prefers-reduced-motion settings
+ * - Interactive content within the hover card remains functional
+ * - Focus management for interactive elements when content is open
+ * - Proper contrast ratios with popover color scheme
+ * - Content stays open when hovering over it, allowing interaction
+ *
+ * @animation
+ * - Fade in/out animations using data-[state] attributes
+ * - Scale animations (zoom-in-95/zoom-out-95) for smooth appearance
+ * - Directional slide animations based on positioning side
+ * - Origin-based scaling using CSS custom properties from Radix UI
+ * - Animations automatically disabled when prefers-reduced-motion is set
+ *
+ * @positioning
+ * - Auto-positioning with collision detection to stay within viewport
+ * - Supports all four sides (top, right, bottom, left) relative to trigger
+ * - Three alignment options (start, center, end) for each side
+ * - Configurable offsets for fine-tuned positioning
+ * - Boundary detection with customizable collision boundaries
+ * - Sticky positioning when content would overflow viewport
  *
- * @param side - Side of the trigger to position content ("top" | "right" | "bottom" | "left")
- * @param align - Alignment relative to trigger ("start" | "center" | "end")
- * @param sideOffset - Distance in pixels from the trigger (default: 4)
- * @param alignOffset - Offset in pixels from the alignment axis
- * @param className - Additional CSS classes
+ * @see {@link HoverCardTrigger} The element that activates this content
  */
 function HoverCardContent({
   className,
@@ -132,7 +421,7 @@ function HoverCardContent({
         align={align}
         sideOffset={sideOffset}
         className={cn(
-          "bg-popover text-popover-foreground data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0 data-[state=closed]:zoom-out-95 data-[state=open]:zoom-in-95 data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2 z-50 w-64 origin-(--radix-hover-card-content-transform-origin) rounded-md border p-4 shadow-md outline-hidden",
+          "z-50 w-64 rounded-md border bg-popover p-4 text-popover-foreground shadow-md outline-none data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0 data-[state=closed]:zoom-out-95 data-[state=open]:zoom-in-95 data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2",
           className,
         )}
         {...props}