postcss-calc 11.2.0 → 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.0",
+  "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.3.0",
-    "@types/node": "^26.5.1",
-    "fast-check": "^4.10.0",
-    "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.0"
+    "@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

@@ -1,16 +1,32 @@
 import { baseOf } from './convertUnits.js';
-import { addTypes, isFailure, mathFunctions } from './functions.js';
+import {
+  addTypes,
+  failureType,
+  isFailure,
+  isPercentage,
+  mathFunctions,
+  numberType,
+  percentageType,
+  unknownType,
+} from './functions.js';
 import { assertDepth } from './limits.js';
 
 /** @typedef {import('./node.js').Node} Node */
 /** @typedef {import('./functions.js').CalculationType} CalculationType */
+/** @typedef {Extract<CalculationType, {kind: 'dimension'}>} DimensionType */
 
 /** @typedef {'number' | 'unknown' | {dimension: string | null}} AnalysisType */
 /** @typedef {{type: AnalysisType, valid: boolean, unresolved: boolean}} Analysis */
-
-/** @type {CalculationType} */ const numberType = { kind: 'number' };
-/** @type {CalculationType} */ const unknownType = { kind: 'unknown' };
-/** @type {CalculationType} */ const failureType = { kind: 'failure' };
+/**
+ * @typedef {Object} ProductFactors
+ * @property {boolean} valid
+ * @property {boolean} structurallyValid
+ * @property {boolean} hasUnresolved
+ * @property {DimensionType | null} numerator
+ * @property {DimensionType | null} denominator
+ * @property {boolean} hasOpaqueNumerator
+ * @property {boolean} hasOpaqueDenominator
+ */
 
 /**
  * Analyze the original complete tree and return its root summary. Analysis
@@ -34,10 +50,8 @@ function analyzeType(node, depth = 0) {
     case 'Num':
       return resolved(numberType);
     case 'Dim':
-      // Percentages are contextual. Unknown units are opaque, while known
-      // families can still reject px + seconds.
       return node.unit === '%'
-        ? finish(unknownType, true, true)
+        ? finish(percentageType, true, true)
         : resolved({ kind: 'dimension', base: baseOf(node.unit) });
     case 'Ident':
       return markUnresolved(unknownType);
@@ -56,6 +70,7 @@ function analyzeType(node, depth = 0) {
 function analyzeSum(node, depth) {
   let type = null;
   let hasUnknown = false;
+  let hasPercentage = false;
   let valid = true;
   let hasUnresolved = false;
   for (const term of node.terms) {
@@ -65,7 +80,8 @@ function analyzeSum(node, depth) {
     if (isFailure(child.type)) {
       type = failureType;
     } else if (child.type.kind === 'unknown') {
-      hasUnknown = true;
+      if (isPercentage(child.type)) hasPercentage = true;
+      else hasUnknown = true;
     } else if (type === null) {
       type = child.type;
     } else if (!isFailure(type)) {
@@ -75,11 +91,10 @@ function analyzeSum(node, depth) {
   if (type !== null && isFailure(type)) {
     return finish(failureType, false, hasUnresolved);
   }
-  return finish(
-    type ?? (hasUnknown ? unknownType : numberType),
-    valid,
-    hasUnresolved
-  );
+  let fallback = numberType;
+  if (hasUnknown) fallback = unknownType;
+  else if (hasPercentage) fallback = percentageType;
+  return finish(type ?? fallback, valid, hasUnresolved);
 }
 
 /** @param {Extract<Node, {type: 'Product'}>} node @param {number} depth @return {{type: CalculationType, valid: boolean, unresolved: boolean}} */
