Update inline forms (updated docs and new flexbox styles) (#21212)

* fix form-inline with flex enabled
* grunt
* fix alignment of labels
* shorter if syntax
* add new form example to docs for now
* update inline form docs usage guidelines
* responsive margins
* better margin utils
* fix sizing of .form-check
* flexbox alignment of .form-check
* no need to change direction
* support custom controls in inline form, for default and flex modes
* add example of custom select and checks to docs
* remove hidden and visible label variants since we cover that in the usage guidelines at the start and include hidden labels everywhere
* use property value instead of layout name
* apply to all labels
* add a visible label, space it out
* add id

4 files changed, 125 insertions, 65 deletions

diff --git a/dist/css/bootstrap-flex.css b/dist/css/bootstrap-flex.css
index f60a936d8..82c2dd667 100644
--- a/dist/css/bootstrap-flex.css
+++ b/dist/css/bootstrap-flex.css
@@ -2565,11 +2565,30 @@ select.form-control-lg:not([size]):not([multiple]), .input-group-lg > select.for
   background-image: url("data:image/svg+xml;charset=utf8,%3Csvg xmlns='http://www.w3.org/2000/svg' fill='%23d9534f' viewBox='-2 -2 7 7'%3E%3Cpath stroke='%23d9534f' d='M0 0l3 3m0-3L0 3'/%3E%3Ccircle r='.5'/%3E%3Ccircle cx='3' r='.5'/%3E%3Ccircle cy='3' r='.5'/%3E%3Ccircle cx='3' cy='3' r='.5'/%3E%3C/svg%3E");
 }
 
