rn-smart-tour 1.0.0

package/README.md

@@ -0,0 +1,107 @@
+# react-native-app-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.
+
+## Features
+- **Auto-Start Engine**: Automatically triggers tours the moment specific features mount on the screen.
+- **Seen State Caching**: Provide any storage adapter (`AsyncStorage`, `MMKV`) to ensure users only see tours once.
+- **Zero Config Measurement**: Wraps your components and seamlessly uses Native `measureInWindow` API.
+- **Smart Overlays**: Creates highlighted holes in backdrops over completely custom UIs.
+
+## Installation
+
+```sh
+npm install rn-smart-tour
+```
+
+## Quick Start Guide
+
+### 1. Wrap your App with the Provider
+
+Create your `tours` configuration and mount `<DapProvider>` at the root of your application (above your Navigators):
+
+```tsx
+import React from 'react';
+import { DapProvider } from 'rn-smart-tour';
+import AsyncStorage from '@react-native-async-storage/async-storage'; // Optional, but recommended
+
+const TOURS = {
+  'onboarding-flow': {
+    id: 'onboarding-flow',
+    autoStart: true, // Will automatically start when the first target renders
+    steps: [
+      {
+        targetId: 'save-playlist-btn',
+        title: 'Save your work',
+        description: 'Tap this heart to save your favorite songs anytime.',
+      }
+    ]
+  }
+};
+
+// Map any storage library you prefer so it remembers if users have seen the tour!
+const storageAdapter = {
+  getItem: async (key) => await AsyncStorage.getItem(key),
+  setItem: async (key, value) => { await AsyncStorage.setItem(key, value); }
+};
+
+export default function App() {
+  return (
+    <DapProvider tours={TOURS} storageAdapter={storageAdapter}>
+      <MainAppScreen />
+    </DapProvider>
+  );
+}
+```
+
+### 2. Wrap the targets you want to highlight
+
+Go to any deep-nested screen and wrap buttons or views with `<DapTarget name="targetId">`:
+
+```tsx
+import { DapTarget } from 'rn-smart-tour';
+
+const MainAppScreen = () => {
+  return (
+    <View style={{ flex: 1, justifyContent: 'center', alignItems: 'center' }}>
+      <DapTarget name="save-playlist-btn">
+         <TouchableOpacity style={{ backgroundColor: 'red', padding: 15 }}>
+            <Text>❤️ Add to Favorites</Text>
+         </TouchableOpacity>
+      </DapTarget>
+    </View>
+  );
+};
+```
+
+### 3. Trigger tours Manually (Optional)
+
+If a tour lacks `autoStart: true` or you want to trigger it from a "Help" menu, use the `useDap` hook:
+
+```tsx
+import { useDap } from 'rn-smart-tour';
+
+const HelpMenu = () => {
+    const { startTour } = useDap();
+    
+    return (
+        <Button title="Need help?" onPress={() => startTour('onboarding-flow')} />
+    );
+}
+```
+
+## Advanced Properties & Types
+
+### Tour Object
+| 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. |
+
+### TourStep Object
+| Property | Type | 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. |

package/dist/DapContext.d.ts

@@ -0,0 +1,2 @@
+import { DapContextType } from './types';
+export declare const DapContext: import("react").Context<DapContextType | null>;

package/dist/DapContext.js

@@ -0,0 +1,5 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DapContext = void 0;
+const react_1 = require("react");
+exports.DapContext = (0, react_1.createContext)(null);

package/dist/DapOverlay.d.ts

@@ -0,0 +1,2 @@
+import React from 'react';
+export declare const DapOverlay: () => React.JSX.Element | null;

package/dist/DapOverlay.js

