From 4b84614e7f6fe565afeae516ebbd2dba891b8030 Mon Sep 17 00:00:00 2001
From: Mark Otto <markdotto@gmail.com>
Date: Sat, 1 Jul 2017 19:48:06 -0700
Subject: [PATCH] Redo the "responsive helpers" files

- Moves the embed SCSS to the utilities subfolder
- Separate the floats from the embed docs
- Rename embed docs from responsive helpers to embeds
---
 _data/nav.yml                                 |  3 +-
 .../{responsive-helpers.md => embed.md}       | 37 +++----------
 docs/4.0/utilities/float.md                   | 55 +++++++++++++++++++
 scss/_utilities.scss                          |  1 +
 scss/bootstrap.scss                           |  1 -
 .../_embed.scss}                              |  0
 6 files changed, 66 insertions(+), 31 deletions(-)
 rename docs/4.0/utilities/{responsive-helpers.md => embed.md} (53%)
 create mode 100644 docs/4.0/utilities/float.md
 rename scss/{_responsive-embed.scss => utilities/_embed.scss} (100%)

diff --git a/_data/nav.yml b/_data/nav.yml
index a6d4a6bdce..1ce74e7823 100644
--- a/_data/nav.yml
+++ b/_data/nav.yml
@@ -58,10 +58,11 @@
     - title: Close icon
     - title: Colors
     - title: Display
+    - title: Embed
     - title: Flex
+    - title: Float
     - title: Image replacement
     - title: Position
-    - title: Responsive helpers
     - title: Screenreaders
     - title: Sizing
     - title: Spacing
diff --git a/docs/4.0/utilities/responsive-helpers.md b/docs/4.0/utilities/embed.md
similarity index 53%
rename from docs/4.0/utilities/responsive-helpers.md
rename to docs/4.0/utilities/embed.md
index ae65eff6b4..4f19874ffa 100644
--- a/docs/4.0/utilities/responsive-helpers.md
+++ b/docs/4.0/utilities/embed.md
@@ -1,23 +1,29 @@
 ---
 layout: docs
-title: Responsive helpers
+title: Embeds
 description: Create responsive video or slideshow embeds based on the width of the parent by creating an intrinsic ratio that scales on any device.
 group: utilities
 toc: true
 ---
 
-## Responsive embeds
+## About
 
 Rules are directly applied to `<iframe>`, `<embed>`, `<video>`, and `<object>` elements; optionally use an explicit descendant class `.embed-responsive-item` when you want to match the styling for other attributes.
 
 **Pro-Tip!** You don't need to include `frameborder="0"` in your `<iframe>`s as we override that for you.
 
+## Example
+
+Wrap any embed like an `<iframe>` in a parent element with `.embed-responsive` and an aspect ratio. The `.embed-responsive-item` isn't strictly required, but we encourage it.
+
 {% example html %}
 <div class="embed-responsive embed-responsive-16by9">
   <iframe class="embed-responsive-item" src="https://www.youtube.com/embed/zpOULjyy-n8?rel=0" allowfullscreen></iframe>
 </div>
 {% endexample %}
 
+## Aspect ratios
+
 Aspect ratios can be customized with modifier classes.
 
 {% highlight html %}
@@ -41,30 +47,3 @@ Aspect ratios can be customized with modifier classes.
   <iframe class="embed-responsive-item" src="..."></iframe>
 </div>
 {% endhighlight %}
-
-## Responsive floats
-
-These utility classes float an element to the left or right, or disable floating, based on the current viewport size using the [CSS `float` property](https://developer.mozilla.org/en-US/docs/Web/CSS/float). `!important` is included to avoid specificity issues. These use the same viewport width breakpoints as the grid system.
-
-Two similar non-responsive Sass mixins (`float-left` and `float-right`) are also available.
-
-{% example html %}
-<div class="float-left">Float left on all viewport sizes</div><br>
-<div class="float-right">Float right on all viewport sizes</div><br>
-<div class="float-none">Don't float on all viewport sizes</div><br>
-
-<div class="float-sm-left">Float left on viewports sized SM (small) or wider</div><br>
-<div class="float-md-left">Float left on viewports sized MD (medium) or wider</div><br>
-<div class="float-lg-left">Float left on viewports sized LG (large) or wider</div><br>
-<div class="float-xl-left">Float left on viewports sized XL (extra-large) or wider</div><br>
-{% endexample %}
-
-{% highlight scss %}
-// Related simple non-responsive mixins
-.element {
-  @include float-left;
-}
-.another-element {
-  @include float-right;
-}
-{% endhighlight %}
diff --git a/docs/4.0/utilities/float.md b/docs/4.0/utilities/float.md
new file mode 100644
index 0000000000..18c6b39511
--- /dev/null
+++ b/docs/4.0/utilities/float.md
@@ -0,0 +1,55 @@
+---
+layout: docs
+title: Float
+description: Toggle floats on any element, across any breakpoint, using our responsive float utilities.
+group: utilities
+toc: true
+---
+
+## Overview
+
+These utility classes float an element to the left or right, or disable floating, based on the current viewport size using the [CSS `float` property](https://developer.mozilla.org/en-US/docs/Web/CSS/float). `!important` is included to avoid specificity issues. These use the same viewport breakpoints as our grid system.
+
+## Classes
+
+Toggle a float with a class:
+
+{% example html %}
+<div class="float-left">Float left on all viewport sizes</div><br>
+<div class="float-right">Float right on all viewport sizes</div><br>
+<div class="float-none">Don't float on all viewport sizes</div>
+{% endexample %}
+
+## Mixins
+
+Or by Sass mixin:
+
+{% highlight scss %}
+.element {
+  @include float-left;
+}
+.another-element {
+  @include float-right;
+}
+.one-more {
+  @include float-none;
+}
+{% endhighlight %}
+
+## Responsive
+
+Responsive variations also exist for each `float` value.
+
+{% example html %}
+<div class="float-sm-left">Float left on viewports sized SM (small) or wider</div><br>
+<div class="float-md-left">Float left on viewports sized MD (medium) or wider</div><br>
+<div class="float-lg-left">Float left on viewports sized LG (large) or wider</div><br>
+<div class="float-xl-left">Float left on viewports sized XL (extra-large) or wider</div><br>
+{% endexample %}
+
+Here are all the support classes;
+
+{% for bp in site.data.breakpoints %}
+- `.float{{ bp.abbr }}-left`
+- `.float{{ bp.abbr }}-right`
+- `.float{{ bp.abbr }}-none`{% endfor %}
diff --git a/scss/_utilities.scss b/scss/_utilities.scss
index 7d08ff2f8c..7b2a1ebe9d 100644
--- a/scss/_utilities.scss
+++ b/scss/_utilities.scss
@@ -3,6 +3,7 @@
 @import "utilities/borders";
 @import "utilities/clearfix";
 @import "utilities/display";
+@import "utilities/embed";
 @import "utilities/flex";
 @import "utilities/float";
 @import "utilities/position";
diff --git a/scss/bootstrap.scss b/scss/bootstrap.scss
index 131d9b63df..3bc8001fa4 100644
--- a/scss/bootstrap.scss
+++ b/scss/bootstrap.scss
@@ -33,7 +33,6 @@
 @import "progress";
 @import "media";
 @import "list-group";
-@import "responsive-embed";
 @import "close";
 @import "modal";
 @import "tooltip";
diff --git a/scss/_responsive-embed.scss b/scss/utilities/_embed.scss
similarity index 100%
rename from scss/_responsive-embed.scss
rename to scss/utilities/_embed.scss