Hover card

"use client";

import * as React from "react";
import { Popover, PopoverAnchor, PopoverContent } from "@/components/ui/popover";
import { cn } from "@/lib/utils";

type HoverCardProps = {
  /** The link or button that triggers the card. Wrapped in an inline span that listens for hover and focus. */
  children: React.ReactElement;
  /** The preview. Supplementary only: the same information must exist behind the link. */
  card: React.ReactNode;
  /** Accessible name of the card. */
  label: string;
  side?: "top" | "right" | "bottom" | "left";
  /** Milliseconds before hover opens the card. */
  openDelay?: number;
  /** Milliseconds before leaving closes it, so the pointer can cross the gap. */
  closeDelay?: number;
  className?: string;
};

/**
 * A rich preview that opens on hover and on keyboard focus. It is built on the popover primitive
 * and never takes focus, so the trigger keeps working as an ordinary link. Touch does not open it.
 */
export function HoverCard({
  children,
  card,
  label,
  side = "bottom",
  openDelay = 300,
  closeDelay = 150,
  className,
}: HoverCardProps) {
  const [open, setOpen] = React.useState(false);
  const timer = React.useRef<ReturnType<typeof setTimeout> | undefined>(undefined);

  const schedule = (next: boolean, ms: number) => {
    clearTimeout(timer.current);
    timer.current = setTimeout(() => setOpen(next), ms);
  };
  React.useEffect(() => () => clearTimeout(timer.current), []);

  return (
    <Popover open={open} onOpenChange={setOpen}>
      <PopoverAnchor asChild>
        <span
          className="inline"
          onPointerEnter={(e) => e.pointerType === "mouse" && schedule(true, openDelay)}
          onPointerLeave={(e) => e.pointerType === "mouse" && schedule(false, closeDelay)}
          onFocus={() => schedule(true, 0)}
          onBlur={() => schedule(false, 0)}
          onKeyDown={(e) => e.key === "Escape" && schedule(false, 0)}
        >
          {children}
        </span>
      </PopoverAnchor>
      <PopoverContent
        side={side}
        sideOffset={8}
        aria-label={label}
        onOpenAutoFocus={(e) => e.preventDefault()}
        onCloseAutoFocus={(e) => e.preventDefault()}
        onPointerEnter={() => clearTimeout(timer.current)}
        onPointerLeave={() => schedule(false, closeDelay)}
        className={cn("w-64", className)}
      >
        {card}
      </PopoverContent>
    </Popover>
  );
}