rn-smart-tour 1.0.3 → 1.0.5

package/README.md

@@ -1,15 +1,23 @@
 # rn-smart-tour
 
-An enterprise-grade Digital Adoption Platform (DAP) package for React Native. Easily add product tours, guided walkthroughs, and onboarding overlays directly into your app without intrusive code changes.
+<p align="center">
+  <b>Enterprise-grade Digital Adoption Platform (DAP) for React Native</b><br>
+  Easily add product tours, guided walkthroughs, and onboarding overlays without intrusive code changes.
+</p>
 
-## Features
-- **Multi-Pass Measurement**: Wraps your components and uses the native `measureInWindow` API with a self-correcting, multi-pass strategy — so highlights land correctly even during screen-transition animations.
-- **Rotation & Resize Aware**: Automatically re-measures targets when screen dimensions change (rotation, split-screen, foldables).
-- **Debounced Auto-Start Engine**: Automatically triggers tours when target elements mount, with a built-in debounce to ensure the overlay uses fully settled coordinates.
-- **Seen State Caching**: Connect any local storage database to ensure users only see tours once.
-- **Smart Overlays**: Creates highlighted holes in backdrops over completely custom UIs, with Back/Next/Skip navigation.
+---
+
+## ✨ Features
+
+- 🎯 **Multi-Pass Measurement**: Native `measureInWindow` API with self-correcting strategy for animation resilience.
+- 📱 **Rotation & Resize Aware**: Targets re-measure automatically on orientation change or split-screen.
+- ⚡ **Auto-Start Engine**: Trigger tours instantly on mount with a smart debounce for layout stability.
+- 💾 **Seen State Caching**: Persistent "only-once" logic with pluggable storage (AsyncStorage, MMKV, etc.).
+- 🎨 **Smart Overlays**: Dynamic cutouts with Back/Next/Skip navigation and step indicators.
 
-## Installation
+---
+
+## 📦 Installation
 
 ```sh
 npm install rn-smart-tour
@@ -17,202 +25,126 @@ npm install rn-smart-tour
 
 ---
 
-## 🚀 Quick Start Guide
-
-Adding a product tour to your app only takes 3 simple steps:
+## 🚀 Quick Start
 
-### Step 1: Wrap your App 
-At the very top of your application (usually `App.tsx`), wrap everything in the `<DapProvider>`. Here you define the tours you want to show your users.
+### 1. Wrap your App
+Wrap your root component in the `DapProvider` and define your tours.
 
 ```tsx
-import React from 'react';
 import { DapProvider } from 'rn-smart-tour';
 
