@tent-official/react-walkthrough 1.4.1 → 1.5.0

package/README.md

@@ -118,8 +118,8 @@ Hook to register a walkthrough tour.
 | `skipLabel` | `string` | — | Override tour-level `skipLabel` for this step |
 | `displayStep` | `number` | — | Override the displayed step number for this step (display-only) |
 | `displayTotal` | `number` | — | Override the displayed total for this step (display-only) |
-| `forceRecompute` | `boolean` | — | When `true`, forces a DOM re-read before advancing to the next step. Useful when the next element is conditionally rendered and needs a layout update to appear |
 | `delayAfterNext` | `number` | `0` | Delay in ms after clicking "Next" (after `onStepNext` and `triggerElOnNext` have fired) before advancing to the next step. The overlay stays visible with the popover hidden during the delay |
+| `nextEl` | `string` | — | DOM element ID to look for after `delayAfterNext` completes. If found, advances to the step that owns it. If not found, skips to the next valid step. Supports `#id` or `id` format |
 
 ### `IStepDescription`
 

package/dist/index.d.mts

@@ -59,10 +59,10 @@ interface IWalkthroughStep {
     displayStep?: number;
     /** Override the displayed total step count for this specific step (display-only, does not affect logic). If omitted, uses the tour-level displayTotal or actual count */
     displayTotal?: number;
-    /** When true, forces a recompute of valid steps after advancing from this step. Useful when the next step's element is hidden/conditional and needs DOM changes to become visible. Default: false */
-    forceRecompute?: boolean;
     /** Delay in milliseconds after clicking "Next" (after onStepNext and triggerElOnNext have fired) before advancing to the next step. The overlay stays visible with the popover hidden during the delay. Default: 0 (no delay) */
     delayAfterNext?: number;
+    /** DOM element ID to look for after delayAfterNext completes. If the element is found in the DOM, the tour advances to the step that owns it. If not found, the step is skipped and the tour moves to the next valid step. Supports "#id" or "id" format. */
+    nextEl?: string;
 }
 /**
  * Options for the useWalkthrough hook.

package/dist/index.d.ts

@@ -59,10 +59,10 @@ interface IWalkthroughStep {
     displayStep?: number;
     /** Override the displayed total step count for this specific step (display-only, does not affect logic). If omitted, uses the tour-level displayTotal or actual count */
     displayTotal?: number;
-    /** When true, forces a recompute of valid steps after advancing from this step. Useful when the next step's element is hidden/conditional and needs DOM changes to become visible. Default: false */
-    forceRecompute?: boolean;
     /** Delay in milliseconds after clicking "Next" (after onStepNext and triggerElOnNext have fired) before advancing to the next step. The overlay stays visible with the popover hidden during the delay. Default: 0 (no delay) */
     delayAfterNext?: number;
