# gdb-web-shared-components
Managed by Terraform.

This repository contains set of React components intended to be used across all projects to keep UI consistent;

### How to use
- This library can be installed only if project has `.npmrc` file that contains a link to our private registry;
To get the private registry link, ask DevOps team;
- This library considers `react`, `react-dom` and `frontend-shared-icons` as `peerDependencies` and expects that `react`, `react-dom` and `frontend-shared-icons` are available as dependencies in your project;
- CSS and JavaScript code is distributed separately;
To make sure that components from this library displayed correctly, include CSS file with styles of this library as the project asset.
- The main font for typography is `Montserrat` (400,500,600,700), you need to include it into project;

Use `yarn add gdb-web-shared-components` to install library to your project

Import library styles (root file of you app is a good place to do that):
```
import 'gdb-web-shared-components/dist/esm/vendors.css'
import 'gdb-web-shared-components/dist/esm/index.css'
```

#### Files structure
- Each individual components have to be placed in separate folder inside `./src/components`
- All the files related to component lives inside component folder
- `<ComponentName>/components` - this folder contains sub-components
- `<ComponentName>/types.ts` - contains types we need to use across the component
- `<ComponentName>/helpers.ts` - contains helpers and useful methods for the component
- `<ComponentName>/index.ts` - exports everything that could be needed for use (component, sub-components, types, helpers). Please do not export things we do not need outside
- `./src/components/index.ts` - global components export

#### Types convention
- All component types that we expose outside have to start with component name (e.g. `SelectProps`, `DatePickerValue`, `InputPreferences`)
- Do not mark interfaces specially ( ~~`IMyInterface`~~ or ~~`MyFooInterface`~~) unless it's idiomatic in its environment. When introducing an interface for a class, give it a name that expresses why the interface exists in the first place (e.g. class `TodoItem` and interface `TodoItemStorage` if the interface expresses the format used for storage/serialization in JSON).
- Prefer `clearValue(): void;` instead `clearValue: () => void;`
- Names must be descriptive and clear to a new reader. Do not use abbreviations that are ambiguous or unfamiliar to readers outside your project, and do not abbreviate by deleting letters within a word
- We should not `extends` or use types from external libraries such as `material ui`, `react day picker`, etc., that we exports!!!

#### Gradient border

**Important**

There is a list of components that are dependent on ```BorderSvg``` component:
```Toasts```
Thus it's important to include ```BorderSvg``` component to your project once if you are using any of these components.

Additionally, if there is a need to use gradient border for semi-transparent component in your project, you can include ```BorderSvg``` and use it's clipPath as follows:
```
&::after {
  content: '';
  position: absolute;
  top: -1px;
  left: -1px;
  bottom: -1px;
  right: -1px;
  clip-path: url('#borderSvgPath');
}
```

#### Toasts
To use Toasts in your project, you need to import ```SnackbarProvider``` and wrap in it components that should be able to manipulate toasts (it would be better to do it on the top level).

Then you just need to import ```useManageToasts``` hook and use it to show or close toasts:
```
const { openToast, closeToast } = useManageToasts(theme);
openToast(toast);
closeToast(toast.id);
```

### How to develop

**PLEASE READ THIS IMPORTANT NOTICE!**

On every commit `husky pre-commit` will automatically bump package version up with a `--patch` version by default.

If `--major` or `--minor` version needed, bump it up manually using `yarn version` command.

#### Install
To install dependencies please use `yarn` package manager default workflow, by using `yarn` command in terminal;

#### Build
Run
```yarn rollup```
to build CJS and ESM distribution packages with types definitions;

In case of need for `storybook` static files to distributing and hosting, please run
```yarn build-storybook``` command in terminal;

#### Test
To run tests, ```yarn test``` command should be used;
Test are implemented using Jest and React Testing Library;

#### Lint
To run ESLint and Stylelint, use ```yarn lint```, ```yarn lint:style``` commands;

#### Format
To format code via Prettier use ```yarn prettier:write``` commands;
To check formatting on matching Prettier config use ```yarn prettier:check```

#### Storybook
To run `storybook`on a local env, use `yarn storybook` command in terminal;

#### Run
To run and review existing components, please use `storybook` command;
All existing components should be available in `storybook`;

To learn how to work with repository, please read [Wiki](https://github.com/filtr/gdb-web-shared-components/wiki)

#### Styling
To keep styling consistent we use [BEM](https://getbem.com/naming/) methodology;

`bem` util can help you to write classes, usage:
```
  const className = bem('block');

  className(null); /* block */
  className(null, { isActive: true }); /* block block--isActive */

  className('element'); /* block__element */
  className('element', { isDisabled: true }); /* block__element block__element--isDisabled */
```

Important Note: If you're overriding third party library styles, do not forget ot exclude this class from hashing.
This can be done in `./rollup.config.js`, use `excludeHashingClassesSubstrings`and add there a substing that can indicate the library class override.