@tent-official/react-walkthrough 1.1.77 → 1.1.79

package/dist/index.d.mts

@@ -127,10 +127,24 @@ interface IResetWalkthroughOptions {
     /** List of walkthrough names to reset */
     walkthroughList?: string[];
 }
+/**
+ * Options for the readElement function.
+ */
+interface IReadElementOptions {
+    /** Optional AbortSignal to cancel waiting for the element */
+    signal?: AbortSignal;
+}
 /**
  * Reset specified walkthroughs so they can be replayed without page refresh.
  */
 declare function resetWalkthrough(options?: IResetWalkthroughOptions): void;
+/**
+ * Read (find) a DOM element by its ID.
+ * Returns immediately if the element already exists in the DOM.
+ * If not found, uses a MutationObserver to wait until it appears.
+ * Supports cancellation via AbortSignal.
+ */
+declare function readElement(elementId: string, options?: IReadElementOptions): Promise<HTMLElement | null>;
 /**
  * Hook to register and control a walkthrough tour.
  */
@@ -141,4 +155,4 @@ declare function useWalkthrough(options: IUseWalkthroughOptions): IUseWalkthroug
  */
 declare function WalkthroughOverlay(props?: IWalkthroughOverlayProps): ReactPortal | null;
 
-export { type IResetWalkthroughOptions, type IStepDescription, type IUseWalkthroughOptions, type IUseWalkthroughReturn, type IWalkthroughOverlayProps, type IWalkthroughStep, type TDescriptionDirection, type TPopoverPosition, WalkthroughOverlay, resetWalkthrough, useWalkthrough };
+export { type IReadElementOptions, type IResetWalkthroughOptions, type IStepDescription, type IUseWalkthroughOptions, type IUseWalkthroughReturn, type IWalkthroughOverlayProps, type IWalkthroughStep, type TDescriptionDirection, type TPopoverPosition, WalkthroughOverlay, readElement, resetWalkthrough, useWalkthrough };

package/dist/index.d.ts

@@ -127,10 +127,24 @@ interface IResetWalkthroughOptions {
     /** List of walkthrough names to reset */
     walkthroughList?: string[];
 }
+/**
+ * Options for the readElement function.
+ */
+interface IReadElementOptions {
+    /** Optional AbortSignal to cancel waiting for the element */
+    signal?: AbortSignal;
+}
 /**
  * Reset specified walkthroughs so they can be replayed without page refresh.
  */
 declare function resetWalkthrough(options?: IResetWalkthroughOptions): void;
+/**
+ * Read (find) a DOM element by its ID.
+ * Returns immediately if the element already exists in the DOM.
+ * If not found, uses a MutationObserver to wait until it appears.
+ * Supports cancellation via AbortSignal.
+ */
+declare function readElement(elementId: string, options?: IReadElementOptions): Promise<HTMLElement | null>;
 /**
  * Hook to register and control a walkthrough tour.
  */
@@ -141,4 +155,4 @@ declare function useWalkthrough(options: IUseWalkthroughOptions): IUseWalkthroug
  */
 declare function WalkthroughOverlay(props?: IWalkthroughOverlayProps): ReactPortal | null;
 
-export { type IResetWalkthroughOptions, type IStepDescription, type IUseWalkthroughOptions, type IUseWalkthroughReturn, type IWalkthroughOverlayProps, type IWalkthroughStep, type TDescriptionDirection, type TPopoverPosition, WalkthroughOverlay, resetWalkthrough, useWalkthrough };
+export { type IReadElementOptions, type IResetWalkthroughOptions, type IStepDescription, type IUseWalkthroughOptions, type IUseWalkthroughReturn, type IWalkthroughOverlayProps, type IWalkthroughStep, type TDescriptionDirection, type TPopoverPosition, WalkthroughOverlay, readElement, resetWalkthrough, useWalkthrough };

package/dist/index.js

