@tent-official/react-walkthrough 1.1.93 → 1.1.94

package/README.md

@@ -7,6 +7,8 @@ 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
 - 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)
 - Customizable labels, colors, and layout
 - Reset and replay walkthroughs without page refresh
 - Portal-based rendering (works inside modals)
@@ -74,6 +76,7 @@ Hook to register a walkthrough tour.
 | `steps` | `IWalkthroughStep[]` | **required** | Array of steps |
 | `storageSuffix` | `string` | `""` | Storage suffix for localStorage |
 | `dependsOn` | `string[]` | `[]` | Walkthrough names that must complete first |
+| `startWhenCondition` | `boolean \| () => boolean` | `undefined` | Additional condition that must be true for the walkthrough to start. Both `dependsOn` **AND** `startWhenCondition` must be satisfied. Example: `startWhenCondition: list.length > 0` |
 | `onWalkthroughComplete` | `(name: string) => void` | — | Callback when walkthrough completes (both finish and skip) |
 | `handleWhenLastStep` | `() => void` | — | Callback fired only when the user clicks "Done" on the last step (not on skip). Useful for triggering navigation (e.g. `router.push`) |
 | `isShowSkip` | `boolean` | `true` | Show skip button |
@@ -173,6 +176,44 @@ useWalkthrough({
 });
 ```
 
+## Conditional Start
+
+Use `startWhenCondition` to gate a walkthrough on custom logic. The walkthrough will only start when **both** `dependsOn` (if any) **and** `startWhenCondition` are satisfied:
+
+```jsx
+function Dashboard({ items }) {
+  // Won't start until items are loaded AND intro-tour is done
+  useWalkthrough({
+    name: "items-tour",
+    storageSuffix: "my-app",
+    dependsOn: ["intro-tour"],
+    startWhenCondition: items.length > 0,
+    steps: [/* ... */],
+  });
+
+  // Also accepts a function
+  useWalkthrough({
+    name: "profile-tour",
+    startWhenCondition: () => document.getElementById("profile-btn") !== null,
+    steps: [/* ... */],
+  });
+
+  return <div>...</div>;
+}
+```
+
+> When `startWhenCondition` is `undefined` (default), only `dependsOn` is checked — backward compatible.
+
+## Auto-Cleanup on Navigation
+
+The walkthrough highlight is **automatically removed** when the component that registered it unmounts. This means:
+
+- Pressing **browser back/forward** properly clears the overlay
+- **Route changes** (e.g. React Router, Next.js) clean up automatically
+- No stale highlights left on screen after navigation
+
+No extra configuration needed — this works out of the box.
+
 ## Keyboard Blocking
 
 While a walkthrough is active, the following keyboard keys are **automatically blocked** to prevent users from accidentally interacting with highlighted elements behind the overlay:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tent-official/react-walkthrough",
-  "version": "1.1.93",
+  "version": "1.1.94",
   "description": "Lightweight React walkthrough/tour component with auto-positioning, dependency chains, and smooth animations",
   "main": "dist/index.js",
   "module": "dist/index.mjs",