roots · kellymears · Jan 2, 2022 · Jan 1, 2022 · Jan 1, 2022 · Jan 1, 2022
diff --git a/config/tsdoc.json b/config/tsdoc.json
@@ -3,6 +3,14 @@
   "extends": [
     "@microsoft/api-extractor/extends/tsdoc-base.json"
   ],
-  "tagDefinitions": [],
-  "supportForTags": {}
+  "tagDefinitions": [
+    {
+      "tagName": "@todo",
+      "allowMultiple": true,
+      "syntaxKind": "block"
+    }
+  ],
+  "supportForTags": {
+    "@todo": true
+  }
 }
diff --git a/examples/purgecss/.gitignore b/examples/purgecss/.gitignore
@@ -0,0 +1,5 @@
+node_modules
+dist
+
+# You probably will want to remove these entries
+.bud
diff --git a/examples/purgecss/bud.config.js b/examples/purgecss/bud.config.js
@@ -0,0 +1,8 @@
+module.exports = app =>
+  app
+    .template({template: 'public/index.html'})
+    .entry({app: 'app.css'})
+    .purgecss({
+      content: [app.path('project', 'public', '*.html')],
+      css: [app.path('src', '**', '*.css')],
+    })
diff --git a/examples/purgecss/jsconfig.json b/examples/purgecss/jsconfig.json
@@ -0,0 +1,5 @@
+{
+  "typeAcquisition": {
+    "enable": true
+  }
+}
diff --git a/examples/purgecss/package.json b/examples/purgecss/package.json
@@ -0,0 +1,26 @@
+{
+  "name": "example-purgecss",
+  "private": true,
+  "browserslist": {
+    "production": [
+      ">0.5%",
+      "not dead",
+      "not op_mini all"
+    ],
+    "development": [
+      "last 1 chrome version",
+      "last 1 firefox version",
+      "last 1 safari version"
+    ]
+  },
+  "devDependencies": {
+    "@fullhuman/postcss-purgecss": "4.1.3",
+    "@roots/bud": "workspace:*",
+    "@roots/bud-postcss": "workspace:*",
+    "@roots/bud-purgecss": "workspace:*",
+    "postcss": "8.4.5",
+    "postcss-import": "14.0.2",
+    "postcss-nested": "5.0.6",
+    "postcss-preset-env": "7.1.0"
+  }
+}
diff --git a/examples/purgecss/public/index.html b/examples/purgecss/public/index.html
@@ -0,0 +1,19 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta
+      name="viewport"
+      content="width=device-width, initial-scale=1"
+    />
+
+    <title>%APP_TITLE%</title>
+    <meta name="theme-color" content="%APP_COLOR%" />
+    <meta name="description" content="%APP_DESCRIPTION%" />
+  </head>
+
+  <body>
+    <h1>PostCSS</h1>
+    <h2>PurgeCss test</h2>
+  </body>
+</html>
diff --git a/examples/purgecss/src/app.css b/examples/purgecss/src/app.css
@@ -0,0 +1 @@
+@import 'main';
diff --git a/examples/purgecss/src/main.css b/examples/purgecss/src/main.css
@@ -0,0 +1,11 @@
+h1 {
+  color: black;
+}
+
+h2 {
+  color: red;
+}
+
+h3.exclude {
+  color: yellow;
+}
diff --git a/packages/@roots/bud-purgecss/package.json b/packages/@roots/bud-purgecss/package.json
@@ -73,9 +73,7 @@
     "@fullhuman/postcss-purgecss": "4.1.3",
     "@roots/bud-framework": "workspace:packages/@roots/bud-framework",
     "@roots/bud-postcss": "workspace:packages/@roots/bud-postcss",
-    "@types/jest": "27.0.3",
     "@types/node": "16.11.17",
