# @jisc/jisc-react-components

> React components for sharing across Jisc web estate

Latest version **1.2.0-alpha** (published 2021-06-25) · MIT license · 0 weekly downloads

> **Deprecated.** This package is deprecated.

## Install

```sh
npm install @jisc/jisc-react-components
pnpm add @jisc/jisc-react-components
yarn add @jisc/jisc-react-components
bun add @jisc/jisc-react-components
```

## Health

**Score 10/100 (F)** — status: deprecated.

Negative: deprecated.

## Facts

| | |
|---|---|
| Version | 1.2.0-alpha |
| Published | 2021-06-25 |
| First published | 2021-02-03 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | ESM + CommonJS |
| Node | >=10 |
| Dependencies | 2 |
| Unpacked size | 601.6 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | Jisc |
| Maintainers | will-blenkhorn-jisc, philreeksjisc, kiranjoshi_jisc, josh_ring_jisc, lesley.beattie, keiththomasjisc, faisaltaher-jisc, sreepriyabala, zzcgulm |

## Links

- npm: https://www.npmjs.com/package/@jisc/jisc-react-components
- Repository: https://github.com/JiscSD/jisc-react-components
- Homepage: https://github.com/JiscSD/jisc-react-components#readme
- Issues: https://github.com/JiscSD/jisc-react-components/issues
- npm.io page: https://npm.io/package/@jisc/jisc-react-components

## Dependencies (2)

- [clsx](https://npm.io/package/clsx.md) ^1.1.1
- [prop-types](https://npm.io/package/prop-types.md) ^15.7.2

## Recent versions

- 1.2.0-alpha (latest) — 2021-06-25
- 1.1.0-alpha — 2021-05-28
- 1.0.0-alpha — 2021-05-14
- 0.4.0-alpha — 2021-04-01
- 0.3.1-alpha — 2021-03-19
- 0.3.0-alpha — 2021-03-19
- 0.2.0-alpha — 2021-03-01
- 0.1.0-alpha — 2021-02-03

## README

# React UI components

A library of components based on React and Material UI that are re-usable.

This library is designed to help React developers create UI components that are accessible, usable, and conforms to Jisc branding guidelines.

## Project contents

- The base project `jisc-react-components` is the component library that can be installed by the end users (eg developers working a React website).
- A playground project where developers of this project can test components.
- Storybook server
- Terraform intrastructure code in the `terraform/` directory

## Local set up for developers

### Pre-requisites

Node v14.x

Yarn v1.22.x

#### Recommended developer set-up

IDE: [Visual Studio Code](https://code.visualstudio.com/)

Plugins:

- **Prettier**: by installing this and enabling format on save, the code will automatically be formatted with the included Prettier config file. To enable auto format in VSCode:
  - Install the Prettier plugin
  - In your IDE, press CMD + SHIFT + P (you should get a pop-up with a greater than sign `>`)
  - Type in "preferences" and select "Preferences: Open settings (JSON)"
  - Ensure that the following fields are set:

`"editor.defaultFormatter": "esbenp.prettier-vscode"`

```
 "[javascript]": {
    "editor.formatOnSave": true
  }
```

`"editor.formatOnSave": true`

Bear in mind that Prettier works as well with some [other editors](https://prettier.io/docs/en/editors.html). If the editor that you are using is not supported, please run `yarn format`.

### Set up the component library jisc-react-components

1. Clone the repository: `git clone git@github.com:JiscSD/jisc-react-components.git`
2. `cd jisc-react-components`
3. Ensure your Node version and yarn versions correspond to the pre-requisies above
4. `yarn install`

#### Additional commands

These should be run in the root directory of the `jisc-react-components` directory

- `yarn start` builds the library and watches for updates to then re-build
- `yarn check-format` checks whether the files are formatted correctly
- `yarn format` formats all files according to the prettier config
- `yarn test` runs lint, build, and unit tests including coverage
- `yarn test:build` tests whether the project is able to build correctly
- `yarn test:ci` runs tests designed for the continuous integration pipeline, including lint, build, prettier, unit tests, and test coverage
- `yarn test:coverage` runs the unit tests and coverage to check how much of the code is covered by unit tests
- `yarn test:lint` runs the lint test
- `yarn test:unit` runs the unit tests whilst watching for changes
- `yarn storybook` starts the storybook server
- `yarn test:vreg` runs the [visual regression tests](#visual-regression)
- `yarn vreg-approve` approves the current status of [visual regression tests](#visual-regression)

### Set up the playground application

1. From the root directory of `jisc-react-components` then `cd playground`
2. `yarn install`
3. `yarn start`

### Visual Regression

Prerequisites:

- Make sure you have the latest packages installed by running: `yarn install` in the base folder.
- Have docker daemon running _[how to install docker](https://docs.docker.com/engine/install/)_

The codebuild pipeline will run on every commit pushed to remote on AWS, but if you need to run it locally you can:

1. Run `yarn test:vreg`
1. Check the `.loki` folder to see if there were any differences (tests will fail if this happens).

Approving the diferences:

1. You should have run the visual regression test as stated above first.
1. If you're happy with the changes in the difference folder just run `yarn test:vreg-approve` that will update the reference files.
1. Run `yarn test:vreg` and see how all the visual regression tests pass now.
1. Commit the updated reference files to git.

For more information about Loki you can check their [documentation page](https://loki.js.org/getting-started.html).

On the pull request you can see the visual regression pipeline on every commit as seen here `jisc-ui-loki`:

![image](https://user-images.githubusercontent.com/71711646/123122560-0745ae00-d43e-11eb-8f60-860e30fc89f6.png)

You can see the generated report at [https://jisc-ui-loki.s3.eu-west-1.amazonaws.com/pr/PR_ID_NUMBER/report.html](https://jisc-ui-loki.s3.eu-west-1.amazonaws.com/pr/PR_ID_NUMBER/report.html) (replace PR_ID_NUMBER in the url)

## Usage

Install the following packages:

```
// If using yarn
yarn add @fortawesome/fontawesome-svg-core @fortawesome/free-solid-svg-icons @fortawesome/react-fontawesome @material-ui/core

// If using npm
npm install @fortawesome/fontawesome-svg-core @fortawesome/free-solid-svg-icons @fortawesome/react-fontawesome @material-ui/core
```

Basic example:

```
import { JiscThemeProvider, PageHeader } from '@jisc/jisc-react-components';

function App() {
  return (
    <JiscThemeProvider>
      <PageHeader title="Hello world" />
    </JiscThemeProvider>
  );
}

export  default  App;
```

## Developing components

### Git Hooks

This project uses [git hooks](https://www.atlassian.com/git/tutorials/git-hooks) configured by using the npm package called [`husky`](https://typicode.github.io/husky/#/) algonside [`lint-staged`](https://github.com/okonet/lint-staged). This means that every time you _commit_ code to the repository some scripts/actions will be fired before letting you commit, if any of them fail, the commit will be discarded. These are:

- On Commit (`yarn test`):
  - On the staged files (`yarn lint-staged`):
    - Linting all the codebase with `ESLint`
    - Formatting the codebase with `prettier`
  - Build the library (`yarn test:build`)
  - Audit the dependencies (`yarn audit`)
  - Run all the tests + coverage (`yarn test:coverage`)
- On Push: N/A

_*(on the right you can read the actual command that will automatically run, you can run them invidually before commiting your code)*_

[WIP]

## Development guidelines

1. [Internal coding standards for React applications](https://jiscdev.atlassian.net/l/c/f0fszbWn)

[TODO]

---
_Source: https://npm.io/package/@jisc/jisc-react-components · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._