docs: Update live examples for ARIA compliance. (bootstrap-vue#672)

tmorehouse · web-flow · commit bc418836879d · 2017-07-07T18:10:23.000-03:00
* docs(form-fieldset): add IDs to form-fieldsets and inputs
* docs(form-file): Add ID's to to file-input in examples
* docs(form-radio): Add IDs to radio groups in live example
* docs(form-checkbox): Update examples for ARIA compliance
* docs(form-input): Update live examples and docs
diff --git a/docs/components/form-checkbox/README.md b/docs/components/form-checkbox/README.md
@@ -1,14 +1,14 @@
 # Form Checkbox Input
 
-> For cross browser consistency, `b-form-checkbox` uses Bootstrap's custom
+> For cross browser consistency, `<b-form-checkbox>` uses Bootstrap's custom
 checkbox input to replace the browser default checkbox input. It is built on top of
 semantic and accessible markup, so it is a solid replacement for the default checkbox input.
 
 **Example 1:** Single checkbox
 ```html
 <template>
   <div>
-    <b-form-checkbox v-model="state" value="accepted" unchecked-value="not_accepted">
+    <b-form-checkbox id="checkbox1" v-model="state" value="accepted" unchecked-value="not_accepted">
       I accept terms and use
     </b-form-checkbox>
 
@@ -31,11 +31,19 @@ export default {
 ```html
 <template>
   <div>
-    <b-form-fieldset :label="label" :description="desc" :state="state" :feedback="feedback">
-      <b-form-checkbox v-model="selected" value="orange">Orange</b-form-checkbox>
-      <b-form-checkbox v-model="selected" value="apple">Apple</b-form-checkbox>
-      <b-form-checkbox v-model="selected" value="pineapple">Pineapple</b-form-checkbox>
-      <b-form-checkbox v-model="selected" value="grape">Grape</b-form-checkbox>
+    <b-form-fieldset id="fieldset2"
+                     :label="label"
+                     label-for="checkboxes2"
+                     :description="desc"
+                     :state="state"
+                     :feedback="feedback"
+    >
+      <div role="group" id="checkboxes2">
+        <b-form-checkbox v-model="selected" name="flavour" value="orange">Orange</b-form-checkbox>
+        <b-form-checkbox v-model="selected" name="flavour" value="apple">Apple</b-form-checkbox>
+        <b-form-checkbox v-model="selected" name="flavour" value="pineapple">Pineapple</b-form-checkbox>
+        <b-form-checkbox v-model="selected" name="flavour" value="grape">Grape</b-form-checkbox>
+      </div>
     </b-form-fieldset>
     <hr>
     <div>Selected: <strong>{{ selected }}</strong></div>
@@ -47,7 +55,7 @@ export default {
   data: {
     label: 'Choose Your Flavours:',
     desc: 'Select at most <b>2</b> flavours',
-    selected: []
+    selected: [] // Must be an array reference!
   },
   computed: {
     feedback() {
@@ -88,9 +96,17 @@ Only the value(s) of the chcekboxes will be returned in the `v-model` bound arra
 should provide unique values for each checkbox's `value` prop.
 
 
-### Control sizing
-Set heights/text size by setting the `size` prop to `sm` or `lg` for small or
-large respectively.
+### Multiple checkboxes and accessibility
+When binding multiple checkboxes together, you should set the `name` prop to the same value for
+all checkboxes in the group, as well as wrap the group in a `<div>` (or other block element)
+which has the aria attribute `role="group"`. This will inform users of assitive technologies
+that the checkboxes are related.
+
+When placing the group of checkboxes inside a `<b-form-fieldset>`, set a unique `id` on the
+element with `role="group"` and set the `label-for` prop of the `<b-form-fieldet>` to
+this `id` value (see **Example 2** above).  Whenever using grouped checkboxes, it is
+recommended that they be placed in a `<b-form-fieldset>` component to associate a `<label>`
+with the entire group of checkboxes.
 
 
 ### Contextual states
@@ -103,3 +119,7 @@ of the standard Bootstrap V4 `.has-*` state class applied.
 ### Non custom check inputs
 You can have `b-form-checkbox` render a browser native chechbox input by setting the `plain` prop.
 
+
+### See also
+- [`<b-form-fieldset>`](./form-fieldset)
+
diff --git a/docs/components/form-file/README.md b/docs/components/form-file/README.md
@@ -7,12 +7,12 @@ multiple files, and directory upload (for browsers that support directory mode)
 <template>
 <div>
   <!-- Simple File -->
-  <b-form-file v-model="file"></b-form-file>
+  <b-form-file id="file_input1" v-model="file"></b-form-file>
   <br> Selected file: {{file && file.name}}
 
   <div class="mt-3">
     <!-- Customized labels -->
-    <b-form-file v-model="file2" choose-label="Attachment2"></b-form-file>
+    <b-form-file id="file_input2" v-model="file2" choose-label="Attachment2"></b-form-file>
     <br> Selected file : {{file2 && file2.name}}
   </div>
 </div>
@@ -104,6 +104,12 @@ to use [:lang()](https://developer.mozilla.org/en-US/docs/Web/CSS/:lang) for mul
 ### Non custom file input
 You can have `<b-form-file>` render a browser native file input by setting the `plain` prop.
 
+### Accessibility
+When using the custom version of  `<b-form-file>` input which hides the original input, it is
+highly recommended that you supply a unique ID string via the `id` prop. This will
+automatically render the extra ARIA atributes required to improve usability for
+persons using assitive technologies.
+
 ### Clearing the file selection
 Because of limitations in the value binding with `<input type="file">` elements, `v-model`
 for `<b-form-file>` is unidirectional, and cannot be used to set or clear the file(s) selection.
diff --git a/docs/components/form-input/README.md b/docs/components/form-input/README.md
@@ -3,43 +3,42 @@
 > Create various text style inputs such as: `text`, `password`, `number`, `url`,
 `search`, and more. Also supports creating `textarea` controls.
 
+**Example:**
 ```html
 <template>
   <div>
-    <b-form-input v-model="text"
+    <h5>Text input with formatter</h5>
+    <b-form-input v-model="text1"
                   type="text"
                   placeholder="Enter your name"
-                  :state="text.length?'success':'warning'"
                   :formatter="format"
     ></b-form-input>
     <small class="text-muted">We will convert your name to lowercase instantly</small>
+    <p>Value: {{ text1 }}</p>
 
-    <br>
-    <br>
-
-    <b-form-input v-model="text"
+    <h5>Text input with lazy formatter (on bluer)</h5>
+    <b-form-input v-model="text2"
                   type="text"
                   placeholder="Enter your name"
-                  :state="text.length?'success':'warning'"
                   :formatter="format"
                   lazy-formatter
     ></b-form-input>
     <small class="text-muted">This one is a little lazy!</small>
+    <p>Value: {{ text2 }}</p>
 
-    <br>
-    <br>
-
-    <b-form-input textarea v-model="text" placeholder="Text area mode"></b-form-input>
-
-    <br>
-    <p>Value: {{text}}</p>
+    <h5>Textarea with auto row height</h5>
+    <b-form-input textarea v-model="text3" placeholder="Text area mode"></b-form-input>
+    <p>Value: </p>
+    <pre>{{ text3 }}</pre>
   </div>  
 </template>
 
 <script>
 export default {
   data: {
-    text: '',
+    text1: '',
+    text2: '',
+    text3: ''
   },
   methods: {
     format(value) {
@@ -49,48 +48,58 @@ export default {
 }
 </script>
 
-<!-- form-input.vue -->
+<!-- form-input-1.vue -->
 ```
 
+### Input type
+`<b-form-input>` defaults to a `text` input, but you can set it to any other text-like
+type, such as `password`, `number`, `url`, etc, by setting the `type` prop.
+
+#### Textarea mode
+Render a `<textarea>` element by setting the `textarea` prop to `true`. The
+`type` prop is ignored when prop `textarea` is set.
+
+By default the `<textarea>` will automatically size its height based on on the number
+lines (separated by newlines) of text it contains. You can override this behaviour by supplying
+a numeric value to the `rows` prop. The `rows` prop has no effect on other input types.
+
+
 ### Formatter
-`<b-form-input>` supports optional formatting by passing a function reference to  the `formatter` prop.
+`<b-form-input>` optionally supports formatting by passing a function reference to  the `formatter` prop.
 
-By default, formatting occurs when the control's input event fires.  You can use  the boolean
+By default, formatting occurs when the control's native `input` event fires. You can use the boolean
 prop `lazy-formatter` to restrict the formatter function to being called on the
-control's `change` event only.
+control's native `change` event (which usually occurs on blur).
 
 The `formatter` function receives a single argument which is the control's current value, and 
 should return the formatted value.
 
-### Textarea
-Render a `<textarea>` element by setting the `textarea` prop to `true`. The
-`type` prop is ignored when prop `textarea` is set.
+No formatting occurs if a `formatter` is not provided.
 
-By default the `<textarea>` will automatically size its height based on on the number
-lines (separated by newlines) of text it contains. You can override this behaviour by supplying
-a numeric value to the `rows` prop. The `rows` prop has no effect on other input types.
 
 ### Static Control
 Easily convert a `<b-form-input>` control to a Bootstrap static form
 control by setting the prop `static` to true.
 
 You can also use the `<b-form-input-static>` component to create static form controls.
 
+
 ### 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.
 
+
 ### Contextual States
 Bootstrap includes validation styles for danger, warning, and success states
-on most form controls. Note that these states will not appear unless the
-`<b-form-input>` is wrapped in a `<b-form fieldset>` which also has the same
-`state` value.
+on most form controls.
 
-On `<b-form-input>`, these states will add the corresponding validtion state
-icon at the right of the input. Validation icons are url()s configured via
-Bootstrap V4's Sass variables that are applied to background-image declarations
-for each state.
+**Note that these states will not appear unless the `<b-form-input>` is
+wrapped in a `<b-form fieldset>` which also has the same `state` value.**
+
+On `<b-form-input>`, these states will add the corresponding **validtion state icon**
+at the right of the input. Validation icons are url()s configured via Bootstrap V4's
+SaSS variables that are applied to background-image declarations for each state.
 
 Generally speaking, you’ll want to use a particular state for specific types of feedback:
 - `danger` is great for when there’s a blocking or required field. A user must fill in
@@ -100,10 +109,10 @@ soft validation before a user attempts to submit a form.
 - `success` is ideal for situations when you have per-field validation throughout a form
 and want to encourage a user through the rest of the fields.
 
-To apply one of the contextual states on `<b-form-input>`, set the `state` prop
+To apply one of the contextual state icons on `<b-form-input>`, set the `state` prop
 to `danger`, `warning`, or `success`. Remember that you will not see the validation 
 state icon unless the input is wrapped in a `<b-form-fieldset>` which also
-has the same `state` applied!
+has the **same** `state` applied!
 
 #### Conveying contextual validation state to assistive technologies and colorblind users:
 Using these contextual states to denote the state of a form control only provides
@@ -115,6 +124,7 @@ could include a hint about state in the form control's `<label>` text itself, or
 providing an additional help text block. Specifically for assistive technologies, 
 invalid form controls can also be assigned an `aria-invalid="true"` attribute.
 
+
 ### ARIA `aria-invalid` attribute
 When `<form-input>` has an invalid contextual state (i.e. `danger`) you may also
 want to set the `<b-form-input>` prop `invalid` to `true`, or a string value.
diff --git a/docs/components/form-radio/README.md b/docs/components/form-radio/README.md
@@ -8,17 +8,17 @@ semantic and accessible markup, so it is a solid replacement for the default rad
 <template>
   <div>
     <h5>Inline radios (default)</h5>
-    <b-form-radio v-model="selected" :options="options"></b-form-radio>
+    <b-form-radio id="radios1" v-model="selected" :options="options"></b-form-radio>
 
     <br>
     
     <h5>Stacked radios</h5>
-    <b-form-radio v-model="selected" :options="options" stacked></b-form-radio>
+    <b-form-radio id="radios2" v-model="selected" :options="options" stacked></b-form-radio>
 
     <br>
     
     <h5>Small Stacked radios</h5>
-    <b-form-radio v-model="selected" :options="options" stacked size="sm"></b-form-radio>
+    <b-form-radio id="radios3" v-model="selected" :options="options" stacked size="sm"></b-form-radio>
 
     <hr>
 
@@ -55,13 +55,12 @@ export default {
 Please see options in [`<b-form-select>`](./form-select) docs for details on passing options
 to `<b-form-radio>`
 
-### Control sizing
-Set heights using the `size` prop to `sm` or `lg` for small or large text respectively.
 
 ### Inline or stacked
 By default `<b-form-radio>` generates inline radio inputs. Set the prop `stacked` to make
 the radios appear one over the other.
 
+
 ### Contextual States
 Bootstrap includes validation styles for danger, warning, and success states on most form controls.
 
@@ -87,6 +86,7 @@ could include a hint about state in the form control's `<label>` text itself, or
 providing an additional help text block. Specifically for assistive technologies, 
 invalid form controls can also be assigned an `aria-invalid="true"` attribute (see below).
 
+
 ### ARIA `aria-invalid` attribute
 When `<b-form-radio>` has an invalid contextual state (i.e. `danger`) you may also
 want to set the `<b-form-radio>` prop `invalid` to `true`.
@@ -95,6 +95,6 @@ Supported `invalid` values are:
 - `false` (default) No errors detected
 - `true` The value has failed validation.
 
+
 ### Non custom radio inputs
 You can have `b-form-radio` render a browser native radio input by setting the `plain` prop.
-
