@thejaredwilcurt/csslop 0.0.49 → 0.0.50

package/src/rules/optimize/specificity.js

@@ -0,0 +1,280 @@
+/**
+ * @file Measures the specificity of selectors and selector lists, so rules can be regrouped and reordered without changing which declaration wins the cascade.
+ */
+
+import {
+  findMatchingBracket,
+  findMatchingParenthesis,
+  splitTopLevelCommaList
+} from '../../parser/source-search.js';
+
+/**
+ * Advances past a CSS identifier (name) starting at the given index.
+ *
+ * @param  {string} text   The selector text.
+ * @param  {number} start  The index to start scanning from.
+ * @return {number}        The index just after the identifier.
+ */
+function skipSelectorName (text, start) {
+  let index = start;
+  // Advance over identifier characters (letters, digits, hyphen, underscore)
+  while (index < text.length && isSelectorNameCharacter(text.charCodeAt(index))) {
+    index++;
+  }
+  return index;
+}
+
+/**
+ * Reports whether a character code is an ASCII letter.
+ *
+ * @param  {number}  characterCode  The UTF-16 code unit of the character.
+ * @return {boolean}                True for `a`-`z` and `A`-`Z`.
+ */
+function isAsciiLetter (characterCode) {
+  return (
+    (characterCode >= 97 && characterCode <= 122) ||
+    (characterCode >= 65 && characterCode <= 90)
+  );
+}
+
+/**
+ * Reports whether a character code can appear in a selector name, which here
+ * means an ASCII letter, digit, hyphen, or underscore. Comparing character
+ * codes avoids running a regular expression once per character.
+ *
+ * @param  {number}  characterCode  The UTF-16 code unit of the character.
+ * @return {boolean}                True when the character continues a name.
+ */
+function isSelectorNameCharacter (characterCode) {
+  const isDigit = characterCode >= 48 && characterCode <= 57;
+  const isHyphen = characterCode === 45;
+  const isUnderscore = characterCode === 95;
+  return isAsciiLetter(characterCode) || isDigit || isHyphen || isUnderscore;
+}
+
+/**
+ * Compares two specificity tuples [ids, classes, types] lexicographically.
+ *
+ * @param  {Array}  first   The first specificity tuple.
+ * @param  {Array}  second  The second specificity tuple.
+ * @return {number}         Negative, zero, or positive per standard comparison.
+ */
+function compareSpecificity (first, second) {
+  for (let index = 0; index < 3; index++) {
+    if (first[index] !== second[index]) {
+      return first[index] - second[index];
+    }
+  }
+  return 0;
+}
+
+/**
+ * Computes the CSS specificity of a single complex selector as an
+ * [ids, classes, types] tuple. The nesting selector `&` is ignored because its
+ * contribution comes from the shared parent when comparing sibling selectors.
+ * Functional pseudo-classes `:is()`, `:not()`, `:has()`, and `:matches()` add
+ * the maximum specificity of their arguments; `:where()` adds nothing.
+ *
+ * @param  {string} selector  A single complex selector string.
+ * @return {Array}            The [ids, classes, types] specificity tuple.
+ */
+function computeSpecificity (selector) {
+  const specificity = [0, 0, 0];
+  const text = selector.trim();
+  let index = 0;
+  while (index < text.length) {
+    const character = text[index];
+    if (character === '#') {
+      specificity[0]++;
+      index = skipSelectorName(text, index + 1);
+    } else if (character === '.') {
+      specificity[1]++;
+      index = skipSelectorName(text, index + 1);
+    } else if (character === '[') {
+      specificity[1]++;
+      // An attribute selector that never closes runs to the end of the selector
+      const closeBracketIndex = findMatchingBracket(text, index);
+      index = closeBracketIndex === -1 ? text.length : closeBracketIndex + 1;
+    } else if (character === ':') {
+      if (text[index + 1] === ':') {
+        specificity[2]++;
+        index = skipSelectorName(text, index + 2);
+      } else {
+        const nameStart = index + 1;
+        const nameEnd = skipSelectorName(text, nameStart);
+        const name = text.slice(nameStart, nameEnd).toLowerCase();
+        if (text[nameEnd] === '(') {
+          // An argument list that never closes runs to the end of the selector
+          const closeIndex = findMatchingParenthesis(text, nameEnd);
+          const argumentsEnd = closeIndex === -1 ? text.length : closeIndex;
+          const inner = text.slice(nameEnd + 1, argumentsEnd);
+          if (name === 'where') {
+            // :where() contributes zero specificity
+          } else if (name === 'is' || name === 'not' || name === 'has' || name === 'matches') {
+            const innerMax = maxSelectorSpecificity(inner);
+            specificity[0] += innerMax[0];
+            specificity[1] += innerMax[1];
+            specificity[2] += innerMax[2];
+          } else {
+            specificity[1]++;
+          }
+          index = argumentsEnd + 1;
+        } else {
+          // Legacy single-colon pseudo-elements count as pseudo-elements
+          if (name === 'before' || name === 'after' || name === 'first-line' || name === 'first-letter') {
+            specificity[2]++;
+          } else {
+            specificity[1]++;
+          }
+          index = nameEnd;
+        }
+      }
+    } else if (character === '*' || character === '&') {
+      // Universal selector and nesting selector add no counted specificity here
+      index++;
+    } else if (isAsciiLetter(text.charCodeAt(index))) {
+      specificity[2]++;
+      index = skipSelectorName(text, index);
+    } else {
+      // Combinators and whitespace do not affect specificity
+      index++;
+    }
+  }
+  return specificity;
+}
+
+/**
+ * Memoizes the strongest and weakest specificity of each selector list seen
+ * during the current stylesheet. The same rules are measured again on every
+ * merge pass, and a selector list always has the same specificity, so each
+ * distinct list is only split and scanned once per stylesheet.
+ *
+ * @type {Map<string, {strongest: Array, weakest: Array}>}
+ */
+const specificityRangeCache = new Map();
+
+/**
+ * Discards every memoized specificity range. The minifier calls this around
+ * each stylesheet, so the cache does not outlive the pass that filled it.
+ */
+function clearSpecificityCache () {
+  specificityRangeCache.clear();
+}
+
+/**
+ * Scans every selector of a comma-separated list for the strongest and the
+ * weakest specificity among them. The returned tuples are frozen because they
+ * are shared by everything that asks about the same list.
+ *
+ * @param  {string} selectorList  The selector list string.
+ * @return {object}               The `strongest` and `weakest` [ids, classes, types] tuples.
+ */
+function computeSpecificityRange (selectorList) {
+  let strongest = [0, 0, 0];
+  let weakest = null;
+  for (const selector of splitTopLevelCommaList(selectorList)) {
+    const specificity = computeSpecificity(selector);
+    if (compareSpecificity(specificity, strongest) > 0) {
+      strongest = specificity;
+    }
+    if (!weakest || compareSpecificity(specificity, weakest) < 0) {
+      weakest = specificity;
+    }
+  }
+  return {
+    strongest: Object.freeze(strongest),
+    weakest: Object.freeze(weakest || [0, 0, 0])
+  };
+}
+
+/**
+ * Returns the strongest and weakest specificity of a selector list, measuring
+ * it the first time it is asked about.
+ *
+ * @param  {string} selectorList  The selector list string.
+ * @return {object}               The `strongest` and `weakest` [ids, classes, types] tuples.
+ */
+function getSpecificityRange (selectorList) {
+  let range = specificityRangeCache.get(selectorList);
+  if (!range) {
+    range = computeSpecificityRange(selectorList);
+    specificityRangeCache.set(selectorList, range);
+  }
+  return range;
+}
+
+/**
+ * Returns the maximum specificity tuple across a comma-separated selector list,
+ * matching how a comma-separated group behaves as `:is()`.
+ *
+ * @param  {string} selectorList  The selector list string.
+ * @return {Array}                The maximum [ids, classes, types] tuple.
+ */
+function maxSelectorSpecificity (selectorList) {
+  return getSpecificityRange(selectorList).strongest;
+}
+
+/**
+ * Returns the strongest specificity a rule can match with, which is the highest
+ * of its individual selectors.
+ *
+ * @param  {Array} selectors  The rule's selector strings.
+ * @return {Array}            The [ids, classes, types] specificity tuple.
+ */
+function maximumRuleSpecificity (selectors) {
+  return maxSelectorSpecificity((selectors || []).join(','));
+}
+
+/**
+ * Returns the weakest specificity a rule's declarations are applied with. Every
+ * selector of a top-level rule applies the same declarations under its own
+ * specificity, so the weakest selector decides whether another rule is able to
+ * override the rule as a whole.
+ *
+ * @param  {Array} selectors  The rule's selector strings.
+ * @return {Array}            The [ids, classes, types] specificity tuple.
+ */
+function minimumRuleSpecificity (selectors) {
+  return getSpecificityRange((selectors || []).join(',')).weakest;
+}
+
+/**
+ * Adds two specificity tuples together, which is how a nested selector combines
+ * with the parent selector it only ever matches through.
+ *
+ * @param  {Array} first   The first [ids, classes, types] tuple.
+ * @param  {Array} second  The second [ids, classes, types] tuple.
+ * @return {Array}         The summed specificity tuple.
+ */
+function addSpecificity (first, second) {
+  return [
+    first[0] + second[0],
+    first[1] + second[1],
+    first[2] + second[2]
+  ];
+}
+
+/**
+ * Reports whether a rule that nests blocks may take on further selectors. A
+ * nested selector resolves against its parent's whole selector list as `:is()`,
+ * which matches with the specificity of the strongest selector in that list, so
+ * the list may only grow while every selector in it weighs the same.
+ *
+ * @param  {Array}   selectors  The selector list the merged rule would carry.
+ * @return {boolean}            Whether the nested blocks keep their current weight.
+ */
+function selectorsShareSpecificity (selectors) {
+  const strongest = maximumRuleSpecificity(selectors);
+  const weakest = minimumRuleSpecificity(selectors);
+  return compareSpecificity(strongest, weakest) === 0;
+}
+
+export {
+  addSpecificity,
+  clearSpecificityCache,
+  compareSpecificity,
+  maximumRuleSpecificity,
+  maxSelectorSpecificity,
+  minimumRuleSpecificity,
+  selectorsShareSpecificity
+};

