Skip to content

Commit

Permalink
docs: Update live examples for ARIA compliance. (#672)
Browse files Browse the repository at this point in the history 
* 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
  • Loading branch information
@tmorehouse
tmorehouse committed Jul 7, 2017
1 parent aafea81 commit bc41883
Show file tree
Hide file tree
Showing 4 changed files with 89 additions and 53 deletions.
42 changes: 31 additions & 11 deletions docs/components/form-checkbox/README.md
View file
Original file line number Diff line number Diff line change
@@ -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>

Expand All @@ -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>
Expand All @@ -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() {
Expand Down Expand Up @@ -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
Expand All @@ -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)

10 changes: 8 additions & 2 deletions docs/components/form-file/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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>
Expand Down Expand Up @@ -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.
Expand Down
78 changes: 44 additions & 34 deletions docs/components/form-input/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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) {
Expand All @@ -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
Expand All @@ -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
Expand All @@ -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.
Expand Down
12 changes: 6 additions & 6 deletions docs/components/form-radio/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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>

Expand Down Expand Up @@ -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.

Expand All @@ -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`.
Expand All @@ -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.

0 comments on commit bc41883

Please sign in to comment.