fixins/README.md

A collection of functions and mixins for use with precss and postcss-functions

# fixins

> A collection of functions and mixins for use with
  [precss][0] and [postcss-functions][1]

## Install

```sh
npm install fixins --save-dev
```

## Usage

`fixins` should be required and passed into
[precss][0] and [postcss-functions][1] options within
a [postcss][4] plugin config.

Here is an example using gulp:

```js
// ...
const postcss = require('gulp-postcss');

const precss = require('precss');
const functions = require('postcss-functions');

const fixins = require('fixins');

// not required but certainly helps if you're
// using precss
const syntax = require('postcss-scss');

gulp.task('css', () => {
  return gulp.src('src/**/*.css')
    .pipe(postcss([
      precss({
        import: {
          // this is just my personal preference
          extension: 'pcss'
        },
        mixins: {
          // this is required!
          mixins: fixins.mixins
        }
      }),
      functions({
        // this is required!
        functions: fixins.functions
      }),
    ]))
    .pipe(gulp.dest('build/'));
});
```

Consult [postcss#usage][3] for a more complete overview
of how to integrate postcss plugins (this is __not__ a plugin, btw).


# Overview

All fixins are prefixed with `fx-` as to not collide with other frameworks/collections.
Most mixins can be called with positional or named arguments unless otherwise stated.
Positional arguments are separated by comma and not enclosed in parenthesis, while named arguments
can appear in any order but must be enclosed in parenthesis. Functions do not support named syntax.

##### Example: positional vs named arguments:
```scss
/* positional arguments (col and float)*/
@mixin fx-span 3, none;

/* named - col arg defaults to 12 */
@mixin fx-span(float:right);
```
































# API (Table of Contents)

+ Functions

  + [fx-lerp](#a0)
  + [fx-md-color](#a1)
  + [fx-closest-md-color](#a2)
  + [fx-red|orange|yellow|green|cyan|blue|violet|magenta|gray](#a3)
  + [fx-golden-ratio](#a4)
  + [fx-random](#a5)
  + [fx-str](#a6)


+ Mixins

  + [fx-ab](#a7)
  + [fx-box-shadow](#a8)
  + [fx-center](#a9)
  + [fx-ellipsis](#a10)
  + [fx-emboss](#a11)
  + [fx-horizontal-list](#a12)
  + [fx-list-unstyled](#a13)
  + [fx-size](#a14)
  + [fx-span](#a15)
  + [fx-underline-on-hover](#a16)

***

## Functions


## <a name="a0"></a> fx-lerp(color, color, [factor=0.5])



Mix `color1` and `color2` by `factor`.
The algorithm used is pretty basic. For more serious use, see
[postcss-color-mix](https://github.com/iamstarkov/postcss-color-mix)


#### Example
```scss
// input
fx-lerp(#ff0000, rgb(0,0,255,0))
// output
rgba(128,0,128,0.5)
```
#### Params
+ `color1` - CSS rgb, rgba, or hex string
+ `color2` - CSS rgb, rgba, or hex string
+ `[factor=0.5]` - range [0,1] or [0,100%]


#### Return
+ CSS rgba color



***

## <a name="a1"></a> fx-md-color(color1, [shade=500], [alpha])



Material design colors accessor


#### Example
```scss
// input
fx-md(red, 500)
// output
#f44336


// alpha support:
// input
fx-md(red, 500, 0.5)
// output
rgba(244, 67, 54, 0.5)
```


#### Params
+ `color` - material design color name
+ `shade` - material design color shade
+ `[alpha=1]` - range [0 1]


#### Return
+ CSS hex color if `alpha` argument is not passed
+ CSS rgba color if `alpha` was passed


##### Alias
+ `fx-mdc`
+ `fx-md`



***

## <a name="a2"></a> fx-closest-md-color(color)



Find the material design color that is closest to `color`.


#### Params
+ `color` - CSS hex color


#### Return
+ CSS hex color


##### Alias
+ `fx-cmd`
+ `fx-cmdc`
+ `fx-closest`



***

## <a name="a3"></a> fx-<red|orange|yellow|green|cyan|blue|violet|magenta|gray>(value, [alpha=1])



Get a shade of <color> between 0-255


#### Params
+ `value` - range [0, 255]
+ `[alpha=1]` - range [0, 1]


#### Return
+ CSS rgba color


##### Alias
+ gray: `grayscale`, `gray-scale`, and for you britts: `grey`, `greyscale`, `grey-scale`
+ violet: `purple`
+ magenta: `pink`

***

## <a name="a4"></a> fx-golden-ratio([number=100], [scale=1])



Get the golden ratio of `number` recursively scaled
`scale` times. A scale setting less then 1 will return
the smaller portion.


#### Example
```scss
fx-golden-ratio(30,  1) //=> 48.54102
fx-golden-ratio(30,  2) //=> 78.54102
fx-golden-ratio(30, -1) //=> 18.54102
fx-golden-ratio(30, -2) //=> 11.45898
```


#### Params
+ `[number=100] `- the base number
+ `[scale=1]` - the factor to scale `number` by


#### Return
+ The "A" (larger) portion if `number` is positive; "C" otherwise


##### Alias
+ fx-golden

***

## <a name="a5"></a> fx-random ([min=0], [max=256], [float=false [, inclusive=false]])



Get a random number between `min` and `max`, inclusive.
Random number generation provided by
[random-js](https://github.com/ckknight/random-js)


#### Params
+ `min` - range minimum (default = 0)
+ `max` - output range maximum (default = 255)
+ `float` - if truthy, output is floating point, default is false (integer output)
+ `inclusive` - if `float` is true, choose to include 0 and 1 (default false)


#### Return
+ a random integer or floating point number depending on the truthyness of `float`

***

## <a name="a6"></a> fx-str([input])



Wrap input as string, ensures output
in css is wrapped in quotes.


#### Params
+ `input` - anything


#### Return
+ "`input`"

***

## Mixins


## <a name="a7"></a> fx-ab([selector], prop, variable, [template])



This mixin outputs two rules for the passed selector:
one as is, with prop and variable as is; the other with `.b` class
appended to the selector, and a `b` prepended to the variable name before it is
evaluated. Note that `variable` is sass-like, but you should NOT include the dollar sign
of your variable when passing it into `fx-ab`. Note also that this mixin
does not support the named argument syntax like the most of the __fx-__
mixins do.


To futher compilcate things, `fx-ab` has different signatures
depending on if is being called in root context or not.
When on a root element the signature is `<selector>, <prop>, <variable>, [template]`.
In this context, `.b` is appended to the parent-most
(left-most) selector, so `x y z` will become `x.b y c`.


#### Example
```scss
// given input ...
$text-color: black;
$b-text-color: white;


// note the lack of `$` before `text-color`
@mixin fx-ab .box, color, text-color;


// results in ...
.box {
  color: black;
}
.box.b {
  color: white;
}
```


When inside a rule the signature is `<prop>, <variable>, [template]`.
The `.b` class will be appended to the child-most
(right-most) selector, so `x y z` will become `x y z.b`.


#### Example
```scss
// input
$text-color: black;
$b-text-color: white;


// note the lack of `$` before `text-color`
.box {
  .medium {
 	 @mixin fx-ab color, text-color;
  }
}


// note again the difference in output in root context
@mixin .box .medium, color, text-color;


// output
.box .medium {
  color: black;
}
.box .medium.b {
  color: white;
}


.box .medium {
  color: black;
}
.box.b .medium {
  color: white;
}
```


Using an optional template, any occurrence of `$$` will
be replaced with `variable`. This is useful when your variable
is included in a multiple word value definition./


```scss
$color: black;
$b-color: white;


@mixin fx-ab .box, box-shadow, color, 0 1px 0 1px $$;


// results in
.box {
  box-shadow: 0 1px 0 1px black;
}
.box.b {
  box-shadow: 0 1px 0 1px white;
}
```


#### Params
+ `[selector]` - selector
+ `prop` - left handle property key
+ `variable` - sass-like variable reference without the leading `$`.
Passing `foo` is read internally as "use $foo and $b-foo".
If no reference to $foo or $b-foo is found, foo and b-foo literals will be output.
+ `[template]` - text sequence to use as the right-hand value with
any occurrence of `$$` replaced with `variable` results.

***

## <a name="a8"></a> fx-box-shadow([color=rgba(0, 0, 0, 0.25)])


***

## <a name="a9"></a> fx-center



#### Return
`margin: 0 auto;`

***

## <a name="a10"></a> fx-ellipsis



Truncate text with an ellipsis `...`.
Works best on elements with a determined height
(not `auto` or `100%`)

***

## <a name="a11"></a> fx-emboss([radius=0], [top-opacity=0.3], [bottom-opacity=0.25], [background-opacity=0.2])



An opinionated emboss effect suitable for square containers.
Currently only suitable for light themes.

***

## <a name="a12"></a> fx-horizontal-list



Bare bones horizontal list. Note that this mixin
is meant to be placed directly under a `ul|ol` or
class placed directly on a `ul|ol`

***

## <a name="a13"></a> fx-list-unstyled


***

## <a name="a14"></a> fx-size([width], [height=width])



Width and height together in one line.
Called with 1 arg, height will mimick width (output square).
Note that this mixin does not support the named
argument syntax as that is completely redundant.

***

## <a name="a15"></a> fx-span([cols=12], [float=left])



Dynamically add `$number` of columns to an element.
Assumes a 12 column grid with no gutters (no gutters? that's right,
using box-sizing:border-box on everything, wrappers for your grid classes
and padding for inner content and things become much simpler in grid land).

***

## <a name="a16"></a> fx-underline-on-hover([color=#000], [speed=0.3s])



Animated text underline.
If using with an `a` element, be sure to set
`text-decoration: none;` on the element and its `:hover`.
Credit goes to someone on Codepen, but somehow I misplaced the
link to that work... will update here when found. Thanks, whoever you are!
































***

## Road Map

+ [ ] - support hsla
+ [ ] - flex-box helpers
+ [ ] - tighten test demo and github.io that sucker

## License
[MIT][2]

[0]: https://github.com/jonathantneal/precss
[1]: https://github.com/andyjansson/postcss-functions
[2]: http://lokua.net/license-mit.html
[3]: https://github.com/postcss/postcss#usage
[4]: https://github.com/postcss/postcss