From 34f4790def217b3de8b69ab781fda076db62b124 Mon Sep 17 00:00:00 2001 From: Cory Simmons Date: Mon, 16 Mar 2015 23:49:09 -0400 Subject: [PATCH] Add JSDocs --- lost.styl | 173 +++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 172 insertions(+), 1 deletion(-) diff --git a/lost.styl b/lost.styl index a0cf02e2..b91cb79f 100644 --- a/lost.styl +++ b/lost.styl @@ -6,10 +6,31 @@ $old = false $rtl = false +/** + * Sets a translucent background color to all elements it affects. Helpful while setting up, or debugging, the structure of your site to make sure all items are cleared correctly. + * + * @param {string} [$bg=blue] - A color to be lightened, so make sure you pick a darkish color. + * + * @example + * section + * edit(red) + */ + edit($bg = blue) * background: rgba($bg, 10%) + +/** + * Clearfix used to clear floated children columns. http://nicolasgallagher.com/micro-clearfix-hack + * + * @example + * .parent + * cf() + * .child + * column(1/2) + */ + cf() *zoom: 1 &:before, &:after @@ -18,6 +39,22 @@ cf() &:after clear: both + +/** + * Vertically and/or horizontally align nested elements. + * + * @param {string} [$direction=both] - Either vertical, v, horizontal, or h. Defaults to both. + * + * @example + * .parent + * align(vertical) + * width: 600px + * height: 400px + * .child + * width: 300px + * height: 150px + */ + align($direction = both) if $old position: relative @@ -51,6 +88,18 @@ align($direction = both) justify-content: center align-items: center + +/** + * Create a container that is centered in the middle of the page with some padding on the left and right sides of it. + * + * @param {number} [$pad=0] - Padding on the left and right side of the element. 0 by default, but feel free to increase it so containers don't touch the edge of the viewport. + * @param {number} [$mw=$breakpoint] - The max-width of the element. + * + * @example + * section + * center(45px) + */ + center($pad = 0, $mw = $breakpoint) max-width: $mw margin-right: auto @@ -63,6 +112,20 @@ center($pad = 0, $mw = $breakpoint) padding-left: $pad padding-right: $pad + +/** + * Apply a negative margin on each side of the element. This is required when adding columns and such to negate their outer margins. This mixin automatically applies clearfix as it's assumed floated elements will be nested within it. + * + * @param {number} [$ratios=1] - If $old is false, a single fraction used to determine the negative left and right margins of the element. If $old is true, a collection of container ratios (fractions). + * @param {number} [$gut=$gutter] - The gutter width. This is typically left alone, but if you want a specific row/column combination to have a larger or smaller gutter, you need to specify the same $gut on both types of elements. + * + * @example + * .parent + * row() + * .children + * column(1/2) + */ + row($ratios = 1, $gut = $gutter) cf() if $old @@ -74,6 +137,30 @@ row($ratios = 1, $gut = $gutter) margin-left: -($gut / 2) margin-right: -($gut / 2) + +/** + * Creates a column that is a fraction of the size of it's containing element with a margin on each side of the element. If $old is set to false, you don't need to pass any additional ratios (fractions), as the grid system will make use of calc(). If $old is set to true, the grid system will support more browsers, but you will need to pass additional ratios for each nested container. It's highly recommended you use the calc() syntax to avoid confusion. + * + * @param {number} [$ratios=1] - If $old is false, this is a simple fraction of the containing element's width. If $old is true, this is a collection of fractions with the containing element's fraction passed each time it is nested. + * @param {number} [$gut=$gutter] - The margin on each side of the element used to create a gutter. Typically this is left alone, but if you need to have a specifically large or small gutter, you will need to alter this along with the containing row's gutter so they are the same. + * + * @example + * .parent + * row() + * .children + * column(1/4) + * + * @example + * .parent + * row() + * .child + * column(1/2) + * .nested-parent + * row(1/2) + * .nested-child + * column(1/4 1/2) + */ + column($ratios = 1, $gut = $gutter) if $rtl float: right @@ -96,6 +183,20 @@ column($ratios = 1, $gut = $gutter) if $gut is 0 width: s('calc(100% * %s)', $ratios) + +/** + * Margin to the left or right of an elements depending on if the fraction passed is positive or negative. + * + * @param {number} [$ratios=false] - Fraction of the container to be offset. + * @param {number} [$gut=$gutter] - How large the gutter involved is, typically this won't be adjusted, but if you have set the columns for that row to have different gutters than default, you will need to match that gutter here as well. + * + * @example + * .two-elements + * column(1/3) + * &:nth-child(2) + * offset(1/3) + */ + offset($ratios = false, $gut = $gutter) if $old $gut = $gut * .1 @@ -122,6 +223,23 @@ offset($ratios = false, $gut = $gutter) if $ratios < 0 margin-right: s('calc(-100% * %s)', $ratios) + +/** + * Source ordering. Useful for having an element appear above or below another element on mobile devices, and then to the opposite side on larger devices. For instance, a sidebar and article. You might want the sidebar to appear before the article on mobile, but be to the right of the article on desktop. This is how that is achieved. + * + * @param {number} [$ratios=false] - Fraction of the container to be moved by it's left value. + * + * @example + * .sidebar + * @media (min-width: 800px) + * column(1/3) + * move(2/3) + * .article + * @media (min-width: 800px) + * column(2/3) + * move(-1/3) + */ + move($ratios = false) position: relative if $old @@ -130,19 +248,58 @@ move($ratios = false) $ratios = $ratios[0] left: s('calc(100% * %s)', $ratios) + +/** + * Since columns are floated, when they are of unequal height, they will misalign easily. By setting cycle() you can make sure elements are being cleared on appropriate rows. + * + * @param {number} [$item=-1] - The nth-child + 1 element to clear on. If you want a row to be 3 elements wide, then you'd pass 3. + * + * @example + * .gallery + * img + * column(1/3) + * cycle(3) + */ + cycle($item = -1) &:nth-child(n) clear: none &:nth-child({$item}n + 1) clear: both -// Private + +/** + * Reverses a list of numbers (or in our case, fractions) + * + * @param {number} $list - A list of numbers or fractions to be reversed. + * + * @example + * $foo: 1 2 3 + * _reverse($foo) + * + * @access private + */ + _reverse($list) result = () for item in $list prepend(result, item) return result + +/** + * Gets a column's width and gutter size as an integer. + * + * @param {number} [$ratios=1] - A list of fractions to be used in calculating the appropriate width and gutter size returned. + * @param {number} [$gut=$gutter] - The gutter size used to generate an appropriate width and gutter size to be returned by the function. + * + * @example + * .third + * width: (_get-column(1/3, '30px')[0])% + * + * @access private + */ + _get-column($ratios = 1, $gut = $gutter) $ratios = _reverse($ratios) width = 100 @@ -151,8 +308,22 @@ _get-column($ratios = 1, $gut = $gutter) width = 100 * $ratio - $gut return width ($gut / 2) + +/** + * A helper class used for centering by default values. + * + * @see {center} + */ + .center center() + +/** + * A helper class used to create rows with default values. + * + * @see {row} + */ + .row row()