@@ -0,0 +1,145 @@
+"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.DapOverlay = void 0;
+const react_1 = __importStar(require("react"));
+const react_native_1 = require("react-native");
+const DapContext_1 = require("./DapContext");
+const { width: SCREEN_WIDTH, height: SCREEN_HEIGHT } = react_native_1.Dimensions.get('window');
+const DapOverlay = () => {
+    const context = (0, react_1.useContext)(DapContext_1.DapContext);
+    if (!context || !context.activeTour)
+        return null;
+    const { activeTour, currentStepIndex, targets, nextStep, stopTour } = context;
+    const currentStep = activeTour.steps[currentStepIndex];
+    if (!currentStep)
+        return null;
+    const targetId = currentStep.targetId;
+    const measurement = targets[targetId];
+    // If the target hasn't been measured yet, we can't show the overlay correctly.
+    if (!measurement) {
+        return (<react_native_1.Modal transparent visible animationType="fade">
+         <react_native_1.View style={styles.fullscreen}>
+           <react_native_1.Text style={{ color: 'white', marginTop: 100, textAlign: 'center' }}>
+             Waiting for target "{targetId}" to mount...
+           </react_native_1.Text>
+         </react_native_1.View>
+       </react_native_1.Modal>);
+    }
+    const { x, y, width, height } = measurement;
+    return (<react_native_1.Modal transparent visible animationType="fade">
+      <react_native_1.View style={styles.fullscreen}>
+        {/* Top backdrop */}
+        <react_native_1.View style={[styles.backdrop, { top: 0, left: 0, right: 0, height: Math.max(0, y) }]}/>
+        {/* Bottom backdrop */}
+        <react_native_1.View style={[styles.backdrop, { top: y + height, left: 0, right: 0, bottom: 0 }]}/>
+        {/* Left backdrop */}
+        <react_native_1.View style={[styles.backdrop, { top: y, left: 0, width: Math.max(0, x), height }]}/>
+        {/* Right backdrop */}
+        <react_native_1.View style={[styles.backdrop, { top: y, left: x + width, right: 0, height }]}/>
+
+        {/* The Tooltip Card */}
+        <react_native_1.View style={[styles.tooltipContainer, { top: y + height + 10, left: Math.max(10, x - 20) }]}>
+          <react_native_1.Text style={styles.title}>{currentStep.title}</react_native_1.Text>
+          <react_native_1.Text style={styles.description}>{currentStep.description}</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>
+            <react_native_1.TouchableOpacity onPress={nextStep} style={[styles.actionBtn, styles.primaryBtn]}>
+              <react_native_1.Text style={[styles.actionText, styles.primaryText]}>
+                {currentStepIndex === activeTour.steps.length - 1 ? 'Finish' : 'Next'}
+              </react_native_1.Text>
+            </react_native_1.TouchableOpacity>
+          </react_native_1.View>
+        </react_native_1.View>
+      </react_native_1.View>
+    </react_native_1.Modal>);
+};
+exports.DapOverlay = DapOverlay;
+const styles = react_native_1.StyleSheet.create({
+    fullscreen: {
+        ...react_native_1.StyleSheet.absoluteFillObject,
+    },
+    backdrop: {
+        position: 'absolute',
+        backgroundColor: 'rgba(0, 0, 0, 0.6)',
+    },
+    tooltipContainer: {
+        position: 'absolute',
+        backgroundColor: 'white',
+        padding: 16,
+        borderRadius: 8,
+        width: 250,
+        shadowColor: '#000',
+        shadowOffset: { width: 0, height: 2 },
+        shadowOpacity: 0.25,
+        shadowRadius: 3.84,
+        elevation: 5,
+    },
+    title: {
+        fontSize: 16,
+        fontWeight: 'bold',
+        marginBottom: 8,
+        color: '#333',
+    },
+    description: {
+        fontSize: 14,
+        color: '#666',
+        marginBottom: 16,
+    },
+    actions: {
+        flexDirection: 'row',
+        justifyContent: 'flex-end',
+        marginTop: 10,
+    },
+    actionBtn: {
+        paddingHorizontal: 15,
+        paddingVertical: 8,
+        marginLeft: 10,
+        borderRadius: 4,
+    },
+    primaryBtn: {
+        backgroundColor: '#007AFF',
+    },
+    actionText: {
+        color: '#666',
+        fontWeight: '600',
+    },
+    primaryText: {
+        color: 'white',
+        fontWeight: '600',
+    },
+});

package/dist/DapProvider.d.ts

@@ -0,0 +1,8 @@
+import React from 'react';
+import { Tour, StorageAdapter } from './types';
+export interface DapProviderProps {
+    children: React.ReactNode;
+    tours: Record<string, Tour>;
+    storageAdapter?: StorageAdapter;
+}
+export declare const DapProvider: React.FC<DapProviderProps>;

package/dist/DapProvider.js

