@eifi1/ui-kit 0.51.7 → 0.52.0

package/dist/tour/tour-overlay.js

@@ -0,0 +1,741 @@
+"use client";
+import { Fragment, jsx, jsxs } from "react/jsx-runtime";
+import {
+  useCallback,
+  useEffect,
+  useEffectEvent,
+  useId,
+  useLayoutEffect,
+  useRef,
+  useState,
+  useSyncExternalStore
+} from "react";
+import { createPortal } from "react-dom";
+import { cn } from "../lib/cn.js";
+import { Button } from "../components/button.js";
+import { firstTabStop, tabStops, useFocusTrap } from "../hooks/use-focus-trap.js";
+import { useDismissLayer } from "../hooks/use-dismiss.js";
+import { sameRect } from "../hooks/use-anchored-rect.js";
+import { anchoredInline, viewportSize } from "../hooks/use-anchored-panel.js";
+import { useBreakpoint } from "../hooks/use-breakpoint.js";
+import { useCoarsePointer } from "../hooks/use-large-text.js";
+import { dirOf, horizontalStep } from "../lib/direction.js";
+import { isComposing } from "../lib/ime.js";
+import { focusQuietly } from "../lib/quiet-focus.js";
+import { devWarnings, isShown, stepContext } from "./tour-gates.js";
+import { dockEdge, dockStyle, readBand, scrollIntoFreeHalf } from "./tour-dock.js";
+const NOOP = () => {
+};
+function firstEmptied(steps, floor, index, gates) {
+  const ctx = stepContext(gates, "goto");
+  for (let j = floor; j < index; j++) {
+    const key = steps[j].gate;
+    if (key && gates.get(key) === false && isShown(steps[j], ctx)) return j;
+  }
+  return -1;
+}
+function isVisible(el) {
+  const r = el.getBoundingClientRect();
+  if (r.width <= 0 || r.height <= 0) return false;
+  const style = getComputedStyle(el);
+  return style.visibility !== "hidden" && style.display !== "none";
+}
+function queryVisibleTarget(selector) {
+  const els = document.querySelectorAll(selector);
+  for (const el of els) {
+    if (isVisible(el)) return el;
+  }
+  return null;
+}
+function rectOf(el) {
+  const r = el.getBoundingClientRect();
+  return { top: r.top, left: r.left, width: r.width, height: r.height };
+}
+const RING_BAND = 6;
+function spotRectOf(el, step) {
+  const own = rectOf(el);
+  if (!isFieldStep(step)) return own;
+  const ids = /* @__PURE__ */ new Set();
+  const holders = [el, ...Array.from(el.querySelectorAll("[aria-describedby]"))];
+  for (const holder of holders) {
+    for (const id of (holder.getAttribute("aria-describedby") ?? "").split(/\s+/)) if (id) ids.add(id);
+  }
+  if (ids.size === 0) return own;
+  const lines = [];
+  for (const id of ids) {
+    const line = document.getElementById(id);
+    if (!line || el.contains(line) || line.closest('[role="tooltip"]') || !isVisible(line)) continue;
+    const r = line.getBoundingClientRect();
+    if (r.width > 1 && r.height > 1) lines.push(r);
+  }
+  let top = own.top;
+  let left = own.left;
+  let right = own.left + own.width;
+  let bottom = own.top + own.height;
+  const reach = (step.padding ?? 8) + RING_BAND;
+  for (let grew = true; grew; ) {
+    grew = false;
+    for (let i = lines.length - 1; i >= 0; i--) {
+      const r = lines[i];
+      const across = r.left < right && r.right > left;
+      const gap = Math.max(r.top - bottom, top - r.bottom);
+      if (!across || gap > reach) continue;
+      top = Math.min(top, r.top);
+      left = Math.min(left, r.left);
+      right = Math.max(right, r.right);
+      bottom = Math.max(bottom, r.bottom);
+      lines.splice(i, 1);
+      grew = true;
+    }
+  }
+  return { top, left, width: right - left, height: bottom - top };
+}
+function layerHost(el) {
+  return el.closest("[data-kit-layer]");
+}
+function coversViewport(host, el) {
+  let surface = host;
+  if (host.getAttribute("data-kit-layer") === "backdrop") {
+    for (const child of Array.from(host.children)) {
+      if (child.contains(el)) {
+        surface = child;
+        break;
+      }
+    }
+  }
+  const r = surface.getBoundingClientRect();
+  const vv = window.visualViewport;
+  const view = viewportSize();
+  const top = vv?.offsetTop ?? 0;
+  const bottom = top + (vv?.height ?? view.height);
+  const width = vv?.width ?? view.width;
+  return r.width > 0 && r.left <= 1 && r.top <= top + 1 && r.right >= width - 1 && r.bottom >= bottom - 1;
+}
+function docks(step, dockOnPhones, phone) {
+  if (!phone || !step.target) return false;
+  return step.placement === "dock" || step.placement === void 0 && dockOnPhones && isFieldStep(step);
+}
+function isFieldStep(step) {
+  return !!(step.interactive || step.awaitInput || step.gate || step.awaitGate);
+}
+function TourOverlay({
+  steps,
+  index,
+  via,
+  floor,
+  position,
+  count,
+  refusal,
+  onGoTo,
+  labels,
+  gates,
+  dockOnPhones,
+  onNext,
+  onPrev,
+  onSkip
+}) {
+  const step = steps[index];
+  const isFirst = position <= 1;
+  const isLast = position >= count;
+  const [located, setLocated] = useState(null);
+  const current = located !== null && located.index === index && located.step === step ? located : null;
+  const ready = current !== null;
+  const rect = current?.rect ?? null;
+  const dir = current?.dir ?? "ltr";
+  const rootRef = useRef(null);
+  const cardRef = useRef(null);
+  const bodyId = useId();
+  const hintId = useId();
+  const phone = useBreakpoint("max-sm");
+  const coarse = useCoarsePointer();
+  const coarseOnArrival = useEffectEvent(() => coarse);
+  const gateVersion = useSyncExternalStore(gates.subscribe, gates.version, gates.version);
+  const gateKey = step.gate;
+  const enforced = !!gateKey && gates.has(gateKey);
+  const locked = enforced && gates.get(gateKey) !== true;
+  const [polite, setPolite] = useState("");
+  const announce = useCallback((text) => {
+    setPolite((prev) => prev === text ? `${text}\u200B` : text);
+  }, []);
+  useEffect(() => {
+    let cancelled = false;
+    let raf = 0;
+    const settle = (el) => {
+      let layer2 = null;
+      let fullScreen = false;
+      if (el && isFieldStep(step)) {
+        const host = layerHost(el);
+        layer2 = document.createElement("div");
+        layer2.setAttribute("data-tour-layer", "");
+        if (host) host.after(layer2);
+        else document.body.appendChild(layer2);
+        fullScreen = !!host && coversViewport(host, el);
+      }
+      setLocated({ index, step, rect: el ? spotRectOf(el, step) : null, dir: dirOf(el), layer: layer2, fullScreen });
+    };
+    void (async () => {
+      try {
+        await step.beforeStep?.(stepContext(gates, via));
+      } catch (error) {
+        console.error(error);
+      }
+      if (cancelled) return;
+      if (!step.target) {
+        settle(null);
+        return;
+      }
+      let tries = 0;
+      const find = () => {
+        if (cancelled) return;
+        const el = queryVisibleTarget(step.target);
+        if (el) {
+          if (docks(step, dockOnPhones, phone)) scrollIntoFreeHalf(el, null, null);
+          else el.scrollIntoView({ block: "center", behavior: "smooth" });
+          settle(el);
+          return;
+        }
+        if (tries++ < 45) raf = requestAnimationFrame(find);
+        else settle(null);
+      };
+      find();
+    })();
+    return () => {
+      cancelled = true;
+      cancelAnimationFrame(raf);
+    };
+  }, [index, step]);
+  useEffect(() => {
+    if (!step.target) return;
+    const update = () => {
+      const el = queryVisibleTarget(step.target);
+      if (el) {
+        const next = spotRectOf(el, step);
+        const host = layerHost(el);
+        const full = !!host && coversViewport(host, el);
+        setLocated((prev) => {
+          if (!prev || prev.index !== index || prev.step !== step) return prev;
+          const fullScreen = prev.layer ? full : prev.fullScreen;
+          if (sameRect(prev.rect, next) && fullScreen === prev.fullScreen) return prev;
+          return { ...prev, rect: next, fullScreen };
+        });
+      }
+    };
+    window.addEventListener("scroll", update, true);
+    window.addEventListener("resize", update);
+    const id = window.setInterval(update, 250);
+    return () => {
+      window.removeEventListener("scroll", update, true);
+      window.removeEventListener("resize", update);
+      clearInterval(id);
+    };
+  }, [index, step]);
+  const layer = located?.layer ?? null;
+  useEffect(() => {
+    if (!layer) return;
+    return () => layer.remove();
+  }, [layer]);
+  useDismissLayer(
+    ready,
+    (e) => {
+      if (interactive && step.target && e.target instanceof Node) {
+        const el = queryVisibleTarget(step.target);
+        if (el?.contains(e.target)) return;
+      }
+      onSkip();
+    },
+    // Not an overlay to `useOverlayOpen`: a floating launcher a tour spotlights stays.
+    { overlay: false }
+  );
+  const spotted = rect !== null;
+  useEffect(() => {
+    if (!ready || !spotted || !step.awaitClick || !step.target) return;
+    const el = queryVisibleTarget(step.target);
+    if (!el) return;
+    const onClick = () => window.setTimeout(() => onNext(), 0);
+    el.addEventListener("click", onClick, { once: true });
+    return () => el.removeEventListener("click", onClick);
+  }, [ready, spotted, index, step, onNext]);
+  const interactive = spotted && !!step.target && isFieldStep(step);
+  const guided = interactive && !!(step.gate || step.awaitInput || step.awaitGate);
+  const awaitsRelease = spotted && !!step.target && !!step.awaitGate;
+  const warnedGateRef = useRef(null);
+  useEffect(() => {
+    if (!ready || !gateKey || gates.has(gateKey) || !devWarnings() || warnedGateRef.current === step) return;
+    warnedGateRef.current = step;
+    console.warn(
+      `[ui-kit] Tour step "${step.title}" waits for the gate "${gateKey}", which nothing publishes: its Next is open. Publish it with useTourGate beside the field, or the form has closed under the tour.`
+    );
+  }, [ready, gateKey, gates, step, gateVersion]);
+  useEffect(() => {
+    if (!ready || !step.optional || step.gate || !devWarnings()) return;
+    console.warn(
+      `[ui-kit] Tour step "${step.title}" is \`optional\` without a \`gate\`: it shows the Optional chip and a plain Next. "Leave empty" needs a gate to compare.`
+    );
+  }, [ready, step]);
+  const wasLockedRef = useRef(null);
+  useEffect(() => {
+    if (!ready || !gateKey) return;
+    const before = wasLockedRef.current;
+    if (before && before.step === step && before.locked && !locked && enforced) announce(labels.gateReady);
+    wasLockedRef.current = { step, locked };
+  }, [ready, gateKey, step, locked, enforced, announce, labels.gateReady]);
+  useEffect(() => {
+    if (!ready || !guided || !step.target) return;
+    const el = queryVisibleTarget(step.target);
+    const control = el ? firstTabStop(el) : null;
+    const previous = control ? control.getAttribute("aria-describedby") : null;
+    if (control) control.setAttribute("aria-describedby", previous ? `${previous} ${bodyId}` : bodyId);
+    if (coarseOnArrival() || !control) cardRef.current?.focus();
+    else if (!el.contains(document.activeElement)) focusQuietly(control);
+    if (!control) return;
+    return () => {
+      if (previous === null) control.removeAttribute("aria-describedby");
+      else control.setAttribute("aria-describedby", previous);
+    };
+  }, [ready, guided, index, step, bodyId]);
+  useEffect(() => {
+    if (!ready || !guided || !step.target) return;
+    const onTab = (e) => {
+      if (e.key !== "Tab") return;
+      const el = queryVisibleTarget(step.target);
+      const card = cardRef.current;
+      if (!el || !card) return;
+      const active = document.activeElement;
+      const fieldStops = tabStops(el);
+      const cardStops = tabStops(card);
+      if (fieldStops.length === 0 || cardStops.length === 0) return;
+      let to = null;
+      if (active instanceof Node && el.contains(active)) {
+        if (!e.shiftKey && active === fieldStops[fieldStops.length - 1]) to = cardStops[0];
+        else if (e.shiftKey && active === fieldStops[0]) to = cardStops[cardStops.length - 1];
+      } else if (active instanceof Node && card.contains(active)) {
+        if (!e.shiftKey && active === cardStops[cardStops.length - 1]) to = fieldStops[0];
+        else if (e.shiftKey && (active === cardStops[0] || active === card)) to = fieldStops[fieldStops.length - 1];
+      }
+      if (!to) return;
+      e.preventDefault();
+      e.stopPropagation();
+      to.focus();
+    };
+    document.addEventListener("keydown", onTab, true);
+    return () => document.removeEventListener("keydown", onTab, true);
+  }, [ready, guided, index, step]);
+  useEffect(() => {
+    if (!ready || !spotted || !gateKey || !step.target) return;
+    const el = queryVisibleTarget(step.target);
+    if (!el) return;
+    const satisfied = () => !gates.has(gateKey) || gates.get(gateKey) === true;
+    let timer = 0;
+    let armed = el.contains(document.activeElement);
+    const check = () => {
+      window.clearTimeout(timer);
+      timer = window.setTimeout(() => {
+        if (satisfied()) onNext();
+      }, 0);
+    };
+    const onFocusIn = () => {
+      armed = true;
+    };
+    const onFocusOut = (e) => {
+      const to = e.relatedTarget;
+      if (to instanceof Node && el.contains(to)) return;
+      const wasArmed = armed;
+      armed = false;
+      if (!wasArmed) return;
+      if (to === null || to instanceof Node && rootRef.current?.contains(to)) check();
+    };
+    const onKeyDown = (e) => {
+      if (e.key !== "Enter" || !(e.target instanceof Node) || !el.contains(e.target)) return;
+      if (e.defaultPrevented || isComposing(e)) return;
+      if (e.target instanceof HTMLTextAreaElement && !(e.ctrlKey || e.metaKey)) return;
+      check();
+    };
+    el.addEventListener("focusin", onFocusIn);
+    el.addEventListener("focusout", onFocusOut);
+    document.addEventListener("keydown", onKeyDown);
+    return () => {
+      window.clearTimeout(timer);
+      el.removeEventListener("focusin", onFocusIn);
+      el.removeEventListener("focusout", onFocusOut);
+      document.removeEventListener("keydown", onKeyDown);
+    };
+  }, [ready, spotted, gateKey, gates, index, step, onNext]);
+  useEffect(() => {
+    if (!ready || !spotted || !step.awaitInput || !step.target) return;
+    const el = queryVisibleTarget(step.target);
+    if (!el) return;
+    const read = () => fieldValues(el);
+    const before = read();
+    let timer = 0;
+    let done = false;
+    const check = () => {
+      window.clearTimeout(timer);
+      timer = window.setTimeout(() => {
+        if (done || read() === before) return;
+        done = true;
+        onNext();
+      }, 0);
+    };
+    const onFocusOut = (e) => {
+      if (e.relatedTarget instanceof Node && el.contains(e.relatedTarget)) return;
+      check();
+    };
+    const onKeyDown = (e) => {
+      if (e.key === "Enter") check();
+    };
+    el.addEventListener("focusout", onFocusOut);
+    el.addEventListener("keydown", onKeyDown);
+    el.addEventListener("change", check);
+    return () => {
+      window.clearTimeout(timer);
+      el.removeEventListener("focusout", onFocusOut);
+      el.removeEventListener("keydown", onKeyDown);
+      el.removeEventListener("change", check);
+    };
+  }, [ready, spotted, index, step, onNext]);
+  const gateHint = step.gateHint ?? labels.gateHint;
+  const lockedNext = useCallback(() => {
+    const el = step.target ? queryVisibleTarget(step.target) : null;
+    const control = el ? firstTabStop(el) : null;
+    if (control) focusQuietly(control);
+    announce(gateHint);
+  }, [step.target, announce, gateHint]);
+  const tryNext = awaitsRelease ? NOOP : locked ? lockedNext : onNext;
+  const backTo = refusal ? firstEmptied(steps, floor, index, gates) : -1;
+  useEffect(() => {
+    const onKey = (e) => {
+      if (interactive && e.target instanceof Node && e.target !== document.body && !rootRef.current?.contains(e.target)) {
+        return;
+      }
+      if (e.key === "Escape") {
+        if (!ready) onSkip();
+        return;
+      }
+      if (!ready) return;
+      if (e.key === "Enter") {
+        if (step.awaitClick || step.awaitInput || ownsKey(e.target, "Enter")) return;
+        e.preventDefault();
+        tryNext();
+        return;
+      }
+      if (ownsKey(e.target, e.key)) return;
+      const delta = horizontalStep(e.key, rootRef.current);
+      if (delta === 1) {
+        e.preventDefault();
+        tryNext();
+      } else if (delta === -1) {
+        if (!isFirst) onPrev();
+      }
+    };
+    document.addEventListener("keydown", onKey);
+    return () => document.removeEventListener("keydown", onKey);
+  }, [isFirst, step, interactive, tryNext, onPrev, onSkip, ready]);
+  if (!ready) return null;
+  const bare = interactive && !!current?.fullScreen;
+  const pad = step.padding ?? 8;
+  const spot = rect ? { top: rect.top - pad, left: rect.left - pad, width: rect.width + pad * 2, height: rect.height + pad * 2 } : null;
+  return createPortal(
+    /* @__PURE__ */ jsxs(
+      "div",
+      {
+        ref: rootRef,
+        className: cn("pointer-events-none fixed inset-0", interactive ? "z-50" : "z-[60]"),
+        role: "dialog",
+        "aria-modal": interactive ? void 0 : "true",
+        "data-tour-overlay": "",
+        "data-tour-interactive": interactive ? "" : void 0,
+        "data-tour-bare": bare ? "" : void 0,
+        "aria-label": step.title,
+        dir,
+        children: [
+          spot && !bare && /* @__PURE__ */ jsx(SpotlightShields, { spot }),
+          spot ? /* @__PURE__ */ jsx(
+            "div",
+            {
+              className: "pointer-events-none fixed rounded-lg transition-all duration-200 ease-out",
+              style: {
+                top: spot.top,
+                left: spot.left,
+                width: spot.width,
+                height: spot.height,
+                // A two-tone frame, not a single translucent ring.
+                //
+                // The old treatment was `ring-2 ring-white/80` over a 55% scrim, and it
+                // "was barely visible" on the app's blue-tinted surfaces. Two reasons,
+                // and a single ring can't fix either: at 55% the surround stays bright
+                // enough that the un-dimmed hole barely reads AS a hole, and a 80%-white
+                // ring sitting on the edge of a light card is white-on-near-white.
+                //
+                // So: an opaque white band immediately around the target, a dark keyline
+                // outside it, then the scrim. Whatever the target's own colour is, one of
+                // the two bands is always in contrast with it and the other is always in
+                // contrast with the dimmed surround — there is no background that can
+                // swallow both. The blurred layer between them softens the step so the
+                // frame reads as lighting rather than as a pasted-on rectangle.
+                boxShadow: [
+                  "0 0 0 3px rgba(255,255,255,0.98)",
+                  "0 0 0 5px rgba(15,23,42,0.92)",
+                  "0 0 18px 6px rgba(15,23,42,0.45)",
+                  ...bare ? [] : ["0 0 0 9999px rgba(15,23,42,0.70)"]
+                ].join(", ")
+              }
+            }
+          ) : /* @__PURE__ */ jsx("div", { className: "pointer-events-auto fixed inset-0 bg-black/70" }),
+          /* @__PURE__ */ jsx(
+            TourCard,
+            {
+              cardRef,
+              step,
+              index,
+              position,
+              total: count,
+              labels,
+              isFirst,
+              isLast,
+              rect: spot,
+              dir,
+              trap: !guided,
+              bodyId,
+              hintId,
+              locked,
+              gateHint,
+              onBack: onPrev,
+              onNext: tryNext,
+              onLeaveEmpty: onNext,
+              onSkip,
+              awaitsRelease,
+              docked: spot !== null && docks(step, dockOnPhones, phone),
+              refusal,
+              backTo: backTo >= 0 ? { title: steps[backTo].title, go: () => onGoTo(backTo) } : null
+            }
+          ),
+          /* @__PURE__ */ jsx("div", { className: "sr-only", "aria-live": "polite", "aria-atomic": "true", children: polite })
+        ]
+      }
+    ),
+    interactive && current?.layer || document.body
+  );
+}
+function fieldValues(el) {
+  const fields = el.matches("input,textarea,select") ? [el] : Array.from(el.querySelectorAll("input,textarea,select"));
+  return fields.map(
+    (f) => f instanceof HTMLInputElement && (f.type === "checkbox" || f.type === "radio") ? String(f.checked) : f.value
+  ).join("\0");
+}
+function ownsKey(target, key) {
+  if (!(target instanceof HTMLElement)) return false;
+  if (target.isContentEditable) return true;
+  const tag = target.tagName;
+  if (tag === "TEXTAREA" || tag === "SELECT") return true;
+  if (tag === "INPUT") {
+    const type = target.type;
+    return key !== "Enter" || type !== "checkbox";
+  }
+  if (key !== "Enter") return false;
+  return tag === "BUTTON" || tag === "A" && target.hasAttribute("href") || target.getAttribute("role") === "button" || target.getAttribute("role") === "link";
+}
+function SpotlightShields({ spot }) {
+  const shield = "pointer-events-auto fixed";
+  const bottom = spot.top + spot.height;
+  return /* @__PURE__ */ jsxs(Fragment, { children: [
+    /* @__PURE__ */ jsx(
+      "div",
+      {
+        "data-tour-shield": "",
+        className: shield,
+        style: { top: 0, left: 0, right: 0, height: Math.max(0, spot.top) }
+      }
+    ),
+    /* @__PURE__ */ jsx("div", { "data-tour-shield": "", className: shield, style: { top: bottom, left: 0, right: 0, bottom: 0 } }),
+    /* @__PURE__ */ jsx(
+      "div",
+      {
+        "data-tour-shield": "",
+        className: shield,
+        style: { top: spot.top, left: 0, width: Math.max(0, spot.left), height: spot.height }
+      }
+    ),
+    /* @__PURE__ */ jsx(
+      "div",
+      {
+        "data-tour-shield": "",
+        className: shield,
+        style: { top: spot.top, left: spot.left + spot.width, right: 0, height: spot.height }
+      }
+    )
+  ] });
+}
+function placeCard(rect, cw, ch, vw, vh, m, placement, dir = "ltr") {
+  if (placement === "start") placement = dir === "rtl" ? "right" : "left";
+  else if (placement === "end") placement = dir === "rtl" ? "left" : "right";
+  const clampX = (x) => anchoredInline({ left: x, right: x + cw }, cw, { dir, align: "left", edge: m, viewportWidth: vw }).left;
+  if (!rect || placement === "center") {
+    return { top: Math.max(m, (vh - ch) / 2), left: clampX((vw - cw) / 2) };
+  }
+  const clampY = (y) => Math.min(Math.max(m, y), Math.max(m, vh - ch - m));
+  const centerX = clampX(rect.left + rect.width / 2 - cw / 2);
+  const centerY = clampY(rect.top + rect.height / 2 - ch / 2);
+  const belowTop = rect.top + rect.height + m;
+  const aboveTop = rect.top - ch - m;
+  const rightLeft = rect.left + rect.width + m;
+  const leftLeft = rect.left - cw - m;
+  const fitsBelow = belowTop + ch <= vh;
+  const fitsAbove = aboveTop >= 0;
+  const fitsRight = rightLeft + cw <= vw;
+  const fitsLeft = leftLeft >= 0;
+  switch (placement) {
+    case "top":
+      return { top: fitsAbove ? aboveTop : fitsBelow ? belowTop : clampY(aboveTop), left: centerX };
+    case "bottom":
+      return { top: fitsBelow ? belowTop : fitsAbove ? aboveTop : clampY(belowTop), left: centerX };
+    case "right":
+      return { top: centerY, left: fitsRight ? rightLeft : fitsLeft ? leftLeft : clampX(rightLeft) };
+    case "left":
+      return { top: centerY, left: fitsLeft ? leftLeft : fitsRight ? rightLeft : clampX(leftLeft) };
+    default:
+      if (fitsBelow) return { top: belowTop, left: centerX };
+      if (fitsAbove) return { top: aboveTop, left: centerX };
+      return { top: Math.max(m, (vh - ch) / 2), left: centerX };
+  }
+}
+function TourCard({
+  cardRef: ref,
+  step,
+  index,
+  position,
+  total,
+  labels,
+  isFirst,
+  isLast,
+  rect,
+  dir,
+  trap,
+  bodyId,
+  hintId,
+  locked,
+  gateHint,
+  onBack,
+  onNext,
+  onLeaveEmpty,
+  onSkip,
+  awaitsRelease,
+  docked,
+  refusal,
+  backTo
+}) {
+  const [style, setStyle] = useState({ opacity: 0 });
+  useFocusTrap(ref, { active: trap });
+  const edgeRef = useRef(null);
+  const [bandTick, setBandTick] = useState(0);
+  const [edge, setEdge] = useState(null);
+  useEffect(() => {
+    if (!docked) return;
+    let last = "";
+    const look = () => {
+      const target = step.target ? queryVisibleTarget(step.target) : null;
+      const band = readBand(target, ref.current);
+      const key = `${band.top}:${band.bottom}`;
+      if (key === last) return;
+      last = key;
+      if (target) {
+        const r = target.getBoundingClientRect();
+        if (r.top < band.top || r.bottom > band.bottom) {
+          edgeRef.current = scrollIntoFreeHalf(target, ref.current, edgeRef.current);
+        }
+      }
+      setBandTick((t) => t + 1);
+    };
+    const vv = window.visualViewport;
+    vv?.addEventListener("resize", look);
+    vv?.addEventListener("scroll", look);
+    window.addEventListener("resize", look);
+    const id = window.setInterval(look, 250);
+    return () => {
+      vv?.removeEventListener("resize", look);
+      vv?.removeEventListener("scroll", look);
+      window.removeEventListener("resize", look);
+      clearInterval(id);
+    };
+  }, [docked, step.target, ref]);
+  useLayoutEffect(() => {
+    const card = ref.current;
+    if (!card) return;
+    if (docked) {
+      const target = step.target ? queryVisibleTarget(step.target) : null;
+      const band = readBand(target, card);
+      const next = rect ? dockEdge(rect, band, edgeRef.current, card.offsetHeight) : "bottom";
+      edgeRef.current = next;
+      setEdge(next);
+      setStyle(dockStyle(next, rect, band));
+      return;
+    }
+    setEdge(null);
+    const view = viewportSize();
+    setStyle(placeCard(rect, card.offsetWidth, card.offsetHeight, view.width, view.height, 12, step.placement, dir));
+  }, [ref, rect, index, step.placement, step.target, dir, docked, bandTick]);
+  const awaitsTarget = (step.awaitClick || step.awaitInput) && step.target && rect || awaitsRelease;
+  return /* @__PURE__ */ jsxs(
+    "div",
+    {
+      ref,
+      tabIndex: -1,
+      style,
+      "data-tour-card": "",
+      "data-tour-docked": edge ?? void 0,
+      className: cn(
+        "pointer-events-auto fixed z-[61] w-80 max-w-[calc(100vw-1.5rem)] rounded-lg border border-subtle bg-surface p-4 shadow-xl outline-none transition-all duration-200 ease-out",
+        // Docked, the height is capped: the body scrolls, the title and buttons stay.
+        docked && "flex flex-col"
+      ),
+      children: [
+        /* @__PURE__ */ jsxs("div", { className: "flex flex-wrap items-center gap-x-2 gap-y-1 text-sm font-semibold text-primary", children: [
+          /* @__PURE__ */ jsx("span", { children: step.title }),
+          step.optional && /* @__PURE__ */ jsx("span", { className: "rounded-full border border-subtle px-1.5 py-px text-xs font-normal text-muted", children: labels.optional })
+        ] }),
+        /* @__PURE__ */ jsx(
+          "div",
+          {
+            id: bodyId,
+            className: cn("mt-1 text-sm leading-relaxed text-secondary", docked && "min-h-0 shrink overflow-y-auto"),
+            children: step.body
+          }
+        ),
+        step.action && /* @__PURE__ */ jsx("div", { className: "mt-3", children: step.action }),
+        /* @__PURE__ */ jsxs("div", { className: "mt-4 space-y-2", children: [
+          /* @__PURE__ */ jsxs("div", { className: "flex items-center justify-between gap-2", children: [
+            /* @__PURE__ */ jsx("button", { type: "button", onClick: onSkip, className: "text-xs text-placeholder hover:text-secondary", children: labels.skip }),
+            /* @__PURE__ */ jsxs("div", { className: "flex items-center gap-2", children: [
+              /* @__PURE__ */ jsx("span", { className: "whitespace-nowrap text-xs tabular-nums text-placeholder", children: labels.step(position, total) }),
+              !isFirst && /* @__PURE__ */ jsx(Button, { variant: "secondary", onClick: onBack, className: "px-2.5 py-1 text-xs", children: labels.back }),
+              step.optional && locked && !awaitsTarget && /* @__PURE__ */ jsx(Button, { variant: "secondary", onClick: onLeaveEmpty, className: "px-2.5 py-1 text-xs", children: labels.leaveEmpty }),
+              !awaitsTarget && /* @__PURE__ */ jsx(
+                Button,
+                {
+                  variant: "accent",
+                  onClick: onNext,
+                  "aria-disabled": locked || void 0,
+                  "aria-describedby": locked ? hintId : void 0,
+                  className: cn("px-2.5 py-1 text-xs", locked && "opacity-60"),
+                  children: isLast ? labels.done : labels.next
+                }
+              )
+            ] })
+          ] }),
+          awaitsTarget && /* @__PURE__ */ jsx("div", { className: "text-center text-xs italic text-placeholder", children: awaitsRelease ? step.awaitGateHint ?? labels.awaitGateHint : step.awaitInput && !step.awaitClick ? labels.awaitInputHint : labels.awaitClickHint }),
+          awaitsRelease && /* @__PURE__ */ jsxs("div", { "aria-live": "assertive", "aria-atomic": "true", className: "space-y-1", children: [
+            refusal && /* @__PURE__ */ jsxs("p", { "data-tour-refused": "", className: "text-xs text-danger", children: [
+              refusal.reason ?? labels.awaitGateRefused,
+              refusal.seq % 2 === 0 ? "\u200B" : ""
+            ] }),
+            refusal && backTo && /* @__PURE__ */ jsx(Button, { variant: "link", onClick: backTo.go, className: "text-xs", children: labels.backToStep(backTo.title) })
+          ] }),
+          locked && !awaitsTarget && /* @__PURE__ */ jsx("div", { id: hintId, className: "text-center text-xs italic text-placeholder", children: gateHint })
+        ] })
+      ]
+    }
+  );
+}
+export {
+  TourOverlay
+};
+//# sourceMappingURL=tour-overlay.js.map