Merge pull request #19099 from twbs/v4-grid-redux

v4: Grid redux

2 files changed, 275 insertions, 36 deletions

diff --git a/docs/layout/flexbox-grid.md b/docs/layout/flexbox-grid.md
new file mode 100644
index 000000000..6d372a96c
--- /dev/null
+++ b/docs/layout/flexbox-grid.md
@@ -0,0 +1,212 @@
+---
+layout: docs
+title: Flexbox grid system
+group: layout
+---
+
+Fancy a more modern grid system? [Enable flexbox support in Bootstrap](/getting-started/flexbox) to take full advantage of CSS's Flexible Box module for even more control over your site's layout, alignment, and distribution of content.
+
+Bootstrap's flexbox grid includes support for every feature from our [default grid system](/layout/grid), and then some. Please read the [default grid system docs](/layout/grid) before proceeding through this page. Features that are covered there are only summarized here. Please note that **Internet Explorer 9 does not support flexbox**, so proceed with caution when enabling it.
+
+{% callout warning %}
+**Heads up!** The flexbox grid documentation is only functional when flexbox support is explicitly enabled.
+{% endcallout %}
+
+## Contents
+
+* Will be replaced with the ToC, excluding the "Contents" header
+{:toc}
+
+## How it works
+
+The flexbox grid system behaves similar to our default grid system, but with a few notable differences:
+
+- [Grid mixins](/layout/grid#sass-mixins) and [predefined classes](/layout/grid#predefined-classes) include support for flexbox. Just [enable flexbox support](/getting-started/flexbox) to utilize them as you would otherwise.
+- Nesting, offsets, pushes, and pulls are all supported in the flexbox grid system.
+- Flexbox grid columns without a set width will automatically layout with equal widths. For example, four columns will each automatically be 25% wide.
+- Flexbox grid columns have significantly more alignment options available, including vertical alignment.
+- Unlike the default grid system where a grid column starts as full-width in the `xs` tier, flexbox requires a `.col-{breakpoint}` class for each tier.
+
+Chill? Awesome—keep reading for more information and some code snippets.
+
+## Auto-layout columns
+
+When flexbox support is enabled, you can utilize breakpoint-specific column classes for equal-width columns. Add any number of `.col-{breakpoint}`s for each breakpoint you need and you're good to go. For example, here's are two grid layouts that apply to every device and viewport possible.
+
+<div class="bd-example-row">
+{% example html %}
+<div class="container">
+  <div class="row">
+    <div class="col-xs">
+      1 of 2
+    </div>
+    <div class="col-xs">
+      1 of 2
+    </div>
+  </div>
+  <div class="row">
+    <div class="col-xs">
+      1 of 3
+    </div>
+    <div class="col-xs">
+      1 of 3
+    </div>
+    <div class="col-xs">
+      1 of 3
+    </div>
+  </div>
+</div>
+{% endexample %}
+</div>
+
+Auto-layout for flexbox grid columns also means you can set the width of one column and the others will automatically resize around it. You may use predefined grid classes (as shown below), grid mixins, or inline widths.
+
+<div class="bd-example-row">
+{% example html %}
+<div class="container">
+  <div class="row">
+    <div class="col-xs">
+      1 of 3
+    </div>
+    <div class="col-xs-6">
+      2 of 3 (wider)
+    </div>
+    <div class="col-xs">
+      3 of 3
+    </div>
+  </div>
+</div>
+{% endexample %}
+</div>
+
+## Responsive flexbox
+
+Unlike the default grid system, the flexbox grid requires a class for full-width columns. If you have a `.col-sm-6` and don't add `.col-xs-12`, your `xs` grid will not render correctly. Note that flexbox grid tiers still scale up across breakpoints, so if you want two 50% wide columns across `sm`, `md`, and `lg`, you only need to set `.col-sm-6`.
+
+<div class="bd-example-row">
+{% example html %}
+<div class="container">
+  <div class="row">
+    <div class="col-xs-12 col-sm-6">
+      1 of 2 (stacked on mobile)
+    </div>
+    <div class="col-xs-12 col-sm-6">
+      1 of 2 (stacked on mobile)
+    </div>
+  </div>
+</div>
+{% endexample %}
+</div>
+
+## Vertical alignment
+
+Use the flexbox alignment utilities to vertically align columns.
+
+<div class="bd-example-row">
+{% example html %}
+<div class="container">
+  <div class="row flex-items-xs-top">
+    <div class="col-xs">
+      One of three columns
+    </div>
+    <div class="col-xs">
+      One of three columns
+    </div>
+    <div class="col-xs">
+      One of three columns
+    </div>
+  </div>
+  <div class="row flex-items-xs-middle">
+    <div class="col-xs">
+      One of three columns
+    </div>
+    <div class="col-xs">
+      One of three columns
+    </div>
+    <div class="col-xs">
+      One of three columns
+    </div>
+  </div>
+  <div class="row flex-items-xs-bottom">
+    <div class="col-xs">
+      One of three columns
+    </div>
+    <div class="col-xs">
+      One of three columns
+    </div>
+    <div class="col-xs">
+      One of three columns
+    </div>
+  </div>
+</div>
+{% endexample %}
+</div>
+
+<div class="bd-example-row bd-example-row-flex-cols">
+{% example html %}
+<div class="container">
+  <div class="row">
+    <div class="col-xs flex-xs-top">
+      One of three columns
+    </div>
+    <div class="col-xs flex-xs-middle">
+      One of three columns
+    </div>
+    <div class="col-xs flex-xs-bottom">
+      One of three columns
+    </div>
+  </div>
+</div>
+{% endexample %}
+</div>
+
+## Horizontal alignment
+
+Flexbox utilities for horizontal alignment also exist for a number of layout options.
+
+<div class="bd-example-row">
+{% example html %}
+<div class="container">
+  <div class="row flex-items-xs-left">
+    <div class="col-xs-4">
+      One of two columns
+    </div>
+    <div class="col-xs-4">
+      One of two columns
+    </div>
+  </div>
+  <div class="row flex-items-xs-center">
+    <div class="col-xs-4">
+      One of two columns
+    </div>
+    <div class="col-xs-4">
+      One of two columns
+    </div>
+  </div>
+  <div class="row flex-items-xs-right">
+    <div class="col-xs-4">
+      One of two columns
+    </div>
+    <div class="col-xs-4">
+      One of two columns
+    </div>
+  </div>
+  <div class="row flex-items-xs-around">
+    <div class="col-xs-4">
+      One of two columns
+    </div>
+    <div class="col-xs-4">
+      One of two columns
+    </div>
+  </div>
+  <div class="row flex-items-xs-between">
+    <div class="col-xs-4">
+      One of two columns
+    </div>
+    <div class="col-xs-4">
+      One of two columns
+    </div>
+  </div>
+</div>
+{% endexample %}
+</div>
diff --git a/docs/layout/grid.md b/docs/layout/grid.md
index f2427137f..3a76a651b 100644
--- a/docs/layout/grid.md
+++ b/docs/layout/grid.md
@@ -52,8 +52,7 @@ The above example creates three equal-width columns on small, medium, large, and
 
 ## Grid options
 
-While Bootstrap uses `em`s or `rem`s for defining most sizes, `px`s are used for grid breakpoints and container widths.
-This is because the viewport width is in pixels and does not change with the [font size](https://drafts.csswg.org/mediaqueries-3/#units).
+While Bootstrap uses `em`s or `rem`s for defining most sizes, `px`s are used for grid breakpoints and container widths. This is because the viewport width is in pixels and does not change with the [font size](https://drafts.csswg.org/mediaqueries-3/#units).
 
 See how aspects of the Bootstrap grid system work across multiple devices with a handy table.
 
@@ -136,9 +135,12 @@ When using Bootstrap's source Sass files, you have the option of using Sass vari
 
 ### Variables
 
-Variables determine the number of columns, the gutter width, and the media query point at which to begin floating columns. We use these to generate the predefined grid classes documented above, as well as for the custom mixins listed below.
+Variables and maps determine the number of columns, the gutter width, and the media query point at which to begin floating columns. We use these to generate the predefined grid classes documented above, as well as for the custom mixins listed below.
 
 {% highlight scss %}
+$grid-columns:      12;
+$grid-gutter-width: 15px;
+
 $grid-breakpoints: (
   // Extra small screen / phone
   xs: 0,
@@ -152,9 +154,12 @@ $grid-breakpoints: (
   xl: 1200px
 );
 
-
-$grid-columns:      12;
-$grid-gutter-width: 1.875rem;
+$container-max-widths: (
+  sm: 576px,
+  md: 720px,
+  lg: 940px,
+  xl: 1140px
+) !default;
 {% endhighlight %}
 
 ### Mixins
@@ -263,36 +268,36 @@ In addition to our semantic mixins, Bootstrap includes an extensive set of prebu
 
 ### Example: Stacked-to-horizontal
 
-Using a single set of `.col-md-*` grid classes, you can create a basic grid system that starts out stacked on mobile devices and tablet devices (the extra small to small range) before becoming horizontal on desktop (medium) devices. Place grid columns in any `.row`.
+Using a single set of `.col-md-*` grid classes, you can create a basic grid system that starts out stacked on mobile devices and tablet devices (the extra small to small range) before becoming horizontal on desktop (medium) devices. Place grid columns with the `.col` base class and a modifier within any `.row`.
 
 <div class="bd-example-row">
 {% example html %}
 <div class="row">
-  <div class="col-md-1">.col-md-1</div>
-  <div class="col-md-1">.col-md-1</div>
-  <div class="col-md-1">.col-md-1</div>
-  <div class="col-md-1">.col-md-1</div>
-  <div class="col-md-1">.col-md-1</div>
-  <div class="col-md-1">.col-md-1</div>
-  <div class="col-md-1">.col-md-1</div>
-  <div class="col-md-1">.col-md-1</div>
-  <div class="col-md-1">.col-md-1</div>
-  <div class="col-md-1">.col-md-1</div>
-  <div class="col-md-1">.col-md-1</div>
-  <div class="col-md-1">.col-md-1</div>
+  <div class="col-md-1">md-1</div>
+  <div class="col-md-1">md-1</div>
+  <div class="col-md-1">md-1</div>
+  <div class="col-md-1">md-1</div>
+  <div class="col-md-1">md-1</div>
+  <div class="col-md-1">md-1</div>
+  <div class="col-md-1">md-1</div>
+  <div class="col-md-1">md-1</div>
+  <div class="col-md-1">md-1</div>
+  <div class="col-md-1">md-1</div>
+  <div class="col-md-1">md-1</div>
+  <div class="col-md-1">md-1</div>
 </div>
 <div class="row">
-  <div class="col-md-8">.col-md-8</div>
-  <div class="col-md-4">.col-md-4</div>
+  <div class="col-md-8">md-8</div>
+  <div class="col-md-4">md-4</div>
 </div>
 <div class="row">
-  <div class="col-md-4">.col-md-4</div>
-  <div class="col-md-4">.col-md-4</div>
-  <div class="col-md-4">.col-md-4</div>
+  <div class="col-md-4">md-4</div>
+  <div class="col-md-4">md-4</div>
+  <div class="col-md-4">md-4</div>
 </div>
 <div class="row">
-  <div class="col-md-6">.col-md-6</div>
-  <div class="col-md-6">.col-md-6</div>
+  <div class="col-md-6">md-6</div>
+  <div class="col-md-6">md-6</div>
 </div>
 {% endexample %}
 </div>
@@ -383,32 +388,32 @@ In addition to column clearing at responsive breakpoints, you may need to **rese
 {% example html %}
 <div class="row">
   <div class="col-sm-5 col-md-6">.col-sm-5 .col-md-6</div>
-  <div class="col-sm-5 col-sm-offset-2 col-md-6 col-md-offset-0">.col-sm-5 .col-sm-offset-2 .col-md-6 .col-md-offset-0</div>
+  <div class="col-sm-5 offset-sm-2 col-md-6 offset-md-0">.col-sm-5 .offset-sm-2 .col-md-6 .offset-md-0</div>
 </div>
 
 <div class="row">
-  <div class="col-sm-6 col-md-5 col-lg-6">.col-sm-6 .col-md-5 .col-lg-6</div>
-  <div class="col-sm-6 col-md-5 col-md-offset-2 col-lg-6 col-lg-offset-0">.col-sm-6 .col-md-5 .col-md-offset-2 .col-lg-6 .col-lg-offset-0</div>
+  <div class="col-sm-6 col-md-5 col-lg-6">.col.col-sm-6.col-md-5.col-lg-6</div>
+  <div class="col-sm-6 col-md-5 offset-md-2 col-lg-6 offset-lg-0">.col-sm-6 .col-md-5 .offset-md-2 .col-lg-6 .offset-lg-0</div>
 </div>
 {% endexample %}
 </div>
 
 ### Example: Offsetting columns
 
-Move columns to the right using `.col-md-offset-*` classes. These classes increase the left margin of a column by `*` columns. For example, `.col-md-offset-4` moves `.col-md-4` over four columns.
+Move columns to the right using `.offset-md-*` classes. These classes increase the left margin of a column by `*` columns. For example, `.offset-md-4` moves `.col-md-4` over four columns.
 
 <div class="bd-example-row">
 {% example html %}
 <div class="row">
   <div class="col-md-4">.col-md-4</div>
-  <div class="col-md-4 col-md-offset-4">.col-md-4 .col-md-offset-4</div>
+  <div class="col-md-4 offset-md-4">.col-md-4 .offset-md-4</div>
 </div>
 <div class="row">
-  <div class="col-md-3 col-md-offset-3">.col-md-3 .col-md-offset-3</div>
-  <div class="col-md-3 col-md-offset-3">.col-md-3 .col-md-offset-3</div>
+  <div class="col-md-3 offset-md-3">.col-md-3 .offset-md-3</div>
+  <div class="col-md-3 offset-md-3">.col-md-3 .offset-md-3</div>
 </div>
 <div class="row">
-  <div class="col-md-6 col-md-offset-3">.col-md-6 .col-md-offset-3</div>
+  <div class="col-md-6 offset-md-3">.col-md-6 .offset-md-3</div>
 </div>
 {% endexample %}
 </div>
@@ -442,8 +447,30 @@ Easily change the order of our built-in grid columns with `.col-md-push-*` and `
 <div class="bd-example-row">
 {% example html %}
 <div class="row">
-  <div class="col-md-9 col-md-push-3">.col-md-9 .col-md-push-3</div>
-  <div class="col-md-3 col-md-pull-9">.col-md-3 .col-md-pull-9</div>
+  <div class="col-md-9 push-md-3">.col-md-9 .push-md-3</div>
+  <div class="col-md-3 pull-md-9">.col-md-3 .pull-md-9</div>
 </div>
 {% endexample %}
 </div>
+
+## Customizing the grid
+
+Using our built-in grid Sass variables and maps, it's possible to completely customize the predefined grid classes. Change the number of tiers, the media query dimensions, and the container widths—then recompile.
+
+For example, if you wanted just three grid tiers, you'd update the `$grid-breakpoints` and `$container-max-widths` to something like this:
+
+{% highlight scss %}
+$grid-breakpoints: (
+  sm: 480px,
+  md: 768px,
+  lg: 1024px
+);
+
+$container-max-widths: (
+  sm: 420px,
+  md: 720px,
+  lg: 940px
+) !default;
+{% endhighlight %}
+
+Save your changes and recompile to have a brand new set of predefined grid classes for column widths, offsets, pushes, and pulls. Responsive visibility utilities will also be updated to use the custom breakpoints.