Merge branch 'v4-dev' into v4-docs-streamlined

11 files changed, 169 insertions, 91 deletions

diff --git a/docs/utilities/colors.md b/docs/utilities/colors.md
index f041f6947..b114d74fe 100644
--- a/docs/utilities/colors.md
+++ b/docs/utilities/colors.md
@@ -13,6 +13,7 @@ Convey meaning through color with a handful of emphasis utility classes. These m
 <p class="text-info">Maecenas sed diam eget risus varius blandit sit amet non magna.</p>
 <p class="text-warning">Etiam porta sem malesuada magna mollis euismod.</p>
 <p class="text-danger">Donec ullamcorper nulla non metus auctor fringilla.</p>
+<p class="text-gray-dark">Eget risus varius blandit sit ultricies vehicula amet non magna.</p>
 <p class="text-white">Etiam porta sem malesuada ultricies vehicula.</p>
 {% endexample %}
 
diff --git a/docs/utilities/display-property.md b/docs/utilities/display-property.md
deleted file mode 100644
index 50ea29367..000000000
--- a/docs/utilities/display-property.md
+++ /dev/null
@@ -1,29 +0,0 @@
----
-layout: docs
-title: Display property
-group: utilities
----
-
-Use `.d-block`, `.d-inline`, or `.d-inline-block` to simply set an element's [`display` property](https://developer.mozilla.org/en-US/docs/Web/CSS/display) to `block`, `inline`, or `inline-block` (respectively).
-
-To make an element `display: none`, use our [responsive utilities]({{ site.baseurl }}/layout/responsive-utilities/) instead.
-
-{% example html %}
-<div class="d-inline bg-success">Inline</div>
-<div class="d-inline bg-success">Inline</div>
-{% endexample %}
-
-{% example html %}
-<span class="d-block bg-primary">Block</span>
-{% endexample %}
-
-{% example html %}
-<div class="d-inline-block bg-warning">
-  <h3>inline-block</h3>
-  Boot that strap!
-</div>
-<div class="d-inline-block bg-warning">
-  <h3>inline-block</h3>
-  Strap that boot!
-</div>
-{% endexample %}
diff --git a/docs/utilities/display.md b/docs/utilities/display.md
new file mode 100644
index 000000000..27f70e0b2
--- /dev/null
+++ b/docs/utilities/display.md
@@ -0,0 +1,64 @@
+---
+layout: docs
+title: Display property
+group: utilities
+---
+
+Quickly and responsively toggle the `display` value of components and more with our display utilities. Includes support for some of the more common values, as well as some extras for controlling `display` when printing.
+
+## Contents
+
+* Will be replaced with the ToC, excluding the "Contents" header
+{:toc}
+
+## Common `display` values
+
+The [`display` property](https://developer.mozilla.org/en-US/docs/Web/CSS/display) accepts a handful of values and we support many of them with utility classes. We purposefully don't provide every value as a utility, so here's what we support:
+
+- `.d-none`
+- `.d-inline`
+- `.d-inline-block`
+- `.d-block`
+- `.d-table`
+- `.d-table-cell`
+- `.d-flex`
+- `.d-inline-flex`
+
+Put them to use by applying any of the classes to an element of your choice. For example, here's how you could use the inline, block, or inline-block utilities (the same applies to the other classes).
+
+{% example html %}
+<div class="d-inline bg-success">d-inline</div>
+<div class="d-inline bg-success">d-inline</div>
+{% endexample %}
+
+{% example html %}
+<span class="d-block bg-primary">d-block</span>
+{% endexample %}
+
+{% example html %}
+<div class="d-inline-block bg-warning">d-inline-block</div>
+<div class="d-inline-block bg-warning">d-inline-block</div>
+{% endexample %}
+
+Responsive variations also exist for every single utility mentioned above.
+
+{% for bp in site.data.breakpoints %}
+- `.d{{ bp.abbr }}-none`
+- `.d{{ bp.abbr }}-inline`
+- `.d{{ bp.abbr }}-inline-block`
+- `.d{{ bp.abbr }}-block`
+- `.d{{ bp.abbr }}-table`
+- `.d{{ bp.abbr }}-table-cell`
+- `.d{{ bp.abbr }}-flex`
+- `.d{{ bp.abbr }}-inline-flex`{% endfor %}
+
+## Display in print
+
+Change the `display` value of elements when printing with our print display utilities.
+
+| Class | Print style |
+| --- | --- |
+| `.d-print-block` | Applies `display: block` to the element when printing |
+| `.d-print-inline` | Applies `display: inline` to the element when printing |
+| `.d-print-inline-block` | Applies `display: inline-block` to the element when printing |
+| `.d-print-none` | Applies `display: none` to the element when printing |
diff --git a/docs/utilities/flexbox.md b/docs/utilities/flexbox.md
index 9b6add5c4..9bca02848 100644
--- a/docs/utilities/flexbox.md
+++ b/docs/utilities/flexbox.md
@@ -354,9 +354,9 @@ Change the _visual_ order of specific flex items with a handful of `order` utili
 
 {% example html %}
 <div class="d-flex flex-nowrap bd-highlight">
-  <div class="flex-last p-2 bd-highlight">First flex item</div>
+  <div class="order-last p-2 bd-highlight">First flex item</div>
   <div class="p-2 bd-highlight">Second flex item</div>
-  <div class="flex-first p-2 bd-highlight">Third flex item</div>
+  <div class="order-first p-2 bd-highlight">Third flex item</div>
 </div>
 {% endexample %}
 
@@ -365,7 +365,7 @@ Responsive variations also exist for `order`.
 {% for bp in site.data.breakpoints %}
 - `.order{{ bp.abbr }}-first`
 - `.order{{ bp.abbr }}-last`
-- `.order{{ bp.abbr }}-unordered`{% endfor %}
+- `.order{{ bp.abbr }}-0`{% endfor %}
 
 ## Align content
 
diff --git a/docs/utilities/invisible-content.md b/docs/utilities/invisible-content.md
deleted file mode 100644
index 84da6ad01..000000000
--- a/docs/utilities/invisible-content.md
+++ /dev/null
@@ -1,23 +0,0 @@
----
-layout: docs
-title: Invisible content
-group: utilities
----
-
-The `.invisible` class can be used to toggle only the visibility of an element, meaning its `display` is not modified and the element can still affect the flow of the document.
-
-{% highlight html %}
-<div class="invisible">...</div>
-{% endhighlight %}
-
-{% highlight scss %}
-// Class
-.invisible {
-  visibility: hidden;
-}
-
-// Usage as a mixin
-.element {
-  @include invisible;
-}
-{% endhighlight %}
diff --git a/docs/utilities/position.md b/docs/utilities/position.md
new file mode 100644
index 000000000..6b8268c48
--- /dev/null
+++ b/docs/utilities/position.md
@@ -0,0 +1,31 @@
+---
+layout: docs
+title: Position
+group: utilities
+---
+
+Position utilities are helpful for quickly placing a component outside the normal document flow. Choose from a handful of fixed or sticky position classes as needed.
+
+### Fixed top
+
+Position an element at the top of the viewport, from edge to edge. Be sure you understand the ramifications of fixed position in your project; you may need to add aditional CSS.
+
+{% highlight html %}
+<div class="fixed-top">...</div>
+{% endhighlight %}
+
+### Fixed bottom
+
+Position an element at the bottom of the viewport, from edge to edge. Be sure you understand the ramifications of fixed position in your project; you may need to add aditional CSS.
+
+{% highlight html %}
+<div class="fixed-bottom">...</div>
+{% endhighlight %}
+
+### Sticky top
+
+Position an element at the top of the viewport, from edge to edge, but only after you scroll past it. The `.sticky-top` utility uses CSS's `position: sticky`, which isn't fully supported in all browsers.
+
+{% highlight html %}
+<div class="sticky-top">...</div>
+{% endhighlight %}
diff --git a/docs/utilities/responsive-helpers.md b/docs/utilities/responsive-helpers.md
index 35e7fcf2f..0f1a43ee1 100644
--- a/docs/utilities/responsive-helpers.md
+++ b/docs/utilities/responsive-helpers.md
@@ -14,7 +14,7 @@ Rules are directly applied to `<iframe>`, `<embed>`, `<video>`, and `<object>` e
 
 {% example html %}
 <div class="embed-responsive embed-responsive-16by9">
-  <iframe class="embed-responsive-item" src="//www.youtube.com/embed/zpOULjyy-n8?rel=0" allowfullscreen></iframe>
+  <iframe class="embed-responsive-item" src="https://www.youtube.com/embed/zpOULjyy-n8?rel=0" allowfullscreen></iframe>
 </div>
 {% endexample %}
 
diff --git a/docs/utilities/sizing-and-positioning.md b/docs/utilities/sizing.md
index a6de778ca..eabb4653a 100644
--- a/docs/utilities/sizing-and-positioning.md
+++ b/docs/utilities/sizing.md
@@ -1,27 +1,12 @@
 ---
 layout: docs
-title: Sizing and positioning
+title: Sizing
 group: utilities
 ---
 
-## Fixed positioning
+Easily make an element as wide or as tall (relative to its parent) with our width and height utilities. Includes support for `25%`, `50%`, `75%`, and `100%` by default.
 
-The `.pos-f-t` class can be used to easily position elements at the top of the viewport and make them as wide as the viewport. **Be sure you understand the ramifications of fixed-position elements within your project.** Here's how the class is defined:
-
-{% highlight scss %}
-.pos-f-t {
-  position: fixed;
-  top: 0;
-  right: 0;
-  left: 0;
-  z-index: $zindex-navbar-fixed;
-}
-{% endhighlight %}
-
-
-## Width and height
-
-Easily make an element as wide or as tall (relative to its parent) with our width and height utilities. Includes support for `25%`, `50%`, `75%`, and `100%`.
+Width and height utilities are generated from the `$sizes` Sass map in `_variables.scss`. Modify those values as you need to generate different utilities here.
 
 {% example html %}
 <div class="w-25 p-3" style="background-color: #eee;">Width 25%</div>
diff --git a/docs/utilities/spacing.md b/docs/utilities/spacing.md
index 0a5132941..fa8a0d76c 100644
--- a/docs/utilities/spacing.md
+++ b/docs/utilities/spacing.md
@@ -35,11 +35,11 @@ Where *sides* is one of:
 Where *size* is one of:
 
 * `0` - for classes that eliminate the `margin` or `padding` by setting it to `0`
-* `1` - (by default) for classes that set the `margin` or `padding` to `$spacer-x * .25` or `$spacer-y * .25`
-* `2` - (by default) for classes that set the `margin` or `padding` to `$spacer-x * .5` or `$spacer-y * .5`
-* `3` - (by default) for classes that set the `margin` or `padding` to `$spacer-x` or `$spacer-y`
-* `4` - (by default) for classes that set the `margin` or `padding` to `$spacer-x * 1.5` or `$spacer-y * 1.5`
-* `5` - (by default) for classes that set the `margin` or `padding` to `$spacer-x * 3` or `$spacer-y * 3`
+* `1` - (by default) for classes that set the `margin` or `padding` to `$spacer * .25`
+* `2` - (by default) for classes that set the `margin` or `padding` to `$spacer * .5`
+* `3` - (by default) for classes that set the `margin` or `padding` to `$spacer`
+* `4` - (by default) for classes that set the `margin` or `padding` to `$spacer * 1.5`
+* `5` - (by default) for classes that set the `margin` or `padding` to `$spacer * 3`
 
 (You can add more sizes by adding entries to the `$spacers` Sass map variable.)
 
@@ -53,16 +53,16 @@ Here are some representative examples of these classes:
 }
 
 .ml-1 {
-  margin-left: ($spacer-x * .25) !important;
+  margin-left: ($spacer * .25) !important;
 }
 
 .px-2 {
-  padding-left: ($spacer-x * .5) !important;
-  padding-right: ($spacer-x * .5) !important;
+  padding-left: ($spacer * .5) !important;
+  padding-right: ($spacer * .5) !important;
 }
 
 .p-3 {
-  padding: $spacer-y $spacer-x !important;
+  padding: $spacer !important;
 }
 {% endhighlight %}
 
