README.md

# ce-ui-common
**Common React hooks and components for CE UI applications**

## How to install this module in your app

### Prerequisites
First, make sure you have installed all of `ce-ui-common`'s peer dependencies into your app. You can find the list of peer dependencies in this repository's `package.json`.  

Latest lts (18.12.1) version of node should be sufficient. Anything above version 7 of npm should automatically install the peer dependencies of the `package.json`.

### Installation
You can install `ce-ui-common` in a dependent app directly from this git repository:

```
npm install git+https://gitlab.esss.lu.se/ccce/dev/ce-ui-common.git
```

You can use the `#<commit-ish>` syntax to install specific commits, branches, tags, even version ranges. For example, to install the `develop` branch, you can use: 

```
npm install git+https://gitlab.esss.lu.se/ccce/dev/ce-ui-common.git#develop
```

See the [npm-install docs](https://docs.npmjs.com/cli/v6/commands/npm-install) for more info about this syntax.

## Styling and design with Material UI

The styled and styling of the components are done with Material UI.  
If you have a need for changing anything css wise please refer the Material UI documentation:  
https://mui.com/system/styled/  
https://mui.com/material-ui/customization/theming/  
https://mui.com/material-ui/guides/interoperability/#styled-components  
https://mui.com/system/getting-started/the-sx-prop/  

## Available Scripts

In the project directory, you can run:

### `npm test`

Launches the test runner in the interactive watch mode.\
See the section about [running tests](https://facebook.github.io/create-react-app/docs/running-tests) for more information.

### `npm run cypress:run` & `npm run cypress:open`  

This will run cypress tests on the components that's been setup with at cypress testing library test.  
`npm run cypress:run` will run in headless state as for `npm run cypress:open` will open the cypress app gui and run in a browser.

### `npm run storybook`

Starts the interactive storybook server (see https://storybook.js.org/)

### `npm build storybook`

Builds the static storybook for this project (see https://storybook.js.org/)

### `npm run watch`

Starts a file watcher process which executes `npm run devInstall` whenever changes are made to files in the `src` directory. Now you can see live updates from edits to `ce-ui-common` in your client app's dev server (see discussion `devInstall`).

### `npm run devInstall`

Transpiles the module and rsyncs it tp `$CE_DEV_INSTALL_DIR/ce-ui-common`. This is useful when you are simultaneously working on this `ce-ui-common` and some dependent app. You can set `CE_DEV_INSTALL_DIR` in `.env.development` like this:

```
CE_DEV_INSTALL_DIR="somewhere/lib"
```

Once you have configured the install directory, you can start using your development version of ce-ui-common in the dependent app like this:

```
ce-ui-common$ npm run devInstall
ce-ui-common$ cd /path/to/dependent-app
dependent-app$ npm install --no-save somewhere/lib/ce-ui-common
```

This will create `ccce-ui-common` as a symolic link to the install dir in the dependent-app's `node_modules`, but it won't update the dependent-app's `package.json`. Whenever you make changes to ce-ui-common and need to push changes to the client app, just run `npm run devInstall` again. If the client app is using create-react-app, this will even trigger a hot reload of the dev server!

Note:  If you have some existing version of `ccce-ui-common` installed in the dependent-app (like from npm or git), `npm install --no-save somewhere/lib/ce-ui-common` will simply overwrite it with the local version. This is great for testing your local changes to `ce-ui-common` during development without screwing up the app's dependencies. When you want to revert back to the original version, just run: `npm install` again.

Warning! If `CE_DEV_INSTALL_DIR` or any of its ancestors contain a `node_modules` directory, webpack will try to resolve imports using those node modules! In other words, don't set `CE_DEV_INSTALL_DIR` to the child of any app or library project. Use some other external location instead.

### Fix when dev server in dependent-app won't pick up changes

Sometimes, especially when switching between an external and local version of the package, the webpack dev server in your client app will not show the new versions of the files even though you can see the new versions in `dependent-app/node_modules/ce-ui-common`. This is because the dev server has cached some files to make startup faster.

To fix this, simply stop the dev server, delete the cached files:
```
cd /path/to/dependent-app
rm node_modules/.cache/default-development/*
```
and restart the dev server.

### `npm run dist`

Transpiles the code using babel and stores the output in `dist`. Check `.babelrc` if you need to ignore certain files during transpilation or change some other configuration.

### `npm run pack`

Transpiles code using Babel and packages the module up into a .tgz

Warning! This is not the same as `npm pack`. It executes the extra step of transpiling the code with `npm run dist` before running `npm pack` to create the tarball. It is possible to automatically execute the transpilation by putting `npm run dist` step into the a `prepare` script. However, npm runs `prepare` when installing a module locally and this causes all sorts of problems in the scenario where a client app is installing the packaged version of this library.

### `npm run eject`

**Note: this is a one-way operation. Once you `eject`, you can't go back!**

If you aren't satisfied with the build tool and configuration choices, you can `eject` at any time. This command will remove the single build dependency from your project.

Instead, it will copy all the configuration files and the transitive dependencies (webpack, Babel, ESLint, etc) right into your project so you have full control over them. All of the commands except `eject` will still work, but they will point to the copied scripts so you can tweak them. At this point you're on your own.

You don't have to ever use `eject`. The curated feature set is suitable for small and middle deployments, and you shouldn't feel obligated to use this feature. However we understand that this tool wouldn't be useful if you couldn't customize it when you are ready for it.

## Getting Started with Create React App

This project was bootstrapped with [Create React App](https://github.com/facebook/create-react-app).

## Learn More

You can learn more in the [Create React App documentation](https://facebook.github.io/create-react-app/docs/getting-started).

To learn React, check out the [React documentation](https://reactjs.org/).

### Code Splitting

This section has moved here: [https://facebook.github.io/create-react-app/docs/code-splitting](https://facebook.github.io/create-react-app/docs/code-splitting)

### Analyzing the Bundle Size

This section has moved here: [https://facebook.github.io/create-react-app/docs/analyzing-the-bundle-size](https://facebook.github.io/create-react-app/docs/analyzing-the-bundle-size)

### Making a Progressive Web App

This section has moved here: [https://facebook.github.io/create-react-app/docs/making-a-progressive-web-app](https://facebook.github.io/create-react-app/docs/making-a-progressive-web-app)

### Advanced Configuration

This section has moved here: [https://facebook.github.io/create-react-app/docs/advanced-configuration](https://facebook.github.io/create-react-app/docs/advanced-configuration)

### Deployment

This section has moved here: [https://facebook.github.io/create-react-app/docs/deployment](https://facebook.github.io/create-react-app/docs/deployment)

### `npm run build` fails to minify

This section has moved here: [https://facebook.github.io/create-react-app/docs/troubleshooting#npm-run-build-fails-to-minify](https://facebook.github.io/create-react-app/docs/troubleshooting#npm-run-build-fails-to-minify)