Peek

"use client";

import {
  useEffect,
  useId,
  useRef,
  useState,
  type ComponentProps,
  type FocusEvent,
  type KeyboardEvent,
  type MouseEvent,
  type PointerEvent,
  type ReactElement,
  type ReactNode,
} from "react";
import "./peek.css";

const KEY_HOLD = 250;
const POINTER_HOLD = 300;
const GAP = 8;
const SLOP = 6;

const ACTIVATES_ON_SPACE =
  'button, summary, input:is([type="button"], [type="submit"], [type="reset"], [type="checkbox"], [type="radio"])';

export type PeekProps = Omit<ComponentProps<"span">, "children"> & {
  /** Names the preview panel for assistive tech, e.g. "Deploy a3f9c1 summary". */
  label: string;
  /** What the panel shows while held. */
  preview: ReactNode;
  /** Exactly one focusable element: a link, a button or a row. */
  children: ReactElement<{ "aria-describedby"?: string }>;
  /** Beside the trigger (flips to the start side) or below it (flips above). */
  placement?: "end" | "bottom";
};

type Key = Pick<
  globalThis.KeyboardEvent,
  "key" | "repeat" | "altKey" | "ctrlKey" | "metaKey" | "preventDefault" | "stopPropagation"
>;

type Hold = { source: "key" | "pointer"; shown: boolean; timer: number; x: number; y: number };

