Merge pull request #2 from jasongaare/v0.1-refinements

Version 0.1

Author: jasongaare

README.md

@@ -12,6 +12,12 @@ React Native Walkthrough is an app-wide walkthrough library, with a minimal foot
 yarn add react-native-walkthrough
 ```
 
+### Roadmap
+- [ ] Move library to Typescript (soon!)
+- [ ] add ability to pass external EventEmitter instance via props
+- [ ] add props for changing timeout durations
+- [ ] ???
+
 ### Basic Usage
 
 React Native Walkthrough exports the following:
@@ -20,6 +26,7 @@ React Native Walkthrough exports the following:
   - [`WalkthroughElement component`](#walkthroughelement)
   - [`startWalkthrough` function](#startwalkthrough)
   - [`dispatchWalkthroughEvent` function](#dispatchwalkthroughevent)
+  - [`goToWalkthroughElementWithId` function](#gotowalkthroughelementwithid)
 
 
 #### `WalkthroughProvider`
@@ -91,6 +98,22 @@ render (
 )
 ```
 
+#### `goToWalkthroughElementWithId`
+
+Function that accepts a string element id. Finds the first element in the current walkthrough with a matching `id` and sets that element as the current element.  
+
+```js
+import { goToWalkthroughElementWithId } from 'react-native-walkthrough';
+
+
+<TouchableOpacity
+  onPress={() => goToWalkthroughElementWithId('step-3')}
+>
+  <Text>{"Skip to next step"}</Text>
+</TouchableOpacity>
+
+```
+
 ### Creating a Walkthrough Guide
 
 A walkthrough guide is simply an array of objects, where each object correlates to a `WalkthroughElement`. Each element object in the guide must have an `id` and `content` to display in the tooltip bubble. 
