@tent-official/react-walkthrough 1.1.102 → 1.3.0

package/README.md

@@ -92,6 +92,7 @@ Hook to register a walkthrough tour.
 | `displayTotal` | `number` | — | Override the total step count displayed in the step counter (display-only, does not affect logic) |
 | `displayStepOffset` | `number` | `0` | Offset added to the displayed current step number (display-only, does not affect logic). e.g. `displayStepOffset: 3` with 3 real steps shows 4/total → 5/total → 6/total |
 | `isClearLastPositionOnEnd` | `boolean` | `false` | When `true`, clears the saved last highlight position when the tour ends. This prevents the next tour from animating its highlight from this tour's last position |
+| `onStepNext` | `Record<number, () => void>` | — | Callbacks fired when the user clicks "Next" on a specific step. The key is the original step index (0-based). Called right before advancing to the next step |
 
 **Returns:** `{ start: () => void }`
 
@@ -113,6 +114,9 @@ Hook to register a walkthrough tour.
 | `nextLabel` | `string` | — | Override tour-level `nextLabel` for this step |
 | `prevLabel` | `string` | — | Override tour-level `prevLabel` for this step |
 | `skipLabel` | `string` | — | Override tour-level `skipLabel` for this step |
+| `displayStep` | `number` | — | Override the displayed current step number for this step (display-only, does not affect logic) |
+| `displayTotal` | `number` | — | Override the displayed total step count for this step (display-only, does not affect logic) |
+| `forceRecompute` | `boolean` | `false` | 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 |
 
 ### `IStepDescription`
 
@@ -254,6 +258,45 @@ The popover automatically positions itself to stay within the viewport:
 
 The popover also waits for the target element to be scrolled into view before appearing.
 
+## Step-Level Callbacks (`onStepNext`)
+
+Use `onStepNext` to fire a custom function when the user clicks "Next" on a specific step. The key is the original step index (0-based):
+
+```jsx
+useWalkthrough({
+  name: "setup-tour",
+  steps: [
+    { el: "print-side", title: "Print Side", description: [{ description: "Select print side" }] },
+    { el: "print-system", title: "Print System", description: [{ description: "Select print system" }] },
+    { el: "print-color", title: "Print Color", description: [{ description: "Select color" }] },
+  ],
+  onStepNext: {
+    0: () => openPrintSystemDropdown(),   // fired when leaving step 0
+    1: () => fetchColorOptions(),          // fired when leaving step 1
+  },
+});
+```
+
+## Force Recompute (`forceRecompute`)
+
+When a step's next element is conditionally rendered (hidden until some action), use `forceRecompute` to wait for it to appear before advancing:
+
+```jsx
+steps: [
+  {
+    el: "print-side",
+    title: "Print Side",
+    forceRecompute: true, // wait for next element to appear after advancing
+    description: [{ description: "Select print side — the next section will appear after selection" }],
+  },
+  {
+    el: "print-system", // this element is hidden until print-side is selected
+    title: "Print System",
+    description: [{ description: "Now select the print system" }],
+  },
+]
+```
+
 ## License
 
 MIT

package/dist/index.d.mts

@@ -52,6 +52,12 @@ interface IWalkthroughStep {
     prevLabel?: string;
     /** Override tour-level skipLabel for this specific step. If omitted, uses the tour-level value */
     skipLabel?: string;
+    /** Override the displayed current step number for this specific step (display-only, does not affect logic). If omitted, uses the calculated value from tour-level settings */
+    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;
 }
 /**
  * Options for the useWalkthrough hook.
@@ -97,6 +103,8 @@ interface IUseWalkthroughOptions {
     displayStepOffset?: number;
     /** When true, clears the saved last highlight position when the tour ends. This prevents the next tour from animating its highlight FROM this tour's last position. Default: false */
     isClearLastPositionOnEnd?: boolean;
+    /** Callbacks fired when the user clicks "Next" on a specific step. The key is the original step index (0-based). Called right before advancing to the next step. Example: `onStepNext: { 0: () => openDropdown(), 2: () => fetchData() }` */
+    onStepNext?: Record<number, () => void>;
 }
 /**
  * Return value of the useWalkthrough hook.

package/dist/index.d.ts

@@ -52,6 +52,12 @@ interface IWalkthroughStep {
     prevLabel?: string;
     /** Override tour-level skipLabel for this specific step. If omitted, uses the tour-level value */
     skipLabel?: string;
