Hover Card

---
// src/components/ui/overlays/hover-card/HoverCard.astro — headless primitive (see ../../README.md).
// The preview card that appears when you rest on a link. Compose HoverCardTrigger / HoverCardContent.
//
// THE DELAYS ARE THE COMPONENT. Without an open delay the card fires at every link the pointer
// crosses on its way somewhere else; without a close delay it vanishes the instant the pointer
// leaves the trigger, which is exactly when the pointer is travelling INTO the card. Both are the
// difference between a hover card that is usable with a trackpad and one that is not, and neither
// can be expressed in CSS, which is why this primitive ships a script and Tooltip does not.
//
// Keyboard and screen-reader users are not served by hover at all, so they get a different, better
// contract: the trigger is `aria-describedby` the content, so the card is ANNOUNCED on focus rather
// than shown on a timer. The card still opens on keyboard focus (`:focus-visible` only — a mouse
// click on a link focuses it too, and that should not count as intent), and Escape closes it
// natively. A hover card must therefore never hold anything not reachable another way.
import type { HTMLAttributes } from "astro/types";

type Props = HTMLAttributes<"span"> & {
  /** Rest-before-open, in ms. Long enough to not fire while the pointer is merely passing. */
  openDelay?: number;
  /** Grace period before closing, in ms. Must cover the trip from the trigger into the card. */
  closeDelay?: number;
};

const { openDelay = 600, closeDelay = 300, class: className, ...rest } = Astro.props;
---

<span
  class={className}
  data-slot="hover-card"
  data-open-delay={openDelay}
  data-close-delay={closeDelay}
  {...rest}
>
  <slot />
</span>

<script>
  import { anchorTo, place } from "../../_anchor";
  import { onReadyOnce } from "../../_once";

  function wire(root: HTMLElement) {
    const trigger = root.querySelector<HTMLElement>('[data-slot="hover-card-trigger"]');
    const panel = root.querySelector<HTMLElement>('[data-slot="hover-card-content"]');
    if (!trigger || !panel) return;

    const openDelay = Number(root.dataset.openDelay);
    const closeDelay = Number(root.dataset.closeDelay);
    let timer: ReturnType<typeof setTimeout> | undefined;

    const open = () => {
      clearTimeout(timer);
      timer = setTimeout(() => {
        if (panel.matches(":popover-open")) return;
        // There is no `popovertarget` here — the card is opened by intent, not by a click — so the
        // controller is told what to anchor to. It forgets on close, hence re-stating it each time.
        anchorTo(panel, () => trigger.getBoundingClientRect());
        panel.showPopover();
        place(panel);
      }, openDelay);
    };
    const close = () => {
      clearTimeout(timer);
      timer = setTimeout(() => {
        if (panel.matches(":popover-open")) panel.hidePopover();
      }, closeDelay);
    };

    // The panel gets the same pair so the pointer can live inside the card without it closing.
    for (const el of [trigger, panel]) {
      el.addEventListener("pointerenter", open);
      el.addEventListener("pointerleave", close);
    }
    // `:focus-visible` is the whole guard: clicking a link focuses it, and a click is not a request
    // for a preview of where you are already going.
    trigger.addEventListener("focus", () => {
      if (trigger.matches(":focus-visible")) open();
    });
    trigger.addEventListener("blur", close);
  }

  onReadyOnce('[data-slot="hover-card"]', wire);
</script>

---
// src/components/ui/overlays/hover-card/HoverCardContent.astro — HoverCard compound part (see ../../README.md).
// Top-layer preview panel. `popover="auto"` for native Escape and light dismiss; `data-anchor` opts
// it into the shared `_anchor` controller, which the HoverCard script points at the trigger (there
// is no `popovertarget` — the card is opened by pointer intent, not by activation).
//
// It is NOT `role="dialog"`: nothing here should be reachable only by hovering, so announcing it as
// a dialog would promise an interaction model the component deliberately does not have. The trigger
// describes itself with this content instead — see HoverCardTrigger.
import "../../../../styles/structure.css";

import type { HTMLAttributes } from "astro/types";

type Props = HTMLAttributes<"div"> & {
  id: string;
  side?: "bottom" | "top" | "left" | "right";
  align?: "start" | "center" | "end";
  offset?: number;
};

const { side = "bottom", align = "center", offset, class: className, ...rest } = Astro.props;
---

<div
  popover="auto"
  data-slot="hover-card-content"
  data-anchor
  data-side={side}
  data-align={align}
  data-offset={offset}
  class={className}
  {...rest}
>
  <slot />
</div>

---
// src/components/ui/overlays/hover-card/HoverCardTrigger.astro — HoverCard compound part (see ../../README.md).
// Renders an <a> when `href` is set (the usual case — a hover card previews a destination), a
// <button> otherwise. `for` must be the HoverCardContent's `id`: it becomes `aria-describedby`, so
// the card's content is announced to a screen-reader user on focus, who will never trigger a hover.
import type { HTMLAttributes } from "astro/types";

type Props = HTMLAttributes<"button"> & { for: string; href?: string };

const { for: target, href, class: className, ...rest } = Astro.props;
const Tag = href ? "a" : "button";
---

<Tag
  href={href}
  type={href ? undefined : "button"}
  aria-describedby={target}
  data-slot="hover-card-trigger"
  class={className}
  {...rest}
>
  <slot />
</Tag>

import HoverCard from "./HoverCard.astro";
import HoverCardContent from "./HoverCardContent.astro";
import HoverCardTrigger from "./HoverCardTrigger.astro";

export { HoverCard, HoverCardContent, HoverCardTrigger };
export default HoverCard;