Merge branch 'main' into gs/js-docsgs/js-docs

11 files changed, 128 insertions, 34 deletions

diff --git a/scss/_tables.scss b/scss/_tables.scss
index 601d86cc9f..1fdd43c6bb 100644
--- a/scss/_tables.scss
+++ b/scss/_tables.scss
@@ -42,7 +42,7 @@
 }
 
 .table-group-divider {
-  border-top: calc(2 * $table-border-width) solid $table-group-separator-color; // stylelint-disable-line function-disallowed-list
+  border-top: ($table-border-width * 2) solid $table-group-separator-color;
 }
 
 //
diff --git a/site/assets/js/snippets.js b/site/assets/js/snippets.js
index 4a9a9dc8f6..5e58493de5 100644
--- a/site/assets/js/snippets.js
+++ b/site/assets/js/snippets.js
@@ -1,5 +1,7 @@
-// NOTICE!! DO NOT USE ANY OF THIS JAVASCRIPT
-// IT'S ALL JUST JUNK FOR OUR DOCS!
+// NOTICE!!! Initially embedded in our docs this JavaScript
+// file contains elements that can help you create reproducible
+// use cases in StackBlitz for instance.
+// In a real project please adapt this content to your needs.
 // ++++++++++++++++++++++++++++++++++++++++++
 
 /*!
@@ -15,18 +17,28 @@
 (() => {
   'use strict'
 
-  // Tooltip and popover demos
-  // Tooltip and popover demos
+  // --------
+  // Tooltips
+  // --------
+  // Instanciate all tooltips in a docs or StackBlitz page
   document.querySelectorAll('[data-bs-toggle="tooltip"]')
     .forEach(tooltip => {
       new bootstrap.Tooltip(tooltip)
     })
 
+  // --------
+  // Popovers
+  // --------
+  // Instanciate all popovers in a docs or StackBlitz page
   document.querySelectorAll('[data-bs-toggle="popover"]')
     .forEach(popover => {
       new bootstrap.Popover(popover)
     })
 
+  // -------------------------------
+  // Toasts
+  // -------------------------------
+  // Used by 'Placement' example in docs or StackBlitz
   const toastPlacement = document.getElementById('toastPlacement')
   if (toastPlacement) {
     document.getElementById('selectToastPlacement').addEventListener('change', function () {
@@ -38,6 +50,7 @@
     })
   }
 
+  // Instanciate all toasts in a docs page only
   document.querySelectorAll('.bd-example .toast')
     .forEach(toastNode => {
       const toast = new bootstrap.Toast(toastNode, {
@@ -47,6 +60,7 @@
       toast.show()
     })
 
+  // Instanciate all toasts in a docs page only
   const toastTrigger = document.getElementById('liveToastBtn')
   const toastLiveExample = document.getElementById('liveToast')
   if (toastTrigger) {
@@ -57,6 +71,10 @@
     })
   }
 
+  // -------------------------------
+  // Alerts
+  // -------------------------------
+  // Used in 'Show live toast' example in docs or StackBlitz
   const alertPlaceholder = document.getElementById('liveAlertPlaceholder')
   const alertTrigger = document.getElementById('liveAlertBtn')
 
@@ -78,13 +96,19 @@
     })
   }
 
-  // Indeterminate checkbox example
+  // -------------------------------
+  // Checks & Radios
+  // -------------------------------
+  // Indeterminate checkbox example in docs and StackBlitz
   document.querySelectorAll('.bd-example-indeterminate [type="checkbox"]')
     .forEach(checkbox => {
       checkbox.indeterminate = true
     })
 
-  // Disable empty links in docs examples
+  // -------------------------------
+  // Links
+  // -------------------------------
+  // Disable empty links in docs examples only
   document.querySelectorAll('.bd-content [href="#"]')
     .forEach(link => {
       link.addEventListener('click', event => {
@@ -92,7 +116,10 @@
       })
     })
 
-  // Modal relatedTarget demo
+  // -------------------------------
+  // Modal
+  // -------------------------------
+  // Modal 'Varying modal content' example in docs and StackBlitz
   const exampleModal = document.getElementById('exampleModal')
   if (exampleModal) {
     exampleModal.addEventListener('show.bs.modal', event => {
@@ -110,7 +137,10 @@
     })
   }
 
-  // Offcanvas demo
+  // -------------------------------
+  // Offcanvas
+  // -------------------------------
+  // 'Offcanvas components' example in docs only
   const myOffcanvas = document.querySelector('.bd-example-offcanvas #offcanvas')
   if (myOffcanvas) {
     myOffcanvas.addEventListener('show.bs.offcanvas', event => {
diff --git a/site/content/docs/5.2/components/alerts.md b/site/content/docs/5.2/components/alerts.md
index 12cad35881..6962b7155f 100644
--- a/site/content/docs/5.2/components/alerts.md
+++ b/site/content/docs/5.2/components/alerts.md
@@ -27,7 +27,7 @@ Alerts are available for any length of text, as well as an optional close button
 
 Click the button below to show an alert (hidden with inline styles to start), then dismiss (and destroy) it with the built-in close button.
 
-{{< example >}}
+{{< example js_snippet="true" >}}
 <div id="liveAlertPlaceholder"></div>
 <button type="button" class="btn btn-primary" id="liveAlertBtn">Show live alert</button>
 {{< /example >}}
diff --git a/site/content/docs/5.2/components/modal.md b/site/content/docs/5.2/components/modal.md
index a2354eb855..4acfe4a751 100644
--- a/site/content/docs/5.2/components/modal.md
+++ b/site/content/docs/5.2/components/modal.md
@@ -444,7 +444,7 @@ Have a bunch of buttons that all trigger the same modal with slightly different
 
 Below is a live demo followed by example HTML and JavaScript. For more information, [read the modal events docs](#events) for details on `relatedTarget`.
 
-{{< example >}}
+{{< example js_snippet="true" >}}
 <button type="button" class="btn btn-primary" data-bs-toggle="modal" data-bs-target="#exampleModal" data-bs-whatever="@mdo">Open modal for @mdo</button>
 <button type="button" class="btn btn-primary" data-bs-toggle="modal" data-bs-target="#exampleModal" data-bs-whatever="@fat">Open modal for @fat</button>
 <button type="button" class="btn btn-primary" data-bs-toggle="modal" data-bs-target="#exampleModal" data-bs-whatever="@getbootstrap">Open modal for @getbootstrap</button>
diff --git a/site/content/docs/5.2/components/popovers.md b/site/content/docs/5.2/components/popovers.md
index b6d3b304df..a08850f94c 100644
--- a/site/content/docs/5.2/components/popovers.md
+++ b/site/content/docs/5.2/components/popovers.md
@@ -46,7 +46,7 @@ const popoverList = [...popoverTriggerList].map(popoverTriggerEl => new bootstra
 
 We use JavaScript similar to the snippet above to render the following live popover. Titles are set via `title` attribute and body content is set via `data-bs-content`.
 
-{{< example >}}
+{{< example js_snippet="true" >}}
 <button type="button" class="btn btn-lg btn-danger" data-bs-toggle="popover" title="Popover title" data-bs-content="And here's some amazing content. It's very engaging. Right?">Click to toggle popover</button>
 {{< /example >}}
 
@@ -54,7 +54,7 @@ We use JavaScript similar to the snippet above to render the following live popo
 
 Four options are available: top, right, bottom, and left. Directions are mirrored when using Bootstrap in RTL. Set `data-bs-placement` to change the direction.
 
-{{< example >}}
+{{< example js_snippet="true" >}}
 <button type="button" class="btn btn-secondary" data-bs-container="body" data-bs-toggle="popover" data-bs-placement="top" data-bs-content="Top popover">
   Popover on top
 </button>
@@ -87,7 +87,7 @@ You can customize the appearance of popovers using [CSS variables](#variables).
 
 {{< scss-docs name="custom-popovers" file="site/assets/scss/_component-examples.scss" >}}
 
-{{< example class="custom-popover-demo" >}}
+{{< example class="custom-popover-demo" js_snippet="true" >}}
 <button type="button" class="btn btn-secondary"
         data-bs-toggle="popover" data-bs-placement="right"
         data-bs-custom-class="custom-popover"
@@ -107,7 +107,7 @@ Use the `focus` trigger to dismiss popovers on the user's next click of a differ
 For proper cross-browser and cross-platform behavior, you must use the `<a>` tag, _not_ the `<button>` tag, and you also must include a [`tabindex`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/tabindex) attribute.
 {{< /callout >}}
 
-{{< example >}}
+{{< example js_snippet="true" >}}
 <a tabindex="0" class="btn btn-lg btn-danger" role="button" data-bs-toggle="popover" data-bs-trigger="focus" title="Dismissible popover" data-bs-content="And here's some amazing content. It's very engaging. Right?">Dismissible popover</a>
 {{< /example >}}
 
@@ -123,7 +123,7 @@ Elements with the `disabled` attribute aren't interactive, meaning users cannot
 
 For disabled popover triggers, you may also prefer `data-bs-trigger="hover focus"` so that the popover appears as immediate visual feedback to your users as they may not expect to _click_ on a disabled element.
 
-{{< example >}}
+{{< example js_snippet="true" >}}
 <span class="d-inline-block" tabindex="0" data-bs-toggle="popover" data-bs-trigger="hover focus" data-bs-content="Disabled popover">
   <button class="btn btn-primary" type="button" disabled>Disabled button</button>
 </span>
diff --git a/site/content/docs/5.2/components/toasts.md b/site/content/docs/5.2/components/toasts.md
index 8c46d9a825..3cae1998b0 100644
--- a/site/content/docs/5.2/components/toasts.md
+++ b/site/content/docs/5.2/components/toasts.md
@@ -197,7 +197,7 @@ Building on the above example, you can create different toast color schemes with
 
 Place toasts with custom CSS as you need them. The top right is often used for notifications, as is the top middle. If you're only ever going to show one toast at a time, put the positioning styles right on the `.toast`.
 
-{{< example >}}
+{{< example js_snippet="true" >}}
 <form>
   <div class="mb-3">
     <label for="selectToastPlacement">Toast placement</label>
diff --git a/site/content/docs/5.2/components/tooltips.md b/site/content/docs/5.2/components/tooltips.md
index 458301620a..ef5944b489 100644
--- a/site/content/docs/5.2/components/tooltips.md
+++ b/site/content/docs/5.2/components/tooltips.md
@@ -45,7 +45,7 @@ const tooltipList = [...tooltipTriggerList].map(tooltipTriggerEl => new bootstra
 
 Hover over the links below to see tooltips:
 
-{{< example class="tooltip-demo" >}}
+{{< example class="tooltip-demo" js_snippet="true" >}}
 <p class="muted">Placeholder text to demonstrate some <a href="#" data-bs-toggle="tooltip" title="Default tooltip">inline links</a> with tooltips. This is now just filler, no killer. Content placed here just to mimic the presence of <a href="#" data-bs-toggle="tooltip" title="Another tooltip">real text</a>. And all that just to give you an idea of how tooltips would look when used in real-world situations. So hopefully you've now seen how <a href="#" data-bs-toggle="tooltip" title="Another one here too">these tooltips on links</a> can work in practice, once you use them on <a href="#" data-bs-toggle="tooltip" title="The last tip!">your own</a> site or project.
 </p>
 {{< /example >}}
@@ -59,7 +59,7 @@ You can customize the appearance of tooltips using [CSS variables](#variables).
 {{< scss-docs name="custom-tooltip" file="site/assets/scss/_component-examples.scss" >}}
 
 
-{{< example class="tooltip-demo" >}}
+{{< example class="tooltip-demo" js_snippet="true" >}}
 <button type="button" class="btn btn-secondary"
         data-bs-toggle="tooltip" data-bs-placement="top"
         data-bs-custom-class="custom-tooltip"
diff --git a/site/content/docs/5.2/forms/checks-radios.md b/site/content/docs/5.2/forms/checks-radios.md
index 812e7c198e..d719689d3b 100644
--- a/site/content/docs/5.2/forms/checks-radios.md
+++ b/site/content/docs/5.2/forms/checks-radios.md
@@ -36,7 +36,7 @@ Our checks use custom Bootstrap icons to indicate checked or indeterminate state
 
 Checkboxes can utilize the `:indeterminate` pseudo class when manually set via JavaScript (there is no available HTML attribute for specifying it).
 
-{{< example class="bd-example-indeterminate">}}
+{{< example class="bd-example-indeterminate" js_snippet="true" >}}
 <div class="form-check">
   <input class="form-check-input" type="checkbox" value="" id="flexCheckIndeterminate">
   <label class="form-check-label" for="flexCheckIndeterminate">
diff --git a/site/content/docs/5.2/utilities/api.md b/site/content/docs/5.2/utilities/api.md
index ef6d9ac1eb..81017ee8eb 100644
--- a/site/content/docs/5.2/utilities/api.md
+++ b/site/content/docs/5.2/utilities/api.md
@@ -392,7 +392,6 @@ New utilities can be added to the default `$utilities` map with a `map-merge`. M
 @import "bootstrap/scss/maps";
 @import "bootstrap/scss/mixins";
 @import "bootstrap/scss/utilities";
-@import "bootstrap/scss/utilities/api";
 
 $utilities: map-merge(
   $utilities,
@@ -405,6 +404,8 @@ $utilities: map-merge(
     )
   )
 );
+
+@import "bootstrap/scss/utilities/api";
 ```
 
 ### Modify utilities
@@ -417,7 +418,6 @@ Modify existing utilities in the default `$utilities` map with `map-get` and `ma
 @import "bootstrap/scss/maps";
 @import "bootstrap/scss/mixins";
 @import "bootstrap/scss/utilities";
-@import "bootstrap/scss/utilities/api";
 
 $utilities: map-merge(
   $utilities,
@@ -433,6 +433,8 @@ $utilities: map-merge(
     ),
   )
 );
+
+@import "bootstrap/scss/utilities/api";
 ```
 
 #### Enable responsive
@@ -445,7 +447,6 @@ You can enable responsive classes for an existing set of utilities that are not
 @import "bootstrap/scss/maps";
 @import "bootstrap/scss/mixins";
 @import "bootstrap/scss/utilities";
-@import "bootstrap/scss/utilities/api";
 
 $utilities: map-merge(
   $utilities, (
@@ -455,6 +456,8 @@ $utilities: map-merge(
     ),
   )
 );
+
+@import "bootstrap/scss/utilities/api";
 ```
 
 This will now generate responsive variations of `.border` and `.border-0` for each breakpoint. Your generated CSS will look like this:
@@ -499,7 +502,6 @@ Missing v4 utilities, or used to another naming convention? The utilities API ca
 @import "bootstrap/scss/maps";
 @import "bootstrap/scss/mixins";
 @import "bootstrap/scss/utilities";
-@import "bootstrap/scss/utilities/api";
 
 $utilities: map-merge(
   $utilities, (
@@ -509,11 +511,13 @@ $utilities: map-merge(
     ),
   )
 );
+
+@import "bootstrap/scss/utilities/api";
 ```
 
 ### Remove utilities
 
-Remove any of the default utilities by setting the group key to `null`. For example, to remove all our `width` utilities, create a `$utilities` `map-merge` and add `"width": null` within.
+Remove any of the default utilities with the [`map-remove()` Sass function](https://sass-lang.com/documentation/modules/map#remove).
 
 ```scss
 @import "bootstrap/scss/functions";
@@ -521,7 +525,21 @@ Remove any of the default utilities by setting the group key to `null`. For exam
 @import "bootstrap/scss/maps";
 @import "bootstrap/scss/mixins";
 @import "bootstrap/scss/utilities";
+
+// Remove multiple utilities with a comma-separated list
+$utilities: map-remove($utilities, "width", "float");
+
 @import "bootstrap/scss/utilities/api";
+```
+
+You can also use the [`map-merge()` Sass function](https://sass-lang.com/documentation/modules/map#merge) and set the group key to `null` to remove the utility.
+
+```scss
+@import "bootstrap/scss/functions";
+@import "bootstrap/scss/variables";
+@import "bootstrap/scss/maps";
+@import "bootstrap/scss/mixins";
+@import "bootstrap/scss/utilities";
 
 $utilities: map-merge(
   $utilities,
@@ -529,6 +547,44 @@ $utilities: map-merge(
     "width": null
   )
 );
+
+@import "bootstrap/scss/utilities/api";
+```
+
+### Add, remove, modify
+
+You can add, remove, and modify many utilities all at once with the [`map-merge()` Sass function](https://sass-lang.com/documentation/modules/map#merge). Here's how you can combine the previous examples into one larger map.
+
+```scss
+@import "bootstrap/scss/functions";
+@import "bootstrap/scss/variables";
+@import "bootstrap/scss/maps";
+@import "bootstrap/scss/mixins";
+@import "bootstrap/scss/utilities";
+
+$utilities: map-merge(
+  $utilities,
+  (
+    // Remove the `width` utility
+    "width": null,
+
+    // Make an existing utility responsive
+    "border": map-merge(
+      map-get($utilities, "border"),
+      ( responsive: true ),
+    ),
+
+    // Add new utilities
+    "cursor": (
+      property: cursor,
+      class: cursor,
+      responsive: true,
+      values: auto pointer grab,
+    )
+  )
+);
+
+@import "bootstrap/scss/utilities/api";
 ```
 
 #### Remove utility in RTL
diff --git a/site/layouts/partials/scripts.html b/site/layouts/partials/scripts.html
index 56513c7ff8..5535d64391 100644
--- a/site/layouts/partials/scripts.html
+++ b/site/layouts/partials/scripts.html
@@ -26,11 +26,16 @@
   document.querySelectorAll('.btn-edit').forEach(btn => {
     btn.addEventListener('click', event => {
       const htmlSnippet = event.target.closest('.bd-code-snippet').querySelector('.bd-example').innerHTML
-      StackBlitzSDK.openBootstrapSnippet(htmlSnippet)
+
+      // Get extra classes for this example except '.bd-example'
+      const classes = Array.from(event.target.closest('.bd-code-snippet').querySelector('.bd-example').classList).filter(x => x !== 'bd-example').join(' ')
+
+      const jsSnippet = event.target.closest('.bd-code-snippet').querySelector('.btn-edit').getAttribute('data-js-snippet')
+      StackBlitzSDK.openBootstrapSnippet(htmlSnippet, jsSnippet, classes)
     })
   })
 
-  StackBlitzSDK.openBootstrapSnippet = snippet => {
+  StackBlitzSDK.openBootstrapSnippet = (htmlSnippet, jsSnippet, classes) => {
     const markup = `<!doctype html>
 <html lang="en">
   <head>
@@ -38,24 +43,25 @@
     <meta name="viewport" content="width=device-width, initial-scale=1">
     <link href="{{ .Site.Params.cdn.css }}" rel="stylesheet">
     <title>Bootstrap Example</title>
+    <${'script'} src="{{ .Site.Params.cdn.js_bundle }}"></${'script'}>
   </head>
-  <body>
+  <body class="p-3 ${classes}">
 
     <!-- Example Code -->
-${snippet.replace(/^/gm, '    ')}
+${htmlSnippet.replace(/^/gm, '    ')}
     <!-- End Example Code -->
-
-    <${'script'} src="{{ .Site.Params.cdn.js_bundle }}"></${'script'}>
   </body>
 </html>`
 
+    const jsSnippetContent = jsSnippet ? '{{ os.ReadFile "site/assets/js/snippets.js" }}' : null
     const project = {
       files: {
-        'index.html': markup
+        'index.html': markup,
+        'index.js': jsSnippetContent
       },
       title: 'Bootstrap Example',
       description: `Official example from ${window.location.href}`,
-      template: 'html',
+      template: jsSnippet ? 'javascript' : 'html',
       tags: ['bootstrap']
     }
 
diff --git a/site/layouts/shortcodes/example.html b/site/layouts/shortcodes/example.html
index 9bfa2c906c..a1685a0a6b 100644
--- a/site/layouts/shortcodes/example.html
+++ b/site/layouts/shortcodes/example.html
@@ -4,6 +4,7 @@
   `args` are all optional and can be one of the following:
     * id: the `div`'s id - default: ""
     * class: any extra class(es) to be added to the `div` - default: ""
+    * js_snippet: add extra JS snippet to StackBlitz - default: `false`
     * show_preview: if the preview should be output in the HTML - default: `true`
     * show_markup: if the markup should be output in the HTML - default: `true`
 */ -}}
@@ -13,6 +14,7 @@
 {{- $lang := .Get "lang" | default "html" -}}
 {{- $show_preview := .Get "show_preview" | default true -}}
 {{- $show_markup := .Get "show_markup" | default true -}}
+{{- $js_snippet := .Get "js_snippet" | default false -}}
 {{- $input := .Inner -}}
 
 <div class="bd-example-snippet bd-code-snippet">
@@ -27,7 +29,7 @@
       <div class="d-flex align-items-center highlight-toolbar bg-light ps-3 pe-2 py-1">
         <small class="font-monospace text-muted text-uppercase">{{- $lang -}}</small>
         <div class="d-flex ms-auto">
-          <button type="button" class="btn-edit text-nowrap" title="Try it on StackBlitz">
+          <button type="button" class="btn-edit text-nowrap"{{ with $js_snippet }} data-js-snippet="{{ $js_snippet }}"{{ end }} title="Try it on StackBlitz">
             <svg class="bi" role="img" aria-label="Try it"><use xlink:href="#lightning-charge-fill"/></svg>
           </button>
           <button type="button" class="btn-clipboard mt-0 me-0" title="Copy to clipboard">