+    /** DOM element ID to look for after delayAfterNext completes. If the element is found in the DOM, the tour advances to the step that owns it. If not found, the step is skipped and the tour moves to the next valid step. Supports "#id" or "id" format. */
+    nextEl?: string;
 }
 /**
  * Options for the useWalkthrough hook.

package/dist/index.js

@@ -967,43 +967,6 @@ var WalkthroughOverlay = ({
       setPopoverPos(null);
       const nextValidStep = validSteps[currentValidPos + 1];
       const nextOrigIdx = hasTrigger && !nextValidStep ? currentOrigIdx + 1 : (_a2 = nextValidStep == null ? void 0 : nextValidStep._originalIdx) != null ? _a2 : currentOrigIdx + 1;
-      const shouldForceRecompute = !!step.forceRecompute;
-      if (shouldForceRecompute) {
-        const nextStepDef = activeTour.steps[nextOrigIdx];
-        if (nextStepDef) {
-          const nextElId = resolveElId(nextStepDef.el);
-          const SETTLE_DELAY = 150;
-          const doAdvance = () => {
-            setGlobalState((s) => ({
-              ...s,
-              activeTour: { ...s.activeTour, currentStep: nextOrigIdx }
-            }));
-          };
-          const alreadyExists = document.getElementById(nextElId);
-          if (alreadyExists) {
-            setTimeout(() => doAdvance(), SETTLE_DELAY);
-          } else {
-            waitingForElsRef.current = true;
-            const observer = new MutationObserver(() => {
-              const found = document.getElementById(nextElId);
-              if (found) {
-                observer.disconnect();
-                waitingForElsRef.current = false;
-                setTimeout(() => doAdvance(), SETTLE_DELAY);
-              }
-            });
-            observer.observe(document.body, { childList: true, subtree: true });
-            setTimeout(() => {
-              observer.disconnect();
-              if (waitingForElsRef.current) {
-                waitingForElsRef.current = false;
-                doAdvance();
-              }
-            }, 3e3);
-          }
-          return;
-        }
-      }
       setGlobalState((s) => ({
         ...s,
         activeTour: { ...s.activeTour, currentStep: nextOrigIdx }
@@ -1019,6 +982,7 @@ var WalkthroughOverlay = ({
     }
     const hasTrigger = !!step.triggerElOnNext;
     const afterNextDelay = (_b2 = step.delayAfterNext) != null ? _b2 : 0;
+    const nextElId = step.nextEl ? resolveElId(step.nextEl) : null;
     const withDelay = (fn) => {
       if (afterNextDelay > 0) {
         setTimeout(fn, afterNextDelay);
@@ -1026,6 +990,39 @@ var WalkthroughOverlay = ({
         fn();
       }
     };
+    const advanceWithNextEl = () => {
+      const SETTLE_DELAY = 150;
+      const targetEl = document.getElementById(nextElId);
+      if (targetEl) {
+        const targetStepIdx = activeTour.steps.findIndex(
+          (s) => resolveElId(s.el) === nextElId
+        );
+        if (targetStepIdx !== -1) {
+          const targetStepDef = activeTour.steps[targetStepIdx];
+          const targetStepWithIdx = { ...targetStepDef, _originalIdx: targetStepIdx };
+          const alreadyInValid = validSteps.some((s) => s._originalIdx === targetStepIdx);
+          const newValidSteps = alreadyInValid ? validSteps : [...validSteps, targetStepWithIdx].sort((a, b) => a._originalIdx - b._originalIdx);
+          setValidSteps(newValidSteps);
+          skipNextRecomputeRef.current = true;
+          setTimeout(() => {
+            setGlobalState((s) => ({
+              ...s,
+              activeTour: { ...s.activeTour, currentStep: targetStepIdx }
+            }));
+          }, SETTLE_DELAY);
+          return;
+        }
+      }
+      const nextValid = validSteps.find((s) => s._originalIdx > currentOrigIdx);
+      if (nextValid) {
+        setGlobalState((s) => ({
+          ...s,
+          activeTour: { ...s.activeTour, currentStep: nextValid._originalIdx }
+        }));
+      } else {
+        completeTour();
+      }
+    };
     if (hasTrigger) {
       setPopoverHidden(true);
       setPopoverPos(null);
@@ -1037,32 +1034,33 @@ var WalkthroughOverlay = ({
         triggerTarget.dispatchEvent(new MouseEvent("mouseup", { bubbles: true, cancelable: true, button: 0 }));
         triggerTarget.click();
       }
-      const currentOrigIdx2 = validSteps[currentValidPos]._originalIdx;
-      const nextOrigIdx = currentOrigIdx2 + 1;
+      if (nextElId) {
+        withDelay(() => advanceWithNextEl());
+        return;
+      }
+      const nextOrigIdx = currentOrigIdx + 1;
       const nextStepDef = activeTour.steps[nextOrigIdx];
       if (nextStepDef) {
-        const nextElId = resolveElId(nextStepDef.el);
+        const nextStepElId = resolveElId(nextStepDef.el);
         const injectAndAdvance = () => {
           const nextStepWithIdx = { ...nextStepDef, _originalIdx: nextOrigIdx };
           const alreadyInValid = validSteps.some((s) => s._originalIdx === nextOrigIdx);
           const newValidSteps = alreadyInValid ? validSteps : [...validSteps, nextStepWithIdx].sort((a, b) => a._originalIdx - b._originalIdx);
           setValidSteps(newValidSteps);
-          if (!step.forceRecompute) {
-            skipNextRecomputeRef.current = true;
-          }
+          skipNextRecomputeRef.current = true;
           setGlobalState((s) => ({
             ...s,
             activeTour: { ...s.activeTour, currentStep: nextOrigIdx }
           }));
         };
         const SETTLE_DELAY = 150;
-        const alreadyExists = document.getElementById(nextElId);
+        const alreadyExists = document.getElementById(nextStepElId);
         if (alreadyExists) {
           withDelay(() => setTimeout(() => injectAndAdvance(), SETTLE_DELAY));
         } else {
           waitingForElsRef.current = true;
           const observer = new MutationObserver(() => {
-            const found = document.getElementById(nextElId);
+            const found = document.getElementById(nextStepElId);
             if (found) {
               observer.disconnect();
               waitingForElsRef.current = false;
@@ -1085,6 +1083,12 @@ var WalkthroughOverlay = ({
       setTimeout(() => completeTour(), 300);
       return;
     }
+    if (nextElId) {
+      setPopoverHidden(true);
+      setPopoverPos(null);
+      withDelay(() => advanceWithNextEl());
+      return;
+    }
     if (afterNextDelay > 0) {
       setPopoverHidden(true);
       setPopoverPos(null);