Hover card

"use client";

import {
  createContext,
  useContext,
  useEffect,
  useId,
  useRef,
  useState,
  type ComponentProps,
  type FocusEvent,
  type PointerEvent,
  type ReactNode,
  type RefObject,
  type ToggleEvent,
} from "react";
import "./hover-card.css";

const OPEN_DELAY = 500;
const CLOSE_DELAY = 200;

/* Must match the @supports condition in hover-card.css exactly. */
const ANCHOR_SUPPORT = "(anchor-name: --a) and (position-area: bottom) and (position-try-fallbacks: flip-block)";

type Card = {
  id: string;
  anchorName: string;
  trigger: RefObject<HTMLSpanElement | null>;
  open: (delay: number) => void;
  close: (delay: number) => void;
  cancel: () => void;
};

const CardContext = createContext<Card | null>(null);

function useCard(name: string) {
  const card = useContext(CardContext);
  if (!card) throw new Error(`${name} must be inside a HoverCard.`);
  return card;
}

/** Fallback for engines without anchor positioning: below the trigger, flipped above when there is no room. */
function place(anchor: Element, card: HTMLElement) {
  const box = anchor.getBoundingClientRect();
  const viewWidth = document.documentElement.clientWidth;
  const viewHeight = document.documentElement.clientHeight;
  const gap = parseFloat(getComputedStyle(card).marginTop) || 0;
  const height = card.offsetHeight + gap;
  const below = box.bottom + height <= viewHeight || box.top - height < 0;
  const edge = 8;
  const style = card.style;
  style.left = `${Math.max(edge, Math.min(box.left, viewWidth - card.offsetWidth - edge))}px`;
  style.right = "auto";
  style.top = below ? `${box.bottom}px` : "auto";
  style.bottom = below ? "auto" : `${viewHeight - box.top}px`;
}

export type HoverCardProps = ComponentProps<"span"> & {
  /** Required. Given to the card, so other markup can refer to it. */
  id: string;
};

/**
 * Holds a trigger and its card. It renders an inline span, so it can sit in a sentence.
 */
export function HoverCard({ id, className, onBlur, children, ...rest }: HoverCardProps) {
  const anchorName = `--eq-hover-card-${useId().replace(/[^\w-]/g, "")}`;
  const trigger = useRef<HTMLSpanElement>(null);
  const timer = useRef<number | undefined>(undefined);

  useEffect(() => () => window.clearTimeout(timer.current), []);

  function show() {
    const card = document.getElementById(id);
    const anchor = trigger.current?.firstElementChild ?? trigger.current;
    if (!card || !anchor || card.matches(":popover-open")) return;
    const fallback = !CSS.supports(ANCHOR_SUPPORT);
    if (fallback) place(anchor, card);
    card.showPopover();
    if (fallback) place(anchor, card);
  }

  function hide() {
    const card = document.getElementById(id);
    if (card?.matches(":popover-open")) card.hidePopover();
  }

  const value: Card = {
    id,
    anchorName,
    trigger,
    open(delay) {
      window.clearTimeout(timer.current);
      if (delay === 0) show();
      else timer.current = window.setTimeout(show, delay);
    },
    close(delay) {
      window.clearTimeout(timer.current);
      if (delay === 0) hide();
      else timer.current = window.setTimeout(hide, delay);
    },
    cancel() {
      window.clearTimeout(timer.current);
    },
  };

  // Focus that leaves both the trigger and the card closes it. Moving into the card does not.
  function handleBlur(event: FocusEvent<HTMLSpanElement>) {
    onBlur?.(event);
    if (!event.currentTarget.contains(event.relatedTarget)) value.close(0);
  }

  return (
    <CardContext.Provider value={value}>
      <span {...rest} className={["eq-hover-card", className].filter(Boolean).join(" ")} onBlur={handleBlur}>
        {children}
      </span>
    </CardContext.Provider>
  );
}