@@ -88,8 +103,13 @@ function analyzeProduct(node, depth) {
   let denominator = null;
   let valid = true;
   let structurallyValid = true;
-  let hasUnknownNumerator = false;
-  let hasUnknownDenominator = false;
+  // Opaque factors (unknowns and pure percentages) are counted per side so
+  // the pass below can decide whether any unknown remains after cancelling
+  // `% / %` pairs.
+  let opaqueNumerator = 0;
+  let opaqueDenominator = 0;
+  let percentageNumerator = 0;
+  let percentageDenominator = 0;
   let hasUnresolved = false;
   for (const factor of node.factors) {
     const child = analyzeType(factor.node, depth + 1);
@@ -99,8 +119,13 @@ function analyzeProduct(node, depth) {
       continue;
     }
     if (child.type.kind === 'unknown') {
-      if (factor.exponent === 1) hasUnknownNumerator = true;
-      else hasUnknownDenominator = true;
+      if (factor.exponent === 1) {
+        opaqueNumerator++;
+        if (isPercentage(child.type)) percentageNumerator++;
+      } else {
+        opaqueDenominator++;
+        if (isPercentage(child.type)) percentageDenominator++;
+      }
       continue;
     }
     if (child.type.kind !== 'dimension') continue;
@@ -112,10 +137,36 @@ function analyzeProduct(node, depth) {
       else denominator = child.type;
     }
   }
+  // A percentage divided by a percentage is always a plain number: both
+  // operands resolve in the same context, so their contextual type cancels.
+  // Consume one such pair before judging the remaining unknowns so a
+  // surrounding sum does not mistake `% / %` for a length-compatible term.
+  const cancelled = Math.min(percentageNumerator, percentageDenominator);
+  const hasOpaqueNumerator = opaqueNumerator - cancelled > 0;
+  const hasOpaqueDenominator = opaqueDenominator - cancelled > 0;
+  return finishProduct({
+    valid,
+    structurallyValid,
+    hasUnresolved,
+    numerator,
+    denominator,
+    hasOpaqueNumerator,
+    hasOpaqueDenominator,
+  });
+}
+
+/**
+ * Classify a product once its factors are analyzed. Opaque factors can supply
+ * missing type information, but they cannot make an already-invalid
+ * combination of known dimensions valid.
+ * @param {ProductFactors} factors
+ * @return {{type: CalculationType, valid: boolean, unresolved: boolean}}
+ */
+function finishProduct(factors) {
+  const { valid, structurallyValid, hasUnresolved } = factors;
   if (!valid) return finish(failureType, false, hasUnresolved);
-  // Opaque factors can supply missing type information, but they cannot make
-  // an already-invalid combination of known dimensions valid.
   if (!structurallyValid) return finish(failureType, false, hasUnresolved);
+  const { numerator, denominator } = factors;
   if (
     numerator !== null &&
     denominator !== null &&
@@ -127,18 +178,13 @@ function analyzeProduct(node, depth) {
   // only leave that dimension in place (when it resolves to a number) or make
   // the product invalid. It can never make the product a bare number. Keep
   // that known constraint so a surrounding sum can reject `1px * 1% + 1`.
-  const constrained = constrainedNumerator(
-    hasUnknownNumerator,
-    hasUnknownDenominator,
-    numerator,
-    denominator
-  );
+  const constrained = constrainedNumerator(factors);
   if (constrained !== null) {
     return finish(constrained, true, hasUnresolved);
   }
   // Other opaque factors may supply type information that changes how the
   // known dimensions combine once the known factors are structurally valid.
-  if (hasUnknownNumerator || hasUnknownDenominator) {
+  if (factors.hasOpaqueNumerator || factors.hasOpaqueDenominator) {
     return finish(unknownType, true, hasUnresolved);
   }
   if (numerator !== null && denominator !== null) {
@@ -153,23 +199,15 @@ function analyzeProduct(node, depth) {
 }
 
 /**
- * @param {boolean} hasUnknownNumerator
- * @param {boolean} hasUnknownDenominator
- * @param {CalculationType | null} numerator
- * @param {CalculationType | null} denominator
- * @return {CalculationType | null}
+ * @param {ProductFactors} factors
+ * @return {DimensionType | null}
  */
-function constrainedNumerator(
-  hasUnknownNumerator,
-  hasUnknownDenominator,
-  numerator,
-  denominator
-) {
-  return hasUnknownNumerator &&
-    !hasUnknownDenominator &&
-    numerator !== null &&
-    denominator === null
-    ? numerator
+function constrainedNumerator(factors) {
+  return factors.hasOpaqueNumerator &&
+    !factors.hasOpaqueDenominator &&
+    factors.numerator !== null &&
+    factors.denominator === null
+    ? factors.numerator
     : 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/functions.js

@@ -14,13 +14,23 @@ import { simplifyLog } from './simplify/log.js';
 import { simplifyHypot } from './simplify/hypot.js';
 
 /** @typedef {import('./node.js').Node} Node */
-/** @typedef {{kind: 'number'} | {kind: 'dimension', base: string | null} | {kind: 'unknown'} | {kind: 'failure'}} CalculationType */
+/**
+ * `percent` marks a value that resolves in the same percentage context as its
+ * peers (a pure percentage). It is only produced at leaves, by abs(), and by
+ * homogeneous sums and calls — never by a product, where an unpaired
+ * percentage could no longer cancel against anything.
+ * @typedef {{kind: 'number'} | {kind: 'dimension', base: string | null} | {kind: 'unknown', percent?: true} | {kind: 'failure'}} CalculationType
+ */
 /** @typedef {(name: string, args: Node[]) => Node} MathSimplifier */
 /** @typedef {(args: CalculationType[], nodes: Node[]) => CalculationType} TypeAnalyzer */
 /** @typedef {{analyze: TypeAnalyzer, simplify?: MathSimplifier, isKeyword?: (node: Node, index: number) => boolean, calculation?: boolean}} MathFunction */
 
 /** @type {CalculationType} */ const numberType = { kind: 'number' };
 /** @type {CalculationType} */ const unknownType = { kind: 'unknown' };
+/** @type {CalculationType} */ const percentageType = {
+  kind: 'unknown',
+  percent: true,
+};
 /** @type {CalculationType} */ const failureType = { kind: 'failure' };
 
 /** @param {CalculationType} type @return {boolean} */
@@ -28,10 +38,23 @@ function isFailure(type) {
   return type.kind === 'failure';
 }
 
+/** @param {CalculationType} type @return {boolean} */
+function isPercentage(type) {
+  return type.kind === 'unknown' && type.percent === true;
+}
+
 /** @param {CalculationType} a @param {CalculationType} b @return {CalculationType} */
 function addTypes(a, b) {
   if (isFailure(a) || isFailure(b)) return failureType;
-  if (a.kind === 'unknown' || b.kind === 'unknown') return unknownType;
+  if (a.kind === 'unknown' || b.kind === 'unknown') {
+    // A pure percentage keeps its contextual type so a surrounding product
+    // can cancel `% / %`; mixing it with any other opaque operand loses the
+    // guarantee that it resolves in the same context as its peers. A known
+    // number + percentage sum is likewise kept unknown and valid: the spec
+    // resolves the percentage against its surrounding context, which this
+    // coarse type model does not track.
+    return isPercentage(a) && isPercentage(b) ? percentageType : unknownType;
+  }
   if (a.kind === 'number' && b.kind === 'number') return numberType;
   if (a.kind === 'dimension' && b.kind === 'dimension') {
     if (a.base === null || b.base === null) return unknownType;
@@ -129,9 +152,11 @@ function analyzeRound(args, nodes) {
 /** @param {CalculationType[]} args @return {CalculationType} */
 function analyzeAtan2(args) {
   const type = matchingArguments(args, 2, 2);
-  return isFailure(type) || type.kind === 'unknown'
-    ? type
-    : { kind: 'dimension', base: 'angle' };
+  if (isFailure(type)) return type;
+  // The type table gives atan2() «["angle" → 1]»; an unresolved result is
+  // plain unknown, never the percentage of its arguments.
+  if (type.kind === 'unknown') return unknownType;
+  return { kind: 'dimension', base: 'angle' };
 }
 
 /** @param {CalculationType[]} args @return {CalculationType} */
@@ -354,11 +379,16 @@ function hasPotentialMathFunction(value) {
 
 export {
   addTypes,
-  mathFunctions,
-  lookupMathFunction,
-  QUICK_MATH_TEST,
-  isFailure,
+  failureType,
+  hasPotentialMathFunction,
   isCalculationFunction,
+  isFailure,
+  isPercentage,
   isSupportedMathFunction,
-  hasPotentialMathFunction,
+  lookupMathFunction,
+  mathFunctions,
+  numberType,
+  percentageType,
+  QUICK_MATH_TEST,
+  unknownType,
 };

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
@@ -215,7 +261,7 @@ function negate(node) {
   }
   if (node.type === 'Sum') {
     // A grouped sum may contain opaque terms whose meaning depends on the
-    // surrounding context. Keep the group intact so `-(a + b)` cannot turn
+    // surrounding context. Keep the group intact so `-1 * (a + b)` cannot turn
     // into `-a - b` while it is still unresolved.
     if (node.grouped) {
       return mkSum([{ sign: -1, 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,
+};