Add ESDoc, bump some deps (shipshapecode#365)

* serve logo from repo

* add branding info to `.esdoc` config

* link to Step#constructor in tour.js constructor doc

* begin embedding examples into Tour#constructor parameter descriptions

* Bump some deps, add some docs

* Adjust paths for utils

.esdoc.js

@@ -1,13 +1,31 @@
 module.exports = {
   source: './src',
-  destination: './esdoc',
+  destination: './docs/esdoc',
+  index: "./README.md",
+  excludes: ['utils'],
   plugins: [
     {
-      name: 'esdoc-standard-plugin'
+      name: 'esdoc-standard-plugin',
+      option: {
+        test: {source: "./test", includes: ["\\.spec\\.js$"]},
+        brand: {
+          title: 'Shepherd',
+          logo: './docs/assets/img/ship-shape-logo.png',
+          description: 'Guide your users through a tour of your app.',
+          repository: 'https://github.com/shipshapecode/shepherd.git'
+        },
+        manual: {
+          index: './README.md',
+          files: [
+            './manual/overview.md',
+            './CHANGELOG.md'
+          ]
+        }
+      }
     },
     {
       name: 'esdoc-ecmascript-proposal-plugin',
       option: { all: true }
     }
   ]
-};
+};

.gitignore

@@ -7,7 +7,7 @@
 /coverage/
 /cypress/
 /dist/
-/esdoc/
+/docs/esdoc/
 /node_modules/
 /test/unit/dist
 /.DS_Store

manual/index.md

@@ -0,0 +1 @@
+# Index

manual/overview.md

@@ -0,0 +1,3 @@
+# Overview
+
+## Bar

package.json

@@ -47,11 +47,11 @@
   "dependencies": {
     "element-matches": "^0.1.2",
     "lodash-es": "^4.17.11",
-    "tippy.js": "^4.2.1"
+    "tippy.js": "^4.3.0"
   },
   "devDependencies": {
-    "@babel/core": "^7.4.3",
-    "@babel/preset-env": "^7.4.3",
+    "@babel/core": "^7.4.4",
+    "@babel/preset-env": "^7.4.4",
     "autoprefixer": "^9.5.1",
     "babel-core": "^7.0.0-bridge.0",
     "babel-jest": "^24.7.1",
@@ -60,23 +60,23 @@
     "codeclimate-test-reporter": "^0.5.1",
     "cssnano": "^4.1.10",
     "cypress": "^3.2.0",
-    "del": "^4.1.0",
+    "del": "^4.1.1",
     "esdoc": "^1.1.0",
     "esdoc-ecmascript-proposal-plugin": "^1.0.0",
     "esdoc-standard-plugin": "^1.0.0",
     "eslint": "^5.16.0",
-    "eslint-plugin-jest": "^22.4.1",
+    "eslint-plugin-jest": "^22.5.1",
     "eslint-plugin-ship-shape": "^0.6.0",
     "glob": "^7.1.3",
     "http-server": "^0.11.1",
     "jest": "^24.7.1",
-    "jest-dom": "^3.1.3",
+    "jest-dom": "^3.1.4",
     "jest-expect-message": "^1.0.2",
     "jest-transform-css": "^2.0.0",
     "mutationobserver-shim": "^0.3.3",
     "postcss": "^7.0.14",
     "replace": "^1.1.0",
-    "rollup": "^1.10.0",
+    "rollup": "^1.10.1",
     "rollup-plugin-babel": "^4.3.2",
     "rollup-plugin-browsersync": "^1.0.0",
     "rollup-plugin-commonjs": "^9.3.4",
@@ -89,8 +89,8 @@
     "rollup-plugin-sass": "^1.2.2",
     "rollup-plugin-stylelint": "^0.0.4",
     "rollup-plugin-terser": "^4.0.4",
-    "sinon": "^7.3.1",
-    "start-server-and-test": "^1.7.13",
+    "sinon": "^7.3.2",
+    "start-server-and-test": "^1.9.0",
     "stylelint": "^10.0.1",
     "stylelint-config-ship-shape": "^0.5.2"
   },

src/js/step.js

@@ -6,8 +6,8 @@ import isString from 'lodash-es/isString';
 import isUndefined from 'lodash-es/isUndefined';
 import { Evented } from './evented.js';
 import 'element-matches';
