refactor: rename whitelist to safelist

- CLI option
- Documentation

#428 #439

README.md

@@ -28,7 +28,7 @@ You can find the PurgeCSS documentation on [this website](https://purgecss.com).
 - [Configuration](https://purgecss.com/configuration.html)
 - [Command Line Interface](https://purgecss.com/CLI.html)
 - [Programmatic API](https://purgecss.com/api.html)
-- [Whitelisting](https://purgecss.com/whitelisting.html)
+- [Whitelisting](https://purgecss.com/safelisting.html)
 - [Extractors](https://purgecss.com/extractors.html)
 - [Comparison](https://purgecss.com/comparison.html)
 

docs/.vuepress/config.js

@@ -99,7 +99,7 @@ module.exports = {
             ["configuration", "Configuration"],
             ["CLI", "Command Line Interface"],
             ["api", "Programmatic API"],
-            ["whitelisting", "Whitelisting"],
+            ["safelisting", "Safelisting"],
             ["extractors", "Extractors"],
           ],
         },

docs/CLI.md

@@ -35,7 +35,7 @@ Options:
   -font, --font-face       option to remove unused font-faces
   -keyframes, --keyframes  option to remove unused keyframes
   -rejected, --rejected    option to output rejected selectors
-  -w, --whitelist <list>   list of classes that should not be removed (comma separated)
+  -s, --safelist <list>   list of classes that should not be removed (comma separated)
   -h, --help               display help for command
 ```
 
@@ -71,10 +71,10 @@ By default, the CLI outputs the result in the console. If you wish to return the
 purgecss --css css/app.css --content src/index.html,"src/**/*.js" --output build/css/
 ```
 
-### --whitelist
+### --safelist
 
-If you wish to prevent PurgeCSS from removing a specific CSS selector, you can whitelist it.
+If you wish to prevent PurgeCSS from removing a specific CSS selector, you can add it to the safelist.
 
 ```text
-purgecss --css css/app.css --content src/index.html --whitelist classnameToWhitelist
+purgecss --css css/app.css --content src/index.html --safelist classnameToSafelist
 ```

docs/README.md

@@ -13,7 +13,7 @@ meta:
 PurgeCSS is a tool to remove unused CSS. It can be part of your development workflow.  
 When you are building a website, you might decide to use a CSS framework like TailwindCSS, Bootstrap, MaterializeCSS, Foundation, etc... But you will only use a small set of the framework, and a lot of unused CSS styles will be included.
 
-This is where PurgeCSS comes into play. PurgeCSS analyzes your content and your css files. Then it matches the selectors used in your files with the one in your content files. It removes unused selectors from your css, resulting in smaller css files.
+This is where PurgeCSS comes into play. PurgeCSS analyzes your content and your CSS files. Then it matches the selectors used in your files with the one in your content files. It removes unused selectors from your CSS, resulting in smaller CSS files.
 
 ## Table of Contents
 
@@ -22,7 +22,7 @@ This is where PurgeCSS comes into play. PurgeCSS analyzes your content and your
 - [Configuration](configuration.md)
 - [Command Line Interface](CLI.md)
 - [Programmatic API](api.md)
-- [Whitelisting](whitelisting.md)
+- [Safelisting](safelisting.md)
 - [Extractors](extractors.md)
 - [Comparison](comparison.md)
 
@@ -42,3 +42,8 @@ This is where PurgeCSS comes into play. PurgeCSS analyzes your content and your
 - [Next.js](guides/next.md)
 - [Razzle](guides/razzle.md)
 - [WordPress](guides/wordpress.md)
+
+### Common Questions
+
+- [How to use with CSS modules?](css_modules.md)
+- [How to use with Ant Design?](ant_design.md)

docs/api.md

@@ -64,8 +64,3 @@ interface ResultPurge {
   rejected?: string[];
 }
 ```
-
-::: tip
- Take a look at the type definition file to get the complete information.
- [Definition file](https://github.com/FullHuman/purgecss/tree/master/packages/purgecss/lib/purgecss.d.ts)
-:::

docs/configuration.md

@@ -37,21 +37,18 @@ The options are defined by the following types:
 
 ```ts
 interface UserDefinedOptions {
-  content: Array<string | RawContent>
-  css: Array<string | RawCSS>
-  defaultExtractor?: ExtractorFunction
-  extractors?: Array<Extractors>
-  fontFace?: boolean
-  keyframes?: boolean
-  output?: string
-  rejected?: boolean
-  stdin?: boolean
-  stdout?: boolean
-  variables?: boolean
-  whitelist?: string[]
-  whitelistPatterns?: Array<RegExp>
-  whitelistPatternsChildren?: Array<RegExp>
-  whitelistPatternsGreedy?: Array<RegExp>
+  content: Array<string | RawContent>;
+  css: Array<string | RawCSS>;
+  defaultExtractor?: ExtractorFunction;
+  extractors?: Array<Extractors>;
+  fontFace?: boolean;
+  keyframes?: boolean;
+  output?: string;
+  rejected?: boolean;
+  stdin?: boolean;
+  stdout?: boolean;
+  variables?: boolean;
+  safelist?: UserDefinedSafelist;
 }
 
 interface RawContent {
@@ -62,6 +59,18 @@ interface RawContent {
 interface RawCSS {
   raw: string
 }
+
+type StringRegExpArray = Array<RegExp | string>;
+
+type ComplexSafelist = {
+  standard?: StringRegExpArray;
+  deep?: RegExp[];
+  greedy?: RegExp[];
+  variables?: StringRegExpArray;
+  keyframes?: StringRegExpArray;
+};
+
+type UserDefinedSafelist = StringRegExpArray | ComplexSafelist;
 ```
 
 - **content**
@@ -215,57 +224,79 @@ await new PurgeCSS().purge({
 })
 ```
 
-- **whitelist**
+- **safelist**
+
+You can indicate which selectors are safe to leave in the final CSS. This can be accomplished with the option `safelist`.
+
+Two forms are available for this option.
+
+```ts
+safelist: ['random', 'yep', 'button', /^nav-/]
+```
+
+In this form, safelist is an array that can take a string or a regex.
+
+The _complex_ form is:
+
+```ts
+safelist: {
+    standard: ['random', 'yep', 'button', /^nav-/],
+    deep: [],
+    greedy: [],
+    keyframes: [],
+    variables: []
+}
+```
 
-You can whitelist selectors to stop PurgeCSS from removing them from your CSS. This can be accomplished with the options `whitelist`, `whitelistPatterns`, `whitelistPatternsChildren`, and `whitelistPatternsGreedy`.
+e.g:
 
 ```js
 const purgecss = await new PurgeCSS().purge({
   content: [], // content
   css: [], // css
-  whitelist: ['random', 'yep', 'button']
+  safelist: ['random', 'yep', 'button']
 })
 ```
 
 In this example, the selectors `.random`, `#yep`, `button` will be left in the final CSS.
 
-- **whitelistPatterns**
-
-You can whitelist selectors based on a regular expression with `whitelistPatterns`.
-
 ```js
 const purgecss = await new PurgeCSS().purge({
   content: [], // content
   css: [], // css
-  whitelistPatterns: [/red$/]
+  safelist: [/red$/]
 })
 ```
 
 In this example, selectors ending with `red` such as `.bg-red` will be left in the final CSS.
 
-- **whitelistPatternsChildren**
+- **safelist.deep**
 
-You can whitelist selectors and their children based on a regular expression with `whitelistPatternsChildren`.
+You can safelist selectors and their children based on a regular expression with `safelist.deep`.
 
 ```js
 const purgecss = await new PurgeCSS().purge({
   content: [], // content
   css: [], // css
-  whitelistPatternsChildren: [/red$/]
+  safelist: {
+    deep: [/red$/]
+  }
 })
 ```
 
 In this example, selectors such as `.bg-red .child-of-bg` will be left in the final CSS, even if `child-of-bg` is not found.
 
-- **whitelistPatternsGreedy**
+- **safelist.greedy**
 
-Finally, you can whitelist whole selectors if any part of that selector matches a regular expression with `whitelistPatternsGreedy`.
+Finally, you can safelist whole selectors if any part of that selector matches a regular expression with `safelist.greedy`.
 
 ```js
 const purgecss = await new PurgeCSS().purge({
   content: [], // content
   css: [], // css
-  whitelistPatternsGreedy: [/red$/]
+  safelist: {
+    greedy: [/red$/]
+  }
 })
 ```
 

docs/guides/nuxt.md

@@ -120,6 +120,6 @@ npm i --save-dev @fullhuman/postcss-purgecss
 ```javascript
 '@fullhuman/postcss-purgecss': {
   content: ['./pages/**/*.vue', './layouts/**/*.vue', './components/**/*.vue'],
-  whitelist: ['html', 'body']
+  safelist: ['html', 'body']
 }
 ```

docs/guides/vue.md

@@ -45,7 +45,6 @@ Below are the PurgeCSS options set by this plugin:
     const contentWithoutStyleBlocks = content.replace(/<style[^]+?<\/style>/gi, '')
     return contentWithoutStyleBlocks.match(/[A-Za-z0-9-_/:]*[A-Za-z0-9-_/]+/g) || []
   },
-  whitelist: [],
-  whitelistPatterns: [ /-(leave|enter|appear)(|-(to|from|active))$/, /^(?!(|.*?:)cursor-move).+-move$/, /^router-link(|-exact)-active$/, /data-v-.*/ ],
+  safelist: [ /-(leave|enter|appear)(|-(to|from|active))$/, /^(?!(|.*?:)cursor-move).+-move$/, /^router-link(|-exact)-active$/, /data-v-.*/ ],
 }
 ```

docs/guides/wordpress.md

@@ -3,14 +3,14 @@ title: WordPress | PurgeCSS
 lang: en-US
 meta:
   - name: description
-    content: PurgeCSS can be used for WordPress development. A module exists to ease the process and provide common whitelist items.
+    content: PurgeCSS can be used for WordPress development. A module exists to ease the process and provide common safelist items.
   - name: keywords
     content: PurgeCSS WordPress purgecss-with-wordpress remove unused css
 ---
 
 # WordPress
 
-If you want to use PurgeCSS with WordPress, you might need to whitelist classes generated by WordPress to avoid them being removed by PurgeCSS. `purgecss-with-wordpress` contains the classes needed to be whitelisted.
+If you want to use PurgeCSS with WordPress, you might need to safelist classes generated by WordPress to avoid them being removed by PurgeCSS. `purgecss-with-wordpress` contains the classes needed to be safelisted.
 
 ## Installation
 
@@ -30,23 +30,19 @@ import purgecssWordpress from 'purgecss-with-wordpress'
 const purgeCss = new Purgecss({
   content: ['**/*.html'],
   css: ['**/*.css'],
-  whitelist: purgecssWordpress.whitelist,
-  whitelistPatterns: purgecssWordpress.whitelistPatterns
+  safelist: purgecssWordpress.safelist
 })
 const result = purgecss.purge()
 ```
 
-If you have additional classes you want to include in either of the `whitelist` or `whitelistPatterns`, you can include them using the spread operator:
+If you have additional classes you want to include, you can include them using the spread operator:
 
 ```js
 {
-  whitelist: [
-    ...purgecssWordpress.whitelist,
+  safelist: [
+    ...purgecssWordpress.safelist,
     'red',
     'blue',
-  ],
-  whitelistPatterns: [
-    ...purgecssWordpress.whitelistPatterns,
     /^red/,
     /blue$/,
   ]

docs/plugins/webpack.md

@@ -125,40 +125,26 @@ new PurgecssPlugin({
 })
 ```
 
-* #### whitelist, whitelistPatterns, whitelistPatternsChildren, and whitelistPatternsGreedy
+* #### safelist
 
-Similar as for the `paths` option, you can also define functions for the following options:
+Similar as for the `paths` option, you also can define a function for this option:
 
 ```js
-function collectWhitelist() {
-    // do something to collect the whitelist
-    return ['whitelisted'];
-}
-
-function collectWhitelistPatterns() {
-    // do something to collect the whitelist
-    return [/^whitelisted-/];
-}
-
-function collectWhitelistPatternsChildren() {
-    // do something to collect the whitelist
-    return [/^whitelisted-/];
-}
-
-function collectWhitelistPatternsGreedy() {
-    // do something to collect the whitelist
-    return [/^whitelisted-/];
+function collectSafelist() {
+  return {
+    standard: ['safelisted', /^safelisted-/],
+    deep: [/^safelisted-deep-/],
+    greedy: [/^safelisted-greedy/]
+  }
 }
 
 // In the webpack configuration
-new PurgecssPlugin({
-  whitelist: collectWhitelist,
-  whitelistPatterns: collectWhitelistPatterns,
-  whitelistPatternsChildren: collectWhitelistPatternsChildren,
-  whitelistPatternsGreedy: collectWhitelistPatternsGreedy
+new PurgeCSSPlugin({
+  safelist: collectSafelist
 })
 ```
 
+
 * #### rejected
 
 When this option is set to `true` all removed selectors are added to the [Stats Data](https://webpack.js.org/api/stats/) as `purged`.