From 5fbc617e75314b749a4853b6353d461c688dad08 Mon Sep 17 00:00:00 2001
From: Troy Morehouse <troymore@nbnet.nb.ca>
Date: Mon, 26 Jun 2017 00:58:50 -0300
Subject: [PATCH] [docs] form control & button documentation update (#544)

* [form-input] documentation update

* [form-select] documentation update

* [form-file] Documentation update

* [form-radio] Documentation update

* [form-checkbox] Documentation update

* [form] Documentation

* [form-fieldset] documentation update

* [button] Documentation update
---
 docs/components/button/README.md        | 49 ++++++++++++++++++++++++-
 docs/components/form-checkbox/README.md | 19 +++++++++-
 docs/components/form-fieldset/README.md | 41 ++++++++++++++++++++-
 docs/components/form-file/README.md     | 21 +++++++++--
 docs/components/form-input/README.md    | 30 +++++++++++++++
 docs/components/form-radio/README.md    | 44 +++++++++++++++++++---
 docs/components/form-select/README.md   | 35 +++++++++++++++++-
 docs/components/form/README.md          | 18 +++++++++
 docs/components/form/index.js           |  4 ++
 docs/components/form/meta.json          |  4 ++
 docs/components/index.js                |  1 +
 11 files changed, 252 insertions(+), 14 deletions(-)
 create mode 100644 docs/components/form/README.md
 create mode 100644 docs/components/form/index.js
 create mode 100644 docs/components/form/meta.json

diff --git a/docs/components/button/README.md b/docs/components/button/README.md
index 36ec6f76036..fd662a42b4c 100755
--- a/docs/components/button/README.md
+++ b/docs/components/button/README.md
@@ -1,4 +1,51 @@
 # Buttons
 
->  Use Bootstrap’s custom button styles for actions in forms, dialogs, and more.
+>  Use Bootstrap’s custom `b-button` component for actions in forms, dialogs, and more.
    Includes support for a handful of contextual variations, sizes, states, and more.
+   
+The `b-buton` component generally renders a `<button>` element. However, you can also
+render a an `<a>` element by proding an `href` prop vale. You man also generate
+`vue-router` `<router-link>` when providing a value for the `to` prop (`vue-router`
+is  required).
+
+### Button Sizes
+Fancy larger or smaller buttons? Specify `lg` or `sm` via the `size` prop.
+
+Create block level buttons — those that span the full width of a parent — by
+setting the `block` prop.
+
+### Button contextual variants
+Use the `variant` prop to generate the various bootstrap contextual button variants.
+
+By default `b-button` will render with the `secondary` variant.
+
+#### Solid color variants:
+`primary`, `secondary`, `success`, `warning`, and `danger`.
+
+#### Outline color variants:
+In need of a button, but not the hefty background colors they bring? Use the 
+`outline-*` variants to remove all background images and colors on any `b-button`
+
+`outline-primary`, `outline-secondary`, `outline-success`, `outline-warning`,
+and `outline-danger`.
+
+#### Link variant:
+Variant `link` will reder a button with the appearance of a link while maintaning the
+default passing and size of a button.
+
+### Disabled state
+Set the `disabled` prop to disable button default funtionality. `disabled` also 
+works with buttons rednered as `<a>` elements and `router-link`
+
+### Button type
+When neither `href` nor `to` props are provided, `b-button` renders an html `<button>`
+element.  You cn specify the button's type by setting the prop `type` to `button`,
+`submit` or `reset`.  The default type is `button`.
+
+### Router links
+Refer to [`vue-router`](https://router.vuejs.org/) docs for the various router-link related props.
+
+Note the `tag`attribute for `router-link` is refered to as `router-tag` in `bootstrap-vue`
+
+### Alias
+`<b-button>` can also be used by its shorter alias `<b-btn>`
diff --git a/docs/components/form-checkbox/README.md b/docs/components/form-checkbox/README.md
index 0928a6a5779..3e4cb1d3cc1 100755
--- a/docs/components/form-checkbox/README.md
+++ b/docs/components/form-checkbox/README.md
@@ -1,2 +1,19 @@
-# Forms Checkbox
+# Form Checkbox Input
 
+> For cross browser consistency, `b-form-checkbox` uses Bottstrap'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.
+
+### Value
+By default, the checkbox value will be `true` when checked and `false` when unchecked.
+You can customize the checked and unchecked values by specifying the `value` and `unchecked-value`
+properties.
+
+`v-model` binds to the `checked` property.  When you have multiple checkboxes that bind to a
+single data state variable, provide an array reference `[]` to your `v-model`.
+
+### Control sizing
+Set heights using thw `size` prop to `sm` or `lg` for small or large respectively.
+
+### Non custom check inputs
+You can have `b-form-checkbox` render a browser native chechbox input by setting the `plain` prop.
diff --git a/docs/components/form-fieldset/README.md b/docs/components/form-fieldset/README.md
index 761628ea785..9caee6d0715 100755
--- a/docs/components/form-fieldset/README.md
+++ b/docs/components/form-fieldset/README.md
@@ -1,2 +1,41 @@
-# Form fieldsets
+# Form fieldset (Form group)
 
+> The `b-form=fieldset` component is the easiest way to add some structure to forms. Its
+purpose is to provide a label and control pairing, help text and feedback text, as well
+as contextual state visual feedback
+
+### Options
+
+#### Label:
+The content of the generted `<label>` element (html supported).
+You may optionally visually hide the label by setting the prop `label-sr-only`.
+
+By default, the label apepars above the input element, but you may optionallu set
+the prop `horizontal` to place the label on the same line and control the width
+of the label by setting `label-size` to the number of columns (default of `3`).
+`label-size` has no effect if the layout is not `horizontal`
+
+The label may also optionally be alligned `left`, `center` or `right` by setting
+the respective value via the prop `label-text-align`. Alignment has no effect if
+`label-sr-only` is set.
+
+#### Description:
+Optional descriptive text which is always shown with the `.text-muted` class (html supported).
+
+#### Feedback:
+Optional text to provide textual state feedback (html supported).
+
+#### Contextual visual state:
+Optional contextual visual feedback state of `danger`, `warning` or `success`.
+You should always provide `feedback` content to assit users using assistive technologies.
+
+### Accessibility
+To enable auto-generateion of `aria-*` attributes, you must supply a unique `id`
+prop to `b-form-fieldset`.
+
+To automatically associate the label to the first input element, you must provide
+a unique `id` prop on the input component. You may optionally specify which containing
+input component the label is for by setting the `b-form-fieldset` prop `for` to the
+id string of the input.
+
+It is highly recommended that you provide a unique `id` prop on your input element.
diff --git a/docs/components/form-file/README.md b/docs/components/form-file/README.md
index 88e6b72e4e4..1f037483189 100755
--- a/docs/components/form-file/README.md
+++ b/docs/components/form-file/README.md
@@ -1,14 +1,21 @@
-# Form File
+# Form File Input
 
-On single file mode, when no file is selected or user cancels Browse dialog `v-model` is `null` indicating no file selected.
-Also drop mode is enabled by default. it can disabled by setting `no-drop` prop.
+> Customized, cross-browser consitant, file input control that supports single file,
+multiple files, and directory upload (for browsers that support directory mode)
+
+For cross browser consistency, Form file defaults to the Bootstrap custom file
+input to replace the browser defaults. They’re built on top of semantic and accessible
+markup, so it is a solid replacement for the default file input.
+
+### Single file (default)
+On single file mode, when no file is selected or user cancels Browse dialog, `v-model` is `null`
+indicating no file selected.
 
 ### Multiple files
 Multiple file uploading is supported by adding `multiple` prop to component.
 In this case `v-model` is *always* an `Array`.   
 
 ### Directory mode
-
 By adding `directory` prop, the user can select directories instead of files.
 When a directory is selected, the directory and its entire hierarchy of contents are included in the set of selected items.
 The selected file system entries can be obtained using the `webkitEntries` property. 
@@ -17,6 +24,9 @@ The selected file system entries can be obtained using the `webkitEntries` prope
 be relied for production.
 [Read more on MDN](https://developer.mozilla.org/en-US/docs/Web/API/HTMLInputElement/webkitdirectory)
 
+### Drag and Drop
+Drop mode is enabled by default. it can disabled by setting the `no-drop` prop.
+
 ### Customizations
 Language strings and chosen file name is injected using `data-` props to css `content`. 
 Local customization can be easily done with provided props such as `placeholder`, `choose-label`, `selected-format` and `drop-label`.
@@ -39,6 +49,9 @@ Also it is advised to use [:lang()](https://developer.mozilla.org/en-US/docs/Web
 }
 ```
 
+### Non custom file input
+You can have `b-form-file` render a browser native file input by setting the `plain` prop.
+
 ### 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.  To get around this 
diff --git a/docs/components/form-input/README.md b/docs/components/form-input/README.md
index 64dd97cde8c..4ef3b9fd765 100755
--- a/docs/components/form-input/README.md
+++ b/docs/components/form-input/README.md
@@ -24,3 +24,33 @@ a numeric value to the `rows` prop. The `rows` prop has no effect on other input
 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 thw `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.
+
+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
+this field properly to submit the form.
+- `warning` works well for input values that are in progress, like password strength, or
+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 steates on `b-form-input`, set the `state` prop
+to `danger`, `warning`, or `success`.
+
+#### Conveying contextual validation 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.
+
+Ensure that an alternative indication of state is also provided. For instance, you
+could include a hint about state in the form control's `<label>` text itself, or by
+providing an additional help text block. Specifically for assistive technologies, 
+invalid form controls can also be assigned an `aria-invalid="true"` attribute.
+
diff --git a/docs/components/form-radio/README.md b/docs/components/form-radio/README.md
index 73900d401cb..56bb123493a 100755
--- a/docs/components/form-radio/README.md
+++ b/docs/components/form-radio/README.md
@@ -1,9 +1,41 @@
-# Forms Radio
+# Form Radio Input
 
-> For even more customization and cross browser consistency, 
-use our completely custom form elements to replace the browser defaults.
-They’re built on top of semantic and accessible markup, so they’re solid replacements for any default form control.
+> For cross browser consistency, `b-form-radio` uses Bottstrap's custom
+radio input to replace the browser default radio input. It is built on top of
+semantic and accessible markup, so it is a solid replacement for the default radio input.
 
-**options**
+### Options
+
+Please see options in [`<b-form-select>`](./form-select) docs for details on passing options
+to `b-form-radio`
+
+### Control sizing
+Set heights using thw `size` prop to `sm` or `lg` for small or large respectively. 
+
+### Contextual States
+Bootstrap includes validation styles for danger, warning, and success states on most form controls.
+
+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
+this field properly to submit the form.
+- `warning` works well for input values that are in progress, like password strength, or
+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 steates on `b-form-radio`, set the `state` prop
+to `danger`, `warning`, or `success`.
+
+#### Conveying contextual validation 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.
+
+Ensure that an alternative indication of state is also provided. For instance, you
+could include a hint about state in the form control's `<label>` text itself, or by
+providing an additional help text block. Specifically for assistive technologies, 
+invalid form controls can also be assigned an `aria-invalid="true"` attribute.
+
+### Non custom radio inputs
+You can have `b-form-radio` render a browser native radio input by setting the `plain` prop.
 
-Please see options in [`<form-select>`](./form-select) docs.
diff --git a/docs/components/form-select/README.md b/docs/components/form-select/README.md
index 2418237fa17..f96f61ed1f7 100755
--- a/docs/components/form-select/README.md
+++ b/docs/components/form-select/README.md
@@ -38,4 +38,37 @@ Keys are mapped to value and values are mapped to option object.
   d: {text: 'D', disabled: true},
   e: {text: 'D', value:'overridden_value'}
 }
-```
\ No newline at end of file
+```
+
+### Value
+By Default `b-form-select` returns the value of the currently selected option. By
+setting the `return-object` prop to `true`, you can return the entire option object.
+
+### Control sizing
+Set heights using thw `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.
+
+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
+this field properly to submit the form.
+- `warning` works well for input values that are in progress, like password strength, or
+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 steates on `b-form-select`, set the `state` prop
+to `danger`, `warning`, or `success`.
+
+#### Conveying contextual validation 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.
+
+Ensure that an alternative indication of state is also provided. For instance, you
+could include a hint about state in the form control's `<label>` text itself, or by
+providing an additional help text block. Specifically for assistive technologies, 
+invalid form controls can also be assigned an `aria-invalid="true"` attribute.
diff --git a/docs/components/form/README.md b/docs/components/form/README.md
new file mode 100644
index 00000000000..decd62c581e
--- /dev/null
+++ b/docs/components/form/README.md
@@ -0,0 +1,18 @@
+# Form
+
+> Bootstrap form component that optionally supports inline form styles
+
+### Inline form
+Set the `inline` property to generate a Bootstrap inline form.
+
+### Related components
+See also:
+- [`<b-form-input>`](./form-input) Textual and text-like inputs
+- [`<b-form-select>`](./form-select) Select input
+- [`<b-form-radio>`](./form-radio) Radio Input groups
+- [`<b-form-checkbox>`](./form-checkbox) Checkbox Input
+- [`<b-form-file>`](./form-file) File Input
+- [`<b-form-fieldset>`](./form-fieldset) Form input wrapper to gernerate form-groups that support labels, help text and feedback
+- [`<b-button>`](./button) Buttons
+- [`<b-input-group>`](./inputgroup) Form inputs with add-ons
+
diff --git a/docs/components/form/index.js b/docs/components/form/index.js
new file mode 100644
index 00000000000..a0eb1ad8815
--- /dev/null
+++ b/docs/components/form/index.js
@@ -0,0 +1,4 @@
+import meta from './meta.json';
+import readme from './README.md';
+
+export default {meta, readme};
diff --git a/docs/components/form/meta.json b/docs/components/form/meta.json
new file mode 100644
index 00000000000..a93e175a3d0
--- /dev/null
+++ b/docs/components/form/meta.json
@@ -0,0 +1,4 @@
+{
+  "title": "Form",
+  "component": "bForm"
+}
diff --git a/docs/components/index.js b/docs/components/index.js
index 06da3d4f5cb..a27ca0d252b 100755
--- a/docs/components/index.js
+++ b/docs/components/index.js
@@ -11,6 +11,7 @@ export default {
     'carousel': require('./carousel').default,
     'collapse': require('./collapse').default,
     'dropdown': require('./dropdown').default,
+    'form': require('./form').default,
     'form-checkbox': require('./form-checkbox').default,
     'form-fieldset': require('./form-fieldset').default,
     'form-file': require('./form-file').default,