cleverjam / reach-ui

The Accessible Foundation for React Apps and Design Systems

Welcome to Reach UI Development ♿️

Thanks for getting involved with Reach UI development!

Looking for the documentation?

https://reacttraining.com/reach-ui/

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:

git clone [email protected]:reach/reach-ui.git
cd reach-ui
yarn install
yarn build

Root Repo Scripts:

yarn build        # builds all packages
yarn start        # starts storybook server
yarn test         # runs tests in all packages

Running / Writing Examples

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

yarn start

Next, put a file in packages/<component-dir>/examples/<name>.example.js and make it look like this:

import React from "react";

// The name of the example, you must export it as `name`
export let name = "Basic";

// The example to render, you must name it `Example`
export let Example = () => <div>Cool cool cool</div>;

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:

yarn test

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

yarn test --watch

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

cd packages/<component-path>
yarn test --watch

Development Plans

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

✅ - Released
🧪 - Beta Released
🛠 - Planning to Build
❓ - Might Build?

Status	Name
🛠	Accordion
✅	Alert
✅	Alert Dialog
❓	Breadcrumb
❓	Button
🛠	Carousel
🛠	Checkbox
✅	Combo Box
✅	Dialog (Modal)
🛠	Disclosure
❓	Feed
❓	Grids
❓	Link
🛠	Listbox
❓	Menu or Menu bar
✅	Menu Button
🛠	Radio Group
✅	Slider
🛠	Slider (Multi-Thumb)
❓	Spinbutton
❓	Table
✅	Tabs
❓	Toolbar
✅	Tooltip
🛠	Tree View
❓	Treegrid
❓	Window Splitter

Releases

This is 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...

# First, run the build locally and make sure there are no problems
# and that all the tests pass:
$ yarn build
$ yarn test

# Generate the changelog and copy it somewhere for later. We'll
# automate this part eventually, but for now you can get the changelog
# with:
$ yarn changes

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

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

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

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

# Open up travis-ci.com/reach/reach-ui and watch the build. There will
# be 2 builds, one for the push to the master branch and one for the
# new tag. The tag build will run the build and all the tests and then
# automatically publish to npm if everything passes. If there's a
# problem, we have to figure out how to fix manually.

# Paste the changelog into the release on GitHub. The release is
# complete … huzzah!

You need to be careful when publishing a new package because the lerna publish on Travis 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://reacttraining.com/reach-ui/ when the website branch is updated.

Contributors

This project exists thanks to our contributors and financial backers.