locomotive-boilerplate/docs/grid.md

# Grid system

* [Architectures](#architectures)
  * [Styles](#styles)
  * [Build tasks](#build-tasks)
    * [Config file](#config-file)
* [Usage](#usage)
  * [Example](#example)
* [Limitations](#limitations)

## Architectures

The Grid System is meant to be simple and easy to use. To goal is to create a light, flexible and reusable way to build layouts.

### Styles

Some styles are needed to make it work properly :

* [`o-grid.scss`](../assets/styles/objects/_grid.scss): Object file where the default grid styles are set. Column numbers, modifiers, options.
* [`u-grid-columns.scss`](../assets/styles/utilities/_grid-column.scss): Utility file where it generates every possible column styles based on an array of media queries and column numbers.

### Build tasks

The generation of columns adds a lot of styles in the css output file. To solve that, a build task is set up to purge unused css generated by [`u-grid-columns.scss`](../assets/styles/utilities/_grid-column.scss) using [PurgeCSS].

#### Config file

Depending on your project, you will need to specify all the files that include CSS classes from the grid system. These files will be scanned by [PurgeCSS] to your compiled CSS files.

Example of a Charcoal project:

```jsonc
"purgeCSS": {
    "content": [
        "./views/app/template/**/*.mustache",
        "./src/App/Template/*.php",
        "./assets/scripts/**/*" // use case: `el.classList.add('u-gc-1/2')`
    ]
}

## Usage

The first step is to set intial SCSS values in the following files :

- [`settings/_config.scss`](../assets/styles/settings/_config.scss)

    ```scss
    // Grid
    // ==========================================================================
    $base-column-nb: 12;
    $base-column-gap: $unit-small;
    ```

    You can create multiple column layouts depending on media queries.

- [`objects/_grid.scss`](../assets/styles/objects/_grid.scss)

    ```scss
    .o-grid {
        display: grid;
        width: 100%;
        margin: 0;
        padding: 0;
        list-style: none;

        // ==========================================================================
        // Cols
        // ==========================================================================
        &.-col-#{$base-column-nb} {
            grid-template-columns: repeat(#{$base-column-nb}, 1fr);
        }

        &.-col-4 {
            grid-template-columns: repeat(4, 1fr);
        }

        &.-col-#{$base-column-nb}\@from-medium {
            @media (min-width: $from-medium) {
                grid-template-columns: repeat(#{$base-column-nb}, 1fr);
            }
        }
        // …
    ```

### Example

The following layout has 4 columns at `>=999px` and 12 columns at `<1000px`.

```html
<div class="o-container">
    <h1 class="c-heading -h1">Hello</h1>

    <div class="o-grid -col-4 -col-12@from-medium -gutters">
        <div class="o-grid_item u-gc-1/8@from-medium">
            <h2 class="c-heading -h2">This grid has 4 columns and 12 columns from `medium` MQ</h2>
        </div>

        <div class="o-grid_item u-gc-1/5@from-medium">
            <p>Lorem, ipsum dolor sit amet consectetur adipisicing elit. Expedita provident distinctio deleniti eaque cumque doloremque aut quo dicta porro commodi, temporibus totam dolor autem tempore quasi ullam sed suscipit vero?</p>
        </div>

        <div class="o-grid_item u-gc-5/9@from-medium">
            <p>Lorem, ipsum dolor sit amet consectetur adipisicing elit. Expedita provident distinctio deleniti eaque cumque doloremque aut quo dicta porro commodi, temporibus totam dolor autem tempore quasi ullam sed suscipit vero?</p>
        </div>

        <div class="o-grid_item u-gc-9/13@from-medium">
            <p>Lorem, ipsum dolor sit amet consectetur adipisicing elit. Expedita provident distinctio deleniti eaque cumque doloremque aut quo dicta porro commodi, temporibus totam dolor autem tempore quasi ullam sed suscipit vero?</p>
        </div>
    </div>
</div>
```

[PurgeCSS]: https://purgecss.com/