diff --git a/docs/utilities/typography.md b/docs/utilities/typography.md
index 42b61131e..5e29fd88c 100644
--- a/docs/utilities/typography.md
+++ b/docs/utilities/typography.md
@@ -19,14 +19,6 @@ Easily realign text to components with text alignment classes.
 <p class="text-justify">Ambitioni dedisse scripsisse iudicaretur. Cras mattis iudicium purus sit amet fermentum. Donec sed odio operae, eu vulputate felis rhoncus. Praeterea iter est quasdam res quas ex communi. At nos hinc posthac, sitientis piros Afros. Petierunt uti sibi concilium totius Galliae in diem certam indicere. Cras mattis iudicium purus sit amet fermentum.</p>
 {% endexample %}
 
-{% example html %}
-<div class="card">
-  <div class="card-block text-nowrap">
-    Curabitur blandit tempus ardua ridiculus sed magna.
-  </div>
-</div>
-{% endexample %}
-
 For left, right, and center alignment, responsive classes are available that use the same viewport width breakpoints as the grid system.
 
 {% example html %}
@@ -40,6 +32,31 @@ For left, right, and center alignment, responsive classes are available that use
 <p class="text-xl-left">Left aligned text on viewports sized XL (extra-large) or wider.</p>
 {% endexample %}
 
