bootstrap-vue · tmorehouse · Apr 7, 2019 · Apr 5, 2019 · Apr 5, 2019 · Apr 5, 2019
diff --git a/src/components/modal/README.md b/src/components/modal/README.md
@@ -180,8 +180,8 @@ export default {
 
 To prevent `<b-modal>` from closing (for example when validation fails). you can call the
 `.preventDefault()` method of the event object passed to your `ok` (**OK** button), `cancel`
-(**Cancel** button) and `hide` event handlers. Note that `.preventDefault()`, when used, must be
-called synchronously, as async is not supported.
+(**Cancel** button) and `hide` event handlers. Note that `.preventDefault()`, when used, **must**
+be called synchronously, as async is not supported.
 
 ```html
 <template>
@@ -223,9 +223,9 @@ called synchronously, as async is not supported.
       clearName() {
         this.name = ''
       },
-      handleOk(evt) {
+      handleOk(bvModalEvt) {
         // Prevent modal from closing
-        evt.preventDefault()
+        bvModalEvt.preventDefault()
         if (!this.name) {
           alert('Please enter your name')
         } else {
@@ -257,13 +257,14 @@ The `ok`, `cancel`, and `hide` event object contains several properties and meth
 
 | Property or Method   | Type     | Description                                                                                                                                                                                                                                                                                                |
 | -------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `e.preventDefault()` | Method   | When called prevents the modal from closing                                                                                                                                                                                                                                                                |
-| `trigger`            | Property | Will be one of: `ok` (Default **OK** Clicked), `cancel` (Default **Cancel** clicked), `esc` (if the <kbd>ESC</kbd> key was pressed), `backdrop` (if the backdrop was clicked), `headerclose` (if the header X button was clicked), the argument provided to the `hide()` method, or `undefined` otherwise. |
-| `target`             | Property | A reference to the modal element                                                                                                                                                                                                                                                                           |
-| `vueTarget`          | property | A reference to the modal's Vue VM instance                                                                                                                                                                                                                                                                 |
+| `preventDefault()` | Method   | When called prevents the modal from closing                                                                                                                                                                                                                                                                |
+| `trigger`          | Property | Will be one of: `ok` (Default **OK** Clicked), `cancel` (Default **Cancel** clicked), `esc` (if the <kbd>ESC</kbd> key was pressed), `backdrop` (if the backdrop was clicked), `headerclose` (if the header X button was clicked), the argument provided to the `hide()` method, or `undefined` otherwise. |
+| `target`           | Property | A reference to the modal element                                                                                                                                                                                                                                                                           |
+| `vueTarget`        | property | A reference to the modal's Vue VM instance                                                                                                                                                                                                                                                                 |
+| `modalId`          | property | The modal's ID                                                                                                                                                                                                                                                                                             |
 
 You can set the value of `trigger` by passing an argument to the component's `hide()` method for
-advanced control.
+advanced control (i.e. detecting what button or action triggerd the modal to hide).
 
 **Note:** `ok` and `cancel` events will be only emitted when the argument to `hide()` is strictly
 `'ok'` or `'cancel'` respectively. The argument passed to `hide()` will be placed into the `trigger`

diff --git a/src/components/modal/helpers/bv-modal-event.class.js b/src/components/modal/helpers/bv-modal-event.class.js
@@ -0,0 +1,34 @@
+import BvEvent from '../../../utils/bv-event.class'
+import warn from '../../../utils/warn'
+import { defineProperties, readonlyDescriptor } from '../../../utils/object'
+
+class BvModalEvent extends BvEvent {
+  constructor(type, eventInit = {}) {
+    super(type, eventInit)
+    // Freeze our new props as readonly, but leave them enumerable.
+    defineProperties(this, {
+      modalId: readonlyDescriptor(),
+      trigger: readonlyDescriptor()
+    })
+  }
+
+  cancel() /* istanbul ignore next */ {
+    // Backwards compatibility for 1.x BootstrapVue
+    warn('b-modal: evt.cancel() is deprecated. Please use evt.preventDefault().')
+    this.preventDefault()
+  }
+
+  static get Defaults() {
+    return {
+      ...super.Defaults,
+      modalId: null,
+      trigger: null
+    }
+  }
+}
+
+// Named Exports
+export { BvModalEvent }
+
+// Default Export
+export default BvModalEvent
diff --git a/src/components/modal/helpers/bv-modal-event.class.spec.js b/src/components/modal/helpers/bv-modal-event.class.spec.js
@@ -0,0 +1,103 @@
+import BvModalEvent from './bv-modal-event.class'
+import BvEvent from '../../../utils/bv-event.class'
+
+describe('modal > BvModalEvent', () => {
+  it('works', async () => {
+    const evt = new BvModalEvent('foobar')
+    expect(evt).toBeInstanceOf(BvModalEvent)
+    expect(evt).toBeInstanceOf(BvEvent)
+    expect(evt.type).toBe('foobar')
+  })
+
+  it('throws exception if no type given', async () => {
+    let evt = null
+    let failed = false
+    try {
+      evt = new BvModalEvent()
+    } catch (e) {
+      failed = true
+    }
+    expect(evt).not.toBeInstanceOf(BvModalEvent)
+    expect(evt).not.toBeInstanceOf(BvEvent)
+    expect(evt).toBe(null)
+    expect(failed).toBe(true)
+  })
+
+  it('supports cancelable events via evt.preventDefault()', async () => {
+    const evt = new BvModalEvent('foobar', {
+      cancelable: true
+    })
+    expect(evt).toBeInstanceOf(BvModalEvent)
+    expect(evt.type).toBe('foobar')
+    expect(evt.cancelable).toBe(true)
+    expect(evt.defaultPrevented).toBe(false)
+    evt.preventDefault()
+    expect(evt.defaultPrevented).toBe(true)
+  })
+
+  it('supports cancelable events via deprecated evt.cancel()', async () => {
+    const evt = new BvModalEvent('foobar', {
+      cancelable: true
+    })
+    expect(evt).toBeInstanceOf(BvModalEvent)
+    expect(evt.type).toBe('foobar')
+    expect(evt.cancelable).toBe(true)
+    expect(evt.defaultPrevented).toBe(false)
+    evt.cancel()
+    expect(evt.defaultPrevented).toBe(true)
+  })
+
+  it('supports non cancelable events', async () => {
+    const evt = new BvModalEvent('foobar', {
+      cancelable: false
+    })
+    expect(evt).toBeInstanceOf(BvModalEvent)
+    expect(evt.type).toBe('foobar')
+    expect(evt.cancelable).toBe(false)
+    expect(evt.defaultPrevented).toBe(false)
+    evt.preventDefault()
+    expect(evt.defaultPrevented).toBe(false)
+  })
+
+  it('supports built in properties', async () => {
+    const evt = new BvModalEvent('foobar', {
+      target: 'baz',
+      trigger: 'ok',
+      modalId: 'foo'
+    })
+    expect(evt).toBeInstanceOf(BvModalEvent)
+    expect(evt.type).toBe('foobar')
+    expect(evt.cancelable).toBe(true)
+    expect(evt.target).toBe('baz')
+    expect(evt.trigger).toBe('ok')
+    expect(evt.modalId).toBe('foo')
+
+    let failed = false
+    try {
+      evt.trigger = 'foobar'
+    } catch (e) {
+      failed = true
+    }
+    expect(failed).toBe(true)
+    expect(evt.trigger).toBe('ok')
+
+    failed = false
+    try {
+      evt.modalId = 'fail'
+    } catch (e) {
+      failed = true
+    }
+    expect(failed).toBe(true)
+    expect(evt.modalId).toBe('foo')
+  })
+
+  it('supports custom properties', async () => {
+    const evt = new BvEvent('foobar', {
+      custom: 123
+    })
+    expect(evt).toBeInstanceOf(BvEvent)
+    expect(evt.type).toBe('foobar')
+    expect(evt.cancelable).toBe(true)
+    expect(evt.custom).toBe(123)
+  })
+})
diff --git a/src/components/modal/modal.js b/src/components/modal/modal.js
@@ -1,13 +1,12 @@
 import Vue from 'vue'
+import modalManager from './helpers/modal-manager'
+import BvModalEvent from './helpers/bv-modal-event.class'
 import BButton from '../button/button'
 import BButtonClose from '../button/button-close'
-import modalManager from './helpers/modal-manager'
 import idMixin from '../../mixins/id'
 import listenOnRootMixin from '../../mixins/listen-on-root'
 import observeDom from '../../utils/observe-dom'
-import warn from '../../utils/warn'
 import KeyCodes from '../../utils/key-codes'
-import BvEvent from '../../utils/bv-event.class'
 import { inBrowser } from '../../utils/env'
 import { getComponentConfig } from '../../utils/config'
 import { stripTags } from '../../utils/html'
@@ -364,12 +363,11 @@ export default Vue.extend({
         return
       }
       this.is_opening = true
-      const showEvt = new BvEvent('show', {
+      const showEvt = new BvModalEvent('show', {
         cancelable: true,
         vueTarget: this,
         target: this.$refs.modal,
         relatedTarget: null,
-        // Modal specifi properties
         modalId: this.safeId()
       })
       this.emitEvent(showEvt)
@@ -387,20 +385,13 @@ export default Vue.extend({
         return
       }
       this.is_closing = true
-      const hideEvt = new BvEvent('hide', {
-        // BvEvent standard properties
+      const hideEvt = new BvModalEvent('hide', {
         cancelable: true,
         vueTarget: this,
         target: this.$refs.modal,
         relatedTarget: null,
-        // Modal specific properties and methods
         modalId: this.safeId(),
-        trigger: trigger || null,
-        cancel() /* istanbul ignore next */ {
-          // Backwards compatibility
-          warn('b-modal: evt.cancel() is deprecated. Please use evt.preventDefault().')
-          this.preventDefault()
-        }
+        trigger: trigger || null
       })
       // We emit specific event for one of the three built-in buttons
       if (trigger === 'ok') {
@@ -475,7 +466,7 @@ export default Vue.extend({
       this.is_show = true
       this.is_transitioning = false
       this.$nextTick(() => {
-        const shownEvt = new BvEvent('shown', {
+        const shownEvt = new BvModalEvent('shown', {
           cancelable: false,
           vueTarget: this,
           target: this.$refs.modal,
@@ -503,7 +494,7 @@ export default Vue.extend({
       this.$nextTick(() => {
         this.returnFocusTo()
         this.is_closing = false
-        const hiddenEvt = new BvEvent('hidden', {
+        const hiddenEvt = new BvModalEvent('hidden', {
           cancelable: false,
           vueTarget: this,
           target: this.lazy ? null : this.$refs.modal,

diff --git a/src/components/modal/modal.spec.js b/src/components/modal/modal.spec.js
@@ -1,5 +1,5 @@
 import BModal from './modal'
-import BvEvent from '../../utils/bv-event.class'
+import BvModalEvent from './helpers/bv-modal-event.class'
 
 import { mount, createWrapper } from '@vue/test-utils'
 
@@ -353,7 +353,7 @@ describe('modal', () => {
       // Try and close modal (but we prevent it)
       $close.trigger('click')
       expect(trigger).toEqual('headerclose')
-      expect(evt).toBeInstanceOf(BvEvent)
+      expect(evt).toBeInstanceOf(BvModalEvent)
 
       await wrapper.vm.$nextTick()
       await waitAF()
@@ -369,7 +369,7 @@ describe('modal', () => {
       evt = null
       $close.trigger('click')
       expect(trigger).toEqual('headerclose')
-      expect(evt).toBeInstanceOf(BvEvent)
+      expect(evt).toBeInstanceOf(BvModalEvent)
 
       await wrapper.vm.$nextTick()
       await waitAF()
@@ -722,6 +722,66 @@ describe('modal', () => {
       wrapper.destroy()
     })
 
+    it('$root bv::toggle::modal works', async () => {
+      const wrapper = mount(BModal, {
+        attachToDocument: true,
+        stubs: {
+          transition: false
+        },
+        propsData: {
+          id: 'test',
+          visible: false
+        }
+      })
+
+      expect(wrapper.isVueInstance()).toBe(true)
+
+      await wrapper.vm.$nextTick()
+      await waitAF()
+      await wrapper.vm.$nextTick()
+      await waitAF()
+
+      const $modal = wrapper.find('div.modal')
+      expect($modal.exists()).toBe(true)
+
+      expect($modal.element.style.display).toEqual('none')
+
+      // Try and open modal via `bv::toggle::modal`
+      wrapper.vm.$root.$emit('bv::toggle::modal', 'test')
+
+      await wrapper.vm.$nextTick()
+      await waitAF()
+      await wrapper.vm.$nextTick()
+      await waitAF()
+
+      // Modal should now be open
+      expect($modal.element.style.display).toEqual('')
+
+      // Try and close modal via `bv::toggle::modal`
+      wrapper.vm.$root.$emit('bv::toggle::modal', 'test')
+
+      await wrapper.vm.$nextTick()
+      await waitAF()
+      await wrapper.vm.$nextTick()
+      await waitAF()
+
+      // Modal should now be closed
+      expect($modal.element.style.display).toEqual('none')
+
+      // Try and open modal via `bv::toggle::modal` with wrong ID
+      wrapper.vm.$root.$emit('bv::toggle::modal', 'not-test')
+
+      await wrapper.vm.$nextTick()
+      await waitAF()
+      await wrapper.vm.$nextTick()
+      await waitAF()
+
+      // Modal should now be open
+      expect($modal.element.style.display).toEqual('none')
+
+      wrapper.destroy()
+    })
+
     it('show event is cancellable', async () => {
       let prevent = true
       let called = 0
@@ -790,5 +850,53 @@ describe('modal', () => {
 
       wrapper.destroy()
     })
+
+    it('instance .toggle() methods works', async () => {
+      const wrapper = mount(BModal, {
+        attachToDocument: true,
+        stubs: {
+          transition: false
+        },
+        propsData: {
+          id: 'test',
+          visible: false
+        }
+      })
+
+      expect(wrapper.isVueInstance()).toBe(true)
+
+      await wrapper.vm.$nextTick()
+      await waitAF()
+      await wrapper.vm.$nextTick()
+      await waitAF()
+
+      const $modal = wrapper.find('div.modal')
+      expect($modal.exists()).toBe(true)
+
+      expect($modal.element.style.display).toEqual('none')
+
+      // Try and open modal via .toggle() method
+      wrapper.vm.toggle()
+
+      await wrapper.vm.$nextTick()
+      await waitAF()
+      await wrapper.vm.$nextTick()
+      await waitAF()
+
+      // Modal should now be open
+      expect($modal.element.style.display).toEqual('')
+
+      // Try and close modal via .toggle()
+      wrapper.vm.toggle()
+
+      await wrapper.vm.$nextTick()
+      await waitAF()
+      await wrapper.vm.$nextTick()
+      await waitAF()
+
+      // Modal should now be closed
+      expect($modal.element.style.display).toEqual('none')
+      wrapper.destroy()
+    })
   })
 })