Merge branch 'feature/handle-keyboard-events' into develop

Author: mmorainville

src/components/VStep.vue

@@ -55,7 +55,7 @@ export default {
     let params = this.step.params || {}
     let targetElement = document.querySelector(this.step.target)
 
-    // Add a debug mode?
+    // TODO: debug mode
     // console.log('[Vue Tour] The target element ' + this.step.target + ' of .v-step[id="' + this.hash + '"] is:', targetElement)
 
     if (targetElement) {

src/components/VTour.vue

@@ -30,6 +30,8 @@
 </template>
 
 <script>
+import { DEFAULT_OPTIONS, KEYS } from '../shared/constants'
+
 export default {
   name: 'v-tour',
   props: {
@@ -39,6 +41,10 @@ export default {
     },
     name: {
       type: String
+    },
+    options: {
+      type: Object,
+      default: () => { return DEFAULT_OPTIONS }
     }
   },
   data () {
@@ -48,30 +54,71 @@ export default {
   },
   mounted () {
     this.$tours[this.name] = this
+
+    if (this.customOptions.useKeyboardNavigation) {
+      window.addEventListener('keyup', this.handleKeyup)
+    }
+  },
+  beforeDestroy () {
+    // Remove the keyup listener if it has been defined
+    if (this.customOptions.useKeyboardNavigation) {
+      window.removeEventListener('keyup', this.handleKeyup)
+    }
   },
   computed: {
+    // Allow us to define custom options and merge them with the default options.
+    // Since options is a computed property, it is reactive and can be updated during runtime.
+    customOptions () {
+      return {
+        ...DEFAULT_OPTIONS,
+        ...this.options
+      }
+    },
+    // Return true if the tour is active, which means that there's a VStep displayed
+    isRunning () {
+      return this.currentStep > -1 && this.currentStep < this.numberOfSteps
+    },
     isFirst () {
       return this.currentStep === 0
     },
     isLast () {
       return this.currentStep === this.steps.length - 1
+    },
+    numberOfSteps () {
+      return this.steps.length
     }
   },
   methods: {
     start () {
       // Wait for the DOM to be loaded, then start the tour
       setTimeout(() => {
         this.currentStep = 0
-      })
+      }, this.customOptions.startTimeout)
     },
     previousStep () {
-      this.currentStep--
+      if (this.currentStep > 0) this.currentStep--
     },
     nextStep () {
-      this.currentStep++
+      if (this.currentStep < this.numberOfSteps - 1 && this.currentStep !== -1) this.currentStep++
     },
     stop () {
       this.currentStep = -1
+    },
+
+    handleKeyup (e) {
+      // TODO: debug mode
+      // console.log('[Vue Tour] A keyup event occured:', e)
+      switch (e.keyCode) {
+        case KEYS.ARROW_RIGHT:
+          this.nextStep()
+          break
+        case KEYS.ARROW_LEFT:
+          this.previousStep()
+          break
+        case KEYS.ESCAPE:
+          this.stop()
+          break
+      }
     }
   }
 }

src/shared/constants.js

@@ -0,0 +1,10 @@
+export const KEYS = {
+  ARROW_RIGHT: 39,
+  ARROW_LEFT: 37,
+  ESCAPE: 27
+}
+
+export const DEFAULT_OPTIONS = {
+  useKeyboardNavigation: true,
+  startTimeout: 0
+}

test/unit/VTour.spec.js

@@ -6,19 +6,19 @@ import VTour from '@/components/VTour.vue'
 
 Vue.use(VueTour)
 
+const steps = [
+  {
+    target: '#v-step-0',
+    content: `Discover <strong>Vue Tour</strong>!`
+  },
+  {
+    target: '#v-step-1',
+    content: 'An awesome plugin made with Vue.js!'
+  }
+]
+
 describe('VTour.vue', () => {
   it('has the correct number of steps', () => {
-    const steps = [
-      {
-        target: '#v-step-0',
-        content: `Discover <strong>Vue Tour</strong>!`
-      },
-      {
-        target: '#v-step-1',
-        content: 'An awesome plugin made with Vue.js!'
-      }
-    ]
-
     const wrapper = mount(VTour, {
       propsData: {
         name: 'myTestTour',
@@ -39,4 +39,39 @@ describe('VTour.vue', () => {
 
     expect(wrapper.vm.$tours).to.be.an('object').that.has.all.keys('myTestTour')
   })
+
+  it('stays within the boundaries of the number of steps', () => {
+    const wrapper = mount(VTour, {
+      propsData: {
+        name: 'myTestTour',
+        steps
+      }
+    })
+
+    expect(wrapper.vm.currentStep).to.equal(-1)
+
+    wrapper.vm.start()
+
+    setTimeout(() => {
+      expect(wrapper.vm.currentStep).to.equal(0)
+
+      // We call nextStep one more time than needed
+      for (let i = 0; i < steps.length; i++) {
+        wrapper.vm.nextStep()
+      }
+
+      expect(wrapper.vm.currentStep).to.equal(1)
+
+      // We call previousStep one more time than needed
+      for (let i = 0; i < steps.length; i++) {
+        wrapper.vm.previousStep()
+      }
+
+      expect(wrapper.vm.currentStep).to.equal(0)
+
+      wrapper.vm.stop()
+
+      expect(wrapper.vm.currentStep).to.equal(-1)
+    })
+  })
 })