postcss-calc 11.2.1 → 11.2.2

package/README.md

@@ -4,8 +4,9 @@
 [![Support Chat][git-img]][git-url]
 
 [PostCSS Calc] lets you reduce `calc()` references whenever it's possible.
-When multiple units are mixed together in the same expression, the `calc()`
-statement is left as is, to fallback to the [W3C calc() implementation].
+When an expression mixes units that cannot be combined exactly (such as `px`
+and `em`), or contains values only known at runtime (such as `var()`), the
+unresolved part is left for the browser's [W3C calc() implementation].
 
 ## Installation
 
@@ -62,7 +63,7 @@ leaving all other text untouched.
 import reduceCalc from 'postcss-calc/reduce';
 
 reduceCalc('calc(1in + 10px)');
-// => 'calc(1.10417in)'
+// => 'calc(106px)'
 
 reduceCalc('min(50px, calc(2 * 40px))');
 // => 'calc(50px)'
@@ -123,6 +124,28 @@ Allows you to define the precision for decimal numbers. Set it to `false` to
 disable rounding and preserve full IEEE-754 floating-point precision (emitting
 the shortest round-tripping decimal representation).
 
+Values below 1 keep `precision` significant digits (`.0123456px` becomes
+`.012346px`), and larger values keep `precision` decimals. Divisions and unit
+conversions are folded only when the result is exact at the precision;
+otherwise they stay symbolic and everything around them is still simplified:
+
+```css
+.a {
+  width: calc(100% / 4);
+} /* calc(25%) */
+.b {
+  width: calc(100% / 3);
+} /* calc(100% / 3), not 33.33333% */
+.c {
+  width: calc(1cm + 1px);
+} /* calc(1cm + 1px) */
+.d {
+  width: calc(1px + 1pt);
+} /* calc(1.75pt) */
+```
+
+With `precision: false` nothing is rounded, so every division is folded.
+
 ```js
 var out = postcss()
   .use(calc({ precision: 10 }))
@@ -235,15 +258,10 @@ canonical-form decisions:
   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.
@@ -265,13 +283,15 @@ To replace the value of CSS custom properties at build time, try [PostCSS Custom
 ## Contributing
 
 Work on a branch, install dev-dependencies, respect coding style & run tests
-before submitting a bug fix or a feature.
+before submitting a bug fix or a feature. See [CONTRIBUTING.md](CONTRIBUTING.md)
+for the full guidelines. The project uses [pnpm](https://pnpm.io/).
 
 ```bash
 git clone git@github.com:postcss/postcss-calc.git
 git checkout -b patch-1
-npm install
-npm test
+pnpm install
+pnpm test
+pnpm lint
 ```
 
 The normal test run uses a deterministic structural sample of the harvested
@@ -282,11 +302,19 @@ when changing parsing/simplification behavior:
 pnpm test:corpus:full
 ```
 
