@tent-official/react-walkthrough 1.3.5 → 1.4.1

package/README.md

@@ -6,6 +6,7 @@ Lightweight React walkthrough/tour component with auto-positioning, dependency c
 
 - SVG-based spotlight overlay with smooth animated transitions
 - Auto-positioning popover (top/bottom/left/right) with viewport detection
+- Inner positions (`inner-top`, `inner-bottom`, `inner-left`, `inner-right`) — place the popover inside the highlight area
 - Dependency chains — start a walkthrough only after another completes
 - Conditional start — `startWhenCondition` prop to gate walkthrough on custom logic (e.g. data loaded)
 - Auto-cleanup on navigation — highlight is automatically removed when the component unmounts (e.g. browser back/forward)
@@ -104,7 +105,7 @@ Hook to register a walkthrough tour.
 | `el` | `string` | **required** | DOM element ID to highlight (with or without `#` prefix) |
 | `title` | `string` | — | Popover title |
 | `description` | `IStepDescription[]` | **required** | Description blocks |
-| `position` | `"top" \| "bottom" \| "left" \| "right"` | auto | Preferred popover position |
+| `position` | `"top" \| "bottom" \| "left" \| "right" \| "inner-top" \| "inner-bottom" \| "inner-left" \| "inner-right"` | auto | Preferred popover position. `inner-*` positions place the popover inside the highlight area (12 px inset) |
 | `padding` | `number` | `8` | Padding around highlighted element (px) |
 | `borderRadius` | `number` | `10` | Border radius of highlight cutout (px) |
 | `width` | `number \| string` | `"auto"` | Popover width |
