Add function type for `popperConfig` option (#32882)

* Add function type for `popperConfig` option

* Update .bundlewatch.config.json

* copy edits

Co-authored-by: XhmikosR <xhmikosr@gmail.com>
Co-authored-by: Mark Otto <markdotto@gmail.com>

diff --git a/.bundlewatch.config.json b/.bundlewatch.config.json
index da47da48014549181943bfdb5b0f861d9b7b8a5d..36404b38cfda0dc0206614dd7f31521e3c3e9355 100644 (file)
--- a/.bundlewatch.config.json
+++ b/.bundlewatch.config.json
@@ -34,7 +34,7 @@
     },
     {
       "path": "./dist/js/bootstrap.bundle.js",
-      "maxSize": "41 kB"
+      "maxSize": "42 kB"
     },
     {
       "path": "./dist/js/bootstrap.bundle.min.js",

diff --git a/js/src/dropdown.js b/js/src/dropdown.js
index 878a5a9a21d9ec586fdc5821cbb6e39dff55f044..7221debfc29f7a433b4287afb32ff02b673c1263 100644 (file)
--- a/js/src/dropdown.js
+++ b/js/src/dropdown.js
@@ -86,7 +86,7 @@ const DefaultType = {
   boundary: '(string|element)',
   reference: '(string|element|object)',
   display: 'string',
-  popperConfig: '(null|object)'
+  popperConfig: '(null|object|function)'
 }
 
 /**
@@ -322,7 +322,7 @@ class Dropdown extends BaseComponent {
   }
 
   _getPopperConfig() {
-    const popperConfig = {
+    const defaultBsPopperConfig = {
       placement: this._getPlacement(),
       modifiers: [{
         name: 'preventOverflow',
@@ -341,15 +341,15 @@ class Dropdown extends BaseComponent {
 
     // Disable Popper if we have a static display
     if (this._config.display === 'static') {
-      popperConfig.modifiers = [{
+      defaultBsPopperConfig.modifiers = [{
         name: 'applyStyles',
         enabled: false
       }]
     }
 
     return {
-      ...popperConfig,
-      ...this._config.popperConfig
+      ...defaultBsPopperConfig,
+      ...(typeof this._config.popperConfig === 'function' ? this._config.popperConfig(defaultBsPopperConfig) : this._config.popperConfig)
     }
   }
 

diff --git a/js/src/tooltip.js b/js/src/tooltip.js
index 11209625cd181261e7845d9ee476ec83f88517f8..42da4c93858ef27404e828eee68797aa6a72f7de 100644 (file)
--- a/js/src/tooltip.js
+++ b/js/src/tooltip.js
@@ -58,7 +58,7 @@ const DefaultType = {
   sanitize: 'boolean',
   sanitizeFn: '(null|function)',
   allowList: 'object',
-  popperConfig: '(null|object)'
+  popperConfig: '(null|object|function)'
 }
 
 const AttachmentMap = {
@@ -490,7 +490,7 @@ class Tooltip extends BaseComponent {
   }
 
   _getPopperConfig(attachment) {
-    const defaultBsConfig = {
+    const defaultBsPopperConfig = {
       placement: attachment,
       modifiers: [
         {
@@ -533,8 +533,8 @@ class Tooltip extends BaseComponent {
     }
 
     return {
-      ...defaultBsConfig,
-      ...this.config.popperConfig
+      ...defaultBsPopperConfig,
+      ...(typeof this.config.popperConfig === 'function' ? this.config.popperConfig(defaultBsPopperConfig) : this.config.popperConfig)
     }
   }
 

diff --git a/js/tests/unit/dropdown.spec.js b/js/tests/unit/dropdown.spec.js
index 01d599ceb6d425b73005cc1f9f957e801dd0fbe2..e97ce7717ce6dc8d684a6ca633bd7e04a441c923 100644 (file)
--- a/js/tests/unit/dropdown.spec.js
+++ b/js/tests/unit/dropdown.spec.js
@@ -123,6 +123,28 @@ describe('Dropdown', () => {
 
       expect(popperConfig.placement).toEqual('left')
     })
+
+    it('should allow to pass config to Popper with `popperConfig` as a function', () => {
+      fixtureEl.innerHTML = [
+        '<div class="dropdown">',
+        '  <button class="btn dropdown-toggle" data-bs-toggle="dropdown" data-bs-placement="right" >Dropdown</button>',
+        '  <div class="dropdown-menu">',
+        '    <a class="dropdown-item" href="#">Secondary link</a>',
+        '  </div>',
+        '</div>'
+      ].join('')
+
+      const btnDropdown = fixtureEl.querySelector('[data-bs-toggle="dropdown"]')
+      const getPopperConfig = jasmine.createSpy('getPopperConfig').and.returnValue({ placement: 'left' })
+      const dropdown = new Dropdown(btnDropdown, {
+        popperConfig: getPopperConfig
+      })
+
+      const popperConfig = dropdown._getPopperConfig()
+
+      expect(getPopperConfig).toHaveBeenCalled()
+      expect(popperConfig.placement).toEqual('left')
+    })
   })
 
   describe('toggle', () => {

diff --git a/js/tests/unit/tooltip.spec.js b/js/tests/unit/tooltip.spec.js
index 38af0235ba2988c7f0831839bb483d808baa4a42..e1d037154661b9766496462bed118cbab3ca60b6 100644 (file)
--- a/js/tests/unit/tooltip.spec.js
+++ b/js/tests/unit/tooltip.spec.js
@@ -156,6 +156,21 @@ describe('Tooltip', () => {
 
       expect(popperConfig.placement).toEqual('left')
     })
+
+    it('should allow to pass config to Popper with `popperConfig` as a function', () => {
+      fixtureEl.innerHTML = '<a href="#" rel="tooltip">'
+
+      const tooltipEl = fixtureEl.querySelector('a')
+      const getPopperConfig = jasmine.createSpy('getPopperConfig').and.returnValue({ placement: 'left' })
+      const tooltip = new Tooltip(tooltipEl, {
+        popperConfig: getPopperConfig
+      })
+
+      const popperConfig = tooltip._getPopperConfig('top')
+
+      expect(getPopperConfig).toHaveBeenCalled()
+      expect(popperConfig.placement).toEqual('left')
+    })
   })
 
   describe('enable', () => {

diff --git a/site/content/docs/5.0/components/dropdowns.md b/site/content/docs/5.0/components/dropdowns.md
index d5efd3adbc1cb4838093ae605ad03760506839bc..24353f0f4dd987c8c4fa73e213822d05db2e14bc 100644 (file)
--- a/site/content/docs/5.0/components/dropdowns.md
+++ b/site/content/docs/5.0/components/dropdowns.md
@@ -993,13 +993,28 @@ Options can be passed via data attributes or JavaScript. For data attributes, ap
     </tr>
     <tr>
       <td><code>popperConfig</code></td>
-      <td>null | object</td>
+      <td>null | object | function</td>
       <td><code>null</code></td>
-      <td>To change Bootstrap's default Popper config, see <a href="https://popper.js.org/docs/v2/constructors/#options">Popper's configuration</a></td>
+      <td>
+        <p>To change Bootstrap's default Popper config, see <a href="https://popper.js.org/docs/v2/constructors/#options">Popper's configuration</a>.</p>
+        <p>When a function is used to create the Popper configuration, it's called with an object that contains the Bootstrap's default Popper configuration. It helps you use and merge the default with your own configuration. The function must return a configuration object for Popper.</p>
+      </td>
     </tr>
   </tbody>
 </table>
 
+#### Using function with `popperConfig`
+
+```js
+var dropdown = new bootstrap.Dropdown(element, {
+  popperConfig: function (defaultBsPopperConfig) {
+    // var newPopperConfig = {...}
+    // use defaultBsPopperConfig if needed...
+    // return newPopperConfig
+  }
+})
+```
+
 ### Methods
 
 <table class="table">

diff --git a/site/content/docs/5.0/components/popovers.md b/site/content/docs/5.0/components/popovers.md
index 56616fd0cd141eb0f21829ac9b40a2e7faf2e098..8a2efa0a2a83dc98ef8f0c4d1316cf2e52122f7e 100644 (file)
--- a/site/content/docs/5.0/components/popovers.md
+++ b/site/content/docs/5.0/components/popovers.md
@@ -279,9 +279,12 @@ Note that for security reasons the `sanitize`, `sanitizeFn`, and `allowList` opt
     </tr>
     <tr>
       <td><code>popperConfig</code></td>
-      <td>null | object</td>
+      <td>null | object | function</td>
       <td><code>null</code></td>
-      <td>To change Bootstrap's default Popper config, see <a href="https://popper.js.org/docs/v2/constructors/#options">Popper's configuration</a></td>
+      <td>
+        <p>To change Bootstrap's default Popper config, see <a href="https://popper.js.org/docs/v2/constructors/#options">Popper's configuration</a>.</p>
+        <p>When a function is used to create the Popper configuration, it's called with an object that contains the Bootstrap's default Popper configuration. It helps you use and merge the default with your own configuration. The function must return a configuration object for Popper.</p>
+      </td>
     </tr>
   </tbody>
 </table>
@@ -292,6 +295,18 @@ Note that for security reasons the `sanitize`, `sanitizeFn`, and `allowList` opt
 Options for individual popovers can alternatively be specified through the use of data attributes, as explained above.
 {{< /callout >}}
 
+#### Using function with `popperConfig`
+
+```js
+var popover = new bootstrap.Popover(element, {
+  popperConfig: function (defaultBsPopperConfig) {
+    // var newPopperConfig = {...}
+    // use defaultBsPopperConfig if needed...
+    // return newPopperConfig
+  }
+})
+```
+
 ### Methods
 
 {{< callout danger >}}

diff --git a/site/content/docs/5.0/components/tooltips.md b/site/content/docs/5.0/components/tooltips.md
index 9a5dd93931c43e70fc06ea4871b217da7058b3c6..ee6d06e9e9bafb213269709e221943c06384c5ad 100644 (file)
--- a/site/content/docs/5.0/components/tooltips.md
+++ b/site/content/docs/5.0/components/tooltips.md
@@ -304,9 +304,12 @@ Note that for security reasons the `sanitize`, `sanitizeFn`, and `allowList` opt
     </tr>
     <tr>
       <td><code>popperConfig</code></td>
-      <td>null | object</td>
+      <td>null | object | function</td>
       <td><code>null</code></td>
-      <td>To change Bootstrap's default Popper config, see <a href="https://popper.js.org/docs/v2/constructors/#options">Popper's configuration</a></td>
+      <td>
+        <p>To change Bootstrap's default Popper config, see <a href="https://popper.js.org/docs/v2/constructors/#options">Popper's configuration</a>.</p>
+        <p>When a function is used to create the Popper configuration, it's called with an object that contains the Bootstrap's default Popper configuration. It helps you use and merge the default with your own configuration. The function must return a configuration object for Popper.</p>
+      </td>
     </tr>
   </tbody>
 </table>
@@ -317,6 +320,18 @@ Note that for security reasons the `sanitize`, `sanitizeFn`, and `allowList` opt
 Options for individual tooltips can alternatively be specified through the use of data attributes, as explained above.
 {{< /callout >}}
 
+#### Using function with `popperConfig`
+
+```js
+var tooltip = new bootstrap.Tooltip(element, {
+  popperConfig: function (defaultBsPopperConfig) {
+    // var newPopperConfig = {...}
+    // use defaultBsPopperConfig if needed...
+    // return newPopperConfig
+  }
+})
+```
+
 ### Methods
 
 {{< callout danger >}}

diff --git a/site/content/docs/5.0/migration.md b/site/content/docs/5.0/migration.md
index 6e4839348e87ac3aca2df2ceb679a1bb03a9dc55..99a9c9e38ce5b40c28aa31fe393d724ea61837e5 100644 (file)
--- a/site/content/docs/5.0/migration.md
+++ b/site/content/docs/5.0/migration.md
@@ -24,6 +24,7 @@ toc: true
 - The default value for the `fallbackPlacements` is changed to `['top', 'right', 'bottom', 'left']` for better placement of popper elements.
 - All the events for the dropdown are now triggered on the dropdown toggle button and then bubbled up to the parent element.
 - Dropdown menus now have a `data-bs-popper="static"` attribute set when the positioning of the dropdown is static and `data-bs-popper="none"` when dropdown is in the navbar. This is added by our JavaScript and helps us use custom position styles without interfering with Popper's positioning.
+- `popperConfig` can be passed as a function that accepts the Bootstrap's default Popper config as an argument, so that you can merge this default configuration in your way.
 
 ## v5.0.0-beta1