html-minifier-next 7.5.2 → 7.6.0

package/src/htmlminifier.js

@@ -2,11 +2,13 @@ import { HTMLParser, endTag } from './htmlparser.js';
 import TokenChain from './tokenchain.js';
 import { presets, getPreset, getPresetNames } from './presets.js';
 
-import { LRU, identity, isThenable, lowercase, uniqueId } from './lib/utils.js';
+import { LRU, findTagEnd, identity, isThenable, lowercase, uniqueId } from './lib/utils.js';
+import { collectUsedSymbols } from './lib/unused-css.js';
 
 import {
   RE_LEGACY_ENTITIES,
   RE_ESCAPE_LT,
+  RE_STYLE_ELEMENT,
   inlineElementsToKeepWhitespaceAround,
   inlineElementsToKeepWhitespaceWithin,
   specialContentElements,
@@ -437,6 +439,20 @@ import { processOptions } from './lib/options.js';
  *
  *  Default: `false`
  *
+ * @prop {boolean | {safelist?: Array<string | RegExp>, scripts?: boolean}} [removeUnusedCSS]
+ *  **Note that this can change how a document renders!**
+ *
+ *  Remove rules from `style` elements whose class or ID selectors the document
+ *  never references. Requires `minifyCSS` (removal runs through Lightning CSS)
+ *  and has no effect on `style` or `media` attributes.
+ *
+ *  Class names and IDs are collected from the markup, from `data-*` attributes,
+ *  and—unless `scripts` is set to `false`—from inline `script` elements. Names
+ *  that only ever appear in external scripts cannot be detected; list those
+ *  under `safelist` (strings or regular expressions) to keep them.
+ *
+ *  Default: `false`
+ *
  * @prop {boolean | ((tag: string, attrs: HTMLAttribute[]) => void)} [sortAttributes]
  *  When true, enables sorting of attributes. If a function is provided it
  *  will be used as a custom attribute sorter, which should mutate `attrs`
@@ -570,28 +586,6 @@ const RE_FOREIGN_ELEMENT_PROBE = /<(?:svg|math)[\s/>]/i;
 
 // Script merging
 
-/**
- * Find the index of the `>` that closes an opening tag, correctly skipping
- * over quoted attribute values (which may contain `>`).
- * @param {string} html
- * @param {number} pos - Start position (just after the tag name)
- * @returns {number} Index of the closing `>`, or -1 if not found
- */
-function findTagEnd(html, pos) {
-  let i = pos;
-  while (i < html.length) {
-    const ch = html[i];
-    if (ch === '>') return i;
-    if (ch === '"' || ch === "'") {
-      const q = ch;
-      i++;
-      while (i < html.length && html[i] !== q) i++;
-    }
-    i++;
-  }
-  return -1;
-}
-
 /**
  * Merge consecutive inline script tags into one (`mergeConsecutiveScripts`).
  * Only merges scripts that are compatible:
@@ -910,23 +904,23 @@ async function createSortFns(value, options, uidIgnore, uidAttr, ignoredMarkupCh
     // Memoize `sortClassNames` results—class lists often repeat in templates
     const classNameCache = new LRU(500);
 
-    options.sortClassNames = function (/** @type {string} */ value) {
+    options.sortClassNames = function (/** @type {string} */ classNames) {
       // Fast path: Single class (no spaces) needs no sorting
-      if (value.indexOf(' ') === -1) {
-        return value;
+      if (classNames.indexOf(' ') === -1) {
+        return classNames;
       }
 
       // Check cache first
-      const cached = /** @type {string | undefined} */ (classNameCache.get(value));
+      const cached = /** @type {string | undefined} */ (classNameCache.get(classNames));
       if (cached !== undefined) {
         return cached;
       }
 
       // Expand UID tokens back to original content before sorting
       // Fast path: Skip if no HTML comments (UID markers) present
-      let expandedValue = value;
-      if (uidReplacePattern && value.indexOf('<!--') !== -1) {
-        expandedValue = value.replace(uidReplacePattern, function (/** @type {string} */ _match, /** @type {string} */ index) {
+      let expandedValue = classNames;
+      if (uidReplacePattern && classNames.indexOf('<!--') !== -1) {
+        expandedValue = classNames.replace(uidReplacePattern, function (/** @type {string} */ _match, /** @type {string} */ index) {
           return ignoredMarkupChunks[+index] || '';
         });
         // Reset `lastIndex` for pattern reuse
@@ -939,7 +933,7 @@ async function createSortFns(value, options, uidIgnore, uidAttr, ignoredMarkupCh
       const result = sorted.join(' ');
 
       // Cache the result
-      classNameCache.set(value, result);
+      classNameCache.set(classNames, result);
       return result;
     };
   }
@@ -1092,13 +1086,13 @@ async function minifyHTML(value, options, partialMarkup) {
 
           if (options.minifyCSS !== identity) {
             options.minifyCSS = (function (/** @type {ProcessedOptions['minifyCSS']} */ fn) {
-              return function (/** @type {string} */ text, /** @type {string | undefined} */ type) {
+              return function (/** @type {string} */ text, /** @type {string | undefined} */ type, /** @type {ProcessedOptions['cssContext']} */ context) {
                 text = text.replace(/** @type {RegExp} */ (uidPattern), function (/** @type {string} */ _match, /** @type {string} */ _prefix, /** @type {string} */ index) {
                   const chunks = ignoredCustomMarkupChunks[+index];
                   return (chunks?.[1] ?? '') + uidAttr + index + uidAttr + (chunks?.[2] ?? '');
                 });
 
-                return fn(text, type);
+                return fn(text, type, context);
               };
             })(options.minifyCSS);
           }
@@ -1148,11 +1142,11 @@ async function minifyHTML(value, options, partialMarkup) {
 
   // Look for trailing whitespaces, bypass any inline tags
   function trimTrailingWhitespace(/** @type {number} */ index, /** @type {string} */ nextTag) {
-    for (let endTag = ''; index >= 0 && canTrimWhitespace(endTag, emptyAttrs); index--) {
+    for (let prevTag = ''; index >= 0 && canTrimWhitespace(prevTag, emptyAttrs); index--) {
       const str = buffer[index] ?? '';
       const match = str.match(/^<\/([\w:-]+)>$/);
       if (match) {
-        endTag = match[1] ?? '';
+        prevTag = match[1] ?? '';
       } else if (/>$/.test(str) || (buffer[index] = collapseWhitespaceSmart(str, '', nextTag, emptyAttrs, emptyAttrs, options, inlineElements, inlineTextSet))) {
         break;
       }
@@ -1398,13 +1392,13 @@ async function minifyHTML(value, options, partialMarkup) {
                   // Collapse if both sides are element/closing tags or HTML comments, and neither is inline
                   if ((currentTagMatch || currentIsHtmlComment || currentClosingTagMatch) &&
                       (prevTagMatch || prevIsHtmlComment || prevClosingTagMatch)) {
-                    const currentTag = currentTagMatch ? resolveName(currentTagMatch[1] ?? '')
+                    const currentTagName = currentTagMatch ? resolveName(currentTagMatch[1] ?? '')
                       : currentClosingTagMatch ? resolveName(currentClosingTagMatch[1] ?? '') : null;
-                    const prevTag = prevTagMatch ? resolveName(prevTagMatch[1] ?? '')
+                    const prevTagName = prevTagMatch ? resolveName(prevTagMatch[1] ?? '')
                       : prevClosingTagMatch ? resolveName(prevClosingTagMatch[1] ?? '') : null;
 
                     // Don’t collapse between inline elements (HTML comments count as non-inline)
-                    if (!inlineElements.has(currentTag ?? '') && !inlineElements.has(prevTag ?? '')) {
+                    if (!inlineElements.has(currentTagName ?? '') && !inlineElements.has(prevTagName ?? '')) {
                       // Collapse whitespace respecting context rules
                       let collapsedText = prevText;
 
@@ -1758,7 +1752,7 @@ async function minifyHTML(value, options, partialMarkup) {
           text = await options.minifyJS(text, false, isModuleScript);
         }
         if (needsMinifyCSS) {
-          text = await options.minifyCSS(text);
+          text = await options.minifyCSS(text, undefined, options.cssContext);
         }
         charsFinalize(text);
       })();
@@ -2094,6 +2088,25 @@ export const minify = async function (value, options) {
   }
   // Work on a shallow copy so per-call reassignments don’t reach the cached base
   const processedOptions = /** @type {ProcessedOptions} */ ({ ...processedBase });
+
+  // Warnings are deduplicated per document, so the state has to live on the per-call
+  // copy; the `minifyCSS` closure hangs off the memoized base, shared across calls
+  processedOptions.cssContext = { warned: new Set() };
+
+  // Unused-CSS removal needs the whole document’s symbols before the first `style`
+  // element is minified, so collect them upfront from the raw input. A document
+  // without a style sheet has nothing to remove from, and scanning it would be work
+  // spent on an empty result.
+  if (processedOptions.removeUnusedCSS && RE_STYLE_ELEMENT.test(value)) {
+    processedOptions.cssContext.usedSymbols = collectUsedSymbols(
+      value,
+      processedOptions.removeUnusedCSS.scripts,
+      value.indexOf('&') !== -1
+        ? /** @type {(text: string) => string} */ (await getDecodeHTML())
+        : undefined
+    );
+  }
+
   let result = await minifyHTML(value, processedOptions);
 
   // Post-processing: Merge consecutive inline scripts if enabled

package/src/htmlparser.js

@@ -154,7 +154,7 @@ function buildAttrRegex(handler) {
 
 /** @param {HTMLParserHandler} handler */
 function getAttrRegexForHandler(handler) {
-  let cached = attrRegexCache.get(handler);
+  const cached = attrRegexCache.get(handler);
   if (cached) return cached;
   const compiled = buildAttrRegex(handler);
   attrRegexCache.set(handler, compiled);
@@ -166,7 +166,7 @@ const attrRegexStickyCache = new WeakMap();
 
 /** @param {HTMLParserHandler} handler */
 function getAttrRegexStickyForHandler(handler) {
-  let cached = attrRegexStickyCache.get(handler);
+  const cached = attrRegexStickyCache.get(handler);
   if (cached) return cached;
   const nonSticky = getAttrRegexForHandler(handler);
   // Derive sticky version: Remove `^` anchor, add `y` flag
@@ -657,12 +657,12 @@ export class HTMLParser {
 
     // `needle` must already be lowercase
     function findTagInCurrentTable(/** @type {string} */ needle) {
-      let pos;
-      for (pos = stack.length - 1; pos >= 0; pos--) {
-        const entry = stack[pos];
+      let stackIndex;
+      for (stackIndex = stack.length - 1; stackIndex >= 0; stackIndex--) {
+        const entry = stack[stackIndex];
         const currentTag = entry?.lowerTag;
         if (currentTag === needle) {
-          return pos;
+          return stackIndex;
         }
         // Stop searching if hitting a table boundary
         if (currentTag === 'table') {
@@ -672,25 +672,25 @@ export class HTMLParser {
       return -1;
     }
 
-    function parseEndTagAt(/** @type {number} */ pos) {
-      // Close all open elements up to `pos` (mirrors `parseEndTag`’s core branch);
+    function parseEndTagAt(/** @type {number} */ stackIndex) {
+      // Close all open elements up to `stackIndex` (mirrors `parseEndTag`’s core branch);
       // `end` handlers are synchronous—invoked without awaiting, as in `parseEndTag`
-      for (let i = stack.length - 1; i >= pos; i--) {
+      for (let i = stack.length - 1; i >= stackIndex; i--) {
         const entry = /** @type {NonNullable<(typeof stack)[number]>} */ (stack[i]);
         if (handler.end) {
           handler.end(entry.tag, entry.attrs, true);
         }
       }
-      stack.length = pos;
-      lastTag = pos ? (stack[pos - 1]?.tag ?? '') : '';
-      lastTagLower = pos ? (stack[pos - 1]?.lowerTag ?? '') : '';
+      stack.length = stackIndex;
+      lastTag = stackIndex ? (stack[stackIndex - 1]?.tag ?? '') : '';
+      lastTagLower = stackIndex ? (stack[stackIndex - 1]?.lowerTag ?? '') : '';
     }
 
     function closeIfFoundInCurrentTable(/** @type {string} */ tagName) {
-      const pos = findTagInCurrentTable(tagName);
-      if (pos >= 0) {
+      const stackIndex = findTagInCurrentTable(tagName);
+      if (stackIndex >= 0) {
         // Close at the specific index to avoid re-searching
-        parseEndTagAt(pos);
+        parseEndTagAt(stackIndex);
         return true;
       }
       return false;
@@ -812,38 +812,38 @@ export class HTMLParser {
 
     // `needle` must already be lowercase
     function findTag(/** @type {string} */ needle) {
-      let pos;
-      for (pos = stack.length - 1; pos >= 0; pos--) {
-        if (stack[pos]?.lowerTag === needle) {
+      let stackIndex;
+      for (stackIndex = stack.length - 1; stackIndex >= 0; stackIndex--) {
+        if (stack[stackIndex]?.lowerTag === needle) {
           break;
         }
       }
-      return pos;
+      return stackIndex;
     }
 
     async function parseEndTag(/** @type {string} */ tag, /** @type {string} */ tagName) {
-      let pos;
+      let stackIndex;
       const lowerTagName = tagName ? tagName.toLowerCase() : '';
 
       // Find the closest opened tag of the same type
       if (tagName) {
-        pos = findTag(lowerTagName);
+        stackIndex = findTag(lowerTagName);
       } else { // If no tag name is provided, clean shop
-        pos = 0;
+        stackIndex = 0;
       }
 
-      if (pos >= 0) {
+      if (stackIndex >= 0) {
         // Close all the open elements, up the stack
-        for (let i = stack.length - 1; i >= pos; i--) {
+        for (let i = stack.length - 1; i >= stackIndex; i--) {
           if (handler.end) {
-            handler.end(stack[i]?.tag, stack[i]?.attrs, i > pos || !tag);
+            handler.end(stack[i]?.tag, stack[i]?.attrs, i > stackIndex || !tag);
           }
         }
 
         // Remove the open elements from the stack
-        stack.length = pos;
-        lastTag = pos ? (stack[pos - 1]?.tag ?? '') : '';
-        lastTagLower = pos ? (stack[pos - 1]?.lowerTag ?? '') : '';
+        stack.length = stackIndex;
+        lastTag = stackIndex ? (stack[stackIndex - 1]?.tag ?? '') : '';
+        lastTagLower = stackIndex ? (stack[stackIndex - 1]?.lowerTag ?? '') : '';
       } else if (handler.partialMarkup && tagName) {
         // In partial markup mode, preserve stray end tags
         if (handler.end) {

package/src/lib/attributes.js

@@ -470,7 +470,7 @@ function cleanAttributeValue(tag, attrName, attrValue, options, attrs, minifyHTM
         attrValue = attrValue.replace(/\s*;$/, ';');
       }
       const originalAttrValue = attrValue;
-      const cssResult = options.minifyCSS(attrValue, 'inline');
+      const cssResult = options.minifyCSS(attrValue, 'inline', options.cssContext);
       if (isThenable(cssResult)) {
         return cssResult
           .then((/** @type {string} */ minified) => {
@@ -487,7 +487,7 @@ function cleanAttributeValue(tag, attrName, attrValue, options, attrs, minifyHTM
       }
       // Sync path (`minifyCSS` disabled—identity function)
       if (cssResult && /^(?:[a-z-]+:[;\s]*)+$/i.test(cssResult)) return '';
-      return cssResult != null ? cssResult : attrValue;
+      return cssResult ?? attrValue;
     }
     return attrValue;
   }
@@ -581,7 +581,7 @@ function cleanAttributeValue(tag, attrName, attrValue, options, attrs, minifyHTM
       return attrValue;
     }
     const originalAttrValue = attrValue;
-    const cssResult = options.minifyCSS(attrValue, 'media');
+    const cssResult = options.minifyCSS(attrValue, 'media', options.cssContext);
     if (isThenable(cssResult)) {
       return cssResult.catch((/** @type {Error} */ err) => {
         if (!options.continueOnMinifyError) throw err;
@@ -589,7 +589,7 @@ function cleanAttributeValue(tag, attrName, attrValue, options, attrs, minifyHTM
         return originalAttrValue;
       });
     }
-    return cssResult != null ? cssResult : attrValue;
+    return cssResult ?? attrValue;
   }
 
   if (tag === 'iframe' && attrName === 'srcdoc') {
@@ -635,7 +635,7 @@ function chooseAttributeQuote(attrValue, options) {
  */
 function normalizeAttr(attr, attrs, tag, options, minifyHTML) {
   const attrName = options.name(attr.name);
-  let attrValue = attr.value;
+  const attrValue = attr.value;
 
   // Entity decoding requires a lazy import—async only when `&` is present
   if (options.decodeEntities && attrValue && attrValue.indexOf('&') !== -1) {

package/src/lib/constants.js

@@ -16,6 +16,7 @@ const RE_ESCAPE_LT = /</g;
 const RE_ATTR_WS_CHECK = /[ \n\r\t\f]/;
 const RE_ATTR_WS_COLLAPSE = /[ \n\r\t\f]+/g;
 const RE_ATTR_WS_TRIM = /^[ \n\r\t\f]+|[ \n\r\t\f]+$/g;
+const RE_STYLE_ELEMENT = /<style[\s/>]/i;
 
 // Inline element sets for whitespace handling
 
@@ -192,6 +193,7 @@ export {
   RE_ATTR_WS_CHECK,
   RE_ATTR_WS_COLLAPSE,
   RE_ATTR_WS_TRIM,
+  RE_STYLE_ELEMENT,
   // Inline element sets
   inlineElementsToKeepWhitespaceAround,
   inlineElementsToKeepWhitespaceWithin,

package/src/lib/elements.js

@@ -137,7 +137,7 @@ function canRemoveElement(tag, attrs) {
 }
 
 /**
- * @param {string} str - Tag name or HTML-like element spec (e.g., “td” or “<span aria-hidden='true'>”)
+ * @param {string} str - Tag name or HTML-like element spec (e.g., `td` or `<span aria-hidden='true'>`)
  * @param {ProcessedOptions} options - Options object for name normalization
  * @returns {{tag: string, attrs: Object.<string, string|undefined>|null}|null} Parsed spec or null if invalid
  */
@@ -203,12 +203,12 @@ function parseRemoveEmptyElementsExcept(input, options) {
     if (typeof item === 'string') {
       const spec = parseElementSpec(item, options);
       if (!spec && options.log) {
-        options.log('Warning: Unable to parse “removeEmptyElementsExcept” specification: “' + item + '”');
+        options.log('Warning: Unable to parse `removeEmptyElementsExcept` specification: “' + item + '”');
       }
       return spec;
     }
     if (options.log) {
-      options.log('Warning: “removeEmptyElementsExcept” specification must be a string, received: ' + typeof item);
+      options.log('Warning: `removeEmptyElementsExcept` specification must be a string, received: ' + typeof item);
     }
     return null;
   }).filter(Boolean));

package/src/lib/option-definitions.js

@@ -104,15 +104,15 @@ const optionDefinitions = {
   },
   minifyCSS: {
     description: 'Minify CSS in `style` elements and attributes (uses Lightning CSS)',
-    type: 'json'
+    type: 'jsonObject'
   },
   minifyJS: {
     description: 'Minify JavaScript in `script` elements and event attributes (uses Terser or SWC; pass `{"engine": "swc"}` for SWC)',
-    type: 'json'
+    type: 'jsonObject'
   },
   minifySVG: {
     description: 'Minify SVG elements (uses SVGO)',
-    type: 'json'
+    type: 'jsonObject'
   },
   minifyURLs: {
     description: 'Minify URLs in various attributes',
@@ -178,6 +178,10 @@ const optionDefinitions = {
     description: 'Remove space between attributes whenever possible; note that this will result in invalid HTML',
     type: 'boolean'
   },
+  removeUnusedCSS: {
+    description: 'Remove rules from `style` elements whose class or ID selectors the document never references (requires `--minify-css`); note that class names only applied by external scripts cannot be detected—use `{"safelist": […]}` for those',
+    type: 'jsonObject'
+  },
   sortAttributes: {
     description: 'Sort attributes by frequency',
     type: 'boolean'