Release 1.1.0 (#216)

* Relative links will be the end of me * Relative links to definitions directory * Two more * Add links to docs and starter app, tighten up other copy * Significantly faster cc @annekainicUSDS * Add a consoleSubmit option for debugging output (#153) * Add a consoleSubmit option for debugging output Fixes #135 * Use pre-push hook to ensure build artifacts are up to date (#151) Fixes #97 * Add docs for creating a simple form (#149) * Add docs for creating a simple form * Fix link (#157) * [WIP] Add placeholder topic for available components (#154) * Add placeholder topic for available components * Additional changes after discussion with @dmethvin-gov and @fatimanoorva * Add a consoleSubmit option for debugging output (#153) * Add a consoleSubmit option for debugging output Fixes #135 * Use pre-push hook to ensure build artifacts are up to date (#151) Fixes #97 * Add docs for creating a simple form (#149) * Add docs for creating a simple form * Add some code examples and explanations on components * Better headings * Revert "Better headings" This reverts commit 66f40ae. * Apply Dave's changes again because Git is hard * Big reorg * Add placeholder topic for available components * fixes few relative links * add "contributing to this project" section include: links to code of conduct, CONTRIBUTING.md, and instructions on how to join the forms listserv * Update shortdesc * More line breaks 😩 * A bit more elaboration courtesy of Anne * Field component props and what they do * Clarify the purpose of this description once and for all * Clarify this weird point * What are "they"? * Links back to README, fix markdown * Better headings * Add these links * Add a hopefully better description of the keepInPageOnReview property * Keep consistent with "review page" * Use Anne's language, needs clarification on the second sentence * Introduction component * Form footer * Prgoress bar * Title and subtitle * Update mini-toc with new combined section header * For example * Date fields * Hidden contextual information - needs info on how to specify cc @dmethvin-gov * Radio Button and Checkbox Group - needs a code sample cc @dmethvin-gov * Password usage guidelines - what do we want to say about this? * Just kidding, the previous commit was for required fields, this one's for password * Duplicate field validation * Conditional form fields * Small reword * Add widget descriptions (#166) * Complete table with widget information * Add more description for some components * Add usage info for error messages * Edits from review * Remove password description * Make review edits * Add remaining descriptions (#174) * Add remaining descriptions * Make updates from review * Update language * Refactor from review comments * Remove one word * Rename components topic * Remove hidden contextual information cc #173 * Minor cleanup * Set the property to `true` * Create the new individual files * Move content, turn table rows into sections for linking * Move content * Add more descriptions for widgets * Rename to "Available" rather than "Common" * Edits from @dmethvin-gov * Fix link to docs (#181) * Widget links as appropriate * Add guidance on using widgets * currencyUI * This is guidance for adding widgets, the previous commit was for definitions * Combine info more coherently * Remove less specific information * Definitions for widgets and... definitions * More verbose explanation of the example * Remove AddressField per @annekainicUSDS * Improve content on the form config (#186) * Separate out advanced information on how the form config works, and create new content at a beginner level for basic information you need to know about creating a form config * Move to new customization map * Update links after move * Rename new conceptual topic * Rename map * Update main README after renames and moves * Rename again * Copy edits * Update shortdesc cc @annekainicUSDS * Remove these sections * Not "our" * Small fixes * Fix misspelling * H1 header * Fake breadcrumbs * relative link * 😩 * Once more * Two dots * Map topic readme links * Relative links for every breadcrumb * Topic links * Add folder name * This is broken * Fix links * All these commits are going to have the same commit message * Add folder * Once more * All breadcrumbs * Small link fixes here * Fix relative link? * Remove directory * Add markdown extension * Relative link * One more level * All small fixes for "Building a form" * Small updates for "Customizing the library" * Add react * Lots of hardcoded links * Remove containing directory * Line link doesn't work * Not plural * Markdown extension * MARKDOWN EXTENSION * Fix the example for conditionally hiding fields (#183) This is simplified from the big form I'm building. * More detail on use of definitions (#188) * [WIP] More detail on use of definitions * Fix imports; further updates * Add autosuggest section * Add missing expandable group styles (#192) * Add basic tutorial (#194) * Add basic tutorial * Fix language * Add Dave's suggestions * Add Sheri's suggestions * More edits from Sheri * Edit images * Small edits * No apostrophe (#197) * Don't show back button on first page (#195) Routes in `pageList` mocks now reflect the way they really look, using a leading slash. Also cleans up FormPage/ReviewPage unit tests which had remnants of vets.gov user login. Fixes #177 * TOC at the top of the tutorial * Minor cleanup * Add readme links * Minor cleanup of review section * Add breadcrumbs * Add content to question issue template * Clarify a couple of questions * Typos * Do not filter out properties on inactive pages that also appear on active pages (#155) * Add functionality to not filter out properties on inactive pages that also appear on active pages Refactor Refactor Remove duplicate properties from array Return properties * Write unit tests for new functionality * Refactor from code review * Change _.uniq to only be called once * Run build on latest changes * Clean up and dry out the FormPage unit tests (#202) * Update node-sass to remove the node-gyp vuln (#213) * 1.1.0 * Fix merge conflict
usds · Aug 20, 2018 · b3dcc5e · b3dcc5e
1 parent fb62c2e
commit b3dcc5e
Show file tree

Hide file tree

Showing 42 changed files with 4,260 additions and 3,266 deletions.
diff --git a/.github/ISSUE_TEMPLATE/Questions.md b/.github/ISSUE_TEMPLATE/Questions.md
@@ -4,4 +4,13 @@ about: Ask questions about the library
 
 ---
 
+Learn more about how your form project could leverage the US Forms System. To help all of us use our time most efficiently:
 
+- **What is the scope of your project?**
+- **What are you using/planning on using to build your form? Provide a link to a repository if you have one!**
+- **How complex is your form?**
+- **Have you reviewed the [US Forms System Documentation](https://github.com/usds/us-forms-system/blob/master/docs/README.md)?**
+- **Have you tried prototyping your form with the US Forms System?**
+- **Are you/will you be working with a designer or information architect?**
+
+*If you have another question, delete the text above and ask here!*
diff --git a/README.md b/README.md
@@ -1,13 +1,32 @@
 # U.S. Forms System
 
+The US Forms System is an open source library and set of guiding principles for building complex web-based forms using [React](https://reactjs.org), the [JSON Schema standard](http://json-schema.org/), and the [US Web Design System](https://designsystem.digital.gov/).
+
 ***THIS IS A WORK IN PROGRESS.***
 
-Modelled after the [US Web Design System](https://designsystem.digital.gov/), this project creates an open source code library and set of guiding principles for building complex web-based forms significantly faster than existing methods, using best practices in user experience and data collection, validation, and transmission.
+### About this project
+
+Inspired by Mozilla's [react-jsonschema-form](https://github.com/mozilla-services/react-jsonschema-form) library, the US Forms System is specifically intended for consistently styled governmental web-based forms. This library enables you to describe form fields in a JSON Schema configuration file, which then renders the backing React components necessary to build your form. You'll build forms significantly faster than existing methods, and benefit from the US Web Design System's best practices in user experience and data collection, validation, and transmission.
+
+### Using the library
+
+For information about setting up and using the US Forms System, see the *[US Forms System Documentation](./docs/README.md)*.
+
+Additionally, the [US Forms System Starter App](https://github.com/usds/us-forms-system-starter-app) provides the basic files and configuration needed to get started building a form using the US Forms System.
+
+### Contributing to this project:
+
+Please read our [Code of Conduct](https://github.com/usds/us-forms-system/blob/master/CODE_OF_CONDUCT.md) and [CONTRIBUTING.md](https://github.com/usds/us-forms-system/blob/master/CONTRIBUTING.md) for more details.
+
+#### Join the contributor mailing list: 
+
+To receive regular updates about this project, please join our mailing list by sending an email to forms-subscribe-request@listserv.gsa.gov. 
 
-This library enables you to build web-based forms using [React](https://reactjs.org) and the [JSON Schema standard](http://json-schema.org/). Instead of building and configuring your React components from scratch, use this library and guidance to describe the form fields in a JSON Schema configuration file, which will then render the backing React components necessary to build your form.
+#### Contact the project team:
 
-Originally inspired by Mozilla's [react-jsonschema-form](https://github.com/mozilla-services/react-jsonschema-form) library, we've created a version specific build web-based forms for government, styled using the [U.S. Web Design System](https://designsystem.digital.gov/) for a consistent look and feel across government.
+If you want to directly contact the project team, you can send your questions to forms@lists.usds.gov. 
 
----
+### More project artifacts
 
-We'll be documenting our roadmap, research, and process in [the wiki](https://github.com/usds/us-forms-system/wiki) as work on getting the code library ready. Feel free to look around [our wiki](https://github.com/usds/us-forms-system/wiki) and [our project board](https://github.com/orgs/usds/projects/3) if you want to follow along with our progress. That's also where developer documentation and best practices guidance for forms design and development will be found as it comes together.
+- Roadmap, research, and process: [US Forms System Wiki](https://github.com/usds/us-forms-system/wiki)
+- Project progress: [US Forms System Project Board](https://github.com/orgs/usds/projects/3)
diff --git a/docs/README.md b/docs/README.md
@@ -1,11 +1,18 @@
 # US Forms System Documentation
 
-- [Getting started with the Forms System Library](getting-started/README.md)
+- [Getting started with the US Forms System](getting-started/README.md)
   - [Tools for getting started with the US Forms System](getting-started/tools-for-getting-started-with-the-us-forms-system.md)
   - [Creating a new application with the US Forms System Starter App](getting-started/creating-a-new-application-with-the-us-forms-system-starter-app.md)
+  - [Tutorial: Building a simple address form](getting-started/tutorial.md)
   - [Installing the US Forms System in an existing application](getting-started/installing-the-us-forms-system-in-an-existing-application.md)
 - [Building a form](building-a-form/README.md)
-  - [About the US Forms System library](building-a-form/about-the-us-forms-system-library.md)
+  - [About the `schema` and `uiSchema` objects](building-a-form/about-the-schema-and-uischema-objects.md)
+  - [Quick Start: Example `form.js` file](building-a-form/quick-start-example-formjs-file.md)
   - [Creating a form config file](building-a-form/creating-a-form-config-file.md)
-  - [Adding widgets and definitions](building-a-form/adding-widgets-and-definitions.md)
+  - [Available form features and usage guidelines](building-a-form/available-form-features-and-usage-guidelines.md)
+  - [Available widgets](building-a-form/available-widgets.md)
+  - [Common definitions](building-a-form/common-definitions.md)
   - [Common patterns for building forms](building-a-form/common-patterns-for-building-forms.md)
+- [Customizing the library](customizing-the-library/README.md)
+  - [About the React component hierarchy](customizing-the-library/about-the-react-component-hierarchy.md)
+  - [Creating custom fields and widgets](customizing-the-library/creating-custom-fields-and-widgets.md)
diff --git a/docs/building-a-form/README.md b/docs/building-a-form/README.md
@@ -1,19 +1,33 @@
+:book: [*US Forms System Documentation*](../README.md)
+
 # Building a form
 
-### [About the US Forms System library](about-the-us-forms-system-library.md)
+### [About the `schema` and `uiSchema` objects](about-the-schema-and-uischema-objects.md)
+
+The US Forms System lets you build web-based forms using the JSON Schema standard for form data and React for the form UI. The form data and UI are represented by `schema` and `uiSchema` objects, respectively, which are included in the form configuration file.
 
-The US Forms System lets you build web-based forms using React and the JSON Schema standard.
+### [Quick Start: Example `form.js` file](quick-start-example-formjs-file.md)
+
+Use this example `form.js` file to build a basic form.
 
 ### [Creating a form config file](creating-a-form-config-file.md)
 
 Your form is generated from a `form.js` file, along with a few other key configuration files.
 
-### [Adding widgets and definitions](adding-widgets-and-definitions.md)
+### [Available form features and usage guidelines](available-form-features-and-usage-guidelines.md)
+
+These form features are available in the US Forms System library. We've provided information about how to implement them in your form.
+
+### [Available widgets](available-widgets.md)
+
+Widgets are React components that return specific HTML form elements. Set these widgets in a config file while building your form.
+
+### [Common definitions](common-definitions.md)
 
-There are many common fields and widgets you can use to build forms. There are common types of definitions: `schema`/`uiSchema` objects and functions that return `schema`/`uiSchema` objects.
+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.
 
 ### [Common patterns for building forms](common-patterns-for-building-forms.md)
 
 Some forms require custom validation, styles, or conditional information based on user input. Use these patterns to address those needs.
 
-[Back to *US Forms System Documentation*](docs/README.md)
+[Back to *US Forms System Documentation*](../README.md)
diff --git a/docs/building-a-form/about-the-schema-and-uischema-objects.md b/docs/building-a-form/about-the-schema-and-uischema-objects.md
@@ -0,0 +1,244 @@
+:book: [*US Forms System Documentation*](../README.md) :arrow_right: [*Building a Form*](./README.md)
+
+# About the `schema` and `uiSchema` objects
+
+The US Forms System lets you build web-based forms using the JSON Schema standard for form data and React for the form UI. The form data and UI are represented by `schema` and `uiSchema` objects, respectively, which are included in the form configuration file.
+
+- [Understanding the `schema` object](#understanding-the-schema-object)
+  - [Describing object fields and arrays](#describing-object-fields-and-arrays)
+- [Understanding the `uiSchema` object](#understanding-the-uischema-object)
+  - [Configuring `uiSchema` using rjsf options](#configuring-uischema-using-rjsf-options)
+  - [Configuring `uiSchema` using US Form System options](#configuring-uischema-using-us-forms-system-options)
+
+### Understanding the `schema` object
+
+The JSON Schema standard describes the allowed shape of JSON objects. Using a `schema` object, a JSON schema provides information about structured JSON data. For more information about the JSON Schema Standard, see [Understanding JSON Schema](https://spacetelescope.github.io/understanding-json-schema/).
+
+For JSON Schema validator libraries, the US Forms System uses [ajv](https://www.npmjs.com/package/ajv) for unit tests and [jsonschema](https://www.npmjs.com/package/jsonschema) in the us-forms-system code.
+
+##### Describing object fields and arrays
+
+This example describes a JSON document that is an object with one property called `myField`, which is a number, meaning `{ myField: 2 }` would be valid:
+
+```
+{
+  type: 'object',
+  properties: {
+    myField: {
+      type: 'number'
+    }
+  }
+}
+```
+
+However, `{}` is also valid. To require a property in an object, use the `required` property, which takes an array of property names passed as strings. As in this example, `required` is always on the object that contains the field, not the field itself:
+
+```
+{
+  type: 'object',
+  required: ['myField'],
+  properties: {
+    myField: {
+      type: 'number'
+    }
+  }
+}
+```
+
+Arrays work similarly to objects. This example describes an array of boolean values: `[true, false, true]`. Items can be an object schema or any other type of schema as well:
+
+```
+{
+  type: 'array',
+  items: {
+    type: 'boolean'
+  }
+}
+```
+
+### Understanding the `uiSchema` object
+
+The `uiSchema` object was introduced by [react-jsonschema-form](https://github.com/mozilla-services/react-jsonschema-form#react-jsonschema-form), or *rjsf*, as a means of describing how a form page should be rendered from a `schema`. To generate a form, react-jsonschema-form steps through the schema depth and renders different React components based on the type of data each property in the schema represents. In the US Forms System library, `uiSchema` follows the format described in the [react-jsonschema-form documentation](https://github.com/mozilla-services/react-jsonschema-form#the-uischema-object), with some custom us-forms-system additions. The `schema` and `uiSchema` objects should have a similar structure, with the same fields organized in the same way with these exceptions:
+
+- `uiSchema` doesn't need to contain all the fields found in the `schema` object.
+- `uiSchema` doesn't need a `properties` object for sub-fields.
+
+For example, given this schema:
+
+```js
+{
+  type: 'object',
+  properties: {
+    field1: {
+      type: 'string'
+    }
+  }
+}
+```
+
+The matching `uiSchema` would be:
+
+```js
+{
+  'ui:title': 'My form',
+  field1: {
+    'ui:title': 'My field'
+  }
+}
+```
+
+For array fields, you must specify an `items` object that contains the fields for each row in the array in the `uiSchema` object:
+
+```js
+{
+  'ui:title': 'My form',
+  toursOfDuty: {
+    items: {
+      branchName: {
+        'ui:title': 'Branch'
+      }
+    }
+  }
+}
+```
+
+##### Configuring `uiSchema` using rjsf options
+
+If you're not already familiar with the rjsf uiSchema options, see the [rjsf library documentation](https://github.com/mozilla-services/react-jsonschema-form#the-uischema-object). Some commonly used options include:
+
+- [ui:order](https://github.com/mozilla-services/react-jsonschema-form#object-fields-ordering): An array of field names in the order in which they should appear.
+- [ui:widget](https://github.com/mozilla-services/react-jsonschema-form#alternative-widgets): The name of an alternative widget to use for the field, for example, a custom widget called `yesNo`.
+- [ui:field](https://github.com/mozilla-services/react-jsonschema-form#custom-field-components): The name of a custom field.
+- [classNames](https://github.com/mozilla-services/react-jsonschema-form#custom-css-class-names): The class names to put on the component.
+
+##### Configuring `uiSchema` using US Forms System options
+
+The us-forms-system code includes additional `uiSchema` functionality not found in the rjsf library.
+
+```js
+{
+  // Used instead of the `title` property in the JSON Schema.
+  'ui:title': '',
+  // It can also be a component, which passes the current form data as a property.
+  'ui:title': ({ formData }) => <legend>{`A ${formData.thing} title`}</legend>,
+
+  // Used instead of the `description` property in the JSON Schema. This can be a string
+  // or a React component, and is normally used on object fields in the schema to provide
+  // description text or HTML before a block of fields.
+  'ui:description': '' || DescriptionComponent,
+
+  // Customizes the field or widget you're using.
+  'ui:field': '' || FieldComponent,
+  'ui:widget': '' || WidgetComponent,
+
+  // Renders string fields on the review page. Always used when you specify a custom widget
+  // component. Can also be used with regular widgets.
+  'ui:reviewWidget': WidgetComponent,
+
+  // Provides a function to make a field conditionally required. The data in the whole form,
+  // with no page breaks, is the only parameter. Don't make a field required in the JSON
+  // schema and in addition to using `ui:required` on that field. The index argument is
+  // provided if you use `ui:required` on data inside an array.
+  'ui:required': function (formData, index) {
+    return true || false;
+  },
+
+  // An array of validation functions or objects that you can use to add validation that's
+  // not possible through JSON Schema. See below for the properties passed to the validation
+  // functions and how to use them.
+  'ui:validations': [
+    /**
+     * Note the difference between the three data parameters:
+     *
+     * @param {any} fieldData The data for the current field being validated
+     * @param {object} formData The data for all the fields in every page
+     */
+    function (errors, fieldData, formData, fieldSchema, errorMessages) {
+      errors.addError('My error');
+    },
+    {
+      validator: (errors, fieldData, formData, fieldSchema, errorMessages, options) => {
+        errors.addError('My other error');
+      },
+      options: {}
+    }
+  ],
+
+  // An object with field-specific error messages. Structured by error name (from JSON Schema
+  // error types). This is passed to custom validations in `ui:validations` in order to allow
+  // configurable error messages in a validator.
+  'ui:errorMessages': {
+    'pattern': 'Please provide a value in the right format'
+  },
+  'ui:options': {
+
+    // An map of enum values to labels that are shown by the select and radio widgets.
+    labels: {
+      chapter30: 'A readable description (Chapter 30)'
+    },
+
+    // A map of values to a component, text, or JSX
+    // (https://reactjs.org/docs/introducing-jsx.html). If your field is a radio widget, the
+    // content here is shown underneath the radio button for that value when it's selected.
+    nestedContent: {
+      'value': <p>Some text</p>
+    },
+
+    // A string of class names that are added to the widget for the current field.
+    // `widgetClassNames` is similar to the default `classNames` property, but it puts the
+    // class names on the input/select/etc element itself, rather than a surrounding `div`.
+    widgetClassNames: '',
+
+    // For array fields, this component is shown when the item in the array is rendered as
+    // read-only on a page that is not a review page.
+    viewField: RowViewComponent,
+
+    // To show a field only when another field is true, set this option to the property name.
+    // It wraps the fields with an ExpandingGroup component using the `expandUnder` field as
+    // the first question.
+    expandUnder: '',
+
+    // To match to a specific value, use the `expandUnderCondition` option to specify the
+    // value that the `expandUnder` field's data should equal.
+    expandUnderCondition: 'someValue',
+    // `expandUnderCondition` can also be a function that receives the data from the
+    // `expandUnder` field as an argument.
+    expandUnderCondition: (field) => field === 'someValue' || field === 'someOtherValue',
+
+    // When using the expandUnder option, you can set `expandUnderClassNames` on the field
+    // specified by `expandUnder` and it will add classes to the `div` that wraps all of the
+    // fields when they're expanded. See cookbook for an example use case.
+    expandUnderClassNames: '',
+
+    // Hides the specified field on the review page.
+    hideOnReview: true || false,
+
+    // Hides the specified field on the review page when the field value is `false`.
+    hideOnReviewIfFalse: true || false
+
+    // A function that conditionally hides fields in the form. `hideIf` provides the `index`
+    // argument when you use `ui:required` on data inside an array.
+    hideIf: function (formData, index) {
+      return true || false;
+    }
+
+    // A function that conditionally replaces the current field's schema. `updateSchema`
+    // provides the `index` argument when you use `ui:required` on data inside an array.
+    updateSchema: function (formData, schema, uiSchema, index, pathToCurrentData) {
+      // This function returns an object with the properties you want to update. Instead of
+      // replacing the existing schema, it updates the individual properties.
+      return {
+        type: 'string'
+      };
+    },
+
+    // By default, array fields that are displayed on a single page in a form, such as
+    // information for multiple dependents, are displayed in a separate section on the
+    // review page. To keep the information in a single section on a review page, set
+    // this property to `true`.
+    keepInPageOnReview: true
+  }
+}
+```
+
+[Back to *Building a Form*](./README.md)