@usds.gov/questionable

If you have questions, you have questionable content. Questionable is a USDS React component that transforms complex workflows into a simple, linear wizard.

Install

Install this package with npm or yarn:

yarn add @usds.gov/questionable

or

npm i @usds.gov/questionable

Usage

It is strongly suggested applications use the same version of USWDS that is used by @trussworks/react-uswds. A version mismatch may result in unexpected markup & CSS combinations. This project will stay current with @trussworks/react-uswds, which is often behind the USWDS by a point release or two.

You can import Questionable components using ES6 syntax:

import { Questionable } from '@usds.gov/questionable';

More detailed examples are provided in the storybook.

Organization

This project is comprised by four sub-projects (aka "packages", "workspaces"). The root of the project contains configuration and utilities for all sub-projects. Workspaces are located in /packages. Common functions such as yarn build and yarn lint can be run from the root of the project and will run on each sub-project in turn.

• /packages/questionable
• /packages/ssa-eligibility
• /packages/storybook
• /packages/tests

The Component (Questionable)

This project represents the generic web component. This is the code behind the @usds.gov@questionable package published to NPM. This project provides a generic wizard suitable for testing eligibility workflows and perhaps other point of entry flows that rely on simple state machine mechanics and can be expressed as a set of linear steps with rules governing their sequence according to branching logic.

• components: UI components used for rendering each question in the survey
• composable: Stateful classes that organize the components into a unified app
• lib: Generic helper utilities
• schema: Auto-generated JSON schema representing the data model
• state: React reducer for the aggregation of survey data
• survey: Core interfaces and classes for the data structure of the question/answer/results

Storybook

This project demonstrates the Questionable component and its subcomponents in the Storybook portfolio with working examples of the use of the plugin.

Tests

Still in-progress collection of unit tests to assert that each data point is evaluated and resolved thus validating an entire workflow is valid (or not).

ssa-eligibility

This project is a specific implementation of Questionable using live, production data. This component is bundled and published as @usds.gov/sss-eligibility.

Background

The primary deliverable is a published npm package that can be included as a dependency in other projects that use USWDS with React. In order for these components to be useful, they should follow best practices for accessible, semantic, markup; be well-tested across browsers and devices; and allow for an appropriate level of customization. We adhere to a set of development guidelines as much as possible and use automation to enforce tests, linting, and other standards.

Non-Goals

This is not meant to be a one-size-fits-all front end solution, We are starting off with the opinionated decision to cater towards projects that use the U.S. Design System 2.0, and encapsulate these specific styles and markup in React components.

Development

In the project directory, you can run:

yarn start

Runs the storybook for the components.
Open http://localhost:9009 to view it in the browser.

The page will reload if you make edits.
You will also see any lint errors in the console.

yarn test

Launches the test runner in the interactive watch mode.

yarn build

Builds the app for production to the build folder.
It correctly bundles React in production mode and optimizes the build for the best performance.

yarn deploy

Builds and deploys the app to GitHub Pages.

Maintainers

• @froehlichcr
• @TomNUSDS

Contributing

Interested in contributing? See our guidelines and dev setup here.

This repository is governed by the Contributor Covenant

Acknowledgements

• This project was bootstrapped with Create React App.
• This project uses the U.S. Web Design System (USWDS) and the @trussworks React USWDS component library.
• This project uses Luxon for date/time validation.
• The React use-wizard provides essential hooks for navigation
• JSON Schema is generated thanks to ts-json-schema-generator
• JSON to Form edit mode is powered by react-jsonschema-form

Contributors ✨

Thanks goes to these wonderful people (emoji key):

Christopher Froehlich 🐛 💻 🎨

TomNUSDS 💬 🐛 💻 👀 ⚠️

This project follows the all-contributors specification. Contributions of any kind welcome!