grid api

mixins

fixed-grid

@mixin fixed-grid($number-of-columns, $gutter-width: 1em, $gutter-height: $gutter-height, $distribute-dangling, $dangling-at-beginning) { ... }

Description

Use this when you know the number of columns. All cells are always of equal width (with exception of the last or first column in combination with some flags). You are not in charge of cell sizes; you can only influence the gutter width.

Parameters

parameter Name	parameter Description	parameter Type	parameter Default value
`$number-of-columns`	The number of columns the grid will have.	`Number`	— none
`$gutter-width`	The distance between two horizontal neighbor cells.	`Number`	`1em`
`$gutter-height`	The distance between two vertical neighbor cells.	`Number`	`$gutter-height`
`$distribute-dangling`	When there are not enough elements in the last column, they are left dangling to the left, making the grid uneven. By setting this parameter to `true`, you can force the grid to make the dangling elements in the last column wider. In you'd prefer this to happen in the first column, check out `$dangling-at-beginning`.	`Boolean`	— none
`$dangling-at-beginning`	By default, dangling elements are at the bottom of the grid. If this flag is set, the dangling elements considered to be the ones at the first row of the grid. This flag makes sense only if `$distribute-dangling` is set to true.	`Boolean`	— none

Example

The basic usage

@include fixed-grid(3);
// with 6 elements    with 5 elements    with 4 elements
// x-x x-x x-x        x-x x-x x-x        x-x x-x x-x
// x-x x-x x-x        x-x x-x            x-x

Handling dangling elements

@include fixed-grid(3, $distribute-dangling: true);
// with 6 elements    with 5 elements    with 4 elements
// x-x x-x x-x        x-x x-x x-x        x-x x-x x-x
// x-x x-x x-x        x-x-x x-x-x        x-x-x-x-x-x

Handling dangling element (at top)

@include fixed-grid(3, $distribute-dangling: true);
// with 6 elements    with 5 elements    with 4 elements
// x-x x-x x-x        x-x-x x-x-x        x-x-x-x-x-x
// x-x x-x x-x        x-x x-x x-x        x-x x-x x-x

Output

The CSS properties necessary for making the grid look the specified way.

Author

Lazar Ljubenović (lazarljubenovic)

grid

Since 0.1.0

@mixin grid($spec, $gutter-width: 1em, $gutter-height: $gutter-width) { ... }

Description

Use this for more complex grids. You specify the way each row will behave by an item in the list passed as a first argument, $spec. Each row can, individually, be specified in one of the two syntaxes:

ASCII-art syntax
distribute-syntax

ASCII-art syntax is designed to help you visualize the resulting grid. Use it when the grid is complex with different widths and offsets for cells.

Distribute-syntax is used to easily create n cells of equal width. It's very handy when cells are misaligned; for example consider a grid where the first row has three equal cells, and second row has five equal elements. Because GCD of 3 and 5 is 15, you'd have to do something like this if you use only ASCII-art syntax.

 'x-x-x-x-x x-x-x-x-x x-x-x-x-x'
 'x-x-x x-x-x x-x-x x-x-x x-x-x'

Since this is very cumbersome to work with and doesn't help visualising at all. Instead, you can do the following.

 distribute 3
 distribute 5

It simply says that the first row should distribute three, and the second five cells.

You can also combine the two syntaxes. For example, instead of

 'x-x x-x'
 'x-x-x x'
 'x x-x-x'
 'x-x x-x'

you can write the following.

 distribute 2
 'x-x-x x'
 'x x-x-x'
 distribute 2

Refer to examples for more.

