@tent-official/react-walkthrough 1.1.51 → 1.1.53

package/README.md

@@ -83,9 +83,6 @@ Hook to register a walkthrough tour.
 | `skipLabel` | `string` | `"Skip"` | Skip button label (can be overridden per step) |
 | `delay` | `number` | `0` | Delay in ms before highlighting the first step. During delay, a dark overlay is shown |
 | `doneLabel` | `string` | `"Done"` | Done button label (last step) |
-| `animationSpeed` | `number` | `350` | Base animation speed (ms). Used to calculate scroll-wait duration. Lower = faster, higher = slower |
-| `manualTotal` | `number` | — | Override the displayed total step count (cosmetic only, does not affect logic) |
-| `initialStep` | `number` | `0` | Offset added to the displayed current step number (cosmetic only). e.g. `initialStep: 3` makes step 1 display as "4/total" |
 
 **Returns:** `{ start: () => void }`
 
@@ -126,6 +123,7 @@ Place this component once at the root of your app. It renders via React Portal i
 | `$popoverBorderRadius` | `number` | `8` | Border radius of popover (px) |
 | `$popoverGap` | `number` | `12` | Gap between highlight and popover (px) |
 | `$popoverMinWidth` | `number` | `275` | Minimum width of the popover (px) |
+| `$animationSpeed` | `number` | `350` | Base animation speed (ms). Actual duration is calculated from distance — shorter distance = faster, longer distance = slower. Lower value = faster overall, higher = slower overall |
 | `nextColor` | `string` | `"#000"` | Custom next button color |
 | `prevColor` | `string` | — | Custom previous button color |
 | `skipColor` | `string` | — | Custom skip button color |

package/dist/index.d.mts

