Convert popovers to CSS variables

Deprecates two variables in the process

4 files changed, 140 insertions, 61 deletions

diff --git a/scss/_popover.scss b/scss/_popover.scss
index 3b8208e16..52276a4ff 100644
--- a/scss/_popover.scss
+++ b/scss/_popover.scss
@@ -1,27 +1,47 @@
 .popover {
+  // scss-docs-start popover-css-vars
+  --#{$variable-prefix}popover-max-width: #{$popover-max-width};
+  --#{$variable-prefix}popover-font-size: #{$popover-font-size};
+  --#{$variable-prefix}popover-bg: #{$popover-bg};
+  --#{$variable-prefix}popover-border-width: #{$popover-border-width};
+  --#{$variable-prefix}popover-border-color: #{$popover-border-color};
+  --#{$variable-prefix}popover-border-radius: #{$popover-border-radius};
+  --#{$variable-prefix}popover-box-shadow: #{$popover-box-shadow};
+  --#{$variable-prefix}popover-header-padding: #{$popover-header-padding-y $popover-header-padding-x};
+  --#{$variable-prefix}popover-header-color: #{$popover-header-color};
+  --#{$variable-prefix}popover-header-bg: #{$popover-header-bg};
+  --#{$variable-prefix}popover-body-padding: #{$popover-body-padding-y $popover-body-padding-x};
+  --#{$variable-prefix}popover-body-font-size: #{$popover-font-size};
+  --#{$variable-prefix}popover-body-color: #{$popover-body-color};
+  --#{$variable-prefix}popover-arrow-width: #{$popover-arrow-width};
+  --#{$variable-prefix}popover-arrow-height: #{$popover-arrow-height};
+  --#{$variable-prefix}popover-arrow-border: var(--#{$variable-prefix}popover-border-color);
+  // scss-docs-end popover-css-vars
+
   position: absolute;
   top: 0;
   left: 0 #{"/* rtl:ignore */"};
   z-index: $zindex-popover;
   display: block;
-  max-width: $popover-max-width;
+  max-width: var(--#{$variable-prefix}popover-max-width);
   // Our parent element can be arbitrary since tooltips are by default inserted as a sibling of their target element.
   // So reset our font and text properties to avoid inheriting weird values.
   @include reset-text();
-  @include font-size($popover-font-size);
+  font-size: var(--#{$variable-prefix}popover-font-size);
   // Allow breaking very long words so they don't overflow the popover's bounds
   word-wrap: break-word;
-  background-color: $popover-bg;
+  background-color: var(--#{$variable-prefix}popover-bg);
   background-clip: padding-box;
-  border: $popover-border-width solid $popover-border-color;
-  @include border-radius($popover-border-radius);
-  @include box-shadow($popover-box-shadow);
+  border: var(--#{$variable-prefix}popover-border-width) solid var(--#{$variable-prefix}popover-border-color);
+  // border-radius: var(--#{$variable-prefix}popover-border-radius);
+  @include border-radius(var(--#{$variable-prefix}popover-border-radius));
+  @include box-shadow(var(--#{$variable-prefix}popover-bg));
 
   .popover-arrow {
     position: absolute;
     display: block;
-    width: $popover-arrow-width;
-    height: $popover-arrow-height;
+    width: var(--#{$variable-prefix}popover-arrow-width);
+    height: var(--#{$variable-prefix}popover-arrow-height);
 
     &::before,
     &::after {
@@ -30,62 +50,70 @@
       content: "";
       border-color: transparent;
       border-style: solid;
+      border-width: 0;
     }
   }
 }
 
+
 .bs-popover-top {
   > .popover-arrow {
-    bottom: subtract(-$popover-arrow-height, $popover-border-width);
+    bottom: calc((var(--#{$variable-prefix}popover-arrow-height)) * -1); // stylelint-disable-line function-disallowed-list
 
     &::before {
       bottom: 0;
-      border-width: $popover-arrow-height ($popover-arrow-width * .5) 0;
-      border-top-color: $popover-arrow-outer-color;
+      border-top-color: var(--#{$variable-prefix}popover-arrow-border);
+      border-top-width: var(--#{$variable-prefix}popover-arrow-height);
+      border-inline-width: calc(var(--#{$variable-prefix}popover-arrow-width) * .5); // stylelint-disable-line function-disallowed-list
     }
 
     &::after {
-      bottom: $popover-border-width;
-      border-width: $popover-arrow-height ($popover-arrow-width * .5) 0;
-      border-top-color: $popover-arrow-color;
+      bottom: var(--#{$variable-prefix}popover-border-width);
+      border-top-color: var(--#{$variable-prefix}popover-bg);
+      border-top-width: var(--#{$variable-prefix}popover-arrow-height);
+      border-inline-width: calc(var(--#{$variable-prefix}popover-arrow-width) * .5); // stylelint-disable-line function-disallowed-list
     }
   }
 }
 
 .bs-popover-end {
   > .popover-arrow {
-    left: subtract(-$popover-arrow-height, $popover-border-width);
-    width: $popover-arrow-height;
-    height: $popover-arrow-width;
+    left: calc((var(--#{$variable-prefix}popover-arrow-height)) * -1); // stylelint-disable-line function-disallowed-list
+    width: var(--#{$variable-prefix}popover-arrow-height);
+    height: var(--#{$variable-prefix}popover-arrow-width);
 
     &::before {
       left: 0;
-      border-width: ($popover-arrow-width * .5) $popover-arrow-height ($popover-arrow-width * .5) 0;
-      border-right-color: $popover-arrow-outer-color;
+      border-right-color: var(--#{$variable-prefix}popover-arrow-border);
+      border-right-width: var(--#{$variable-prefix}popover-arrow-height);
+      border-block-width: calc(var(--#{$variable-prefix}popover-arrow-width) * .5); // stylelint-disable-line function-disallowed-list
     }
 
     &::after {
       left: $popover-border-width;
-      border-width: ($popover-arrow-width * .5) $popover-arrow-height ($popover-arrow-width * .5) 0;
-      border-right-color: $popover-arrow-color;
+      border-right-color: var(--#{$variable-prefix}popover-bg);
+      border-right-width: var(--#{$variable-prefix}popover-arrow-height);
+      border-block-width: calc(var(--#{$variable-prefix}popover-arrow-width) * .5); // stylelint-disable-line function-disallowed-list
     }
   }
 }
 
 .bs-popover-bottom {
   > .popover-arrow {
-    top: subtract(-$popover-arrow-height, $popover-border-width);
+    top: calc((var(--#{$variable-prefix}popover-arrow-height)) * -1); // stylelint-disable-line function-disallowed-list
 
     &::before {
       top: 0;
-      border-width: 0 ($popover-arrow-width * .5) $popover-arrow-height ($popover-arrow-width * .5);
-      border-bottom-color: $popover-arrow-outer-color;
+      border-bottom-color: var(--#{$variable-prefix}popover-arrow-border);
+      border-bottom-width: var(--#{$variable-prefix}popover-arrow-height);
+      border-inline-width: calc(var(--#{$variable-prefix}popover-arrow-width) * .5); // stylelint-disable-line function-disallowed-list
     }
 
     &::after {
-      top: $popover-border-width;
-      border-width: 0 ($popover-arrow-width * .5) $popover-arrow-height ($popover-arrow-width * .5);
-      border-bottom-color: $popover-arrow-color;
+      top: var(--#{$variable-prefix}popover-border-width);
+      border-bottom-color: var(--#{$variable-prefix}popover-bg);
+      border-bottom-width: var(--#{$variable-prefix}popover-arrow-height);
+      border-inline-width: calc(var(--#{$variable-prefix}popover-arrow-width) * .5); // stylelint-disable-line function-disallowed-list
     }
   }
 
@@ -95,29 +123,31 @@
     top: 0;
     left: 50%;
     display: block;
-    width: $popover-arrow-width;
-    margin-left: -$popover-arrow-width * .5;
+    width: var(--#{$variable-prefix}popover-arrow-width);
+    margin-left: calc(var(--#{$variable-prefix}popover-arrow-width) * -.5); // stylelint-disable-line function-disallowed-list
     content: "";
-    border-bottom: $popover-border-width solid $popover-header-bg;
+    border-bottom: var(--#{$variable-prefix}popover-border-width) solid var(--#{$variable-prefix}popover-header-bg);
   }
 }
 
 .bs-popover-start {
   > .popover-arrow {
-    right: subtract(-$popover-arrow-height, $popover-border-width);
-    width: $popover-arrow-height;
-    height: $popover-arrow-width;
+    right: calc((var(--#{$variable-prefix}popover-arrow-height)) * -1); // stylelint-disable-line function-disallowed-list
+    width: var(--#{$variable-prefix}popover-arrow-height);
+    height: var(--#{$variable-prefix}popover-arrow-width);
 
     &::before {
       right: 0;
-      border-width: ($popover-arrow-width * .5) 0 ($popover-arrow-width * .5) $popover-arrow-height;
-      border-left-color: $popover-arrow-outer-color;
+      border-left-color: var(--#{$variable-prefix}popover-arrow-border);
+      border-left-width: var(--#{$variable-prefix}popover-arrow-height);
+      border-block-width: calc(var(--#{$variable-prefix}popover-arrow-width) * .5); // stylelint-disable-line function-disallowed-list
     }
 
     &::after {
       right: $popover-border-width;
-      border-width: ($popover-arrow-width * .5) 0 ($popover-arrow-width * .5) $popover-arrow-height;
-      border-left-color: $popover-arrow-color;
+      border-left-color: var(--#{$variable-prefix}popover-bg);
+      border-left-width: var(--#{$variable-prefix}popover-arrow-height);
+      border-block-width: calc(var(--#{$variable-prefix}popover-arrow-width) * .5); // stylelint-disable-line function-disallowed-list
     }
   }
 }
@@ -139,12 +169,12 @@
 
 // Offset the popover to account for the popover arrow
 .popover-header {
-  padding: $popover-header-padding-y $popover-header-padding-x;
+  padding: var(--#{$variable-prefix}popover-header-padding);
   margin-bottom: 0; // Reset the default from Reboot
   @include font-size($font-size-base);
-  color: $popover-header-color;
-  background-color: $popover-header-bg;
-  border-bottom: $popover-border-width solid $popover-border-color;
+  color: var(--#{$variable-prefix}popover-header-color);
+  background-color: var(--#{$variable-prefix}popover-header-bg);
+  border-bottom: var(--#{$variable-prefix}popover-border-width) solid var(--#{$variable-prefix}popover-border-color);
   @include border-top-radius($popover-inner-border-radius);
 
   &:empty {
@@ -153,6 +183,6 @@
 }
 
 .popover-body {
-  padding: $popover-body-padding-y $popover-body-padding-x;
-  color: $popover-body-color;
+  padding: var(--#{$variable-prefix}popover-body-padding);
+  color: var(--#{$variable-prefix}popover-body-color);
 }
diff --git a/scss/_variables.scss b/scss/_variables.scss
index 0568adc12..35183180a 100644
--- a/scss/_variables.scss
+++ b/scss/_variables.scss
@@ -1322,7 +1322,7 @@ $tooltip-margin:                    0 !default;
 $tooltip-arrow-width:               .8rem !default;
 $tooltip-arrow-height:              .4rem !default;
 // fusv-disable
-$tooltip-arrow-color:               null !default; // Deprecated in v5.2.0 for CSS variables
+$tooltip-arrow-color:               null !default; // Deprecated in Bootstrap 5.2.0 for CSS variables
 // fusv-enable
 // scss-docs-end tooltip-variables
 
@@ -1360,10 +1360,13 @@ $popover-body-padding-x:            $spacer !default;
 
 $popover-arrow-width:               1rem !default;
 $popover-arrow-height:              .5rem !default;
-$popover-arrow-color:               $popover-bg !default;
+// scss-docs-end popover-variables
 
+// fusv-disable
+// Deprecated in Bootstrap 5.2.0 for CSS variables
+$popover-arrow-color:               $popover-bg !default;
 $popover-arrow-outer-color:         fade-in($popover-border-color, .05) !default;
-// scss-docs-end popover-variables
+// fusv-enable
 
 
 // Toasts
diff --git a/site/assets/scss/_component-examples.scss b/site/assets/scss/_component-examples.scss
index f0fc4d7f7..effde2d95 100644
--- a/site/assets/scss/_component-examples.scss
+++ b/site/assets/scss/_component-examples.scss
@@ -237,6 +237,14 @@
   --bs-tooltip-bg: var(--bs-primary);
 }
 
+.custom-popover {
+  --bs-popover-max-width: 200px;
+  --bs-popover-border-color: var(--bs-primary);
+  --bs-popover-header-bg: var(--bs-primary);
+  --bs-popover-header-color: var(--bs-white);
+  --bs-popover-body-padding: .5rem 1rem;
+}
+
 // Scrollspy demo on fixed height div
 .scrollspy-example {
   position: relative;
diff --git a/site/content/docs/5.1/components/popovers.md b/site/content/docs/5.1/components/popovers.md
index 4511645ce..5635f0bca 100644
--- a/site/content/docs/5.1/components/popovers.md
+++ b/site/content/docs/5.1/components/popovers.md
@@ -10,7 +10,7 @@ toc: true
 
 Things to know when using the popover plugin:
 
-- Popovers rely on the 3rd party library [Popper](https://popper.js.org/) for positioning. You must include [popper.min.js]({{< param "cdn.popper" >}}) before bootstrap.js or use `bootstrap.bundle.min.js` / `bootstrap.bundle.js` which contains Popper in order for popovers to work!
+- Popovers rely on the third party library [Popper](https://popper.js.org/) for positioning. You must include [popper.min.js]({{< param "cdn.popper" >}}) before `bootstrap.js`, or use one `bootstrap.bundle.min.js` which contains Popper.
 - Popovers require the [tooltip plugin]({{< docsref "/components/tooltips" >}}) as a dependency.
 - Popovers are opt-in for performance reasons, so **you must initialize them yourself**.
 - Zero-length `title` and `content` values will never show a popover.
@@ -31,9 +31,11 @@ Things to know when using the popover plugin:
 
 Keep reading to see how popovers work with some examples.
 
-## Example: Enable popovers everywhere
+## Examples
 
-One way to initialize all popovers on a page would be to select them by their `data-bs-toggle` attribute:
+### Enable popovers
+
+As mentioned above, you must initialize popovers before they can be used. One way to initialize all popovers on a page would be to select them by their `data-bs-toggle` attribute, like so:
 
 ```js
 var popoverTriggerList = [].slice.call(document.querySelectorAll('[data-bs-toggle="popover"]'))
@@ -42,17 +44,9 @@ var popoverList = popoverTriggerList.map(function (popoverTriggerEl) {
 })
 ```
 
-## Example: Using the `container` option
-
-When you have some styles on a parent element that interfere with a popover, you'll want to specify a custom `container` so that the popover's HTML appears within that element instead.
-
-```js
-var popover = new bootstrap.Popover(document.querySelector('.example-popover'), {
-  container: 'body'
-})
-```
+### Live demo
 
-## Example
+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 >}}
 <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>
@@ -60,7 +54,7 @@ var popover = new bootstrap.Popover(document.querySelector('.example-popover'),
 
 ### Four directions
 
-Four options are available: top, right, bottom, and left aligned. Directions are mirrored when using Bootstrap in RTL.
+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 >}}
 <button type="button" class="btn btn-secondary" data-bs-container="body" data-bs-toggle="popover" data-bs-placement="top" data-bs-content="Top popover">
@@ -77,6 +71,42 @@ Four options are available: top, right, bottom, and left aligned. Directions are
 </button>
 {{< /example >}}
 
+### Custom `container`
+
+When you have some styles on a parent element that interfere with a popover, you'll want to specify a custom `container` so that the popover's HTML appears within that element instead. This is common in responsive tables, input groups, and the like.
+
+```js
+var popover = new bootstrap.Popover(document.querySelector('.example-popover'), {
+  container: 'body'
+})
+```
+
+### Custom popovers
+
+<small class="d-inline-flex px-2 py-1 font-monospace text-muted border rounded-3">Added in v5.2.0</small>
+
+You can customize the appearance of popovers using [CSS variables](#variables). We set a custom class with `data-bs-custom-class="custom-popover"` to scope our custom appearance and use it to override some of the local CSS variables.
+
+```css
+.custom-popover {
+  --bs-popover-max-width: 200px;
+  --bs-popover-border-color: var(--bs-primary);
+  --bs-popover-header-bg: var(--bs-primary);
+  --bs-popover-header-color: var(--bs-white);
+  --bs-popover-body-padding: .5rem 1rem;
+}
+```
+
+{{< example class="custom-popover-demo" >}}
+<button type="button" class="btn btn-secondary"
+        data-bs-toggle="popover" data-bs-placement="right"
+        data-bs-custom-class="custom-popover"
+        title="Custom popover"
+        data-bs-content="This popover is themed via CSS variables.">
+  Custom popover
+</button>
+{{< /example >}}
+
 ### Dismiss on next click
 
 Use the `focus` trigger to dismiss popovers on the user's next click of a different element than the toggle element.
@@ -109,10 +139,18 @@ For disabled popover triggers, you may also prefer `data-bs-trigger="hover focus
 </span>
 {{< /example >}}
 
-## Sass
+## CSS
 
 ### Variables
 
+<small class="d-inline-flex px-2 py-1 font-monospace text-muted border rounded-3">Added in v5.2.0</small>
+
+As part of Bootstrap’s evolving CSS variables approach, popovers now use local CSS variables on `.popover` for enhanced real-time customization. Values for the CSS variables are set via Sass, so Sass customization is still supported, too.
+
+{{< scss-docs name="popover-css-vars" file="scss/_popover.scss" >}}
+
+### Sass variables
+
 {{< scss-docs name="popover-variables" file="scss/_variables.scss" >}}
 
 ## Usage