Purgecss: Change Whitelist Option

[Ffloriel]

Context

Whitelist started as a simple option whitelist but grew up with the different use-cases and needs that appears with time.
It is now more complex and overly complicated, and somewhat difficult to remember how to use it with the different option.

Below is a recap of the different options:

• whitelist

whitelist: ['random', 'yep', 'button']

In the example, the selectors .random, #yep, button will be left in the final CSS

• whitelistPatterns

whitelistPatterns: [/red$/],

In the example, selectors ending with red such as .bg-red

• whitelistPatternsChildren

whitelistPatternsChildren: [/blue$/]

In the example, children of selectors ending with blue such as blue p or .bg-blue .child-of-bg

• whitelistPatternsGreedy

whitelistPatternsGreedy: [/^my-module$/],

.my-module.color-blue {} will be left in the final CSS even if color-blue is not seen as used by PurgeCSS.

Changes Proposed

New Option Name

First, the option whitelist will change its name based on https://github.com/FullHuman/purgecss/issues/428.
whitelist will be replaced by safelist. It will indicate which selectors are _safe_ to leave in the final CSS.

New Option: Blocklist

Blocklist will _block_ the CSS selectors from appearing in the final output CSS. The selectors will be removed even when they are seen as __used__ by PurgeCSS.

blocklist: ['usedClass', /^nav-/]

Even if nav-links and usedClass are found by an extractor, they will be removed.

Simplify the option

Two forms will be available. The simple form will be:

safelist: ['invisibleClass', /^nav-/]

In this form, safelist is an array that can take a string or a regex.

The _complex_ form will look like:

safelist: {
    standard: ['invisibleClass', /^nav-/],
    deep: [],
    greedy: [],
    keyframes: [],
    variables: []
}

In this form, safelist is an object taking optional properties:

standard is the same as the simple form and replaces whitelist and whitelistPatterns
deep replaces whitelistPatternsChildren
greedy is a new option coming from https://github.com/FullHuman/purgecss/pull/424
keyframes can be used to add keyframes to the safelist, when using keyframes: true (https://github.com/FullHuman/purgecss/issues/418)
variables can be used to add CSS variables to the safelist, when using variables: true

standard, deep and greedy might have more intuitive and self explanatory names so open to suggestion and comments.

Issues related:

https://github.com/FullHuman/purgecss/issues/428
https://github.com/FullHuman/purgecss/issues/418
https://github.com/FullHuman/purgecss/issues/302

[ruslanchek]

[/red$/], probably your proposition lacks that one. Not only black matter, but other colors are also important too. Anyway such a dumb proposal. Our descendants will be laughing at it. Besides that it is racism, it looks like you won't say that people can be black or white or any other color. If I would be black, then I would be laughing at it as well. It's the overhyped hysterical dumbest thing, that puts the US and now the other countries into anarchy mess. Nothing good comes after this.

[ruslanchek]

You also have to remove that "Children" things away. Perhaps one day in the future one parent will give a slap to his children. Then a bunch of morons who calls itself society decided to deprecate that word too. Like Children lives matter shit blah-blah.

[Ffloriel]

@ruslanchek noted. The proposal is more about simplifying the option that renaming it.

whitelist: [''invisibleClass'],
whitelistPatterns: [/^nav-/]
whitelistPatternsChildren: [],
whitelistPatternsGreedy: [],

to something like

safelist: {
    standard: ['invisibleClass', /^nav-/],
    deep: [],
    greedy: [],
    keyframes: [], // new for keyframes
    variables: [] // new for variables
}

the object is also better in my opinion than having multiple whitelistSomething options.

what do you think?

[ruslanchek]

@Ffloriel sorry for emotional feedback the situation in the world is frustrating. About the object - that seems good!

[ianhobbs]

A small case in my usage. Trying to capture img[data-sizes="auto"] within whitelist is proving to be difficult.

[Ffloriel]

• [x] Rename whitelist to safelist in the code
• [x] Rename whitelist to safelist in the documentation
• [x] Add safelist keyframes option
• [x] Add safelist variables option
• [x] Add blocklist option
• [x] Update documentation with new options