package/src/{position-try.js → rules/position-try.js}

@@ -2,7 +2,7 @@
  * @file Handles `@position-try` rule analysis, usage tracking, and dead-rule elimination during CSS minification.
  */
 
-import { registersCustomProperty } from './rules/property.js';
+import { registersCustomProperty } from './property.js';
 
 /**
  * Scans top-level rules to register `@property` custom properties in the context and collect `@position-try` rule declarations and initial usage counts.

package/src/utilities.js

@@ -19,6 +19,20 @@ function resolveUnicodeEscape (hex) {
   return String.fromCodePoint(codePoint);
 }
 
+/**
+ * Reports whether a property is a custom property. A custom property holds an
+ * arbitrary token stream rather than a typed value, so every one of its tokens,
+ * whitespace included, is part of what it stores, and neither shorthands nor
+ * `all` ever reset it.
+ *
+ * @param  {string}  property  The CSS property name.
+ * @return {boolean}           Whether the property is a custom property.
+ */
+function isCustomProperty (property) {
+  return Boolean(property) && property.startsWith('--');
+}
+
 export {
+  isCustomProperty,
   resolveUnicodeEscape
 };

package/src/value/border.js

@@ -0,0 +1,85 @@
+/**
+ * @file Rewrites `border` and `outline` values into their shortest canonical form, stating the width before the style and dropping the default width.
+ */
+
+/**
+ * Matches the keywords that state a border line style.
+ *
+ * @type {string}
+ */
+const BORDER_STYLE_KEYWORD_SOURCE = 'solid|dashed|dotted|double|groove|ridge|inset|outset|hidden|none';
+
+/**
+ * Matches the ways a border line width is stated: one of its three keywords, a
+ * length, or a math function that resolves to one.
+ *
+ * @type {string}
+ */
+const BORDER_WIDTH_SOURCE = 'thin|medium|thick|[+-]?(?:\\d+|\\d*\\.\\d+)(?:e[+-]?\\d+)?[a-z]*|(?:calc|min|max|clamp)\\([^()]*\\)';
+
+/**
+ * Matches a `border` value that states its line style in front of its line
+ * width, with the two captured so they can be swapped.
+ *
+ * @type {RegExp}
+ */
+const BORDER_STYLE_BEFORE_WIDTH_PATTERN = new RegExp(
+  '^(' + BORDER_STYLE_KEYWORD_SOURCE + ')\\s+(' + BORDER_WIDTH_SOURCE + ')(?=\\s|$)',
+  'i'
+);
+
+/**
+ * Rewrites a `border` value that leads with its line style into the canonical
+ * width-style-color order. The width has to be recognized before the two are
+ * swapped: `border` states its components in any order, so the component behind
+ * the style may be a color instead, as in `solid #8aadf4 1px`, and that one
+ * belongs behind the width rather than in front of it.
+ *
+ * @param  {string} value  The `border` value.
+ * @return {string}        The value with its width stated before its style.
+ */
+function reorderBorderWidthBeforeStyle (value) {
+  return value.replace(BORDER_STYLE_BEFORE_WIDTH_PATTERN, '$2 $1');
+}
+
+/**
+ * Removes the default `medium` line width from a `border` value, since the
+ * shorthand resets an unstated width to it anyway.
+ *
+ * @param  {string} value  The `border` value.
+ * @return {string}        The value without its default line width.
+ */
+function removeDefaultBorderWidth (value) {
+  // Match the medium keyword and the whitespace that separates it from the next component
+  return value.replace(/\bmedium\s+/g, '');
+}
+
+/**
+ * Matches a line style keyword written directly against one of the color
+ * keywords that can follow it, capturing both so a space can be put back
+ * between them.
+ *
+ * @type {RegExp}
+ */
+const STYLE_TOUCHING_COLOR_PATTERN = new RegExp(
+  '\\b(' + BORDER_STYLE_KEYWORD_SOURCE + ')(red|green|olive|tan|transparent)\\b',
+  'g'
+);
+
+/**
+ * Restores the space between an `outline` value's line style and a color
+ * keyword when the two have been written against each other, since together
+ * they would read as one unknown keyword.
+ *
+ * @param  {string} value  The `outline` value.
+ * @return {string}        The value with its style and color keywords separated.
+ */
+function separateOutlineStyleFromColor (value) {
+  return value.replace(STYLE_TOUCHING_COLOR_PATTERN, '$1 $2');
+}
+
+export {
+  removeDefaultBorderWidth,
+  reorderBorderWidthBeforeStyle,
+  separateOutlineStyleFromColor
+};

package/src/value/{colors.js → color/conversion.js}

@@ -2,8 +2,9 @@
  * @file Provides color parsing, color space conversion (sRGB, OKLab, OKLCH, HSL, HWB), and hex formatting for CSS value minification.
  */
 
-import { namedColors } from './named-colors.js';
-import { parseAlphaString } from './shared.js';
+import { parseAlphaString } from '../shared.js';
+
+import { namedColors } from './named.js';
 
 /**
  * Reverse lookup from "r,g,b" to the shortest CSS named color keyword.