Update docs for definitions

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

@@ -2,27 +2,29 @@
 
 # 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 it to add the `schema` and `uiSchema` functions. The definition is a function that takes the title for that field, which is used to populate the 'ui:title' property in uiSchema:
 
 ```js
 uiSchema: {
   ...
-  monthlyWages: currencyUI('Monthly wages')
+  currency: currencyConfig.uiSchema('Currency'),
+  ...
+}
+schema: {
+  ...
+  currency: currencyConfig.schema(),
   ...
 }
 ```
@@ -45,22 +47,25 @@ 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';
 
-schema: {
-  type: 'object',
-  properties: {
-    officeLocation: {
-      type: 'string',
-      enum: [
-        'LA', 'NY', 'CH'
-      ],
-      enumNames: [
-        'Los Angeles',
-        'New York',
-        'Chicago'
-      ]
+function schema() {
+  return {
+    type: 'object'
+    properties: {
+      officeLocation: {
+        type: 'string',
+        enum: [
+          'LA', 'NY', 'CH'
+        ],
+        enumNames: [
+          'Los Angeles',
+          'New York',
+          'Chicago'
+        ]
+      }
     }
   }
 },
@@ -81,63 +86,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 this 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 this 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')
+  currentOrPastDate: currentOrPastDateConfig.uiSchema()
+},
+schema: {
+  type: 'object'
+  properties: {
+    currentOrPastDate: 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 this 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')
+  currentOrPastMonthYear: currentOrPastMonthYearConfig.uiSchema()
+},
+schema: {
+  type: 'object',
+  properties: {
+    currentOrPastMonthYear: 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 this function the 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')
+  date: dateConfig.uiSchema()
+},
+schema: {
+  type: 'object',
+  properties: {
+    date: 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')
+  dateRange: dateRangeConfig.uiSchema()
+},
+schema: {
+  type: 'object',
+  properties: {
+    dateRange: dateRangeConfig.schema()
+  }
 }
 ```
 Source: [/src/js/definitions/dateRange.js](../../src/js/definitions/dateRange.js)
@@ -150,60 +197,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 call this function with the label to be displayed 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')
+  monthYear: monthYearConfig.uiSchema()
+},
+schema: {
+  type: 'object',
+  properties: {
+    monthYear: 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.
+
+![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()
+  monthYearRange: monthYearRangeConfig.uiSchema()
+},
+schema: {
+  type: 'object',
+  properties: {
+    monthYearRange: 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 this function the 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()
+},
+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.
+
+![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
+  year: yearConfig.uiSchema()
+},
+schema: {
+  type: 'object',
+  properties: {
+    year: yearConfig.schema()
+  }
 }
 ```
 Source: [/src/js/definitions/year.js](../../src/js/definitions/year.js)