@salesforce-ux/sds-grid - npm Package Compare versions

Comparing version 0.2.1 to 0.2.2

lib/scripts/build.js

@@ -14,4 +14,3 @@ const fs = require('fs-extra');
 const css = path.resolve(root, 'src/css/init.css');
-const buildFolder = path.resolve(root, '.build');
-const output = path.resolve(buildFolder, 'sds-grid.css');
+const output = path.resolve(root, '.build/sds-grid.css');
 
@@ -18,0 +17,0 @@ fs.readFile(css, (err, data) => {

package.json

 {
   "name": "@salesforce-ux/sds-grid",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "description": "The SDS grid system provides a flexible, mobile-first, device-agnostic layout system. It has features to control alignment, flow, and gaps.",
@@ -22,3 +22,3 @@ "author": "Salesforce UX",
   },
-  "gitHead": "a2f8444588cbb1313d907bc4bb1c20ca6dba2c8e"
+  "gitHead": "34bb66c0f5cadd8e23674e1fdd751c241dcb0370"
 }

README.md

@@ -17,4 +17,339 @@ # `@salesforce-ux/sds-grid`
 
-Coming Soon
+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/).
 
-[npm]: https://www.npmjs.com/
+### 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.
+
+To modify independently, you add the `grid-item` attribute to the element you want to effect.
+
+```html
+<div grid>
+  <div grid-item>item</div>
+  <div grid-item>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     |
+| ------- | --------- |
+| `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:
+
+**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/

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

129141

increased by7.67%

Number of package files

30

increased by3.45%

Number of lines in readme file

355

increased by1768.42%

Worsened metrics

Lines of code

4691

decreased by-0.02%

No dependency changes