# Styles

Styling rules for Aura Design System with [SCSS](https://sass-lang.com/).

- [Styles](#styles)
  - [Setup](#setup)
    - [Installation](#installation)
    - [Start](#start)
    - [Folder structure](#folder-structure)
  - [Development](#development)
    - [Transforming](#transforming)
    - [Commands](#commands)
    - [Git Committs](#git-committs)
  - [Distribution](#distribution)
    - [Release](#release)
    - [Cache](#cache)
    - [Versioning](#versioning)
    - [Publishing](#publishing)
  - [Usage](#usage)
    - [Package](#package)
    - [CDN](#cdn)
    - [Implementation](#implementation)

## Setup

### Installation

Install **dependencies** :

```bash
~ npm i
```

### Start

Initiate **watcher**:

```bash
~ npm run start
```

**attention**: Make sure your **node** version is between `14 and 16`.

### Folder structure

- **settings/variables**: files with global **$variables**.
- **helpers**: files with **constructors** of classes and placeholders.
- **generic**: files with **generic** rules, including definition of custom properties in `:root`.
- **elements**: files with **html elements** styling.
- **tools**: files with additional utilities like **@functions**.

New files should be prefixed with `_[name].scss`.
New files should be listed on `index.scss` inside the corresponding folder.

## Development

Use the provided `index.html` to test the results in the browser.
Open the file and refresh when making any changes, as **livereload** is not available.

When adding new styles, ideally, each class should have a correspoding placeholder:

```scss
.flex,
%flex {
  display: flex;
}
```

This assures the system can be use with both`.scss`, `.html` and `.jsx` files.

### Transforming

[PostCss](https://postcss.org/) is set to transform `.scss` files during **build** process.
To add more plugins and options, check `postcss.config.js` file.

### Commands

Others available **commands** are:

- **linter**: runs the linter.

```bash
~ npm run lint
```

- **fixer**: runs linter and fixs possible issues.

```bash
~ npm run lint:fix
```

- **builder**: builds the compiled `.css` files via [node-sass](https://github.com/sass/node-sass).

```bash
~ npm run build
```

For more information about other **commands**, check the `scripts` section in `package.json` file.

### Git Committs

When committing any changes, **linter** runs to make sure code is formatted correctly, via [husky](https://github.com/typicode/husky) and [lint-staged](https://github.com/okonet/lint-staged).
If it throws an error, check the output and make sure to fix the issues.

## Distribution

### Release

Distribution is done with [bitbucket pipelines](https://bitbucket.org/product/features/pipelines).

When merging into `master` branch, the following processes occurr:

- **Installation** of dependencies
- **Linting** of files
- **Building** of compiled files
- **Release** of package in [npm.js](https://www.npmjs.com/)

When **pushing** into the repository, the first two processes occur.

When creating a **pull-request**, the first three processes occurr.

It's possible to make a release without **bickbucket pipelines** by running:

```bash
~ npm run release:manual
```

For more information of all processes check `bitbucket-pipelines.yml` file.

**attention**: Make sure to keep all unwanted files from distribution listed on `.npmignore` file.

**attention**: When Creating a `pull-request`, pipelines will trigger two times:

- `branch` pipe
- `pull-request` pipe

This is a limitation, so the `branch` pipe can be stopped manually to avoid two pipes running at same time.

### Cache

In order to increase the speed of [bitbucket pipelines](https://bitbucket.org/product/features/pipelines), a [cache](https://support.atlassian.com/bitbucket-cloud/docs/cache-dependencies/) for `node` is setup.
In case of installating new **packages** it's good to clean it beforehand, otherwise the **install** process will not contains the new **packages**, and the process might fail.

### Versioning

It's automaticaly done by [standard-version](https://www.npmjs.com/package/standard-version).

After updating `package.json` inside the pipelines with the `[new-version-number]`, a new commit is created in `master` branch:

```bash
chore(release): 0.0.[new-version-number]
```

### Publishing

It's done with Bitbucket's [deploy-to-npm](https://support.atlassian.com/bitbucket-cloud/docs/deploy-to-npm/) pipe.

Because it's [pushing back to the repository](https://support.atlassian.com/bitbucket-cloud/docs/push-back-to-your-repository/) it always creates an empty commit to trigger the publish.

After each **publish**, a new commit is created in `master` branch:

```bash
[skip ci] Trigger from pipelines release step.
```

**attention**: Make sure always pull `master` after each **release** so the two new commits are available locally.

## Usage

### Package

Install as a **package**:

```bash
~ npm install sdb-dd-styles --save
```

Import in your **application**:

```scss
/* styles.scss */

@import 'sdb-dd-styles';
```

### CDN

Compiled version are accessible via the following links:

- non-minified: [https://cdn.jsdelivr.net/npm/sdb-dd-styles/dist/styles.css](https://cdn.jsdelivr.net/npm/sdb-dd-styles/dist/styles.css)
- minified: [https://cdn.jsdelivr.net/npm/sdb-dd-styles/dist/styles.min.css](https://cdn.jsdelivr.net/npm/sdb-dd-styles/dist/styles.min.css)

```html
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/sdb-dd-styles/dist/styles.min.css">
```

### Implementation

Use as an `.scss` extend:

```scss
/** styles.scss */

div {
  @extends %flex;
}
```

Or CSS class in `.html` or `.jsx`:

```html
<!-- index.html -->

<div class="flex"></div>
```

```jsx
// index.jsx

<div class="flex"></div>
```