@glowhop/core-tour 1.0.2 → 1.2.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @glowhop/core-tour
 
+## 1.2.0
+
+### Minor Changes
+
+- 3058e3d: When a step's target is removed from the DOM while its step is showing, the tour now freezes the presentation in place for a short grace period and resumes on the target without a re-entrance animation if it reconnects, instead of immediately unmounting and replaying the appear animation. When the target reappears somewhere else, the cutout is animated to its new box rather than snapping, unless the step opts out of animation. Interaction with the underlying page stays blocked during the freeze even when `allowInteraction` is `true`. If the target doesn't come back within the grace period, `missingTargetStrategy` and `targetTimeout` apply exactly as before — the grace period counts against `targetTimeout` rather than extending it. Under `wait` the presentation stays frozen and the tour stays `active` for the whole budget, so the popover's buttons keep working instead of going dead behind a `transitioning` status.
+
+## 1.1.0
+
+### Minor Changes
+
+- 165797b: `allowScroll` now defaults to `true`: the page stays scrollable while a tour runs. Pass `allowScroll: false` to keep the previous scroll-lock behaviour.
+
 ## 1.0.2
 
 ### Patch Changes

package/dom/tour-view-driver.d.ts

@@ -17,6 +17,15 @@ export interface TourViewCommands {
 export interface TourViewDriver<T> {
     show(step: ActiveStep<T>, direction: TourDirection, signal: AbortSignal, onBeforePopoverAppear?: () => void | Promise<void>): Promise<void> | void;
     clear(signal: AbortSignal): Promise<void> | void;
+    /**
+     * Resumes a frozen presentation on `step.target` after its previous target
+     * reconnected or was replaced, without unmounting or replaying `appear()`.
+     * A no-op when the driver isn't frozen for this step — callers only invoke
+     * it in response to a `targetDisconnected` notification they are recovering
+     * from, so a stale or superseded call should be silently ignored rather
+     * than throw.
+     */
+    retarget(step: ActiveStep<T>, signal: AbortSignal): Promise<void> | void;
     dispose(): void;
     releaseMount?(): void;
     setCommands?(commands: TourViewCommands): void;
@@ -24,6 +33,7 @@ export interface TourViewDriver<T> {
 export declare class NoopTourViewDriver<T> implements TourViewDriver<T> {
     show(_step: ActiveStep<T>, _direction: TourDirection, _signal: AbortSignal, onBeforePopoverAppear?: () => void | Promise<void>): void | Promise<void> | undefined;
     clear(_signal: AbortSignal): void;
+    retarget(_step: ActiveStep<T>, _signal: AbortSignal): void;
     dispose(): void;
     releaseMount(): void;
 }
@@ -32,6 +42,7 @@ export declare class DomTourViewDriver<T> implements TourViewDriver<T> {
     private readonly scrollLock;
     private readonly modalToken;
     private readonly stepCleanups;
+    private readonly targetCleanups;
     private commands;
     private direction;
     private currentStep;
@@ -39,6 +50,16 @@ export declare class DomTourViewDriver<T> implements TourViewDriver<T> {
     private disposed;
     private generation;
     private active;
+    /**
+     * True while the presentation is held in place on a lost target: the
+     * reposition loop is stopped and interaction is force-blocked, but overlay,
+     * popover and pointer stay mounted at their last known position instead of
+     * disappearing. Cleared by `retarget()` (target came back) or `clear()`
+     * (the caller gave up and is tearing the presentation down).
+     */
+    private frozen;
+    private activeTarget;
+    private targetFocusedAtFreeze;
     private lastTargetRect;
     private lastViewport;
     private inertBranches;
@@ -72,6 +93,13 @@ export declare class DomTourViewDriver<T> implements TourViewDriver<T> {
     private restoreInertBranches;
     private appear;
     private attachStepResources;
+    /**
+     * Binds the step's custom event handlers to its target element. Split out
+     * from `attachStepResources` so a lost-then-recovered target can be
+     * rebound on its own by `retarget()`, without re-subscribing the
+     * step-level resources (props, capabilities, controls) that never left.
+     */
+    private attachTargetResources;
     private listen;
     private schedulePosition;
     private updatePosition;
@@ -100,8 +128,50 @@ export declare class DomTourViewDriver<T> implements TourViewDriver<T> {
     private isLiveDisabled;
     private isPointerEnabled;
     private cleanupStepResources;
+    private cleanupTargetResources;
     private isCurrentTargetAvailable;
-    private stopForDisconnectedTarget;
+    /**
+     * Holds the presentation exactly where it is when its target disappears,
+     * instead of tearing it down: overlay, popover and pointer stay mounted at
+     * their last known rect, focus guard and scroll lock stay engaged, and only
+     * the target's own listeners (now pointing at a dead node) are removed.
+     * The generation is deliberately left untouched — popover buttons, the
+     * keyboard shortcuts and any pending capability/focus bookkeeping must
+     * keep working while frozen, since the popover is the user's escape hatch
+     * out of a tour whose target never comes back. `commands.targetDisconnected`
+     * drives the actual recovery (grace period, then the configured strategy)
+     * and eventually calls back into `retarget()` or `clear()`.
+     */
+    private freezeForDisconnectedTarget;
+    /**
+     * Blocks (or restores) interaction with the underlying page independently
+     * of `step.behavior.allowInteraction`. Used to force interaction off while
+     * frozen — the cutout no longer corresponds to anything after a reflow, so
+     * it must not let clicks through even on a step that normally allows them —
+     * and to restore the step's own setting once retargeted.
+     */
+    private applyInteractionLock;
+    private isFocusInsideTarget;
+    /**
+     * Resumes a presentation frozen by `freezeForDisconnectedTarget` on its new
+     * target: reattaches the target-bound listeners, restores the step's own
+     * interaction setting, and lets the existing reposition loop tween overlay
+     * and popover to the new rect on the next frame. Deliberately skips
+     * `appear()` (no re-entrance animation) and `activateFocus()` (focus stays
+     * where the user left it), only reclaiming it if it was on the target that
+     * just disappeared.
+     */
+    retarget(step: ActiveStep<T>, signal: AbortSignal): Promise<void>;
+    /**
+     * Walks the presentation from where it froze to the new target's box. The
+     * per-frame loop can't do this on its own: it only tweens the cutout when
+     * the step's own visuals changed, and a target that reappears elsewhere is
+     * a pure geometry jump, which would snap. `animateTo` and the popover's
+     * reposition both fall back to an instant move when the step isn't
+     * animated, so this respects `animated: false` and reduced motion without
+     * asking about them.
+     */
+    private moveToRetargetedRect;
     private beginGeneration;
     private cancelAnimationsOnAbort;
     private cancelElementAnimations;

package/index.js

@@ -1904,6 +1904,7 @@ class DomTourViewDriver {
   scrollLock = new ScrollLock;
   modalToken = {};
   stepCleanups = [];
+  targetCleanups = [];
   commands;
   direction = "advance";
   currentStep = null;
@@ -1911,6 +1912,9 @@ class DomTourViewDriver {
   disposed = false;
   generation = 0;
   active = false;
+  frozen = false;
+  activeTarget = null;
+  targetFocusedAtFreeze = false;
   lastTargetRect = null;
   lastViewport = null;
   inertBranches = [];
@@ -1987,6 +1991,9 @@ class DomTourViewDriver {
       this.cleanupStepResources();
       this.throwIfStale(generation, signal);
       this.active = false;
+      this.frozen = false;
+      this.activeTarget = null;
+      this.targetFocusedAtFreeze = false;
       this.currentStep = step;
       this.currentSignal = signal;
       this.direction = direction;
@@ -2004,6 +2011,7 @@ class DomTourViewDriver {
       const target = step.target;
       if (!target)
         return;
+      this.activeTarget = target;
       this.syncModality(step.behavior?.allowInteraction === true);
       await this.scrollTargetIntoView(step, target, signal);
       this.throwIfStale(generation, signal);
@@ -2042,6 +2050,9 @@ class DomTourViewDriver {
       this.scrollLock.deactivate();
       this.throwIfStale(generation, signal);
       this.active = false;
+      this.frozen = false;
+      this.activeTarget = null;
+      this.targetFocusedAtFreeze = false;
       this.currentStep = null;
       this.currentSignal = null;
       this.lastTargetRect = null;
@@ -2066,6 +2077,9 @@ class DomTourViewDriver {
     this.focusGuard.deactivate();
     this.scrollLock.deactivate();
     this.active = false;
+    this.frozen = false;
+    this.activeTarget = null;
+    this.targetFocusedAtFreeze = false;
     this.currentStep = null;
     this.currentSignal = null;
     this.overlay?.release();
@@ -2084,7 +2098,7 @@ class DomTourViewDriver {
     this.commands = null;
   }
   refreshRegisteredElements() {
-    if (!this.active || !this.currentStep || !this.lastTargetRect)
+    if (!this.active || this.frozen || !this.currentStep || !this.lastTargetRect)
       return;
     const generation = this.beginGeneration();
     this.cleanupStepResources();
@@ -2101,6 +2115,7 @@ class DomTourViewDriver {
     const signal = this.currentSignal;
     if (this.disposed || !step || !target || !targetRect || !signal)
       return;
+    this.activeTarget = target;
     this.initializeElements(step);
     await this.appear(targetRect, step);
     this.throwIfStale(generation);
@@ -2212,6 +2227,26 @@ class DomTourViewDriver {
       if (active)
         this.flushPendingKeyboardCommand(step, generation);
     }) ?? (() => {}));
+    this.attachTargetResources(step, target, generation, signal);
+    const currentWindow = this.getWindow(target);
+    if (typeof currentWindow?.addEventListener === "function") {
+      this.listen(currentWindow, "keydown", (event) => {
+        if (this.isCurrentGeneration(generation))
+          this.handleKeydown(event);
+      });
+      this.listen(currentWindow, "click", (event) => {
+        if (this.isCurrentGeneration(generation) && this.activeTarget) {
+          this.handleOverlayClick(event, step, this.activeTarget);
+        }
+      });
+    }
+    this.attachButtonHandlers(step);
+    this.observeControls(step, generation);
+    this.syncControlState(step);
+    this.syncShortcutLabels(step);
+    this.schedulePosition(generation);
+  }
+  attachTargetResources(step, target, generation, signal) {
     for (const handler of step.definition.eventHandlers) {
       const listener = (event) => {
         if (!this.isCurrentGeneration(generation))
@@ -2230,32 +2265,15 @@ class DomTourViewDriver {
           return this.commands?.reportError(error);
         });
       };
-      this.listen(target, handler.event, listener);
+      this.listen(target, handler.event, listener, undefined, this.targetCleanups);
     }
-    const currentWindow = this.getWindow(target);
-    if (typeof currentWindow?.addEventListener === "function") {
-      this.listen(currentWindow, "keydown", (event) => {
-        if (this.isCurrentGeneration(generation))
-          this.handleKeydown(event);
-      });
-      this.listen(currentWindow, "click", (event) => {
-        if (this.isCurrentGeneration(generation)) {
-          this.handleOverlayClick(event, step, target);
-        }
-      });
-    }
-    this.attachButtonHandlers(step);
-    this.observeControls(step, generation);
-    this.syncControlState(step);
-    this.syncShortcutLabels(step);
-    this.schedulePosition(generation);
   }
-  listen(target, type, listener, options) {
+  listen(target, type, listener, options, bucket = this.stepCleanups) {
     target.addEventListener(type, listener, options);
-    this.stepCleanups.push(() => target.removeEventListener(type, listener, options));
+    bucket.push(() => target.removeEventListener(type, listener, options));
   }
   schedulePosition(generation = this.generation) {
-    if (!this.isCurrentGeneration(generation) || !this.currentStep || this.rafId !== null)
+    if (!this.isCurrentGeneration(generation) || !this.currentStep || this.rafId !== null || this.frozen)
       return;
     const owner = this.currentStep.target?.ownerDocument?.defaultView;
     const ownerRequest = owner?.requestAnimationFrame;
@@ -2282,7 +2300,7 @@ class DomTourViewDriver {
     if (!this.isCurrentGeneration(generation) || !step || !target)
       return;
     if (!this.isCurrentTargetAvailable(target)) {
-      this.stopForDisconnectedTarget(target, generation);
+      this.freezeForDisconnectedTarget(step, target, generation);
       return;
     }
     const targetRect = target.getBoundingClientRect();
@@ -2589,30 +2607,94 @@ class DomTourViewDriver {
       this.rafCancel?.(this.rafId);
     this.rafId = null;
     this.rafCancel = null;
+    this.cleanupTargetResources();
     for (const cleanup of this.stepCleanups.splice(0))
       cleanup();
   }
+  cleanupTargetResources() {
+    for (const cleanup of this.targetCleanups.splice(0))
+      cleanup();
+  }
   isCurrentTargetAvailable(target) {
     const rootDocument = this.root?.ownerDocument;
     return target.isConnected && (!rootDocument || target.ownerDocument === rootDocument);
   }
-  stopForDisconnectedTarget(target, generation) {
-    if (!this.isCurrentGeneration(generation))
+  freezeForDisconnectedTarget(step, target, generation) {
+    if (!this.isCurrentGeneration(generation) || this.frozen)
       return;
-    this.beginGeneration();
-    this.cleanupStepResources();
-    this.releaseModality();
-    this.focusGuard.deactivate();
-    this.scrollLock.deactivate();
-    this.active = false;
-    this.currentSignal = null;
-    this.currentStep = null;
-    this.lastTargetRect = null;
-    this.lastViewport = null;
+    this.frozen = true;
+    if (this.rafId !== null)
+      this.rafCancel?.(this.rafId);
+    this.rafId = null;
+    this.rafCancel = null;
+    this.targetFocusedAtFreeze = this.isFocusInsideTarget(target);
+    this.cleanupTargetResources();
+    this.applyInteractionLock(step, true);
     Promise.resolve(this.commands?.targetDisconnected(target)).catch((error) => {
       this.commands?.reportError(error).catch(() => {});
     });
   }
+  applyInteractionLock(step, locked) {
+    const allowed = !locked && step.behavior?.allowInteraction === true;
+    this.overlay?.setInteractionAllowed(allowed);
+    this.syncModality(allowed);
+    const popover = this.popover?.getElement();
+    if (isHTMLElement(popover, this.root ?? popover)) {
+      if (allowed)
+        popover.removeAttribute("aria-modal");
+      else
+        popover.setAttribute("aria-modal", "true");
+    }
+  }
+  isFocusInsideTarget(target) {
+    const activeElement = target.ownerDocument?.activeElement;
+    if (!activeElement)
+      return false;
+    return activeElement === target || target.contains(activeElement);
+  }
+  async retarget(step, signal) {
+    this.throwIfAborted(signal);
+    if (this.disposed || !this.frozen || this.currentStep !== step)
+      return;
+    const target = step.target;
+    if (!target)
+      return;
+    this.frozen = false;
+    this.currentSignal = signal;
+    this.activeTarget = target;
+    this.applyInteractionLock(step, false);
+    this.attachTargetResources(step, target, this.generation, signal);
+    const popover = this.popover?.getElement();
+    if (isHTMLElement(popover, this.root ?? popover)) {
+      this.focusGuard.update({
+        allowedTarget: target,
+        allowTargetInteraction: step.behavior?.allowInteraction === true,
+        direction: this.direction,
+        fallback: this.root ?? popover.parentElement,
+        popover
+      });
+    }
+    if (this.targetFocusedAtFreeze) {
+      this.targetFocusedAtFreeze = false;
+      if (step.behavior?.allowInteraction === true)
+        target.focus();
+    }
+    this.syncControlState(step);
+    this.syncShortcutLabels(step);
+    this.moveToRetargetedRect(step, target);
+    this.schedulePosition(this.generation);
+  }
+  moveToRetargetedRect(step, target) {
+    const generation = this.generation;
+    const targetRect = target.getBoundingClientRect();
+    this.observeDynamicOperation(this.overlay?.animateTo(targetRect, step), generation);
+    const placement = this.popover?.updatePosition(targetRect, step, (reposition) => this.observeDynamicOperation(reposition, generation));
+    if (this.isPointerEnabled(step)) {
+      this.observeDynamicOperation(this.pointer?.moveToTarget(targetRect, step, true, placement), generation);
+    }
+    this.lastTargetRect = snapshotRect(targetRect);
+    this.lastViewport = snapshotViewport(target);
+  }
   beginGeneration() {
     this.generation += 1;
     this.pendingKeyboardCommand = null;
@@ -2983,7 +3065,7 @@ class ActiveStep {
     this.props = createStepPropsStore(this.initialProps, reportSubscriberError, path);
     this.behavior = mergeStepBehavior(defaults.behavior, definition.behavior);
     this.animated = defaults.animated;
-    this.allowScroll = defaults.allowScroll === true;
+    this.allowScroll = defaults.allowScroll !== false;
   }
   reset() {
     this.props.set(this.initialProps);
@@ -3305,6 +3387,7 @@ function prefixReservations(document2) {
 
 // packages/core/src/runtime/tour-controller.ts
 var DEFAULT_TARGET_TIMEOUT = 3000;
+var TARGET_LOSS_GRACE_MS = 150;
 var DISPOSED_ERROR_MESSAGE = "Tour controller is disposed";
 function resolveStartIndex(workflow, startAt) {
   if (startAt === undefined)
@@ -3335,6 +3418,7 @@ class TourController {
   direction = "advance";
   status = "idle";
   error = null;
+  recoveringTarget = null;
   operationToken = 0;
   publicationRevision = 0;
   operation = null;
@@ -3617,34 +3701,63 @@ class TourController {
       this.assertCurrent(operation);
     }
   }
+  async pollForTarget(step, operation, budgetMs) {
+    const startedAt = Date.now();
+    while (true) {
+      const target = await step.resolveTarget(this.signalFor(operation));
+      this.assertCurrent(operation);
+      if (target)
+        return target;
+      if (Date.now() - startedAt >= budgetMs)
+        return null;
+      await abortableDelay(16, this.signalFor(operation));
+      this.assertCurrent(operation);
+    }
+  }
   async recoverDisconnectedTarget(target) {
-    if (this.disposed || this.status !== "active")
+    if (this.disposed || this.status !== "active" || this.recoveringTarget === target)
       return;
     const step = this.currentStep();
     if (!step || step.target !== target)
       return;
+    this.recoveringTarget = target;
     const index = this.index;
     const direction = this.direction;
     const operation = this.beginOperation();
     try {
-      this.setStatus("transitioning");
       this.assertCurrent(operation);
-      await this.driver.clear(this.signalFor(operation));
+      const recoveredDuringGrace = await this.pollForTarget(step, operation, TARGET_LOSS_GRACE_MS);
       this.assertCurrent(operation);
-      const recoveredTarget = await this.resolveTarget(step, operation);
-      this.assertCurrent(operation);
-      if (!recoveredTarget) {
+      if (recoveredDuringGrace) {
+        step.target = recoveredDuringGrace;
+        await this.driver.retarget(step, this.signalFor(operation));
+        this.assertCurrent(operation);
+        this.publish();
+        return;
+      }
+      const strategy = step.behavior?.missingTargetStrategy ?? "error";
+      if (strategy === "skip") {
         await this.advancePastRecoveryMissingTarget(step, index, direction, operation);
         return;
       }
-      step.target = recoveredTarget;
-      await this.driver.show(step, direction, this.signalFor(operation));
+      if (strategy !== "wait")
+        throw this.missingTargetError(step);
+      const timeout = step.behavior?.targetTimeout ?? DEFAULT_TARGET_TIMEOUT;
+      const recoveredAfterWait = await this.pollForTarget(step, operation, Math.max(0, timeout - TARGET_LOSS_GRACE_MS));
       this.assertCurrent(operation);
-      this.setStatus("active");
+      if (!recoveredAfterWait)
+        throw this.missingTargetError(step);
+      step.target = recoveredAfterWait;
+      await this.driver.retarget(step, this.signalFor(operation));
+      this.assertCurrent(operation);
+      this.publish();
     } catch (error) {
       try {
         await this.handleFailure(error, operation);
       } catch {}
+    } finally {
+      if (this.recoveringTarget === target)
+        this.recoveringTarget = null;
     }
   }
   async advancePastMissingTarget(index, direction, operation) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@glowhop/core-tour",
-  "version": "1.0.2",
+  "version": "1.2.0",
   "description": "Framework-agnostic tour controller and DOM runtime for GlowTour.js.",
   "license": "MIT",
   "homepage": "https://github.com/Glowhop/GlowTour.js#readme",

package/runtime/tour-controller.d.ts

@@ -2,6 +2,16 @@ import { WorkflowBuilder } from "../builder";
 import type { WorkflowDefinition } from "../definition";
 import { type TourViewDriver } from "../dom/tour-view-driver";
 import type { GlowTour, GlowTourOptions, RunOptions, StartOptions, TourEventSource, TourState } from "../types";
+/**
+ * How long a step stays frozen on its last known position after its target
+ * disappears from the DOM, before the configured `missingTargetStrategy`
+ * takes over. Covers the dominant case — a framework remounting the target
+ * within a frame or two — without a visible unmount/remount flicker. Not
+ * configurable: it is a presentation detail of the recovery, not a policy
+ * choice; `missingTargetStrategy` and `targetTimeout` remain the only knobs.
+ * Exported for the test suite's timing assertions only.
+ */
+export declare const TARGET_LOSS_GRACE_MS = 150;
 interface TourControllerOptions<T> extends GlowTourOptions {
     assertCanRun?: (workflow: WorkflowDefinition<T>) => Document | void;
     onDispose?: () => void;
@@ -17,6 +27,14 @@ export declare class TourController<T> {
     private direction;
     private status;
     private error;
+    /**
+     * The target currently being recovered from a disconnect, if any. The
+     * public status stays "active" through the grace period (see
+     * TARGET_LOSS_GRACE_MS), so it can no longer serve as the re-entrancy guard
+     * a repeated or overlapping `targetDisconnected` notification for the same
+     * target relies on — this field takes over that job instead.
+     */
+    private recoveringTarget;
     private operationToken;
     private publicationRevision;
     private operation;
@@ -49,6 +67,29 @@ export declare class TourController<T> {
     private transition;
     private runActions;
     private resolveTarget;
+    /**
+     * Repeatedly re-resolves `step.target` until it succeeds or `budgetMs`
+     * elapses, polling every 16ms like `resolveTarget`. Unlike `resolveTarget`
+     * it never applies `missingTargetStrategy` itself — callers decide what a
+     * timed-out budget means (grace period vs. a "wait" strategy's own
+     * timeout), so the same polling loop serves both.
+     */
+    private pollForTarget;
+    /**
+     * Recovers from a target disconnecting while its step is on screen. The
+     * driver has already frozen the presentation in place (overlay, popover,
+     * pointer held at their last position; focus guard and scroll lock still
+     * engaged) and stopped polling geometry — this only decides how long to
+     * keep it frozen and what to do once that budget runs out.
+     *
+     * The public status stays "active" for the whole freeze, "wait" included.
+     * A frozen presentation isn't a transition: nothing is animating, the step
+     * and its index are unchanged, and the popover is still on screen. Calling
+     * it "transitioning" would close `canNavigate` and leave the user staring
+     * at a live-looking popover whose buttons are dead for the rest of the
+     * budget — the popover is the escape hatch out of a target that never
+     * comes back, so it has to keep working.
+     */
     private recoverDisconnectedTarget;
     private advancePastMissingTarget;
     private advancePastRecoveryMissingTarget;

package/types/index.d.ts

@@ -186,10 +186,10 @@ export interface StartOptions<T> {
     /** Allow users to cancel the tour. @default true */
     cancellable?: boolean;
     /**
-     * Locks page scroll while the tour is active, restoring it on finish,
-     * cancel, error, or dispose.
+     * Leaves page scroll available while the tour is active. Set `false` to lock
+     * scroll instead, restoring it on finish, cancel, error, or dispose.
      *
-     * @default false
+     * @default true
      */
     allowScroll?: boolean;
     /** Default overlay options for all steps. */