npm package: @springtree/eva-suite-ui
Description: Shared React component library for the EVA Admin suite
Latest version: 2.29.0

# EVA Suite UI

This package contains reusable UI components meant for EVA-Suite and should be used in React `(>=16.8.0)`.
The goal of this package is to provide developers with a managed and consistent set of UI components to build EVA Suite applications.
The focus is on small reusable and focussed components with high fidelity and consistent styling.

Most components are based on the [Material-UI](https://material-ui.com/) framework.
We extend them to reduce the amount of options they offer to simplify how we use them in our applications.
For example: A TextField component from Material-UI contains the prop `variants`.
You can choose 3 variants in this prop but we only use one.

The last reason we build our own components is because not every UI component is a Material UI component.
There are also custom components like `AutoComplete` that is built with [Downshift](https://github.com/downshift-js/downshift).
Components like `StatusLabel` or `Card` are done without the Material UI framework.

## Usage

Install the EVA Suite UI module from npm:

```bash
npm i @springtree/eva-suite-ui
```

Please check the [documentation](https://springtreesolutions.github.io/eva-suite-ui) for component details.

## Development

Check out the repository and run npm install to get started:

```bash
git clone git@github.com/springtreesolutions/eva-suite-ui.git
cd eva-suite-ui
npm install
```

This repository is divided in 4 sections:

- The built version of the components (`/dist`)
- A playground environment where you can render the components (`/playground`)
- Storybook integration. `npm run storybook:start`
- Playroom integration. `npm run playroom:start`

### Commands

- `npm start` => This command will build and watch the exported components from `src/index.ts`. Although when you render the components in playground, it is not really needed.
- `npm run build` => This command will make a build in the `/dist` folder.

Deployment is managed through the CI through pull request to the `master` branch.
Versions are managed using [semantic-release](https://github.com/semantic-release/semantic-release) so you should never set it manually in the `package.json` file.

## Playground environment

While creating new components, or making adjustments to existing components it would be nice to have an environment where you can see them.
An environment has been added for this purpose in the playground folder.
To use the playground application you need to do the following:

1. `cd playground` and then you can add `npm i`.
2. Now you can run `npm start` and you will open up a window for you.

The application uses [parcel](https://parceljs.org/) and has nice HMR capabilities. Sometimes when it seems that your screen did not change, you can either try to reload, or restart.

## Storybook integration

All our components should be documented.
This is done using Storybook.
Storybook writes its documentation in the MDX-format.
This is a Markdown format combination with JSX.

Start storybook by running `npm run storybook:start`.
This command should open up your browser on [https://localhost:9009](https://localhost:9009).
The stories have 2 tabs.
The 'canvas' tab shows you the component without any other information.
The 'Docs' tabs show you all the components, a Props table and all information that has been written in to the story.

### Write a Storybook story

When adding a new components it is important to document it.
We can give background information on the reasoning behind the component and how to best use it.
Any relevant notes from the designer could also be beneficial.
To add a story create a file to the component folder: `_ComponentName.stories.mdx_`

```javascript
import { Meta, Story, Preview, Props } from "@storybook/addon-docs/blocks";
import Checkbox from './Checkbox';

<Meta title="Checkbox" />

# Checkbox component
## Base
Add description...

<Preview>
  <Story name="Base">
    <div style={{display: 'flex', flexDirection: 'column'}}>
      <Checkbox>Checkbox label</Checkbox>
      <Checkbox>Checkbox label</Checkbox>
      <Checkbox>Checkbox label</Checkbox>
      <Checkbox>Checkbox label</Checkbox>
    </div>
  </Story>
</Preview>

## Pre-filled checked options
Add description...

<Preview>
  <Story name="Prefilled checked options">
    <div style={{display: 'flex', flexDirection: 'column'}}>
      <Checkbox>Checkbox label</Checkbox>
      <Checkbox checked>Checkbox label</Checkbox>
      <Checkbox>Checkbox label</Checkbox>
      <Checkbox checked>Checkbox label</Checkbox>
    </div>
  </Story>
</Preview>

## Props
<Props of={Checkbox} />
```

The `Meta` component is used to add the title of the folder where the component will be stored.
The `Preview` and `Story` components are the wrappers around the component you want to add. Make sure that the name of the story is unique.
The `Props` component shows a list of props on the component.
You can see a live version of the storybook at [Eva Suite UI Storybook](https://eva-suite-ui.netlify.com/storybook).
When the master branch gets updated, Netlify triggers `npm run storybook:build` and deploys it.

## Playroom integration

After seeing [this talk](https://www.youtube.com/watch?v=orPcyJMJh7Y&t=1s) by Mark Dalgleish we wanted to add a playground for our components.
The statement of Playroom is 'Design with JSX, powered by your own component library.'.
It let's you design simultaneously across a variety of screen sizes based on JSX.
You can create fast mockups with it and share them via a URL.
You can see a deployed version on [Eva Suite UI Playroom](https://eva-suite-ui.netlify.com/playroom).

When the master branch gets updated, Netlify triggers `npm run playroom:build` and deploys it.