# deqaf
Decaffeinate your JS-powered CSS stylesheets client-side
> Looking to work with caffeinated stylesheets server-side? Check out [qaffeine](https://github.com/tomhodgins/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](https://github.com/tomhodgins/caffeinated-style-sheets). 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:
```html
```
To use deqaf, you can run the function supplying the following argument:
```js
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:
```js
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:
```js
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:
```js
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:
```js
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](https://github.com/tomhodgins/deqaf-demo/blob/master/dist/index.html#L113&L124) from the [deqaf-demo](https://github.com/tomhodgins/deqaf-demo) project
## Writing Extended Selectors for JS-Powered Rules
```css
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:
```css
selector { 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]`.
```css
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:
```js
demo('h1', 'background: lime;')
```
> To see an example of an extended selector deqaf can read, check out [stylesheet.css](https://github.com/tomhodgins/deqaf-demo/blob/master/src/stylesheet.css#L110) from the [deqaf-demo](https://github.com/tomhodgins/deqaf-demo) project:
```css
.minwidth[--element='{"minWidth": 300}'] {
border-color: limegreen;
}
```
### Defining custom events for extended selectors
```css
--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:
```css
[--example] {
--selector: window;
--events: ["load", "resize", "input", "click"]
}
```
Instead, if you wanted a rule to reprocess only on the `paste` event, and only on `