Reach UI

The Accessible Foundation for React Apps and Design Systems

AccessibilityReactModalTooltipMenuHeadless components
reach/reach-uireacttraining.com/reach-ui/@reach/component-component

README

Welcome to Reach UI Development ♿️


Thanks for getting involved with Reach UI development!

Looking for the documentation?


https://reach.tech/

Getting Started


Reach UI is built and tested with Yarn. Please follow their install instructions to get Yarn installed on your system.

Then, run these commands:

  1. ```
  2. git clone git@github.com:reach/reach-ui.git
  3. cd reach-ui
  4. pnpm install
  5. pnpm build
  6. ```

Root Repo Scripts:


  1. ```sh
  2. pnpm build        # builds all packages
  3. pnpm dev        # starts storybook server
  4. pnpm test         # runs tests in all packages
  5. ```

Running / Writing Examples


First do the steps in "Getting started", then start the Storybook server:

  1. ```
  2. pnpm dev
  3. ```

Next, put a file in `packages//examples/.example.js` and make it look like this:

  1. ``` js
  2. import * as React from "react";

  4. // The name of the example (always name the variable `name`)
  5. let name = "Basic";

  7. // The example to render (always name the function `Example`)
  8. function Example() {
  9. return <div>Cool cool cool</div>;
  10. }

  12. // Assign the name to the example and then export it as a named constant
  13. Example.storyName = name;
  14. export const Basic = Example;

  16. // Default export an object with the title matching the name of the Reach package
  17. export default { title: "Dialog" };
  18. ```

Now you can edit the files in packages/* and storybook will automatically reload your changes.

Note: If you change an internal dependency you will need to run yarn build again. For example, if working on MenuButton requires a change to Rect (an internal dependency of MenuButton), you will need to run yarn build for the changes to Rect to show up in your MenuButton example.

Running / Writing Tests


First do the steps in "Getting Started", then:

  1. ```
  2. pnpm test
  3. ```

Or if you want to run the tests as you edit files:

  1. ```
  2. pnpm test --watch
  3. ```

Often you'll want to just test the component you're working on:

  1. ```
  2. cd packages/<component-path>
  3. pnpm test --watch
  4. ```

Development Plans


The components to be built come from the the Aria Practices Design Patterns and Widgets, with a few exceptions. Here is a table of the components and their status.

✅ - Released
🛠 - Building

StatusName
--------------------
✅Accordion
✅Alert
✅Alert
✅Checkbox
✅Combo
✅Dialog
✅Disclosure
🛠Hover
✅Listbox
✅Menu
🛠Radio
✅Slider
✅Tabs
🛠Toggletip
✅Tooltip

Releases [DEPRECATED]


This is (was?) our current release process. It's not perfect, but it has almost the right balance of manual + automation for me. We might be able to put some of this in a script...

  1. ```sh
  2. $ git checkout main
  3. $ git pull origin main
  4. $ git checkout dev
  5. $ git pull origin dev
  6. $ git checkout -b release-<version>
  7. $ git merge main

  9. # Resolve any merge conflicts and commit if necessary

  11. # Run the build locally and make sure there are no problems
  12. $ pnpm build
  13. $ pnpm test

  15. # Check out the `main` branch and merge release changes from `dev`
  16. $ git checkout main
  17. $ git pull origin main
  18. $ git merge dev

  20. # Write the changelog based on commits. We'll automate this part
  21. # eventually, but for now this is manual.

  23. # Then create a new version and git tag locally. Don't push yet!
  24. $ pnpm ver [version]

  26. # Take a look around and make sure everything is as you'd expect.
  27. # You can inspect everything from the commit that lerna made with:
  28. $ git log -p

  30. # If something needs to be changed, you can undo the commit and
  31. # delete the tag that lerna created and try again.

  33. # If everything looks good, push to GitHub along with the new tag:
  34. $ git push origin main --follow-tags

  36. # Open up https://github.com/reach/reach-ui/actions and watch the build. There will
  37. # be 2 builds, one for the push to the main branch and one for the
  38. # new tag. The tag build will run the build and all the tests and then
  39. # automatically publish to npm if everything passes. If there's a
  40. # problem, we have to figure out how to fix manually.

  42. # Paste the changelog into the release on GitHub. The release is
  43. # complete … huzzah!
  44. ```

You need to be careful when publishing a new package because the lerna publish on CI will fail for new packages. To get around this, you should publish a 0.0.0 version of the package manually ahead of time. Then the release from CI will be ok. This is really janky but AFAICT the only workaround.

Stuff I'd like to improve:

- Automate changelog generation and GitHub release from CI
- Document how we're using GitHub PRs to generate the changelog somewhere

Website


The website is a Gatsby app in the website directory. It automatically deploys to https://reach.tech/ when the website branch is updated.