Now that we have a public Storybook page, we should add some custom theming, additional info and better organization for our components.

Things we might want to add include:

• Display ReactUSWDS version and USWDS version somewhere
• Truss-specific branding/logo
• Links back to Github repo, Truss site?
• Custom theme fonts/colors?
• Some static pages to display documentation, introduction, other info

Please add your own ideas/thoughts!

References:

• https://storybook.js.org/docs/configurations/theming/
• https://medium.com/storybookjs/how-design-systems-use-storybook-2ed735ad07a9

https://designsystem.digital.gov/components/card/

Since USWDS recommends using FontAwesome for icons (https://designsystem.digital.gov/components/icons/), it doesn't seem necessary to create an Icon component. It might make more sense to officially recommend using https://github.com/FortAwesome/react-fontawesome and provide documentation on how to use it in your project.

The GovBanner component markup has changed in the latest version of USWDS. Update the component so it uses the most up-to-date markup defined by USWDS (https://designsystem.digital.gov/components/banner/).

Add Validation component: https://designsystem.digital.gov/components/form-controls/#validation

• We can use/extend the existing Alert component
• Probably add a new component <ValidationChecklist />
• Validation checking will depend on what forms solution the application is using. For now I'd recommend this component accept a prop that indicates which validations have been met somehow.
• Stories should showcase validation working with react-uswds Form

Create a Github workflow that:

• Every time a PR is merged to develop, publish to the next tag on npm (if tests pass)

This will require storing an npm token in GH. Probably a job for @trussworks-infra

Right now, the Grid components (Grid, GridContainer) render a div. They should be modified to accept an optional Component prop (probably of type ReactNode) in case the user wants to render some other element (such as a ul). They should still default to div if no Component props is defined.

Start a conversation and determine logistics for how we want to handle a security rotation. This function should support:

• Team members from Truss can opt-in to be part of the "on call" rotation
• On-call shifts should have a pre-determined length of time
• Add description of responsibilities while on-call -- primarily paying attention to any security alerts that come in from Github, making sure urgent PRs are being attended to, etc. The on-call person may not be required to resolve issues themselves, but instead make sure they are not being dropped or ignored.

Write some more documentation specifically around how to write new components. Include guidance around:

• How to decide whether to add a new component
• Once decided, make sure it is abstract enough for general usage but also fits in the USWDS
• Make sure props type inherits the HTML element attributes
• Make sure to add corresponding stories and tests
• Make sure to export the new component from the package entrypoint (index.ts)

Add a PR template.

Several builds in CircleCi have failed due to the following error:

ENOMEM: not enough memory, read

This is not a consistent issue, but crops up enough to need to be addressed. For reference: https://circleci.com/gh/trussworks/react-uswds/316

Combo Box

A combo box helps users select an item from a large list of options.

Proposed Requirements

Props = {
  id: string,
  name: string
  children: React.ReactNode
  options: [],
  onSelect: (option) => void,
  defaultValue? : string
  required?: boolean
} & JSX.IntrinsicElements['select']

• base element is <select>
• ability clear selections or already typed text
• See uswds combo box js

Other Considerations

Does your feature request relate to a specific USWDS feature?
No

Is your feature request related to a problem? Please describe.
This feature will demonstrate real-life usage of ReactUSWDS components and provide another avenue for testing.

Describe the solution you'd like
Add the following to the /example application:

• router
• basic navigation & page UI

Additional context
Initial discussion: #77

Does your feature request relate to a specific USWDS feature?
No

Is your feature request related to a problem? Please describe.
This is an optimization of the lib bundle size which can improve performance

Describe the solution you'd like
Investigate generating pkg.module with a bundler tool (e.g. rollup, esbuild, or adapt existing webpack). Create a PR implementing the suggested approach with a brief rationale.

Describe alternatives you've considered
We can choose to do nothing.

Additional context
Port from initial roadmap -- motivation behind this is to optimize the library exports for better performance & modern JS applications.

• https://github.com/rollup/rollup/wiki/pkg.module
• https://stackoverflow.com/questions/41289200/output-an-es-module-using-webpack

Character Count

Character count helps users know how much text they can enter when there is a limit on the number of characters.

Proposed Requirements

Props = {
  id: string,
  name: string
  maxLength: number
  defaultValue?: string
  isTextArea?: boolean
  getCharacterCount?: (text: string) => number
  getCharacterCountMessage? : (remainingCount: number) => string
  inputRef: InputRef
} 

• Supports both <input type="text" /> and <textarea>
• Character limit is determined by the maxLength. It does not limit the actual input field length, allowing the user to exceed the soft cap.
• Input is invalid when maxLength is exceeded
• getCharacterCount prop allows custom logic for character count (that accounts for emojis, ligatures, etc). It defaults to a function that uses .length
• getMessage returns custom hint messages to display. It defaults to a function that returns English messages.
• Component state tracks the input text length and validity. The consumer can pass in props that calculate the character count and determine which messages to display.

Other Considerations

• Account for no-JavaScript environments. Add a default message in the message element that refers to the character limit. This will appear in instances when JavaScript does not load.
• Instead of using <Label /> inside this component use render props as per #217 (review)

Add a basic example application that uses this library and demonstrates how to use it. This can also be used in addition to Storybook for developing/testing new components. It can also be used if we want to set up end-to-end integration & a11y testing.

Acceptance criteria:

• boilerplate create-react-app is set up in a subdirectory of this project (/example)
• local react-uswds is a dependency of the example app

Describe the bug
The :hover styles on primary links in Footer(#78) do not match styles applied in the USWDS design system docs. Specifically the blue color that comes from the typeset-link mixin is not being applied in our code.

Expected behavior
We want our storybook examples to look like the examples on uswds design system docs. In this case, all links should be blue when hovered.

Additional context

• Look more into how $theme-global-link-styles is used we probably need to turn this on in our repo.
• Also, revisit how we bring in uswds styles our storybook config. We should probably be importing .scss instead of instead of as compiled .css.
• @suzubara knows more about all of this

Add Range slider component: https://designsystem.digital.gov/components/form-controls/#range

Right now the Search component renders a label & input with hardcoded id and name attributes (search-field and search). It should be modified to accept props to define these instead, since the user will likely need full control over id and name attributes.

As of 2019-10-21, Node 12 is in active LTS, which means it should be safe for us to update this library to use Node 12 for development.

First, ensure that all dependencies support and function in v12 without issues. You can do this by checking the releases for all dependencies, updating to the latest stable versions, and making sure all tests and builds pass in this project.

Once verified everything looks good, the new Node version should be specified in:

• package.json
• docs/contributing.md
• .circleci/config.yml

Add Search component: https://designsystem.digital.gov/components/search/

Support options: default, big, small

Right now changelog updates and releases are very manual. If we can decide on some ways to standardize our workflow, hopefully we can streamline this process in the interest of releasing frequently without friction. Ideas may include using https://www.conventionalcommits.org/en/v1.0.0/ and auto-generating changelog items from commit messages. This is a new area for me so I am actively seeking input and ideas. Also if anyone is interested in taking this on, playing around with some ideas and figuring out what might be a good workflow, please feel free!

Add Footer component: https://designsystem.digital.gov/components/footer/

Should support all options: Big, Medium, Slim
Should support mobile view (seen particularly in Big Footer)

Render content:

• Return to top link
• Navigation tree (might be sub components, and/or children)
• Sign up form or similar form
• Address, logo, and social media links(sub components rendered as children)

Right now, commitlint is set up to make sure every commit message follows the conventional commits format. That way, certain types of commits will automatically be included in the changelog. However, we'd like to support a workflow where only merge commits, and/or squash and merge PR titles have to match the format. Ideally a developer can check out a branch, write whatever commits they want, and then when they merge a PR the commit message will match the conventional commits format (probably based off the PR title).

https://github.com/conventional-changelog/standard-version
https://commitlint.js.org/#/

Right now, the Button component will only render a button. However it's very common for a user to want to implement button styles on an <a> element or even a custom link component (such as if they are using client-side routing). So the Button component should be modified to accept an optional Component prop (probably of type ReactNode) to support that use case. It should still default to button if no Component prop is defined.

Update the version of USWDS we're using to the latest (2.7.0 as of this writing). I don't believe there are any breaking changes relevant to our code but it's worth double checking.

We currently have Alert included in our system, but the usa-alert--slim class has no means of being applied. We could go about this in a couple of ways:

• we could add support for custom classes
• we could add an additional attribute that would apply the class, similarly to how we currently set an Alert to be warning, success, etc.
• we could do both, just to cover all our bases

Slim Alert sample: https://components.designsystem.digital.gov/components/detail/alerts--slim.html

**Needed for MilMove

Try making dependabot a code owner of yarn.lock to see if that unblocks its automerge process

It is probably worth documenting base USWDS styles that apply to just plain old HTML, without creating React components for them. For example, what does a ul, ol, dl look like with the USWDS CSS applied? We should add Storybook stories to illustrate these elements.

For a comprehensive list of HTML elements, see https://developer.mozilla.org/en-US/docs/Web/HTML/Element

Right now, the NavDropDownButton component implements a prop called menuId which is meant to be the id attribute of the corresponding Menu. However the Menu component doesn't accept an id prop. It should be modified to accept all ul props (ie., using React.HTMLAttributes<HTMLUListElement>) and pass them into the rendered NavList.

The same change should also be made to the MegaMenu component.

Keep track of code test coverage in this repo. Since we're open source we can probably use a free service!

Running a yarn storybook or yarn build or yarn install on any of the branches of this project seems to modify some generated files even if nothing was changed. Not sure what is causing this to be different than before.

❯ git status
On branch release-1.1.0
Your branch is up to date with 'origin/release-1.1.0'.

Changes not staged for commit:
  (use "git add <file>..." to update what will be committed)
  (use "git restore <file>..." to discard changes in working directory)
        modified:   src/components/Alert/Alert.module.css.d.ts
        modified:   src/components/Modal/Modal.module.scss.d.ts
        modified:   src/components/Table/Table.module.css.d.ts

As part of automated testing, I recommend we set up https://loki.js.org/ to run against storybook in this project, and the corresponding CircleCI job to run it so that contributions and improvements do not break the visual appearance of components unexpected.

Add a yarn shortcut script to use when adding a new component. This will be used by developers adding new components to the project.

Acceptance criteria:

• yarn create-component <componentName> creates a new directory insrc/component named after the component.
• The following files are also created:

src/components/ComponentName/ComponentName.tsx
src/components/ComponentName/ComponentName.stories.tsx
src/components/ComponentName/ComponentName.tests.tsx

Optional extensions to this work could be:

• The command also exports the component from index.js
• The command also adds boilerplate code with the component Name to the different files.

We have an existing Link component that should be adjusted to handle a new variant prop called nav.

Requirements:

• Add nav as another possible value to the StyledLinkProps variant type definition
• Adjust the logic in the linkClasses function so that it includes the usa-nav__link class when the variant prop is nav
• Add a storybook example to Link.stories.tsx for <Link variant="nav">

In order to make this library more accessible and so it's easier to view the components, we should set up the Storybook instance as a public Github page. More info https://storybook.js.org/docs/basics/exporting-storybook/#deploying-to-github-pages

Both the Search component and the Form component add the usa-search CSS class to the search form, resulting in the class being output twice in the rendered markup. This isn't causing any issues but there's no reason to include it twice. I'd recommend deleting it from the Form component.

Add components for rendering the USWDS Grid: https://designsystem.digital.gov/utilities/layout-grid/

These may just be divs with the proper classes. Examples:

• GridContainer
• GridRow
• GridCol with size/responsive props

Since most of the time, Trussels who are working on this library actively will probably be on Reserve, they may need to be onboarded/offboarded relatively quickly and frequently. We may also often run into the situation where a Trussel is not able to complete work in progress if they end up joining a new client project on short notice. We should add some documentation that outlines what to do when you are onboarding & offboarding as an "active" contributor to this project.

We have several components such as Header, Footer, Button, and maybe even aspects of Grid, with boolean props that can conflict.

For example, you should not have the big and medium prop applied to the same footer. Some of this should be on the developer to use our props ... properly 😝... AND we also could starting using variants as well when helpful.

Instead of booleans we could move towards a single prop named something like size or type that accepts one of these types. The types would be enums. How do folks feel about this? Is this something we could start code reviewing for and document as practice?

Proposed requirements to close this issue:

• Add a type variant to the Button component (keep the old way of doing these props too but add a deprecation warning - it can be removed fully in next major release ).
• Write out additional issues for other components with this problem.
• Add description of best practices with props to #73

In the interest of minimum coverage of USWDS, it would be good to include implementations of all examples documented on the USWDS site, if only as proof of concepts that our library can do everything it can do. This is achieved by creating Storybook stories for different use cases. We have form templates for Name and Address, but should add Sign-in form and Password reset form: https://designsystem.digital.gov/components/form-templates

Dependabot encountered the following error when parsing your .dependabot/config.yml:

Automerging is not enabled for this account. You can enable it from the [account settings](https://app.dependabot.com/accounts/trussworks/settings) screen in your Dependabot dashboard.

Please update the config file to conform with Dependabot's specification using our docs and online validator.

There are some new components that could include lang strings- see "Return to top" in Footer #78 and SearchInput #104 . Since sites using the library can be in another language, we are creating components that won't be flexible to internationalization.

One solution could be that we don't include any hardcode any strings in our components (or only as a default value that can be overridden by a prop). Other thoughts or ideas?

Create a Github workflow for every time a PR is merged to master:

• Create a new release on Github (https://github.com/trussworks/react-uswds/releases) using the most recent CHANGELOG entry (and/or PR description)
• Merge master into develop so that develop is up to date with the new version.
• Publish the new version on npm (if tests pass)

This will require storing an npm token in GH. Probably a job for @trussworks-infra

Add Date input component: https://designsystem.digital.gov/components/form-controls/#date-input

• This is not a calendar/date picker.
• We may want to support partial date formats (ie, month/year, day/month, year only)

Create Storybook stories that render the page templates provided by USWDS, using ReactUSWDS components.

https://designsystem.digital.gov/page-templates

• Landing page
• Documentation page

Button Group

A button group collects similar or related actions

Proposed requirements

Props<T> =  
  type: "default" | "segmented"  
  children: React.ReactNode 
}

• ButtonGroup wraps Button children in a list. Children are required.
• Base element by default is <ul> and the button children are rendered as list items

Other Considerations

Convey relationship. If not using a list element, give the parent element role="group" in order to convey to screen readers that actions are part of a group. If using as part of a toolbar, use role="toolbar".

• add a usage of button group to example app

Make a basic Link component that wraps a link in the classes we need for an internal link usa-link versus and external link usa-link usa-link--external.

This is another way to encapsulate styles. See Typography > Links.

By default renders an anchor tag, but has an optional prop to accept a different component.

Deprecated @storybook/addon-info is pulling in a bad marked dependency via marsky. Although this is already fixed in marked, it is unlikely to be fixed any time soon for marksy: storybookjs/marksy#78. (There were breaking changes which marksy maintainers have yet to resolve; it is a non-trivial fix.)

Since @storybook/addon-info is deprecated, even without the security vulnerability we should be switching to @storybook/addon-docs.

yarn audit output

>> yarn audit
yarn audit v1.22.4
┌───────────────┬──────────────────────────────────────────────────────────────┐
│ moderate      │ Regular Expression Denial of Service                         │
├───────────────┼──────────────────────────────────────────────────────────────┤
│ Package       │ marked                                                       │
├───────────────┼──────────────────────────────────────────────────────────────┤
│ Patched in    │ >=0.6.2                                                      │
├───────────────┼──────────────────────────────────────────────────────────────┤
│ Dependency of │ @storybook/addon-info                                        │
├───────────────┼──────────────────────────────────────────────────────────────┤
│ Path          │ @storybook/addon-info > marksy > marked                      │
├───────────────┼──────────────────────────────────────────────────────────────┤
│ More info     │ https://www.npmjs.com/advisories/812                         │
└───────────────┴──────────────────────────────────────────────────────────────┘
1 vulnerabilities found - Packages audited: 328229
Severity: 1 Moderate
✨  Done in 1.60s.

references

• storybook's list of addons which calls info out as deprecated
• storybook's info -> docs migration guide
• storybook addons-docs main
• https://www.npmjs.com/advisories/812
• storybookjs/marksy#78

Add Header component: https://designsystem.digital.gov/components/header/

Should support all options: Basic, Extended, "mega menu"

Possible sub components:

• Header title
• Horizontal nav (nav tree with dropdowns, dropdown may be "mega menu")
• Search input
• Secondary nav

Update docs on how to add an audit to a PR that changes dependencies