feat(dropdowns): add boundary prop for controlling placement constraint (bootstrap-vue#1440)

* feat(dropdowns): add boundary prop for controlling placement constraint

New prop `boundary` which can be `scrollParent` (Popper default), `viewport`, `window` or a reference to an HTML element.

Controls how the placement is constrained visually.

* Update dropdown.js

* Update dropdown.js

* Update README.md

* Update dropdown.js

* Update dropdown.js

* Update README.md

* Update dropdown.js

* Update README.md

* Update README.md

* Update dropdown.js

Author: tmorehouse

src/components/dropdown/README.md

@@ -171,6 +171,19 @@ the toggle button:
 <!-- dropdown-offset.vue -->
 ```
 
+### Boundary constraint
+By default, dropdowns are visually constrained to its scroll parent, which will suffice
+in most situations.  However, if you place a dropdown inside an element that has `overflow: scroll`
+(or similar) set, the drodpwon menu may - in some situations - get cut off.  To get around this,
+you can sepcify a boundary element via the `boundary` prop.  Supported values are `'scrollParent'`
+(the default), `'viewport'`, `'window'` or a reference to an HTML element. The boundary value
+is passed directly to Popper.js's `boundariesElement` configurtion option.
+
+**Note:** when `boundary` is any value other than the default of `'scrollParent'`, the style
+`position: static` is applied to to the dropdown component's root element in order to allow the
+menu to "break-out" of its scroll container. In some situations this may affect your layout or
+positioning of the dropdown trigger button. In these cases you may need to wrap your
+dropdown inside another element.
 
 ## Split button support
 Create a split dropdown button, where the left button provides standard

src/components/dropdown/dropdown.js

@@ -71,7 +71,11 @@ export default {
       },
       [ this.$slots.default ]
     )
-    return h('div', { attrs: { id: t.safeId() }, class: t.dropdownClasses }, [split, toggle, menu])
+    return h(
+      'div',
+      { attrs: { id: t.safeId() }, class: t.dropdownClasses, style: t.dropdownStyles },
+      [ split, toggle, menu ]
+    )
   },
   props: {
     split: {
@@ -97,6 +101,12 @@ export default {
     role: {
       type: String,
       default: 'menu'
+    },
+    boundary: {
+      // String: `scrollParent`, `window` or `viewport`
+      // Object: HTML Element reference
+      type: [String, Object],
+      default: 'scrollParent'
     }
   },
   computed: {
@@ -109,6 +119,16 @@ export default {
         this.visible ? 'show' : ''
       ]
     },
+    dropdownStyles () {
+      // Position `static` is needed to allow menu to "breakout" of the scrollParent boundaries
+      // See https://github.com/twbs/bootstrap/issues/24251#issuecomment-341413786
+      if (this.boundary === 'scrollParent' || !this.boundary) {
+        return {}
+      }
+      // We enable this feature only when the user supplies a boundary other than `scrollParent`
+      // to preserve default functionality
+      return { position: 'static' }
+    },
     menuClasses () {
       return [
         'dropdown-menu',

src/mixins/dropdown.js

@@ -82,12 +82,14 @@ export default {
     // Use new namespaced events
     this.listenOnRoot('bv::link::clicked', this.rootCloseListener)
   },
+  /* istanbul ignore next: not easy to test */
   deactivated () {
     // In case we are inside a `<keep-alive>`
     this.visible = false
     this.setTouchStart(false)
     this.removePopper()
   },
+  /* istanbul ignore next: not easy to test */
   beforeDestroy () {
     this.visible = false
     this.setTouchStart(false)
@@ -194,6 +196,11 @@ export default {
           }
         }
       }
+      if (this.boundary) {
+        popperConfig.modifiers.preventOverflow = {
+          boundariesElement: this.boundary
+        }
+      }
       return assign(popperConfig, this.popperOpts || {})
     },
     setTouchStart (on) {
@@ -214,6 +221,7 @@ export default {
         })
       }
     },
+    /* istanbul ignore next: not easy to test */
     _noop () {
       // Do nothing event handler (used in touchstart event handler)
     },
@@ -264,6 +272,7 @@ export default {
       }
       this.$emit('click', evt)
     },
+    /* istanbul ignore next: not easy to test */
     onKeydown (evt) {
       // Called from dropdown menu context
       const key = evt.keyCode
@@ -281,6 +290,7 @@ export default {
         this.focusNext(evt, true)
       }
     },
+    /* istanbul ignore next: not easy to test */
     onEsc (evt) {
       if (this.visible) {
         this.visible = false
@@ -290,6 +300,7 @@ export default {
         this.$nextTick(this.focusToggler)
       }
     },
+    /* istanbul ignore next: not easy to test */
     onTab (evt) {
       if (this.visible) {
         // TODO: Need special handler for dealing with form inputs
@@ -304,6 +315,7 @@ export default {
       }
       this.visible = false
     },
+    /* istanbul ignore next: not easy to test */
     onMouseOver (evt) {
       // Focus the item on hover
       // TODO: Special handling for inputs? Inputs are in a special .dropdown-form container