@@ -0,0 +1,154 @@
+"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.DapProvider = void 0;
+const react_1 = __importStar(require("react"));
+const DapContext_1 = require("./DapContext");
+const DapOverlay_1 = require("./DapOverlay");
+const STORAGE_KEY = '@rn-dap:seen_tours';
+const DapProvider = ({ children, tours, storageAdapter }) => {
+    const [targets, setTargets] = (0, react_1.useState)({});
+    const [activeTourId, setActiveTourId] = (0, react_1.useState)(null);
+    const [currentStepIndex, setCurrentStepIndex] = (0, react_1.useState)(0);
+    const [seenTours, setSeenTours] = (0, react_1.useState)({});
+    const [isStorageLoaded, setIsStorageLoaded] = (0, react_1.useState)(!storageAdapter);
+    // Load seen tours on mount if a storage adapter is provided
+    (0, react_1.useEffect)(() => {
+        const loadStorage = async () => {
+            if (storageAdapter) {
+                try {
+                    const stored = await storageAdapter.getItem(STORAGE_KEY);
+                    if (stored) {
+                        setSeenTours(JSON.parse(stored));
+                    }
+                }
+                catch (e) {
+                    console.error('[rn-dap] failed to load storage', e);
+                }
+                setIsStorageLoaded(true);
+            }
+        };
+        loadStorage();
+    }, [storageAdapter]);
+    const saveSeenTour = async (tourId) => {
+        const nextSeen = { ...seenTours, [tourId]: true };
+        setSeenTours(nextSeen);
+        if (storageAdapter) {
+            try {
+                await storageAdapter.setItem(STORAGE_KEY, JSON.stringify(nextSeen));
+            }
+            catch (e) {
+                console.error('[rn-dap] failed to save storage', e);
+            }
+        }
+    };
+    const registerTarget = (0, react_1.useCallback)((id, measurement) => {
+        setTargets(prev => ({ ...prev, [id]: measurement }));
+    }, []);
+    const unregisterTarget = (0, react_1.useCallback)((id) => {
+        setTargets(prev => {
+            const next = { ...prev };
+            delete next[id];
+            return next;
+        });
+    }, []);
+    const startTour = (0, react_1.useCallback)((tourId) => {
+        if (tours[tourId] && !seenTours[tourId]) {
+            setActiveTourId(tourId);
+            setCurrentStepIndex(0);
+        }
+        else if (!tours[tourId]) {
+            console.warn(`[rn-dap] Tour with id ${tourId} not found.`);
+        }
+    }, [tours, seenTours]);
+    const stopTour = (0, react_1.useCallback)((markAsSeen = true) => {
+        if (activeTourId && markAsSeen) {
+            saveSeenTour(activeTourId);
+        }
+        setActiveTourId(null);
+        setCurrentStepIndex(0);
+    }, [activeTourId, seenTours]);
+    const nextStep = (0, react_1.useCallback)(() => {
+        if (activeTourId && tours[activeTourId]) {
+            const tour = tours[activeTourId];
+            if (currentStepIndex < tour.steps.length - 1) {
+                setCurrentStepIndex(prev => prev + 1);
+            }
+            else {
+                // Finished the last step
+                stopTour(true);
+            }
+        }
+    }, [activeTourId, currentStepIndex, tours, stopTour]);
+    const prevStep = (0, react_1.useCallback)(() => {
+        if (currentStepIndex > 0) {
+            setCurrentStepIndex(prev => prev - 1);
+        }
+    }, [currentStepIndex]);
+    // Auto-Start Engine
+    (0, react_1.useEffect)(() => {
+        // Wait until storage is loaded, and ensure no tour is currently running
+        if (!isStorageLoaded || activeTourId)
+            return;
+        for (const tourId of Object.keys(tours)) {
+            const tour = tours[tourId];
+            if (tour.autoStart && !seenTours[tourId] && 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
+                }
+            }
+        }
+    }, [targets, tours, seenTours, isStorageLoaded, activeTourId, startTour]);
+    const activeTour = activeTourId ? tours[activeTourId] : null;
+    return (<DapContext_1.DapContext.Provider value={{
+            registerTarget,
+            unregisterTarget,
+            startTour,
+            stopTour,
+            nextStep,
+            prevStep,
+            activeTour,
+            currentStepIndex,
+            targets,
+            seenTours
+        }}>
+      {children}
+      <DapOverlay_1.DapOverlay />
+    </DapContext_1.DapContext.Provider>);
+};
+exports.DapProvider = DapProvider;

