postcss-calc 10.1.0 → 11.0.0-rc.0

package/README.md

@@ -120,6 +120,61 @@ div[data-size="calc(3*3)"] {
 }
 ```
 
+#### `onParseError`
+
+Callback invoked when a `calc()` body fails to parse or simplify. Matches
+[`@csstools/css-calc`][csstools-css-calc]'s shape:
+
+```js
+calc({
+  onParseError: (err, input) => {
+    throw err; // or log, route to a different channel, etc.
+  }
+})
+```
+
+When omitted, errors are reported via PostCSS `result.warn()` so the
+plugin never throws at the postcss level.
+
+### Behavior differences from the legacy parser
+
+The legacy [jison][jison]-generated parser was replaced by a hand-written
+Pratt parser whose simplifier follows [CSS Values 4][css-values-4]. Most
+inputs reduce to identical output; the differences are spec-aligned or
+canonical-form decisions:
+
+- **Strict whitespace (§10.1).** `calc(2px+3px)` is invalid CSS (binary
+  `+` / `-` require surrounding whitespace) and is preserved with a
+  warning instead of reduced.
+- **Canonical operand order.** Commutative operands serialize
+  numeric-first, matching [`@csstools/css-calc`][csstools-css-calc]:
+  `calc(var(--foo) + 10px)` → `calc(10px + var(--foo))`.
+- **Zero buckets are kept.** `calc(100px - (100px - 100%))` →
+  `calc(0px + 100%)`, not `100%` — [WPT calc-serialization-002][wpt-calc-serialization]
+  requires the zero term because it carries the length-percentage type.
+- **Constant folding.** `calc(43 + pi)` now folds to `46.14159` (§10.7.1).
+  Previously `pi` / `e` stayed symbolic.
+- **Reciprocal conversion.** `calc(var(--x) / 2)` becomes
+  `calc(var(--x) * 0.5)`. The two are mathematically equivalent;
+  previously the division shape was kept.
+- **Distributive multiplication.** `calc(0.5 * (100vw - 10px))` becomes
+  `calc(50vw - 5px)`.
+- **Unit case normalization.** `2PX` becomes `2px` (CSS units are case-
+  insensitive; lowercase is conventional).
+- **Calc unwrap (§10.6).** `calc(var(--foo))` becomes `var(--foo)` — a
+  `calc()` containing a single value is replaced by that value.
+- **Spec-style spaced operators.** `2px*var(--x)` is serialized as
+  `2px * var(--x)`. The tokenizer is unaffected; only output spacing
+  differs.
+- **Division by zero / by a unit.** `calc(500px/0)` reduces to
+  `calc(infinity * 1px)` (§10.13) instead of throwing. Use `onParseError`
+  if you want validation behavior.
+
+[css-values-4]: https://www.w3.org/TR/css-values-4/
+[csstools-css-calc]: https://www.npmjs.com/package/@csstools/css-calc
+[wpt-calc-serialization]: https://github.com/web-platform-tests/wpt/blob/master/css/css-values/calc-serialization-002.html
+[jison]: https://github.com/zaach/jison
+
 ---
 
 ## Related PostCSS plugins
@@ -149,5 +204,5 @@ npm test
 [PostCSS]: https://github.com/postcss
 [PostCSS Calc]: https://github.com/postcss/postcss-calc
 [PostCSS Custom Properties]: https://github.com/postcss/postcss-custom-properties
-[tests]: src/__tests__/index.js
+[tests]: test/index.js
 [W3C calc() implementation]: https://www.w3.org/TR/css3-values/#calc-notation

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "postcss-calc",
-  "version": "10.1.0",
+  "version": "11.0.0-rc.0",
   "description": "PostCSS plugin to reduce calc()",
   "keywords": [
     "css",
@@ -24,27 +24,33 @@
   "author": "Andy Jansson",
   "license": "MIT",
   "engines": {
-    "node": "^18.12 || ^20.9 || >=22.0"
+    "node": "^22.12 || ^24.11 || >=26.0"
   },
   "devDependencies": {
-    "@types/node": "^22.10.2",
-    "eslint": "^9.17.0",
-    "eslint-config-prettier": "^9.1.0",
-    "jison-gho": "0.6.1-216",
-    "postcss": "^8.4.49",
-    "prettier": "^3.4.2",
-    "typescript": "~5.7.2"
+    "@csstools/css-calc": "^3.2.1",
+    "@eslint/js": "^10.0.1",
+    "@rmenke/css-tokenizer-tests": "^1.2.0",
+    "@stryker-mutator/core": "^9.6.1",
+    "@stryker-mutator/typescript-checker": "^9.6.1",
+    "@types/node": "^26.1.1",
+    "eslint": "^10.7.0",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-plugin-sonarjs": "^4.2.0",
+    "fast-check": "^4.9.0",
+    "postcss": "^8.5.19",
+    "prettier": "^3.9.5",
+    "typescript": "~6.0.3"
   },
   "dependencies": {
-    "postcss-selector-parser": "^7.0.0",
+    "@csstools/css-tokenizer": "^4.0.0",
     "postcss-value-parser": "^4.2.0"
   },
   "peerDependencies": {
-    "postcss": "^8.4.38"
+    "postcss": "^8.5.19"
   },
   "scripts": {
-    "build": "jison ./parser.jison -o src/parser.js",
     "lint": "eslint . && tsc",
-    "test": "node --test"
+    "test": "node --test",
+    "test:mutation": "stryker run"
   }
 }

package/src/index.js

@@ -1,45 +1,140 @@
 'use strict';
-const transform = require('./lib/transform.js');
+
+// PostCSS adapter. Walks declaration values (and optionally @rule params
+// and selectors), feeds calc() bodies through tokenize → parse → simplify
+// → serialize, and writes the result back.
+
+const valueParser = require('postcss-value-parser');
+
+const { tokenize } = require('./lib/tokenizer.js');
+const { parse } = require('./lib/parser.js');
+const { simplify } = require('./lib/simplify.js');
+const { serialize } = require('./lib/serialize.js');
+
+const MATCH_CALC = /^(?:-(?:moz|webkit)-)?calc$/i;
+
+// Bare math-function calls (no calc() wrapper) — fed to the same pipeline.
+// Mirrors the dispatch in lib/simplify/call.js.
+const MATH_FUNCTIONS = new Set([
+  'min', 'max', 'clamp',
+  'abs', 'sign',
+  'mod', 'rem', 'round',
+  'sin', 'cos', 'tan', 'asin', 'acos', 'atan', 'atan2',
+  'pow', 'sqrt', 'hypot', 'log', 'exp',
+]);
 
 /**
- * @typedef {{precision?: number | false,
- *          preserve?: boolean,
- *          warnWhenCannotResolve?: boolean,
- *          mediaQueries?: boolean,
- *          selectors?: boolean}} PostCssCalcOptions
+ * @typedef {object} PluginOptions
+ * @property {number | false} [precision]
+ * @property {boolean} [preserve]
+ * @property {boolean} [warnWhenCannotResolve]
+ * @property {boolean} [mediaQueries]
+ * @property {boolean} [selectors]
+ * @property {(error: Error, input: string) => void} [onParseError] Invoked when parse/simplify throws. Replaces the default `result.warn`.
  */
+
+/** @typedef {Required<Omit<PluginOptions, 'onParseError'>> & Pick<PluginOptions, 'onParseError'>} ResolvedOptions */
+
+/**
+ * @param {string} value
+ * @param {ResolvedOptions} options
+ * @param {import('postcss').Result} result
+ * @param {import('postcss').ChildNode} item
+ * @return {string}
+ */
+function transformValue(value, options, result, item) {
+  return valueParser(value)
+    .walk((node) => {
+      if (node.type !== 'function') {return;}
+      const isCalc = MATCH_CALC.test(node.value);
+      const isMath = !isCalc && MATH_FUNCTIONS.has(node.value.toLowerCase());
+      if (!isCalc && !isMath) {return;}
+
+      // calc(): feed the body. Bare math: feed the whole call.
+      const inner = valueParser.stringify(node.nodes);
+      const contents = isCalc ? inner : `${node.value}(${inner})`;
+      try {
+        const simplified = simplify(parse(tokenize(contents)));
+        const str = serialize(simplified, {
+          precision: options.precision,
+          calcName: isCalc ? node.value : 'calc', // preserve vendor prefix on calc()
+        });
+
+        if (options.warnWhenCannotResolve && str.startsWith(`${node.value}(`)) {
+          result.warn('Could not reduce expression: ' + value, {
+            plugin: 'postcss-calc',
+            node: item,
+          });
+        }
+
+        // Re-tag as `word` so value-parser emits `str` verbatim instead of
+        // re-wrapping it as `name(...)`. Cast widens the `'function'` literal.
+        /** @type {{type: string}} */ (node).type = 'word';
+        node.value = str;
+      } catch (error) {
+        const err = error instanceof Error ? error : new Error('Error');
+        if (options.onParseError) {
+          options.onParseError(err, contents);
+        } else {
+          result.warn(err.message, { node: item });
+        }
+      }
+      return false;
+    })
+    .toString();
+}
+
 /**
- * @type {import('postcss').PluginCreator<PostCssCalcOptions>}
- * @param {PostCssCalcOptions} opts
+ * @type {import('postcss').PluginCreator<PluginOptions>}
+ * @param {PluginOptions} [opts]
  * @return {import('postcss').Plugin}
  */
 function pluginCreator(opts) {
-  const options = Object.assign(
-    {
-      precision: 5,
-      preserve: false,
-      warnWhenCannotResolve: false,
-      mediaQueries: false,
-      selectors: false,
-    },
-    opts
-  );
+  /** @type {ResolvedOptions} */
+  const options = {
+    precision: 5,
+    preserve: false,
+    warnWhenCannotResolve: false,
+    mediaQueries: false,
+    selectors: false,
+    ...opts,
+  };
 
   return {
     postcssPlugin: 'postcss-calc',
     OnceExit(css, { result }) {
       css.walk((node) => {
-        const { type } = node;
-        if (type === 'decl') {
-          transform(node, 'value', options, result);
+        if (node.type === 'decl') {
+          const next = transformValue(node.value, options, result, node);
+          if (options.preserve && node.value !== next && node.parent) {
+            const clone = node.clone();
+            clone.value = next;
+            node.parent.insertBefore(node, clone);
+          } else {
+            node.value = next;
+          }
         }
-
-        if (type === 'atrule' && options.mediaQueries) {
-          transform(node, 'params', options, result);
+        if (node.type === 'atrule' && options.mediaQueries) {
+          const next = transformValue(node.params, options, result, node);
+          if (options.preserve && node.params !== next && node.parent) {
+            const clone = node.clone();
+            clone.params = next;
+            node.parent.insertBefore(node, clone);
+          } else {
+            node.params = next;
+          }
         }
-
-        if (type === 'rule' && options.selectors) {
-          transform(node, 'selector', options, result);
+        if (node.type === 'rule' && options.selectors) {
+          // Reduces `:nth-child(calc(...))` via the function walk. calc() in a
+          // quoted attribute value is a literal match, so it's left untouched.
+          const next = transformValue(node.selector, options, result, node);
+          if (options.preserve && node.selector !== next && node.parent) {
+            const clone = node.clone();
+            clone.selector = next;
+            node.parent.insertBefore(node, clone);
+          } else {
+            node.selector = next;
+          }
         }
       });
     },

package/src/lib/convertUnits.js

@@ -0,0 +1,105 @@
+'use strict';
+
+// Spec: https://www.w3.org/TR/css-values-4/#calc-type-checking
+
+/**
+ * @typedef {'length' | 'angle' | 'time' | 'frequency' | 'resolution' | 'flex' | 'percentage'} BaseType
+ */
+
+/** @type {Record<string, BaseType>} */
+const UNIT_TO_BASE = {
+  px: 'length', cm: 'length', mm: 'length', q: 'length',
+  in: 'length', pt: 'length', pc: 'length',
+  em: 'length', ex: 'length', ch: 'length', rem: 'length',
+  lh: 'length', rlh: 'length', ic: 'length', cap: 'length',
+  vw: 'length', vh: 'length', vmin: 'length', vmax: 'length',
+  vb: 'length', vi: 'length',
+  svw: 'length', svh: 'length', svmin: 'length', svmax: 'length',
+  svb: 'length', svi: 'length',
+  lvw: 'length', lvh: 'length', lvmin: 'length', lvmax: 'length',
+  lvb: 'length', lvi: 'length',
+  dvw: 'length', dvh: 'length', dvmin: 'length', dvmax: 'length',
+  dvb: 'length', dvi: 'length',
+  cqw: 'length', cqh: 'length', cqi: 'length', cqb: 'length',
+  cqmin: 'length', cqmax: 'length',
+
+  deg: 'angle', grad: 'angle', rad: 'angle', turn: 'angle',
+
+  s: 'time', ms: 'time',
+
+  hz: 'frequency', khz: 'frequency',
+
+  dpi: 'resolution', dpcm: 'resolution', dppx: 'resolution', x: 'resolution',
+
+  fr: 'flex',
+
+  '%': 'percentage',
+};
+
+/**
+ * @param {string} unit
+ * @return {BaseType | null}
+ */
+function baseOf(unit) {
+  return UNIT_TO_BASE[unit.toLowerCase()] ?? null;
+}
+
+// Conversion factors to each family's canonical unit. Units NOT listed
+// (em, rem, vw, cqw, fr, % …) share a base type with something convertible
+// but can't resolve statically — the simplifier preserves them as separate
+// summands rather than merging.
+/** @type {Record<string, number>} */
+const TO_CANONICAL = {
+  px: 1,
+  cm: 96 / 2.54,
+  mm: 96 / 25.4,
+  q: 96 / 101.6,
+  in: 96,
+  pt: 96 / 72,
+  pc: 16,
+  deg: 1,
+  grad: 0.9,
+  rad: 180 / Math.PI,
+  turn: 360,
+  s: 1,
+  ms: 0.001,
+  hz: 1,
+  khz: 1000,
+  dppx: 1,
+  dpi: 1 / 96,
+  dpcm: 2.54 / 96,
+  x: 1,
+  // flex / percentage: identity — only combinable with the same unit.
+  fr: 1,
+  '%': 1,
+};
+
+/**
+ * Convert a value within a single conversion family. Returns null when
+ * either unit is missing from the table (em/rem/vw need runtime context)
+ * or when the units belong to different base types.
+ * @param {number} value
+ * @param {string} from
+ * @param {string} to
+ * @return {number | null}
+ */
+function convert(value, from, to) {
+  const fromKey = from.toLowerCase();
+  const toKey = to.toLowerCase();
+  if (fromKey === toKey) {
+    return value;
+  }
+  const f = TO_CANONICAL[fromKey];
+  const t = TO_CANONICAL[toKey];
+  if (f === undefined || t === undefined) {
+    return null;
+  }
+  // Cross-family guard: `px` and `s` both have entry 1, so without this
+  // `convert(1, 'px', 's')` would silently return 1.
+  if (UNIT_TO_BASE[fromKey] !== UNIT_TO_BASE[toKey]) {
+    return null;
+  }
+  return (value * f) / t;
+}
+
+module.exports = { baseOf, convert };

package/src/lib/node.js

@@ -0,0 +1,189 @@
+'use strict';
+
+// Canonical AST. N-ary Sum and Product with signed numeric leaves.
+// Invariants enforced by the constructors below:
+//
+//   - Num/Dim values may be any finite number (negatives allowed); a `-5`
+//     is `Num(-5)`, never `Sum([{sign:-1, Num(5)}])`. One form per value.
+//   - In a SumTerm with Num/Dim node, sign is always +1; the sign slot is
+//     reserved for opaque nodes (Ident, Call, Product, multi-term Sum).
+//   - No Sum directly contains another Sum (flattened on construction).
+//   - No Product directly contains another Product (flattened).
+//   - A Sum/Product with one positive element collapses to that element.
+//   - A Sum/Product with no elements collapses to Num(0) / Num(1).
+//   - Zero-valued Nums are dropped from sums (they contribute nothing).
+//     Zero-valued Dims are kept — the unit carries type info.
+
+/**
+ * @typedef {{type: 'Num', value: number}} Num
+ * @typedef {{type: 'Dim', value: number, unit: string}} Dim
+ * @typedef {{type: 'Ident', name: string}} Ident
+ * @typedef {{type: 'Call', name: string, args: Node[]}} Call
+ * @typedef {{sign: 1 | -1, node: Node}} SumTerm Sign is always +1 when node is Num or Dim.
+ * @typedef {{type: 'Sum', terms: SumTerm[]}} Sum
+ * @typedef {{exponent: 1 | -1, node: Node}} ProductFactor exponent +1 = numerator, -1 = denominator.
+ * @typedef {{type: 'Product', factors: ProductFactor[]}} Product
+ * @typedef {Num | Dim | Ident | Call | Sum | Product} Node
+ */
+
+/**
+ * @param {number} value
+ * @return {Num}
+ */
+function num(value) {
+  return { type: 'Num', value };
+}
+
+/**
+ * @param {number} value
+ * @param {string} unit
+ * @return {Dim}
+ */
+function dim(value, unit) {
+  return { type: 'Dim', value, unit };
+}
+
+/**
+ * @param {string} name
+ * @return {Ident}
+ */
+function ident(name) {
+  return { type: 'Ident', name };
+}
+
+/**
+ * @param {string} name
+ * @param {Node[]} args
+ * @return {Call}
+ */
+function call(name, args) {
+  return { type: 'Call', name, args };
+}
+
+/**
+ * @param {SumTerm[]} rawTerms
+ * @return {Node}
+ */
+function mkSum(rawTerms) {
+  /** @type {SumTerm[]} */
+  const flat = [];
+  for (const t of rawTerms) {
+    pushSumTerm(flat, t);
+  }
+  if (flat.length === 0) {
+    return { type: 'Num', value: 0 };
+  }
+  if (flat.length === 1 && flat[0].sign === 1) {
+    return flat[0].node;
+  }
+  return { type: 'Sum', terms: flat };
+}
+
+/**
+ * @param {SumTerm[]} out
+ * @param {SumTerm} term
+ * @return {void}
+ */
+function pushSumTerm(out, term) {
+  let { sign, node } = term;
+
+  if (node.type === 'Sum') {
+    for (const inner of node.terms) {
+      pushSumTerm(out, {
+        sign: /** @type {1 | -1} */ (sign * inner.sign),
+        node: inner.node,
+      });
+    }
+    return;
+  }
+
+  // sign=-1 around a Num/Dim leaf collapses into the value's sign — the
+  // canonical-form rule downstream code relies on.
+  if (sign === -1) {
+    if (node.type === 'Num') {
+      node = { type: 'Num', value: -node.value };
+      sign = 1;
+    } else if (node.type === 'Dim') {
+      node = { type: 'Dim', value: -node.value, unit: node.unit };
+      sign = 1;
+    }
+  }
+
+  // Drop zero-valued Nums. Dims with value 0 stay — the unit carries type.
+  if (node.type === 'Num' && node.value === 0) {
+    return;
+  }
+
+  out.push({ sign, node });
+}
+
+/**
+ * @param {ProductFactor[]} rawFactors
+ * @return {Node}
+ */
+function mkProduct(rawFactors) {
+  /** @type {ProductFactor[]} */
+  const flat = [];
+  for (const f of rawFactors) {
+    pushProductFactor(flat, f);
+  }
+  if (flat.length === 0) {
+    return { type: 'Num', value: 1 };
+  }
+  if (flat.length === 1 && flat[0].exponent === 1) {
+    return flat[0].node;
+  }
+  return { type: 'Product', factors: flat };
+}
+
+/**
+ * @param {ProductFactor[]} out
+ * @param {ProductFactor} f
+ * @return {void}
+ */
+function pushProductFactor(out, f) {
+  const n = f.node;
+  if (n.type === 'Product') {
+    for (const inner of n.factors) {
+      out.push({
+        exponent: /** @type {1 | -1} */ (f.exponent * inner.exponent),
+        node: inner.node,
+      });
+    }
+    return;
+  }
+  // Factor of 1 contributes nothing regardless of exponent (1/1 = 1).
+  if (n.type === 'Num' && n.value === 1) {
+    return;
+  }
+  out.push(f);
+}
+
+/**
+ * Negate any node, preserving canonical form.
+ * @param {Node} node
+ * @return {Node}
+ */
+function negate(node) {
+  if (node.type === 'Num') {
+    return num(-node.value);
+  }
+  if (node.type === 'Dim') {
+    return dim(-node.value, node.unit);
+  }
+  if (node.type === 'Sum') {
+    return mkSum(
+      node.terms.map((t) => ({
+        sign: /** @type {1 | -1} */ (-t.sign),
+        node: t.node,
+      }))
+    );
+  }
+  // Opaque (Ident, Call, Product): wrap as a single negative-sign term —
+  // the only case where sign=-1 remains on a SumTerm.
+  return { type: 'Sum', terms: [{ sign: -1, node }] };
+}
+
+// Stryker disable next-line all: instrumenting this line breaks Node's
+// cjs-module-lexer named-export detection for .mjs `import { x } from` consumers.
+module.exports = { num, dim, ident, call, mkSum, mkProduct, negate };