massive rewrite of forms docs and some css

dist/css/bootstrap.css

@@ -1657,7 +1657,6 @@ label {
 .form-control {
   display: block;
   width: 100%;
-  height: 2.625rem;
   padding: .5rem .75rem;
   font-size: 1rem;
   line-height: 1.5;
@@ -1670,6 +1669,9 @@ label {
        -o-transition: border-color ease-in-out .15s, box-shadow ease-in-out .15s;
           transition: border-color ease-in-out .15s, box-shadow ease-in-out .15s;
 }
+.form-control:not(textarea), .form-control:not(select[size]), .form-control:not(select[multiple]) {
+  height: 2.625rem;
+}
 .form-control:focus {
   border-color: #66afe9;
   outline: 0;
@@ -1698,10 +1700,8 @@ label {
   cursor: false;
 }
 
-textarea.form-control {
-  height: auto;
-  padding-top: .75rem;
-  padding-bottom: .75rem;
+.form-control-file {
+  display: block;
 }
 
 input[type="search"] {
@@ -1715,12 +1715,11 @@ input[type="search"] {
 .radio, .checkbox {
   position: relative;
   display: block;
-  margin-top: 10px;
-  margin-bottom: 10px;
+  margin-bottom: .75rem;
 }
 .radio label, .checkbox label {
   min-height: 1;
-  padding-left: 20px;
+  padding-left: 1.25rem;
   margin-bottom: 0;
   font-weight: normal;
   cursor: pointer;
@@ -1728,18 +1727,18 @@ input[type="search"] {
 
 .radio input[type="radio"], .radio-inline input[type="radio"], .checkbox input[type="checkbox"], .checkbox-inline input[type="checkbox"] {
   position: absolute;
-  margin-top: 4px \9;
-  margin-left: -20px;
+  margin-top: .25rem;
+  margin-left: -1.25rem;
 }
 
 .radio + .radio, .checkbox + .checkbox {
-  margin-top: -5px;
+  margin-top: -.25rem;
 }
 
 .radio-inline, .checkbox-inline {
   position: relative;
   display: inline-block;
-  padding-left: 20px;
+  padding-left: 1.25rem;
   margin-bottom: 0;
   font-weight: normal;
   vertical-align: middle;
@@ -1748,7 +1747,7 @@ input[type="search"] {
 
 .radio-inline + .radio-inline, .checkbox-inline + .checkbox-inline {
   margin-top: 0;
-  margin-left: 10px;
+  margin-left: .75rem;
 }
 
 input[type="radio"]:disabled, input[type="radio"].disabled, fieldset[disabled] input[type="radio"], input[type="checkbox"]:disabled, input[type="checkbox"].disabled, fieldset[disabled] input[type="checkbox"] {
@@ -1947,8 +1946,8 @@ textarea.input-lg, .input-group-lg > textarea.form-control, .input-group-lg > te
 
 .help-block {
   display: block;
-  margin-top: 5px;
-  margin-bottom: 10px;
+  margin-top: .25rem;
+  margin-bottom: .75rem;
   color: #747a7f;
 }
 

docs/_data/nav.yml

@@ -76,7 +76,6 @@
         - title: User input
         - title: Sample output
     - title: Tables
-    - title: Forms
     - title: Jumbotron
     - title: Page header
     - title: Buttons
@@ -91,13 +90,14 @@
         - title: Single toggle
         - title: Checkbox and radio
         - title: Methods
+    - title: Button group
+    - title: Button dropdown
+    - title: Forms
     - title: Custom forms
       sections:
         - title: Checkboxes and radios
         - title: Select menu
         - title: File browser
-    - title: Button group
-    - title: Button dropdown
     - title: Input group
       sections:
         - title: Basic example

docs/components/forms.md

@@ -3,28 +3,70 @@ layout: page
 title: Forms
 ---
 
-Bootstrap normalizes common HTML5 form elements and adds a number of layout options for building forms of all sizes.
+Bootstrap provides several form control styles, layout options, and custom components for creating a wide variety of forms.
 
-## Example form
+## Form controls
 
-Individual form controls automatically receive some global styling. All textual `<input>`, `<textarea>`, and `<select>` elements with `.form-control` are set to `width: 100%;` by default. Wrap labels and controls in `.form-group` for optimum spacing.
+Bootstrap's form controls expand on [our Rebooted form styles](/components/reboot/#forms) with classes. Use these classes to opt into their customized displays for a more consistent rendering across browsers and devices. The example form below demonstrates common HTML form elements that receive updated styles from Bootstrap with additional classes.
 
-**Do not mix form groups directly with [input groups](/components/#input-groups).** Instead, nest the input group inside of the form group.
+Remember, since Bootstrap utilizies the HTML5 doctype, **all inputs must have a `type` attribute** for proper rendering.
 
 {% example html %}
 <form>
-  <div class="form-group">
+  <fieldset class="form-group">
     <label for="exampleInputEmail1">Email address</label>
     <input type="email" class="form-control" id="exampleInputEmail1" placeholder="Enter email">
-  </div>
-  <div class="form-group">
+  </fieldset>
+  <fieldset class="form-group">
     <label for="exampleInputPassword1">Password</label>
     <input type="password" class="form-control" id="exampleInputPassword1" placeholder="Password">
-  </div>
-  <div class="form-group">
+  </fieldset>
+  <fieldset class="form-group">
+    <label for="exampleSelect1">Example select</label>
+    <select class="form-control">
+      <option>1</option>
+      <option>2</option>
+      <option>3</option>
+      <option>4</option>
+      <option>5</option>
+    </select>
+  </fieldset>
+  <fieldset class="form-group">
+    <label for="exampleSelect2">Example multiple select</label>
+    <select multiple class="form-control">
+      <option>1</option>
+      <option>2</option>
+      <option>3</option>
+      <option>4</option>
+      <option>5</option>
+    </select>
+  </fieldset>
+  <fieldset class="form-group">
+    <label for="exampleTextarea">Example textarea</label>
+    <textarea class="form-control" id="exampleTextarea" rows="3"></textarea>
+  </fieldset>
+  <fieldset class="form-group">
     <label for="exampleInputFile">File input</label>
     <input type="file" id="exampleInputFile">
     <p class="help-block">Example block-level help text here.</p>
+  </fieldset>
+  <div class="radio">
+    <label>
+      <input type="radio" name="optionsRadios" id="optionsRadios1" value="option1" checked>
+      Option one is this and that&mdash;be sure to include why it's great
+    </label>
+  </div>
+  <div class="radio">
+    <label>
+      <input type="radio" name="optionsRadios" id="optionsRadios2" value="option2">
+      Option two can be something else and selecting it will deselect option one
+    </label>
+  </div>
+  <div class="radio disabled">
+    <label>
+      <input type="radio" name="optionsRadios" id="optionsRadios3" value="option3" disabled>
+      Option three is disabled
+    </label>
   </div>
   <div class="checkbox">
     <label>
@@ -35,31 +77,133 @@ Individual form controls automatically receive some global styling. All textual
 </form>
 {% endexample %}
 
-## Inline forms
+Below is a complete list of the specific from controls supported by Bootstrap and the classes that customize them. Additional documentation is available for each group.
+
+<table>
+  <thead>
+    <tr>
+      <th>Classes</th>
+      <th>Used for</th>
+      <th>Supported variations</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td>
+        {% markdown %}`.form-group`{% endmarkdown %}
+      </td>
+      <td class="text-nowrap">
+        Any group of form controls
+      </td>
+      <td>
+        {% markdown %}Use with any block-level element like `<fieldset>` or `<div>`{% endmarkdown %}
+      </td>
+    </tr>
+    <tr>
+      <td rowspan="3">
+        {% markdown %}`.form-control`{% endmarkdown %}
+      </td>
+      <td>
+        Textual inputs
+      </td>
+      <td>
+        {% markdown %}`text`, `password`, `datetime`, `datetime-local`, `date`, `month`, `time`, `week`, `number`, `email`, `url`, `search`, `tel`, `color`{% endmarkdown %}
+      </td>
+    </tr>
+    <tr>
+      <td>
+        Select menus
+      </td>
+      <td>
+        {% markdown %}`multiple`, `size`{% endmarkdown %}
+      </td>
+    </tr>
+    <tr>
+      <td>
+        Textareas
+      </td>
+      <td>
+        <span class="text-muted">N/A</span>
+      </td>
+    </tr>
+    <tr>
+      <td class="text-nowrap">
+        {% markdown %}`.form-control-file`{% endmarkdown %}
+      </td>
+      <td>
+        File inputs
+      </td>
+      <td>
+        {% markdown %}`file`{% endmarkdown %}
+      </td>
+    </tr>
+    <tr>
+      <td class="text-nowrap">
+{% markdown %}
+`.radio`<br>
+`.radio-inline`<br>
+`.checkbox`<br>
+`.checkbox-inline`
+{% endmarkdown %}
+      </td>
+      <td class="text-nowrap">
+        Checkboxes and radios
+      </td>
+      <td>
+        <span class="text-muted">N/A</span>
+      </td>
+    </tr>
+  </tbody>
+</table>
+
+## Form layouts
+
+Since Bootstrap applies `display: block` and `width: 100%` to almost all our form controls, forms will by default stack vertically. Additional classes can be used to vary this layout on a per-form basis.
+
+### Form groups
+
+The `.form-group` class is the easiest way to add some structure to forms. It's only purpose is to provide `margin-bottom` around a label and control pairing. As a bonus, since it's a class you can use it with `<fieldset>`s, `<div>`s, or nearly any other element.
 
-Add `.form-inline` to your `<form>` or a parent element for left-aligned and inline-block controls. Inputs and selects are set to `width: auto;` in inline forms. Depending on your layout, additional custom widths may be required. As shown below, you should alwys include a `<label>` with each form control.
+{% example html %}
+<form>
+  <fieldset class="form-group">
+    <label for="formGroupExampleLabel">Example label</label>
+    <input type="text" class="form-control" id="formGroupExampleInput" placeholder="Example input">
+  </fieldset>
+  <fieldset class="form-group">
+    <label for="formGroupExampleLabel2">Another label</label>
+    <input type="text" class="form-control" id="formGroupExampleInput2" placeholder="Another input">
+  </fieldset>
+</form>
+{% endexample %}
+
+### Inline forms
+
+Use the `.inline-form` class to to display a series of labels, form controls, and buttons on a single horizontal row. Form controls within inline forms behave differently:
+
+- 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.
 
-**Inline forms only appear inline in viewports that are at least 768px wide.**
+Because of this, you may need to manually adddres the width and alignment of individual form controls. Lastly, as shown below, you should always include a `<label>` with each form control.
 
-### Visible labels
+#### Visible labels
 
 {% example html %}
-<div class="bd-example" data-example-id="simple-form-inline">
-  <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="jane.doe@example.com">
-    </div>
-    <button type="submit" class="btn btn-primary">Send invitation</button>
-  </form>
-</div>
+<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="jane.doe@example.com">
+  </div>
+  <button type="submit" class="btn btn-primary">Send invitation</button>
+</form>
 {% endexample %}
 
-### Hidden labels
+#### Hidden labels
 
 {% example html %}
 <form class="form-inline">
@@ -94,85 +238,44 @@ Add `.form-inline` to your `<form>` or a parent element for left-aligned and inl
 </form>
 {% endexample %}
 
-## Horizontal forms
+### Using the Grid
 
-Use Bootstrap's predefined grid classes to align labels and groups of form controls in a horizontal layout by adding `.form-horizontal` to the form or form control's parent. Doing so changes `.form-group`s to behave as grid rows, so no need for `.row`.
+For more structured form layouts, you can utilize Bootstrap's predefined grid classes (or mixins). Add the `.row` class to form groups and use the `.col-*` classes to specify the width of your labels and controls.
 
 {% example html %}
-<form class="form-horizontal">
-  <div class="form-group">
+<form>
+  <div class="form-group row">
     <label for="inputEmail3" class="col-sm-2 control-label">Email</label>
     <div class="col-sm-10">
       <input type="email" class="form-control" id="inputEmail3" placeholder="Email">
     </div>
   </div>
-  <div class="form-group">
+  <div class="form-group row">
     <label for="inputPassword3" class="col-sm-2 control-label">Password</label>
     <div class="col-sm-10">
       <input type="password" class="form-control" id="inputPassword3" placeholder="Password">
     </div>
   </div>
-  <div class="form-group">
+  <div class="form-group row">
     <div class="col-sm-offset-2 col-sm-10">
       <div class="checkbox">
         <label>
           <input type="checkbox"> Remember me
         </label>
       </div>
-    </div>
-  </div>
-  <div class="form-group">
-    <div class="col-sm-offset-2 col-sm-10">
       <button type="submit" class="btn btn-secondary">Sign in</button>
     </div>
   </div>
 </form>
 {% endexample %}
 
-## Supported controls
-
-Examples of standard form controls supported in an example form layout.
-
-### Inputs
-
-The most common form control, text-based input fields. Includes support for all HTML5 types:
-
-- `text`
-- `password`
-- `datetime`
-- `datetime-local`
-- `date`
-- `month`
-- `time`
-- `week`
-- `number`
-- `email`
-- `url`
-- `search`
-- `tel`
-- `color`
-
-Since Bootstrap requires the HTML5 doctype, **all inputs must have a `type` attribute.**
-
-{% example html %}
-<input type="text" class="form-control" placeholder="Text input">
-{% endexample %}
-
-### Textarea
-
-Form control which supports multiple lines of text. Change `rows` attribute as necessary.
-
-{% example html %}
-<textarea class="form-control" rows="3"></textarea>
-{% endexample %}
-
-### Checkboxes and radios
+## Checkboxes and radios
 
 Checkboxes are for selecting one or several options in a list, while radios are for selecting one option from many.
 
 A checkbox or radio with the `disabled` attribute will be styled appropriately. To have the `<label>` for the checkbox or radio also display a "not-allowed" cursor when the user hovers over the label, add the `.disabled` class to your `.radio`, `.radio-inline`, `.checkbox`, `.checkbox-inline`, or `<fieldset>`.
 
-#### Default (stacked)
+### Default (stacked)
 
 {% example html %}
 <div class="checkbox">
@@ -208,7 +311,7 @@ A checkbox or radio with the `disabled` attribute will be styled appropriately.
 </div>
 {% endexample %}
 
-#### Inline
+### Inline
 
 Use the `.checkbox-inline` or `.radio-inline` classes on a series of checkboxes or radios for controls that appear on the same line.
 
@@ -236,7 +339,7 @@ Use the `.checkbox-inline` or `.radio-inline` classes on a series of checkboxes
 </label>
 {% endexample %}
 
-#### Without labels
+### Without labels
 
 Should you have no text within the `<label>`, the input is positioned as you'd expect. **Currently only works on non-inline checkboxes and radios.**
 
@@ -253,34 +356,6 @@ Should you have no text within the `<label>`, the input is positioned as you'd e
 </div>
 {% endexample %}
 
-### Selects
-
-Note that many native select menus—namely in Safari and Chrome—have rounded corners that cannot be modified via `border-radius` properties.
-
-Use the default option, or add `multiple` to show multiple options at once.
-
-{% example html %}
-<select class="form-control">
-  <option>1</option>
-  <option>2</option>
-  <option>3</option>
-  <option>4</option>
-  <option>5</option>
-</select>
-{% endexample %}
-
-For `<select>` controls with the `multiple` attribute, multiple options are shown by default.
-
-{% example html %}
-<select multiple class="form-control">
-  <option>1</option>
-  <option>2</option>
-  <option>3</option>
-  <option>4</option>
-  <option>5</option>
-</select>
-{% endexample %}
-
 ## Static controls
 
 When you need to place plain text next to a form label within a form, use the `.form-control-static` class on a `<p>`.

docs/dist/css/bootstrap.css

@@ -1657,7 +1657,6 @@ label {
 .form-control {
   display: block;
   width: 100%;
-  height: 2.625rem;
   padding: .5rem .75rem;
   font-size: 1rem;
   line-height: 1.5;
@@ -1670,6 +1669,9 @@ label {
        -o-transition: border-color ease-in-out .15s, box-shadow ease-in-out .15s;
           transition: border-color ease-in-out .15s, box-shadow ease-in-out .15s;
 }
+.form-control:not(textarea), .form-control:not(select[size]), .form-control:not(select[multiple]) {
+  height: 2.625rem;
+}
 .form-control:focus {
   border-color: #66afe9;
   outline: 0;
@@ -1698,10 +1700,8 @@ label {
   cursor: false;
 }
 
-textarea.form-control {
-  height: auto;
-  padding-top: .75rem;
-  padding-bottom: .75rem;
+.form-control-file {
+  display: block;
 }
 
 input[type="search"] {
@@ -1715,12 +1715,11 @@ input[type="search"] {
 .radio, .checkbox {
   position: relative;
   display: block;
-  margin-top: 10px;
-  margin-bottom: 10px;
+  margin-bottom: .75rem;
 }
 .radio label, .checkbox label {
   min-height: 1;
-  padding-left: 20px;
+  padding-left: 1.25rem;
   margin-bottom: 0;
   font-weight: normal;
   cursor: pointer;
@@ -1728,18 +1727,18 @@ input[type="search"] {
 
 .radio input[type="radio"], .radio-inline input[type="radio"], .checkbox input[type="checkbox"], .checkbox-inline input[type="checkbox"] {
   position: absolute;
-  margin-top: 4px \9;
-  margin-left: -20px;
+  margin-top: .25rem;
+  margin-left: -1.25rem;
 }
 
 .radio + .radio, .checkbox + .checkbox {
-  margin-top: -5px;
+  margin-top: -.25rem;
 }
 
 .radio-inline, .checkbox-inline {
   position: relative;
   display: inline-block;
-  padding-left: 20px;
+  padding-left: 1.25rem;
   margin-bottom: 0;
   font-weight: normal;
   vertical-align: middle;
@@ -1748,7 +1747,7 @@ input[type="search"] {
 
 .radio-inline + .radio-inline, .checkbox-inline + .checkbox-inline {
   margin-top: 0;
-  margin-left: 10px;
+  margin-left: .75rem;
 }
 
 input[type="radio"]:disabled, input[type="radio"].disabled, fieldset[disabled] input[type="radio"], input[type="checkbox"]:disabled, input[type="checkbox"].disabled, fieldset[disabled] input[type="checkbox"] {
@@ -1947,8 +1946,8 @@ textarea.input-lg, .input-group-lg > textarea.form-control, .input-group-lg > te
 
 .help-block {
   display: block;
-  margin-top: 5px;
-  margin-bottom: 10px;
+  margin-top: .25rem;
+  margin-bottom: .75rem;
   color: #747a7f;
 }
 

scss/_forms.scss

@@ -100,25 +100,38 @@ label {
 .form-control {
   display: block;
   width: 100%;
-  height: $input-height-base; // Make inputs at least the height of their button counterpart (base line-height + padding + border)
+  // display: inline-block;
+  // // Make inputs at least the height of their button counterpart (base line-height + padding + border)
+  // height: $input-height-base;
   padding: $padding-base-vertical $padding-base-horizontal;
   font-size: $font-size-base;
   line-height: $line-height-base;
   color: $input-color;
   background-color: $input-bg;
-  background-image: none; // Reset unusual Firefox-on-Android default style; see https://github.com/necolas/normalize.css/issues/214
+  // Reset unusual Firefox-on-Android default style; see https://github.com/necolas/normalize.css/issues/214.
+  background-image: none;
   border: 1px solid $input-border;
-  @include border-radius($input-border-radius); // Note: This has no effect on <select>s in some browsers, due to the limited stylability of `<select>`s in CSS.
+   // Note: This has no effect on <select>s in some browsers, due to the limited stylability of `<select>`s in CSS.
+  @include border-radius($input-border-radius);
   @include box-shadow(inset 0 1px 1px rgba(0,0,0,.075));
   transition: border-color ease-in-out .15s, box-shadow ease-in-out .15s;
 
+  // Make inputs at least the height of their button counterpart (base line-height + padding + border).
+  // Only apply the height to textual inputs and some selcts.
+  &:not(textarea),
+  &:not(select[size]),
+  &:not(select[multiple]) {
+    height: $input-height-base;
+  }
+
   // Customize the `:focus` state to imitate native WebKit styles.
   @include form-control-focus();
 
   // Placeholder
   &::placeholder {
     color: $input-color-placeholder;
-    opacity: 1; // Override Firefox's unusual default opacity; see https://github.com/twbs/bootstrap/pull/11526
+    // Override Firefox's unusual default opacity; see https://github.com/twbs/bootstrap/pull/11526.
+    opacity: 1;
   }
 
   // Disabled and read-only inputs
@@ -130,7 +143,8 @@ label {
   &[readonly],
   fieldset[disabled] & {
     background-color: $input-bg-disabled;
-    opacity: 1; // iOS fix for unreadable disabled content; see https://github.com/twbs/bootstrap/issues/11655
+    // iOS fix for unreadable disabled content; see https://github.com/twbs/bootstrap/issues/11655.
+    opacity: 1;
   }
 
   &[disabled],
@@ -139,13 +153,17 @@ label {
   }
 }
 
-// Reset height for `textarea`s
-textarea.form-control {
-  height: auto;
-  padding-top: $padding-base-horizontal;
-  padding-bottom: $padding-base-horizontal;
-}
+// // Reset height for `textarea`s
+// textarea.form-control {
+//   height: auto;
+//   padding-top: $padding-base-horizontal;
+//   padding-bottom: $padding-base-horizontal;
+// }
 
+// Make file inputs better match text inputs by forcing them to new lines.
+.form-control-file {
+  display: block;
+}
 
 // Search inputs in iOS
 //
@@ -204,12 +222,13 @@ input[type="search"] {
 .checkbox {
   position: relative;
   display: block;
-  margin-top: 10px;
-  margin-bottom: 10px;
+  // margin-top:    ($spacer * .75);
+  margin-bottom: ($spacer * .75);
 
   label {
-    min-height: $line-height-computed; // Ensure the input doesn't jump when there is no text
-    padding-left: 20px;
+    // Ensure the input doesn't jump when there is no text
+    min-height: $line-height-computed;
+    padding-left: 1.25rem;
     margin-bottom: 0;
     font-weight: normal;
     cursor: pointer;
@@ -220,13 +239,15 @@ input[type="search"] {
 .checkbox input[type="checkbox"],
 .checkbox-inline input[type="checkbox"] {
   position: absolute;
-  margin-top: 4px \9;
-  margin-left: -20px;
+  margin-top: .25rem;
+  // margin-top: 4px \9;
+  margin-left: -1.25rem;
 }
 
 .radio + .radio,
 .checkbox + .checkbox {
-  margin-top: -5px; // Move up sibling radios or checkboxes for tighter spacing
+  // Move up sibling radios or checkboxes for tighter spacing
+  margin-top: -.25rem;
 }
 
 // Radios and checkboxes on same line
@@ -234,7 +255,7 @@ input[type="search"] {
 .checkbox-inline {
   position: relative;
   display: inline-block;
-  padding-left: 20px;
+  padding-left: 1.25rem;
   margin-bottom: 0;
   font-weight: normal;
   vertical-align: middle;
@@ -243,7 +264,7 @@ input[type="search"] {
 .radio-inline + .radio-inline,
 .checkbox-inline + .checkbox-inline {
   margin-top: 0;
-  margin-left: 10px; // space out consecutive inline controls
+  margin-left: .75rem;
 }
 
 // Apply same disabled cursor tweak as for inputs
@@ -406,8 +427,8 @@ input[type="checkbox"] {
 
 .help-block {
   display: block; // account for any element using help-block
-  margin-top: 5px;
-  margin-bottom: 10px;
+  margin-top: .25rem;
+  margin-bottom: .75rem;
   color: lighten($text-color, 25%); // lighten the text some for contrast
 }