+.form-inline {
+  display: -webkit-box;
+  display: -webkit-flex;
+  display: -ms-flexbox;
+  display: flex;
+  -webkit-flex-flow: row wrap;
+      -ms-flex-flow: row wrap;
+          flex-flow: row wrap;
+}
+
 @media (min-width: 576px) {
   .form-inline .form-group {
-    display: inline-block;
+    display: -webkit-box;
+    display: -webkit-flex;
+    display: -ms-flexbox;
+    display: flex;
+    -webkit-box-flex: 0;
+    -webkit-flex: 0 0 auto;
+        -ms-flex: 0 0 auto;
+            flex: 0 0 auto;
+    -webkit-flex-flow: row wrap;
+        -ms-flex-flow: row wrap;
+            flex-flow: row wrap;
     margin-bottom: 0;
-    vertical-align: middle;
   }
   .form-inline .form-control {
     display: inline-block;
@@ -2580,18 +2599,8 @@ select.form-control-lg:not([size]):not([multiple]), .input-group-lg > select.for
     display: inline-block;
   }
   .form-inline .input-group {
-    display: inline-table;
-    width: auto;
-    vertical-align: middle;
-  }
-  .form-inline .input-group .input-group-addon,
-  .form-inline .input-group .input-group-btn,
-  .form-inline .input-group .form-control {
     width: auto;
   }
-  .form-inline .input-group > .form-control {
-    width: 100%;
-  }
   .form-inline .form-control-label {
     margin-bottom: 0;
     vertical-align: middle;
diff --git a/dist/css/bootstrap.css b/dist/css/bootstrap.css
index 531a02965..d86305c65 100644
--- a/dist/css/bootstrap.css
+++ b/dist/css/bootstrap.css
@@ -2315,8 +2315,8 @@ select.form-control-lg:not([size]):not([multiple]), .input-group-lg > select.for
 @media (min-width: 576px) {
   .form-inline .form-group {
     display: inline-block;
-    margin-bottom: 0;
     vertical-align: middle;
+    margin-bottom: 0;
   }
   .form-inline .form-control {
     display: inline-block;
@@ -2327,8 +2327,8 @@ select.form-control-lg:not([size]):not([multiple]), .input-group-lg > select.for
     display: inline-block;
   }
   .form-inline .input-group {
-    display: inline-table;
     width: auto;
+    display: inline-table;
     vertical-align: middle;
   }
   .form-inline .input-group .input-group-addon,
diff --git a/docs/components/forms.md b/docs/components/forms.md
index 8915c9e7b..dd3e0027f 100644
--- a/docs/components/forms.md
+++ b/docs/components/forms.md
@@ -274,62 +274,54 @@ The `.form-group` class is the easiest way to add some structure to forms. Its o
 
 ### Inline forms
 
-Use the `.form-inline` class to display a series of labels, form controls, and buttons on a single horizontal row. Form controls within inline forms behave differently:
+Use the `.form-inline` class to display a series of labels, form controls, and buttons on a single horizontal row. Form controls within inline forms vary slightly from their default states.
 
-- Controls are `display: inline-block` to provide alignment control via `vertical-align` and `margin`.
-- Controls receive `width: auto` to override the Bootstrap default `width: 100%`.
-- Controls **only appear inline in viewports that are at least 768px wide** to account for narrow viewports on mobile devices.
+- Controls are `display: inline-block` (or `flex` when enabled) to provide alignment control via `vertical-align` and `margin`. Those also means you'll have some HTML character spaces between elements by default.
+- Controls and input groups receive `width: auto` to override the Bootstrap default `width: 100%`.
+- Controls **only appear inline in viewports that are at least 576px wide** to account for narrow viewports on mobile devices.
 
-Because of this, you may need to manually address the width and alignment of individual form controls. Lastly, as shown below, you should always include a `<label>` with each form control.
-
-#### Visible labels
+You may need to manually address the width and alignment of individual form controls with [spacing utilities]({{ site.baseurl }}/utilities/spacing/) (as shown below). Lastly, be sure to always include a `<label>` with each form control, even if you need to hide it from non-screenreader visitors with `.sr-only`.
 
 {% example html %}
 <form class="form-inline">
-  <div class="form-group">
-    <label for="exampleInputName2">Name</label>
-    <input type="text" class="form-control" id="exampleInputName2" placeholder="Jane Doe">
-  </div>
-  <div class="form-group">
-    <label for="exampleInputEmail2">Email</label>
-    <input type="email" class="form-control" id="exampleInputEmail2" placeholder="[email protected]">
-  </div>
-  <button type="submit" class="btn btn-primary">Send invitation</button>
-</form>
-{% endexample %}
+  <label class="sr-only" for="inlineFormInput">Name</label>
+  <input type="text" class="form-control mb-2 mr-sm-2 mb-sm-0" id="inlineFormInput" placeholder="Jane Doe">
 
-#### Hidden labels
-
-{% example html %}
-<form class="form-inline">
-  <div class="form-group">
-    <label class="sr-only" for="exampleInputEmail3">Email address</label>
-    <input type="email" class="form-control" id="exampleInputEmail3" placeholder="Enter email">
-  </div>
-  <div class="form-group">
-    <label class="sr-only" for="exampleInputPassword3">Password</label>
-    <input type="password" class="form-control" id="exampleInputPassword3" placeholder="Password">
+  <label class="sr-only" for="inlineFormInputGroup">Username</label>
+  <div class="input-group mb-2 mr-sm-2 mb-sm-0">
+    <div class="input-group-addon">@</div>
+    <input type="text" class="form-control" id="inlineFormInputGroup" placeholder="Username">
   </div>
-  <div class="form-check">
+
+  <div class="form-check mb-2 mr-sm-2 mb-sm-0">
     <label class="form-check-label">
       <input class="form-check-input" type="checkbox"> Remember me
     </label>
   </div>
-  <button type="submit" class="btn btn-primary">Sign in</button>
+
+  <button type="submit" class="btn btn-primary">Submit</button>
 </form>
 {% endexample %}
 
+Custom form controls and selects are also supported.
+
 {% example html %}
 <form class="form-inline">
-  <div class="form-group">
-    <label class="sr-only" for="exampleInputAmount">Amount (in dollars)</label>
-    <div class="input-group">
-      <div class="input-group-addon">$</div>
-      <input type="text" class="form-control" id="exampleInputAmount" placeholder="Amount">
-      <div class="input-group-addon">.00</div>
-    </div>
-  </div>
-  <button type="submit" class="btn btn-primary">Transfer cash</button>
+  <label class="mr-sm-2" for="inlineFormCustomSelect">Preference</label>
+  <select class="custom-select mb-2 mr-sm-2 mb-sm-0" id="inlineFormCustomSelect">
+    <option selected>Choose...</option>
+    <option value="1">One</option>
+    <option value="2">Two</option>
+    <option value="3">Three</option>
+  </select>
+
+  <label class="custom-control custom-checkbox mb-2 mr-sm-2 mb-sm-0">
+    <input type="checkbox" class="custom-control-input">
+    <span class="custom-control-indicator"></span>
+    <span class="custom-control-description">Remember my preference</span>
+  </label>
+
+  <button type="submit" class="btn btn-primary">Submit</button>
 </form>
 {% endexample %}
 
diff --git a/scss/_forms.scss b/scss/_forms.scss
index be19a0795..08086c22c 100644
--- a/scss/_forms.scss
+++ b/scss/_forms.scss
@@ -306,14 +306,40 @@ select.form-control-lg {
 // default HTML form controls and our custom form controls (e.g., input groups).
 
 .form-inline {
+  @if $enable-flex {
+    display: flex;
+    flex-flow: row wrap;
+
+    // Because we use flex, the initial sizing of checkboxes is collapsed and
+    // doesn't occupy the full-width (which is what we want for xs grid tier),
+    // so we force that here.
+    .form-check {
+      width: 100%;
+    }
+  }
 
   // Kick in the inline
   @include media-breakpoint-up(sm) {
+    label {
+      @if $enable-flex {
+        display: flex;
+        align-items: center;
+        justify-content: center;
+      }
+      margin-bottom: 0;
+    }
+
     // Inline-block all the things for "inline"
     .form-group {
-      display: inline-block;
+      @if $enable-flex {
+        display: flex;
+        flex: 0 0 auto;
+        flex-flow: row wrap;
+      } @else {
+        display: inline-block;
+        vertical-align: middle;
+      }
       margin-bottom: 0;
-      vertical-align: middle;
     }
 
     // Allow folks to *not* use `.form-group`
@@ -329,20 +355,25 @@ select.form-control-lg {
     }
 
     .input-group {
-      display: inline-table;
       width: auto;
-      vertical-align: middle;
 
-      .input-group-addon,
-      .input-group-btn,
-      .form-control {
-        width: auto;
+      @if not $enable-flex {
+        display: inline-table;
+        vertical-align: middle;
+
+        .input-group-addon,
+        .input-group-btn,
+        .form-control {
+          width: auto;
+        }
       }
     }
 
     // Input groups need that 100% width though
     .input-group > .form-control {
-      width: 100%;
+      @if not $enable-flex {
+        width: 100%;
+      }
     }
 
     .form-control-label {
@@ -353,10 +384,17 @@ select.form-control-lg {
     // Remove default margin on radios/checkboxes that were used for stacking, and
     // then undo the floating of radios and checkboxes to match.
     .form-check {
-      display: inline-block;
+      @if $enable-flex {
+        display: flex;
+        align-items: center;
+        justify-content: center;
+      } @else {
+        display: inline-block;
+        vertical-align: middle;
+      }
+      width: auto;
       margin-top: 0;
       margin-bottom: 0;
-      vertical-align: middle;
     }
     .form-check-label {
       padding-left: 0;
@@ -366,6 +404,27 @@ select.form-control-lg {
       margin-left: 0;
     }
 
+    // Custom form controls
+    .custom-control {
+      padding-left: 0;
+
+      @if $enable-flex {
+        display: flex;
+        align-items: center;
+        justify-content: center;
+      } @else {
+        vertical-align: middle;
+      }
+    }
+    .custom-control-indicator {
+      position: static;
+      display: inline-block;
+      @if $enable-flex {
+        margin-right: .25rem; // Flexbox alignment means we lose our HTML space here, so we compensate.
+      }
+      vertical-align: text-bottom;
+    }
+
     // Re-override the feedback icon.
     .has-feedback .form-control-feedback {
       top: 0;