+    /** Override the displayed current step number for this specific step (display-only, does not affect logic). If omitted, uses the calculated value from tour-level settings */
+    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;
 }
 /**
  * Options for the useWalkthrough hook.
@@ -97,6 +103,8 @@ interface IUseWalkthroughOptions {
     displayStepOffset?: number;
     /** When true, clears the saved last highlight position when the tour ends. This prevents the next tour from animating its highlight FROM this tour's last position. Default: false */
     isClearLastPositionOnEnd?: boolean;
+    /** Callbacks fired when the user clicks "Next" on a specific step. The key is the original step index (0-based). Called right before advancing to the next step. Example: `onStepNext: { 0: () => openDropdown(), 2: () => fetchData() }` */
+    onStepNext?: Record<number, () => void>;
 }
 /**
  * Return value of the useWalkthrough hook.

package/dist/index.js

@@ -222,11 +222,13 @@ var useWalkthrough = ({
   animationSpeed = 350,
   displayTotal,
   displayStepOffset,
-  isClearLastPositionOnEnd = false
+  isClearLastPositionOnEnd = false,
+  onStepNext
 }) => {
   const started = react.useRef(false);
   const onCompleteRef = react.useRef(onWalkthroughComplete);
   const handleWhenLastStepRef = react.useRef(handleWhenLastStep);
+  const onStepNextRef = react.useRef(onStepNext);
   const conditionMet = startWhenCondition === void 0 ? true : typeof startWhenCondition === "function" ? startWhenCondition() : !!startWhenCondition;
   react.useEffect(() => {
     onCompleteRef.current = onWalkthroughComplete;
@@ -234,6 +236,9 @@ var useWalkthrough = ({
   react.useEffect(() => {
     handleWhenLastStepRef.current = handleWhenLastStep;
   }, [handleWhenLastStep]);
+  react.useEffect(() => {
+    onStepNextRef.current = onStepNext;
+  }, [onStepNext]);
   const start = react.useCallback(() => {
     if (isDone(storageSuffix, name) || started.current) return;
     started.current = true;
@@ -257,7 +262,8 @@ var useWalkthrough = ({
         animationSpeed,
         displayTotal,
         displayStepOffset,
-        isClearLastPositionOnEnd
+        isClearLastPositionOnEnd,
+        onStepNext: onStepNextRef.current
       }
     });
   }, [
@@ -609,7 +615,7 @@ var WalkthroughOverlay = ({
   prevColor,
   skipColor
 } = {}) => {
-  var _a, _b, _c, _d, _e, _f, _g, _h, _i, _j, _k, _l, _m, _n;
+  var _a, _b, _c, _d, _e, _f, _g, _h, _i, _j, _k, _l, _m, _n, _o, _p;
   injectKeyframes();
   const { activeTour } = useGlobalState();
   const instanceIdRef = react.useRef(null);
@@ -911,9 +917,9 @@ var WalkthroughOverlay = ({
   const totalSteps = validSteps.length;
   const isLast = currentValidPos === totalSteps - 1;
   const stepOffset = (_c = activeTour.displayStepOffset) != null ? _c : 0;
-  const displayCurrentStep = currentValidPos + 1 + stepOffset;
-  const displayTotalSteps = (_d = activeTour.displayTotal) != null ? _d : totalSteps;
-  const borderRadius = (_e = step.borderRadius) != null ? _e : 10;
+  const displayCurrentStep = (_d = step.displayStep) != null ? _d : currentValidPos + 1 + stepOffset;
+  const displayTotalSteps = (_f = (_e = step.displayTotal) != null ? _e : activeTour.displayTotal) != null ? _f : totalSteps;
+  const borderRadius = (_g = step.borderRadius) != null ? _g : 10;
   const {
     isShowSkip = true,
     isShowPrev = true,
@@ -923,9 +929,9 @@ var WalkthroughOverlay = ({
     skipLabel: tourSkipLabel = "Skip",
     doneLabel = "Done"
   } = activeTour;
-  const nextLabel = (_f = step.nextLabel) != null ? _f : tourNextLabel;
-  const prevLabel = (_g = step.prevLabel) != null ? _g : tourPrevLabel;
-  const skipLabel = (_h = step.skipLabel) != null ? _h : tourSkipLabel;
+  const nextLabel = (_h = step.nextLabel) != null ? _h : tourNextLabel;
+  const prevLabel = (_i = step.prevLabel) != null ? _i : tourPrevLabel;
+  const skipLabel = (_j = step.skipLabel) != null ? _j : tourSkipLabel;
   const advanceStep = (hasTrigger) => {
     var _a2;
     const currentOrigIdx = validSteps[currentValidPos]._originalIdx;
@@ -939,6 +945,43 @@ 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 }
@@ -946,6 +989,12 @@ var WalkthroughOverlay = ({
     }
   };
   const next = () => {
+    var _a2;
+    const currentOrigIdx = validSteps[currentValidPos]._originalIdx;
+    const stepNextCb = (_a2 = activeTour.onStepNext) == null ? void 0 : _a2[currentOrigIdx];
+    if (typeof stepNextCb === "function") {
+      stepNextCb();
+    }
     const hasTrigger = !!step.triggerElOnNext;
     if (hasTrigger) {
       setPopoverHidden(true);
@@ -958,8 +1007,8 @@ var WalkthroughOverlay = ({
         triggerTarget.dispatchEvent(new MouseEvent("mouseup", { bubbles: true, cancelable: true, button: 0 }));
         triggerTarget.click();
       }
-      const currentOrigIdx = validSteps[currentValidPos]._originalIdx;
-      const nextOrigIdx = currentOrigIdx + 1;
+      const currentOrigIdx2 = validSteps[currentValidPos]._originalIdx;
+      const nextOrigIdx = currentOrigIdx2 + 1;
       const nextStepDef = activeTour.steps[nextOrigIdx];
       if (nextStepDef) {
         const nextElId = resolveElId(nextStepDef.el);
@@ -968,7 +1017,9 @@ var WalkthroughOverlay = ({
           const alreadyInValid = validSteps.some((s) => s._originalIdx === nextOrigIdx);
           const newValidSteps = alreadyInValid ? validSteps : [...validSteps, nextStepWithIdx].sort((a, b) => a._originalIdx - b._originalIdx);
           setValidSteps(newValidSteps);
-          skipNextRecomputeRef.current = true;
+          if (!step.forceRecompute) {
+            skipNextRecomputeRef.current = true;
+          }
           setGlobalState((s) => ({
             ...s,
             activeTour: { ...s.activeTour, currentStep: nextOrigIdx }
@@ -1043,10 +1094,10 @@ var WalkthroughOverlay = ({
     displayPosRef.current = currentValidPos;
   }
   const ds = displayStepRef.current;
-  const dir = (_i = popoverPos == null ? void 0 : popoverPos.dir) != null ? _i : "bottom";
-  const align = (_j = popoverPos == null ? void 0 : popoverPos.align) != null ? _j : "start";
-  const offsetX = (_k = popoverPos == null ? void 0 : popoverPos.offsetX) != null ? _k : 0;
-  const offsetY = (_l = popoverPos == null ? void 0 : popoverPos.offsetY) != null ? _l : 0;
+  const dir = (_k = popoverPos == null ? void 0 : popoverPos.dir) != null ? _k : "bottom";
+  const align = (_l = popoverPos == null ? void 0 : popoverPos.align) != null ? _l : "start";
+  const offsetX = (_m = popoverPos == null ? void 0 : popoverPos.offsetX) != null ? _m : 0;
+  const offsetY = (_n = popoverPos == null ? void 0 : popoverPos.offsetY) != null ? _n : 0;
   const anchorStyle = popoverReady ? {
     position: "fixed",
     top: rect.top,
@@ -1140,7 +1191,7 @@ var WalkthroughOverlay = ({
       /* @__PURE__ */ jsxRuntime.jsxs(PopoverBody, { children: [
         /* @__PURE__ */ jsxRuntime.jsxs("div", { style: { display: "flex", flexDirection: "row", justifyContent: "space-between" }, children: [
           pStep.title ? /* @__PURE__ */ jsxRuntime.jsx(PopoverTitle, { children: pStep.title }) : "",
-          ((_m = pStep.isShowStep) != null ? _m : pIsShowStep) && /* @__PURE__ */ jsxRuntime.jsxs("span", { style: { color: "#a1a1aa", fontSize: "12px", fontWeight: "400" }, children: [
+          ((_o = pStep.isShowStep) != null ? _o : pIsShowStep) && /* @__PURE__ */ jsxRuntime.jsxs("span", { style: { color: "#a1a1aa", fontSize: "12px", fontWeight: "400" }, children: [
             pDisplayCurrentStep,
             "/",
             pDisplayTotalSteps
@@ -1165,7 +1216,7 @@ var WalkthroughOverlay = ({
           }
         ) }),
         /* @__PURE__ */ jsxRuntime.jsxs(ButtonGroup, { children: [
-          ((_n = pStep.isShowPrev) != null ? _n : pIsShowPrev) && pCurrentValidPos > 0 && /* @__PURE__ */ jsxRuntime.jsx(
+          ((_p = pStep.isShowPrev) != null ? _p : pIsShowPrev) && pCurrentValidPos > 0 && /* @__PURE__ */ jsxRuntime.jsx(
             "button",
             {
               className: "wt-btn",