@tent-official/react-walkthrough 1.3.5 → 1.4.0

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 |
@@ -259,6 +260,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.
  */

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.
  */

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 = {
@@ -1143,7 +1147,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 ? {