feat(tooltip, popover): add support for contextual variants and custo…

…m class (closes #1983, #2075) (#3644)
bootstrap-vue · Jul 9, 2019 · 695edae · 695edae
1 parent 0d0f22b
commit 695edae
Show file tree

Hide file tree

Showing 24 changed files with 605 additions and 49 deletions.
diff --git a/src/_variables.scss b/src/_variables.scss
@@ -17,6 +17,16 @@ $b-toaster-offset-bottom: $b-toaster-offset-top !default;
 $b-toaster-offset-left: $b-toaster-offset-top !default;
 $b-toaster-offset-right: $b-toaster-offset-top !default;
 
+// --- Toast variant levels wrt theme color value ---
 $b-toast-bg-level: $alert-bg-level !default;
 $b-toast-border-level: $alert-border-level !default;
 $b-toast-color-level: $alert-color-level !default;
+
+// --- Tooltip variants ---
+$bv-enable-tooltip-variants: true !default;
+
+// --- Popover variant levels wrt theme color value ---
+$bv-enable-popover-variants: true !default;
+$bv-popover-bg-level: $alert-bg-level !default;
+$bv-popover-border-level: $alert-border-level !default;
+$bv-popover-color-level: $alert-color-level !default;
diff --git a/src/components/index.scss b/src/components/index.scss
@@ -9,5 +9,7 @@
 @import "navbar/index";
 @import "pagination/index";
 @import "pagination-nav/index";
+@import "popover/index";
 @import "table/index";
 @import "toast/index";
+@import "tooltip/index";
diff --git a/src/components/popover/README.md b/src/components/popover/README.md
@@ -16,17 +16,15 @@
 
 Things to know when using popover component:
 
-- Popovers rely on the 3rd party library Popper.js for positioning. The library is bundled with
-  BootstrapVue dist files!
+- Popovers rely on the 3rd party library [Popper.js](https://popper.js.org/) for positioning.
 - Popovers with zero-length title _and_ content are never displayed.
 - Specify `container` as `null` (default, appends to `<body>`) to avoid rendering problems in more
   complex components (like input groups, button groups, etc). You can use `container` to optionally
-  specify a different element to append the popover to.
+  specify a different element to append the rendered popover to.
 - Triggering popovers on hidden elements will not work.
 - Popovers for `disabled` elements must be triggered on a wrapper element.
 - When triggered from hyperlinks that span multiple lines, popovers will be centered. Use
   `white-space: nowrap;` on your `<a>`s, `<b-link>`s and `<router-link>`s to avoid this behavior.
-- Popovers must be hidden before their corresponding markup elements have been removed from the DOM.
 
 The `<b-popover>` component inserts a hidden (`display: none;`) `<div>` intermediate container
 element at the point in the DOM where the `<b-popover>` component is placed. This may affect layout
@@ -266,6 +264,49 @@ The special `blur` trigger **must** be used in combination with the `click` trig
 | `container`          | `null`           | Element string ID to append rendered popover into. If `null` or element not found, popover is appended to `<body>` (default)                                                                               | Any valid in-document unique element ID.                                                                                                         |
 | `boundary`           | `'scrollParent'` | The container that the popover will be constrained visually. The default should suffice in most cases, but you may need to change this if your target element is in a small container with overflow scroll | `'scrollParent'` (default), `'viewport'`, `'window'`, or a reference to an HTML element.                                                         |
 | `boundary-padding`   | `5`              | Amount of pixel used to define a minimum distance between the boundaries and the popover. This makes sure the popover always has a little padding between the edges of its container.                      | Any positive number                                                                                                                              |
+| `variant`            | `null`           | Contextual color variant for the popover                                                                                                                                                                   | Any contextual theme color variant name                                                                                                          |
+| `customClass`        | `null`           | A custom classname to apply to the popover outer wrapper element                                                                                                                                           | A string                                                                                                                                         |
+
+### Variants and custom class
+
+<span class="badge badge-info small">NEW in 2.0.0-rc.26</span>
+
+BootstrapVue's popovers support contextual color variants via our custom CSS, via the `variant`
+prop:
+
+```html
+<div class="text-center">
+  <b-button id="popover-button-variant">Button</b-button>
+  <b-popover target="popover-button-variant" variant="danger" triggers="focus">
+    <template slot="title">Danger!</template>
+    Danger variant popover
+  </b-popover>
+</div>
+
+<!-- b-popover-variant.vue -->
+```
+
+Bootstrap default theme variants are: `danger`, `warning`, `success`, `primary`, `secondary`,
+`info`, `light`, and `dark`. You can change or add additional variants via Bootstrap
+[SCSS variables](/docs/reference/theming)
+
+A custom class can be applied to the popover outer wrapper `<div>` by using the `custom-class` prop:
+
+```html
+<div class="text-center">
+  <b-button id="my-button">Button</b-button>
+  <b-popover target="my-button" custom-class="my-popover-class">
+    <template slot="title">Popover Title</template>
+    Popover content
+  </b-popover>
+</div>
+```
+
+**Note:** Custom classes will not work with scoped styles, as the popovers are appended to the
+document `<body>` element by default.
+
+Refer to the [popover directive](/docs/directives/popover) docs on applying variants and custom
+class to the directive version.
 
 ### Programmatically show and hide popover
 

diff --git a/src/components/popover/_popover.scss b/src/components/popover/_popover.scss
@@ -0,0 +1,97 @@
+@if $bv-enable-popover-variants {
+  @each $color, $value in $theme-colors {
+    .b-popover-#{$color} {
+      $po-bg-color: theme-color-level($color, $bv-popover-bg-level);
+      $po-border-color: theme-color-level($color, $bv-popover-border-level);
+      $po-color: theme-color-level($color, $bv-popover-color-level);
+      $po-header-bg: darken($po-bg-color, 3%);
+      $po-header-color: color-yiq($po-header-bg);
+      $po-arrow-color: $po-bg-color;
+      $po-arrow-color-bottom: $po-header-bg;
+      $po-arrow-outer-color: fade-in($po-border-color, .05);
+
+      &.popover {
+        background-color: $po-bg-color;
+        border-color: $po-border-color;
+      }
+
+      &.bs-popover-top {
+        > .arrow {
+          &::before {
+            border-top-color: $po-arrow-outer-color;
+          }
+
+          &::after {
+            border-top-color: $po-arrow-color;
+          }
+        }
+      }
+
+      &.bs-popover-right {
+        > .arrow {
+          &::before {
+            border-right-color: $po-arrow-outer-color;
+          }
+
+          &::after {
+            border-right-color: $po-arrow-color;
+          }
+        }
+      }
+
+      &.bs-popover-bottom {
+        > .arrow {
+          &::before {
+            border-bottom-color: $po-arrow-outer-color;
+          }
+
+          &::after {
+            // Use the header bg color
+            border-bottom-color: $po-arrow-color-bottom;
+          }
+        }
+
+        .popover-header::before {
+          border-bottom-color: $po-header-bg;
+        }
+      }
+
+      &.bs-popover-left {
+        > .arrow {
+          &::before {
+            border-left-color: $po-arrow-outer-color;
+          }
+
+          &::after {
+            border-left-color: $po-arrow-color;
+          }
+        }
+      }
+
+      &.bs-popover-auto {
+        &[x-placement^="top"] {
+          @extend .bs-popover-top;
+        }
+        &[x-placement^="right"] {
+          @extend .bs-popover-right;
+        }
+        &[x-placement^="bottom"] {
+          @extend .bs-popover-bottom;
+        }
+        &[x-placement^="left"] {
+          @extend .bs-popover-left;
+        }
+      }
+
+      .popover-header {
+        color: $po-header-color;
+        background-color: $po-header-bg;
+        border-bottom-color: darken($po-header-bg, 5%);
+      }
+
+      .popover-body {
+        color: $po-color;
+      }
+    }
+  }
+}
diff --git a/src/components/popover/index.scss b/src/components/popover/index.scss
@@ -0,0 +1 @@
+@import "popover";
diff --git a/src/components/popover/package.json b/src/components/popover/package.json
@@ -4,6 +4,7 @@
   "meta": {
     "title": "Popover",
     "description": "The Popover feature provides a tooltip-like behavior, can be easily applied to any interactive element via the <b-popover> component or v-b-popover directive",
+    "enhanced": true,
     "directives": [
       "VBPopover"
     ],

diff --git a/src/components/popover/popover.js b/src/components/popover/popover.js
@@ -33,6 +33,14 @@ export const props = {
       return isArray(value) || arrayIncludes(['flip', 'clockwise', 'counterclockwise'], value)
     }
   },
+  variant: {
+    type: String,
+    default: () => getComponentConfig(NAME, 'variant')
+  },
+  customClass: {
+    type: String,
+    default: () => getComponentConfig(NAME, 'customClass')
+  },
   delay: {
     type: [Number, Object, String],
     default: () => getComponentConfig(NAME, 'delay')

diff --git a/src/components/popover/popover.spec.js b/src/components/popover/popover.spec.js
@@ -6,7 +6,17 @@ const localVue = new CreateLocalVue()
 
 // Our test application definition
 const appDef = {
-  props: ['triggers', 'show', 'disabled', 'noFade', 'title', 'titleAttr', 'btnDisabled'],
+  props: [
+    'triggers',
+    'show',
+    'disabled',
+    'noFade',
+    'title',
+    'titleAttr',
+    'btnDisabled',
+    'variant',
+    'customClass'
+  ],
   render(h) {
     return h('article', { attrs: { id: 'wrapper' } }, [
       h(
@@ -30,7 +40,9 @@ const appDef = {
             triggers: this.triggers,
             show: this.show,
             disabled: this.disabled,
-            noFade: this.noFade || false
+            noFade: this.noFade || false,
+            variant: this.variant,
+            customClass: this.customClass
           }
         },
         [h('template', { slot: 'title' }, this.$slots.title), this.$slots.default || '']
@@ -45,7 +57,7 @@ const appDef = {
 
 // Note: `wrapper.destroy()` MUST be called at the end of each test in order for
 // the next test to function properly!
-describe('tooltip', () => {
+describe('b-popover', () => {
   const originalCreateRange = document.createRange
   const origGetBCR = Element.prototype.getBoundingClientRect
 

diff --git a/src/components/tooltip/README.md b/src/components/tooltip/README.md
@@ -15,8 +15,7 @@
 
 Things to know when using tooltip component:
 
-- Tooltips rely on the 3rd party library Popper.js for positioning. The library is bundled with
-  BootstrapVue in the dist files!
+- Tooltips rely on the 3rd party library [Popper.js](https://popper.js.org/) for positioning.
 - Tooltips with zero-length titles are never displayed.
 - Triggering tooltips on hidden elements will not work.
 - Specify `container` as `null` (default, appends to `<body>`) to avoid rendering problems in more
@@ -25,7 +24,6 @@ Things to know when using tooltip component:
 - Tooltips for `disabled` elements must be triggered on a wrapper element.
 - When triggered from hyperlinks that span multiple lines, tooltips will be centered. Use
   white-space: nowrap; on your `<a>`s, `<b-link>`s and `<router-link>`s to avoid this behavior.
-- Tooltips must be hidden before their corresponding elements have been removed from the DOM.
 
 The `<b-tooltip>` component inserts a hidden (`display:none`) `<div>` intermediate container element
 at the point in the DOM where the `<b-tooltip>` component is placed. This may affect layout and/or
@@ -156,6 +154,43 @@ then clicks the trigger element, they must click it again **and** move focus to
 | `container`          | `null`           | Element string ID to append rendered tooltip into. If `null` or element not found, tooltip is appended to `<body>` (default)                                                                               | Any valid in-document unique element ID.                                                                                                         |
 | `boundary`           | `'scrollParent'` | The container that the tooltip will be constrained visually. The default should suffice in most cases, but you may need to change this if your target element is in a small container with overflow scroll | `'scrollParent'` (default), `'viewport'`, `'window'`, or a reference to an HTML element.                                                         |
 | `boundary-padding`   | `5`              | Amount of pixel used to define a minimum distance between the boundaries and the tooltip. This makes sure the tooltip always has a little padding between the edges of its container.                      | Any positive number                                                                                                                              |
+| `variant`            | `null`           | Contextual color variant for the tooltip                                                                                                                                                                   | Any contextual theme color variant name                                                                                                          |
+| `customClass`        | `null`           | A custom classname to apply to the tooltip outer wrapper element                                                                                                                                           | A string                                                                                                                                         |
+
+### Variants and custom class
+
+<span class="badge badge-info small">NEW in 2.0.0-rc.26</span>
+
+BootstrapVue's tooltips support contextual color variants via our custom CSS, via the `variant`
+prop:
+
+```html
+<div class="text-center">
+  <b-button id="tooltip-button-variant">Button</b-button>
+  <b-tooltip target="tooltip-button-variant" variant="danger">Danger variant tooltip</b-tooltip>
+</div>
+
+<!-- b-tooltip-variant.vue -->
+```
+
+Bootstrap default theme variants are: `danger`, `warning`, `success`, `primary`, `secondary`,
+`info`, `light`, and `dark`. You can change or add additional variants via Bootstrap
+[SCSS variables](/docs/reference/theming)
+
+A custom class can be applied to the tooltip outer wrapper `<div>` by using the `custom-class` prop:
+
+```html
+<div class="text-center">
+  <b-button id="my-button">Button</b-button>
+  <b-tooltip target="my-button" custom-class="my-tooltip-class">Tooltip Title</b-tooltip>
+</div>
+```
+
+**Note:** Custom classes will not work with scoped styles, as the tooltips are appended to the
+document `<body>` element by default.
+
+Refer to the [tooltip directive](/docs/directives/tooltip) docs on applying variants and custom
+class to the directive version.
 
 ### Programmatically show and hide tooltip
 

diff --git a/src/components/tooltip/_tooltip.scss b/src/components/tooltip/_tooltip.scss
@@ -0,0 +1,52 @@
+// Create custom variants for tooltips
+@if $bv-enable-tooltip-variants {
+  @each $color, $value in $theme-colors {
+    .tooltip.b-tooltip-#{$color} {
+      $tip-text-color: color-yiq($value);
+
+      &.bs-tooltip-top {
+        .arrow::before {
+          border-top-color: $value;
+        }
+      }
+
+      &.bs-tooltip-right {
+        .arrow::before {
+          border-right-color: $value;
+        }
+      }
+
+      &.bs-tooltip-bottom {
+        .arrow::before {
+          border-bottom-color: $value;
+        }
+      }
+
+      &.bs-tooltip-left {
+        .arrow::before {
+          border-left-color: $value;
+        }
+      }
+
+      &.bs-tooltip-auto {
+        &[x-placement^="top"] {
+          @extend .bs-tooltip-top;
+        }
+        &[x-placement^="right"] {
+          @extend .bs-tooltip-right;
+        }
+        &[x-placement^="bottom"] {
+          @extend .bs-tooltip-bottom;
+        }
+        &[x-placement^="left"] {
+          @extend .bs-tooltip-left;
+        }
+      }
+
+      .tooltip-inner {
+        color: color-yiq($value);
+        background-color: $value;
+      }
+    }
+  }
+}
diff --git a/src/components/tooltip/index.scss b/src/components/tooltip/index.scss
@@ -0,0 +1 @@
+@import "tooltip";
diff --git a/src/components/tooltip/package.json b/src/components/tooltip/package.json
@@ -4,6 +4,7 @@
   "meta": {
     "title": "Tooltip",
     "description": "Easily add tooltips to elements or components via the <b-tooltip> component or v-b-tooltip directive.",
+    "enhanced": true,
     "directives": [
       "VBTooltip"
     ],

diff --git a/src/components/tooltip/tooltip.js b/src/components/tooltip/tooltip.js
@@ -33,6 +33,14 @@ export const BTooltip = /*#__PURE__*/ Vue.extend({
         return isArray(value) || arrayIncludes(['flip', 'clockwise', 'counterclockwise'], value)
       }
     },
+    variant: {
+      type: String,
+      default: () => getComponentConfig(NAME, 'variant')
+    },
+    customClass: {
+      type: String,
+      default: () => getComponentConfig(NAME, 'customClass')
+    },
     delay: {
       type: [Number, Object, String],
       default: () => getComponentConfig(NAME, 'delay')