CorySimmons/jeet — pull request #54 by monkeez (2013-09-16 11:03:13+00:00)
Title: Added equidistant nested gutters and a range of other updates

So I've made a lot of changes, some are drastic others not so much but I think you'll like most of them. These changes have been tested in Stylus and SCSS, but not extensively. No SASS testing has been done.

### Condensed the numerator and denominator into a single argument
`col()` and `span()` can be called like this now: `col(1/4)` or `col(0.25)`. I feel like this is a much clearer way of doing the same thing, it's also more obvious what the function is going to do. This change is also needed for my implementation of equidistant column gutters (see below).

### Added ability to have equidistant nested column gutters
This was one of the features you were hoping to have. This is achieved by supplying the `col()` function's first argument, `ratios`, with a space separated list of fractions. You give it the new ratio you want to create first, then the ratios of that element's parents. So for example, `col(1/4 2/3)` is saying, "I want to create a column 1/4 the size of it's container and it's container is 2/3 the size of the whole layout". This can be nested infinitely (within reason), so `col(1/4 2/3 1/2 ...)` is valid.

I've also added a `parent_first` global setting which is set to `false` by default. This reverses the ordering of ratios you give the `col()` function. So `parent_first = false` `col(1/4 2/3)` equivalent to `parent_first = true` `col(2/3 1/4)`.

### Made nested columns automatic
Part of the update adding equidistant column gutters was making column nesting automatic (setting up the `first-child` and `last-child` margins). Columns are automatically nested when the user supplies more than one ratio to the `ratios` argument for `col()`. Another advantage is you don't need to specify the number of nested columns like you had to previously.

### Consolidated `offset()` into `span()` and `column()` for cleaner CSS output
I noticed when using the `offset()` function that it created duplicate assignments of the `margin-left` and `margin-right` properties. Because of this I've moved offset functionality into an `offset` argument for `col()` and `span()`. This removes the extra `margin-left` and `margin-right` declarations and keeps the final CSS clean.

Both `span()` and `col()`'s `offset` argument take a fraction which can be positive or negative depending on which side you want the offset to occur. `col()` has an additional optional boolean argument for `offset`, this is added by making `offset` a space separated list like so: `col(1/3, offset: 1/2 true)`. As `offset` is the second argument, `col(1/3, 1/2 true)` is also valid. This boolean is for specifying whether or not you're offsetting a column away from a nested edge, as a slightly different calculation must be made. This boolean defaults to `false` and isn't needed most of the time, just in a few edge (heh) cases.

### Added `shift()` and `unshift()` functions for content reordering
I've added this function for the sake of content reordering. `shift()` takes a space separated list of ratios similar to `col()`. The first ratio you give is how far you want to shift the element then the remaining ratios are the widths of the parent containers. For instance, `shift(1/4 1/2 1/3)` means, "Shift this element 1/4 to the right, and it's parent ratio is 1/2 and the parent of that is 1/3. Making the first value negative will shift the element in the opposite direction.

`unshift()` is used when you want to remove any element shifting you have done. This is primarily useful when changing the layout for a new breakpoint and you want to reset the shifting you have done.

### Removed `!important` flags
You already mentioned you were going to do this in the next update so I thought I may as well do this while I'm at it.

### Added right to left support
Added the global variable `layout_direction` with a default value of `LTR`. Changing this to `RTL` will flip the entire layout including offsets and shifts. It's possible to change this value in between blocks of styling to have certain parts of your site go in different directions.

### Added a few list functions
A couple of these are being used by the updated `col()` function, maybe these functions could be moved to a separate lists or utilities file?

### Split `get()` into `getSpan()` and `getColumn()`
I thought it might make more sense having these split into two different functions, it also makes the framework more readable. `span()` and `column()` call `getSpan()` and `getColumn()` respectively for their calculations.

### Updated documentation to match changes
I've updated README.md to reflect the changes I've made.

I've also added a *Getting Started* section which takes the user through some basic styling. Furthermore I've updated the Docs section to be a little more readable.

If you have any questions don't hesitate to ask.