harpy-css

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 = require('harpy-css').create();

css.add({
	name: 'mtm',
	property: 'margin-top',
	value: '1rem',
});

css.add({
	name: 'mvm',
}, {
	'marginTop': '1rem',
	'marginBottom': '1rem',
});

css.add({
	name: 'mhm',
}, [
	{
		property: 'margin-right',
		value: '1rem',
	}, {
		property: 'margin-left',
		value: '1rem',
	}
]);

// Get the css rules as a string.
css.stringify()

The result of css.stringify() above:

.mtn,.mvm{margin-top:1rem}.mvm{margin-bottom:1rem}.mhm{margin-right:1rem}.mhm{margin-left:1rem}

Unminified version:

.mtn,
.mvm {
	margin-top: 1rem
}

.mvm {
	margin-bottom: 1rem
}

.mhm {
	margin-right: 1rem
}

.mhm {
	margin-left: 1rem
}

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 = require('harpy-css');

harpyCSS.create()

Creates a new instance of harpy-css.

Returns {Object} A new harpy-css instance.

Example

var css = harpyCSS.create();

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.add({
	name: 'bg-yellow',
	property: 'background-color',
	value: 'yellow',
}).add({
	name: 'bg-green',
	property: 'background-color',
	value: 'green',
});

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.add({
	name: 'phm',
}, {
	paddingRight: '1rem',
	paddingLeft: '1rem',
});

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.add({
	name: 'mhm',
}, [
	{
		property: 'margin-right',
		value: '1rem',
	}, {
		property: 'margin-left',
		value: '1rem',
	}
]);

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.add({
	name: 'phm',
	'#paddingRight': '1rem',
	'#paddingLeft': '1rem',
});

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 is false.

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 in css.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.prepare({
	name: 'bg-yellow',
	property: 'background-color',
	value: 'yellow',
}).add();

// Is the same as this:
css.add({
	name: 'bg-yellow',
	property: 'background-color',
	value: 'yellow',
});

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.prepare({
	name: 'bg-',
	property: 'background-color',
}).join({
	name: 'yellow',
	value: 'yellow',
}).add();

// Is the same as this:
css.add({
	name: 'bg-yellow',
	property: 'background-color',
	value: 'yellow',
});

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 in css.add(paramsAndDeclarations) above

Returns {Object} The same wrapper, so you can chain more calls before calling add().

Example

css.prepare({
	name: 'bg-',
	property: 'background-color',
}).join([
	{
		name: 'yellow',
		value: 'yellow',
	},
	{
		name: 'red',
		value: 'red',
	},
]).add();

// Is the same as this:
css.add({
	name: 'bg-yellow',
	property: 'background-color',
	value: 'yellow',
}).add({
	name: 'bg-red',
	property: 'background-color',
	value: 'red',
});

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.prepare({
	name: 'bg-',
	property: 'background-color',
}).joinMap({
	'yellow': 'yellow',
	'red': 'red',
}).add();

// Is the same as this:
css.prepare({
	name: 'bg-',
	property: 'background-color',
}).join([
	{
		name: 'yellow',
		value: 'yellow',
	},
	{
		name: 'red',
		value: 'red',
	},
]).add();

// Which is the same as this:
css.add({
	name: 'bg-yellow',
	property: 'background-color',
	value: 'yellow',
}).add({
	name: 'bg-red',
	property: 'background-color',
	value: 'red',
});

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.prepare({
	value: 'yellow',
	property: 'color',
	name: 'yellow',
}).joinMap('state', {
	'': undefined,
	'-active': 'active',
	'-hover': 'hover',
}).add();

// Is the same as this:
css.prepare({
	value: 'yellow',
	property: 'color',
	name: 'yellow',
}).join([
	{},
	{
		name: '-active',
		state: 'active',
	},
	{
		name: '-hover',
		state: 'hover',
	},
]).add();

// Which is the same as this:
css.add({
	name: 'yellow',
	property: 'color',
	value: 'yellow',
}).add({
	name: 'yellow-active',
	property: 'color',
	value: 'yellow',
	state: 'active',
}).add({
	name: 'yellow-hover',
	property: 'color',
	value: 'yellow',
	state: 'hover',
});

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.prepare({
	name: 'bt',
	property: 'border-top-',
}).joinMap('property', 'value', {
	'width': '1px',
	'color': 'currentColor',
	'style': 'solid',
}).add();

// Is the same as this:
css.prepare({
	name: 'bt',
	property: 'border-top-',
}).join([
	{
		property: 'width',
		value: '1px',
	},
	{
		property: 'color',
		value: 'currentColor',
	},
	{
		property: 'style',
		value: 'solid',
	},
]).add();

// Which is the same as this:
css.add({
	name: 'bt',
	property: 'border-top-width',
	value: '1px',
}).add({
	name: 'bt',
	property: 'border-top-color',
	value: 'currentColor',
}).add({
	name: 'bt',
	property: 'border-top-style',
	value: 'solid',
});

// Or this:
css.add({
	name: 'bt',
}, {
	'border-top-width': '1px',
	'border-top-color': 'currentColor',
	'border-top-style': 'solid',
});