gr8-util v1.3.0
A little function for generating functional css utilities.
Usage
Given some options, gr8-util
returns a string of css utilities. It does its best to generate concise and logical css selectors.
var util = require('gr8-util')
var css = util({
prop: 'display',
vals: [
'block',
'inline-block',
'inline',
'table',
'table-cell',
'table-row',
'flex',
'none'
]
})
console.log(css)
.db{display:block}
.dib{display:inline-block}
.di{display:inline}
.dt{display:table}
.dtc{display:table-cell}
.dtr{display:table-row}
.df{display:flex}
.dn{display:none}
API
css = util([opts])
Generate a string of css utility rules. opts
accepts the following values:
opts.prop
String | Array | Object css property(ies) *requiredopts.vals
Number | String | Array | Object css values *requiredopts.modifiers
String | Array | Object selector modifier(s)opts.unit
String unit to append to css values (only appended if values are numeric)opts.tail
String string to append after selectoropts.join
String string to join abbreviation and value in selectoropts.selector
Function css selector template functionopts.transform
Function value transform functionopts.parent
String global parent selector
Examples
These examples are primarily to demonstrate how options are used to generate a wide variety of css utilities. They are not necessarily very useful css utilities themselves.
Most basic, single prop
and single vals
var css = util({
prop: 'opacity',
vals: 0
})
.op0{opacity:0}
Use an array as prop
and vals
, as well as define unit
. Notice how floating point values are sanitized in generated selector (decimal replaced with hyphen), and how unit is not appended to a value of 0.
var css = util({
prop: [
'margin',
'padding'
],
vals: [
0,
0.5,
1
],
unit: 'rem'
})
.m0{margin:0}
.m0-5{margin:0.5rem}
.m1{margin:1rem}
.p0{padding:0}
.p0-5{padding:0.5rem}
.p1{padding:1rem}
Use an object as prop
and vals
in order to override generated abbreviations. Define join
to add things like hyphens to selectors.
var css = util({
prop: {
bgc: 'background-color'
},
vals: {
red: '#f00'
},
join: '-'
})
.bgc-red{background-color:#f00}
Use a nested array as prop
in order to generate rules with multiple properties. Notice how kebab-case properties are abbreviated in selector.
var css = util({
prop: [
['margin-left', 'margin-right']
],
vals: 1,
unit: 'rem'
})
.mlmr1{margin-left:1rem;margin-right:1rem}
Use an array which contains both strings and key/val objects as prop
in order to override only specific abbreviations.
var css = util({
prop: [
'margin',
'margin-right',
'margin-left',
{ mx: ['margin-left', 'margin-right'] }
],
vals: 1,
unit: 'rem'
})
.m1{margin:1rem}
.mr1{margin-right:1rem}
.ml1{margin-left:1rem}
.mx1{margin-left:1rem;margin-right:1rem}
Do the same as previous example with vals
as well.
var css = util({
prop: {
x: 'flex-wrap'
},
vals: [
'wrap',
'wrap-reverse',
{ wn: 'nowrap' }
]
})
.xw{flex-wrap:wrap}
.xwr{flex-wrap:wrap-reverse}
.xwn{flex-wrap:nowrap}
Pass a function to selector
in order to create selectors other than class selectors. Function receives the generated selector name as input and should return a css selector as a string.
var css = util({
prop: 'display',
vals: 'block',
selector: s => `[data-util~="${s}"]`
})
[data-util~="db"]{display:block}
Use modifiers
in order to generate rules for things like pseudo-classes, pseudo-elements, and descendant selectors. Exceptionally useful for hover states.
var css = util({
prop: 'text-transform',
vals: [
'uppercase',
'lowercase'
],
modifiers: [
':hover',
':active',
{ foc: ':focus' }
]
})
.ttu-h:hover{text-transform:uppercase}
.ttu-a:active{text-transform:uppercase}
.ttu-foc:focus{text-transform:uppercase}
.ttl-h:hover{text-transform:lowercase}
.ttl-a:active{text-transform:lowercase}
.ttl-foc:focus{text-transform:lowercase}
Passing false
to modifiers generates rules without a modifier. This is useful for concisely creating sets of rules:
var css = util({
prop: { fc: 'color' },
vals: [
'red',
'blue',
'green'
],
modifiers: [
false,
':hover'
]
})
.fcr{color:red}
.fcr-h:hover{color:red}
.fcb{color:blue}
.fcb-h:hover{color:blue}
.fcg{color:green}
.fcg-h:hover{color:green}
Use tail
in order to append an arbitrary string to a selector. Useful when adding things like pseudo-classes which do not need a modifier in the classname.
var css = util({
raw: {
cf: 'content:"";display:block;clear:both'
},
tail: ':after'
})
.cf:after{content:"";display:block;clear:both}
Use transform
in order to transform values as they are placed into declarations. Useful for things like columns:
var css = util({
prop: {
c: 'width'
},
vals: [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12],
unit: '%',
transform: i => (i / 12) * 100
})
.c1{width:8.333333333333332%}
.c2{width:16.666666666666664%}
.c3{width:25%}
.c4{width:33.33333333333333%}
.c5{width:41.66666666666667%}
.c6{width:50%}
.c7{width:58.333333333333336%}
.c8{width:66.66666666666666%}
.c9{width:75%}
.c10{width:83.33333333333334%}
.c11{width:91.66666666666666%}
.c12{width:100%}
Use parent
in order to namespace your rules. Useful for conditional utilities:
var css = util({
prop: { fc: 'color' },
vals: [
'red',
'blue',
'green'
],
modifiers: ':hover',
parent: '.no-touch'
})
.no-touch .fcr-h:hover{color:red}
.no-touch .fcb-h:hover{color:blue}
.no-touch .fcg-h:hover{color:green}
Why
Provides consistency and flexibility when generating functional css utility systems, such as gr8.
Todo
- Defaults
- Assertions