@eifi1/ui-kit 0.49.0 → 0.50.1

package/dist/tour/tour.js

@@ -5,19 +5,42 @@ import {
   useCallback,
   useContext,
   useEffect,
+  useId,
   useLayoutEffect,
+  useMemo,
   useRef,
-  useState
+  useState,
+  useSyncExternalStore
 } from "react";
 import { createPortal } from "react-dom";
 import { cn } from "../lib/cn.js";
 import { useKitLabels } from "../i18n/kit-labels.js";
 import { Button } from "../components/button.js";
 import { useFocusTrap } from "../hooks/use-focus-trap.js";
+import { useDismissLayer } from "../hooks/use-dismiss.js";
 import { sameRect } from "../hooks/use-anchored-rect.js";
 import { dirOf, horizontalStep } from "../lib/direction.js";
+import { isComposing } from "../lib/ime.js";
+import { focusQuietly } from "../lib/quiet-focus.js";
 import { DEFAULT_TOUR_LABELS } from "./tour-labels.js";
 import { completeStored, rememberAccount, rememberMigrate } from "./use-tour-progress.js";
+import { createGateRegistry, devWarnings, TourInternalContext } from "./tour-gates.js";
+import { liveEngine } from "./tour-engine.js";
+import { DOCK_MAX_WIDTH, dockEdge, dockStyle, readBand, scrollIntoFreeHalf } from "./tour-dock.js";
+import { useTourGate, useTourGateRelease } from "./tour-gates.js";
+const ENGINE_KEYS = [
+  "active",
+  "activeId",
+  "start",
+  "stop",
+  "next",
+  "prev",
+  "goToStep",
+  "index",
+  "total",
+  "position",
+  "count"
+];
 const TourContext = createContext(null);
 function useTour() {
   const ctx = useContext(TourContext);
@@ -27,25 +50,28 @@ function useTour() {
 function useTourOptional() {
   return useContext(TourContext);
 }
-function devWarnings() {
-  return Boolean(import.meta.env?.DEV) && !import.meta.env?.VITEST;
-}
 function TourProvider({
   children,
   labels,
   progress,
-  onComplete
+  onComplete,
+  launch,
+  dockOnPhones = true
 }) {
   const merged = useKitLabels("tour", DEFAULT_TOUR_LABELS, labels);
   const [steps, setSteps] = useState(null);
-  const [index, setIndex] = useState(0);
+  const [nav, setNav] = useState(NO_NAV);
+  const index = nav.index;
+  const [refusal, setRefusal] = useState(null);
   const [activeId, setActiveId] = useState(null);
   const optsRef = useRef({});
   const progressRef = useRef(progress);
   const onCompleteRef = useRef(onComplete);
+  const launchRef = useRef(launch);
   useLayoutEffect(() => {
     progressRef.current = progress;
     onCompleteRef.current = onComplete;
+    launchRef.current = launch;
   });
   const storageKey = progress?.storageKey;
   const migrate = progress?.migrate;
@@ -61,15 +87,89 @@ function TourProvider({
     stepsRef.current = steps;
     indexRef.current = index;
   }, [steps, index]);
+  const floorRef = useRef(0);
   const active = !!steps && steps.length > 0;
   const total = steps?.length ?? 0;
-  const start = useCallback((s, opts) => {
-    optsRef.current = opts ?? {};
-    optsRef.current.onStart?.();
-    setIndex(Math.min(Math.max(0, opts?.startIndex ?? 0), Math.max(0, s.length - 1)));
-    setActiveId(opts?.id ?? opts?.tour?.id ?? null);
-    setSteps(s);
-  }, []);
+  const [gates] = useState(createGateRegistry);
+  useLayoutEffect(() => {
+    gates.setActive(active);
+  }, [gates, active]);
+  const canLaunch = !!launch;
+  const internals = useMemo(() => ({ gates, canLaunch }), [gates, canLaunch]);
+  const shown = useCallback(
+    (s, i, via) => isShown(s[i], stepContext(gates, via)),
+    [gates]
+  );
+  const arrive = useCallback(
+    (s, i, via) => {
+      const ctx = stepContext(gates, via);
+      let position = 0;
+      let count = 0;
+      for (let j = floorRef.current; j < s.length; j++) {
+        if (j !== i && !isShown(s[j], ctx)) continue;
+        count++;
+        if (j <= i) position++;
+      }
+      indexRef.current = i;
+      setRefusal(null);
+      setNav({ index: i, floor: floorRef.current, via, position, count });
+    },
+    [gates]
+  );
+  const forward = useCallback(
+    (s, from, via) => {
+      for (let j = Math.max(from, floorRef.current); j < s.length; j++) if (shown(s, j, via)) return j;
+      return -1;
+    },
+    [shown]
+  );
+  const backward = useCallback(
+    (s, from, via) => {
+      for (let j = Math.min(from, s.length - 1); j >= floorRef.current; j--) if (shown(s, j, via)) return j;
+      return -1;
+    },
+    [shown]
+  );
+  const startSteps = useCallback(
+    (s, opts) => {
+      optsRef.current = opts ?? {};
+      optsRef.current.onStart?.();
+      const last = Math.max(0, s.length - 1);
+      floorRef.current = opts?.at === void 0 ? 0 : resolveAt(s, opts.at);
+      const via = opts?.at === void 0 ? "start" : "at";
+      const wanted = Math.min(Math.max(floorRef.current, opts?.startIndex ?? floorRef.current), last);
+      let to = forward(s, wanted, via);
+      if (to < 0) to = backward(s, wanted, via);
+      if (to < 0) return;
+      arrive(s, to, via);
+      setActiveId(opts?.id ?? opts?.tour?.id ?? null);
+      setSteps(s);
+    },
+    [arrive, forward, backward]
+  );
+  const ownStartRef = useRef(null);
+  const [live] = useState(() => liveEngine(ENGINE_KEYS));
+  const engine = live.engine;
+  const start = useCallback(
+    (what, opts) => {
+      if (typeof what !== "string") {
+        startSteps(what, opts);
+        return;
+      }
+      const run = launchRef.current;
+      if (!run) {
+        if (devWarnings()) console.warn(`[ui-kit] start("${what}") needs TourProvider's \`launch\` prop.`);
+        return;
+      }
+      void Promise.resolve(run(what, { at: opts?.at }, ownStartRef.current, engine)).catch(
+        (error) => console.error(error)
+      );
+    },
+    [startSteps, engine]
+  );
+  useLayoutEffect(() => {
+    ownStartRef.current = start;
+  }, [start]);
   const stop = useCallback(() => {
     setSteps(null);
     setActiveId(null);
@@ -103,34 +203,117 @@ function TourProvider({
     setSteps(null);
     setActiveId(null);
   }, []);
-  const goToStep = useCallback((i) => {
-    const len = stepsRef.current?.length ?? 0;
-    if (len === 0) return;
-    setIndex(Math.min(Math.max(0, i), len - 1));
-  }, []);
+  const goToStep = useCallback(
+    (i) => {
+      const s = stepsRef.current;
+      if (!s || s.length === 0) return;
+      const wanted = Math.min(Math.max(floorRef.current, i), s.length - 1);
+      let to = forward(s, wanted, "goto");
+      if (to < 0) to = backward(s, wanted, "goto");
+      if (to >= 0) arrive(s, to, "goto");
+    },
+    [arrive, forward, backward]
+  );
   const next = useCallback(() => {
-    const len = stepsRef.current?.length ?? 0;
-    if (len === 0) return;
-    if (indexRef.current >= len - 1) finish();
-    else setIndex(indexRef.current + 1);
-  }, [finish]);
+    const s = stepsRef.current;
+    if (!s || s.length === 0) return;
+    const to = forward(s, indexRef.current + 1, "next");
+    if (to < 0) finish();
+    else arrive(s, to, "next");
+  }, [arrive, forward, finish]);
   const prev = useCallback(() => {
-    if (indexRef.current > 0) setIndex(indexRef.current - 1);
-  }, []);
-  return /* @__PURE__ */ jsxs(TourContext.Provider, { value: { active, activeId, start, stop, next, prev, goToStep, index, total }, children: [
+    const s = stepsRef.current;
+    if (!s) return;
+    const to = backward(s, indexRef.current - 1, "back");
+    if (to >= 0) arrive(s, to, "back");
+  }, [arrive, backward]);
+  useEffect(() => {
+    if (!active) return;
+    let seq = 0;
+    return gates.listen((signal) => {
+      const s = stepsRef.current;
+      if (!s) return;
+      const i = indexRef.current;
+      if (signal.kind === "refuse") {
+        if (s[i]?.awaitGate === signal.key) setRefusal({ step: s[i], reason: signal.reason, seq: ++seq });
+        return;
+      }
+      const awaiting = s[i]?.awaitGate === signal.key ? i : s.findIndex((st, k) => k > i && st.awaitGate === signal.key);
+      if (awaiting < 0) return;
+      const to = forward(s, awaiting + 1, "next");
+      if (to < 0) finish();
+      else arrive(s, to, "next");
+    });
+  }, [active, gates, arrive, forward, finish]);
+  const value = {
+    active,
+    activeId,
+    start,
+    stop,
+    next,
+    prev,
+    goToStep,
+    index,
+    total,
+    position: active ? nav.position : 0,
+    count: active ? nav.count : 0
+  };
+  useLayoutEffect(() => {
+    live.set(value);
+  });
+  return /* @__PURE__ */ jsx(TourInternalContext.Provider, { value: internals, children: /* @__PURE__ */ jsxs(TourContext.Provider, { value, children: [
     children,
     active && /* @__PURE__ */ jsx(
       TourOverlay,
       {
         steps,
         index,
+        via: nav.via,
+        floor: nav.floor,
+        position: nav.position,
+        count: nav.count,
+        refusal: refusal?.step === steps[index] ? refusal : null,
+        onGoTo: goToStep,
         labels: merged,
+        gates,
+        dockOnPhones,
         onNext: next,
         onPrev: prev,
         onSkip: skip
       }
     )
-  ] });
+  ] }) });
+}
+const NO_NAV = { index: 0, floor: 0, via: "start", position: 0, count: 0 };
+const NOOP = () => {
+};
+function stepContext(gates, via) {
+  return { gate: (key) => gates.get(key), via };
+}
+function resolveAt(steps, at) {
+  if (typeof at === "number") return Math.min(Math.max(0, Math.floor(at)), Math.max(0, steps.length - 1));
+  const anchor = `data-tour="${at}"`;
+  const found = steps.findIndex((step) => step.target?.includes(anchor));
+  if (found >= 0) return found;
+  if (devWarnings()) console.warn(`[ui-kit] A tour was started at "${at}", but no step targets [${anchor}]: it starts at 0.`);
+  return 0;
+}
+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 isShown(step, ctx) {
+  if (!step.when) return true;
+  try {
+    return step.when(ctx) === true;
+  } catch (error) {
+    console.error(error);
+    return false;
+  }
 }
 function isVisible(el) {
   const r = el.getBoundingClientRect();
@@ -149,29 +332,142 @@ 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 top = vv?.offsetTop ?? 0;
+  const bottom = top + (vv?.height ?? window.innerHeight);
+  const width = vv?.width ?? window.innerWidth;
+  return r.width > 0 && r.left <= 1 && r.top <= top + 1 && r.right >= width - 1 && r.bottom >= bottom - 1;
+}
+function docks(step, dockOnPhones) {
+  if (typeof window === "undefined" || window.innerWidth >= DOCK_MAX_WIDTH || !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 firstFocusable(el) {
+  if (el instanceof HTMLElement && el.matches(FOCUSABLE_CONTROL)) return el;
+  return el.querySelector(FOCUSABLE_CONTROL);
+}
+function tabStops(el) {
+  const all = el.matches(FOCUSABLE_CONTROL) ? [el] : [];
+  return all.concat(
+    Array.from(el.querySelectorAll(FOCUSABLE_CONTROL)).filter(
+      (x) => x.tabIndex >= 0 && !x.closest("[hidden],[inert]")
+    )
+  );
+}
+const FOCUSABLE_CONTROL = 'a[href],button:not([disabled]),textarea:not([disabled]),input:not([disabled]),select:not([disabled]),[tabindex]:not([tabindex="-1"])';
+function coarsePointer() {
+  return typeof window !== "undefined" && typeof window.matchMedia === "function" ? window.matchMedia("(pointer: coarse)").matches : false;
+}
 function TourOverlay({
   steps,
   index,
+  via,
+  floor,
+  position,
+  count,
+  refusal,
+  onGoTo,
   labels,
+  gates,
+  dockOnPhones,
   onNext,
   onPrev,
   onSkip
 }) {
   const step = steps[index];
-  const isFirst = index === 0;
-  const isLast = index === steps.length - 1;
+  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 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) => setLocated({ index, step, rect: el ? rectOf(el) : null, dir: dirOf(el) });
+    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 () => {
-      await step.beforeStep?.();
+      await step.beforeStep?.(stepContext(gates, via));
       if (cancelled) return;
       if (!step.target) {
         settle(null);
@@ -182,7 +478,8 @@ function TourOverlay({
         if (cancelled) return;
         const el = queryVisibleTarget(step.target);
         if (el) {
-          el.scrollIntoView({ block: "center", behavior: "smooth" });
+          if (docks(step, dockOnPhones)) scrollIntoFreeHalf(el, null, null);
+          else el.scrollIntoView({ block: "center", behavior: "smooth" });
           settle(el);
           return;
         }
@@ -201,10 +498,15 @@ function TourOverlay({
     const update = () => {
       const el = queryVisibleTarget(step.target);
       if (el) {
-        const next = rectOf(el);
-        setLocated(
-          (prev) => prev && prev.index === index && prev.step === step && !sameRect(prev.rect, next) ? { ...prev, rect: next } : prev
-        );
+        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);
@@ -216,6 +518,23 @@ function TourOverlay({
       clearInterval(id);
     };
   }, [index, step]);
+  const layer = located?.layer ?? null;
+  useEffect(() => {
+    if (!layer) return;
+    return () => layer.remove();
+  }, [layer]);
+  useDismissLayer(
+    ready,
+    (e) => {
+      if (fieldStepNow && 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;
@@ -225,7 +544,112 @@ function TourOverlay({
     el.addEventListener("click", onClick, { once: true });
     return () => el.removeEventListener("click", onClick);
   }, [ready, spotted, index, step, onNext]);
-  const interactive = spotted && !!step.target && !!(step.interactive || step.awaitInput);
+  const interactive = spotted && !!step.target && !!(step.interactive || step.awaitInput || step.gate || step.awaitGate);
+  const guided = interactive && !!(step.gate || step.awaitInput || step.awaitGate);
+  const fieldStepNow = interactive;
+  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 ? firstFocusable(el) : null;
+    const previous = control ? control.getAttribute("aria-describedby") : null;
+    if (control) control.setAttribute("aria-describedby", previous ? `${previous} ${bodyId}` : bodyId);
+    if (coarsePointer() || !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);
@@ -259,34 +683,44 @@ function TourOverlay({
       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 ? firstFocusable(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") {
-        onSkip();
+        if (!ready) onSkip();
         return;
       }
       if (e.key === "Enter") {
         if (step.awaitClick || step.awaitInput || ownsKey(e.target, "Enter")) return;
         e.preventDefault();
-        onNext();
+        tryNext();
         return;
       }
       if (ownsKey(e.target, e.key)) return;
       const delta = horizontalStep(e.key, rootRef.current);
       if (delta === 1) {
         e.preventDefault();
-        onNext();
+        tryNext();
       } else if (delta === -1) {
         if (!isFirst) onPrev();
       }
     };
     document.addEventListener("keydown", onKey);
     return () => document.removeEventListener("keydown", onKey);
-  }, [isFirst, step, interactive, onNext, onPrev, onSkip]);
+  }, [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(
@@ -294,15 +728,16 @@ function TourOverlay({
       "div",
       {
         ref: rootRef,
-        className: cn("pointer-events-none fixed inset-0", interactive ? "z-[45]" : "z-[60]"),
+        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 && /* @__PURE__ */ jsx(SpotlightShields, { spot }),
+          spot && !bare && /* @__PURE__ */ jsx(SpotlightShields, { spot }),
           spot ? /* @__PURE__ */ jsx(
             "div",
             {
@@ -330,7 +765,7 @@ function TourOverlay({
                   "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)",
-                  "0 0 0 9999px rgba(15,23,42,0.70)"
+                  ...bare ? [] : ["0 0 0 9999px rgba(15,23,42,0.70)"]
                 ].join(", ")
               }
             }
@@ -338,23 +773,36 @@ function TourOverlay({
           /* @__PURE__ */ jsx(
             TourCard,
             {
+              cardRef,
               step,
               index,
-              total: steps.length,
+              position,
+              total: count,
               labels,
               isFirst,
               isLast,
               rect: spot,
               dir,
+              trap: !guided,
+              bodyId,
+              hintId,
+              locked,
+              gateHint,
               onBack: onPrev,
-              onNext,
-              onSkip
+              onNext: tryNext,
+              onLeaveEmpty: onNext,
+              onSkip,
+              awaitsRelease,
+              docked: spot !== null && docks(step, dockOnPhones),
+              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 })
         ]
       }
     ),
-    document.body
+    interactive && current?.layer || document.body
   );
 }
 function fieldValues(el) {
@@ -433,38 +881,108 @@ function placeCard(rect, cw, ch, vw, vh, m, placement, dir = "ltr") {
   }
 }
 function TourCard({
+  cardRef: ref,
   step,
   index,
+  position,
   total,
   labels,
   isFirst,
   isLast,
   rect,
   dir,
+  trap,
+  bodyId,
+  hintId,
+  locked,
+  gateHint,
   onBack,
   onNext,
-  onSkip
+  onLeaveEmpty,
+  onSkip,
+  awaitsRelease,
+  docked,
+  refusal,
+  backTo
 }) {
-  const ref = useRef(null);
   const [style, setStyle] = useState({ opacity: 0 });
-  useFocusTrap(ref, { active: true });
+  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);
     setStyle(
       placeCard(rect, card.offsetWidth, card.offsetHeight, window.innerWidth, window.innerHeight, 12, step.placement, dir)
     );
-  }, [rect, index, 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,
-      className: "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",
+      "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__ */ jsx("div", { className: "text-sm font-semibold text-primary", children: step.title }),
-        /* @__PURE__ */ jsx("div", { className: "mt-1 text-sm leading-relaxed text-secondary", children: step.body }),
+        /* @__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: [
@@ -478,12 +996,31 @@ function TourCard({
               }
             ),
             /* @__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(index + 1, total) }),
+              /* @__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.awaitClick || step.awaitInput) && step.target && rect) && /* @__PURE__ */ jsx(Button, { variant: "accent", onClick: onNext, className: cn("px-2.5 py-1 text-xs"), children: isLast ? labels.done : labels.next })
+              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
+                }
+              )
             ] })
           ] }),
-          (step.awaitClick || step.awaitInput) && step.target && rect && /* @__PURE__ */ jsx("div", { className: "text-center text-xs italic text-placeholder", children: step.awaitInput && !step.awaitClick ? labels.awaitInputHint : labels.awaitClickHint })
+          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 })
         ] })
       ]
     }
@@ -493,6 +1030,8 @@ export {
   DEFAULT_TOUR_LABELS,
   TourProvider,
   useTour,
+  useTourGate,
+  useTourGateRelease,
   useTourOptional
 };
 //# sourceMappingURL=tour.js.map