<p align="center">
  <a href="https://legalplace.fr/">
    <img align=top src="./src/assets/img/logo-lp.svg" alt="Storybook" width="400" height='auto'/>
  </a>
</p>
<p align="center">
  <h2 align="center">+</h2>
</p>
  <br /> 
<p  align="center">
    <a href="https://storybook.js.org/">
    <img align=top src="https://user-images.githubusercontent.com/321738/63501763-88dbf600-c4cc-11e9-96cd-94adadc2fd72.png" alt="Storybook" width="400" height='auto'/>
  </a>
</p>
<br /> 
<p  align="center">
  <h1 align="center">Legalplace's Component library</h1>
</p>


<center>
  <img src="https://raw.githubusercontent.com/storybookjs/storybook/master/media/storybook-intro.gif" width="100%" />
</center>

## Getting Started
___
Clone this project.

Then from the project directory, run:

```yarn```
<br /> 

Now, run the app in development mode by running .<br /> 

```yarn start```
<br /> 

The app will run on [http://localhost:9009](http://localhost:9009) in the browser.

<br />

## Upgrading Storybook and structural packages
___

Upgrading the Storybook package and any important structural package should only be done via the "Upgrade" branch. 
This is to avoid having different versions of Storybook on different branches and cause problems and conflicts.

Note: Before any upgrade via the Upgrade branch, you must be up to date with the master branch in order to avoid conflicts also.
Also, when submitting your Merge Request, be sure not to delete the branch on merge.

Note: The Storybook is frequently updated, often for minor fixes and thus should not be applied everytime

## Building Components
___
### __Approach__

The purpose of a Storybook is to use React's approach of breaking down UIs into reusable components but with the capability of using them accross different apps.

Thus, components should not have any logic in them. They should be project agnostic in order to be portable to any app. They should only receive props, whether data or callback functions.

Our aim is to never duplicate components and styles but reuse them as much as possible.


### __Folder and file structure__

#### __Folders__

All components should go in the `components` folder and have their own folder containing all of their code.

The ```pages``` folder serves to put together the components of a specific page in order to test that they are displayed correctly.

```
components
└── MyFirstComponent
└── MyNextComponent
└── ...
...
└── Pages     
    └── Checkout

```

#### __Files__

Each component's folder will contain it's main file, styling, story and tests.

The main file should be used to define it's props and typings (if shared between components it should be exported to an external file).

The styling will live in a ```.style.tsx``` file (see below for more).

Every component displayed in the front-end should have a story to document it. This means it should have a ```.stories.tsx``` file alongside it.

In the case of pages, a ```.stories.tsx``` file can group several component's stories into one file. This is usually the case for a specific topic, page, purpose or usage.

All components should also be tested and the tests will be written in a ```.test.ts``` file (coming soon).

```
components
└── MyFirstComponent
    └── MyFirstComponent.tsx
    └── MyFirstComponent.style.tsx
    └── MyFirstComponent.stories.tsx
    └── MyFirstComponent.test.ts
└── MyNextComponent
    └── MyNextComponent.tsx
    └── MyNextComponent.style.tsx
    └── MyNextComponent.stories.tsx
    └── MyNextComponent.test.ts
└── ...
...
└── Pages    
    └── Checkout
        └── PricingPage.tsx
        └── PaymentPage.tsx
        └── Checkout.stories.tsx
```
<br />

Storybook will then look for your ```.stories.tsx``` in order to display them automatically, as below:

<br />

![alt text](src/assets/img/documentation/stories_list.png "List of stories in Storybook")

<br />

### __Styling__

#### __Styled-Components__

Our Storybook's components are entirely based on the [Styled-Components](https://styled-components.com) library for styling.

Our objective is to never use ```.scss``` files as Styled-Components provide the same capabilities as SCSS along with the power of CSS-in-JS which allows to scope styling to the component level. This way only the styles necessary to the components actually mounted are loaded. 

As mentioned above, a functionnal component's Styled Components must be defined inside a ```.style.tsx``` file 


#### __Global Styling__

SC's GlobalStyles and theming features enable us to easily define global styling properties and variables which will be shared across all of our apps and components.

##### __Global Styles__

Any styling which must be applied to the whole app needs to live in the ```globalStyles.ts``` file at the root of the ```/src``` directory. 

For ex: ```fonts-faces```, ```font-size``` definitions, ```body``` or ```html``` styling.

##### __Themes__

Themes are also defined in the storybook and shared across projects and live in a ```myTheme.ts``` file. 

Their purpose is to provide a source of truth for shared styling properties. This will save dev time and avoid mistakes/confusions which come with repeating code and typo errors.

They are basically objects containing styling variables as ```key: 'value'``` pairs and are injected via Styled-component's ```<ThemeProvider>``` wrapper component.

Themes will contain definitions of colors, spacings, font names and any shared styling property just like any scss variables files. They can also include shorthand strings for better ease.


```
export const lpTheme = {
  legacyPhoneGreen: '#34C25C',
  grey00: '#FFFFFF',
  grey50: '#FBFCFD',
  grey100: '#F6F9FC',
  grey200: '#DEE2E6',
  grey300: '#BDC4CB',
  ...
  boxShadowTooltip: '0 5px 5px 0 rgba(0,0,0,.1)',
  boxShadowTooltipArrowLeft: '-3px 5px  5px 0 rgba(0,0,0,.1)',
  ...
}
```

More [documentation](https://styled-components.com/docs/advanced) on how to use a theme's variables.


##### __Shared Elements and Resets__

All common elements which require base styles or style resets live in the ```Utils``` folder in the ```CommonElements.tsx``` file. 

This might be useful to reset ```ul``` or ```li``` elements to remove unwanted native list styles. Or to have paragraph and heading elements without margins for example.

```
// imports
export const ParagraphXs = styled.p`
  font-size: ${(props) => props.theme.fontSizes.xsmall};
  margin: 0;
`

export const BaseList = styled.ul`
  list-style: none;
  padding: 0;
  margin: 0;
  width: 100%;
`
...
```

## __Testing__
___
### __Mocks__

In order to test your component's props and rendering, you will need to generate mock data. 

Since the components must stay agnostic to any app, no API calls should be made to use data.

Instead, you should generate fake data in the ```mocks``` folder, in a file named after the component which will use it. 

Bear in mind, the component should not adapt to the data so your file should conform to the typing you initially set on the component's props.

### __Local Testing__

Once your components are ready in the storybook, you must check how they behave within the app you intend to use them in and if the data received is correct.

This implies the target app (ex: WizardX) to be connected to the local version of the storybook instead of using the actual package.


As of now, we will be using the ```yarn link``` feature to create a symlink between the storybook project and the target app project.

This part is slightly tricky and you should the following steps:

1. From the storybook run ```yarn build``` 
2. Then run ```yarn link```  
3. From the target app (ex: WizardX) run ```yarn link @legalplace/storybook``` to replace the package with the symlink to the local storybook
4. Because of a Styled-components issue the storybook must use the same React, React-dom and Styled-Components package as the target app or it will crash. So each of these packages must be linked as well:
    * From the target app, navigate to the ```react```, ```react-dom``` and ```styled-components``` folders inside the ```node_modules``` directory.
    * Within each of these folders run ```yarn link``` as well.
5. From the Storybook folder, run the script ```yarn link-all```. This will allow the storybook to use the symlink to each of these packages.
6. All set!
6. Run ```yarn build``` in the storybook to see any new changes in the target app.

Once you are done testing your local components:

1. From the storybook, run ```yarn unlink-all``` to remove the symlink to the target app's ```react```, ```react-dom``` and ```styled-components``` packages.
2. From the target app run ```yarn unlink @legalplace/storybook```.

In both cases, you may need to run ```yarn install --force``` to restore all your packages to normal.

If you run into any issues, delete your ```node_modules``` directory, run ```yarn``` to reinstall all packges and repeat the process above.

### __Unit Tests__

Coming soon


## __Release Process__
___
<br />

Once your component or feature is tested locally (as explained above), then you are ready to release a new version of the Storybook package ! 


To do this, simply run ```yarn release```. This will prepare the storybook for publication by automatically bumping the package version, bundling the code and create the release tag.

Then run ```git push --follow-tags origin MYBRANCH``` or simply ```git push --follow-tags```. 

No need to run ```yarn/npm publish``` as the CI will publish the new version.

Please note, in order to avoid too many version bumps, you should not release a new version for test purposes unless necessary. 

Instead, you should test your components locally by following the steps listed in the "Local Testing" section beforehand.

## Fix Load Stripe Problem 
use ReactStripeScriptLoader to make sure the script is loaded before calling StripeProvider. [link](https://medium.com/@ozluy/loading-stripe-script-if-necessary-189f228e0f34)

## Updated until
aa8dd52a4c5d438e70f7605d68e530f729b38312 (master)