export function Peek({
  label,
  preview,
  children,
  placement = "end",
  className,
  onKeyDown,
  onKeyUp,
  onPointerDown,
  onPointerMove,
  onPointerUp,
  onPointerCancel,
  onPointerEnter,
  onPointerLeave,
  onClickCapture,
  onContextMenu,
  onBlur,
  ...rest
}: PeekProps) {
  const id = useId();
  const hintId = `${id}-hint`;
  const panelId = `${id}-panel`;
  const rootRef = useRef<HTMLSpanElement>(null);
  const panelRef = useRef<HTMLSpanElement>(null);
  const hold = useRef<Hold | null>(null);
  const swallowClick = useRef(false);
  const [shown, setShown] = useState(false);
  const [hovered, setHovered] = useState(false);

  function trigger() {
    const first = rootRef.current?.firstElementChild;
    return first instanceof HTMLElement ? first : null;
  }

  function show() {
    const panel = panelRef.current;
    const el = trigger();
    if (!panel || !el || typeof panel.showPopover !== "function") return;
    if (!panel.matches(":popover-open")) panel.showPopover();
    const r = el.getBoundingClientRect();
    const w = panel.offsetWidth;
    const h = panel.offsetHeight;
    const vw = document.documentElement.clientWidth;
    const vh = document.documentElement.clientHeight;
    let x: number;
    let y: number;
    let side: string;
    if (placement === "end") {
      side = r.right + GAP + w <= vw - GAP || r.left - GAP - w < GAP ? "end" : "start";
      x = side === "end" ? r.right + GAP : r.left - GAP - w;
      y = r.top;
    } else {
      side = r.bottom + GAP + h <= vh - GAP || r.top - GAP - h < GAP ? "bottom" : "top";
      x = r.left;
      y = side === "bottom" ? r.bottom + GAP : r.top - GAP - h;
    }
    panel.style.left = `${Math.max(GAP, Math.min(x, vw - w - GAP))}px`;
    panel.style.top = `${Math.max(GAP, Math.min(y, vh - h - GAP))}px`;
    panel.dataset.side = side;
    if (hold.current) hold.current.shown = true;
    setShown(true);
  }

  function hide() {
    const panel = panelRef.current;
    if (panel?.matches(":popover-open")) panel.hidePopover();
    setShown(false);
  }

  function start(source: Hold["source"], x = 0, y = 0) {
    end();
    const timer = window.setTimeout(show, source === "key" ? KEY_HOLD : POINTER_HOLD);
    hold.current = { source, shown: false, timer, x, y };
  }

  /** Ends any hold. Returns true when the panel had appeared. */
  function end() {
    const current = hold.current;
    hold.current = null;
    if (!current) return false;
    window.clearTimeout(current.timer);
    if (current.shown) hide();
    return current.shown;
  }

  function keyDown(event: Key) {
    if (event.key === "Escape" && hold.current) {
      end();
      return;
    }
    if (event.key !== " " || event.altKey || event.ctrlKey || event.metaKey) return;
    event.preventDefault();
    event.stopPropagation();
    if (!event.repeat && !hold.current) start("key");
  }

  function keyUp(event: Key, el: HTMLElement) {
    if (event.key !== " " || hold.current?.source !== "key") return;
    event.preventDefault();
    event.stopPropagation();
    const wasShown = end();
    if (!wasShown && document.activeElement === el && el.matches(ACTIVATES_ON_SPACE)) el.click();
  }

  // Hover plus Space: only while nothing else has focus, so Space is never taken from a focused control.
  useEffect(() => {
    if (!hovered) return;
    function idle() {
      const active = document.activeElement;
      return !active || active === document.body;
    }
    function down(event: globalThis.KeyboardEvent) {
      const el = trigger();
      if (el && idle()) keyDown(event);
    }
    function up(event: globalThis.KeyboardEvent) {
      const el = trigger();
      if (el && idle()) keyUp(event, el);
    }
    document.addEventListener("keydown", down);
    document.addEventListener("keyup", up);
    return () => {
      document.removeEventListener("keydown", down);
      document.removeEventListener("keyup", up);
    };
  }, [hovered]);

  useEffect(() => () => {
    if (hold.current) window.clearTimeout(hold.current.timer);
  }, []);

  function fromTrigger(target: EventTarget) {
    return target === trigger();
  }

  // The description is set on the element itself, not by cloning: when a server
  // component passes the child, it arrives as a reference whose props cannot be read.
  useEffect(() => {
    const el = trigger();
    if (!el) return;
    const own = (el.getAttribute("aria-describedby") ?? "").split(" ").filter((id) => id && id !== hintId && id !== panelId);
    el.setAttribute("aria-describedby", [...own, hintId, shown ? panelId : ""].filter(Boolean).join(" "));
  });

  return (
    <span
      {...rest}
      ref={rootRef}
      className={["eq-peek", className].filter(Boolean).join(" ")}
      data-placement={placement}
      onKeyDown={(event: KeyboardEvent<HTMLSpanElement>) => {
        onKeyDown?.(event);
        if (fromTrigger(event.target)) keyDown(event);
      }}
      onKeyUp={(event: KeyboardEvent<HTMLSpanElement>) => {
        onKeyUp?.(event);
        const el = trigger();
        if (el && event.target === el) keyUp(event, el);
      }}
      onBlur={(event: FocusEvent<HTMLSpanElement>) => {
        onBlur?.(event);
        if (hold.current?.source === "key") end();
      }}
      onPointerEnter={(event: PointerEvent<HTMLSpanElement>) => {
        onPointerEnter?.(event);
        if (event.pointerType === "mouse") setHovered(true);
      }}
      onPointerLeave={(event: PointerEvent<HTMLSpanElement>) => {
        onPointerLeave?.(event);
        setHovered(false);
        const el = trigger();
        if (hold.current?.source === "pointer" || (hold.current && document.activeElement !== el)) end();
      }}
      onPointerDown={(event: PointerEvent<HTMLSpanElement>) => {
        onPointerDown?.(event);
        swallowClick.current = false;
        const el = trigger();
        if (!event.isPrimary || event.button !== 0 || !el || !el.contains(event.target as Node)) return;
        start("pointer", event.clientX, event.clientY);
      }}
      onPointerMove={(event: PointerEvent<HTMLSpanElement>) => {
        onPointerMove?.(event);
        const current = hold.current;
        if (current?.source !== "pointer" || current.shown) return;
        if (Math.hypot(event.clientX - current.x, event.clientY - current.y) > SLOP) end();
      }}
      onPointerUp={(event: PointerEvent<HTMLSpanElement>) => {
        onPointerUp?.(event);
        if (hold.current?.source === "pointer" && end()) swallowClick.current = true;
      }}
      onPointerCancel={(event: PointerEvent<HTMLSpanElement>) => {
        onPointerCancel?.(event);
        if (hold.current?.source === "pointer") end();
      }}
      onClickCapture={(event: MouseEvent<HTMLSpanElement>) => {
        onClickCapture?.(event);
        if (!swallowClick.current) return;
        swallowClick.current = false;
        event.preventDefault();
        event.stopPropagation();
      }}
      onContextMenu={(event: MouseEvent<HTMLSpanElement>) => {
        onContextMenu?.(event);
        if (hold.current?.source === "pointer") event.preventDefault();
      }}
    >
      {children}
      <span id={hintId} className="eq-peek-hint">
        Hold Space to preview
      </span>
      <span
        ref={panelRef}
        id={panelId}
        popover="manual"
        role="tooltip"
        aria-label={label}
        className="eq-peek-panel"
      >
        {preview}
      </span>
    </span>
  );
}