# `@salesforce-ux/sds-grid`

## About

The SDS grid system provides a flexible, mobile-first, device-agnostic layout system. It has features to control alignment, flow, and gaps.

## Installation

Use [npm][npm] to install the [SDS Grid](https://www.npmjs.com/package/@salesforce-ux/sds-grid):

```bash
npm install --save-dev @salesforce-ux/sds-grid
```

## Usage

The SDS grid system can be used in both light DOM and shadow DOM. The grid is used by applying attributes to your HTML. The SDS grid features a [mobile-first, responsive](https://developer.mozilla.org/en-US/docs/Learn/CSS/CSS_layout/Responsive_Design) layout system; built on [flexbox](https://www.w3.org/TR/css-flexbox-1/).

### Table of Contents

- [Initialize a grid container]()
- [Define the grid axis]()
- [Grid items]()
- [Defining widths]()
  - [Responsive widths]()
- [Add gaps between grid items]()
- [Force multiple rows]()
- [Defining grid container alignment]()
- [Defining grid item alignment]()

### Initialize a grid container

To initialize a grid container, set the `grid` attribute to your element.

```html
<div grid>...</div>
```

### Define the grid axis

By default, a grid flows left-to-right on a horizontal or x-axis. This behavior can be changed to flow right-to-left, top-to-bottom, and bottom-to-top.

**Left to right**

```html
<div grid axis="row">...</div>
```

**Right to left**

```html
<div grid axis="row-reverse">...</div>
```

**Top to bottom**

```html
<div grid axis="vertical">...</div>
```

**Bottom to top**

```html
<div grid axis="vertical-reverse">...</div>
```

### Grid items

A grid container will have 1 or more grid items to make up your layout. The direct descendants of a grid container are considered grid items. By being a grid item, you can modify its attributes independently or by the container.

```html
<div grid>
  <div>Grid item</div>
  <div>Grid item</div>
</div>
```

> A grid container is **required** to change the attributes of a grid item.

### Defining widths

A benefit of using flexbox for your layout is things will automatically adjust inflow based on its flex properties and the size of its children's content.

There are times (most the time) when you want to explicitly define a width on a grid item. You can accomplish this by adding a `size` attribute and a value to determines its width.

```html
<div grid>
  <div size="1:2">item</div>
  <!-- 50% -->
  <div size="1:2">item</div>
  <!-- 50% -->
</div>
```

The size attribute accepts a range of human-friendly values, you may choose to use `6:12` or `1:2`, both outcomes are `50%`. The second value should be based off the number of grid columns you have set for your parent container.

**Available Widths**

| Size    | Value     |
| ------- | --------- |
| `auto`  | `auto`    |
| `1:1`   | `100%`    |
| `1:2`   | `50%`     |
| `1:3`   | `33.333%` |
| `2:3`   | `66.667%` |
| `1:4`   | `25%`     |
| `2:4`   | `50%`     |
| `3:4`   | `75%`     |
| `1:5`   | `20%`     |
| `2:5`   | `40%`     |
| `3:5`   | `60%`     |
| `4:5`   | `80%`     |
| `1:6`   | `16.667%` |
| `2:6`   | `33.333%` |
| `3:6`   | `50%`     |
| `4:6`   | `66.667%` |
| `5:6`   | `83.333%` |
| `1:7`   | `14.28%`  |
| `2:7`   | `28.57%`  |
| `3:7`   | `42.85%`  |
| `4:7`   | `57.14%`  |
| `5:7`   | `71.42%`  |
| `6:7`   | `85.71%`  |
| `1:8`   | `12.5%`   |
| `2:8`   | `25%`     |
| `3:8`   | `37.5%`   |
| `4:8`   | `50%`     |
| `5:8`   | `62.5%`   |
| `6:8`   | `75%`     |
| `7:8`   | `87.5%`   |
| `1:12`  | `8.333%`  |
| `2:12`  | `16.667%` |
| `3:12`  | `25%`     |
| `4:12`  | `33.333%` |
| `5:12`  | `41.667%` |
| `6:12`  | `50%`     |
| `7:12`  | `58.333%` |
| `8:12`  | `66.667%` |
| `9:12`  | `75%`     |
| `10:12` | `83.333%` |
| `11:12` | `91.667%` |

> **Implementation Note**
>
> Be sure to stick within the available widths based on the grid columns you choose to use. For example, if you have established a 12 column grid, the grid items that are direct descendants should refer to the `size` associated to `12`.

**Good**

```html
<!-- 12 column grid -->
<div grid>
  <div size="8:12"></div>
  <div size="4:12"></div>
</div>
```

**Bad**

```html
<!-- unknown column grid -->
<div grid>
  <div size="2:3"></div>
  <div size="4:12"></div>
</div>
```

#### Responsive widths

Additionally, you can easily modify the width of an item at a defined breakpoint depending on the width of the viewport.

This can be done by appending `@` then the breakpoint definition of `x-small`, `small`, `medium`, `large`, or `x-large`. For example, `1:2@medium` would cause the grid item to take up 50% of its available width when the browsers viewport is larger than `768px`.

**Breakpoints**

| T-shirt size name | Breakpoint width |
| ----------------- | ---------------- |
| `x-small`         | `320px`          |
| `small`           | `480px`          |
| `medium`          | `768px`          |
| `large`           | `1024px`         |
| `x-large`         | `1280px`         |

### Add gaps between grid items

To add space between your grid items, you can add a `gap` attribute to your grid container. The `gap` attribute takes a t-shirt size name:

> **Implementation Note**
>
> For a child grid item to pick up the gap size set on the parent, the element is **required** to have a `size` attribute set. If you don't need an explicit width, i.e., 50%, you can add `size="auto"`.

**Gap Sizes**

| T-shirt size name | Value  |
| ----------------- | ------ |
| `xxx-small`       | `2px`  |
| `xx-small`        | `4px`  |
| `x-small`         | `8px`  |
| `small`           | `12px` |
| `medium`          | `16px` |
| `large`           | `24px` |
| `x-large`         | `32px` |
| `xx-large`        | `48px` |

### Force multiple rows

When setting widths to your grid items, once a row of items exceed a total width of 100% you can force them to wrap to multiple rows by adding `flow="wrap"` to your grid container.

By default, the grid items will not wrap.

```html
<div grid flow="wrap">
  <!-- Row 1 - 66.667% | 33.333% -->
  <div size="8:12"></div>
  <div size="4:12"></div>
  <!-- Row 2 - 50% | 50% -->
  <div size="6:12"></div>
  <div size="6:12"></div>
</div>
```

### Defining grid container alignment

Since the grids are built on flexbox, they allow us to do some interesting things with alignment on both a horizontal axis and vertical axis. You can add an alignment value to the `grid` attribute.

**Start of axis**

```html
<div grid="align-start">...</div>
```

```bash
|-----------------|
|[ ][ ][ ]        |
|-----------------|
```

**Center of axis**

```html
<div grid="align-center">...</div>
```

```bash
|-----------------|
|    [ ][ ][ ]    |
|-----------------|
```

**End of axis**

```html
<div grid="align-end">...</div>
```

```bash
|-----------------|
|        [ ][ ][ ]|
|-----------------|
```

**Evenly spaced along axis**

```html
<div grid="align-spread">...</div>
```

```bash
|-----------------|
|[ ]    [ ]    [ ]|
|-----------------|
```

**Equally spaced along axis**

```html
<div grid="align-space">...</div>
```

```bash
|-----------------|
|  [ ]  [ ]  [ ]  |
|-----------------|
```

#### Vertical alignment

> **Implementation Note**
>
> To vertically align elements on a cross-axis of a grid container, the elements need available vertical white space. This is usually achieved by having a height applied to the grid container.

**Start of vertical axis**

```html
<div grid="align-space" axis="vertical">...</div>
```

```bash
|-----------------|
|  [ ]  [ ]  [ ]  |
|                 |
|                 |
|-----------------|
```

**Center of vertical axis**

```html
<div grid="align-center" axis="vertical">...</div>
```

```bash
|-----------------|
|                 |
|  [ ]  [ ]  [ ]  |
|                 |
|-----------------|
```

**End of vertical axis**

```html
<div grid="align-end" axis="vertical">...</div>
```

```bash
|-----------------|
|                 |
|                 |
|  [ ]  [ ]  [ ]  |
|-----------------|
```

### Defining grid item alignment

> **Implementation Note**
>
> To vertically align elements on a cross-axis of a grid container, the elements need available vertical white space. This is usually achieved by having a height applied to the grid container.

To specify the vertical placement of grid items on the cross axis, add the value of `align-start`, `align-center`, and `align-end` to the `grid-item` attribute.

```html
<div grid>
  <div grid-item="align-start"></div>
  <div grid-item="align-center"></div>
  <div grid-item="align-end"></div>
</div>
```

```bash
|-----------------|
|[ ]              |
|       [ ]       |
|              [ ]|
|-----------------|
```

[npm]: https://www.npmjs.com/