docs: adding new components docs #73 (#248)

* docs: reword developing, contributing md, add to codeowners

CODEOWNERS

@@ -1 +1 @@
-* @suzubara @gidjin @tinyels @sarboc
+* @suzubara @gidjin @tinyels @sarboc @haworku

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 `<Header />` and `<FooterExtendedNavList />` 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 `<Accordion />` 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<HTMLFormElement>
+  ): 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 `<Button />`.
+
+### State
+
+- Group state declarations and hooks at the top of the component function. Make it easy to see how state is being used in the component.
+- When using [`useState`](https://reactjs.org/docs/hooks-state.html), prefer [functional updates](https://reactjs.org/docs/hooks-reference.html#functional-updates). Object spread syntax is useful here.
+- Keep components as flexible as possible. This means leaving business logic/implementation details out of the component (use props instead of internal state). Anytime you find yourself using component `state` heavily, ask yourself if its something that should actually be tracked by the consumer instead.
+
+### Children
+
+- Whenever main content is not required and is not highly structured or ordered, passing [`children`](https://reactjs.org/docs/jsx-in-depth.html#children-in-jsx) may be the way to go.
+
+### Using "Subcomponents"
+
+- The `react-uswds` components will not always map one-to-one to uswds design system components. By creating subcomponents, we break down larger component into smaller concerns and benefit from [React's ability to compose components together](https://reactjs.org/docs/composition-vs-inheritance.html).
+- We have a pattern of grouping subcomponents together in a folder. We don't write stories for most subcomponents, unless they seem like a piece of UI that could be reused alone. Examples of subcomponents - `Header`, `Footer`, `Card`
+- Indicators that a subcomponent may be needed:
+  - It's getting hard to pass conditional props (such as styles) to different levels of the HTML tree from the top level.
+  - A smaller piece of UI is being used that is generalizable enough to be used and exported on its own.
+  - The uswds component is complex - an [organism](https://atomicdesign.bradfrost.com/chapter-2/#organisms) in the language of atomic design.
+
+### Common Components in `react-uswds`
+
+- Components that apply uswds styles to a standard HTMLElement - `Button`, `Table`
+- Components that encapsulate user interaction flows - `Accordion`, `Modal`
+- Components for a common gov tech use case - `Search`, `SocialLinks`
+- Components that render children - `Card`, `Header`, `Footer`
+- Components related to forms, especially form inputs - `DateInput`, `TextInput` `Checkbox`, `Label`

docs/contributing.md

@@ -1,5 +1,11 @@
 # Contributing
 
+## Table of Contents
+
+1. [Environment Setup](#environment-setup)
+2. [Development](#development)
+3. [Releasing](#releasing)
+
 ## Environment Setup
 
 1. Clone this repo!
@@ -36,26 +42,35 @@ To start working on a new issue, make sure you've assigned yourself to the issue
 
 For example: `sr-accordion-component-112`
 
-Because this project exports a library that will be used by other projects, it is important to make sure that updates follow a set of standard practices, and new versions are tagged with an accurate description of changes. When you commit your changes, several hooks will run to check and format staged files. In order to be eligible for merging, all branches must pass testing and linting standards. Additionally, this project follows the [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/#summary) specification in order to standardize contributions and streamline the release flow.
+See the guide [adding new components](./docs/adding_new_components.md) to get ideas of where to start.
+
+### Pull Requests
+
+When your branch is ready for review, open a PR into `develop` and request reviews from relevant team members. Reviews from codeowners will automatically be requested. Address any failing tests, lint errors, PR feedback, etc., and once your branch is approved you can squash & merge it into `develop`.
+
+This project follows the [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/#summary) specification. This standardizes contributions and streamlines the release flow. **All pull requests opened into `develop` or `master` must have a title that follows the [conventional commits spec](https://github.com/conventional-changelog/commitlint/tree/master/%40commitlint/config-conventional).** This generates an automated changelog entry and is required to merge.
+
+(TODO) Passing `develop` builds will automatically be published to the `next` tag on NPM. This allows users to easily test out the latest version in their applications, which may be unstable.
+
+### Dev Notes
+
+Because this project exports a library that will be used by other projects, it is important that updates follow a set of standard practices. When you commit your changes, several hooks will run to check and format staged files. In order to be eligible for merging, all branches must pass testing and linting standards.
 
 - [Prettier](https://prettier.io/), [TypeScript compilation](https://www.typescriptlang.org/), [eslint](https://eslint.org/) and [stylelint](https://stylelint.io/) are run on _staged files_ as a pre-commit hook
   - For an optimal developer experience, it's recommended that you configure your editor to run linting & formatting inline.
   - These checks will also be run on all files in CI, and must pass before the branch can be merged
-- All pull requests opened into `develop` or `master` must have a title that follows the [conventional commits spec](https://github.com/conventional-changelog/commitlint/tree/master/%40commitlint/config-conventional). This generates an automated changelog entry and is required to merge. The [WIP] prefix can also be used to indicate a pull request is still work in progress. In this case,  the PR title is not validated and the pull request lint check remains pending.
+- [`standard-version`](https://github.com/conventional-changelog/standard-version) is used during releases to auto-generate version numbers and changelog based on PR title.
+  - The version number is determined based on conventional commits - **[fix]** indicates a bug fix, **[feat]** indicates a minor bump. **[!]** or [BREAKING CHANGES] indicates a major bump. Be sure to use the correct spec.
+  - The **[WIP]** prefix can be used to indicate a pull request is still work in progress. In this case, the PR title is not validated and the pull request lint check remains pending.
+  -  We have set up [`commitizen`](https://commitizen.github.io/cz-cli/) CLI for making it easy to write standard commit messages. You can use `yarn commit` instead of `git commit` to start the commitizen prompt
 - The project is configured to only allow [squash & merge](https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/about-pull-request-merges#squash-and-merge-your-pull-request-commits) PR commits.
-  - We also have set up [`commitizen`](https://commitizen.github.io/cz-cli/) CLI for making it easy to write standard commit messages.
-  - You can use `yarn commit` instead of `git commit` to start the commitizen prompt
-- We also use [dangerjs](https://github.com/danger/danger-js) to enforce several pull request standards, including:
-  - Changes to package source code should include changes to tests
-  - New src/components files should include changes to storybook
-  - Package dependency changes should include `yarn.lock` updates and `yarn audit` outputs
+- [dangerjs](https://github.com/danger/danger-js) is used to enforce several pull request standards, including:
+  - Changes to package source code should include changes to tests.
+  - New `src/components` files should include changes to storybook.
+  - New `src/components` files should be exported from the package entrypoint.
+  - Package dependency changes should include `yarn.lock` updates and `yarn audit` outputs in PR description.
 - All [Jest tests](https://jestjs.io/) will be run in CI and must pass before the branch can be merged
 - [Happo.io visual regression tests](https://docs.happo.io/docs/reviewing-diffs) will be run in CI and all diffs must be approved before the branch can be merged. Developers must have access to the Happo.io account to approve/reject diffs. If you work at Truss, log into Happo.io with your gmail and you will be able to approve/reject changes. Navigate to the happo link for instructions on how to review and approve diffs.
-- [`standard-version`](https://github.com/conventional-changelog/standard-version) is used during releases to auto-generate version numbers and changelog based on commit messages
-
-When your branch is ready for review, open a PR into `develop` and request reviews from relevant team members. Reviews from codeowners will automatically be requested. Address any failing tests, lint errors, PR feedback, etc., and once your branch is approved you can squash & merge it into `develop`.
-
-(TODO) Passing `develop` builds will automatically be published to the `next` tag on NPM. This allows users to easily test out the latest version in their applications, which may be unstable.
 
 ## Releasing