# Design React Kit

[![Join channel #design-devel](https://img.shields.io/badge/Slack%20channel-%23design--devel-blue.svg)](https://developersitalia.slack.com/messages/C7VPAUVB3/)
[![Get an invitation for Slack](https://slack.developers.italia.it/badge.svg)](https://slack.developers.italia.it/)

*Read this in other languages: [Italiano](README.md).*

## Intro

**Design React kit** is a set of React components that implements [Bootstrap Italia](https://italia.github.io/bootstrap-italia/) and [Design UI Kit](https://github.com/italia/design-ui-kit) styling, as [shown on InVision](https://invis.io/TWMUZS6VFP5).

Components are showcased with [Storybook](https://storybook.js.org/).

Public version of Storybook (built from `master` branch) is available here: https://italia.github.io/design-react-kit.

## Table of contents

<!-- START TOC generated by doctoc please keep a comment here to allow automatic updating -->
<!-- DO NOT MODIFY THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->

- [Requirements](#requirements)
- [Usage](#usage)
  - [Peer dependencies](#peer-dependencies)
- [Compiling Storybook](#compiling-storybook)
- [How to create new components](#how-to-create-new-components)
- [Publishing](#publishing)
- [Continuous integration](#continuous-integration)
  - [`build` job](#build-job)
  - [`deploy-github-pages` job](#deploy-github-pages-job)
  - [`npm-publish` job](#npm-publish-job)

<!-- END doctoc generated TOC please keep the comment here to allow automatic updating -->

### Requirements

* NodeJS
* Yarn

## Usage

To use Design React as a dependency in your React project you can install it from [npm](https://www.npmjs.com/~italia). We suggest to use `create-react-app` to create a new React webapp from scratch as follows:

```sh
$ create-react-app nome-app
$ cd nome-app
$ yarn add design-react-kit --save
```

## Add bootstrap-italia and fonts

The `design-react-kit` module does not include the CSS and font files in the bundle, so this needs to be installed as well:

```sh
$ yarn add bootstrap-italia typeface-lora typeface-roboto-mono typeface-titillium-web --save
```

## App.js

Then, you just need to import CSS e font editing `./src/App.js` as shown:

```jsx
import React from 'react';
import './App.css';
import { Alert } from 'design-react-kit';
import 'bootstrap-italia/dist/css/bootstrap-italia.min.css';
import 'typeface-titillium-web';
import 'typeface-roboto-mono';
import 'typeface-lora';

const App = () => {
    return (
        <Alert>This is an Alert</Alert>
    );
};

export default App;
```

#### Loading Fonts

The Bootstrap Italia theme defines a specific set of font typefaces to work: `titillium-web`, `roboto-mono` and `lora`. The loading of this set of fonts can be left to the browser or controlled: in this last case it is necessary to use the `FontLoader` component exported by the library.
Declaring the `FontLoader` on top of the Application tree it is enough to trigger the loading of the fonts.

As alternative it is required to manually manage the loading via the `webfontloader` package:

```js
const WebFont = require('webfontloader')
WebFont.load({
    custom: {
        families: [
        'Titillium Web:300,400,600,700:latin-ext',
        'Lora:400,700:latin-ext',
        'Roboto Mono:400,700:latin-ext'
        ]
    }
})
```

### Peer dependencies

The library does not include `react` and `react-dom`, avoiding versions clashing and increasing the size of the bundle.
For this reason, for local development it will be necessary to manually install dependencies.

The command to be executed is
```sh
$ yarn install --peers
```
or alternatively manually
```sh
$ yarn install react react-dom
```

## Compiling Storybook

Clone the repo and run `yarn` to install the dependencies.
Then run the `yarn storybook:serve` command to start the development server.

Storybook will therefore be available at http://localhost:9001/

![storybook](/assets/storybook-screenshot.jpg?raw=true)

Public version of the Storybook is available [here](https://italia.github.io/design-react-kit).

Storybook has been enriched with some `addons` that make it more talented. Check dependencies on the `package.json` file for details.

## How to create new components

This section explains how to create new components in the repository.
All components reside in the `components` directory: each component is a folder with all that is needed to make it work. *Storybook* stories are instead under `stories`.

i.e. the `Button` component is shown below the `src/components/Button` path and its structure is as follows:

```
src
    └── components
        └── Button
            ├── Button.js
stories
    └── Button
        ├── Button.stories.js
```

Some basic rules for structuring the components:

* JS file component files use JSX syntax.
* The `.stories.js` files only restore the relative component only.

Once you have created a new component, with its history, starting *Storybook* will be able to check that everything works as it should.

## Publishing

A command is available to reach a static version of the Storybook catalog as it can be deployed without using a webserver.

```sh
$ yarn storybook:build
```

Static pages obtained from the compilation process generate under the `storybook-static` directory.

## Building library

To build the library and add files into the `dist` folder:

```sh
$ yarn build
```

## Browsers support

As stated on the Guidelines for Public Services Design, within the Section [6.3.1.2.1. Supporto browser](https://docs.italia.it/italia/designers-italia/design-linee-guida-docs/it/2020.1/doc/user-interface/lo-sviluppo-di-un-interfaccia-e-i-web-kit.html#strumenti), here's a list of supported browsers for this Design Kit.
The list is here available in the `browserslist` format:

```json
"browserslist": [
    "defaults",
    "ie 11",
    "not ie_mob 11",
    "not op_mini all",
    "edge >= 13",
    "safari 11"
]
```

The same list is also available in the `package.json` file. Unfortunately, it's not possible to extend this `browserslist` configuration yet for [security concerns](https://github.com/browserslist/browserslist#shareable-configs).

## TypeScript typing definitions 

To generate Typescript typing definitions file:

```sh
$ yarn typescript:dts
```
