# Arrow

Arrow is a Design System. A design system provides a central source for, among other things, design assets, UX guidelines and reusuable components as code. This repository contains reusuable React components and styles for use when building React web apps. You can also find useful links, guidelines and information on how to follow best practices when building web apps.

If you are reading this document in the component browser, you can browse the available React components using the navigation on the left. The Design Tokens section has guidelines and information on available styles and CSS. 

## Getting Started

### Node requirements

The library is built and tested with node LTS (8.x). We recommend using the latest LTS version.

### Component consumption

Here's an example of using the Button component. First, you specify the component library into your project as a dependency using npm: 

```sh
npm install @bitdepth/ds-components
```

Then you can use it in your React projects like this:

```javascript
import React from 'react';
import IconButton from '@bitdepth/ds-components';

export default (
  <IconButton
    icon="home"
    fill
    border
    label="Home"
  />
);
```

### Style consumption

You will **need to link the styles** as these are currently not baked into the components. There are a couple of ways to do that and the styles are provided as both CSS and SCSS. If you are using the provided components and only need to work with basic styles in you app you should generally be able to simply link the compiled CSS file. However, if you need to do more detailed work you can import the SCSS files to make use of the available design tokens, mixins and other utility functions.

#### CSS

To use the compiled CSS simply link or import `lib.css`.

#### SCSS

The SCSS file are currently under `src/scss`. You can import all the styles via `src/scss/lib.scss`. Alternatively browse that directory to see what is available in each file.

Component specific SCSS files should reside in the component folder alongside other coding assets: `src/components/Button/Button.scss`.  
These files will be imported into the root SCSS file at `src/scss/libs.scss`.

Component specific storybook presentation SCSS should also reside in the component folder alongside other coding assets: `src/components/Button/Button.stories.scss`.  
These files will be imported into the root storybook SCSS file at `src/scss/storybook.scss`. This css is not published with the library.

*TODO: Needs more info.*

##### CSS Namespacing

All published CSS classes should be prefixed with `ds-`.  
All CSS classes used for storybook presentation should be prefixed with `sb-`.

### Typescript definitions

If you are using Typescript in your project you will need to use the supplied Typescript definition file, `index.t.ds`.

## Using from the source

If you want to build from source to test things or to contribute start by cloning the git repo from [here](https://bitbucket.org/colinclark/ds-components).

### NPM scripts

To build the code:
```sh
npm install
npm run fetch:assets
npm run build
```

#### Fetch brand-ai assets

Fetch latest brand-ai assets into /assets directory

```sh
npm run fetch:assets
```

#### Storybook

Storybook is used to display the components. Just run `npm run storybook` and open http://localhost:3000 in a browser.

#### Linting

Run SCSS and Javascript linting using stylelint and eslint + prettier

```sh
npm run lint
```

Fix common JS linting issues

```sh
npm run lint:js:fix
```

#### Testing

Run unit and integration tests using Jest + Enzyme

```sh
npm run test
```

To run individual tests with Jest + Enzyme

```sh
npm run test ./src/components/Dropdown/Dropdown.test.jsx
```

Run end to end and visual regression tests using nightwatch

```sh
npm run e2e
```

To run individual e2e tests use
```sh
npm run e2e -- --test test/e2e/components.js --testcase 'VRT Icon'
```

#### Jenkins e2e
The end to end tests on our Jenkins QA Job run against BrowserStack. These currently target IE, Chrome, Firefox and Safari (Mac). A first point of call after a CI build failure for the e2e tests should be [BrowserStack Automate](https://www.browserstack.com/automate/)   where you can replay video of the tests to try to identify the cause of failure. 

#### Build for release

Build component library for production release using webpack to /dist directory

```sh
npm run build
```

#### Analyze webpack build

```sh
npm run build:analyze
```

### Accessibility

To test the accessibility of the DSM components, run the PA11Y script. PA11Y loops through all the DSM components then compiles a report of any accessibility errors that appear. It will then make recommendations of how to fix the issue.

```sh
npm run test-accessibility
```

The config file can be found here: ds-components/config/pa11y/config.js

### Additional Info
A pre-commit hook is in place to automatically run linting and tests on staged files to ensure only clean commits are made to the repository.

A CI pipeline is in place to checks merges to the Release branch to build an instance of storybook to http://ds-components-qa.s3-website-eu-west-1.amazonaws.com/ for QA. 

Once QA has been completed, the publish script can be run which will merge the Release branch into the Master branch and publish the library to NPM.
```sh
npm run release [minor, major, patch x.x.x]
```

The CI pipeline will then build storybook from the Master branch and deploy to http://ds-components-prod.s3-website-eu-west-1.amazonaws.com/.

#### Jenkins e2e
The end to end tests on our Jenkins QA Job run against BrowserStack. These currently target IE, Chrome, Firefox and Safari (Mac). A first point of call after a CI build failure for the e2e tests should be [BrowserStack Automate](https://www.browserstack.com/automate/)   where you can replay video of the tests to try to identify the cause of failure. 

A temporary version of the site is published to [s3](http://ds-components-vrt.s3-website-eu-west-1.amazonaws.com/) where BrowserStack can access it. You can run the e2e tests from your local machine against this build by typing `npm run e2e:ci` which will give you console access to the test failure report.

You can also baseline the VRT tests by running the VRT App with ``npm run e2e:vrt:ui`` and navigating to the http://localhost:8000


### Contributing and help

See the guidelines in `CONTRIBUTING.md`.

### Links
[Production](http://ds-components-prod.s3-website-eu-west-1.amazonaws.com/)
[QA](http://ds-components-qa.s3-website-eu-west-1.amazonaws.com/)
[VRT](http://ds-components-vrt.s3-website-eu-west-1.amazonaws.com/)

[Jenkins CI](http://ec2-34-240-207-21.eu-west-1.compute.amazonaws.com:8080/)

### Release process

To ensure a smooth release process follow the steps below

* Ensure all PR's for `release` branch are merged with no conflicts
* Checkout the `release` branch locally and pull the latest changes
* Update the `CHANGELOG.md` with the tickets from last sprint
* `npm run release` ensuring you pass in the correct version

The release script will publish the package to NPM and push the latest changes to the `release` branch.
Finally it will checkout `master` and merge the latest changes from `release` before pushing a tagged release to the `master` branch.
