qaffeine

Decaffeinate your JS-powered CSS stylesheets server-side

Looking to work with caffeinated stylesheets client-side? Check out deqaf

About

This project provides a way to parse extended CSS on the server and separate out the plain CSS from the JS-powered styles in "caffeinated" style sheets. This allows you to write CSS stylesheets that include styles supported by JavaScript plugins.

Installation

This project is provided as a Node formatted module.

The easiest way to install qaffeine is via npm:

npm install qaffeine

Plugin Usage

Qaffeine is distributed as a CommonJS module, ready to be used with Node. The easiest way to import qaffeine into your project is with a line similar to this:

const qaffeine = require('qaffeine')

qaffeine(
  {
    stylesheet: {},
    rules: {}
  },
  'input.css',
  'output.js',
  'output.css'
)

From Node

To use qaffeine in node scripts, you can run the function supplying the following arguments:

qaffeine(plugins, inputCSS, outputJS, outputCSS)

plugins is an object containing stylesheet and rule properties, optionally containing any stylesheet or rule plugins you want to make available to qaffeine.
inputCSS is the filename of a CSS file you want to read
outputJS is an optional argument that defines the filename of the JavaScript output
outputCSS is an optional argument that defines the filename of any CSS output

Printing JS to the console

If the plugin is run with no outputJS or outputCSS supplied, the resulting JavaScript will be printed in the console/

Outputting JavaScript-only

If the plugin is run with outputJS defined, but no outputCSS, the resulting JavaScript will be written to a file at the location specified by outputJS, and also include a copy of all CSS styles.

Outputting CSS and JavaScript

This is the recommended way to use qaffeine. When both outputJS and outputCSS filenames are specified, all output JavaScript will be written to a file at the location specified by outputJS, and all output CSS will be written to a file at the location specified by outputCSS.

Defining Plugins

To extend CSS with JavaScript functions, the two following possibilities exist: a rule plugin, or a stylesheet plugin.

A rule plugin accepts a CSS selector list, as well as any additional options, and lastly takes a CSS declaration list (everything inside the curly brackets {} after the selector list. A rule plugin must return a string that is a valid CSS stylesheet.

The other type of plugin is a stylesheet plugin, which takes 0 or more optional arguments, as well as one last argument that contains a CSS stylesheet as a string, and returns a string that is a valid CSS stylesheet.

If you had a plugin named example() that was loaded in the file where you're using qaffeine, suppose it looks like this:

example(selector, rule) {
  return Math.random() > .5
  ? `${selector} { ${rule} }`
  : ''
}

That function would return a rule written for the supplied selector 50% of the time, and return nothing the other 50% of the time. A function like this could be given to qaffeine like this:

qaffeine(
  {
    rule: {
      example
    }
  },
  'input.css'
)

This would load a file named input.css, process any rules that include [--example] in the selector, and would process them with our example() plugin.

On the other hand if we had a simple stylesheet plugin which takes a CSS stylesheet:

function example(stylesheet) {
  return Math.random() > .5
  ? stylesheet
  : ''
}

This function would return the supplied stylesheet 50% of the time, and return nothing the other half of the time. We could pass this into qaffeine like this:

qaffeine(
  {
    stylesheet: {
      example
    }
  },
  'input.css'
)

This would load a file named input.css, process any @supports rules that include --example() in the condition, and would process them with our example() plugin.

By supplying plugins to qaffeine through this structure we can include rule and stylesheet plugins with the same name, as well as give functions a custom name for our use with qaffeine, even if the function has a different name in your JavaScript code. This makes for a flexible and comfortable stylesheet writing experience.

To see an example of a node script using qaffeine, check out index.js from the qaffeine-demo project

Writing Extended Selectors for JS-Powered Rules

selector, list[--custom='"extended", "selector", "here"'] { }

To extend a CSS rule for use with qaffeine, add a custom extended selector between the normal selector list and the declaration list, effectively splitting the rule in two: everything before the extended selector is your CSS selector list, and everything after your extended selector is part of the declaration list:

selector <HERE> { property: value; }

To this location you can add an attribute selector [] that's written for any name you want, as long as it starts with a double dash --. If we were going to extend a rule with a plugin named demo(), we could add [--demo].

h1[--demo] {
  background: lime;
}

This would allow qaffeine to parse out the selector list h1, as well as the declaration list background: lime;, and write a call to our demo() function like this:

demo('h1', 'background: lime;')

To see an example of an extended selector qaffeine can read, check out stylesheet.css from the qaffeine-demo project:

.minwidth[--element='{"minWidth": 300}'] {
  border-color: limegreen;
}

Defining custom events for extended selectors

--selector: ;
--events: [];

--selector is either window or a CSS selector list as a string
--events is an array of events quoted as strings

The default settings for jsincss (which qaffeine uses to run the JS-powered rules it finds) are to listen to the load, resize, input and click events on the window object, so you could think of that like this:

[--example] {
  --selector: window;
  --events: ["load", "resize", "input", "click"]
}

Instead, if you wanted a rule to reprocess only on the paste event, and only on <textarea> elements, you could set custom --selector and --events like this:

[--example] {
  --selector: "textarea";
  --events: ["paste"];
}

To see an example of an extended selector with custom events qaffeine can read, check out stylesheet.css from the qaffeine-demo project:

.min-scroll-y[--element='{"minScrollY": 50}'] {
  --selector: ".min-scroll-y";
  --events: ["scroll"];
  border-color: limegreen;
}

Writing Extended @supports Rules for JS-Powered At-rules

@supports --custom('extended', 'at-rule', 'here') { }

To extend an @supports rule for use with qaffeine, add a custom extended selector between the @supports text and the group body rule.

@supports <HERE> { }

To this location you can add any name you want, as long as it starts with a double dash --, and ends with a pair of brackets (). If we were going to extend a rule with a plugin named demo(), we could add --demo().

@supports --demo() {
  html {
    background: lime;
  }
}

This would allow qaffeine to parse out the group body rule and write a call to our demo() function like this:

demo('html { background: lime; }')