@@ -135,10 +158,12 @@ export default [
 
 |Key|Type|Required|Description|
 |---|----|-----|----|
-|id|string|YES|id string that matches the corresponding WalkthroughElement|
 |content|function/Element| YES | This is the view displayed in the tooltip popover bubble |
+|id|string|YES|id string that matches the corresponding WalkthroughElement|
 |placement|string|NO | Determines placement of tooltip in relation to the element it is wrapping
-|triggerEvent|string|NO|string event id, this element will not appear until the triggerEvent is dispatched via `dispatchWalkthroughEvent`
+|possibleOutcomes|array|NO|An array of objects with keys (`event`, `action`) that creates event listeners for multiple events to provide the ability to have an outcome tree that responds to a user's actions (listens to events dispatched via `dispatchWalkthroughEvent`|
 |tooltipProps|object|NO|additional props to customize the tooltip functionality and style
+|triggerEvent|string|NO|string event id, this element will not appear until the triggerEvent is dispatched via `dispatchWalkthroughEvent`
+
 
 > To learn more about `placement` options and all the options for `tooltipProps` view the [`react-native-walkthrough-tooltip` README](https://github.com/jasongaare/react-native-walkthrough-tooltip#props)

index.js

@@ -1,12 +1,18 @@
 import WalkthroughElement from './src/WalkthroughElement';
 import WalkthroughProvider, {
   dispatchWalkthroughEvent,
+  exitWalkthrough,
+  goToWalkthroughElementWithId,
   startWalkthrough,
+  startWalkthroughAtElement,
 } from './src/WalkthroughProvider';
 
 export {
   dispatchWalkthroughEvent,
+  exitWalkthrough,
+  goToWalkthroughElementWithId,
   startWalkthrough,
+  startWalkthroughAtElement,
   WalkthroughElement,
   WalkthroughProvider,
 };

package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-native-walkthrough",
-  "version": "0.0.2",
+  "version": "0.1.0",
   "description": "A lightweight walkthrough library for React Native utilizing React's Context API",
   "main": "index.js",
   "scripts": {
@@ -18,7 +18,7 @@
   "homepage": "https://github.com/jasongaare/react-native-walkthrough#readme",
   "dependencies": {
     "events": "3.0.0",
-    "react-native-walkthrough-tooltip": "1.0.2"
+    "react-native-walkthrough-tooltip": "1.1.7"
   },
   "peerDependencies": {
     "prop-types": "^15.6.1",

src/ContextWrapper.js

@@ -1,9 +1,8 @@
-import React, {Component} from 'react';
+import React, { Component } from 'react';
 import PropTypes from 'prop-types';
-import {InteractionManager} from 'react-native';
 
 const WAIT_NO_MORE_TIMEOUT = 1000 * 60 * 10; // 10 minutes
-const HOT_SEC = 350;
+const HOT_SEC = 500;
 
 const nullElement = {
   id: null,
@@ -29,42 +28,103 @@ class ContextWrapper extends Component {
   constructor(props) {
     super(props);
 
-    this.state = {currentElement: nullElement, currentGuide: []};
+    this.state = {
+      currentElement: nullElement,
+      currentGuide: [],
+      currentPossibleOutcomes: [],
+      outcomeListenerStartTimestamp: null,
+    };
   }
 
   getCurrentElementIndex = () =>
     this.state.currentGuide.findIndex(
       element => element.id === this.state.currentElement.id,
     );
 
+  clearGuide = () => this.setState(safeSetGuide([]));
+
+  clearCurrentPossibleOutcomes = () => {
+    const { eventEmitter } = this.props;
+
+    this.state.currentPossibleOutcomes.forEach(({ event, action }) => {
+      eventEmitter.removeListener(event, action);
+    });
+
+    this.setState({
+      currentPossibleOutcomes: [],
+      outcomeListenerStartTimestamp: null,
+    });
+  };
+
+  addTimeoutCheckToOutcomeActions = ({ event, action: originalAction }) => ({
+    event,
+    action: () => {
+      const { outcomeListenerStartTimestamp } = this.state;
+
+      if (Date.now() - outcomeListenerStartTimestamp >= WAIT_NO_MORE_TIMEOUT) {
+        this.clearGuide();
+      } else {
+        originalAction();
+      }
+
+      this.clearCurrentPossibleOutcomes();
+    },
+  });
+
+  listenForPossibleOutcomes = element => {
+    const { eventEmitter } = this.props;
+    const { possibleOutcomes } = element;
+
+    if (possibleOutcomes) {
+      if (!Array.isArray(possibleOutcomes)) {
+        console.warn(
+          '[react-native-walkthrough] non-Array value provided to possibleOutcomes',
+        );
+      } else {
+        this.setState(
+          {
+            currentPossibleOutcomes: possibleOutcomes.map(
+              this.addTimeoutCheckToOutcomeActions,
+            ),
+            outcomeListenerStartTimestamp: Date.now(),
+          },
+          () => {
+            this.state.currentPossibleOutcomes.forEach(({ event, action }) =>
+              eventEmitter.once(event, action),
+            );
+          },
+        );
+      }
+    }
+  };
+
+  setElementNull = () => this.setState(safeSetElement(nullElement));
+
   setElement = element => {
     if (element.id !== this.state.currentElement.id) {
       // clear previous element
-      this.setState(safeSetElement(nullElement));
-
-      // after interactions and a hot sec, set current element
-      InteractionManager.runAfterInteractions(() => {
-        setTimeout(() => {
-          this.setState(safeSetElement(element));
-        }, HOT_SEC);
-      });
+      this.setElementNull();
+      this.clearCurrentPossibleOutcomes();
+
+      // after a hot sec, set current element
+      setTimeout(() => {
+        this.setState(safeSetElement(element));
+      }, HOT_SEC);
     }
   };
 
-  setGuide = (guide, callback = () => {}) =>
+  setGuide = (guide, callback = () => {}) => {
+    this.setElementNull();
     this.setState(safeSetGuide(guide), callback);
-
-  setNull = () => this.setState(safeSetElement(nullElement));
-
-  clearGuide = () => this.setState(safeSetGuide([]));
+  };
 
   waitForTrigger = element => {
-    const {eventEmitter} = this.props;
+    const { eventEmitter } = this.props;
 
     const waitStart = Date.now();
     const triggerGuide = JSON.stringify(this.state.currentGuide);
 
-    this.setNull();
+    this.setElementNull();
 
     eventEmitter.once(element.triggerEvent, () => {
       const waitEnd = Date.now();
@@ -87,13 +147,27 @@ class ContextWrapper extends Component {
     }
   };
 
+  goToElementWithId = id => {
+    const elementWithId = this.state.currentGuide.find(
+      element => element.id === id,
+    );
+
+    if (elementWithId) {
+      this.goToElement(elementWithId);
+    }
+  };
+
   goToNext = () => {
+    const { currentElement } = this.state;
     const nextIndex = this.getCurrentElementIndex() + 1;
 
-    if (nextIndex < this.state.currentGuide.length) {
+    if (currentElement.possibleOutcomes) {
+      this.listenForPossibleOutcomes(currentElement);
+      this.setElementNull();
+    } else if (nextIndex < this.state.currentGuide.length) {
       this.goToElement(this.state.currentGuide[nextIndex]);
     } else {
-      this.setNull();
+      this.setElementNull();
       this.clearGuide();
     }
   };
@@ -104,7 +178,8 @@ class ContextWrapper extends Component {
         value={{
           ...this.state,
           goToNext: this.goToNext,
-        }}>
+        }}
+      >
         {this.props.children}
       </WalkthroughContext.Provider>
     );

src/WalkthroughElement.js

@@ -4,7 +4,7 @@ import Tooltip, {
   TooltipChildrenContext,
 } from 'react-native-walkthrough-tooltip';
 
-import {WalkthroughContext} from './ContextWrapper';
+import { WalkthroughContext } from './ContextWrapper';
 
 const WalkthroughElement = props => {
   const elementId = props.id;
@@ -14,13 +14,19 @@ const WalkthroughElement = props => {
 
   return (
     <WalkthroughContext.Consumer>
-      {({currentElement, goToNext}) => {
+      {({ currentElement, goToNext }) => {
         const defaultTooltipProps = {
           useInteractionManager: true,
           isVisible: elementId === currentElement.id,
           content: props.content || currentElement.content,
           placement: currentElement.placement || defaultPlacement,
-          onClose: goToNext,
+          onClose: () => {
+            goToNext();
+
+            if (typeof currentElement.onClose === 'function') {
+              currentElement.onClose();
+            }
+          },
         };
 
         const tooltipProps = {

src/WalkthroughProvider.js

@@ -7,25 +7,33 @@ import ContextWrapper from './ContextWrapper';
 const wrapperRef = React.createRef();
 const ee = new EventEmitter();
 
-const WalkthroughProvider = ({children}) => (
+const WalkthroughProvider = ({ children }) => (
   <ContextWrapper ref={wrapperRef} eventEmitter={ee}>
     {children}
   </ContextWrapper>
 );
 
+const goToWalkthroughElementWithId = id => {
+  const { current: wrapper } = wrapperRef;
+
+  if (wrapper && typeof wrapper.goToElementWithId === 'function') {
+    wrapper.goToElementWithId(id);
+  }
+};
+
 const goToWalkthroughElement = element => {
-  const {current: wrapper} = wrapperRef;
+  const { current: wrapper } = wrapperRef;
 
   if (wrapper && typeof wrapper.goToElement === 'function') {
     wrapper.goToElement(element);
   }
 };
 
-const setWalkthroughGuide = (guide, setGuide) => {
-  const {current: wrapper} = wrapperRef;
+const setWalkthroughGuide = (guide, callback) => {
+  const { current: wrapper } = wrapperRef;
 
   if (wrapper && typeof wrapper.setElement === 'function') {
-    wrapper.setGuide(guide, setGuide);
+    wrapper.setGuide(guide, callback);
   }
 };
 
@@ -41,11 +49,31 @@ const startWalkthrough = walkthrough => {
   }
 };
 
+const startWalkthroughAtElement = (walkthrough, elementId) => {
+  if (Array.isArray(walkthrough)) {
+    setWalkthroughGuide(walkthrough, () => {
+      goToWalkthroughElementWithId(elementId);
+    });
+  } else {
+    console.warn(
+      '[react-native-walkthrough] non-Array argument provided to startWalkthroughAtElement',
+    );
+  }
+};
+
 const dispatchWalkthroughEvent = event => ee.emit(event);
 
+const exitWalkthrough = () => startWalkthrough([{}]);
+
 WalkthroughProvider.propTypes = {
   children: PropTypes.element,
 };
 
-export {dispatchWalkthroughEvent, startWalkthrough};
+export {
+  dispatchWalkthroughEvent,
+  exitWalkthrough,
+  goToWalkthroughElementWithId,
+  startWalkthrough,
+  startWalkthroughAtElement,
+};
 export default WalkthroughProvider;