@thejaredwilcurt/csslop 0.0.1

package/src/index.js

@@ -0,0 +1,90 @@
+/**
+ * @file CSS minification entry point.
+ */
+
+import { parse } from '@node-projects/css-parser';
+
+import { createMinifyContext } from './context.js';
+import {
+  analyzePositionTryRules,
+  cleanPositionTryRules,
+  collectRuleMetadata,
+  filterRedundantCharsets,
+  filterUnusedPositionTry
+} from './position-try.js';
+import { preprocessDeclarationBlocks } from './preprocess.js';
+import {
+  deduplicateKeyframes,
+  expandPureNestedRules,
+  mergeByDeclarations,
+  mergeLayerRules,
+  mergeMediaRules,
+  mergeSelectorRules,
+  nestFlatRules
+} from './rules/optimize.js';
+import { stringifyRule } from './rules/stringify.js';
+import { minifyValue } from './value/minify.js';
+
+/**
+ * Parses, optimizes, and minifies a CSS string by applying rule merging, declaration deduplication, value compression, and dead-code elimination.
+ *
+ * @param  {string} input  The raw CSS string to minify.
+ * @return {string}        The fully minified CSS string, or the original input if parsing fails.
+ */
+export const minifyCSS = function (input) {
+  let source;
+  if (typeof input === 'string') {
+    source = input;
+  } else {
+    source = String(input ?? '');
+  }
+  let ast;
+  const output = [];
+
+  try {
+    ast = parse(preprocessDeclarationBlocks(source), { preserveFormatting: true });
+  } catch {
+    return source;
+  }
+
+  const context = createMinifyContext();
+
+  if (ast?.stylesheet?.rules) {
+    const {
+      positionTryRules,
+      positionTryUsage
+    } = collectRuleMetadata(ast.stylesheet.rules, context);
+
+    analyzePositionTryRules(
+      ast.stylesheet.rules,
+      minifyValue,
+      positionTryRules,
+      positionTryUsage
+    );
+    cleanPositionTryRules(ast.stylesheet.rules);
+
+    ast.stylesheet.rules = filterUnusedPositionTry(
+      ast.stylesheet.rules,
+      positionTryRules,
+      positionTryUsage
+    );
+    ast.stylesheet.rules = filterRedundantCharsets(ast.stylesheet.rules);
+
+    ast.stylesheet.rules = expandPureNestedRules(ast.stylesheet.rules);
+    ast.stylesheet.rules = mergeLayerRules(ast.stylesheet.rules, mergeSelectorRules);
+    ast.stylesheet.rules = mergeMediaRules(ast.stylesheet.rules, mergeSelectorRules);
+    ast.stylesheet.rules = deduplicateKeyframes(ast.stylesheet.rules);
+
+    const mergedRules = mergeSelectorRules(ast.stylesheet.rules);
+    const declarationMergedRules = mergeByDeclarations(mergedRules);
+    const finalRules = nestFlatRules(declarationMergedRules);
+
+    for (const rule of finalRules) {
+      output.push(stringifyRule(rule, context));
+    }
+
+    return output.join('');
+  }
+
+  return source;
+};

package/src/position-try.js

