harpy-css
CSS generator for Harpy.
This utility will help you create DRY CSS utility classes with all the power of Javascript at your hands. There is also a gulp version available called gulp-harpy-css.
How to use
Install using npm:
npm install --save-dev harpy-css
Use it in your Node project:
var css = ; css; css; css; // Get the css rules as a string.css
The result of css.stringify()
above:
Unminified version:
Core principles
The basic idea of harpy-css is to create DRY CSS with a focus on utility classes. The CSS generated by harpy-css follows a certain form, adhering to these rules:
- Every rule contains exactly one declaration.
- There are never two rules with the same declaration wrapped in the same media query.
- Rules can have more than one selector
- Each selector consist of exactly one class and one optional pseudo-class
API
var harpyCSS = ;
harpyCSS.create()
Creates a new instance of harpy-css.
Returns {Object} A new harpy-css instance.
Example
var css = harpyCSS;
css.add(params)
Creates one css rule with the provided class name, property and value. You can also add pseudo-class and media query. If you're adding a rule with the same property and value as another rule that have already been added, the class selector till be joined with the previous selector.
Arguments
- params {Object} Parameters for the new rule
- name {String} The css class name
- property {String} The css property to set
- value {String} The value of the property
- state {String} (Optional) A pseudo-class to add to the rule, e.g.
'hover'
or'active'
- media {String} (Optional) A media query for the rule, e.g.
'(min-with: 40em)'
Returns {Object} The same harpy-css instance, so you can call add
again.
Example
css;
css.add(params, declarationsMap)
Creates one or more css rules (one for every declaration) with the provided class name and declarations. You can also add pseudo-class and media query. Property/value pairs are provided as an object in declarationsMap
argument.
Arguments
- params {Object} Parameters for the new rule
- name {String} The css class name
- state {String} (Optional) A pseudo-class to add to the rule, e.g.
'hover'
or'active'
- media {String} (Optional) A media query for the rule, e.g.
'(min-with: 40em)'
- declarationsMap {Object} An object with properties as keys and their values as values. Camel case properties will be converted to kebab case, e.g.
paddingTop
to'padding-top'
Returns {Object} The same harpy-css instance, so you can call add
again.
Example
css;
css.add(params, declarationsArray)
Creates one or more css rules (one for every declaration) with the provided class name and declarations. You can also add pseudo-class and media query. Declarations are provided as objects in declarationsArray
.
Arguments
- params {Object} Parameters for the new rule
- name {String} The css class name
- state {String} (Optional) A pseudo-class to add to the rule, e.g.
'hover'
or'active'
- media {String} (Optional) A media query for the rule, e.g.
'(min-with: 40em)'
- declarationsArray {[Object]} An array of objects each representing a declaration.
- property {String} The css property to set
- value {String} The value of the property
Returns {Object} The same harpy-css instance, so you can call add
again.
Example
css;
css.add(paramsAndDeclarations)
Creates one or more css rules (one for every declaration) with the provided class name and declarations. You can also add pseudo-class and media query. Declarations are provided as part of the same object as the other parameters.
Arguments
- paramsAndDeclarations {Object} Parameters for the new rule. All keys starting with
#
will be treated as css properties.- name {String} The css class name
- state {String} (Optional) A pseudo-class to add to the rule, e.g.
'hover'
or'active'
- media {String} (Optional) A media query for the rule, e.g.
'(min-with: 40em)'
- #property {String} (Optional) A css declaration
Returns {Object} The same harpy-css instance, so you can call add
again.
Example
css;
css.stringify([options])
Creates one or more css rules (one for every declaration) with the provided class name and declarations. You can also add pseudo-class and media query. Declarations are provided as part of the same object as the other parameters.
Arguments
- options {Object} (Optional)
- beautify {Boolean} (Optional) Set to
true
to return unminified css. Default isfalse
.
- beautify {Boolean} (Optional) Set to
Returns {String} A string of added css rules
css.prepare()
Creates a wrapper for one or more rules so you can manipulate them before adding them to css
.
Returns {Object} A wrapper object. See below.
css.prepare(params)
Creates a wrapper for one or more rules so you can manipulate them before adding them to css
. Starts the chain with the provided params
object.
Arguments
- params {Object} Same as
css.add(paramsAndDeclarations)
above
Returns {Object} The same wrapper, so you can chain more calls before calling add()
.
css.prepare(paramsList)
Creates a wrapper for one or more rules so you can manipulate them before adding them to css
. Starts the chain with the provided objects in paramsList
array.
Arguments
- paramsList {[Object]} An array of parameters, same as
paramsAndDeclarations
incss.add(paramsAndDeclarations)
above
Returns {Object} The same wrapper, so you can chain more calls before calling add()
.
cssParamsListWrapper.add()
Adds the wrapped parameter objects back to the original harpy-css instance and stops the chain.
Returns {Object} The original harpy-css instance.
Example
css; // Is the same as this:css;
cssParamsListWrapper.join(params)
Combines the wrapped parameter objects with the params
object. Parameters with same key will have their values concatenated.
Arguments
- params {Object} Same as
css.add(paramsAndDeclarations)
above
Returns {Object} The same wrapper, so you can chain more calls before calling add()
.
Example
css; // Is the same as this:css;
cssParamsListWrapper.join(paramsList)
Combines the wrapped parameter objects with the ones in paramsList
. Parameters with same key will have their values concatenated. This is similar to a cartesian product och SQL "cross join", so if you have 3 objects and provide 3 new in paramsList
, you will have 9 afterwards, i.e. every parameter object in cssParamsListWrapper
is combined with every object in paramsList
.
Arguments
- paramsList {[Object]} An array of parameters, same as
paramsAndDeclarations
incss.add(paramsAndDeclarations)
above
Returns {Object} The same wrapper, so you can chain more calls before calling add()
.
Example
css; // Is the same as this:css;
cssParamsListWrapper.joinMap(nameValueMap)
Combines the wrapped parameter objects with a set of parameter objects described by nameValueMap
. Each key/value pair is transformed into a parameter object like this:
name: key value: value
Arguments
- nameValueMap {Object} An object where the keys are names and values are values in parameter objects
Returns {Object} The same wrapper, so you can chain more calls before calling add()
.
Example
css; // Is the same as this:css; // Which is the same as this:css;
cssParamsListWrapper.joinMap(valueParam, keyMap)
Combines the wrapped parameter objects with a set of parameter objects described by keyMap
. The valueParam
argument defines what parameter the values in keyMap
will represent. Each key/value pair is thereby transformed into a parameter object like this:
name: key valueParam: value
Arguments
- valueParam {String} The parameter that the values in
keyMap
will represent - keyMap {Object} An object that describes parameter objects as described above
Returns {Object} The same wrapper, so you can chain more calls before calling add()
.
Example
css; // Is the same as this:css; // Which is the same as this:css;
cssParamsListWrapper.joinMap(keyParam, valueParam, map)
Combines the wrapped parameter objects with a set of parameter objects described by map
. The keyParam
argument defines what parameter the keys in map
will represent, and the valueParam
argument will do the same for its values. Each key/value pair is thereby transformed into a parameter object like this:
keyParam: key valueParam: value
Arguments
- keyParam {String} The parameter that the keys in
map
will represent - valueParam {String} The parameter that the values in
map
will represent - map {Object} An object that describes parameter objects as described above
Returns {Object} The same wrapper, so you can chain more calls before calling add()
.
Example
css; // Is the same as this:css; // Which is the same as this:css; // Or this:css;