@@ -40,8 +40,8 @@ interface IWalkthroughStep {
     width?: number | string;
     /** Popover height (px or "auto"). Default: auto */
     height?: number | string;
-    /** If true, clicking "Next" will also trigger a click on the target element */
-    isTriggerEl?: boolean;
+    /** When set, clicking "Next" will trigger a click on an element. If a string (element ID), clicks that element; if true, clicks the step's own target element */
+    isTriggerEl?: string | boolean;
     /** Override tour-level isShowPrev for this specific step. If omitted, uses the tour-level value */
     isShowPrev?: boolean;
     /** Override tour-level isShowStep for this specific step. If omitted, uses the tour-level value */
@@ -87,9 +87,9 @@ interface IUseWalkthroughOptions {
     containerElement?: string;
     /** Base animation speed (ms) used to calculate transition duration from distance. Default: 350 */
     animationSpeed?: number;
-    /** Override the displayed total step count (cosmetic only, does not affect logic). If omitted, uses the actual number of valid steps */
+    /** Override the total step count displayed in the step counter (display-only, does not affect logic). If omitted, uses the actual number of valid steps */
     manualTotal?: number;
-    /** Offset added to the displayed current step number (cosmetic only, does not affect logic). Default: 0. For example, if initialStep is 3, step 1 displays as "4/total" */
+    /** Offset added to the displayed current step number (display-only, does not affect logic). Default: 0. e.g. initialStep: 3 with 3 real steps shows 3/total → 4/total → 5/total */
     initialStep?: number;
 }
 /**

package/dist/index.d.ts

@@ -40,8 +40,8 @@ interface IWalkthroughStep {
     width?: number | string;
     /** Popover height (px or "auto"). Default: auto */
     height?: number | string;
-    /** If true, clicking "Next" will also trigger a click on the target element */
-    isTriggerEl?: boolean;
+    /** When set, clicking "Next" will trigger a click on an element. If a string (element ID), clicks that element; if true, clicks the step's own target element */
+    isTriggerEl?: string | boolean;
     /** Override tour-level isShowPrev for this specific step. If omitted, uses the tour-level value */
     isShowPrev?: boolean;
     /** Override tour-level isShowStep for this specific step. If omitted, uses the tour-level value */
@@ -87,9 +87,9 @@ interface IUseWalkthroughOptions {
     containerElement?: string;
     /** Base animation speed (ms) used to calculate transition duration from distance. Default: 350 */
     animationSpeed?: number;
-    /** Override the displayed total step count (cosmetic only, does not affect logic). If omitted, uses the actual number of valid steps */
+    /** Override the total step count displayed in the step counter (display-only, does not affect logic). If omitted, uses the actual number of valid steps */
     manualTotal?: number;
-    /** Offset added to the displayed current step number (cosmetic only, does not affect logic). Default: 0. For example, if initialStep is 3, step 1 displays as "4/total" */
+    /** Offset added to the displayed current step number (display-only, does not affect logic). Default: 0. e.g. initialStep: 3 with 3 real steps shows 3/total → 4/total → 5/total */
     initialStep?: number;
 }
 /**

package/dist/index.js

@@ -62,6 +62,12 @@ var resetWalkthrough = ({ storageSuffix = "", walkthroughList = [] } = {}) => {
   notify();
   window.dispatchEvent(new Event("walkthrough-done"));
 };
+var easeOutCubic = (t) => {
+  return 1 - Math.pow(1 - t, 3);
+};
+var lerp = (a, b, t) => {
+  return a + (b - a) * t;
+};
 var STYLE_ID = "wt-keyframes";
 var injectKeyframes = () => {
   if (typeof document === "undefined") return;
@@ -242,6 +248,15 @@ var useWalkthrough = ({
   }, [name, storageSuffix, dependsOn, start]);
   return { start };
 };
+var calcTransitionMs = (from, to, baseMs) => {
+  const dx = to.left + to.width / 2 - (from.left + from.width / 2);
+  const dy = to.top + to.height / 2 - (from.top + from.height / 2);
+  const dist = Math.sqrt(dx * dx + dy * dy);
+  const diagonal = Math.sqrt(window.innerWidth ** 2 + window.innerHeight ** 2);
+  const ratio = Math.min(dist / diagonal, 1);
+  const minMs = baseMs * 0.5;
+  return Math.round(minMs + ratio * baseMs);
+};
 var waitForScrollEnd = (container, timeoutMs = 400) => {
   return new Promise((resolve) => {
     let resolved = false;
@@ -271,7 +286,6 @@ var useAnimatedRect = (step, baseMs = 350, containerElement, isTourActive = true
   const scrollingRef = react.useRef(false);
   const cleanupRef = react.useRef(null);
   const prevTourNameRef = react.useRef(null);
-  const lastRectRef = react.useRef(null);
   react.useEffect(() => {
     let cancelled = false;
     if (tourName && tourName !== prevTourNameRef.current) {
@@ -289,9 +303,6 @@ var useAnimatedRect = (step, baseMs = 350, containerElement, isTourActive = true
         targetRef.current = null;
         currentRef.current = null;
       }
-      setDisplayRect(null);
-      currentRef.current = null;
-      targetRef.current = null;
       setIsAnimating(false);
       scrollingRef.current = false;
       return;
@@ -314,13 +325,50 @@ var useAnimatedRect = (step, baseMs = 350, containerElement, isTourActive = true
         height: r.height + padding * 2
       };
     };
-    const placeRect = (newTarget) => {
+    const startAnimation = (newTarget) => {
       if (cancelled) return;
       targetRef.current = newTarget;
-      currentRef.current = newTarget;
-      lastRectRef.current = newTarget;
-      setDisplayRect(newTarget);
-      setIsAnimating(false);
+      if (!currentRef.current) {
+        currentRef.current = newTarget;
+        setDisplayRect(newTarget);
+        setIsAnimating(false);
+        return;
+      }
+      const from = { ...currentRef.current };
+      const to = newTarget;
+      const duration = calcTransitionMs(from, to, baseMs);
+      const startTime = performance.now();
+      setIsAnimating(true);
+      const tick = (now) => {
+        if (cancelled) return;
+        const elapsed = now - startTime;
+        const progress = Math.min(elapsed / duration, 1);
+        const eased = easeOutCubic(progress);
+        const interpolated = {
+          top: lerp(from.top, to.top, eased),
+          left: lerp(from.left, to.left, eased),
+          width: lerp(from.width, to.width, eased),
+          height: lerp(from.height, to.height, eased)
+        };
+        currentRef.current = interpolated;
+        setDisplayRect(interpolated);
+        if (progress < 1) {
+          rafRef.current = requestAnimationFrame(tick);
+        } else {
+          currentRef.current = to;
+          setDisplayRect(to);
+          setIsAnimating(false);
+        }
+      };
+      rafRef.current = requestAnimationFrame(tick);
+    };
+    const shrinkHighlight = () => {
+      if (!currentRef.current) return;
+      const cur = currentRef.current;
+      const centerX = cur.left + cur.width / 2;
+      const centerY = cur.top + cur.height / 2;
+      const shrunkRect = { top: centerY, left: centerX, width: 0, height: 0 };
+      startAnimation(shrunkRect);
     };
     const runForElement = (el2) => {
       if (cancelled) return;
@@ -330,7 +378,6 @@ var useAnimatedRect = (step, baseMs = 350, containerElement, isTourActive = true
         const updated = compute();
         targetRef.current = updated;
         currentRef.current = updated;
-        lastRectRef.current = updated;
         setDisplayRect(updated);
       };
       setIsAnimating(true);
@@ -340,12 +387,12 @@ var useAnimatedRect = (step, baseMs = 350, containerElement, isTourActive = true
         waitForScrollEnd(containerEl, baseMs + 150).then(() => {
           scrollingRef.current = false;
           if (cancelled) return;
-          placeRect(compute());
+          startAnimation(compute());
         });
       } else {
         requestAnimationFrame(() => {
           if (cancelled) return;
-          placeRect(compute());
+          startAnimation(compute());
         });
       }
       window.addEventListener("resize", onLayout);
@@ -362,7 +409,7 @@ var useAnimatedRect = (step, baseMs = 350, containerElement, isTourActive = true
       runForElement(el);
     } else {
       setIsAnimating(true);
-      setDisplayRect(null);
+      shrinkHighlight();
       const observer = new MutationObserver(() => {
         const found = document.getElementById(resolveElId(step.el));
         if (found) {
@@ -380,7 +427,7 @@ var useAnimatedRect = (step, baseMs = 350, containerElement, isTourActive = true
       if (cleanupRef.current) cleanupRef.current();
     };
   }, [step, containerElement, isTourActive, tourName]);
-  return { rect: displayRect, isAnimating, lastRect: lastRectRef.current };
+  return { rect: displayRect, isAnimating };
 };
 var clampSize = (value, max) => {
   if (value === "auto" || value === void 0) return "auto";
@@ -468,7 +515,7 @@ var WalkthroughOverlay = ({
   prevColor,
   skipColor
 } = {}) => {
-  var _a, _b, _c, _d, _e, _f, _g, _h, _i;
+  var _a, _b, _c, _d, _e, _f, _g, _h, _i, _j, _k;
   injectKeyframes();
   const { activeTour } = useGlobalState();
   const instanceIdRef = react.useRef(null);
@@ -489,6 +536,7 @@ var WalkthroughOverlay = ({
   const nextBtnRef = react.useRef(null);
   const popoverRef = react.useRef(null);
   const [popoverPos, setPopoverPos] = react.useState(null);
+  const popoverShownRef = react.useRef(false);
   const [validSteps, setValidSteps] = react.useState([]);
   const waitingForElsRef = react.useRef(false);
   react.useEffect(() => {
@@ -532,6 +580,7 @@ var WalkthroughOverlay = ({
     if (!activeTour) {
       delayDoneForRef.current = null;
       setIsDelaying(false);
+      popoverShownRef.current = false;
       return;
     }
     if (delayDoneForRef.current === activeTour.name) return;
@@ -548,16 +597,15 @@ var WalkthroughOverlay = ({
     return () => clearTimeout(timer);
   }, [currentTourName, activeTour]);
   const step = isDelaying ? null : rawStep;
-  const animationSpeed = (_c = activeTour == null ? void 0 : activeTour.animationSpeed) != null ? _c : 350;
-  const { rect, isAnimating, lastRect } = useAnimatedRect(step, animationSpeed, activeTour == null ? void 0 : activeTour.containerElement, !!activeTour, activeTour == null ? void 0 : activeTour.name);
+  const tourAnimationSpeed = (_c = activeTour == null ? void 0 : activeTour.animationSpeed) != null ? _c : 350;
+  const { rect, isAnimating } = useAnimatedRect(step, tourAnimationSpeed, activeTour == null ? void 0 : activeTour.containerElement, !!activeTour, activeTour == null ? void 0 : activeTour.name);
   const completeTour = react.useCallback(() => {
     if (!activeTour) return;
     const { storageSuffix: sk, name: n, onWalkthroughComplete: cb } = activeTour;
-    const savedRect = rect || lastRect;
-    setGlobalState({ activeTour: null, lastRect: savedRect ? { ...savedRect } : null });
+    setGlobalState({ activeTour: null, lastRect: rect ? { ...rect } : null });
     markDone(sk, n);
     if (cb) cb(n);
-  }, [activeTour, rect, lastRect]);
+  }, [activeTour, rect]);
   react.useEffect(() => {
     if (!activeTour) return;
     if (currentValidPos !== -1) return;
@@ -615,16 +663,6 @@ var WalkthroughOverlay = ({
       nextBtnRef.current.focus();
     }
   }, [activeTour == null ? void 0 : activeTour.currentStep, popoverPos]);
-  const [contentKey, setContentKey] = react.useState(0);
-  const prevStepRef = react.useRef(null);
-  react.useEffect(() => {
-    var _a2;
-    const idx = (_a2 = activeTour == null ? void 0 : activeTour.currentStep) != null ? _a2 : null;
-    if (idx !== prevStepRef.current) {
-      setContentKey((k) => k + 1);
-      prevStepRef.current = idx;
-    }
-  }, [activeTour == null ? void 0 : activeTour.currentStep]);
   if (!activeTour) return null;
   if (_activeOverlayId !== null && _activeOverlayId !== instanceIdRef.current) {
     return null;
@@ -694,7 +732,10 @@ var WalkthroughOverlay = ({
   }
   const totalSteps = validSteps.length;
   const isLast = currentValidPos === totalSteps - 1;
-  const borderRadius = (_d = step.borderRadius) != null ? _d : 10;
+  const displayInitialStep = (_d = activeTour.initialStep) != null ? _d : 0;
+  const displayCurrentStep = currentValidPos + 1 + displayInitialStep;
+  const displayTotalSteps = (_e = activeTour.manualTotal) != null ? _e : totalSteps;
+  const borderRadius = (_f = step.borderRadius) != null ? _f : 10;
   const {
     isShowSkip = true,
     isShowPrev = true,
@@ -702,19 +743,15 @@ var WalkthroughOverlay = ({
     nextLabel: tourNextLabel = "Next",
     prevLabel: tourPrevLabel = "Back",
     skipLabel: tourSkipLabel = "Skip",
-    doneLabel = "Done",
-    manualTotal,
-    initialStep: tourInitialStep
+    doneLabel = "Done"
   } = activeTour;
-  const displayTotal = manualTotal != null ? manualTotal : totalSteps;
-  const displayCurrentStep = (tourInitialStep != null ? tourInitialStep : 0) + currentValidPos + 1;
-  const nextLabel = (_e = step.nextLabel) != null ? _e : tourNextLabel;
-  const prevLabel = (_f = step.prevLabel) != null ? _f : tourPrevLabel;
-  const skipLabel = (_g = step.skipLabel) != null ? _g : tourSkipLabel;
+  const nextLabel = (_g = step.nextLabel) != null ? _g : tourNextLabel;
+  const prevLabel = (_h = step.prevLabel) != null ? _h : tourPrevLabel;
+  const skipLabel = (_i = step.skipLabel) != null ? _i : tourSkipLabel;
   const next = () => {
     if (step.isTriggerEl) {
-      const el = document.getElementById(resolveElId(step.el));
-      if (el) el.click();
+      const triggerTarget = typeof step.isTriggerEl === "string" ? document.getElementById(resolveElId(step.isTriggerEl)) : document.getElementById(resolveElId(step.el));
+      if (triggerTarget) triggerTarget.click();
     }
     if (isLast) {
       completeTour();
@@ -741,6 +778,10 @@ var WalkthroughOverlay = ({
   const popoverWidth = clampSize(step.width, window.innerWidth);
   const popoverHeight = step.height ? clampSize(step.height, window.innerHeight) : void 0;
   const popoverReady = popoverPos && !isAnimating;
+  const shouldAnimatePopover = popoverReady && !popoverShownRef.current;
+  if (popoverReady && !popoverShownRef.current) {
+    popoverShownRef.current = true;
+  }
   const popoverStyle = popoverReady ? {
     top: popoverPos.top,
     left: popoverPos.left,
@@ -748,7 +789,8 @@ var WalkthroughOverlay = ({
     minWidth: $popoverMinWidth,
     padding: $popoverPadding,
     borderRadius: $popoverBorderRadius,
-    fontFamily: "inherit"
+    fontFamily: "inherit",
+    ...shouldAnimatePopover ? {} : { animation: "none" }
   } : {
     position: "fixed",
     top: -9999,
@@ -795,10 +837,10 @@ var WalkthroughOverlay = ({
       /* @__PURE__ */ jsxRuntime.jsxs(PopoverBody, { children: [
         /* @__PURE__ */ jsxRuntime.jsxs("div", { style: { display: "flex", flexDirection: "row", justifyContent: "space-between" }, children: [
           step.title ? /* @__PURE__ */ jsxRuntime.jsx(PopoverTitle, { children: step.title }) : "",
-          ((_h = step.isShowStep) != null ? _h : isShowStep) && /* @__PURE__ */ jsxRuntime.jsxs("span", { style: { color: "#a1a1aa", fontSize: "12px", fontWeight: "400" }, children: [
+          ((_j = step.isShowStep) != null ? _j : isShowStep) && /* @__PURE__ */ jsxRuntime.jsxs("span", { style: { color: "#a1a1aa", fontSize: "12px", fontWeight: "400" }, children: [
             displayCurrentStep,
             "/",
-            displayTotal
+            displayTotalSteps
           ] })
         ] }),
         /* @__PURE__ */ jsxRuntime.jsx(DescriptionScrollArea, { $height: popoverHeight, children: Array.isArray(step.description) && step.description.map((d, i) => /* @__PURE__ */ jsxRuntime.jsxs(DescriptionBlock, { $direction: d.direction, children: [
@@ -808,7 +850,7 @@ var WalkthroughOverlay = ({
           ] }),
           /* @__PURE__ */ jsxRuntime.jsx("span", { style: { whiteSpace: "pre-line" }, children: d.description })
         ] }, i)) })
-      ] }, contentKey),
+      ] }),
       /* @__PURE__ */ jsxRuntime.jsxs(PopoverFooter, { children: [
         /* @__PURE__ */ jsxRuntime.jsx(StepCounter, { children: isShowSkip && /* @__PURE__ */ jsxRuntime.jsx(
           "button",
@@ -820,7 +862,7 @@ var WalkthroughOverlay = ({
           }
         ) }),
         /* @__PURE__ */ jsxRuntime.jsxs(ButtonGroup, { children: [
-          ((_i = step.isShowPrev) != null ? _i : isShowPrev) && currentValidPos > 0 && /* @__PURE__ */ jsxRuntime.jsx(
+          ((_k = step.isShowPrev) != null ? _k : isShowPrev) && currentValidPos > 0 && /* @__PURE__ */ jsxRuntime.jsx(
             "button",
             {
               className: "wt-btn",