rn-smart-tour 1.0.5 → 1.0.8

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,12 +127,18 @@ 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. |
-| `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. |
 
 ### TourStep

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,15 +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 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);
+    /** 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 () => {
@@ -81,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);
                 });
@@ -89,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 => {
@@ -98,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]) {
@@ -114,7 +141,6 @@ const DapProvider = ({ children, tours, storageAdapter }) => {
             if (markAsSeen) {
                 saveSeenTour(currentTourId);
             }
-            // Block this specific tour from auto-restarting until coordinates or seenTours settle.
             tourIdJustStoppedRef.current = currentTourId;
         }
         setActiveTourId(null);
@@ -127,7 +153,6 @@ const DapProvider = ({ children, tours, storageAdapter }) => {
                 setCurrentStepIndex(prev => prev + 1);
             }
             else {
-                // Finished the last step
                 stopTour(true);
             }
         }
@@ -137,32 +162,25 @@ 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];
-                // 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]) {
                         startTour(tourId);
-                        break; // Start only one auto-tour at a time
+                        break;
                     }
                 }
             }
-            // Cleanup the "just stopped" ref once the seenTours state finally reflects the closure.
             if (tourIdJustStoppedRef.current && seenTours[tourIdJustStoppedRef.current]) {
                 tourIdJustStoppedRef.current = null;
             }
@@ -184,7 +202,9 @@ const DapProvider = ({ children, tours, storageAdapter }) => {
         activeTour,
         currentStepIndex,
         targets,
-        seenTours
+        seenTours,
+        requestScroll,
+        _registerScrollRef
     }), [
         registerTarget,
         unregisterTarget,
@@ -195,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,13 +2,7 @@ import React, { ReactElement } from 'react';
 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;
+    children: ReactElement | ReactElement[];
 }
 export declare const DapTarget: React.FC<DapTargetProps>;
 export {};

package/dist/DapTarget.js

@@ -45,22 +45,7 @@ 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;
-/**
- * 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 DapTarget = ({ name, children, ...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. */
@@ -100,7 +85,8 @@ const DapTarget = ({ name, children, asChild, ...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);
@@ -131,26 +117,19 @@ const DapTarget = ({ name, children, asChild, ...props }) => {
             unregisterTarget?.(name);
         };
     }, [name, unregisterTarget, clearAllTimers]);
-    // 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.');
+    /**
+     * 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);
         }
-    }
-    // Fallback to standard View wrapper
+    }, [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,9 +1,17 @@
 {
   "name": "rn-smart-tour",
-  "version": "1.0.5",
+  "version": "1.0.8",
   "description": "Enterprise-grade Digital Adoption Platform (DAP) package for React Native. Provides guided walkthroughs, tooltips, and app tours.",
   "author": "Vishwas Gaur",
   "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Vishwasgaur0819/rn-smart-tour.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Vishwasgaur0819/rn-smart-tour/issues"
+  },
+  "homepage": "https://github.com/Vishwasgaur0819/rn-smart-tour#readme",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "files": [
@@ -36,4 +44,4 @@
     "react-native": "0.73.11",
     "typescript": "^5.9.3"
   }
-}
+}