purgecss-from-html 7.0.2 → 9.0.0

package/README.md

@@ -1,11 +1,94 @@
-# `purgecss-from-html`
+# purgecss-from-html
 
-> TODO: description
+[![npm version](https://img.shields.io/npm/v/purgecss-from-html.svg)](https://www.npmjs.com/package/purgecss-from-html)
+
+HTML extractor for [PurgeCSS](https://purgecss.com). This extractor parses HTML files and extracts used selectors with detailed information about tags, classes, IDs, and attributes.
+
+## Installation
+
+```bash
+npm install purgecss-from-html --save-dev
+```
 
 ## Usage
 
+### With PurgeCSS
+
+```js
+import { PurgeCSS } from "purgecss";
+import purgeFromHtml from "purgecss-from-html";
+
+const result = await new PurgeCSS().purge({
+  content: ["**/*.html"],
+  css: ["**/*.css"],
+  extractors: [
+    {
+      extractor: purgeFromHtml,
+      extensions: ["html"],
+    },
+  ],
+});
 ```
-const purgecssFromHtml = require('purgecss-from-html');
 
-// TODO: DEMONSTRATE API
+### Standalone
+
+You can also use the extractor standalone to extract selectors from HTML content:
+
+```js
+import purgeFromHtml from "purgecss-from-html";
+
+const html = `
+  <div class="container">
+    <h1 id="title" data-section="hero">Hello World</h1>
+    <button class="btn btn-primary">Click me</button>
+  </div>
+`;
+
+const result = purgeFromHtml(html);
+
+console.log(result);
+// {
+//   attributes: {
+//     names: ["class", "id", "data-section", "class"],
+//     values: ["container", "title", "hero", "btn", "btn-primary"]
+//   },
+//   classes: ["container", "btn", "btn-primary"],
+//   ids: ["title"],
+//   tags: ["html", "head", "body", "div", "h1", "button"],
+//   undetermined: []
+// }
 ```
+
+## API
+
+### `purgeFromHtml(content: string): ExtractorResultDetailed`
+
+Parses HTML content and returns detailed selector information.
+
+#### Parameters
+
+- `content` - HTML code as a string
+
+#### Returns
+
+An `ExtractorResultDetailed` object containing:
+
+- `attributes.names` - Array of attribute names found in the HTML
+- `attributes.values` - Array of attribute values (split by spaces)
+- `classes` - Array of class names extracted from `class` attributes
+- `ids` - Array of IDs extracted from `id` attributes
+- `tags` - Array of HTML tag names used
+- `undetermined` - Array of selectors that couldn't be categorized
+
+## How It Works
+
+This extractor uses [parse5](https://github.com/inikulin/parse5) to parse the HTML into an AST and then walks through the tree to extract:
+
+1. **Tag names** - All HTML elements (e.g., `div`, `span`, `button`)
+2. **Classes** - Values from `class` attributes, split by spaces
+3. **IDs** - Values from `id` attributes
+4. **Attributes** - Both attribute names and values, useful for attribute selectors like `[data-theme]` or `[class*=foo]`
+
+## License
+
+MIT License

package/lib/purgecss-from-html.esm.js

@@ -24,9 +24,7 @@ const getSelectorsInElement = (element) => {
         },
         classes: [],
         ids: [],
-        tags: [element.name],
-        undetermined: [],
-    };
+        tags: [element.name]};
     for (const [name, value] of Object.entries(element.attribs)) {
         if (name === "class") {
             result.classes.push(...value.split(" "));

package/lib/purgecss-from-html.js

@@ -46,9 +46,7 @@ const getSelectorsInElement = (element) => {
         },
         classes: [],
         ids: [],
-        tags: [element.name],
-        undetermined: [],
-    };
+        tags: [element.name]};
     for (const [name, value] of Object.entries(element.attribs)) {
         if (name === "class") {
             result.classes.push(...value.split(" "));

package/package.json

@@ -1,10 +1,13 @@
 {
   "name": "purgecss-from-html",
-  "version": "7.0.2",
+  "version": "9.0.0",
   "description": "HTML extractor for PurgeCSS",
   "author": "Ffloriel",
   "homepage": "https://github.com/FullHuman/purgecss#readme",
-  "license": "ISC",
+  "license": "MIT",
+  "engines": {
+    "node": ">=22.12.0"
+  },
   "main": "lib/purgecss-from-html.js",
   "directories": {
     "lib": "lib",
@@ -17,20 +20,19 @@
     "type": "git",
     "url": "git+https://github.com/FullHuman/purgecss.git"
   },
-  "scripts": {
-    "build": "ts-node build.ts",
-    "test": "jest"
-  },
   "bugs": {
     "url": "https://github.com/FullHuman/purgecss/issues"
   },
   "dependencies": {
-    "parse5": "^7.1.2",
-    "parse5-htmlparser2-tree-adapter": "^7.0.0"
+    "parse5": "^8.0.1",
+    "parse5-htmlparser2-tree-adapter": "^8.0.1"
   },
   "publishConfig": {
     "access": "public",
     "registry": "https://registry.npmjs.org/"
   },
-  "gitHead": "e95398d961e03a809b5e3da75e3dae1813b46b68"
-}
+  "scripts": {
+    "build": "ts-node build.ts",
+    "test": "jest"
+  }
+}