docs(input): Initial commit of docs

Also changed the editorconfig for markdown files to ease up on the tabbing restrictions to the code
samples can be aligned nicely.

.editorconfig

@@ -9,3 +9,6 @@ insert_final_newline = true
 indent_style = space
 indent_size = 2
 trim_trailing_whitespace = true
+
+[*.md]
+indent_size = unset

src/components/Input/Input.jsx

@@ -129,14 +129,33 @@ class Input extends React.Component {
 }
 
 Input.propTypes = {
+  /**
+   * The HTML5 type of the input field.
+   */
   type: PropTypes.oneOf(['text', 'number', 'password']), // TODO: finish this list
+  /**
+   * The label.
+   */
   label: PropTypes.string.isRequired,
+  /**
+   * The value.
+   */
   value: PropTypes.oneOfType([
     PropTypes.string,
     PropTypes.number
   ]),
+  /**
+   * A feedback state.
+   */
   feedback: PropTypes.oneOf(['success', 'error']),
+  /**
+   * An error message.
+   */
   error: PropTypes.string,
+  /**
+   * A detailed explanation of the input expected by a form field. Must be a
+   * `Input.Helper` component.
+   */
   /* eslint-disable consistent-return */
   helper: (props, propName, componentName) => {
     const prop = props[propName]
@@ -152,8 +171,23 @@ Input.propTypes = {
     }
   },
   /* eslint-enable consistent-return */
+  /**
+   * A callback function to be invoked when the input value changes.
+   *
+   * @param {SyntheticEvent} event The react `SyntheticEvent`
+   */
   onChange: PropTypes.func,
+  /**
+   * A callback function to be invoked when the input receives focus.
+   *
+   * @param {SyntheticEvent} event The react `SyntheticEvent`
+   */
   onFocus: PropTypes.func,
+  /**
+   * A callback function to be invoked when the input loses focus.
+   *
+   * @param {SyntheticEvent} event The react `SyntheticEvent`
+   */
   onBlur: PropTypes.func
 }
 

src/components/Input/Input.md

@@ -1,21 +1,141 @@
+### Minimal Usage
+
+By default, a "text" input field will be rendered, but other types are also supported.
+
 ```
 <div>
-  <Input label="First name (default)" />
+  <Input label="First name" value="Lucy" />
 
-  <Input type="password" label="Password" value="123abc" />
-  <Input type="number" label="Age" value="32" />
+  <Input type="number" label="Age" value="35" />
+  <Input type="password" label="Tax ID" value="123456789" />
+</div>
+```
 
-  <Input label="First name (auto focus)" autoFocus />
+### Disabling an input
 
-  <Input label="First name (disabled)" disabled />
+```
+<Input label="Address" disabled />
+```
 
-  <Input label="First name (success)" feedback="success" />
-  <Input label="First name (error)" feedback="error" />
+### Showing feedback for entered values
 
-  <Input label="First name (error msg)" feedback="error" error="First name is required" />
+Use the `feedback` attribute to give the user feedback regarding their input. You can affirm that the user's input
+was correct, or highlight errors that must be corrected.
 
-  <Input label="First name (helper)" feedback="success"
-    helper={<Input.Helper>Some helper stuff</Input.Helper>}
+```
+<div>
+  <Input label="Username" value="guest12345" feedback="success" />
+  <Input label="Email" value="guest@telus.com" feedback="error"
+         error="That email is already associated with another account. Choose another one."
+  />
+</div>
+```
+
+TDS does not perform input validations, as that is an application level concern. You will need to track the value of your
+input fields and perform any required data validations either client side or server side, depending on the context.
+
+Here is an example. Enter a value into the field below, then click away to lose focus. If you enter less than 10
+characters you will receive an error message. Enter 10 or more characters to receive the success feedback.
+
+```
+initialState = {
+  value: '',
+  status: undefined,
+  errorMessage: undefined
+};
+
+const updateValue = (event) => {
+  setState({ value: event.target.value })
+}
+
+const validate = (event) => {
+  const value = event.target.value
+
+  if (value.length < 10) {
+    setState({
+      status: 'error',
+      errorMessage: 'Your name must be greater than 10 characters'
+    })
+  }
+  else {
+    setState({
+      status: 'success',
+      errorMessage: undefined
+    })
+  }
+};
+
+<div>
+  <Input label="Name" value={state.value}
+         feedback={state.status} error={state.errorMessage}
+         onChange={updateValue} onBlur={validate}
+  />
+</div>
+```
+
+### Supplying extra information
+
+Use a `helper` to offer the user a detailed explanation of the input expected by a form field. Use the `Input.Helper`
+component.
+
+```
+const passwordRequirements = (
+  <Input.Helper>
+    <Text bold>Your password must be:</Text>
+
+    <ul className="list list--compact">
+      <li className="list__item">16 characters or longer</li>
+      <li className="list__item">Not repeated from previous password</li>
+    </ul>
+  </Input.Helper>
+);
+
+<Input label="Password" type="password" helper={passwordRequirements} />
+```
+
+The helper will also receive the feedback state and will be styled accordingly in response to user input.
+
+Here is an example. Enter a value into the field below, then click away to lose focus. If you enter less than the 16
+character minimum the helper will show as an error. Enter 16 or more characters to receive the success feedback.
+
+```
+initialState = {
+  value: '',
+  status: undefined,
+  errorMessage: undefined
+}
+
+const updateValue = (event) => {
+  setState({ value: event.target.value })
+}
+
+const validate = (event) => {
+  const value = event.target.value
+
+  if (value.length < 16) {
+    setState({ status: 'error' })
+  }
+  else {
+    setState({ status: 'success' })
+  }
+}
+
+const passwordRequirements = (
+  <Input.Helper>
+    <Text bold>Your password must be:</Text>
+
+    <ul className="list list--compact">
+      <li className="list__item">16 characters or longer</li>
+      <li className="list__item">Not repeated from previous password</li>
+    </ul>
+  </Input.Helper>
+);
+
+<div>
+  <Input label="Password" type="password" id="password-2"
+         value={state.value} feedback={state.status}
+         onChange={updateValue} onBlur={validate}
+         helper={passwordRequirements}
   />
 </div>
 ```