bootstrap-vue · tmorehouse · Nov 21, 2018 · Oct 27, 2018 · Oct 28, 2018 · Oct 28, 2018
diff --git a/src/components/form-textarea/README.md b/src/components/form-textarea/README.md
@@ -29,30 +29,59 @@ export default {
 <!-- form-textarea-1.vue -->
 ```
 
-## Displayed rows
+## Control sizing
+Set text height using the `size` prop to `sm` or `lg` for small or large respectively.
 
-`<b-form-textarea>` automaticlly adjusts its height (text rows) to fit the content,
-even as the user enters text. For a textarea with no content, the number of rows
-starts at `1`.
+To control width, place the input inside standard Bootstrap grid column.
 
-To set the initial minimum height (in rows), set the `rows` prop to the desired
-number of lines. If no value is provided to `rows`, then it will default to `1`.
+```html
+<b-container fluid>
+  <b-row class="my-1">
+    <b-col sm="2"><label for="input-small">Small:</label></b-col>
+    <b-col sm="10">
+      <b-form-textarea id="input-small" size="sm" type="text" placeholder="Small Textarea"></b-form-textarea>
+    </b-col>
+  </b-row>
+  <b-row class="my-1">
+    <b-col sm="2"><label for="input-default">Default:</label></b-col>
+    <b-col sm="10">
+      <b-form-textarea id="input-default" type="text" placeholder="Default Textarea"></b-form-text-area>
+    </b-col>
+  </b-row>
+  <b-row class="my-1">
+    <b-col sm="2"><label for="input-large">Large:</label></b-col>
+    <b-col sm="10">
+      <b-form-textarea id="input-large" size="lg" type="text" placeholder="Large Textarea"></b-form-textarea>
+    </b-col>
+  </b-row>
+</b-container>
+
+<!-- form-textarea-size-1.vue -->
+```
 
-To limit the maximum rows that the text area will grow to (before showing a scrollbar),
-set the `max-rows` prop to the maximum number of lines of text.
 
-To keep the text-area at a set height, set both `rows` and `max-rows` to the same value.
+## Displayed rows
+To set the height of `<b-form-textarea>`, set the `rows` prop to the desired number of
+rows.  If no value is provided to `rows`, then it will default to `2` (the browser
+default and minimum acceptable value). Setting it to null or a value below 2 will
+result in the default of `2` being used.
 
-**Note:** auto rows will only work when the user explicitly enters newlines in the textarea.
+### Disable resize handle
+Some web browsers will allow the user to re-size the height of the textarea.
+To disable this feature, set the `no-resize` prop to `true`.
 
-### Disable resize
+### Auto height
+`<b-form-textarea>` can also automatically adjust its height (text rows) to fit the content,
+even as the user enters text.
 
-Note that some web browsers will allow the user to re-size the hight of the textarea.
-To disable this, set the `no-resize` prop to `true`.
+To set the initial minimum height (in rows), set the `rows` prop to the desired
+number of lines (or leave it at the default of `2`).
 
+To limit the maximum rows that the text area will grow to (before showing a scrollbar),
+set the `max-rows` prop to the maximum number of lines of text.
 
-## Contextual states
 
+## Textarea contextual states
 Bootstrap includes validation styles for `valid` and `invalid` states on most form controls.
 
 Generally speaking, you’ll want to use a particular state for specific types of feedback:
@@ -61,16 +90,16 @@ Generally speaking, you’ll want to use a particular state for specific types o
 - `null` Displays no validation state
 
 To apply one of the contextual state icons on `<b-form-textarea>`, set the `state` prop to:
-- `'invalid'` or `false` to apply invalid styling)
-- `'valid'` or `true` to apply valid highlighting,
+- The string `'invalid'` or Boolean `false` to apply invalid styling
+- The string `'valid'` or Boolean `true` to apply valid styling
 - `null` for no validation contextual state
 
 ```html
 <template>
   <b-form-textarea id="textarea2"
-                   state="invalid"
+                   :state="text.length >= 10"
                    v-model.trim="text"
-                   placeholder="Enter something"
+                   placeholder="Enter at least 10 characters"
                    :rows="3"></b-form-textarea>
 </template>
 
@@ -88,7 +117,6 @@ export default {
 ```
 
 ### 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.
@@ -98,11 +126,10 @@ include a hint about state in the form control's `<label>` text itself, or by pr
 an additional help text block.
 
 ### ARIA `aria-invalid` attribute
-
 When `<b-form-textarea>` has an invalid contextual state (i.e. `'invalid'` or `false`)
 you may also want to set the prop `aria-invalid` to `true`, or one of hte supported values:
 
-- `false`: No errors detected (default)
+- `false`: No errors (default)
 - `true` or `'true'`: The value has failed validation.
 - `'grammar'`: A grammatical error has been detected.
 - `'spelling'` A spelling error has been detected.
@@ -112,11 +139,16 @@ not explicity set, `<b-form-textarea>` will automatically set the `aria-invalid`
 attribute to `'true'`.
 
 
-## Readonly plain text
+## Formatter support
+Refer to the (`<b-form-input>`)[../form-input] documentation regarding usage of the
+optional formatter feature.
+
 
+## Readonly plain text
 If you want to have `<b-form-textarea 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 and height.
+text, set the `plaintext` prop (no need to set `readonly` as it will be set
+automatically) to remove the default form field styling and preserve the correct
+text size, margin, padding and height.
 
 ```html
 <template>
@@ -136,5 +168,69 @@ export default {
 <!-- form-textarea-plaintext.vue -->
 ```
 
+## V-model modifiers
+Vue does not officially support `.lazy`, `.trim`, and `.number` modifiers on the `v-model` of
+custom component based inputs, and may generate a bad user experience. Avoid using Vue's native modifiers.
+
+To get around this, `<b-for-textarea>` and `<b-form-input>` have two boolean props `trim` and `number`
+which emulate the native Vue `v-model` modifiers `.trim` and `.number` respectivley. Emulation of the
+`.lazy` modifier is _not_ supported (listen for `change` or `blur` events instead).
+
+**Notes:**
+- The `number` prop takes precedence over the `trim` prop (i.e. `trim` will have no effect when `number` is set).
+- When using the `number` prop, and if the value can be parsed as a number (via `parseFloat`) it will return a value of type `Number` to the `v-model`, otherwise the original input value is returned as type `String`. This is the same behaviour as the native `.number` modifier.
+- The `trim` and `number` modifier props do not affect the value returned by the `input` or `change` events. These events will aways return the string value of the content of `<textarea>` after optional formatting (which may not match the value returned via the `v-model` `update` event, which handles the modifiers).
+
+
+## Native and custom events
+All native events (other than the custom `input` and `change` events) are supported, without
+the need for the `.native` modifier.
+
+The custom `input` and `change` events receive a single argument of the current `value` (after any
+formatting has been applied), and are triggerd by user interaction.
+
+The custom `update` event is passed the input value, and is emitted wehenever the v-model needs
+updating (it is emitted before `input`, `change`. and `blur` as needed).
+
+You can always access the native `input` and `change` events by using the `.native` modifier.
+
+
+## Exposed input properties and methods
+`<b-form-input>` exposes several of the native input element's properties and methods on the 
+component reference (i.e. assign a `ref` to your `<b-form-input ref="foo" ...>` and
+use `this.$refs['foo'].propertyName` or `this.$refs['foo'].methodName(...)`).
+
+### Input Properties
+
+| Property | Notes
+| -------- | -----
+| `.selectionStart` | Read/Write
+| `.selectionEnd` | Read/Write
+| `.selectionDirection` | Read/Write
+| `.validity` | Read only
+| `.validationMessage` | Read only
+| `.willValidate` | Read only
+
+### Input Methods
+
+| Method | Notes |
+| ------ | ----- |
+| `.focus()` | Focus the input |
+| `.blur()` | Remove focus from the input |
+| `.select()` | Selects all text within the input |
+| `.setSelectionRange()` |  |
+| `.setRangeText()` |  |
+| `.setCustomValidity()` |  |
+| `.checkValidity()` |  |
+| `.reportValidity()` |  |
+
+Refer to https://developer.mozilla.org/en-US/docs/Web/API/HTMLInputElement for
+more information on these methods and properties.  Support will vary based on
+input type.
+
+
+## Component alias
+You can use `<b-form-textarea>` by it's shorter alias `<b-textarea>`.
+
 
 <!-- Component reference added automatically from component package.json -->
diff --git a/src/components/form-textarea/fixtures/form-textarea.html b/src/components/form-textarea/fixtures/form-textarea.html