docs(popovers, tooltips): add info about focus only trigger and cross platform behaviour (#4767)

tmorehouse · jacobmllr95 · web-flow · commit 97a65c2150c2 · 2020-02-14T19:12:17.000+01:00
* docs(popovers, tooltips): add info about focus only trigger and cross platform behaviour

* Update README.md

* Update README.md

* Update README.md

* Update README.md

* Update README.md

* Update README.md

* Update README.md

* Update README.md

Co-authored-by: Jacob Müller &lt;jacob.mueller.elz@gmail.com&gt;
diff --git a/src/components/popover/README.md b/src/components/popover/README.md
@@ -160,11 +160,37 @@ If a popover has more than one trigger, then all triggers must be cleared before
 close. I.e. if a popover has the trigger `focus click`, and it was opened by `focus`, and the user
 then clicks the trigger element, they must click it again **and** move focus to close the popover.
 
+### Caveats with `focus` trigger on `<button>` elements
+
+For proper cross-browser and cross-platform behavior when using only the `focus` trigger, you must
+use an element that renders the `<a>` tag, not the `<button>` tag, and you also must include a
+`tabindex="0"` attribute.
+
+The following will generate an `<a>` that looks like a button:
+
+```html
+<b-button
+  href="#"
+  tabindex="0"
+  v-b-popover.focus="'Popover content'"
+  title="Popover title"
+>
+  Link button with popover directive
+</b-button>
+
+<b-button id="link-button" href="#" tabindex="0">
+  Link button with popover component
+</b-button>
+<b-popover target="link-button" title="Popover title" triggers="focus">
+  Popover content
+</b-popover>
+```
+
 ### Dismiss on next click (self-dismissing)
 
 Use the `focus` trigger by itself to dismiss popovers on the next click that the user makes. `focus`
 also makes the popover activate on both `focus` and `click` (as a click makes the element receive
-focus, assuming it is in the tab sequence of the page).
+focus on most browsers, assuming it is in the tab sequence of the page).
 
 You can, however, specify your trigger as `click blur`, which will make only a click activate the
 popover, and either a click on the element, _or_ losing focus to another element or part of the
@@ -274,7 +300,7 @@ prop:
 
 ```html
 <div class="text-center">
-  <b-button id="popover-button-variant">Button</b-button>
+  <b-button id="popover-button-variant" href="#" tabindex="0">Button</b-button>
   <b-popover target="popover-button-variant" variant="danger" triggers="focus">
     <template v-slot:title>Danger!</template>
     Danger variant popover
diff --git a/src/components/tooltip/README.md b/src/components/tooltip/README.md
@@ -106,6 +106,32 @@ If a tooltip has more than one trigger, then all triggers must be cleared before
 close. I.e. if a tooltip has the trigger `focus click`, and it was opened by `focus`, and the user
 then clicks the trigger element, they must click it again **and** move focus to close the tooltip.
 
+### Caveats with `focus` trigger on `<button>` elements
+
+For proper cross-browser and cross-platform behavior when using only the `focus` trigger, you must
+use an element that renders the `<a>` tag, not the `<button>` tag, and you also must include a
+`tabindex="0"` attribute.
+
+The following will generate an `<a>` that looks like a button:
+
+```html
+<b-button
+  href="#"
+  tabindex="0"
+  v-b-tooltip.focus
+  title="Tooltip title"
+>
+  Link button with tooltip directive
+</b-button>
+
+<b-button id="link-button" href="#" tabindex="0">
+  Link button with tooltip component
+</b-button>
+<b-tooltip target="link-button" title="Tooltip title" triggers="focus">
+  Tooltip title
+</b-tooltip>
+```
+
 ### Making tooltips work for keyboard and assistive technology users
 
 You should only add tooltips to HTML elements that are traditionally keyboard-focusable and
diff --git a/src/directives/popover/README.md b/src/directives/popover/README.md
@@ -215,6 +215,25 @@ assistive technologies currently do not announce the popover in this situation.
 Additionally, do not rely solely on `hover` as the trigger for your popover, as this will make your
 popovers _impossible to trigger for keyboard-only users_.
 
+### Caveats with `focus` trigger on `<button>` elements
+
+For proper cross-browser and cross-platform behavior when using only the `focus` trigger, you must
+use an element that renders the `<a>` tag, not the `<button>` tag, and you also must include a
+`tabindex="0"` attribute.
+
+The following will generate an `<a>` that looks like a button:
+
+```html
+<b-button
+  href="#"
+  tabindex="0"
+  v-b-popover.focus="'Popover content'"
+  title="Popover title"
+>
+  Link button with popover directive
+</b-button>
+```
+
 ### Dismiss on next click (self dismissing)
 
 Use the `focus` trigger by itself to dismiss popovers on the next click that the user makes. `focus`
diff --git a/src/directives/tooltip/README.md b/src/directives/tooltip/README.md
@@ -172,6 +172,25 @@ override the `pointer-events` on the disabled element.
 <!-- disabled-trigger-element.vue -->
 ```
 
+### Caveats with `focus` trigger on `<button>` elements
+
+For proper cross-browser and cross-platform behavior when using only the `focus` trigger, you must
+use an element that renders the `<a>` tag, not the `<button>` tag, and you also must include a
+`tabindex="0"` attribute.
+
+The following will generate an `<a>` that looks like a button:
+
+```html
+<b-button
+  href="#"
+  tabindex="0"
+  v-b-tooltip.focus
+  title="Tooltip title"
+>
+  Link button with tooltip directive
+</b-button>
+```
+
 ### Dismiss on next click
 
 Use both `click` and `blur` if you would like a tooltip that opens only on click of the element, but