-Profile parser chains with `pnpm benchmark:arithmetic-chains` or
-`pnpm benchmark:nested-fallbacks`; both use 20 fresh paired blocks by default
-and write ignored schema-v2 reports. Compare a saved report with
-`node scripts/compare-parser-benchmarks.js <report>`. Run the correctness-aware
-corpus benchmark with `pnpm benchmark:corpus`.
+Performance changes to the parser, analyzer, simplifier, or serializer should be
+checked with the benchmarks. `pnpm benchmark:arithmetic-chains` and
+`pnpm benchmark:nested-fallbacks` compare the working tree against `HEAD` using
+20 fresh-process paired blocks by default and write git-ignored schema-v2
+reports under `reports/benchmarks/`. Re-check a saved report with
+`pnpm benchmark:reanalyze <report>`. `pnpm benchmark:corpus` compares the whole
+pipeline with `@csstools/css-calc` on real-world expressions and is
+report-only.
+
+These benchmarks time only the parser (or, for the corpus, the whole reducer)
+on one machine, and a `pass` means "no regression detected at the declared
+margin", not "no change". Read [BENCHMARKS.md](BENCHMARKS.md) before
+interpreting results.
 
 The PostCSS benchmark awaits `postcss().process(...)`, and that await already
 triggers result stringification. It therefore does not add a redundant

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "postcss-calc",
-  "version": "11.2.1",
+  "version": "11.2.2",
   "type": "module",
   "description": "PostCSS plugin to reduce calc()",
   "keywords": [
@@ -38,20 +38,20 @@
   "devEngines": {
     "packageManager": {
       "name": "pnpm",
-      "version": "12.4.2"
+      "version": "12.8.1"
     }
   },
   "devDependencies": {
-    "@csstools/css-calc": "^3.4.0",
-    "@types/node": "^26.6.1",
-    "fast-check": "^4.10.1",
-    "oxfmt": "^0.68.0",
-    "oxlint": "^1.83.0",
+    "@csstools/css-calc": "^3.4.1",
+    "@types/node": "^26.6.3",
+    "fast-check": "^4.10.2",
+    "oxfmt": "^0.71.0",
+    "oxlint": "^1.86.0",
     "postcss": "^8.5.28",
     "typescript": "~7.0.2"
   },
   "dependencies": {
-    "@csstools/css-tokenizer": "^4.0.1"
+    "@csstools/css-tokenizer": "^4.0.2"
   },
   "peerDependencies": {
     "postcss": "^8.5.28"
@@ -59,13 +59,13 @@
   "scripts": {
     "lint": "oxlint . && tsc && oxfmt --check",
     "fmt": "oxfmt",
-    "benchmark:arithmetic-chains": "node scripts/benchmark-arithmetic-chains.js",
-    "benchmark:nested-fallbacks": "node scripts/benchmark-nested-fallbacks.js",
-    "benchmark:corpus": "node scripts/benchmark.js",
-    "benchmark:serialization": "node scripts/benchmark-serialization.js",
+    "benchmark:arithmetic-chains": "node scripts/benchmark/benchmark-parser.js arithmetic-chains",
+    "benchmark:nested-fallbacks": "node scripts/benchmark/benchmark-parser.js nested-fallbacks",
+    "benchmark:corpus": "node scripts/benchmark/benchmark-corpus.js",
+    "benchmark:serialization": "node scripts/benchmark/benchmark-serialization.js",
     "test:benchmark": "node --test 'test/unit/benchmark-*.test.js' test/unit/compare-parser-benchmarks.test.js test/unit/corpus-benchmark.test.js",
     "test:benchmark:simulation": "node test/benchmark/statistical-simulation.js",
-    "benchmark:reanalyze": "node scripts/compare-parser-benchmarks.js",
+    "benchmark:reanalyze": "node scripts/benchmark/compare-parser-benchmarks.js",
     "test": "node --test --test-reporter=dot 'test/**/*.test.js' 'test/**/*.test.cjs'",
     "test:mutation:corpus": "node test/mutation/corpus-selection.js",
     "test:corpus:full": "POSTCSS_CALC_FULL_CORPUS=1 node --test test/conformance/corpus.test.js"

package/src/index.js

@@ -65,12 +65,13 @@ function applyTransform(
 function pluginCreator(opts) {
   /** @type {ResolvedOptions} */
   const options = {
-    precision: 5,
     warnWhenCannotResolve: false,
     mediaQueries: false,
     selectors: false,
     unwrapSingleValue: false,
     ...opts,
+    // An explicit `precision: undefined` keeps the default.
+    precision: opts?.precision ?? 5,
   };
 
   return {

package/src/lib/analyze.js

@@ -50,9 +50,6 @@ function analyzeType(node, depth = 0) {
     case 'Num':
       return resolved(numberType);
     case 'Dim':
-      // Percentages are contextual; their percent-ness is tracked so a
-      // `% / %` product cancels to a number. Unknown units are opaque, while
-      // known families can still reject px + seconds.
       return node.unit === '%'
         ? finish(percentageType, true, true)
         : resolved({ kind: 'dimension', base: baseOf(node.unit) });
@@ -83,9 +80,6 @@ function analyzeSum(node, depth) {
     if (isFailure(child.type)) {
       type = failureType;
     } else if (child.type.kind === 'unknown') {
-      // A pure percentage sum stays percentage-typed so a surrounding
-      // product can cancel `% / %`; any other opaque term must widen the
-      // sum back to unknown.
       if (isPercentage(child.type)) hasPercentage = true;
       else hasUnknown = true;
     } else if (type === null) {

package/src/lib/compile.js

@@ -34,7 +34,7 @@ function compileCandidate(candidate, ctx) {
   if (!analysis.valid) {
     throw new Error('Invalid CSS calculation type');
   }
-  const tree = simplify(parsed);
+  const tree = simplify(parsed, ctx.options.precision);
   const original =
     analysis.unresolved && !candidate.calculation
       ? ctx.value.slice(candidate.start, candidate.end)

package/src/lib/node.js

@@ -8,7 +8,11 @@
 //   - No ungrouped Sum directly contains another Sum (flattened on
 //     construction). A grouped Sum is retained so a later negative sign
 //     cannot be distributed across opaque terms.
-//   - No Product directly contains another Product (flattened).
+//   - No Product directly contains another ungrouped Product (flattened). A
+//     grouped Product is retained: it is a parenthesized group around a
+//     substitution function (`var()`, `env()`, ...), whose tokens must not
+//     merge with the surrounding factors. A grouped Product may hold a single
+//     factor.
 //   - A Sum/Product with one positive element collapses to that element.
 //   - A Sum/Product with no elements collapses to Num(0) / Num(1).
 //   - Positive zero-valued Nums are dropped from all-number sums. They are
@@ -28,7 +32,7 @@
  * @typedef {{sign: 1 | -1, node: Node}} SumTerm Sign is always +1 when node is Num or Dim.
  * @typedef {{type: 'Sum', terms: SumTerm[], grouped?: boolean}} Sum
  * @typedef {{exponent: 1 | -1, node: Node}} ProductFactor exponent +1 = numerator, -1 = denominator.
- * @typedef {{type: 'Product', factors: ProductFactor[]}} Product
+ * @typedef {{type: 'Product', factors: ProductFactor[], grouped?: boolean}} Product
  * @typedef {Num | Dim | Ident | Call | OpaqueCall | Sum | Product} Node
  */
 
@@ -185,7 +189,7 @@ function mkProduct(rawFactors) {
  */
 function pushProductFactor(out, f) {
   const n = f.node;
-  if (n.type === 'Product') {
+  if (n.type === 'Product' && !n.grouped) {
     for (const inner of n.factors) {
       out.push({
         exponent: /** @type {1 | -1} */ (f.exponent * inner.exponent),
@@ -201,6 +205,48 @@ function pushProductFactor(out, f) {
   out.push(f);
 }
 
+/**
+ * Mark a node as a source parenthesized group. A Sum or Product keeps its
+ * structure; any other node becomes a single-factor grouped Product.
+ * @param {Node} node
+ * @return {Node}
+ */
+function mkGroup(node) {
+  if (node.type === 'Sum' || node.type === 'Product') {
+    return { ...node, grouped: true };
+  }
+  return {
+    type: 'Product',
+    factors: [{ exponent: 1, node }],
+    grouped: true,
+  };
+}
+
+/**
+ * Whether a node is a substitution function call (`var()`, `env()`, ...), or
+ * an ungrouped Product that directly contains one. Nested groups are not
+ * inspected: they already bound their own tokens.
+ * @param {Node} node
+ * @return {boolean}
+ */
+function isSubstitutionNode(node) {
+  if (node.type === 'OpaqueCall') return true;
+  if (node.type === 'Product' && !node.grouped) {
+    return node.factors.some((factor) => isSubstitutionNode(factor.node));
+  }
+  return false;
+}
+
+/**
+ * Group a parenthesized expression when its tokens must stay bound: a sum, or
+ * a product around a substitution function.
+ * @param {Node} node
+ * @return {Node}
+ */
+function groupSubstitution(node) {
+  return node.type === 'Sum' || isSubstitutionNode(node) ? mkGroup(node) : node;
+}
+
 /**
  * Negate any node, preserving canonical form.
  * @param {Node} node
@@ -233,4 +279,15 @@ function negate(node) {
   return mkSum([{ sign: -1, node }]);
 }
 
-export { num, dim, ident, call, opaqueCall, mkSum, mkProduct, negate };
+export {
+  num,
+  dim,
+  ident,
+  call,
+  opaqueCall,
+  mkSum,
+  mkProduct,
+  mkGroup,
+  groupSubstitution,
+  negate,
+};

package/src/lib/parser/opaque.js

@@ -0,0 +1,151 @@
+// Opaque function parsing: `var()`, unknown functions and their component trees.
+import { TokenType as CssType } from '@csstools/css-tokenizer';
+import { ident, opaqueCall } from '../node.js';
+import {
+  isCalculationFunction,
+  isSupportedMathFunction,
+} from '../functions.js';
+import { assertDepth } from '../limits.js';
+import { eofPositionAt, sourceSpelling } from './tokens.js';
+
+/** @typedef {import('@csstools/css-tokenizer').CSSToken} CSSToken */
+/** @typedef {import('../node.js').Node} Node */
+/** @typedef {import('../node.js').OpaqueComponent} OpaqueComponent */
+/** @typedef {import('./tokens.js').ParseInput} ParseInput */
+/** @typedef {import('./tokens.js').Cursor} Cursor */
+/** @typedef {import('./tokens.js').FunctionToken} FunctionToken */
+/** @typedef {(input: ParseInput, start: number, end: number) => Node} ParseRange */
+
+/** @param {OpaqueComponent[]} target @param {OpaqueComponent} part */
+function pushComponent(target, part) {
+  if (typeof part === 'string' && typeof target.at(-1) === 'string')
+    target[target.length - 1] += part;
+  else target.push(part);
+}
+
+/** @param {ParseInput} input @param {Cursor} cursor @param {FunctionToken} token @param {string} name @return {number} */
+function closeOfCall(input, cursor, token, name) {
+  const close = input.index.closeOf(token.index, input.end);
+  if (close === -1)
+    throw new Error(
+      `Unclosed ${name}( at position ${eofPositionAt(input, cursor.index)}`
+    );
+  return close;
+}
+
+/** @param {ParseInput} input @param {Cursor} cursor @param {FunctionToken} token @param {string} name @param {string} rawName @param {ParseRange} parseRange @return {Node} */
+function parseOpaqueCall(input, cursor, token, name, rawName, parseRange) {
+  const close = closeOfCall(input, cursor, token, name);
+  cursor.skipTo(close + 1);
+  return opaqueCall(
+    name,
+    componentTree(input, token.index + 1, close, parseRange, []),
+    sourceSpelling(rawName, name)
+  );
+}
+
+/** @param {CSSToken[]} tokens @param {number} start @param {number} end */
+function rawTokens(tokens, start, end) {
+  let raw = '';
+  for (let i = start; i < end; i++) raw += tokens[i][1];
+  return raw;
+}
+/** @param {CSSToken[]} tokens @param {number} start @param {number} end */
+function customProperty(tokens, start, end) {
+  /** @type {CSSToken | null} */
+  let found = null;
+  let foundIndex = -1;
+  for (let i = start; i < end; i++) {
+    const type = tokens[i][0];
+    if (type === CssType.Whitespace || type === CssType.Comment) continue;
+    if (found !== null) return null;
+    found = tokens[i];
+    foundIndex = i;
+  }
+  if (!found || found[0] !== CssType.Ident) return null;
+  const decoded = found[4].value;
+  return decoded.startsWith('--') && decoded !== '--'
+    ? { decoded, raw: found[1], index: foundIndex }
+    : null;
+}
+/**
+ * Append the component tree of `[start, end)` to `root` and return it.
+ * Callers seed `root` so leading components need no copy or spread.
+ * @param {ParseInput} input @param {number} start @param {number} end @param {ParseRange} parseRange @param {OpaqueComponent[]} root @return {OpaqueComponent[]}
+ */
+function componentTree(input, start, end, parseRange, root) {
+  /** @type {OpaqueComponent[]} */ let tree = root;
+  /** @type {{parent: OpaqueComponent[], tree: OpaqueComponent[], close: number, end: number}[]} */
+  const frames = [];
+  const { tokens } = input;
+  let i = start;
+  while (true) {
+    if (i >= end) {
+      if (frames.length === 0) break;
+      const frame =
+        /** @type {{parent: OpaqueComponent[], tree: OpaqueComponent[], close: number, end: number}} */ (
+          frames.pop()
+        );
+      tree = frame.parent;
+      pushComponent(tree, frame.tree);
+      pushComponent(tree, tokens[frame.close][1]);
+      end = frame.end;
+      i = frame.close + 1;
+      continue;
+    }
+
+    const token = tokens[i];
+    const close = input.index.closeOf(i, end);
+    if (close === -1) {
+      pushComponent(tree, token[1]);
+      i++;
+      continue;
+    }
+
+    const isMathFunction =
+      token[0] === CssType.Function &&
+      (isCalculationFunction(token[4].value) ||
+        isSupportedMathFunction(token[4].value));
+    if (isMathFunction) {
+      try {
+        pushComponent(tree, parseRange(input, i, close + 1));
+      } catch {
+        pushComponent(tree, rawTokens(tokens, i, close + 1));
+      }
+      i = close + 1;
+      continue;
+    }
+
+    pushComponent(tree, token[1]);
+    assertDepth(frames.length + 1);
+    /** @type {OpaqueComponent[]} */
+    const child = [];
+    frames.push({ parent: tree, tree: child, close, end });
+    tree = child;
+    end = close;
+    i++;
+  }
+  return root;
+}
+/** @param {ParseInput} input @param {Cursor} cursor @param {FunctionToken} token @param {string} name @param {string} rawName @param {ParseRange} parseRange @return {Node} */
+function parseVar(input, cursor, token, name, rawName, parseRange) {
+  const { tokens } = input;
+  const start = token.index + 1;
+  const close = closeOfCall(input, cursor, token, name);
+  const comma = input.index.firstTopLevelComma(start, close);
+  const property = customProperty(tokens, start, comma === -1 ? close : comma);
+  if (!property)
+    throw new Error(
+      `Invalid custom property in ${name}() at position ${tokens[start]?.[2] ?? eofPositionAt(input, cursor.index)}`
+    );
+  cursor.skipTo(close + 1);
+  /** @type {OpaqueComponent[]} */
+  const components = [
+    ident(property.decoded, sourceSpelling(property.raw, property.decoded)),
+  ];
+  if (comma !== -1)
+    componentTree(input, property.index + 1, close, parseRange, components);
+  return opaqueCall(name, components, sourceSpelling(rawName, name));
+}
+
+export { parseOpaqueCall, parseVar };