+## Text wrapping and overflow
+
+Prevent text from wrapping with a `.text-nowrap` class.
+
+{% example html %}
+<div class="row">
+  <div class="col-1 text-nowrap">
+    Curabitur blandit tempus ardua ridiculus sed magna.
+  </div>
+  <div class="col-11">
+    <img data-src="holder.js/50x50" alt="An image to show the text doesn't wrap">
+  </div>
+</div>
+{% endexample %}
+
+For longer content, you can add a `.text-truncate` class to truncate the text with an ellipsis.
+
+{% example html %}
+<div class="row">
+  <div class="col-2 text-truncate">
+    Praeterea iter est quasdam res quas ex communi.
+  </div>
+</div>
+{% endexample %}
+
 ## Text transform
 
 Transform text in components with text capitalization classes.
diff --git a/docs/utilities/visibility.md b/docs/utilities/visibility.md
new file mode 100644
index 000000000..5b7d28664
--- /dev/null
+++ b/docs/utilities/visibility.md
@@ -0,0 +1,32 @@
+---
+layout: docs
+title: Visibility
+group: utilities
+---
+
+Set the `visibility` of elements with our visibility utilities. These do not modify the `display` value at all and are helpful for hiding content from most users, but still keeping them for screen readers.
+
+Apply `.visible` or `.invisible` as needed.
+
+{% highlight html %}
+<div class="visible">...</div>
+<div class="invisible">...</div>
+{% endhighlight %}
+
+{% highlight scss %}
+// Class
+.visible {
+  visibility: visible;
+}
+.invisible {
+  visibility: hidden;
+}
+
+// Usage as a mixin
+.element {
+  @include invisible(visible);
+}
+.element {
+  @include invisible(hidden);
+}
+{% endhighlight %}