diff --git a/CODEOWNERS b/CODEOWNERS index 7654532f48..2bee5cb052 100644 --- a/CODEOWNERS +++ b/CODEOWNERS @@ -1 +1 @@ -* @suzubara @gidjin @tinyels @sarboc +* @suzubara @gidjin @tinyels @sarboc @haworku diff --git a/docs/adding_new_components.md b/docs/adding_new_components.md new file mode 100644 index 0000000000..eeeaf44c97 --- /dev/null +++ b/docs/adding_new_components.md @@ -0,0 +1,73 @@ +# Adding New Components + +## Checklist + +Every new `react-uswds` component needs the following: + +- [ ] **A Github issue with the requirements clearly listed.** Requirements include a rough sketch of the expected props and any state the component will handle. +- [ ] **A component file (`.tsx`) inside a matching folder** - e.g. `component/GovBanner/GovBanner.tsx`. +- [ ] **An export from the package entry point** - e.g. `index.ts` must have the line `export { GovBanner } from './components/GovBanner/GovBanner'` +- [ ] **Unit tests** (`test.tsx` file) for logic relating to props and events handlers. +- [ ] **Storybook stories** (`stories.tsx` file) illustrating the use of the component. The goal is parity with the USWDS design system examples. Use the [component story format](https://storybook.js.org/docs/formats/component-story-format/). + +## Navigating documentation + +We can extrapolate the requirements for `react-uswds` components by referencing several sources. Relevant documentation includes: + +- HTML markup and written descriptions of components in the [design system docs](https://designsystem.digital.gov/components/footer/) +- Live code demos in the [uswds storybook](https://components.designsystem.digital.gov/) +- Implementation details from the [uswds github repo](https://github.com/uswds/uswds/tree/50f6ffd6b0b6afa1b499daa36b6f8ee0312b1123/src/js/components) +- HTML attribute documentation in [MDN reference docs](https://developer.mozilla.org/en-US/docs/Web/HTML/Element) + +Pay special attention to: + +- _Mobile._ There are often mobile and desktop styles - see `
` and `` for two different approaches to implementing mobile styles. +- _User Interaction._ Consider interactions such `click`, `focus`, `hover`. Some of this will be naturally handled by applying the proper uswds CSS classes, other behaviors will need custom implementation. See `` for examples of both cases, +- _Accessibility._ Double check behavior of keyboard-only interactions. Some user interaction requires multiple event handlers (e.g. for non interactive elements that use `onClick`, a keyboard listener (such as `onKeyDown` or `onKeyPress` is also needed)). We have added the `jsx-a11y` plugin to help with accessibility requirements. + +## Guiding Patterns For Writing Flexible Components in react-uswds + +### Props + +- Require props that are fundamental to the element (such as `id` and `name` for a form input), even if they aren't necessarily "required" HTML attributes. Make all other props optional. +- Extend the standard HTML attributes as props for the primary element in the component. For example, a form can have its own props and also extend the `HTMLFormElement` + +```javascript + interface FormProps { + children: React.ReactNode, + big: boolean + } + + export const Form = ( + props: FormProps & React.FormHTMLAttributes + ): React.ReactElement => + ``` + +- Avoid [conflicting boolean props](https://spicefactory.co/blog/2019/03/26/how-to-avoid-the-boolean-trap-when-designing-react-components/). When props are mutually exclusive you likely need to use an enum prop instead. See `