Note that ASCII art comes as a string (this is necessary because whitespace is important), and distribute comes as a list of two items, where first item is a string distribute (which you don't have to quote), and second is the number of elements you want to distribute in the row.

Parameters

parameter Name	parameter Description	parameter Type	parameter Default value
`$spec`	The grid specification. See above.	`List`	— none
`$gutter-width`	The distance between two horizontal neighbor cells.	`Number`	`1em`
`$gutter-height`	The distance between two vertical neighbor cells.	`Number`	`$gutter-width`

Example

A simple ASCII grid

.container {
  @include grid((
    'x x-x'
    'x-x x'
  ));
}

A complex ASCII grid

@include grid((
  'x-x-x x-x x'
  'x     x x-x'
  '      x    '
  '  x-x     x'
));

Two equivalent grids (demonstrates why distribute is handy)

@include grid((
  'x-x x-x-x-x x-x-x-x'
  'x-x-x-x-x x-x-x-x-x'
))
@include grid((
  'x x-x x-x'
  distribute 2
));

Output

The properties used to create the specified grid.

Throws

First argument ($spec) must be a list. If you are trying to pass in a single item in a list, you have to enclose it in parenthesis and add a trailing comma. In other words, instead of `@include grid((

Requires

[function] _fn-apply
[function] _fn-filter
[function] _fn-apply
[function] _parse-row

Author

Lazar Ljubenović (lazarljubenovic)

internal

functions

[private] _global-to-chained

Since 0.1.0

@function _global-to-chained($list) { ... }

Description

In "global" format, the second number (offset) in the spec pair tells us at which column does the cell begin. This is the format which is given by the user. This function transforms that into a "chained" format where the second number (chained offset) tells us how many cells are supposed to be skipped, relative from the last known cell.

The algorithm works as follows.

Decrement all offsets.
Subtract "current" offset from the sum of all previous pairs.

Parameters

parameter Name	parameter Description	parameter Type	parameter Default value
`$list`	The list global syntax.	`List`	— none

Returns

List —

The list in chained syntax.

Example


'x x x-x'             // ascii visualization (irrelevant in code)
((1 1) (1 2) (2 3))   // input
((1 0) (1 0) (2 0))   // output

'x-x   x'             // ascii
((2 1) (1 4))         // input
((2 0) (1 1))         // output

'  x-x-x'             // ascii
((3 2))               // input
((3 1))               // output

Author

Lazar Ljubenović (lazarljubenovic)

[private] _parse-row

Since 0.1.0

@function _parse-row($input) { ... }

Description

Parses a single row of string-based spec (in form of characters 'x', '-' and ' '), giving chained syntax as output.

It currently has to receive a fictional second argument which is unused due to Sass limitation of dynamically figuring out the number of arguments a function expects.

Parameters

parameter Name	parameter Description	parameter Type	parameter Default value
`$input`	A string which represents the ASCII specification for a single row of a grid. For example, `x-x-x x' or 'x x'. Note that the string must be quotes because it contains whitespaces (sometimes even several in a row, which is important for constructing the grid). This information would be lost if the string was unquoted.	`String`	— none

Returns

List —

A specification of the row in chained syntax.

Example

$row: 'x x x';
parse-row($row, 0); // (1 0) (1 0) (1 0)
                    // All elements have one "unit" width, and no offset from
                    // the previous element.

$row: 'x-x x';
parse-row($row, 0); // (2 0) (1 0)
                    // The first element is two units, the second one unit.

$row: 'x   x-x';
parse-row($row, 0); // (1 0) (2 1)
                    // The first element is one unit. The second element is two
                    // units, offset by one unit from the previous element.

Throws

Parsing empty string
A row cannot being with
Parsing error. Unexpected token after
A row cannot end with

Used by

[mixin] grid

Author

Lazar Ljubenović (lazarljubenovic)

[private] _shorthand-to-expanded-chained

Since 0.1.0

@function _shorthand-to-expanded-chained($list) { ... }

Description

Users can use shorthands because they usually don't want to specify an offset. This function expands the shorthand syntax to expanded syntax.

Parameters

parameter Name	parameter Description	parameter Type	parameter Default value
`$list`	A (partially) shorthand syntax for grid row spec.	`List`	— none

Returns

List —

The grid row spec in chained extended syntax.

Example

_shorthand-to-expanded-chained(1 1 2); // (1 0) (1 2) (2 3)

Author

Lazar Ljubenović (lazarljubenovic)

internal util

functions

[private] _fn-apply

Since 0.1.0

@function _fn-apply($list, $fn) { ... }

Description

Creates a new list with the results of calling a provided function one very item in this list. Equivalent to Array#map in JavaScript.

Parameters

parameter Name	parameter Description	parameter Type	parameter Default value
`$list`	The list which the function is being applied to.	`List`	— none
`$fn`	Reference to a function applied to every item. This function must take two arguments: item and index.	`Function`	— none

Returns

List —

A new list (see description).

Example

@function square($x, $i) { @return $x * $x }
fn-apply(1 2 3 4, square); // 1 4 9 16

Used by

[mixin] grid
[mixin] grid

Author

Lazar Ljubenović (lazarljubenovic)

[private] _fn-reduce

Since 0.1.0

@function _fn-reduce($list, $fn, $initial) { ... }

Description

Applies a function against an accumulator and each item of the list (from left to right), to reduce it to a single value. Equivalent to Array#reduce in JavaScript.

Parameters

parameter Name	parameter Description	parameter Type	parameter Default value
`$list`	The list being reduced.	`List`	— none
`$fn`	Reference to a function applied to every item. This function must take two arguments: accumulated and current value.	`Function`	— none
`$initial`	The initial value of the accumulator, before any items are visited.	`Any`	— none

Returns

List —

A new list (see description).

Example

@function sum($acc, $curr) { @return $acc + $curr }
fn-apply(1 2 3 4, sum, 0); // 10

Author

Lazar Ljubenović (lazarljubenovic)

[private] _fn-filter

Since 0.1.0

@function _fn-filter($list, $fn) { ... }

Description

Creates a new list with all items that pass the test implemented by the provided function. Equivalent to Array#filter in JavaScript.

Parameters

parameter Name	parameter Description	parameter Type	parameter Default value
`$list`	The list being filtered.	`List`	— none
`$fn`	Reference to a filtering function.	`Function`	— none

Returns

List —

A new list (see description).

Example

@function aboveTen($x) { @return x > 10 }
fn-filter(2 20 30 3 4 100, aboveTen); // 20 30 100

Used by

[mixin] grid

Author

Lazar Ljubenović (lazarljubenovic)