-import { bindAdvance, bindButtonEvents, bindCancelLink, bindMethods } from './bind.js';
-import { createFromHTML, setupTooltip, parseAttachTo } from './utils.js';
+import { bindAdvance, bindButtonEvents, bindCancelLink, bindMethods } from './utils/bind.js';
+import { createFromHTML, setupTooltip, parseAttachTo } from './utils/general.js';
 
 /**
  * Creates incremented ID for each newly created step
@@ -23,7 +23,7 @@ const uniqueId = (function() {
 })();
 
 /**
- * Class representing steps to be added to a tour
+ * A class representing steps to be added to a tour.
  * @extends {Evented}
  */
 export class Step extends Evented {
@@ -32,16 +32,40 @@ export class Step extends Evented {
    * @param {Tour} tour The tour for the step
    * @param {Object} options The options for the step
    * @param {Object|string} options.attachTo What element the step should be attached to on the page.
-   * It can either be a string of the form "element on", or an object with those properties.
-   * For example: ".some #element left", or {element: '.some #element', on: 'left'}.
+   * It can either be a string of the form `[element] [on]` (where [element] is an element selector path):
+   * ```js
+   * const new Step(tour, {
+   *   attachTo: '.some .selector-path left',
+   *   ...moreOptions,
+   * })'
+   * ```
+   * Or an object with those properties:
+   * ```js
+   * const new Step(tour, {
+   *   attachTo: { element: '.some .selector-path', on: 'left' },
+   *   ...moreOptions
+   * })'
+   * ```
    * If you use the object syntax, element can also be a DOM element. If you don’t specify an attachTo the
    * element will appear in the middle of the screen.
    * @param {HTMLElement|string} options.attachTo.element
    * @param {string} options.attachTo.on
    * @param {Object|string} options.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.
+   * It can be of the form `"selector event"`:
+  * ```js
+   * const new Step(tour, {
+   *   advanceOn: '.some .selector-path click',
+   *   ...moreOptions
+   * })'
+   * ```
+   * ...or an object with those properties:
+   * ```js
+   * const new Step(tour, {
+   *   advanceOn: { selector: '.some .selector-path', event: 'click' },
+   *   ...moreOptions
+   * })'
+   * ```
+   * `event` 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()`.
    * @param {function} options.beforeShowPromise A function that returns a promise.
    * When the promise resolves, the rest of the `show` code for the step will execute.
@@ -385,6 +409,11 @@ export class Step extends Evented {
     this.trigger('show');
   }
 
+  /**
+   * When a step is hidden, remove the highlightClass and 'shepherd-enabled'
+   * and 'shepherd-target' classes
+   * @private
+   */
   _updateStepTargetOnHide() {
     if (this.options.highlightClass) {
       this.target.classList.remove(this.options.highlightClass);

src/js/tour.js

@@ -6,7 +6,7 @@ import isUndefined from 'lodash-es/isUndefined';
 import { Evented } from './evented.js';
 import { Modal } from './modal.js';
 import { Step } from './step.js';
-import { bindMethods } from './bind.js';
+import { bindMethods } from './utils/bind.js';
 import tippy from 'tippy.js';
 import { defaults as tooltipDefaults } from './utils/tooltip-defaults';
 
@@ -46,7 +46,7 @@ const Shepherd = new Evented();
 export class Tour extends Evented {
   /**
    * @param {Object} options The options for the tour
-   * @param {Object} options.defaultStepOptions Default options for Steps created through `addStep`
+   * @param {Object} options.defaultStepOptions Default options for Steps ({@link Step#constructor}), created through `addStep`
    * @param {Step[]} options.steps An array of Step instances to initialize the tour with
    * @param {string} options.tourName An optional "name" for the tour. This will be appended to the the tour's
    * dynamically generated `id` property -- which is also set on the `body` element as the `data-shepherd-active-tour` attribute
@@ -198,6 +198,10 @@ export class Tour extends Evented {
     }
   }
 
+  /**
+   * Check if the tour is active
+   * @return {boolean}
+   */
   isActive() {
     return Shepherd.activeTour === this;
   }
@@ -355,10 +359,19 @@ export class Tour extends Evented {
     this.show(nextIndex, forward);
   }
 
+  /**
+   * Set the tippy defaults
+   * @private
+   */
   _setTooltipDefaults() {
     tippy.setDefaults(tooltipDefaults);
   }
 
+  /**
+   * Before showing, hide the current step and if the tour is not
+   * already active, call `this._setupActiveTour`.
+   * @private
+   */
   _updateStateBeforeShow() {
     if (this.currentStep) {
       this.currentStep.hide();
@@ -369,18 +382,32 @@ export class Tour extends Evented {
     }
   }
 
+  /**
+   * Sets this.id to `${tourName}--${uuid}`
+   * @private
+   */
   _setTourID() {
     const tourName = this.options.tourName || 'tour';
     const uuid = uniqueId();
 
     this.id = `${tourName}--${uuid}`;
   }
 
+  /**
+   * Adds the data-shepherd-active-tour attribute and the 'shepherd-active'
+   * class to the body.
+   * @private
+   */
   _addBodyAttrs() {
     document.body.setAttribute('data-shepherd-active-tour', this.id);
     document.body.classList.add('shepherd-active');
   }
 
+  /**
+   * Removes the data-shepherd-active-tour attribute and the 'shepherd-active'
+   * class from the body.
+   * @private
+   */
   _removeBodyAttrs() {
     document.body.removeAttribute('data-shepherd-active-tour');
     document.body.classList.remove('shepherd-active');

src/js/bind.js → src/js/utils/bind.js

@@ -1,4 +1,4 @@
-import { parseShorthand } from './utils.js';
+import { parseShorthand } from './general.js';
 import forOwn from 'lodash-es/forOwn';
 import isString from 'lodash-es/isString';
 import isUndefined from 'lodash-es/isUndefined';

src/js/utils.js → src/js/utils/general.js

@@ -3,7 +3,7 @@ import isString from 'lodash-es/isString';
 import isUndefined from 'lodash-es/isUndefined';
 import zipObject from 'lodash-es/zipObject';
 import tippy from 'tippy.js';
-import { missingTippy } from './utils/error-messages';
+import { missingTippy } from './error-messages';
 
 const centeredStylePopperModifier = {
   computeStyle: {

test/unit/utils.spec.js → test/unit/utils/general.spec.js

@@ -1,7 +1,7 @@
 import {
   _parseAttachToOpts,
   parseShorthand
-} from '../../src/js/utils.js';
+} from '../../../src/js/utils/general.js';
 
 describe('Utils', function() {
   describe('_parseAttachToOpts', function() {