namuol / free-style

Make CSS easier and more maintainable by using inline style objects

Free Style

Free Style is designed to make CSS easier and more maintainable by using inline style objects.

Installation

npm install free-style --save
bower install free-style --save

Why?

There's a really great presentation by Christopher Chedeau you should check out.

Solved by using CSS in JS

• No global variables (what is .button?)
• Built in dependency system (CommonJS, Require.js, <script />)
• Dead code elimination (automatically remove associated styles)
• Minification (minify JS with existing tools)
• Shared constants (using variables)
• Isolation (every style is uniquely namespaced)
• Extensible (just use JavaScript - everything from math to color manipulation built in!)

Also solved by using Free Style

• Works with legacy DOM components (you can nest .class-name in your style)
• Easily expose third-party theming hooks through semantic class names (.button)
• Consistently generated styles and class names (generate on the server and merges duplicate style definitions)
• Develop the component right beside the style (no more hunting for that ul > li > a)
• Create isomorphic JavaScript applications by serving styles for only the components rendered (see React Free Style)
• Continue using the CSS you know ({ '&:hover': { ... } })
• Automatically namespaced @-rules ({ '@media (min-width: 500px)': { ... } })
• Easily merge multiple style definitions (FreeStyle#registerStyle(a, b, c))
• Define duplicate rules using arrays ({ backgroundColor: ['red', 'linear-gradient(to right, red 0%, blue 100%)'] })
• Integrates with any third-party system

Usage

Available using Common.js, AMD and window.

var FreeStyle = require('free-style')
// var FreeStyle = window.FreeStyle

// Create a new instance.
var freeStyle = FreeStyle.create()

var STYLE = freeStyle.registerStyle({
  backgroundColor: 'red'
})

// Injects a `<style />` element into the DOM.
freeStyle.inject()

React.render(
  <div className={STYLE.className}>Hello world!</div>,
  document.body
)

Namespaced Styles

var BUTTON_STYLE = freeStyle.registerStyle({
  backgroundColor: 'red',
  padding: 10
})

console.log(BUTTON_STYLE.selector) //=> ".n1c471b35"
console.log(BUTTON_STYLE.className) //=> "n1c471b35"
console.log(BUTTON_STYLE.style) //=> { backgroundColor: 'red', padding: '10px' }

Multiple Style Declarations

freeStyle.registerStyle({
  background: [
    'red',
    '-moz-linear-gradient(left, red 0%, blue 100%)',
    '-webkit-linear-gradient(left, red 0%, blue 100%)',
    '-o-linear-gradient(left, red 0%, blue 100%)',
    '-ms-linear-gradient(left, red 0%, blue 100%)',
    'linear-gradient(to right, red 0%, blue 100%)'
  ]
})

Nested @-rules

freeStyle.registerStyle({
  color: 'red',
  '@media (min-width: 500px)': {
    color: 'blue'
  }
})

Nested Selectors

Please note: Although this is possible, it is not recommended. It circumvents the usefulness of componentized styles, but it is useful for styling legacy DOM components.

freeStyle.registerStyle({
  '.classname': {
    color: 'blue'
  }
})

Selector Parent Reference

freeStyle.registerStyle({
  '&:hover': {
    color: 'blue'
  }
})

Mixin Style Objects

var ellipsisStyle = freeStyle.registerStyle({
  whiteSpace: 'nowrap',
  overflow: 'hidden',
  textOverflow: 'ellipsis'
})

var redEllipsisStyle = freeStyle.registerStyle({
  color: 'red'
}, ellipsisStyle.style)

Keyframes

var ANIM = freeStyle.registerKeyframes({
  from: { color: 'red' },
  to: { color: 'blue' }
})

freeStyle.registerStyle({
  animationName: ANIM.name,
  animationDuration: '1s'
})

Nested @-rules

freeStyle.registerKeyframes({
  '@supports (animation-name: test)': {
    from: { color: 'red' },
    to: { color: 'blue' }
  }
})

Output

CSS String

freeStyle.getStyles() //=> ".n1c471b35{background-color:red;padding:10px;}"

Inject Styles

Please note: This is just a thin wrapper around freeStyle.getStyles() that creates and appends a <style /> element to the head.

freeStyle.inject(/* optional target */)

Utilities

URL

freeStyle.url('http://example.com') //=> 'url("http://example.com")'

Join

freeStyle.join(style.className, 'string', { yes: true, no: false }) //=> "n1c471b35 string yes"

Create a New Instance

new FreeStyle.FreeStyle()

Change Events

freeStyle.addChangeListener(fn)
freeStyle.removeChangeListener(fn)

Third-Party Methods

Please note: These methods should only be used by third-party implementers. The add/remove and attach/detach combinations keep track of counts so you need to remove the same number of times you add, if you want to remove it entirely.

var STYLE = freeStyle.createStyle({ ... })
var ANIM = freeStyle.createKeyframes({ ... })

freeStyle.add(STYLE) // Add to internal cache and emit change.
freeStyle.has(STYLE) // Check if the style already exists.
freeStyle.remove(STYLE) // Remove from internal cache and emit change.

var child = freeStyle.create()

freeStyle.attach(child) // Attach the child styles and listen for changes.
freeStyle.detach(child) // Detach the child styles and stop listening for changes.

Legacy Browsers

To support legacy browsers (<= IE8) you'll need to polyfill some ES5 features, such as Array.prototype.forEach and Object.keys.

License

MIT