@@ -0,0 +1,199 @@
+/**
+ * @file Handles `@position-try` rule analysis, usage tracking, and dead-rule elimination during CSS minification.
+ */
+
+/**
+ * Scans top-level rules to register `@property` custom properties in the context and collect `@position-try` rule declarations and initial usage counts.
+ *
+ * @param  {Array}  rules    The top-level AST rule nodes to scan.
+ * @param  {object} context  The minification context to populate with custom property registrations.
+ * @return {object}          An object with positionTryRules Map and positionTryUsage Map.
+ */
+function collectRuleMetadata (rules, context) {
+  const positionTryRules = new Map();
+  const positionTryUsage = new Map();
+
+  for (const rule of rules) {
+    if (rule.type === 'property' && rule.name) {
+      context.registeredCustomProperties.add(rule.name);
+      const syntaxDeclaration = (rule.declarations || []).find((declaration) => {
+        return declaration.type !== 'whitespace' && declaration.property === 'syntax';
+      });
+      if (syntaxDeclaration?.value) {
+        context.registeredCustomPropertySyntax.set(rule.name, syntaxDeclaration.value);
+      }
+    }
+    if (rule.type === 'position-try') {
+      const declarations = (rule.declarations || []).filter((declaration) => {
+        return declaration.type !== 'whitespace';
+      });
+      if (declarations.length > 0) {
+        positionTryRules.set(rule.name, declarations);
+        positionTryUsage.set(rule.name, 0);
+      }
+    }
+  }
+
+  return {
+    positionTryRules,
+    positionTryUsage
+  };
+}
+
+/**
+ * Walks rules to resolve position-try-fallbacks references, replacing simple single-declaration patterns with built-in keywords like flip-block and tracking usage counts.
+ *
+ * @param {Array}                    rules             The AST rule nodes to analyze.
+ * @param {function(object): string} minifyValue       The value minification function for resolving declaration values.
+ * @param {Map}                      positionTryRules  Map of `@position-try` names to their declaration arrays.
+ * @param {Map}                      positionTryUsage  Map of `@position-try` names to their reference counts.
+ */
+function analyzePositionTryRules (rules, minifyValue, positionTryRules, positionTryUsage) {
+  for (const rule of rules) {
+    if (rule.type === 'rule') {
+      let basePositionArea = null;
+      for (const declaration of rule.declarations || []) {
+        if (declaration.type !== 'whitespace' && declaration.property === 'position-area') {
+          basePositionArea = minifyValue(declaration);
+        }
+      }
+
+      for (const declaration of rule.declarations || []) {
+        const isPositionTryProperty = (
+          declaration.type !== 'whitespace' &&
+          (declaration.property === 'position-try-fallbacks' || declaration.property === 'position-try')
+        );
+        if (!isPositionTryProperty) {
+          continue;
+        }
+
+        const minifiedValue = minifyValue(declaration);
+        const parts = minifiedValue.split(',').map((segment) => {
+          return segment.trim();
+        });
+        const replacedParts = [];
+
+        for (const part of parts) {
+          if (!part.startsWith('--')) {
+            replacedParts.push(part);
+            continue;
+          }
+
+          if (!positionTryRules.has(part)) {
+            replacedParts.push(part);
+            continue;
+          }
+
+          const tryDeclarations = positionTryRules.get(part);
+          const isSinglePositionArea = (
+            tryDeclarations.length === 1 &&
+            tryDeclarations[0].property === 'position-area' &&
+            basePositionArea
+          );
+
+          if (isSinglePositionArea) {
+            const tryValue = minifyValue(tryDeclarations[0]);
+            const isVerticalFlip = (
+              (basePositionArea === 'top' && tryValue === 'bottom') ||
+              (basePositionArea === 'bottom' && tryValue === 'top')
+            );
+
+            if (isVerticalFlip && parts.length === 1) {
+              replacedParts.push('flip-block');
+              continue;
+            }
+          }
+
+          replacedParts.push(part);
+          const currentUsage = positionTryUsage.get(part);
+          positionTryUsage.set(part, currentUsage + 1);
+        }
+
+        declaration.value = replacedParts.join(',');
+      }
+    } else if (rule.rules) {
+      analyzePositionTryRules(rule.rules, minifyValue, positionTryRules, positionTryUsage);
+    }
+  }
+}
+
+/**
+ * Removes empty position-try-fallbacks and position-try declarations left with blank values after analysis inlined their references.
+ *
+ * @param {Array} rules  The AST rule nodes to clean in place.
+ */
+function cleanPositionTryRules (rules) {
+  for (const rule of rules) {
+    if (rule.type === 'rule') {
+      rule.declarations = (rule.declarations || []).filter((declaration) => {
+        const isPositionTryProperty = (
+          declaration.type !== 'whitespace' &&
+          (declaration.property === 'position-try-fallbacks' || declaration.property === 'position-try')
+        );
+        if (isPositionTryProperty) {
+          return declaration.value !== '';
+        }
+        return true;
+      });
+    } else if (rule.rules) {
+      cleanPositionTryRules(rule.rules);
+    }
+  }
+}
+
+/**
+ * Filters out unused `@position-try` rules whose references were fully inlined.
+ *
+ * @param  {Array} rules             The top-level AST rule nodes to filter.
+ * @param  {Map}   positionTryRules  Map of `@position-try` names to their declaration arrays.
+ * @param  {Map}   positionTryUsage  Map of `@position-try` names to their reference counts.
+ * @return {Array}                   A new array of rules with unused `@position-try` entries removed.
+ */
+function filterUnusedPositionTry (rules, positionTryRules, positionTryUsage) {
+  return rules.filter((rule) => {
+    if (rule.type === 'position-try') {
+      if (!positionTryRules.has(rule.name)) {
+        return false;
+      }
+      if (positionTryUsage.get(rule.name) === 0) {
+        return false;
+      }
+    }
+    return true;
+  });
+}
+
+/**
+ * Removes duplicate and redundant UTF-8 `@charset` rules, keeping only the first
+ * non-UTF-8 charset declaration.
+ *
+ * @param  {Array} rules  The top-level AST rule nodes to filter.
+ * @return {Array}        A new array of rules with redundant `@charset` entries removed.
+ */
+function filterRedundantCharsets (rules) {
+  let firstCharsetFound = false;
+
+  return rules.filter((rule) => {
+    if (rule.type === 'charset') {
+      if (!firstCharsetFound) {
+        firstCharsetFound = true;
+        // Strip surrounding quotes from the charset value for comparison
+        const normalizedCharset = rule.charset?.toLowerCase().replace(/["']/g, '');
+        if (normalizedCharset === 'utf-8') {
+          return false;
+        }
+        return true;
+      }
+      return false;
+    }
+    return true;
+  });
+}
+
+export {
+  analyzePositionTryRules,
+  cleanPositionTryRules,
+  collectRuleMetadata,
+  filterRedundantCharsets,
+  filterUnusedPositionTry
+};

package/src/preprocess.js

@@ -0,0 +1,27 @@
+/**
+ * @file Preprocesses CSS declaration blocks by converting Unicode escape sequences to their literal characters before parsing.
+ */
+
+import { resolveUnicodeEscape } from './utilities.js';
+
+/**
+ * Converts CSS Unicode escape sequences inside declaration blocks to their literal character equivalents, while preserving control characters that must remain escaped.
+ *
+ * @param  {string} css  The raw CSS string to preprocess.
+ * @return {string}      The CSS string with printable Unicode escapes resolved inside declaration blocks.
+ */
+function preprocessDeclarationBlocks (css) {
+  // Match top-level declaration blocks (non-nested { ... })
+  return css.replace(/\{([^{}]*)\}/g, (match, content) => {
+    // Skip quoted strings, then match CSS unicode escapes (backslash + 1-6 hex digits + optional whitespace)
+    const processed = content.replace(/"(?:[^"\\]|\\.)*"|'(?:[^'\\]|\\.)*'|\\([0-9a-fA-F]{1,6})\s?/g, (fullMatch, hex) => {
+      if (!hex) {
+        return fullMatch;
+      }
+      return resolveUnicodeEscape(hex) ?? fullMatch;
+    });
+    return '{' + processed + '}';
+  });
+}
+
+export { preprocessDeclarationBlocks };