@@ -68,6 +68,36 @@ var easeOutCubic = (t) => {
 var lerp = (a, b, t) => {
   return a + (b - a) * t;
 };
+var resolveElId = (id) => typeof id === "string" && id.startsWith("#") ? id.slice(1) : id;
+var readElement = (elementId, { signal } = {}) => {
+  return new Promise((resolve) => {
+    if (signal == null ? void 0 : signal.aborted) {
+      resolve(null);
+      return;
+    }
+    const id = resolveElId(elementId);
+    const el = document.getElementById(id);
+    if (el) {
+      resolve(el);
+      return;
+    }
+    const observer = new MutationObserver(() => {
+      const found = document.getElementById(id);
+      if (found) {
+        observer.disconnect();
+        resolve(found);
+      }
+    });
+    observer.observe(document.body, { childList: true, subtree: true });
+    if (signal) {
+      const onAbort = () => {
+        observer.disconnect();
+        resolve(null);
+      };
+      signal.addEventListener("abort", onAbort, { once: true });
+    }
+  });
+};
 var STYLE_ID = "wt-keyframes";
 var injectKeyframes = () => {
   if (typeof document === "undefined") return;
@@ -166,7 +196,6 @@ var StepCounter = react.forwardRef(({ style, children, ...props }, ref) => /* @_
   ...style
 }, ...props, children }));
 var ButtonGroup = react.forwardRef(({ style, children, ...props }, ref) => /* @__PURE__ */ jsxRuntime.jsx("div", { ref, style: { display: "flex", gap: 6, ...style }, ...props, children }));
-var resolveElId = (id) => typeof id === "string" && id.startsWith("#") ? id.slice(1) : id;
 var _overlayInstanceCounter = 0;
 var _activeOverlayId = null;
 var useWalkthrough = ({
@@ -562,16 +591,42 @@ var WalkthroughOverlay = ({
   const [popoverHidden, setPopoverHidden] = react.useState(false);
   const displayStepRef = react.useRef(null);
   const displayPosRef = react.useRef(null);
+  const delayDoneForRef = react.useRef(null);
+  const [isDelaying, setIsDelaying] = react.useState(false);
+  const currentTourName = (_a = activeTour == null ? void 0 : activeTour.name) != null ? _a : null;
+  react.useEffect(() => {
+    var _a2;
+    if (!activeTour) {
+      delayDoneForRef.current = null;
+      setIsDelaying(false);
+      return;
+    }
+    if (delayDoneForRef.current === activeTour.name) return;
+    const ms = (_a2 = activeTour.delay) != null ? _a2 : 0;
+    if (ms <= 0) {
+      delayDoneForRef.current = activeTour.name;
+      return;
+    }
+    setIsDelaying(true);
+    const timer = setTimeout(() => {
+      delayDoneForRef.current = activeTour.name;
+      setIsDelaying(false);
+    }, ms);
+    return () => clearTimeout(timer);
+  }, [currentTourName, activeTour]);
   const [validSteps, setValidSteps] = react.useState([]);
   const waitingForElsRef = react.useRef(false);
+  const elReadyRef = react.useRef(false);
   react.useEffect(() => {
-    var _a2, _b2;
-    if (!activeTour) {
+    var _a2, _b2, _c2;
+    if (!activeTour || isDelaying) {
       setValidSteps([]);
       waitingForElsRef.current = false;
+      elReadyRef.current = false;
       return;
     }
     waitingForElsRef.current = true;
+    const abortController = new AbortController();
     const compute = () => activeTour.steps.map((s, i) => ({ ...s, _originalIdx: i })).filter((s) => document.getElementById(resolveElId(s.el)));
     const found = compute();
     if (found.length > 0) {
@@ -580,71 +635,54 @@ var WalkthroughOverlay = ({
       if (currentStepInFound) {
         setValidSteps(found);
         waitingForElsRef.current = false;
+        elReadyRef.current = true;
         return;
       }
       setValidSteps(found);
+      elReadyRef.current = true;
       const currentStepEl = (_b2 = activeTour.steps[currentStepIdx]) == null ? void 0 : _b2.el;
       if (!currentStepEl) {
         waitingForElsRef.current = false;
         return;
       }
-      const observer2 = new MutationObserver(() => {
-        const el = document.getElementById(resolveElId(currentStepEl));
-        if (el) {
+      readElement(currentStepEl, { signal: abortController.signal }).then((el) => {
+        if (el && !abortController.signal.aborted) {
           waitingForElsRef.current = false;
           setValidSteps(compute());
-          observer2.disconnect();
         }
       });
-      observer2.observe(document.body, { childList: true, subtree: true });
       return () => {
-        observer2.disconnect();
+        abortController.abort();
         waitingForElsRef.current = false;
       };
     }
     setValidSteps([]);
-    const observer = new MutationObserver(() => {
-      const updated = compute();
-      if (updated.length > 0) {
-        waitingForElsRef.current = false;
-        setValidSteps(updated);
-        observer.disconnect();
+    const firstStepEl = (_c2 = activeTour.steps[0]) == null ? void 0 : _c2.el;
+    if (!firstStepEl) {
+      waitingForElsRef.current = false;
+      elReadyRef.current = true;
+      return;
+    }
+    readElement(firstStepEl, { signal: abortController.signal }).then((el) => {
+      if (el && !abortController.signal.aborted) {
+        const updated = compute();
+        if (updated.length > 0) {
+          waitingForElsRef.current = false;
+          elReadyRef.current = true;
+          setValidSteps(updated);
+        }
       }
     });
-    observer.observe(document.body, { childList: true, subtree: true });
     return () => {
-      observer.disconnect();
+      abortController.abort();
       waitingForElsRef.current = false;
     };
-  }, [activeTour]);
-  const currentOriginalIdx = (_a = activeTour == null ? void 0 : activeTour.currentStep) != null ? _a : 0;
+  }, [activeTour, isDelaying]);
+  const currentOriginalIdx = (_b = activeTour == null ? void 0 : activeTour.currentStep) != null ? _b : 0;
   const currentValidPos = validSteps.findIndex(
     (s) => s._originalIdx === currentOriginalIdx
   );
   const rawStep = currentValidPos !== -1 ? validSteps[currentValidPos] : null;
-  const delayDoneForRef = react.useRef(null);
-  const [isDelaying, setIsDelaying] = react.useState(false);
-  const currentTourName = (_b = activeTour == null ? void 0 : activeTour.name) != null ? _b : null;
-  react.useEffect(() => {
-    var _a2;
-    if (!activeTour) {
-      delayDoneForRef.current = null;
-      setIsDelaying(false);
-      return;
-    }
-    if (delayDoneForRef.current === activeTour.name) return;
-    const ms = (_a2 = activeTour.delay) != null ? _a2 : 0;
-    if (ms <= 0) {
-      delayDoneForRef.current = activeTour.name;
-      return;
-    }
-    setIsDelaying(true);
-    const timer = setTimeout(() => {
-      delayDoneForRef.current = activeTour.name;
-      setIsDelaying(false);
-    }, ms);
-    return () => clearTimeout(timer);
-  }, [currentTourName, activeTour]);
   const step = isDelaying ? null : rawStep;
   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);
@@ -657,6 +695,8 @@ var WalkthroughOverlay = ({
   }, [activeTour, rect]);
   react.useEffect(() => {
     if (!activeTour) return;
+    if (isDelaying) return;
+    if (!elReadyRef.current) return;
     if (currentValidPos !== -1) return;
     if (waitingForElsRef.current) return;
     if (validSteps.length === 0) {
@@ -676,6 +716,7 @@ var WalkthroughOverlay = ({
     }
   }, [
     activeTour,
+    isDelaying,
     currentValidPos,
     currentOriginalIdx,
     validSteps,
@@ -1013,6 +1054,7 @@ var WalkthroughOverlay = ({
 };
 
 exports.WalkthroughOverlay = WalkthroughOverlay;
+exports.readElement = readElement;
 exports.resetWalkthrough = resetWalkthrough;
 exports.useWalkthrough = useWalkthrough;
 //# sourceMappingURL=index.js.map