Update docs for definitions (#236)

* First pass at updating definitions and code samples

* Swap out schema and uiSchema

* Add and reference images for the rendered definition fields

* Update descriptions

* Complete the currency fields

* Incorporate feedback from @annekainicUSDS and @dmethvin-gov

I added some example labels in the `uiSchemas` - let me know what you think.

* Fix bad js, code sample cc @annekainicUSDS

* Small fix from Anne

docs/building-a-form/common-definitions.md

@@ -2,27 +2,31 @@
 
 # Common definitions
 
-Definitions are pieces of the form config that can be dropped in to represent specific types of questions. Most often used in `uiSchema`, definitions include features such as label text, validation functions, error messages, and rules for which widget to render.
+Definitions, located in [/src/js/definitions](../../src/js/definitions), are pieces of the form config that can be dropped in to represent specific types of questions. They include features such as label text, validation functions, error messages, and rules for which widget to render.
 
-There are common types of definitions: `schema`/`uiSchema` objects and functions that return `schema`/`uiSchema` objects. For the function versions, there is documentation within the fields for the parameters. Definitions are located in [/src/js/definitions](../../src/js/definitions).
-
-- Simple definitions are provided as `schema` and `uiSchema` objects that you can import and overwrite to customize.
-- More complex definitions are functions that require certain parameters.
+Definitions export `schema` and `uiSchema` objects, which are functions that require certain parameters.
 
 ### Using definitions
 
 To use a definition, import it near the top of the file you want to reference it in:
 
 ```js
-import currencyUI from 'us-forms-system/lib/js/definitions/currency';
+import { currencyConfig } from 'us-forms-system/lib/js/definitions/currency';
 ```
 
-Then, call it to add all the `uiSchema` definitions. In this example, the definition is a function that takes the title for that field, which is used to populate the 'ui:title' property in uiSchema:
+Then, call the `schema` and `uiSchema` functions on the definition where needed.
+
+Functions may take arguments to configure how the definitions are used. In this example, the `uiSchema` for currency takes an optional argument for the title of the field. To set the title to "Currency", pass that as a string to the `uiSchema` function:
 
 ```js
 uiSchema: {
   ...
-  monthlyWages: currencyUI('Monthly wages')
+  currency: currencyConfig.uiSchema('Currency'),
+  ...
+}
+schema: {
+  ...
+  currency: currencyConfig.schema(),
   ...
 }
 ```
@@ -45,8 +49,9 @@ Available definitions are:
 ### Autosuggest
 
 A common type-ahead widget that lets a user type in values and narrow down a longer list of options. It is most commonly used with an `enum` of the available options as shown here. Define the uiSchema by calling the function that you import. You can pass an object with additional uiSchema properties.
+
 ```js
-import { uiSchema as autosuggestUI } from 'us-forms-system/lib/js/definitions/autosuggest';
+import { autosuggestConfig } from 'us-forms-system/lib/js/definitions/autosuggest';
 
 schema: {
   type: 'object',
@@ -65,7 +70,8 @@ schema: {
   }
 },
 uiSchema: {
-  officeLocation: autosuggestUI(
+  uiSchema: {
+  officeLocation: autosuggestConfig.uiSchema(
     'Preferred Office Location',  // field title
     null,         // Promise to get options (optional)
     {             // Additional uiSchema options
@@ -81,63 +87,105 @@ Source: [/src/js/definitions/autosuggest.js](../../src/js/definitions/autosugges
 
 ### Currency
 
-Formats and validates a US currency field. The display includes a leading `$` character. Call this exported function and pass it the label to be used on the field.
+Formats and validates a US currency field that includes a leading `$` character. You can pass the `uiSchema` function a label to be used on the field.
+
+![Two currency fields, one with the field selected](../images/definitions/currency.png)
 
 ```js
-import currencyUI from 'us-forms-system/lib/js/definitions/currency';
+import { currencyConfig } from 'us-forms-system/lib/js/definitions/currency';
 
 uiSchema: {
-  payments: currencyUI('Total Payments')
+  currency: currencyConfig.uiSchema('Currency')
+},
+schema: {
+  type: 'object',
+  properties: {
+    currency: currencyConfig.schema()
+  }
 }
 ```
 Source: [/src/js/definitions/currency.js](../../src/js/definitions/currency.js)
 
 ### Current or past dates
 
-The common date field with current or past validation set (i.e., dates in the future are not valid). Call this exported function and pass it the label to be used on the field.
+The common date field with validation warning that dates in the past or future are not valid. You can pass the `uiSchema` function a label to be used on the field. Dates must be on or before January 1, 1900.
+
+![Four date fields, with and without focus, with an invalid year, and with valid data](../images/definitions/currentOrPastDate.png)
 
 ```js
-import currentOrPastDateUI from 'us-forms-system/lib/js/definitions/currentOrPastDate';
+import { currentOrPastDateConfig } from 'us-forms-system/lib/js/definitions/currentOrPastDate';
 
 uiSchema: {
-  birthdate: currentOrPastDate('Date of Birth')
+  birthdate: currentOrPastDateConfig.uiSchema('Date of Birth')
+},
+schema: {
+  type: 'object'
+  properties: {
+    birthdate: currentOrPastDateConfig.schema()
+  }
 }
 ```
 Source: [/src/js/definitions/currentOrPastDate.js](../../src/js/definitions/currentOrPastDate.js)
 
 ### Current or past month/year
 
-The common date field without the day field and with current or past validation set (i.e., dates in the future are not valid). Call this exported function and pass it the label to be used on the field.
+The common date field with only month and year fields and with validation warning that dates in the past or future are not valid. You can pass the `uiSchema` function a label to be used on the field. Dates must be on or before January 1, 1900.
+
+![Three date fields, one empty, one with invalid data, and one with valid data](../images/definitions/currentOrPastMonthYear.png)
 
 ```js
-import currentOrPastMonthYear from 'us-forms-system/lib/js/definitions/currentOrPastMonthYear';
+import { currentOrPastMonthYearConfig } from 'us-forms-system/lib/js/definitions/currentOrPastMonthYear';
 
 uiSchema: {
-  lastContact: currentOrPastMonthYear('Last Contact')
+  lastContact: currentOrPastMonthYearConfig.uiSchema('Last Contact')
+},
+schema: {
+  type: 'object',
+  properties: {
+    lastContact: currentOrPastMonthYearConfig.schema()
+  }
 }
 ```
 Source:  [/src/js/definitions/currentOrPastMonthYear.js](../../src/js/definitions/currentOrPastMonthYear.js)
 
 ### Date
 
-The common date field with basic date validation. Call this exported function and pass it the label to be used on the field.
+The common date field with basic date validation. You can pass the `uiSchema` function a label to be used on the field. Dates must be on or before January 1, 1900.
+
+![Two date fields, one with an invalid year](../images/definitions/date.png)
+
 ```js
-import dateUI from 'us-forms-system/lib/js/definitions/date';
+import { dateConfig } from 'us-forms-system/lib/js/definitions/date';
 
 uiSchema: {
-  startDate: dateUI('startDate')
+  startDate: dateConfig.uiSchema('Start Date')
+},
+schema: {
+  type: 'object',
+  properties: {
+    startDate: dateConfig.schema()
+  }
 }
 ```
 Source: [/src/js/definitions/date.js](../../src/js/definitions/date.js)
 
 ### Date range
 
-Two common date fields with validation to ensure they form a valid range. Call this exported function.
+Two common date fields with validation to ensure they form a valid range. Dates must be on or before January 1, 1900.
+
+![Two date fields, signifying a date range](../images/definitions/dateRange.png)
+
 ```js
-import dateRangeUI from 'us-forms-system/lib/js/definitions/dateRange';
+import { dateRangeConfig } from 'us-forms-system/lib/js/definitions/dateRange';
 
 uiSchema: {
-  servicePeriod: dateRangeUI('servicePeriod')
+  servicePeriod: dateRangeConfig.uiSchema('Period of Service')
+},
+schema: {
+  type: 'object',
+  properties: {
+    servicePeriod: dateRangeConfig.schema()
+  }
 }
 ```
 Source: [/src/js/definitions/dateRange.js](../../src/js/definitions/dateRange.js)
@@ -150,60 +198,105 @@ Source: [/src/js/definitions/file.js](../../src/js/definitions/file.js)
 
 ### Month/year
 
-The common date field, excluding day field, with basic validation. Call this exported function with the label to be displayed on the field.
+The common date field, excluding day field, with basic validation. Dates must be on or before January 1, 1900. You can pass the `uiSchema` function a label to be used on the field.
+
+![Two date fields, one unfilled and one filled with a date](../images/definitions/date.png)
+
 ```js
-import monthYearUI from 'us-forms-system/lib/js/definitions/monthYear';
+import { monthYearConfig } from 'us-forms-system/lib/js/definitions/monthYear';
 
 uiSchema: {
-  serviceStart: monthYearUI('Month/Year Service Started')
+  serviceStart: monthYearConfig.uiSchema('Month and Year Service Started')
+},
+schema: {
+  type: 'object',
+  properties: {
+    serviceStart: monthYearConfig.schema()
+  }
 }
 ```
 Source: [/src/js/definitions/monthYear.js](../../src/js/definitions/monthYear.js)
 
 ### Month/year range
 
-Two common date fields, excluding day field, with validation to ensure the dates form a valid range. Similar to the `Date range` above but without the days. Call this exported function.
+Two common date fields, excluding day field, with validation to ensure the dates form a valid range. Dates must be on or before January 1, 1900. You can pass the `uiSchema` function a label to be used on the field.
+
+![Four range fields, one empty, one with valid data, and two with invalid data](../images/definitions/monthYearRange.png)
+
 ```js
-import monthYearRangeUI from 'us-forms-system/lib/js/definitions/monthYearRange';
+import { monthYearRangeConfig } from 'us-forms-system/lib/js/definitions/monthYearRange';
 
 uiSchema: {
-  serviceStart: monthYearRangeUI()
+  serviceRange: monthYearRangeConfig.uiSchema('Period of Service')
+},
+schema: {
+  type: 'object',
+  properties: {
+    serviceRange: monthYearRangeConfig.schema()
+  }
 }
 ```
 Source: [/src/js/definitions/monthYearRange.js](../../src/js/definitions/monthYearRange.js)
 
 ### Phone
 
-A phone number with basic validation. Call this exported function, optionally passing it the label for the field (the default is "Phone").
+A phone number with basic validation. You can pass the `uiSchema` function a label to be used on the field.
+
+![A phone field without focus, with focus, invalid data, and valid data](../images/definitions/phone.png)
+
 ```js
-import phoneUI from 'us-forms-system/lib/js/definitions/phone';
+import { phoneConfig } from 'us-forms-system/lib/js/definitions/phone';
 
 uiSchema: {
-  homePhone: phoneUI('Home Phone')
+  phone: phoneConfig.uiSchema('Home Phone')
+},
+schema: {
+  type: 'object',
+  properties: {
+    phone: phoneConfig.schema()
+  }
 }
 ```
 Source: [/src/js/definitions/phone.js](../../src/js/definitions/phone.js)
 
 ### Social Security Number
 
-A social security number with default label text and validation. This is an object.
+A US social security number field with validation.
+
+![Three social security fields, one unselected, one selected, and one with invalid data](../images/definitions/ssn.png)
+
 ```js
-import ssnUI from 'us-forms-system/lib/js/definitions/ssn';
+import { ssnConfig } from 'us-forms-system/lib/js/definitions/ssn';
 
 uiSchema: {
-  ssn: ssnUI
+  ssn: ssnConfig.uiSchema()
+},
+schema: {
+  type: 'object',
+  properties: {
+    ssn: ssnConfig.schema()
+  }
 }
 ```
 Source: [/src/js/definitions/ssn.js](../../src/js/definitions/ssn.js)
 
 ### Year
 
-A text field that validates the current or a past year. This is an object.
+A text field that validates the current or a past year. Dates must be on or before January 1, 1900. You can pass the `uiSchema` function a label to be used on the field.
+
+![Four year fields, selected, unselected, and with valid and invalid data](../images/definitions/year.png)
+
 ```js
-import yearUI from 'us-forms-system/lib/js/definitions/year';
+import { yearConfig } from 'us-forms-system/lib/js/definitions/year';
 
 uiSchema: {
-  yearBorn: yearUI
+  taxYear: yearConfig.uiSchema('Year Filed')
+},
+schema: {
+  type: 'object',
+  properties: {
+    taxYear: yearConfig.schema()
+  }
 }
 ```
 Source: [/src/js/definitions/year.js](../../src/js/definitions/year.js)