@@ -118,6 +119,7 @@ Hook to register a walkthrough tour.
 | `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 |
 
 ### `IStepDescription`
 
@@ -259,6 +261,21 @@ 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.
 
+### Inner Positions
+
+Use `inner-top`, `inner-bottom`, `inner-left`, or `inner-right` to place the popover **inside** the highlight area, inset 12 px from the corresponding edge. Inner positions never auto-fallback — they always stay exactly where specified.
+
+This is useful when the highlighted area is large (e.g. a table or a panel) and you want the popover to appear within it rather than outside.
+
+```jsx
+{
+  el: "large-table",
+  title: "Table Overview",
+  description: [{ description: "Here is your data table." }],
+  position: "inner-bottom", // popover sits inside the highlight, near the bottom-right corner
+}
+```
+
 ## Instant Dismiss
 
 When the user clicks **Done** on the last step (or **Skip** at any step), the highlight and popover vanish **instantly** in the same render frame — no lingering overlay or flash.

package/dist/index.d.mts

@@ -3,8 +3,11 @@ import { ReactNode, ReactPortal } from 'react';
 /**
  * Position of the popover relative to the target element.
  * If the preferred position doesn't fit in the viewport, it will auto-fallback.
+ *
+ * "inner-*" positions place the popover **inside** the highlight area,
+ * inset 12 px from the corresponding edge. These never auto-fallback.
  */
-type TPopoverPosition = "top" | "bottom" | "left" | "right";
+type TPopoverPosition = "top" | "bottom" | "left" | "right" | "inner-top" | "inner-bottom" | "inner-left" | "inner-right";
 /**
  * Direction for description block layout.
  */
@@ -58,6 +61,8 @@ interface IWalkthroughStep {
     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;
 }
 /**
  * Options for the useWalkthrough hook.

package/dist/index.d.ts

@@ -3,8 +3,11 @@ import { ReactNode, ReactPortal } from 'react';
 /**
  * Position of the popover relative to the target element.
  * If the preferred position doesn't fit in the viewport, it will auto-fallback.
+ *
+ * "inner-*" positions place the popover **inside** the highlight area,
+ * inset 12 px from the corresponding edge. These never auto-fallback.
  */
-type TPopoverPosition = "top" | "bottom" | "left" | "right";
+type TPopoverPosition = "top" | "bottom" | "left" | "right" | "inner-top" | "inner-bottom" | "inner-left" | "inner-right";
 /**
  * Direction for description block layout.
  */
@@ -58,6 +61,8 @@ interface IWalkthroughStep {
     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;
 }
 /**
  * Options for the useWalkthrough hook.

package/dist/index.js

@@ -531,7 +531,11 @@ var clampSize = (value, max) => {
   return clamped;
 };
 var EDGE_MARGIN = 8;
+var INNER_INSET = 12;
 var choosePopoverDir = (rect, popoverW, popoverH, gap, preferred) => {
+  if (preferred && preferred.startsWith("inner-")) {
+    return { dir: preferred, align: "start", offsetX: 0, offsetY: 0 };
+  }
   const vw = window.innerWidth;
   const vh = window.innerHeight;
   const space = {
@@ -1007,13 +1011,21 @@ var WalkthroughOverlay = ({
     }
   };
   const next = () => {
-    var _a2;
+    var _a2, _b2;
     const currentOrigIdx = validSteps[currentValidPos]._originalIdx;
     const stepNextCb = (_a2 = activeTour.onStepNext) == null ? void 0 : _a2[currentOrigIdx];
     if (typeof stepNextCb === "function") {
       stepNextCb();
     }
     const hasTrigger = !!step.triggerElOnNext;
+    const afterNextDelay = (_b2 = step.delayAfterNext) != null ? _b2 : 0;
+    const withDelay = (fn) => {
+      if (afterNextDelay > 0) {
+        setTimeout(fn, afterNextDelay);
+      } else {
+        fn();
+      }
+    };
     if (hasTrigger) {
       setPopoverHidden(true);
       setPopoverPos(null);
@@ -1046,7 +1058,7 @@ var WalkthroughOverlay = ({
         const SETTLE_DELAY = 150;
         const alreadyExists = document.getElementById(nextElId);
         if (alreadyExists) {
-          setTimeout(() => injectAndAdvance(), SETTLE_DELAY);
+          withDelay(() => setTimeout(() => injectAndAdvance(), SETTLE_DELAY));
         } else {
           waitingForElsRef.current = true;
           const observer = new MutationObserver(() => {
@@ -1054,7 +1066,7 @@ var WalkthroughOverlay = ({
             if (found) {
               observer.disconnect();
               waitingForElsRef.current = false;
-              setTimeout(() => injectAndAdvance(), SETTLE_DELAY);
+              withDelay(() => setTimeout(() => injectAndAdvance(), SETTLE_DELAY));
             }
           });
           observer.observe(document.body, { childList: true, subtree: true });
@@ -1062,7 +1074,7 @@ var WalkthroughOverlay = ({
             observer.disconnect();
             if (waitingForElsRef.current) {
               waitingForElsRef.current = false;
-              advanceStep(hasTrigger);
+              withDelay(() => advanceStep(hasTrigger));
             }
           }, 3e3);
         }
@@ -1073,7 +1085,13 @@ var WalkthroughOverlay = ({
       setTimeout(() => completeTour(), 300);
       return;
     }
-    advanceStep(hasTrigger);
+    if (afterNextDelay > 0) {
+      setPopoverHidden(true);
+      setPopoverPos(null);
+      withDelay(() => advanceStep(hasTrigger));
+    } else {
+      advanceStep(hasTrigger);
+    }
   };
   const prev = () => {
     var _a2;
@@ -1143,7 +1161,12 @@ var WalkthroughOverlay = ({
     bottom: { top: `calc(100% + ${$popoverGap}px)`, ...hAlign },
     top: { bottom: `calc(100% + ${$popoverGap}px)`, ...hAlign },
     right: { left: `calc(100% + ${$popoverGap}px)`, ...vAlign },
-    left: { right: `calc(100% + ${$popoverGap}px)`, ...vAlign }
+    left: { right: `calc(100% + ${$popoverGap}px)`, ...vAlign },
+    // inner-* : popover sits INSIDE the highlight rect, inset 12px from the edge
+    "inner-bottom": { bottom: INNER_INSET, right: INNER_INSET },
+    "inner-top": { top: INNER_INSET, right: INNER_INSET },
+    "inner-left": { left: INNER_INSET, bottom: INNER_INSET },
+    "inner-right": { right: INNER_INSET, bottom: INNER_INSET }
   };
   const maxHeightStyle = (popoverPos == null ? void 0 : popoverPos.maxHeight) != null ? { maxHeight: popoverPos.maxHeight, overflowY: "auto" } : {};
   const popoverStyle = popoverReady ? {