Merge branch 'v4-dev' into form-tweaks

2026-05-30 15:24:08 +03:00 · 2017-05-26 21:22:08 -07:00
parent e0e1e849e6 f2829dd6ea
commit 04724939a3
94 changed files with 3824 additions and 1675 deletions
@@ -12,6 +12,13 @@ Dropdowns are toggleable, contextual overlays for displaying lists of links and
 * Will be replaced with the ToC, excluding the "Contents" header
 {:toc}

+## Overview
+
+Things to know when using the popover plugin:
+
+- Dropdown rely on the 3rd party library [Popper.js](https://popper.js.org) for positioning. You must include [popper.min.js](https://cdnjs.cloudflare.com/ajax/libs/popper.js/1.9.9/umd/popper.min.js) before bootstrap.js in order for dropdowns to work!
+- Popper.js handle natively the flip of Dropdown when it's outside the viewport, if you want to disable that's behavior use `flip` attribute
+
 ## Examples

 Wrap the dropdown's toggle (your button or link) and the dropdown menu within `.dropdown`, or another element that declares `position: relative;`. Dropdowns can be triggered from `<a>` or `<button>` elements to better fit your potential needs.
@@ -19,7 +26,7 @@ Wrap the dropdown's toggle (your button or link) and the dropdown menu within `.
 {% callout info %}
 ### Dropdown menu accessibility

-The [<abbr title="Web Accessibility Initiative">WAI</abbr> <abbr title="Accessible Rich Internet Applications">ARIA</abbr>](https://www.w3.org/TR/wai-aria/) standard defines an actual [`role="menu"` widget](https://www.w3.org/TR/wai-aria/roles#menu), but this is specific to application-like menus which trigger actions or functions. <abbr title="Accessible Rich Internet Applications">ARIA</abbr> menus can only contain menu items, checkbox menu items, radio button menu items, radio button groups, and sub-menus. 
+The [<abbr title="Web Accessibility Initiative">WAI</abbr> <abbr title="Accessible Rich Internet Applications">ARIA</abbr>](https://www.w3.org/TR/wai-aria/) standard defines an actual [`role="menu"` widget](https://www.w3.org/TR/wai-aria/roles#menu), but this is specific to application-like menus which trigger actions or functions. <abbr title="Accessible Rich Internet Applications">ARIA</abbr> menus can only contain menu items, checkbox menu items, radio button menu items, radio button groups, and sub-menus.

 Bootstrap's dropdowns, on the other hand, are designed to be generic and applicable to a variety of situations and markup structures. For instance, it is possible to create dropdowns that contain additional inputs and form controls, such as search fields or login forms. For this reason, Bootstrap does not expect (nor automatically add) any of the `role` and `aria-` attributes required for true <abbr title="Accessible Rich Internet Applications">ARIA</abbr> menus. Authors will have to include these more specific attributes themselves.

@@ -527,13 +534,47 @@ Regardless of whether you call your dropdown via JavaScript or instead use the d

 ### Options

-*None.*
+Options can be passed via data attributes or JavaScript. For data attributes, append the option name to `data-`, as in `data-placement=""`.
+
+<table class="table table-bordered table-striped table-responsive">
+  <thead>
+    <tr>
+      <th style="width: 100px;">Name</th>
+      <th style="width: 100px;">Type</th>
+      <th style="width: 50px;">Default</th>
+      <th>Description</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td>placement</td>
+      <td>string</td>
+      <td>'bottom'</td>
+      <td>
+        <p>How to position the popover - top | bottom.</p>
+      </td>
+    </tr>
+    <tr>
+      <td>offset</td>
+      <td>number | string</td>
+      <td>0</td>
+      <td>Offset of the dropdown relative to its target. For more information refer to Popper.js's <a href="https://popper.js.org/popper-documentation.html#modifiers..offset.offset">offset docs</a>.</td>
+    </tr>
+    <tr>
+      <td>flip</td>
+      <td>boolean</td>
+      <td>true</td>
+      <td>Allow Dropdown to flip in case of an overlapping on the reference element. For more information refer to Popper.js's <a href="https://popper.js.org/popper-documentation.html#modifiers..flip.enabled">flip docs</a>.</td>
+    </tr>
+  </tbody>
+</table>

 ### Methods

 | Method | Description |
 | --- | --- |
 | `$().dropdown('toggle')` | Toggles the dropdown menu of a given navbar or tabbed navigation. |
+| `$().dropdown('update')` | Updates the position of an element's dropdown. |

 ### Events

@@ -17,7 +17,7 @@ Add small overlay content, like those found in iOS, to any element for housing s
 Things to know when using the popover plugin:


- Popovers rely on the 3rd party library [Tether](http://tether.io/) for positioning. You must include [tether.min.js](https://github.com/HubSpot/tether/blob/master/dist/js/tether.min.js) before bootstrap.js in order for popovers to work!
+- Popovers rely on the 3rd party library [Popper.js](https://popper.js.org) for positioning. You must include [popper.min.js](https://cdnjs.cloudflare.com/ajax/libs/popper.js/1.9.9/umd/popper.min.js) before bootstrap.js in order for popovers to work!
 - Popovers require the [tooltip plugin]({{ site.baseurl }}/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.
@@ -25,6 +25,7 @@ Things to know when using the popover plugin:
 - Triggering popovers on hidden elements will not work.
 - Popovers for `.disabled` or `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 to avoid this behavior.
+- Popovers must be hidden before their corresponding elements have been removed from the DOM.

 Got all that? Great, let's see how they work with some examples.

@@ -55,29 +56,32 @@ $(function () {
 Four options are available: top, right, bottom, and left aligned.

 <div class="bd-example bd-example-popover-static">
-  <div class="popover popover-top">
+  <div class="popover bs-popover-top bs-popover-top-docs">
+    <div class="arrow" x-arrow></div>
    <h3 class="popover-title">Popover top</h3>
    <div class="popover-content">
      <p>Sed posuere consectetur est at lobortis. Aenean eu leo quam. Pellentesque ornare sem lacinia quam venenatis vestibulum.</p>
    </div>
  </div>

-  <div class="popover popover-right">
+  <div class="popover bs-popover-right bs-popover-right-docs">
+    <div class="arrow" x-arrow></div>
    <h3 class="popover-title">Popover right</h3>
    <div class="popover-content">
      <p>Sed posuere consectetur est at lobortis. Aenean eu leo quam. Pellentesque ornare sem lacinia quam venenatis vestibulum.</p>
    </div>
  </div>

-  <div class="popover popover-bottom">
+  <div class="popover bs-popover-bottom bs-popover-bottom-docs">
+    <div class="arrow" x-arrow></div>
    <h3 class="popover-title">Popover bottom</h3>
-
    <div class="popover-content">
      <p>Sed posuere consectetur est at lobortis. Aenean eu leo quam. Pellentesque ornare sem lacinia quam venenatis vestibulum.</p>
    </div>
  </div>

-  <div class="popover popover-left">
+  <div class="popover bs-popover-left bs-popover-left-docs">
+    <div class="arrow" x-arrow></div>
    <h3 class="popover-title">Popover left</h3>
    <div class="popover-content">
      <p>Sed posuere consectetur est at lobortis. Aenean eu leo quam. Pellentesque ornare sem lacinia quam venenatis vestibulum.</p>
@@ -217,7 +221,7 @@ Options can be passed via data attributes or JavaScript. For data attributes, ap
      <td>string | function</td>
      <td>'right'</td>
      <td>
-        <p>How to position the popover - top | bottom | left | right.</p>
+        <p>How to position the popover - auto | top | bottom | left | right.<br>When <code>auto</code> is specified, it will dynamically reorient the popover.</p>
        <p>When a function is used to determine the placement, it is called with the popover DOM node as its first argument and the triggering element DOM node as its second. The <code>this</code> context is set to the popover instance.</p>
      </td>
    </tr>
@@ -230,12 +234,12 @@ Options can be passed via data attributes or JavaScript. For data attributes, ap
    <tr>
      <td>template</td>
      <td>string</td>
-      <td><code>'&lt;div class="popover" role="tooltip"&gt;&lt;div class="popover-arrow"&gt;&lt;/div&gt;&lt;h3 class="popover-title"&gt;&lt;/h3&gt;&lt;div class="popover-content"&gt;&lt;/div&gt;&lt;/div&gt;'</code></td>
+      <td><code>'&lt;div class="popover" role="tooltip"&gt;&lt;div class="arrow" x-arrow&gt;&lt;/div&gt;&lt;h3 class="popover-title"&gt;&lt;/h3&gt;&lt;div class="popover-content"&gt;&lt;/div&gt;&lt;/div&gt;'</code></td>
      <td>
        <p>Base HTML to use when creating the popover.</p>
        <p>The popover's <code>title</code> will be injected into the <code>.popover-title</code>.</p>
        <p>The popover's <code>content</code> will be injected into the <code>.popover-content</code>.</p>
-        <p><code>.popover-arrow</code> will become the popover's arrow.</p>
+        <p><code>.arrow</code> will become the popover's arrow.</p>
        <p>The outermost wrapper element should have the <code>.popover</code> class.</p>
      </td>
    </tr>
@@ -255,16 +259,17 @@ Options can be passed via data attributes or JavaScript. For data attributes, ap
      <td>How popover is triggered - click | hover | focus | manual. You may pass multiple triggers; separate them with a space. `manual` cannot be combined with any other trigger.</td>
    </tr>
    <tr>
-      <td>constraints</td>
-      <td>Array</td>
-      <td>'hover focus'</td>
-      <td>An array of constraints - passed through to Tether. For more information refer to Tether's <a href="http://tether.io/#constraints">constraint docs</a>.</td>
+      <td>offset</td>
+      <td>number | string</td>
+      <td>0</td>
+      <td>Offset of the popover relative to its target. For more information refer to Popper.js's <a href="https://popper.js.org/popper-documentation.html#modifiers..offset.offset">offset docs</a>.</td>
    </tr>
    <tr>
-      <td>offset</td>
-      <td>string</td>
-      <td>'0 0'</td>
-      <td>Offset of the popover relative to its target. For more information refer to Tether's <a href="http://tether.io/#offset">offset docs</a>.</td>
+      <td>fallbackPlacement</td>
+      <td>string | array</td>
+      <td>'flip'</td>
+      <td>Allow to specify which position Popper will use on fallback. For more information refer to
+      Popper.js's <a href="https://popper.js.org/popper-documentation.html#modifiers..flip.behavior">behavior docs</a></td>
    </tr>
  </tbody>
 </table>
@@ -327,6 +332,12 @@ Toggles the ability for an element's popover to be shown or hidden.

 {% highlight js %}$('#element').popover('toggleEnabled'){% endhighlight %}

+#### `.popover('update')`
+
+Updates the position of an element's popover.
+
+{% highlight js %}$('#element').popover('update'){% endhighlight %}
+
 ### Events

 <table class="table table-bordered table-striped table-responsive">
@@ -16,13 +16,14 @@ Inspired by the excellent Tipsy jQuery plugin written by Jason Frame. Tooltips a

 Things to know when using the tooltip plugin:

- Tooltips rely on the 3rd party library [Tether](http://tether.io/) for positioning. You must include [tether.min.js](https://github.com/HubSpot/tether/blob/master/dist/js/tether.min.js) before bootstrap.js in order for tooltips to work!
+- Tooltips rely on the 3rd party library [Popper.js](https://popper.js.org) for positioning. You must include [popper.min.js](https://cdnjs.cloudflare.com/ajax/libs/popper.js/1.9.9/umd/popper.min.js) before bootstrap.js in order for tooltips to work!
 - Tooltips are opt-in for performance reasons, so **you must initialize them yourself**.
 - Tooltips with zero-length titles are never displayed.
 - Specify `container: 'body'` to avoid rendering problems in more complex components (like our input groups, button groups, etc).
 - Triggering tooltips on hidden elements will not work.
 - Tooltips for `.disabled` or `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 to avoid this behavior.
+- Tooltips must be hidden before their corresponding elements have been removed from the DOM.

 Got all that? Great, let's see how they work with some examples.

@@ -50,22 +51,26 @@ Hover over the links below to see tooltips:
 Four options are available: top, right, bottom, and left aligned.

 <div class="bd-example bd-example-tooltip-static">
-  <div class="tooltip tooltip-top" role="tooltip">
+  <div class="tooltip bs-tooltip-top bs-tooltip-top-docs" role="tooltip">
+    <div class="arrow" x-arrow></div>
    <div class="tooltip-inner">
      Tooltip on the top
    </div>
  </div>
-  <div class="tooltip tooltip-right" role="tooltip">
+  <div class="tooltip bs-tooltip-right bs-tooltip-right-docs" role="tooltip">
+    <div class="arrow" x-arrow></div>
    <div class="tooltip-inner">
      Tooltip on the right
    </div>
  </div>
-  <div class="tooltip tooltip-bottom" role="tooltip">
+  <div class="tooltip bs-tooltip-bottom bs-tooltip-bottom-docs" role="tooltip">
+    <div class="arrow" x-arrow></div>
    <div class="tooltip-inner">
      Tooltip on the bottom
    </div>
  </div>
-  <div class="tooltip tooltip-left" role="tooltip">
+  <div class="tooltip bs-tooltip-left bs-tooltip-left-docs" role="tooltip">
+    <div class="arrow" x-arrow></div>
    <div class="tooltip-inner">
      Tooltip on the left
    </div>
@@ -134,8 +139,8 @@ You should only add tooltips to HTML elements that are traditionally keyboard-fo
 <a href="#" data-toggle="tooltip" title="Some tooltip text!">Hover over me</a>

 <!-- Generated markup by the plugin -->
-<div class="tooltip tooltip-top" role="tooltip">
-  <div class="tooltip-arrow"></div>
+<div class="tooltip bs-tooltip-top" role="tooltip">
+  <div class="arrow" x-arrow></div>
  <div class="tooltip-inner">
    Some tooltip text!
  </div>
@@ -195,7 +200,7 @@ Options can be passed via data attributes or JavaScript. For data attributes, ap
      <td>string | function</td>
      <td>'top'</td>
      <td>
-        <p>How to position the tooltip - top | bottom | left | right.</p>
+        <p>How to position the tooltip - auto | top | bottom | left | right.<br>When <code>auto</code> is specified, it will dynamically reorient the tooltip.</p>
        <p>When a function is used to determine the placement, it is called with the tooltip DOM node as its first argument and the triggering element DOM node as its second. The <code>this</code> context is set to the tooltip instance.</p>
      </td>
    </tr>
@@ -208,11 +213,11 @@ Options can be passed via data attributes or JavaScript. For data attributes, ap
    <tr>
      <td>template</td>
      <td>string</td>
-      <td><code>'&lt;div class="tooltip" role="tooltip"&gt;&lt;div class="tooltip-arrow"&gt;&lt;/div&gt;&lt;div class="tooltip-inner"&gt;&lt;/div&gt;&lt;/div&gt;'</code></td>
+      <td><code>'&lt;div class="tooltip" role="tooltip"&gt;&lt;div class="arrow" x-arrow&gt;&lt;/div&gt;&lt;div class="tooltip-inner"&gt;&lt;/div&gt;&lt;/div&gt;'</code></td>
      <td>
        <p>Base HTML to use when creating the tooltip.</p>
        <p>The tooltip's <code>title</code> will be injected into the <code>.tooltip-inner</code>.</p>
-        <p><code>.tooltip-arrow</code> will become the tooltip's arrow.</p>
+        <p><code>.arrow</code> will become the tooltip's arrow.</p>
        <p>The outermost wrapper element should have the <code>.tooltip</code> class.</p>
      </td>
    </tr>
@@ -232,16 +237,17 @@ Options can be passed via data attributes or JavaScript. For data attributes, ap
      <td>How tooltip is triggered - click | hover | focus | manual. You may pass multiple triggers; separate them with a space. `manual` cannot be combined with any other trigger.</td>
    </tr>
    <tr>
-      <td>constraints</td>
-      <td>Array</td>
-      <td>[]</td>
-      <td>An array of constraints - passed through to Tether. For more information refer to Tether's <a href="http://tether.io/#constraints">constraint docs</a>.</td>
+      <td>offset</td>
+      <td>number | string</td>
+      <td>0</td>
+      <td>Offset of the tooltip relative to its target. For more information refer to Popper.js's <a href="https://popper.js.org/popper-documentation.html#modifiers..offset.offset">offset docs</a>.</td>
    </tr>
    <tr>
-      <td>offset</td>
-      <td>string</td>
-      <td>'0 0'</td>
-      <td>Offset of the tooltip relative to its target. For more information refer to Tether's <a href="http://tether.io/#offset">offset docs</a>.</td>
+      <td>fallbackPlacement</td>
+      <td>string | array</td>
+      <td>'flip'</td>
+      <td>Allow to specify which position Popper will use on fallback. For more information refer to
+      Popper.js's <a href="https://popper.js.org/popper-documentation.html#modifiers..flip.behavior">behavior docs</a></td>
    </tr>
  </tbody>
 </table>
@@ -303,6 +309,12 @@ Toggles the ability for an element's tooltip to be shown or hidden.

 {% highlight js %}$('#element').tooltip('toggleEnabled'){% endhighlight %}

+#### `.tooltip('update')`
+
+Updates the position of an element's tooltip.
+
+{% highlight js %}$('#element').tooltip('update'){% endhighlight %}
+
 ### Events

 <table class="table table-bordered table-striped table-responsive">