Merge pull request #266 from qboot/feature/observables

Adding new step props: observables + highlight selectors

Author: elrumordelaluz

README.md

@@ -337,6 +337,9 @@ steps: PropTypes.arrayOf(PropTypes.shape({
   'stepInteraction': PropTypes.bool,
   'navDotAriaLabel': PropTypes.string,
   'observe': PropTypes.string,
+  'highlightedSelectors': PropTypes.array,
+  'mutationObservables': PropTypes.array,
+  'resizeObservables': PropTypes.array,
 })),
 ```
 
@@ -374,6 +377,19 @@ const steps = [
     // If a child is added: the highlighted region is redrawn focused on it
     // If a child is removed: the highlighted region is redrawn focused on the step selector node
     observe: '[data-tour="observable-parent"]',
+    // Array of selectors, each selected node will be included (by union)
+    // in the highlighted region of the mask. You don't need to add the 
+    // step selector here as the default highlighted region is focused on it
+    highlightedSelectors: ['[data-tour="highlighted-element"]'],
+    // Array of selectors, each selected node DOM addition/removal will triggered a rerender
+    // of the mask shape. Useful in combinaison with highlightedSelectors when highlighted
+    // region of mask should be redrawn after a user action
+    mutationObservables: ['[data-tour="mutable-element"]'],
+    // Array of selectors, each selected node resize will triggered a rerender of the mask shape.
+    // Useful in combinaison with highlightedSelectors when highlighted region of mask should
+    // be redrawn after a user action. You should also add the selector in mutationObservables
+    // if you want to track DOM addition/removal too
+    resizeObservables: ['[data-tour="resizable-parent"]'],
   },
   // ...
 ]

src/Tour.js

@@ -14,6 +14,8 @@ import {
   Navigation,
   Dot,
   SvgMask,
+  ResizeObserver as ReactourResizeObserver,
+  MutationObserver as ReactourMutationObserver,
 } from './components/index'
 import Portal from './Portal'
 import * as hx from './helpers'
@@ -153,20 +155,15 @@ class Tour extends Component {
                 ) {
                   const cb = () => stepCallback(mutation.addedNodes[0])
                   setTimeout(
-                    () =>
-                      this.calculateNode(
-                        mutation.addedNodes[0],
-                        step.position,
-                        cb
-                      ),
+                    () => this.calculateNode(mutation.addedNodes[0], step, cb),
                     100
                   )
                 } else if (
                   mutation.type === 'childList' &&
                   mutation.removedNodes.length > 0
                 ) {
                   const cb = () => stepCallback(node)
-                  this.calculateNode(node, step.position, cb)
+                  this.calculateNode(node, step, cb)
                 }
               })
             }),
@@ -185,12 +182,9 @@ class Tour extends Component {
 
     if (node) {
       const cb = () => stepCallback(node)
-      this.calculateNode(node, step.position, cb)
+      this.calculateNode(node, step, cb)
     } else {
-      this.setState(
-        setNodeState(null, this.helper.current, step.position),
-        stepCallback
-      )
+      this.setState(setNodeState(null, step, this.helper.current), stepCallback)
 
       step.selector &&
         console.warn(
@@ -199,9 +193,9 @@ class Tour extends Component {
     }
   }
 
-  calculateNode = (node, stepPosition, cb) => {
+  calculateNode = (node, step, cb) => {
     const { scrollDuration, inViewThreshold, scrollOffset } = this.props
-    const attrs = hx.getNodeRect(node)
+    const attrs = hx.getHighlightedRect(node, step)
     const w = Math.max(
       document.documentElement.clientWidth,
       window.innerWidth || 0
@@ -222,14 +216,25 @@ class Tour extends Component {
         duration: scrollDuration,
         offset,
         callback: nd => {
-          this.setState(setNodeState(nd, this.helper.current, stepPosition), cb)
+          this.setState(setNodeState(nd, step, this.helper.current), cb)
         },
       })
     } else {
-      this.setState(setNodeState(node, this.helper.current, stepPosition), cb)
+      this.setState(setNodeState(node, step, this.helper.current), cb)
     }
   }
 
+  recalculateNode = step => {
+    const node = document.querySelector(step.selector)
+    const stepCallback = o => {
+      if (step.action && typeof step.action === 'function') {
+        this.unlockFocus(() => step.action(o))
+      }
+    }
+
+    this.calculateNode(node, step, () => stepCallback(node))
+  }
+
   close() {
     this.setState(prevState => {
       if (prevState.observer) {
@@ -401,6 +406,14 @@ class Tour extends Component {
       return (
         <Portal>
           <GlobalStyle />
+          <ReactourResizeObserver
+            step={steps[current]}
+            refresh={() => this.recalculateNode(steps[current])}
+          />
+          <ReactourMutationObserver
+            step={steps[current]}
+            refresh={() => this.recalculateNode(steps[current])}
+          />
           <SvgMask
             onClick={this.maskClickHandler}
             forwardRef={c => (this.mask = c)}
@@ -567,7 +580,7 @@ class Tour extends Component {
   }
 }
 
-const setNodeState = (node, helper, position) => {
+const setNodeState = (node, step, helper) => {
   const w = Math.max(
     document.documentElement.clientWidth,
     window.innerWidth || 0
@@ -578,26 +591,29 @@ const setNodeState = (node, helper, position) => {
   )
   const { width: helperWidth, height: helperHeight } = hx.getNodeRect(helper)
 
-  const attrs = node
-    ? hx.getNodeRect(node)
-    : {
-        top: h + 10,
-        right: w / 2 + 9,
-        bottom: h / 2 + 9,
-        left: w / 2 - helperWidth / 2,
-        width: 0,
-        height: 0,
-        w,
-        h,
-        helperPosition: 'center',
-      }
+  let attrs = {
+    top: h + 10,
+    right: w / 2 + 9,
+    bottom: h / 2 + 9,
+    left: w / 2 - helperWidth / 2,
+    width: 0,
+    height: 0,
+    w,
+    h,
+    helperPosition: 'center',
+  }
+
+  if (node) {
+    attrs = hx.getHighlightedRect(node, step)
+  }
+
   return function update() {
     return {
       w,
       h,
       helperWidth,
       helperHeight,
-      helperPosition: position,
+      helperPosition: step.position,
       ...attrs,
       inDOM: node ? true : false,
     }

src/components/MutationObserver.js

@@ -0,0 +1,48 @@
+import { useEffect } from 'react'
+
+export default ({ step, refresh }) => {
+  useEffect(() => {
+    if (!step.mutationObservables) {
+      return
+    }
+
+    const refreshHighlightedRegionIfObservable = nodes => {
+      for (const node of nodes) {
+        if (!node.attributes) {
+          continue
+        }
+
+        const found = step.mutationObservables.find(observable =>
+          node.matches(observable)
+        )
+
+        if (found) {
+          refresh()
+        }
+      }
+    }
+
+    const mutationObserver = new MutationObserver(mutationsList => {
+      for (const mutation of mutationsList) {
+        if (0 !== mutation.addedNodes.length) {
+          refreshHighlightedRegionIfObservable(mutation.addedNodes)
+        }
+
+        if (0 !== mutation.removedNodes.length) {
+          refreshHighlightedRegionIfObservable(mutation.removedNodes)
+        }
+      }
+    })
+
+    const observable = document.documentElement || document.body
+    const config = { childList: true, subtree: true }
+
+    mutationObserver.observe(observable, config)
+
+    return () => {
+      mutationObserver.disconnect()
+    }
+  }, [step])
+
+  return null
+}

src/components/ResizeObserver.js

@@ -0,0 +1,75 @@
+import { useEffect, useState } from 'react'
+
+export default ({ step, refresh }) => {
+  const [mutationsCounter, setMutationsCounter] = useState(0)
+
+  // only use to notify main logic below
+  // that a resizeObservable has been added to DOM (or removed from it)
+  useEffect(() => {
+    if (!step.resizeObservables) {
+      return
+    }
+
+    const incrementMutationsCounterIfObservable = nodes => {
+      for (const node of nodes) {
+        if (!node.attributes) {
+          continue
+        }
+
+        const found = step.resizeObservables.find(observable =>
+          node.matches(observable)
+        )
+
+        if (found) {
+          setMutationsCounter(mutationsCounter + 1)
+        }
+      }
+    }
+
+    const mutationObserver = new MutationObserver(mutationsList => {
+      for (const mutation of mutationsList) {
+        if (0 !== mutation.addedNodes.length) {
+          incrementMutationsCounterIfObservable(mutation.addedNodes)
+        }
+
+        if (0 !== mutation.removedNodes.length) {
+          incrementMutationsCounterIfObservable(mutation.removedNodes)
+        }
+      }
+    })
+
+    const observable = document.documentElement || document.body
+    const config = { childList: true, subtree: true }
+
+    mutationObserver.observe(observable, config)
+
+    return () => {
+      mutationObserver.disconnect()
+    }
+  }, [step, mutationsCounter])
+
+  // the main logic is here
+  useEffect(() => {
+    if (!step.resizeObservables) {
+      return
+    }
+
+    const resizeObserver = new ResizeObserver(entries => {
+      refresh()
+    })
+
+    for (const observable of step.resizeObservables) {
+      const element = document.querySelector(observable)
+
+      if (element) {
+        resizeObserver.observe(element)
+      }
+    }
+
+    return () => {
+      resizeObserver.disconnect()
+    }
+  }, [step, mutationsCounter])
+
+  return null
+}

src/components/index.js

@@ -6,3 +6,5 @@ export { default as Controls } from './Controls'
 export { default as Navigation } from './Navigation'
 export { default as Dot } from './Dot'
 export { default as SvgMask } from './SvgMask'
+export { default as ResizeObserver } from './ResizeObserver'
+export { default as MutationObserver } from './MutationObserver'

src/demo/App.js

@@ -246,6 +246,14 @@ const tourConfig = [
     observe: '[data-tut="reactour__state--observe"]',
     action: node => node.focus(),
   },
+  {
+    selector: '[data-tut="reactour__highlighted"]',
+    content:
+      'Moreover you can highlight multiple elements and adjust highlighted region depending on DOM resizes and mutations. Try clicking the "?" tooltip and playing with tabs...',
+    highlightedSelectors: ['[data-tut="reactour__highlighted-absolute-child"]'],
+    mutationObservables: ['[data-tut="reactour__highlighted-absolute-child"]'],
+    resizeObservables: ['[data-tut="reactour__highlighted-absolute-child"]'],
+  },
 ]
 
 export default App

src/demo/Demo.js

@@ -1,4 +1,5 @@
 import React from 'react'
+import PropTypes from 'prop-types'
 import Section from './Section'
 import Logo from './Logo'
 import Text from './Text'
@@ -9,7 +10,8 @@ import Scrollable from './Scrollable'
 import Footer from './Footer'
 import Image from './Image'
 import { Button, Link } from './Button'
-import PropTypes from 'prop-types'
+import Dropdown from './Dropdown'
+import Tabs from './Tabs'
 
 export default function Demo({ openTour, isShowingMore, toggleShowMore }) {
   return (
@@ -168,7 +170,38 @@ export default function Demo({ openTour, isShowingMore, toggleShowMore }) {
 
         <Row>
           <Box align="right">
-            <Heading h="2">109 Baptist St</Heading>
+            <Heading
+              h="2"
+              style={{
+                display: 'flex',
+                alignItems: 'center',
+                justifyContent: 'flex-end',
+              }}
+              data-tut="reactour__highlighted"
+            >
+              109 Baptist St
+              <Dropdown>
+                <Tabs>
+                  <Tabs.Tab>
+                    This is a div in absolute position which will be in the
+                    highlighted region of the mask when tour is running.
+                  </Tabs.Tab>
+                  <Tabs.Tab>
+                    This is a long text which demonstrates how resizeObservables
+                    works. Lorem ipsum dolor sit amet, consectetur adipisicing
+                    elit. Optio neque vero consequuntur recusandae, dolore. Aut
+                    molestiae error enim illum odio vero sunt laborum
+                    consectetur minus deleniti pariatur eos quos, earum tenetur
+                    architecto veniam voluptatum sit! Optio similique ducimus
+                    esse vel inventore eaque earum adipisci quo, sit illum
+                    reprehenderit? Fugiat rerum inventore commodi dolores nisi
+                    soluta, nulla velit omnis! Quisquam est illo deserunt.
+                    Consequatur modi voluptatem consectetur nesciunt, eligendi,
+                    natus animi.
+                  </Tabs.Tab>
+                </Tabs>
+              </Dropdown>
+            </Heading>
             <Text>
               Lorem ipsum dolor sit amet, consectetur adipisicing elit. Optio
               neque vero consequuntur recusandae, dolore. Aut molestiae error