rn-smart-tour 1.0.4 → 1.0.7

package/README.md

@@ -14,6 +14,7 @@
 - ⚡ **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.
+- 📜 **Auto-Scroll Support**: Seamlessly bring tour targets into view with the new `DapScrollView` integration.
 
 ---
 
@@ -77,6 +78,20 @@ const { startTour } = useDap();
 <Button title="Help" onPress={() => startTour('welcome-tour')} />
 ```
 
+### 4. Enable Auto-Scroll (Optional)
+If your targets are hidden inside a long list, swap your standard `ScrollView` for `DapScrollView`. The tour will automatically scroll to bring each target into the user's view.
+
+```tsx
+import { DapScrollView } from 'rn-smart-tour';
+
+// ... inside your screen
+<DapScrollView>
+  <DapTarget name="bottom-btn">
+    <Button title="Secret Button" ... />
+  </DapTarget>
+</DapScrollView>
+```
+
 ---
 
 ## 🧠 Technical Architecture
@@ -112,6 +127,20 @@ When `autoStart: true` is enabled, the overlay waits **300ms** after registratio
 | `autoStart` | `boolean` | Trigger as soon as the first target mounts. |
 | `steps` | `TourStep[]` | Sequence of highlight steps. |
 
+### DapScrollView
+A direct drop-in replacement for the React Native `ScrollView`. Supports all standard props.
+| Property | Type | Description |
+|:---|:---|:---|
+| `children` | `React.Node` | Components to scroll. |
+| `...props` | `ScrollViewProps` | Standard props are forwarded to the native ScrollView. |
+
+### 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. |
+| `...props` | `ViewProps` | All standard React Native `View` props are forwarded. |
+
 ### TourStep
 | Property | Type | Default | Description |
 |:---|:---|:---|:---|

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

@@ -35,14 +35,10 @@ var __importStar = (this && this.__importStar) || (function () {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.DapProvider = void 0;
 const react_1 = __importStar(require("react"));
+const react_native_1 = require("react-native");
 const DapContext_1 = require("./DapContext");
 const DapOverlay_1 = require("./DapOverlay");
 const STORAGE_KEY = '@rn-dap:seen_tours';
-/**
- * Debounce delay (ms) before auto-starting a tour after a target registers.
- * This gives the multi-pass measurement in DapTarget time to settle on the
- * final coordinates before the overlay is shown.
- */
 const AUTO_START_DEBOUNCE_MS = 300;
 const DapProvider = ({ children, tours, storageAdapter }) => {
     const [targets, setTargets] = (0, react_1.useState)({});
@@ -50,9 +46,13 @@ 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.
     const activeTourIdRef = (0, react_1.useRef)(activeTourId);
     activeTourIdRef.current = activeTourId;
+    const tourIdJustStoppedRef = (0, react_1.useRef)(null);
+    /** Map of target IDs to their native component references (for measureLayout). */
+    const targetRefs = (0, react_1.useRef)({});
+    /** Reference to the active ScrollView (if any) for auto-scrolling. */
+    const scrollRef = (0, react_1.useRef)(null);
     // Load seen tours on mount if a storage adapter is provided
     (0, react_1.useEffect)(() => {
         const loadStorage = async () => {
@@ -75,7 +75,6 @@ const DapProvider = ({ children, tours, storageAdapter }) => {
         setSeenTours(prev => {
             const nextSeen = { ...prev, [tourId]: true };
             if (storageAdapter) {
-                // Safe side-effect here for async storage, as long as it's fire-and-forget
                 Promise.resolve(storageAdapter.setItem(STORAGE_KEY, JSON.stringify(nextSeen))).catch(e => {
                     console.error('[rn-dap] failed to save storage', e);
                 });
@@ -83,8 +82,11 @@ const DapProvider = ({ children, tours, storageAdapter }) => {
             return nextSeen;
         });
     }, [storageAdapter]);
-    const registerTarget = (0, react_1.useCallback)((id, measurement) => {
+    const registerTarget = (0, react_1.useCallback)((id, measurement, ref) => {
         setTargets(prev => ({ ...prev, [id]: measurement }));
+        if (ref) {
+            targetRefs.current[id] = ref;
+        }
     }, []);
     const unregisterTarget = (0, react_1.useCallback)((id) => {
         setTargets(prev => {
@@ -92,6 +94,37 @@ const DapProvider = ({ children, tours, storageAdapter }) => {
             delete next[id];
             return next;
         });
+        delete targetRefs.current[id];
+    }, []);
+    const _registerScrollRef = (0, react_1.useCallback)((ref) => {
+        scrollRef.current = ref;
+    }, []);
+    /**
+     * Calculates the relative position of a target to the registered ScrollView
+     * and triggers a native scrollTo call.
+     */
+    const requestScroll = (0, react_1.useCallback)((targetId) => {
+        const target = targetRefs.current[targetId];
+        const scroll = scrollRef.current;
+        if (!target || !scroll)
+            return;
+        // Use measureLayout for scrollable positioning calculation
+        const targetHandle = (0, react_native_1.findNodeHandle)(target);
+        const scrollHandle = (0, react_native_1.findNodeHandle)(scroll);
+        if (targetHandle && scrollHandle) {
+            try {
+                target.measureLayout(scrollHandle, (_x, y) => {
+                    // Scroll target into view with some top padding
+                    scroll.scrollTo({ y: Math.max(0, y - 100), animated: true });
+                }, () => {
+                    console.warn(`[rn-dap] Failed to measure layout for target: ${targetId}`);
+                });
+            }
+            catch (e) {
+                // Fallback if measureLayout isn't available on the component ref directly
+                console.warn('[rn-dap] measureLayout failed', e);
+            }
+        }
     }, []);
     const startTour = (0, react_1.useCallback)((tourId) => {
         if (tours[tourId] && !seenTours[tourId]) {
@@ -102,11 +135,13 @@ 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);
+            }
+            tourIdJustStoppedRef.current = currentTourId;
         }
         setActiveTourId(null);
         setCurrentStepIndex(0);
@@ -118,7 +153,6 @@ const DapProvider = ({ children, tours, storageAdapter }) => {
                 setCurrentStepIndex(prev => prev + 1);
             }
             else {
-                // Finished the last step
                 stopTour(true);
             }
         }
@@ -128,29 +162,28 @@ const DapProvider = ({ children, tours, storageAdapter }) => {
             setCurrentStepIndex(prev => prev - 1);
         }
     }, [currentStepIndex]);
-    /** Timer ref for debounced auto-start. */
     const autoStartTimerRef = (0, react_1.useRef)();
-    // Auto-Start Engine — debounced so multi-pass measurements can settle.
     (0, react_1.useEffect)(() => {
-        // Wait until storage is loaded, and ensure no tour is currently running
         if (!isStorageLoaded || activeTourId)
             return;
-        // Clear any previously scheduled auto-start
         if (autoStartTimerRef.current) {
             clearTimeout(autoStartTimerRef.current);
         }
         autoStartTimerRef.current = setTimeout(() => {
             for (const tourId of Object.keys(tours)) {
                 const tour = tours[tourId];
-                if (tour.autoStart && !seenTours[tourId] && tour.steps.length > 0) {
+                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]) {
                         startTour(tourId);
-                        break; // Start only one auto-tour at a time
+                        break;
                     }
                 }
             }
+            if (tourIdJustStoppedRef.current && seenTours[tourIdJustStoppedRef.current]) {
+                tourIdJustStoppedRef.current = null;
+            }
         }, AUTO_START_DEBOUNCE_MS);
         return () => {
             if (autoStartTimerRef.current) {
@@ -169,7 +202,9 @@ const DapProvider = ({ children, tours, storageAdapter }) => {
         activeTour,
         currentStepIndex,
         targets,
-        seenTours
+        seenTours,
+        requestScroll,
+        _registerScrollRef
     }), [
         registerTarget,
         unregisterTarget,
@@ -180,7 +215,9 @@ const DapProvider = ({ children, tours, storageAdapter }) => {
         activeTour,
         currentStepIndex,
         targets,
-        seenTours
+        seenTours,
+        requestScroll,
+        _registerScrollRef
     ]);
     return (<DapContext_1.DapContext.Provider value={contextValue}>
       {children}

package/dist/DapScrollView.d.ts

@@ -0,0 +1,8 @@
+import React from 'react';
+import { ScrollViewProps } from 'react-native';
+/**
+ * A wrapper for the React Native ScrollView that integrates with the rn-smart-tour
+ * Auto-Scroll engine. When used, the library can automatically scroll to bring
+ * tour targets into the user's view.
+ */
+export declare const DapScrollView: React.FC<ScrollViewProps>;

package/dist/DapScrollView.js

@@ -0,0 +1,62 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DapScrollView = void 0;
+const react_1 = __importStar(require("react"));
+const react_native_1 = require("react-native");
+const DapContext_1 = require("./DapContext");
+/**
+ * A wrapper for the React Native ScrollView that integrates with the rn-smart-tour
+ * Auto-Scroll engine. When used, the library can automatically scroll to bring
+ * tour targets into the user's view.
+ */
+const DapScrollView = (props) => {
+    const context = (0, react_1.useContext)(DapContext_1.DapContext);
+    const scrollRef = (0, react_1.useRef)(null);
+    (0, react_1.useEffect)(() => {
+        if (context?._registerScrollRef && scrollRef.current) {
+            context._registerScrollRef(scrollRef.current);
+        }
+        return () => {
+            if (context?._registerScrollRef) {
+                context._registerScrollRef(null);
+            }
+        };
+    }, [context]);
+    return (<react_native_1.ScrollView ref={scrollRef} {...props}>
+      {props.children}
+    </react_native_1.ScrollView>);
+};
+exports.DapScrollView = DapScrollView;

package/dist/DapTarget.d.ts

@@ -2,7 +2,7 @@ import React, { ReactElement } from 'react';
 import { ViewProps } from 'react-native';
 interface DapTargetProps extends ViewProps {
     name: string;
-    children: ReactElement;
+    children: ReactElement | ReactElement[];
 }
 export declare const DapTarget: React.FC<DapTargetProps>;
 export {};

package/dist/DapTarget.js

@@ -85,7 +85,8 @@ const DapTarget = ({ name, children, ...props }) => {
                     const next = { x, y, width, height };
                     if (hasPositionChanged(lastMeasurementRef.current, next)) {
                         lastMeasurementRef.current = next;
-                        context.registerTarget(name, next);
+                        // Pass viewRef.current to enable Auto-Scroll layout measurements
+                        context.registerTarget(name, next, viewRef.current);
                     }
                 });
             }, delay);
@@ -116,7 +117,19 @@ const DapTarget = ({ name, children, ...props }) => {
             unregisterTarget?.(name);
         };
     }, [name, unregisterTarget, clearAllTimers]);
-    // collapsable={false} is vital for Android, otherwise it gets optimized away and measure fails
+    /**
+     * Auto-Scroll Trigger: If this target becomes the active step in a tour,
+     * request the provider to bring it into view.
+     */
+    (0, react_1.useEffect)(() => {
+        if (!context || !context.activeTour)
+            return;
+        const activeStep = context.activeTour.steps[context.currentStepIndex];
+        if (activeStep?.targetId === name && context.requestScroll) {
+            context.requestScroll(name);
+        }
+    }, [context?.activeTour, context?.currentStepIndex, context?.requestScroll, name]);
+    // Always use standard View wrapper (asChild reverted per user preference)
     return (<react_native_1.View ref={viewRef} onLayout={handleLayout} collapsable={false} {...props}>
       {children}
     </react_native_1.View>);

package/dist/index.d.ts

@@ -1,4 +1,6 @@
 export * from './DapProvider';
 export * from './DapTarget';
+export * from './DapOverlay';
+export * from './DapScrollView';
 export * from './useDap';
 export * from './types';

package/dist/index.js

@@ -16,5 +16,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./DapProvider"), exports);
 __exportStar(require("./DapTarget"), exports);
+__exportStar(require("./DapOverlay"), exports);
+__exportStar(require("./DapScrollView"), exports);
 __exportStar(require("./useDap"), exports);
 __exportStar(require("./types"), exports);

package/dist/types.d.ts

@@ -20,7 +20,7 @@ export interface StorageAdapter {
     setItem: (key: string, value: string) => Promise<void> | void;
 }
 export interface DapContextType {
-    registerTarget: (id: string, measurement: TargetMeasurement) => void;
+    registerTarget: (id: string, measurement: TargetMeasurement, ref?: any) => void;
     unregisterTarget: (id: string) => void;
     startTour: (tourId: string) => void;
     nextStep: () => void;
@@ -30,4 +30,8 @@ export interface DapContextType {
     currentStepIndex: number;
     targets: Record<string, TargetMeasurement>;
     seenTours: Record<string, boolean>;
+    /** Requests the provider to scroll the active DapScrollView to a specific target. */
+    requestScroll: (targetId: string) => void;
+    /** Internal use only: registers a ScrollView's native ref for coordinate calculations. */
+    _registerScrollRef: (ref: any) => void;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rn-smart-tour",
-  "version": "1.0.4",
+  "version": "1.0.7",
   "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",