package/dist/DapTarget.d.ts

@@ -0,0 +1,8 @@
+import React, { ReactElement } from 'react';
+import { ViewProps } from 'react-native';
+interface DapTargetProps extends ViewProps {
+    name: string;
+    children: ReactElement;
+}
+export declare const DapTarget: React.FC<DapTargetProps>;
+export {};

package/dist/DapTarget.js

@@ -0,0 +1,70 @@
+"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.DapTarget = void 0;
+const react_1 = __importStar(require("react"));
+const react_native_1 = require("react-native");
+const DapContext_1 = require("./DapContext");
+const DapTarget = ({ name, children, ...props }) => {
+    const viewRef = (0, react_1.useRef)(null);
+    const context = (0, react_1.useContext)(DapContext_1.DapContext);
+    const measureAndRegister = () => {
+        if (viewRef.current && context) {
+            setTimeout(() => {
+                viewRef.current?.measureInWindow((x, y, width, height) => {
+                    if (width > 0 && height > 0) {
+                        context.registerTarget(name, { x, y, width, height });
+                    }
+                });
+            }, 100);
+        }
+    };
+    const handleLayout = (e) => {
+        measureAndRegister();
+        if (props.onLayout) {
+            props.onLayout(e);
+        }
+    };
+    (0, react_1.useEffect)(() => {
+        return () => {
+            context?.unregisterTarget(name);
+        };
+    }, [name, context]);
+    // collapsable={false} is vital for Android, otherwise it gets optimized away and measure fails
+    return (<react_native_1.View ref={viewRef} onLayout={handleLayout} collapsable={false} {...props}>
+      {children}
+    </react_native_1.View>);
+};
+exports.DapTarget = DapTarget;

package/dist/index.d.ts

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

package/dist/index.js

@@ -0,0 +1,20 @@
+"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 __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./DapProvider"), exports);
+__exportStar(require("./DapTarget"), exports);
+__exportStar(require("./useDap"), exports);
+__exportStar(require("./types"), exports);

package/dist/types.d.ts

@@ -0,0 +1,33 @@
+export interface TargetMeasurement {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+export interface TourStep {
+    targetId: string;
+    title: string;
+    description: string;
+    position?: 'top' | 'bottom' | 'left' | 'right';
+}
+export interface Tour {
+    id: string;
+    steps: TourStep[];
+    autoStart?: boolean;
+}
+export interface StorageAdapter {
+    getItem: (key: string) => Promise<string | null> | string | null;
+    setItem: (key: string, value: string) => Promise<void> | void;
+}
+export interface DapContextType {
+    registerTarget: (id: string, measurement: TargetMeasurement) => void;
+    unregisterTarget: (id: string) => void;
+    startTour: (tourId: string) => void;
+    nextStep: () => void;
+    prevStep: () => void;
+    stopTour: () => void;
+    activeTour: Tour | null;
+    currentStepIndex: number;
+    targets: Record<string, TargetMeasurement>;
+    seenTours: Record<string, boolean>;
+}

package/dist/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/useDap.d.ts

@@ -0,0 +1 @@
+export declare const useDap: () => import("./types").DapContextType;

package/dist/useDap.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useDap = void 0;
+const react_1 = require("react");
+const DapContext_1 = require("./DapContext");
+const useDap = () => {
+    const context = (0, react_1.useContext)(DapContext_1.DapContext);
+    if (!context) {
+        throw new Error('useDap must be used within a DapProvider');
+    }
+    return context;
+};
+exports.useDap = useDap;

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "rn-smart-tour",
+  "version": "1.0.0",
+  "description": "Enterprise-grade Digital Adoption Platform (DAP) package for React Native. Provides guided walkthroughs, tooltips, and app tours.",
+  "author": "Vishwas Gaur",
+  "license": "MIT",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "keywords": [
+    "react-native",
+    "tour",
+    "walkthrough",
+    "onboarding",
+    "dap",
+    "guide",
+    "product-tour"
+  ],
+  "scripts": {
+    "build": "tsc"
+  },
+  "peerDependencies": {
+    "react": "*",
+    "react-native": "*"
+  },
+  "devDependencies": {
+    "@types/react": "^18.3.28",
+    "@types/react-native": "^0.72.8",
+    "react": "^19.2.4",
+    "react-native": "^0.84.1",
+    "typescript": "^5.9.3"
+  }
+}