docs(forms): Update examples to use form-group where appropriate (#1435)

tmorehouse · web-flow · commit f27f2629ab30 · 2017-12-06T18:15:10.000-04:00
* docs(form-checkbox): Update multiple-checkbox examples to use form-group

* docs(form-radio): update examples to use b-form-group where appropriate

* docs(form-input): minor ARIA updates to examples
diff --git a/src/components/form-checkbox/README.md b/src/components/form-checkbox/README.md
@@ -36,17 +36,19 @@ export default {
 ```html
 <template>
   <div>
-    <h5>Using options array:</h5>
-    <b-form-checkbox-group id="checkboxes1" name="flavour1" v-model="selected" :options="options">
-    </b-form-checkbox-group>
-
-    <h5 class="mt-3">Using sub-components:</h5>
-    <b-form-checkbox-group id="checkboxes2" name="flavour2" v-model="selected">
-      <b-form-checkbox value="orange">Orange</b-form-checkbox>
-      <b-form-checkbox value="apple">Apple</b-form-checkbox>
-      <b-form-checkbox value="pineapple">Pineapple</b-form-checkbox>
-      <b-form-checkbox value="grape">Grape</b-form-checkbox>
-    </b-form-checkbox-group>
+    <b-form-group label="Using <code>options</code> array:">
+      <b-form-checkbox-group id="checkboxes1" name="flavour1" v-model="selected" :options="options">
+      </b-form-checkbox-group>
+    </b-form-group>
+
+    <b-form-group label="Using sub-components:">
+      <b-form-checkbox-group id="checkboxes2" name="flavour2" v-model="selected">
+        <b-form-checkbox value="orange">Orange</b-form-checkbox>
+        <b-form-checkbox value="apple">Apple</b-form-checkbox>
+        <b-form-checkbox value="pineapple">Pineapple</b-form-checkbox>
+        <b-form-checkbox value="grape">Grape</b-form-checkbox>
+      </b-form-checkbox-group>
+    </b-form-group>
     <hr>
     <div>Selected: <strong>{{ selected }}</strong></div>
   </div>
@@ -88,13 +90,15 @@ options (value array) to `<b-form-checkboxes>`.
 ```html
 <template>
   <div>
-    <h5>Inline checkboxes (default)</h5>
-    <b-form-checkbox-group v-model="selected" name="flavour1" :options="options">
-    </b-form-checkbox-group>
-
-    <h5 class="mt-3">Stacked checkboxes</h5>
-    <b-form-checkbox-group stacked v-model="selected" name="flavour2" :options="options">
-    </b-form-checkbox-group>
+    <b-form-group label="Inline checkboxes (default)">
+      <b-form-checkbox-group v-model="selected" name="flavour1" :options="options">
+      </b-form-checkbox-group>
+    </b-form-group>
+
+    <b-form-group label="Stacked  checkboxes">
+      <b-form-checkbox-group stacked v-model="selected" name="flavour2" :options="options">
+      </b-form-checkbox-group>
+    </b-form-group>
   </div>
 </template>
 
@@ -139,7 +143,7 @@ checkboxes are related.
 
 Whenever using multple checkboxes, it is recommended that the `<b-form-check-group>`
 be placed in a [`<b-form-group>`](/docs/components/form-group) component to
-associate a `<label>` with the entire group of checkboxes.
+associate a label with the entire group of checkboxes.
 
 ## Button style checkboxes
 Render checkboxes with the look of a button by setting the prop `buttons` on `<b-form-checkbox-group>`.
@@ -153,24 +157,25 @@ when they are in the _checked_ state.
 ```html
 <template>
   <div>
-    <h5>button style checkboxes</h5>
-    <b-form-checkbox-group buttons v-model="selected" name="butons1" :options="options">
-    </b-form-checkbox-group>
-
-    <h5 class="mt-3">
-      button style checkboxes with variant <code>primary</code> and large buttons
-    </h5>
-    <b-form-checkbox-group v-model="selected"
-                           buttons
-                           button-variant="primary"
-                           size="lg"
-                           name="buttons2"
-                           :options="options">
-    </b-form-checkbox-group>
-
-    <h5 class="mt-3">Stacked (vertical) button style checkboxes</h5>
-    <b-form-checkbox-group buttons v-model="selected" stacked :options="options">
-    </b-form-checkbox-group>
+    <b-form-group label="Button style checkboxes">
+      <b-form-checkbox-group buttons v-model="selected" name="butons1" :options="options">
+      </b-form-checkbox-group>
+    </b-form-group>
+
+    <b-form-group label="Button style checkboxes with variant <code>primary</code> and large buttons">
+      <b-form-checkbox-group v-model="selected"
+                             buttons
+                             button-variant="primary"
+                             size="lg"
+                             name="buttons2"
+                             :options="options">
+      </b-form-checkbox-group>
+    </b-form-group>
+
+    <b-form-group label="Stacked (vertical) button style checkboxes">
+      <b-form-checkbox-group buttons v-model="selected" stacked :options="options">
+      </b-form-checkbox-group>
+    </b-form-group>
   </div>
 </template>
 
@@ -207,11 +212,13 @@ chechbox input by setting the `plain` prop.
 ```html
 <template>
   <div>
-    <h5>Plain inline checkboxes</h5>
-    <b-form-checkbox-group plain v-model="selected" :options="options" />
+    <b-form-group label="Plain inline checkboxes">
+      <b-form-checkbox-group plain v-model="selected" :options="options" />
+    </b-form-group>
 
-    <h5 class="mt-3">Plain stacked checkboxes</h5>
-    <b-form-checkbox-group plain stacked v-model="selected" :options="options" />
+    <b-form-group label="Plain stacked checkboxes">
+      <b-form-checkbox-group plain stacked v-model="selected" :options="options" />
+    </b-form-group>
   </div>
 </template>
 
@@ -312,30 +319,34 @@ export default {
 **Indeterminate checkbox use-case:**
 ```html
 <template>
-  <b-card>
-    <b-form-checkbox v-model="allSelected"
-                     :indeterminate="indeterminate"
-                     aria-describedby="flavours"
-                     aria-controls="flavours"
-                     @change="toggleAll"
-     >
-      {{ allSelected ? 'Un-select' : 'Select' }}
-      All Flavors
-    </b-form-checkbox>
-    <b-form-checkbox-group id="flavors"
-                           stacked
-                           v-model="selected"
-                           name="flavs"
-                           :options="flavours"
-                           class="ml-3"
-                           aria-label="Individual flavours"
-    ></b-form-checkbox-group>
-    <p aria-live="polite">
+  <div>
+    <b-form-group>
+      <template slot="label">
+        <b>Choose your flavours:</b><br>
+        <b-form-checkbox v-model="allSelected"
+                         :indeterminate="indeterminate"
+                         aria-describedby="flavours"
+                         aria-controls="flavours"
+                         @change="toggleAll"
+         >
+          {{ allSelected ? 'Un-select All' : 'Select All' }}
+         </b-form-checkbox>
+      </template>
+      <b-form-checkbox-group id="flavors"
+                             stacked
+                             v-model="selected"
+                             name="flavs"
+                             :options="flavours"
+                             class="ml-4"
+                             aria-label="Individual flavours"
+      ></b-form-checkbox-group>
+    </b-form-group>
+    <p>
       Selected: <strong>{{ selected }}</strong><br>
       All Selected: <strong>{{ allSelected }}</strong><br>
       Indeterminate: <strong>{{ indeterminate }}</strong><br>
     </p>
-  </b-card>
+  </div>
 </template>
 
 <script>
diff --git a/src/components/form-input/README.md b/src/components/form-input/README.md
@@ -26,8 +26,8 @@ export default {
 <!-- form-input-1.vue -->
 ```
 
-## Input type
 
+## Input type
 `<b-form-input>` defaults to a `text` input, but you can set the `type` prop to one
 of the supported types: `text`, `password`, `email`, `number`, `url`, `tel`, `search`,
 `date`, `datetime`, `datetime-local`, `month`, `week`, `time`,`range`, or `color`.
@@ -75,7 +75,6 @@ than what is returned by it's value.
 
 
 ## Control sizing
-
 Set heights using the `size` prop to `sm` or `lg` for small or large respectively.
 
 To control width, place the input inside standard Bootstrap grid column.
@@ -106,7 +105,6 @@ To control width, place the input inside standard Bootstrap grid column.
 ```
 
 ## Contextual States
-
 Bootstrap includes validation styles for `valid` and `invalid` states
 on most form controls.
 
@@ -151,18 +149,20 @@ to:
 ```html
 <template>
   <div role="group">
-    <b-form-input v-model.trim="name"
+    <label for="inputLive">Name:</label>
+    <b-form-input id="inputLive"
+                  v-model.trim="name"
                   type="text"
                   :state="nameState"
-                  aria-describedby="input-help input-feeback"
+                  aria-describedby="inputLiveHelp inputLiveFeeback"
                   placeholder="Enter your name"></b-form-input>
-    <b-form-invalid-feedback id="input-feedback">
+    <b-form-invalid-feedback id="inputLiveFeedback">
       <!-- This will only be shown if the preceeding input has an invalid state -->
       Enter at least 3 letters
     </b-form-invalid-feedback>
-    <b-form-text id="input-help">
+    <b-form-text id="inputLiveHelp">
       <!-- this is a form text block (formerly known as help block) -->
-      Enter your name.
+      Your full name.
     </b-form-text>
   </div>
 </template>
@@ -189,7 +189,6 @@ export default {
 automatically generate markup similar to above.
 
 ### Conveying contextual state to assistive technologies and colorblind users
-
 Using these contextual states to denote the state of a form control only provides
 a visual, color-based indication, which will not be conveyed to users of assistive
 technologies - such as screen readers - or to colorblind users.
@@ -199,7 +198,6 @@ could include a hint about state in the form control's `<label>` text itself, or
 providing an additional help text block.
 
 ### ARIA `aria-invalid` attribute
-
 Specifically for assistive technologies, invalid form controls can also be assigned
 an `aria-invalid="true"` attribute.
 
@@ -217,7 +215,6 @@ then the `aria-invalid` attribute on the input will automatically be set to `'tr
 
 
 ## Formatter support
-
 `<b-form-input>` optionally supports formatting by passing a function reference to
 the `formatter` prop.
 
@@ -235,21 +232,29 @@ No formatting occurs if a `formatter` is not provided.
 ```html
 <template>
   <div>
-    <h5>Text input with formatter (on input)</h5>
-    <b-form-input v-model="text1"
+    <label for="inputFormatter">Text input with formatter (on input)</label>
+    <b-form-input id="inputFormatter"
+                  v-model="text1"
                   type="text"
                   placeholder="Enter your name"
+                  aria-describedby="inputFormatterHelp"
                   :formatter="format"></b-form-input>
-    <b-form-text>We will convert your name to lowercase instantly</b-form-text>
+    <b-form-text id="inputFormatterHelp">
+     We will convert your name to lowercase instantly
+    </b-form-text>
     <p>Value: {{ text1 }}</p>
 
-    <h5>Text input with lazy formatter (on change)</h5>
-    <b-form-input v-model="text2"
+    <label for="inputLazy">Text input with lazy formatter (on change)</label>
+    <b-form-input id="inputLazy"
+                  v-model="text2"
                   type="text"
                   placeholder="Enter your name"
+                  aria-describedby="inputLazyHelp"
                   :formatter="format"
                   lazy-formatter></b-form-input>
-    <b-form-text>This one is a little lazy!</b-form-text>
+    <b-form-text id="inputLazyHelp">
+      This one is a little lazy!
+    </b-form-text>
     <p>Value: {{ text2 }}</p>
   </div>
 </template>
@@ -273,18 +278,20 @@ export default {
 <!-- form-input-formatter.vue -->
 ```
 
-**Note:** When using a non-text-like input (i.e. `color`, `range`, `date`, etc),
-ensure that your formatter function returns the value in the expected format
-for the input type. The formatter **must** return the value as a string.
+**Note:** When using a non-text-like input (i.e. `color`, `range`, `date`,
+`number` etc), ensure that your formatter function returns the value in the
+expected format for the input type. The formatter **must** return the value
+as a string.
 
 
 ## Readonly plain text
-
 If you want to have `<b-form-input readonly>` elements in your form styled as plain
 text, set the `plaintext` prop (no need to set `readonly`) to remove the default form
 field styling and preserve the correct margin and padding.
 
+
 ## Component alias
 You can also use `<b-form-input>` by it's shorter alias of `<b-input>`.
 
+
 ## Component Reference
diff --git a/src/components/form-radio/README.md b/src/components/form-radio/README.md