-// Define the steps of your tour here!
-const MY_TOURS = {
+const TOURS = {
   'welcome-tour': {
     id: 'welcome-tour',
-    steps: [
-      {
-        targetId: 'my-first-button',
-        title: 'Welcome to the App!',
-        description: 'Tapping this button saves your progress.',
-      }
-    ]
+    steps: [{
+      targetId: 'save-btn',
+      title: 'Welcome!',
+      description: 'Tap here to save your progress.',
+    }]
   }
 };
 
 export default function App() {
   return (
-    <DapProvider tours={MY_TOURS}>
-      <MainScreen />
+    <DapProvider tours={TOURS}>
+      <MainApp />
     </DapProvider>
   );
 }
 ```
 
-### Step 2: Target an Element
-Go to any screen in your app and decide what button or view you want to highlight. Wrap that element with `<DapTarget>`. Make sure the `name` matches the `targetId` from Step 1!
+### 2. Mark your Target
+Wrap any view or button you want to highlight with `DapTarget`.
 
 ```tsx
-import { View, Button } from 'react-native';
 import { DapTarget } from 'rn-smart-tour';
 
-export const MainScreen = () => {
-  return (
-    <View style={{ marginTop: 100 }}>
-      {/* Wrap the button you want to highlight! */}
-      <DapTarget name="my-first-button">
-         <Button title="Save Button" onPress={() => {}} />
-      </DapTarget>
-    </View>
-  );
-};
+const MyButton = () => (
+  <DapTarget name="save-btn">
+    <Button title="Save" onPress={...} />
+  </DapTarget>
+);
 ```
 
-### Step 3: Trigger the Tour!
-To start the walkthrough, just call `startTour` anywhere inside your app.
+### 3. Start the Tour
+Use the `useDap` hook to trigger the onboarding.
 
 ```tsx
-import { Button } from 'react-native';
 import { useDap } from 'rn-smart-tour';
 
-export const HelpMenu = () => {
-    const { startTour } = useDap();
-    
-    return (
-        <Button 
-          title="Start Walkthrough" 
-          onPress={() => startTour('welcome-tour')} 
-        />
-    );
-}
+const { startTour } = useDap();
+// ...
+<Button title="Help" onPress={() => startTour('welcome-tour')} />
 ```
 
 ---
 
-## 🧠 Advanced Usage (Pro Features)
-
-### 1. Auto-Start & Show "Only Once"
-For true enterprise onboarding, you want the tour to start *automatically* when a user visits a new screen, and never show it to them again after they finish it.
-
-By passing a `storageAdapter` (like `AsyncStorage`) into the Provider, the package will permanently remember who has seen the tour!
-
-```tsx
-import AsyncStorage from '@react-native-async-storage/async-storage';
-
-const MY_TOURS = {
-  'welcome-tour': {
-    id: 'welcome-tour',
-    autoStart: true, // Automatically starts when "my-first-button" mounts!
-    steps: [ ... ]
-  }
-};
-
-// Map the Storage commands
-const myStorage = {
-  getItem: async (key) => await AsyncStorage.getItem(key),
-  setItem: async (key, value) => { await AsyncStorage.setItem(key, value); }
-};
-
-// Pass it to the Provider
-<DapProvider tours={MY_TOURS} storageAdapter={myStorage}>
-```
+## 🧠 Technical Architecture
 
-### 2. How Measurement Works
+<details>
+<summary><b>View How Measurements Work (Click to expand)</b></summary>
 
-When a `<DapTarget>` mounts or re-layouts, it does **not** rely on a single measurement. Instead, it uses a **multi-pass strategy** to guarantee accuracy:
+To guarantee accuracy during navigation animations, `rn-smart-tour` uses a **multi-pass strategy**:
 
-| Pass | Delay | Purpose |
-|------|-------|---------|
-| 1st  | 100ms | Fast first estimate — may capture mid-animation coordinates |
-| 2nd  | 500ms | Self-corrects after most navigation transitions finish |
-| 3rd  | 1000ms | Final safety net for slow animations or async layout shifts |
+- **Pass 1 (100ms)**: Fast first estimate.
+- **Pass 2 (500ms)**: Corrects after most screen transitions finish.
+- **Pass 3 (1000ms)**: Final safety net for slow async layout shifts.
 
-- Each new `onLayout` event **cancels** all pending timers and schedules fresh measurements.
-- A measurement is only sent to the Provider if the position has **actually changed** (>1pt threshold), avoiding unnecessary re-renders.
-- On **rotation/resize**, all targets automatically re-measure themselves.
-- On unmount, all timers are cleaned up and the target is unregistered.
+Measurements only trigger a re-render if the position changes by more than **1pt (threshold)**.
 
-#### Auto-Start Debounce
+</details>
 
-When `autoStart: true` is set on a tour, the overlay does **not** appear the instant a target registers. Instead, it waits **300ms** before starting. If a more accurate measurement arrives during that window (e.g., the 500ms pass corrects the 100ms pass), the debounce resets and the overlay uses the final, settled coordinates.
+<details>
+<summary><b>Auto-Start & Debounce Settings</b></summary>
 
-This is why you may notice a brief (~300ms) delay before an auto-start tour appears — it's by design to prevent misaligned highlights.
+When `autoStart: true` is enabled, the overlay waits **300ms** after registration. This allows the multi-pass system to settle on the final coordinates before the hole is cut into the backdrop.
 
-#### Tuning Constants
+</details>
 
-If you need to adjust timing for your app's specific animation durations, the following constants can be modified in the source:
-
-| Constant | File | Default | Description |
-|----------|------|---------|-------------|
-| `MEASUREMENT_DELAYS` | `DapTarget.tsx` | `[100, 500, 1000]` | Multi-pass measurement intervals (ms) |
-| `POSITION_THRESHOLD` | `DapTarget.tsx` | `1` | Minimum position change (points) to trigger re-registration |
-| `AUTO_START_DEBOUNCE_MS` | `DapProvider.tsx` | `300` | Debounce delay (ms) before auto-starting a tour |
-
-### 3. Programmatic Control
-
-The `useDap()` hook exposes full control over tours:
-
-```tsx
-const { startTour, stopTour, nextStep, prevStep, activeTour, currentStepIndex } = useDap();
-
-// Start a specific tour
-startTour('welcome-tour');
-
-// Stop and mark as seen (default)
-stopTour();
-
-// Stop WITHOUT marking as seen (user can see it again)
-stopTour(false);
-
-// Navigate between steps
-nextStep();
-prevStep();
-```
+---
 
-## API Reference
+## 🛠 API Reference
 
-### Tour Object
+### Tour Configuration
 | Property | Type | Description |
-|-----------|------|-------------|
-| `id` | `string` | Unique identifier. Needed for cache tracking. |
-| `autoStart` | `boolean` | If true, automatically renders when the first step's target mounts on the screen. |
-| `steps` | `TourStep[]` | The sequence of highlighted elements and tooltips. |
+|:---|:---|:---|
+| `id` | `string` | Unique identifier for caching. |
+| `autoStart` | `boolean` | Trigger as soon as the first target mounts. |
+| `steps` | `TourStep[]` | Sequence of highlight steps. |
 
-### TourStep Object
-| Property | Type | Default | Description |
-|-----------|------|---------|-------------|
-| `targetId` | `string` | — | Must directly match the `name=""` prop passed to `<DapTarget>`. |
-| `title` | `string` | — | Large text inside the tooltip. |
-| `description` | `string` | — | Context explanation inside the tooltip. |
-| `position` | `'top' \| 'bottom' \| 'left' \| 'right'` | `'bottom'` | Where the tooltip appears relative to the highlighted target. |
-
-### DapTarget Props
+### DapTarget
 | Property | Type | Description |
-|-----------|------|-------------|
+|:---|:---|:---|
 | `name` | `string` | Unique identifier that matches a `targetId` in a tour step. |
 | `children` | `ReactElement` | The UI element to wrap and highlight. |
+| `asChild` | `boolean` | **New!** If true, clones the child to avoid an extra View wrapper. (Crucial for flex/percentage layouts). |
 | `...props` | `ViewProps` | All standard React Native `View` props are forwarded. |
 
-### useDap() Hook
-| Property | Type | Description |
-|-----------|------|-------------|
-| `startTour(id)` | `(tourId: string) => void` | Start a tour by its ID. |
-| `stopTour(markAsSeen?)` | `(markAsSeen?: boolean) => void` | Stop the active tour. Pass `false` to allow the tour to show again. |
-| `nextStep()` | `() => void` | Advance to the next step. Finishes the tour if on the last step. |
-| `prevStep()` | `() => void` | Go back to the previous step. |
-| `activeTour` | `Tour \| null` | The currently active tour object, or `null`. |
-| `currentStepIndex` | `number` | Index of the current step in the active tour. |
-| `targets` | `Record<string, TargetMeasurement>` | All registered target measurements. |
-| `seenTours` | `Record<string, boolean>` | Map of tour IDs to whether they've been seen. |
-
-### StorageAdapter Interface
-| Method | Type | Description |
-|--------|------|-------------|
-| `getItem` | `(key: string) => Promise<string \| null> \| string \| null` | Retrieve a stored value by key. |
-| `setItem` | `(key: string, value: string) => Promise<void> \| void` | Store a value by key. |
-
-Compatible with `AsyncStorage`, `MMKV`, or any key-value store that implements this interface.
-# rn-smart-tour
-
+### TourStep
+| Property | Type | Default | Description |
+|:---|:---|:---|:---|
+| `targetId` | `string` | — | Matches the `name` prop in `<DapTarget>`. |
+| `title` | `string` | — | Tooltip header. |
+| `description` | `string` | — | Tooltip body. |
+| `position` | `string` | `'bottom'` | `top`, `bottom`, `left`, `right`. |
+
+### `useDap()` Hook
+| Method | Description |
+|:---|:---|
+| `startTour(id)` | Start a tour by ID. |
+| `stopTour(markAsSeen?)`| End tour. Pass `false` to keep it unread. |
+| `nextStep()` / `prevStep()` | Manual step navigation. |
+| `activeTour` | Current active tour object. |
+| `currentStepIndex` | Current step number (0-indexed). |
+
+---
+
+## 🤝 Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+---
+
+<p align="center">
+  <b>rn-smart-tour</b> • Built with ❤️ for the React Native community.
+</p>

package/dist/DapOverlay.js

@@ -126,9 +126,9 @@ const DapOverlay = () => {
             </react_native_1.Text>)}
 
           <react_native_1.View style={styles.actions}>
-            <react_native_1.TouchableOpacity onPress={() => stopTour()} style={styles.actionBtn}>
-              <react_native_1.Text style={styles.actionText}>Skip</react_native_1.Text>
-            </react_native_1.TouchableOpacity>
+            {!isLastStep && (<react_native_1.TouchableOpacity onPress={() => stopTour()} style={styles.actionBtn}>
+                <react_native_1.Text style={styles.actionText}>Skip</react_native_1.Text>
+              </react_native_1.TouchableOpacity>)}
 
             {!isFirstStep && (<react_native_1.TouchableOpacity onPress={prevStep} style={styles.actionBtn}>
                 <react_native_1.Text style={styles.actionText}>Back</react_native_1.Text>

package/dist/DapProvider.js

@@ -50,9 +50,15 @@ const DapProvider = ({ children, tours, storageAdapter }) => {
     const [currentStepIndex, setCurrentStepIndex] = (0, react_1.useState)(0);
     const [seenTours, setSeenTours] = (0, react_1.useState)({});
     const [isStorageLoaded, setIsStorageLoaded] = (0, react_1.useState)(!storageAdapter);
-    // Ref to avoid stale closures — always holds the latest activeTourId.
+    // Ref to always hold the latest activeTourId, avoiding stale closures.
     const activeTourIdRef = (0, react_1.useRef)(activeTourId);
     activeTourIdRef.current = activeTourId;
+    /**
+     * Ref to track the ID of a tour that was just manually stopped/skipped.
+     * This prevents the auto-start engine from immediately restarting the same tour
+     * before the 'seenTours' state update has been processed.
+     */
+    const tourIdJustStoppedRef = (0, react_1.useRef)(null);
     // Load seen tours on mount if a storage adapter is provided
     (0, react_1.useEffect)(() => {
         const loadStorage = async () => {
@@ -102,11 +108,14 @@ const DapProvider = ({ children, tours, storageAdapter }) => {
             console.warn(`[rn-dap] Tour with id ${tourId} not found.`);
         }
     }, [tours, seenTours]);
-    // Uses activeTourIdRef to avoid stale closures and prevent cascading re-renders.
     const stopTour = (0, react_1.useCallback)((markAsSeen = true) => {
         const currentTourId = activeTourIdRef.current;
-        if (currentTourId && markAsSeen) {
-            saveSeenTour(currentTourId);
+        if (currentTourId) {
+            if (markAsSeen) {
+                saveSeenTour(currentTourId);
+            }
+            // Block this specific tour from auto-restarting until coordinates or seenTours settle.
+            tourIdJustStoppedRef.current = currentTourId;
         }
         setActiveTourId(null);
         setCurrentStepIndex(0);
@@ -142,7 +151,9 @@ const DapProvider = ({ children, tours, storageAdapter }) => {
         autoStartTimerRef.current = setTimeout(() => {
             for (const tourId of Object.keys(tours)) {
                 const tour = tours[tourId];
-                if (tour.autoStart && !seenTours[tourId] && tour.steps.length > 0) {
+                // Skip if this tour was just manually stopped and haven't confirmed 'seen' yet.
+                const wasJustStopped = tourIdJustStoppedRef.current === tourId;
+                if (tour.autoStart && !seenTours[tourId] && !wasJustStopped && tour.steps.length > 0) {
                     const firstTargetId = tour.steps[0].targetId;
                     // If the first target of an unread, auto-starting tour is mounted
                     if (targets[firstTargetId]) {
@@ -151,6 +162,10 @@ const DapProvider = ({ children, tours, storageAdapter }) => {
                     }
                 }
             }
+            // Cleanup the "just stopped" ref once the seenTours state finally reflects the closure.
+            if (tourIdJustStoppedRef.current && seenTours[tourIdJustStoppedRef.current]) {
+                tourIdJustStoppedRef.current = null;
+            }
         }, AUTO_START_DEBOUNCE_MS);
         return () => {
             if (autoStartTimerRef.current) {

package/dist/DapTarget.d.ts

@@ -3,6 +3,12 @@ import { ViewProps } from 'react-native';
 interface DapTargetProps extends ViewProps {
     name: string;
     children: ReactElement;
+    /**
+     * If true, DapTarget will not wrap your child in a View. Instead, it will
+     * clone the child and inject the ref/onLayout logic directly.
+     * Useful for maintaining flex layouts or percentage widths (e.g. 33%).
+     */
+    asChild?: boolean;
 }
 export declare const DapTarget: React.FC<DapTargetProps>;
 export {};

package/dist/DapTarget.js

@@ -45,7 +45,22 @@ const DapContext_1 = require("./DapContext");
 const MEASUREMENT_DELAYS = [100, 500, 1000];
 /** Threshold in points — ignore sub-pixel drift to avoid unnecessary re-registers. */
 const POSITION_THRESHOLD = 1;
-const DapTarget = ({ name, children, ...props }) => {
+/**
+ * Utility to merge multiple refs into a single callback ref.
+ */
+function setRefs(...refs) {
+    return (value) => {
+        refs.forEach((ref) => {
+            if (typeof ref === 'function') {
+                ref(value);
+            }
+            else if (ref && typeof ref === 'object') {
+                ref.current = value;
+            }
+        });
+    };
+}
+const DapTarget = ({ name, children, asChild, ...props }) => {
     const viewRef = (0, react_1.useRef)(null);
     const context = (0, react_1.useContext)(DapContext_1.DapContext);
     /** Holds all scheduled timer IDs so we can cancel them on re-layout or unmount. */
@@ -116,7 +131,26 @@ const DapTarget = ({ name, children, ...props }) => {
             unregisterTarget?.(name);
         };
     }, [name, unregisterTarget, clearAllTimers]);
-    // collapsable={false} is vital for Android, otherwise it gets optimized away and measure fails
+    // If asChild is enabled, clone the child and inject measurement logic.
+    if (asChild && (0, react_1.isValidElement)(children)) {
+        try {
+            const child = react_1.Children.only(children);
+            return (0, react_1.cloneElement)(child, {
+                ...props,
+                ref: setRefs(viewRef, child.ref),
+                onLayout: (e) => {
+                    handleLayout(e);
+                    child.props.onLayout?.(e);
+                },
+                // collapsable={false} is vital for Android measurement
+                collapsable: false,
+            });
+        }
+        catch (e) {
+            console.warn('[rn-dap] asChild requires a single React element as a child.');
+        }
+    }
+    // Fallback to standard View wrapper
     return (<react_native_1.View ref={viewRef} onLayout={handleLayout} collapsable={false} {...props}>
       {children}
     </react_native_1.View>);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rn-smart-tour",
-  "version": "1.0.3",
+  "version": "1.0.5",
   "description": "Enterprise-grade Digital Adoption Platform (DAP) package for React Native. Provides guided walkthroughs, tooltips, and app tours.",
   "author": "Vishwas Gaur",
   "license": "MIT",
@@ -9,14 +9,6 @@
   "files": [
     "dist"
   ],
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/Vishwasgaur0819/rn-smart-tour"
-  },
-  "homepage": "https://github.com/Vishwasgaur0819/rn-smart-tour#readme",
-  "bugs": {
-    "url": "https://github.com/Vishwasgaur0819/rn-smart-tour/issues"
-  },
   "keywords": [
     "react-native",
     "tour",