-    "jest": "27.4.5",
     "postcss": "8.4.5"
   },
   "dependencies": {

diff --git a/packages/@roots/bud-purgecss/src/bud.env.ts b/packages/@roots/bud-purgecss/src/bud.env.ts
@@ -0,0 +1,13 @@
+import {Extension} from '@roots/bud-framework'
+
+import * as purge from './purge.interface'
+
+declare module '@roots/bud-framework' {
+  interface Framework {
+    purgecss: purge.api
+  }
+
+  interface Modules {
+    '@roots/bud-purgecss': Extension.Module
+  }
+}
diff --git a/packages/@roots/bud-purgecss/src/bud.purge.ts b/packages/@roots/bud-purgecss/src/bud.purge.ts
@@ -1,4 +1,6 @@
-import {Framework} from '@roots/bud-framework'
+import purgePlugin from '@fullhuman/postcss-purgecss'
+
+import * as purge from './purge.interface'
 
 /**
  * Purge unused CSS from compiled stylesheets
@@ -8,63 +10,20 @@ import {Framework} from '@roots/bud-framework'
  *
  * @example
  * ```js
- * app.purge({
+ * app.purgecss({
  *   content: [app.path('project', 'resources/views/**')],
  *   allow: require('purgecss-with-wordpress').whitelist,
  *   allowPatterns: require('purgecss-with-wordpress').whitelistPatterns,
  * })
  * ```
+ *
+ * @public
  */
-interface purge {
-  (this: Framework, userOptions: UserOptions): Framework
-}
-
-interface UserOptions {
-  content?: Array<string | RawContent>
-  contentFunction?: (
-    sourceFile: string,
-  ) => 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>
-}
-
-interface RawContent<T = string> {
-  extension: string
-  raw: T
-}
-
-interface RawCSS {
-  raw: string
-}
-
-type ExtractorFunction<T = string> = (content: T) => string[]
-
-interface Extractors {
-  extensions: string[]
-  extractor: ExtractorFunction
-}
-
-const purge: purge = function (
-  this: Framework,
-  userOptions: UserOptions,
-): Framework {
-  this.postcss.setPlugin('@fullhuman/postcss-purgecss', [
-    require('@fullhuman/postcss-purgecss'),
-    userOptions,
-  ])
+export const purgecss: purge.api = function (userOptions) {
+  this.postcss.setPlugin(
+    '@fullhuman/postcss-purgecss',
+    purgePlugin(userOptions),
+  )
 
   return this
 }
-
-export {purge}
diff --git a/packages/@roots/bud-purgecss/src/index.ts b/packages/@roots/bud-purgecss/src/index.ts
@@ -4,39 +4,49 @@
 /**
  * Adds purgecss support to Bud
  *
- * @remarks
- * Requires {@link @roots/bud-postcss# | @roots/bud-postcss} to be installed
+ * @example
+ * ```ts
+ * app.purge({
+ *  content: [app.path('project', 'resources/views/**')],
+ *  allow: require('purgecss-with-wordpress').whitelist,
+ *  allowPatterns: require('purgecss-with-wordpress').whitelistPatterns,
+ * })
+ * ```
  *
  * @see https://roots.io/bud
  * @see https://github.com/roots/bud
  *
- * @remarks
- * - 💁 Composable - Build exceptional applications with a modular, configurable build system
- *
- * - 💪 Modern - Modern framework written in TypeScript with an expressive API
- *
- * - 🌱 Easy - Low bundle size and fast build times
- *
  * @packageDocumentation
  */
 
-import {Extension} from '@roots/bud-framework'
+import './bud.env'
 
-import {purge} from './bud.purge'
+import {purgecss} from './bud.purge'
+import {Purge} from './purge.interface'
 
-declare module '@roots/bud-framework' {
-  interface Framework {
-    purge: purge
-  }
+/**
+ * Module name
+ *
+ * @public
+ */
+export const name: Purge['name'] = '@roots/bud-purgecss'
 
-  /**
-   * {@inheritDoc @roots/bud-framework#Modules}
-   * @public @override
-   */
-  interface Modules {
-    '@roots/bud-purgecss': Extension.Module
-  }
-}
+/**
+ * Module api
+ *
+ * @public
+ */
+export const api: Purge['api'] = {purgecss}
 
-export const name = '@roots/bud-purgecss'
-export const api = {purge}
+/**
+ * Module registration
+ *
+ * @todo facade bindings to `@roots/bud-extension`
+ *
+ * @public
+ */
+export const register: Purge['register'] = async app => {
+  app.api.set('purgecss', purgecss.bind(app))
+  // @ts-ignore
+  app.api.bindFacade('purgecss')
+}
diff --git a/packages/@roots/bud-purgecss/src/purge.interface.ts b/packages/@roots/bud-purgecss/src/purge.interface.ts
@@ -0,0 +1,87 @@
+import {Extension, Framework} from '@roots/bud-framework'
+
+/**
+ * Module registration
+ *
+ * @public
+ */
+export interface register {
+  (app: Framework): Promise<void>
+}
+
+/**
+ * Purge unused CSS from compiled stylesheets
+ *
+ * @remarks
+ * For more information, see [the PurgeCSS API](https://purgecss.com/configuration.html)
+ *
+ * @example
+ * ```js
+ * app.purgecss({
+ *   content: [app.path('project', 'resources/views/**')],
+ *   allow: require('purgecss-with-wordpress').whitelist,
+ *   allowPatterns: require('purgecss-with-wordpress').whitelistPatterns,
+ * })
+ * ```
+ */
+export interface api {
+  (this: Framework, userOptions: UserOptions): Framework
+}
+
+export interface Purge extends Extension.Module {
+  name: string
+  register: register
+  api: {purgecss: api}
+}
+
+/**
+ * PurgeCSS UserOptions
+ *
+ * @see https://purgecss.com/plugins/postcss.html#options
+ *
+ * @public
+ */
+export interface UserOptions {
+  content?: Array<
+    | string
+    | {
+        extension: string
+        raw: string
+      }
+  >
+  contentFunction?: (sourceFile: string) => Array<
+    | string
+    | {
+        extension: string
+        raw: string
+      }
+  >
+  defaultExtractor?: ExtractorFunction
+  extractors?: Array<Extractors>
+  fontFace?: boolean
+  keyframes?: boolean
+  output?: string
+  rejected?: boolean
+  stdin?: boolean
+  stdout?: boolean
+  variables?: boolean
+  safelist?:
+    | {
+        standard?: Array<RegExp | string>
+        deep?: RegExp[]
+        greedy?: RegExp[]
+        variables?: Array<RegExp | string>
+        keyframes?: Array<RegExp | string>
+      }
+    | Array<RegExp | string>
+  blocklist?: Array<RegExp | string>
+}
+
+export type ExtractorFunction<T = string> = (
+  content: T,
+) => string[]
+
+export interface Extractors {
+  extensions: string[]
+  extractor: ExtractorFunction
+}
diff --git a/packages/@roots/bud-purgecss/tsconfig.json b/packages/@roots/bud-purgecss/tsconfig.json
@@ -7,20 +7,13 @@
     "declarationDir": "./types",
     "types": [
       "node",
-      "jest",
       "@roots/bud-api",
       "@roots/bud-framework",
       "@roots/bud-postcss"
     ]
   },
-  "include": [
-    "src"
-  ],
-  "exclude": [
-    "lib",
-    "node_modules",
-    "types"
-  ],
+  "include": ["src"],
+  "exclude": ["lib", "node_modules", "types"],
   "references": [
     {
       "path": "./../bud-framework/tsconfig.json"