package/src/rules/normalize.js

@@ -0,0 +1,108 @@
+/**
+ * @file Normalizes CSS selectors, `@media` queries, and `@supports` conditions by unescaping identifiers and collapsing whitespace.
+ */
+
+import { resolveUnicodeEscape } from '../utilities.js';
+
+/**
+ * Converts CSS Unicode escape sequences in an identifier to their literal characters, preserving control characters that must remain escaped.
+ *
+ * @param  {string} identifier  The CSS identifier string to unescape.
+ * @return {string}             The identifier with printable Unicode escapes resolved.
+ */
+function unescapeIdent (identifier) {
+  // Match CSS unicode escapes: backslash + 1-6 hex digits + optional trailing whitespace
+  return identifier.replace(/\\([0-9a-fA-F]{1,6})\s?/g, (match, hex) => {
+    return resolveUnicodeEscape(hex) ?? match;
+  });
+}
+
+/**
+ * Converts CSS Unicode escape sequences in a selector to literal characters, preserving escapes that are syntactically required such as leading digits after class or ID selectors.
+ *
+ * @param  {string} selector  The CSS selector string to unescape.
+ * @return {string}           The selector with safe Unicode escapes resolved.
+ */
+function unescapeSelector (selector) {
+  // Match CSS unicode escapes: backslash + 1-6 hex digits + optional trailing whitespace
+  return selector.replace(/\\([0-9a-fA-F]{1,6})\s?/g, (match, hex, offset) => {
+    const character = resolveUnicodeEscape(hex);
+    if (character === null) {
+      return match;
+    }
+    let precedingCharacter;
+    if (offset > 0) {
+      precedingCharacter = selector[offset - 1];
+    } else {
+      precedingCharacter = '';
+    }
+    // Check if the unescaped character is a digit that would form an invalid start of a class/id name
+    const isLeadingDigitAfterSelector = (
+      /[0-9]/.test(character) &&
+      (offset === 0 || precedingCharacter === '.' || precedingCharacter === '#')
+    );
+    if (isLeadingDigitAfterSelector) {
+      return match;
+    }
+    return character;
+  });
+}
+
+/**
+ * Normalizes a `@media` query string by collapsing whitespace, stripping the default "all and" prefix, and converting min/max-width to range syntax.
+ *
+ * @param  {string} media  The raw `@media` query string.
+ * @return {string}        The normalized and minified media query.
+ */
+function normalizeMedia (media) {
+  // Collapse whitespace, strip spaces around punctuation, and remove the redundant "all and" prefix
+  media = media.replace(/\s+/g, ' ').replace(/\s*([:,])\s*/g, '$1').replace(/\s*([=<>])\s*/g, '$1').replace(/\(\s+/g, '(').replace(/\s+\)/g, ')').replace(/\b(?:all and )/gi, '');
+  // Convert min-width/max-width to range syntax (e.g. min-width:768px → width>=768px)
+  media = media.replace(/min-width:(\d+[a-z%]*)/gi, 'width>=$1').replace(/max-width:(\d+[a-z%]*)/gi, 'width<=$1');
+  media = media.replace(/min-height:(\d+[a-z%]*)/gi, 'height>=$1').replace(/max-height:(\d+[a-z%]*)/gi, 'height<=$1');
+  // Combine adjacent min+max range queries into a single range expression: (width>=X) and (width<=Y) → (X<=width<=Y)
+  media = media.replace(
+    /\((\w+)>=(\d+[a-z%]*)\)\s+and\s+\((\w+)<=(\d+[a-z%]*)\)/gi,
+    (fullMatch, minProperty, minValue, maxProperty, maxValue) => {
+      if (minProperty === maxProperty) {
+        return '(' + minValue + '<=' + minProperty + '<=' + maxValue + ')';
+      }
+      return fullMatch;
+    }
+  );
+  return media;
+}
+
+/**
+ * Normalizes a `@supports` condition string by collapsing whitespace, trimming, and standardizing spacing around logical operators.
+ *
+ * @param  {string} supports  The raw `@supports` condition string.
+ * @return {string}           The normalized `@supports` condition.
+ */
+function normalizeSupports (supports) {
+  // Collapse whitespace and strip spaces around punctuation
+  supports = supports.replace(/\s+/g, ' ').replace(/\s*([:,])\s*/g, '$1').replace(/\s*([=<>])\s*/g, '$1').replace(/\(\s+/g, '(').replace(/\s+\)/g, ')').trim();
+  supports = supports.replace(/\s+and\s+/g, ' and ').replace(/\s+or\s+/g, ' or ').replace(/\s+not\s+/g, ' not ');
+  // Compact logical operator spacing: ") and (" → ")and ("
+  supports = supports.replace(/\)\s*and\s*\(/g, ')and (');
+  supports = supports.replace(/\)\s*or\s*\(/g, ')or (');
+  return supports;
+}
+
+/**
+ * Checks if a `@supports` condition tests for universally supported features like display:grid or display:flex, allowing the `@supports` wrapper to be safely removed.
+ *
+ * @param  {string}  supports  The normalized `@supports` condition string.
+ * @return {boolean}           True if the `@supports` block can be unwrapped.
+ */
+function canUnwrapSupports (supports) {
+  return supports === '(display:grid)' || supports === '(display:flex)';
+}
+
+export {
+  canUnwrapSupports,
+  normalizeMedia,
+  normalizeSupports,
+  unescapeIdent,
+  unescapeSelector
+};