export type HoverCardTriggerProps = Omit<ComponentProps<"span">, "children"> & {
  /** One link or button. It should lead somewhere useful on its own, since touch users never see the card. */
  children: ReactNode;
};

export function HoverCardTrigger({
  className,
  style,
  onPointerEnter,
  onPointerLeave,
  onFocus,
  children,
  ...rest
}: HoverCardTriggerProps) {
  const card = useCard("HoverCardTrigger");

  return (
    <span
      ref={card.trigger}
      {...rest}
      className={["eq-hover-card-trigger", className].filter(Boolean).join(" ")}
      style={{ anchorName: card.anchorName, ...style }}
      onPointerEnter={(event: PointerEvent<HTMLSpanElement>) => {
        onPointerEnter?.(event);
        if (event.pointerType === "mouse") card.open(OPEN_DELAY);
      }}
      onPointerLeave={(event: PointerEvent<HTMLSpanElement>) => {
        onPointerLeave?.(event);
        if (event.pointerType === "mouse") card.close(CLOSE_DELAY);
      }}
      onFocus={(event: FocusEvent<HTMLSpanElement>) => {
        onFocus?.(event);
        // Keyboard focus opens it at once; a click already had its hover.
        if (event.target.matches(":focus-visible")) card.open(0);
      }}
    >
      {children}
    </span>
  );
}

export type HoverCardContentProps = ComponentProps<"span">;

/**
 * The card. A span with display: block, so it is valid inside a paragraph: fill it with
 * phrasing content (spans, links, strong, img).
 */
export function HoverCardContent({
  className,
  style,
  onToggle,
  onPointerEnter,
  onPointerLeave,
  children,
  ...rest
}: HoverCardContentProps) {
  const card = useCard("HoverCardContent");
  const [open, setOpen] = useState(false);
  const [mode, setMode] = useState<"manual" | "hint">("manual");

  // popover="hint" lets a hint close other hints but leave menus open. Engines without it
  // would read the value as manual anyway; asking first keeps the server render stable.
  useEffect(() => {
    const probe = document.createElement("span");
    probe.setAttribute("popover", "hint");
    if (probe.popover === "hint") setMode("hint");
  }, []);

  // While open: Escape closes and hands focus back to the trigger; any page scroll closes it.
  useEffect(() => {
    if (!open) return;
    const element = document.getElementById(card.id);
    function onKeyDown(event: KeyboardEvent) {
      if (event.key !== "Escape") return;
      event.preventDefault();
      const trigger = card.trigger.current?.firstElementChild;
      if (element?.contains(document.activeElement) && trigger instanceof HTMLElement) trigger.focus();
      card.close(0);
    }
    function onScroll(event: Event) {
      if (event.target instanceof Node && element?.contains(event.target)) return;
      card.close(0);
    }
    document.addEventListener("keydown", onKeyDown, true);
    // Listen from the next frame, so the scroll that focusing the trigger caused does not count.
    const frame = requestAnimationFrame(() =>
      window.addEventListener("scroll", onScroll, { capture: true, passive: true }),
    );
    return () => {
      cancelAnimationFrame(frame);
      document.removeEventListener("keydown", onKeyDown, true);
      window.removeEventListener("scroll", onScroll, { capture: true });
    };
  }, [open, card]);

  return (
    <span
      {...rest}
      id={card.id}
      popover={mode}
      className={["eq-hover-card-content", className].filter(Boolean).join(" ")}
      style={{ positionAnchor: card.anchorName, ...style }}
      onToggle={(event: ToggleEvent<HTMLSpanElement>) => {
        onToggle?.(event);
        setOpen(event.newState === "open");
      }}
      onPointerEnter={(event: PointerEvent<HTMLSpanElement>) => {
        onPointerEnter?.(event);
        card.cancel();
      }}
      onPointerLeave={(event: PointerEvent<HTMLSpanElement>) => {
        onPointerLeave?.(event);
        if (event.pointerType === "mouse") card.close(CLOSE_DELAY);
      }}
    >
      {children}
    </span>
  );
}