[![Coverage Status](https://coveralls.io/repos/github/wealthsimple/patchwork/badge.svg?branch=master&t=keO380)](https://coveralls.io/github/wealthsimple/patchwork?branch=master)
[![Dependabot Status](https://api.dependabot.com/badges/status?host=github&repo=wealthsimple/patchwork&identifier=128153819)](https://dependabot.com)

# Patchwork - Wealthsimple React Component Library

## Purpose:

Patchwork is Wealthsimple's UI Component library for React applications.

It aims to provide a first class DSL for building user interfaces that can:

- Reduce the amount of DOM and CSS you have to write,
- Help ensure that all your UI is themeable,
- Help ensure that all your UI is accessible.

## Patchwork User's Guide

Are you a developer trying to use patchwork to implement features in your application? Check out the [Users' Guide](./docs/users-guide/INTRO.mkd), or the live docs site: https://code.w10e.com/docs/patchwork (you'll need to be on VPN).

## Patchwork Implementer's Guide

Are you a designer or a developer adding features to patchwork itself? Check out the [Implementers' Guide](./docs/implementers-guide/INTRO.mkd).

## Stack

- [React](https://reactjs.org/)
- [Styled-components](https://www.styled-components.com)
- [Storybook](https://storybook.js.org/)
- [Flow](https://flow.org/)

## Architectural Decision Records

Wonder why something is implemented a certain way? Curious about the reasoning behind this code-base's conventions?

Decisions of this nature are recorded in this repo as [Architectural Decision Records (ADRs)](./docs/adr/README.md).

## Consuming components in your project

You can consume this project one of two ways:

#### Babel 7+ With Flow

For compatibility with our internal toolchain, I just expose the ES6+Flow source code for now.
That means you'll need a compatible babel config + bundler setup in your project. Check this project's
`.babel.config.js` for the specific configuration.

Then import things from `@wealthsimple/patchwork` to use them:

```js
import { Box } from '@wealthsimple/patchwork';
```

#### ES5/UMD

Not running a transpiler? Running a transpiler that's not Babel (e.g. TypeScript)? Not using Flow?

No problem. We also expose a UMD-ified ES5 version of this library in the `dist` folder:

ES6/TypeScript:

```js
import { Box } from '@wealthsimple/patchwork/dist';
```

CommonJS:

```js
const { Box } = require('@wealthsimple/patchwork/dist');
```

## Running locally

To run patchwork locally run ( on port 9001):

```
yarn storybook
```

If using a compatible IDE ( RubyMine ) you can display flow errors by linking the flow library:

- Language & Frameworks / JavaScript
- Select language version: Flow
- Select executable flow library "... patchwork/node_modules/flow-bin/flow-osx-v0.78.0/flow"

## Accessibility Testing

As of [January 2021](https://www.ontario.ca/page/how-make-websites-accessible), Wealthsimple is legally required to make any of our websites [WCAG 2.0 Level AA](https://www.w3.org/WAI/standards-guidelines/wcag/) compliant. Accessibility is sometimes forgotten about when developing fast features in web, but it’s extremely important in providing all of our clients the same, equal-level of access to our services. Although not always possible (i.e. with our current colour scheme), we should be striving for perfect AA compliance across our entire application. Patchwork must be accessible because it serves as the building blocks for our entire application.

In order to test accessibility, we’ve tried to automate the accessibility auditing in a way that keeps these tests close to the code and also with fast feedback. To test accessibility, simply do the following:

```js
// in some-feature.test.js
// @flow
import { itIsAccessible } from '@wealthsimple/patchwork/utils/test-utils';
import { SomeFeature } from '.';

describe('SomeComponent', () => {
  describe('common use case', () => {
    // this will automatically make the assertion and mount with patchwork's
    // mountWrappedComponent for you. if there are any errors, you will get
    // valuable context from them around what is failing
    itIsAccessible(<SomeComponent label="Test" />);
  });
```

_Note_: Don’t just rely on the automated accessibility tests. When you make changes or create a new component, before you launch it to the public you show always try and interact with it using a screen-reader.
