Tour

"use client";

import {
  useEffect,
  useId,
  useRef,
  useState,
  type ComponentProps,
  type KeyboardEvent,
  type ReactNode,
} from "react";
import { Button } from "./button";
import "./tour.css";

export type TourStep = {
  /** CSS selector for the element to point at. Steps whose target is missing are skipped. */
  target: string;
  title: string;
  body: ReactNode;
  /** Preferred side of the target for the card. It flips when there is no room. */
  placement?: "top" | "bottom" | "start" | "end";
};

export type TourProps = Omit<ComponentProps<"div">, "children" | "title"> & {
  steps: TourStep[];
  /** Names the tour, e.g. "Product tour". Shown above each step's title. */
  label: string;
  open?: boolean;
  defaultOpen?: boolean;
  onOpenChange?: (open: boolean) => void;
  step?: number;
  defaultStep?: number;
  onStepChange?: (step: number) => void;
  /** Called when Done is pressed on the last step, before the tour closes. */
  onFinish?: () => void;
};

type Side = "top" | "bottom" | "left" | "right";

const HOLE_PAD = 6;
const GAP = 12;
const EDGE = 8;

function findTarget(steps: TourStep[], index: number): Element | null {
  const step = steps[index];
  if (!step) return null;
  try {
    return document.querySelector(step.target);
  } catch {
    return null;
  }
}

function motionIsOff(element: Element) {
  return getComputedStyle(element).getPropertyValue("--eq-dur-move").trim().startsWith("0");
}

/**
 * A guided walkthrough: a spotlight around one element at a time and a card
 * beside it. Both live in the top layer as manual popovers; the page stays
 * usable underneath.
 */
