Replace direct usage of Popper.js with Tippy.js (#261)

- Setup functionality for configuring & creating tippy elements; tweak styles to accomodate Tippy. - Implement functions for generating a centered tippy - Remove the need for manually setting the "render location". - Add testing to cover tooltip element rendering & cleanup. - update webpack.config for tippy - cleanup and refactor references of "popper"
shipshapecode · Oct 8, 2018 · a473c24 · a473c24
1 parent e3e95ec
commit a473c24
Show file tree

Hide file tree

Showing 27 changed files with 869 additions and 609 deletions.
diff --git a/.npmignore b/.npmignore
@@ -1,4 +1,6 @@
 .idea/
+.vscode/
+
 coverage/
 cypress/
 docs/

diff --git a/README.md b/README.md
@@ -16,7 +16,7 @@
 
 __Dependencies__
 
-* __[Popper.js](https://github.com/FezVrasta/popper.js)__
+* __[Tippy.js](https://atomiks.github.io/tippyjs/)__
 
 Installing via `npm` will bring in the above dependencies as well.
 

diff --git a/docs/welcome/css/welcome.css b/docs/welcome/css/welcome.css
diff --git a/docs/welcome/index.html b/docs/welcome/index.html
@@ -37,7 +37,7 @@ <h3>Including</h3>
 
         <script type="text/plain" class="language-markup" id="hero-including-code">
           <link rel="stylesheet" href="shepherd-theme-arrows.css"/>
-          <script src="popper.min.js">&lt;/script>
+          <script src="tippy.all.min.js">&lt;/script>
           <script src="shepherd.min.js">&lt;/script>
         </script>
       </div>
@@ -80,7 +80,7 @@ <h3>Example</h3>
 </div>
 
 <!-- Shepherd -->
-<script src="/shepherd/dist/js/popper.js"></script>
+<script src="/shepherd/dist/js/tippy.all.min.js"></script>
 <script src="/shepherd/dist/js/shepherd.js"></script>
 
 <!-- Welcome page -->

diff --git a/docs/welcome/js/welcome.js b/docs/welcome/js/welcome.js
@@ -1,19 +1,36 @@
 (function() {
-  var init, setupShepherd;
 
-  init = function() {
-    return setupShepherd();
-  };
+  function init() {
+    const shepherd = setupShepherd();
 
-  setupShepherd = function() {
-    var shepherd;
-    shepherd = new Shepherd.Tour({
+    setTimeout(() => {
+      shepherd.start();
+    }, 400);
+  }
+
+  function setupShepherd () {
+    const shepherd = new Shepherd.Tour({
       defaultStepOptions: {
         showCancelLink: true
       }
     });
+
     shepherd.addStep('welcome', {
-      text: ['Shepherd is a javascript library for guiding users through your app. It uses <a href="https://popper.js.org/">Popper.js</a>, another open source library, to position all of its steps.', 'Popper makes sure your steps never end up off screen or cropped by an overflow. Try resizing your browser to see what we mean.'],
+      text: [
+        `
+          Shepherd is a JavaScript library for guiding users through your app.
+          It uses <a href="https://atomiks.github.io/tippyjs//">Tippy.js</a>,
+          another open source library, to render dialogs for each tour "step".
+        `,
+        `
+          Among many things, Tippy makes sure your steps never end up off screen or cropped by an overflow.
+          (Try resizing your browser to see what we mean.)
+        `,
+        `
+          It also offers a robust API for styling animations of steps
+          as they enter and exit the view.
+        `
+      ],
       attachTo: '.hero-welcome bottom',
       classes: 'shepherd shepherd-welcome',
       buttons: [
@@ -29,7 +46,7 @@
     });
     shepherd.addStep('including', {
       title: 'Including',
-      text: 'Including Shepherd is easy! Just include popper.js, shepherd.js, and a Shepherd theme file.',
+      text: 'Including Shepherd is easy! Just include tippy.all.min.js, shepherd.js, and a Shepherd theme file.',
       attachTo: '.hero-including bottom',
       buttons: [
         {
@@ -42,9 +59,25 @@
         }
       ]
     });
-    shepherd.addStep('example', {
-      title: 'Example Shepherd',
-      text: 'Creating a Shepherd is easy too! Just create Shepherd and add as many steps as you want. Check out the <a href="https://shipshapecode.github.io/shepherd/">documentation</a> to learn more.',
+    shepherd.addStep('creating', {
+      title: 'Creating a Shepherd Tour',
+      text: `Creating a Shepherd tour is easy. too!\
+      Just create a \`Tour\` instance, and add as many steps as you want.`,
+      attachTo: '.hero-example bottom',
+      buttons: [
+        {
+          action: shepherd.back,
+          classes: 'shepherd-button-secondary',
+          text: 'Back'
+        }, {
+          action: shepherd.next,
+          text: 'Next'
+        }
+      ]
+    });
+    shepherd.addStep('attaching', {
+      title: 'Attaching to Elements',
+      text: `Your tour steps can target and attach to elements in DOM (like this step).`,
       attachTo: '.hero-example bottom',
       buttons: [
         {
@@ -57,6 +90,22 @@
         }
       ]
     });
+    shepherd.addStep('centered-example', {
+      title: 'Centered Shepherd Element',
+      text: `But attachment is totally optional!\n \
+      Without a target, a tour step will create an element that's centered within the view. \
+      Check out the <a href="https://shipshapecode.github.io/shepherd/">documentation</a> to learn more.`,
+      buttons: [
+        {
+          action: shepherd.back,
+          classes: 'shepherd-button-secondary',
+          text: 'Back'
+        }, {
+          action: shepherd.next,
+          text: 'Next'
+        }
+      ]
+    });
     shepherd.addStep('followup', {
       title: 'Learn more',
       text: 'Star Shepherd on Github so you remember it for your next project',
@@ -72,9 +121,18 @@
         }
       ]
     });
-    return shepherd.start();
-  };
 
-  init();
+    return shepherd;
+  }
+
+  function ready() {
+    if (document.attachEvent ? document.readyState === "complete" : document.readyState !== "loading"){
+      init();
+    } else {
+      document.addEventListener('DOMContentLoaded', init);
+    }
+  }
+
+  ready();
 
 }).call(this);
diff --git a/docs/welcome/scss/welcome.scss b/docs/welcome/scss/welcome.scss
@@ -120,25 +120,26 @@ pre {
 // Import base theme
 @import '../../../src/scss/base';
 
-// Overwrite welcome-step with certain class
-.shepherd-welcome {
+.tippy-popper {
   @include popper-theme-arrows($header-bg: #ffffff);
 
-  &:not(.shepherd-has-title) .shepherd-content {
-    header,
-    .shepherd-header {
-      padding-bottom: 0;
+  .shepherd-welcome {
+    &:not(.shepherd-has-title) .shepherd-content {
+      header,
+      .shepherd-header {
+        padding-bottom: 0;
+      }
     }
-  }
 
-  .shepherd-content {
-    header,
-    .shepherd-header {
-      background: #ffffff;
-    }
+    .shepherd-content {
+      header,
+      .shepherd-header {
+        background: #ffffff;
+      }
 
-    .shepherd-text {
-      color: darken($shepherd-theme-primary, 20);
+      .shepherd-text {
+        color: darken($shepherd-theme-primary, 20);
+      }
     }
   }
 }
diff --git a/index.md b/index.md
@@ -4,7 +4,7 @@ Guide your users through a tour of your app.
 
 ### Dependencies
 
-[Popper](https://popper.js.org/)
+[Tippy.js](https://atomiks.github.io/tippyjs/)
 
 ### Install
 
@@ -191,8 +191,6 @@ to disable.  Each button in the array is an object of the format:
 - `advanceOn`: An action on the page which should advance shepherd to the next step.  It can be of the form `"selector event"`, or an object with those
 properties.  For example: `".some-element click"`, or `{selector: '.some-element', event: 'click'}`.  It doesn't have to be an event inside
 the tour, it can be any event fired on any element on the page.  You can also always manually advance the Tour by calling `myTour.next()`.
-- `renderLocation`: An `HTMLElement` or selector string of the element you want the tour step to render in. Most of the time, you will
-not need to pass anything, and it will default to `document.body`, but this is needed for `<dialog>` and might as well support passing anything.
 - `showCancelLink`: Should a cancel "✕" be shown in the header of the step?
 - `showOn`: A function that, when it returns true, will show the step. If it returns false, the step will be skipped.
 - `scrollTo`: Should the element be scrolled to when this step is shown?
@@ -206,7 +204,7 @@ when: {
   }
 }
 ```
-- `popperOptions`: Extra options to pass to [popper.js](https://github.com/FezVrasta/popper.js)
+- `tippyOptions`: Extra [options to pass to `Tippy.js`](https://atomiks.github.io/tippyjs/#all-options)
 
 ##### Step Methods
 
@@ -292,6 +290,12 @@ let tour = new Shepherd.Tour({
 });
 ```
 
+### Rendering Tours in Specific Locations
+
+By default, tour steps will append their elements to the `body` element of the DOM. This is perfect for most use cases, but not always. If you need to have steps appended elsewhere you can take advantage of Tippy's
+[`appendTo` option](https://atomiks.github.io/tippyjs/#append-to-option) by defining it on the
+`tippyOptions` hash inside of each Step's options hash.
+
 ### Custom Theming
 
 We use [SASS](https://sass-lang.com/) as pre-processor for CSS. This allows us to extend the CSS language with various syntax techniques &mdash; including variables and color functions that can be used to control theming.

diff --git a/install.json b/install.json
@@ -7,7 +7,7 @@
       },
       {
         "type": "script",
-        "src": "./dist/js/popper.js"
+        "src": "./dist/js/tippy.all.min.js"
       },
       {
         "type": "script",

diff --git a/package.json b/package.json
@@ -52,7 +52,7 @@
   "dependencies": {
     "element-matches": "^0.1.2",
     "lodash-es": "^4.17.10",
-    "popper.js": "^1.14.3"
+    "tippy.js": "^3.0.3"
   },
   "devDependencies": {
     "@babel/core": "^7.0.0",