deqaf

Decaffeinate your JS-powered CSS stylesheets client-side

Looking to work with caffeinated stylesheets server-side? Check out qaffeine

About

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

Plugin Usage

This project is provided as an ES module.

The easiest way to use deqaf is to import it inside a module:

<script type=module>
  import deqaf from 'https://unpkg.com/deqaf/index.js'

  deqaf({
    stylesheet: {},
    rule: {}
  })
</script>

To use deqaf, you can run the function supplying the following argument:

deqaf(plugins)

• plugins is an object containing stylesheet and rule properties, optionally containing any stylesheet or rule plugins you want to make available to deqaf.

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 deqaf, 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 deqaf like this:

deqaf(
  {
    rule: {
      example
    }
  }
)

This would loop through the entire CSSOM and 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 deqaf like this:

deqaf(
  {
    stylesheet: {
      example
    }
  }
)

This would process any @supports rules that include --example() in the condition, and would process them with our example() plugin.

By supplying plugins to deqaf 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 deqaf, 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 script using deqaf, check out index.html from the deqaf-demo project

Writing Extended Selectors for JS-Powered Rules

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

To extend a CSS rule for use with deqaf, 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 deqaf 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 deqaf can read, check out stylesheet.css from the deqaf-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 deqaf 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 deqaf can read, check out stylesheet.css from the deqaf-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 deqaf, 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 deqaf to parse out the group body rule and write a call to our demo() function like this:

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

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

@supports --element(".minwidth", {"minWidth": 300}) {
  [--self] {
    background: greenyellow;
  }
}

Defining custom events for extended at-rules

[--options] {
  --selector: ;
  --events: [];
}

• [--options] a custom selector for a rule that we can use to define custom 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 deqaf 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:

[--options] {
  --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:

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

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

@supports --element(".min-scroll-y", {"minScrollY": 50}) {
  [--options] {
    --selector: ".min-scroll-y";
    --events: ["scroll"];
  }
  [--self] {
    background: greenyellow;
  }
}

Known Compatible Stylesheet Plugins

• jsincss-compare-attribute
• jsincss-days
• jsincss-element-query
• jsincss-overflow
• jsincss-protocol-sniffer
• jsincss-viewport
• qaffeine-demo: element query plugin, at-rule edition
• css-polyfill-patterns: dynamic values examples, at-rule examples

Known Compatible Rule Plugins

• jsincss-ancestor-selector
• jsincss-auto-expand
• jsincss-closest-selector
• jsincss-custom-specificity
• jsincss-elder-selector
• jsincss-element-units
• jsincss-first-selector
• jsincss-frontend-variables
• jsincss-has-selector
• jsincss-last-selector
• jsincss-parent-selector
• jsincss-previous-selector
• jsincss-regex-match
• jsincss-scoped-eval
• jsincss-string-match
• jsincss-xpath-selector
• deqaf-demo: element query plugin, selector edition
• css-polyfill-patterns: pseudo class examples, simple selector examples

More Reading

• Qaffeine walkthrough video
• Caffeinated Style Sheets talk slides [Web Unleashed 2018]
• Deqaf demo project
• Qaffeine demo project