export function Tour({
  steps,
  label,
  open: openProp,
  defaultOpen = false,
  onOpenChange,
  step: stepProp,
  defaultStep = 0,
  onStepChange,
  onFinish,
  className,
  onKeyDown,
  ...rest
}: TourProps) {
  const ids = useId();
  const cardRef = useRef<HTMLDivElement>(null);
  const holeRef = useRef<HTMLDivElement>(null);
  const returnFocus = useRef<HTMLElement | null>(null);
  const indexRef = useRef(0);
  const [ownOpen, setOwnOpen] = useState(defaultOpen);
  const [ownStep, setOwnStep] = useState(defaultStep);
  const [present, setPresent] = useState<boolean[] | null>(null);
  const open = openProp ?? ownOpen;
  const index = stepProp ?? ownStep;
  indexRef.current = index;

  function setOpen(next: boolean) {
    if (openProp === undefined) setOwnOpen(next);
    onOpenChange?.(next);
  }

  function setIndex(next: number) {
    if (stepProp === undefined) setOwnStep(next);
    onStepChange?.(next);
  }

  function scan() {
    const found = steps.map((_, i) => findTarget(steps, i) !== null);
    setPresent(found);
    return found;
  }

  function place(target: Element, glide: boolean) {
    const card = cardRef.current;
    const hole = holeRef.current;
    if (!card || !hole) return;
    if (!glide) {
      card.setAttribute("data-instant", "");
      hole.setAttribute("data-instant", "");
    }

    const r = target.getBoundingClientRect();
    hole.style.left = `${r.left - HOLE_PAD}px`;
    hole.style.top = `${r.top - HOLE_PAD}px`;
    hole.style.width = `${r.width + HOLE_PAD * 2}px`;
    hole.style.height = `${r.height + HOLE_PAD * 2}px`;

    const vw = document.documentElement.clientWidth;
    const vh = window.innerHeight;
    const cw = card.offsetWidth;
    const ch = card.offsetHeight;
    const rtl = getComputedStyle(card).direction === "rtl";
    const wanted = steps[indexRef.current]?.placement ?? "bottom";
    const side: Side =
      wanted === "start" ? (rtl ? "right" : "left") : wanted === "end" ? (rtl ? "left" : "right") : wanted;
    const away = HOLE_PAD + GAP;
    const fits: Record<Side, boolean> = {
      bottom: r.bottom + away + ch <= vh - EDGE,
      top: r.top - away - ch >= EDGE,
      right: r.right + away + cw <= vw - EDGE,
      left: r.left - away - cw >= EDGE,
    };
    const opposite: Record<Side, Side> = { top: "bottom", bottom: "top", left: "right", right: "left" };
    const order: Side[] = [side, opposite[side], "bottom", "top", "right", "left"];
    const chosen = order.find((s) => fits[s]) ?? side;

    let x = r.left + r.width / 2 - cw / 2;
    let y = r.top + r.height / 2 - ch / 2;
    if (chosen === "bottom") y = r.bottom + away;
    if (chosen === "top") y = r.top - away - ch;
    if (chosen === "right") x = r.right + away;
    if (chosen === "left") x = r.left - away - cw;
    x = Math.min(Math.max(x, EDGE), Math.max(EDGE, vw - cw - EDGE));
    y = Math.min(Math.max(y, EDGE), Math.max(EDGE, vh - ch - EDGE));
    card.style.left = `${x}px`;
    card.style.top = `${y}px`;
    card.setAttribute("data-side", chosen);

    if (!glide) {
      // Commit the jump before the glide comes back on.
      card.getBoundingClientRect();
      card.removeAttribute("data-instant");
      hole.removeAttribute("data-instant");
    }
  }

  // Opening and closing: the popovers, the first step that exists, and focus.
  useEffect(() => {
    const card = cardRef.current;
    const hole = holeRef.current;
    if (!card || !hole) return;
    if (!open) {
      if (!card.matches(":popover-open")) return;
      const focusInside = card.contains(document.activeElement) || document.activeElement === document.body;
      card.hidePopover();
      hole.hidePopover();
      if (focusInside && returnFocus.current?.isConnected) returnFocus.current.focus();
      return;
    }
    const found = scan();
    let first = -1;
    for (let i = index; i < steps.length && first < 0; i++) if (found[i]) first = i;
    for (let i = index - 1; i >= 0 && first < 0; i--) if (found[i]) first = i;
    if (first < 0) {
      setOpen(false);
      return;
    }
    if (first !== index) setIndex(first);
    returnFocus.current = document.activeElement instanceof HTMLElement ? document.activeElement : null;
    hole.showPopover();
    card.showPopover();
    indexRef.current = first;
    const target = findTarget(steps, first);
    if (target) place(target, false);
    card.focus();
  }, [open]);

  // Each step: bring the target into view and glide the hole and the card to it.
  useEffect(() => {
    const card = cardRef.current;
    if (!open || !card?.matches(":popover-open")) return;
    const target = findTarget(steps, index);
    if (!target) return;
    const r = target.getBoundingClientRect();
    if (r.top < 0 || r.bottom > window.innerHeight || r.left < 0 || r.right > window.innerWidth) {
      target.scrollIntoView({ block: "center", inline: "nearest", behavior: motionIsOff(card) ? "instant" : "smooth" });
    }
    place(target, true);
  }, [open, index]);

  // While open: follow the target through scrolling and resizing, and close on Escape from anywhere.
  useEffect(() => {
    if (!open) return;
    let frame = 0;
    function follow() {
      cancelAnimationFrame(frame);
      frame = requestAnimationFrame(() => {
        const target = findTarget(steps, indexRef.current);
        if (target) place(target, false);
      });
    }
    function escape(event: globalThis.KeyboardEvent) {
      if (event.key !== "Escape" || event.defaultPrevented) return;
      event.preventDefault();
      setOpen(false);
    }
    window.addEventListener("scroll", follow, { capture: true, passive: true });
    window.addEventListener("resize", follow);
    document.addEventListener("keydown", escape);
    return () => {
      cancelAnimationFrame(frame);
      window.removeEventListener("scroll", follow, { capture: true });
      window.removeEventListener("resize", follow);
      document.removeEventListener("keydown", escape);
    };
  }, [open, steps]);

  const found = present ?? steps.map(() => true);
  const shown = found.map((f, i) => (f ? i : -1)).filter((i) => i >= 0);
  const position = shown.indexOf(index);
  const prev = position > 0 ? shown[position - 1] : -1;
  const next = position >= 0 && position < shown.length - 1 ? shown[position + 1] : -1;
  const current = steps[index];

  function go(direction: 1 | -1) {
    const now = scan();
    for (let i = index + direction; i >= 0 && i < steps.length; i += direction) {
      if (now[i]) {
        setIndex(i);
        return;
      }
    }
    if (direction === 1) finish();
  }

  function finish() {
    onFinish?.();
    setOpen(false);
  }

  function handleKeyDown(event: KeyboardEvent<HTMLDivElement>) {
    onKeyDown?.(event);
    if (event.defaultPrevented) return;
    if (event.key !== "ArrowLeft" && event.key !== "ArrowRight") return;
    const rtl = getComputedStyle(event.currentTarget).direction === "rtl";
    const forward = (event.key === "ArrowRight") !== rtl;
    event.preventDefault();
    event.stopPropagation();
    if (forward ? next >= 0 : prev >= 0) go(forward ? 1 : -1);
  }

  return (
    <>
      <div ref={holeRef} popover="manual" className="eq-tour-spotlight" aria-hidden="true" />
      <div
        role="dialog"
        aria-labelledby={`${ids}-label ${ids}-title`}
        aria-describedby={`${ids}-body`}
        tabIndex={-1}
        {...rest}
        ref={cardRef}
        popover="manual"
        className={["eq-tour", className].filter(Boolean).join(" ")}
        onKeyDown={handleKeyDown}
      >
        <div className="eq-tour-header">
          <p id={`${ids}-label`} className="eq-tour-label">
            {label}
          </p>
          <Button
            variant="ghost"
            size="s"
            className="eq-tour-close"
            aria-label="End tour"
            onClick={() => setOpen(false)}
            lead={
              <svg viewBox="0 0 16 16" width="16" height="16" fill="none" stroke="currentColor" strokeWidth="1.5" strokeLinecap="round" aria-hidden="true">
                <path d="M4 4l8 8M12 4l-8 8" />
              </svg>
            }
          />
        </div>
        <div className="eq-tour-content" aria-live="polite">
          <h2 id={`${ids}-title`} className="eq-tour-title">
            {current?.title}
          </h2>
          <div id={`${ids}-body`} className="eq-tour-body">
            {current?.body}
          </div>
        </div>
        <div className="eq-tour-footer">
          <span className="eq-tour-count">
            {Math.max(position, 0) + 1} of {shown.length}
          </span>
          <Button
            variant="outline"
            size="s"
            className="eq-tour-back"
            aria-disabled={prev < 0 || undefined}
            onClick={() => prev >= 0 && go(-1)}
          >
            Back
          </Button>
          <Button size="s" onClick={() => (next >= 0 ? go(1) : finish())}>
            {next >= 0 ? "Next" : "Done"}
          </Button>
        </div>
      </div>
    </>
  );
}