postcss-calc 11.2.1 → 11.2.2

package/src/lib/simplify/cancel.js

@@ -1,17 +1,21 @@
 import { baseOf, convert } from '../convertUnits.js';
+import { isExact } from './exact.js';
 
 /**
  * If `dims` contain exactly one numerator / one denominator pair with the
- * same base type and convertible units, return the numeric factor produced
- * by cancelling them and the list of remaining (uncancelled) dims.
- * Otherwise return null. Used by `simplifyProduct` for typed division
- * (§10.2). More complex cancellation (e.g. `px^2 / px`) is left
+ * same base type and convertible units, return the two sides expressed in a
+ * common unit, so the caller can fold them into its own numerator and
+ * denominator. Otherwise return null. Used by `simplifyProduct` for typed
+ * division (§10.2). More complex cancellation (e.g. `px^2 / px`) is left
  * unreduced — consumers rarely rely on it and the spec doesn't require it.
  * @template {{ exponent: 1 | -1, value: number, unit: string }} D
  * @param {D[]} dims
- * @return {{ factor: number, remaining: D[] } | null}
+ * @param {number | false} [precision] The denominator is converted into the
+ *   numerator's unit when that is exact at this precision (`1px / 1in` →
+ *   `1 / 96`); otherwise the numerator is converted (`1in / 1px` → `96 / 1`).
+ * @return {{ numerator: number, denominator: number, remaining: D[] } | null}
  */
-function tryCancelPair(dims) {
+function tryCancelPair(dims, precision = false) {
   if (dims.length !== 2) {
     return null;
   }
@@ -26,12 +30,32 @@ function tryCancelPair(dims) {
   if (!numBase || numBase !== denBase) {
     return null;
   }
-  const converted = convert(numerator.value, numerator.unit, denominator.unit);
-  if (converted === null) {
-    return null;
-  }
+  const converted = convert(
+    denominator.value,
+    denominator.unit,
+    numerator.unit
+  );
   // denominator.value === 0 yields ±Infinity / NaN naturally (§10.9.1).
-  return { factor: converted / denominator.value, remaining: [] };
+  if (converted !== null && isExact(converted, precision)) {
+    return {
+      numerator: numerator.value,
+      denominator: converted,
+      remaining: [],
+    };
+  }
+  const numConverted = convert(
+    numerator.value,
+    numerator.unit,
+    denominator.unit
+  );
+  if (numConverted !== null && isExact(numConverted, precision)) {
+    return {
+      numerator: numConverted,
+      denominator: denominator.value,
+      remaining: [],
+    };
+  }
+  return null;
 }
 
 export { tryCancelPair };

package/src/lib/simplify/clamp.js

@@ -1,5 +1,5 @@
 import { call } from '../node.js';
-import { foldConstArgs, foldResult } from './fold.js';
+import { foldConstArgs, chosenArg } from './fold.js';
 import { simplifyMinMax } from './min-max.js';
 
 /** @typedef {import('../node.js').Node} Node */
@@ -29,7 +29,7 @@ function simplifyClamp(args) {
       // Spec §10.8: clamp(MIN, VAL, MAX) = max(MIN, min(VAL, MAX)). The
       // outer max(MIN, …) means MIN wins when MIN > MAX — not MAX.
       const clamped = Math.max(lo, Math.min(v, hi));
-      return foldResult(fold, clamped);
+      return chosenArg(args, fold, clamped);
     }
   }
   return call('clamp', args);

package/src/lib/simplify/exact.js

@@ -0,0 +1,18 @@
+import { round } from '../serialize/precision.js';
+
+/**
+ * A value is exact at `precision` when rounding it for output loses nothing
+ * beyond float noise.
+ * @param {number} value
+ * @param {number | false} precision
+ * @return {boolean}
+ */
+function isExact(value, precision) {
+  if (precision === false || !Number.isFinite(value)) {
+    return true;
+  }
+  const snapped = Number(value.toPrecision(15));
+  return round(snapped, precision) === snapped;
+}
+
+export { isExact };

package/src/lib/simplify/fold.js

@@ -16,6 +16,20 @@ function foldResult(fold, value) {
   return fold.unit === '' ? num(value) : dim(value, fold.unit);
 }
 
+/**
+ * Return the argument that produced a folded min/max/clamp value, so the
+ * result keeps its own unit, spelling and zero sign. Falls back to a fresh
+ * node when no argument matches (NaN).
+ * @param {Node[]} args
+ * @param {{ values: number[], unit: string }} fold
+ * @param {number} value
+ * @return {Node}
+ */
+function chosenArg(args, fold, value) {
+  const index = fold.values.findIndex((v) => Object.is(v, value));
+  return index === -1 ? foldResult(fold, value) : args[index];
+}
+
 /**
  * @param {Node[]} args
  * @return {{ values: number[], unit: string } | null}
@@ -75,4 +89,4 @@ function foldDimArgs(args, unit, base) {
   return { values, unit };
 }
 
-export { foldConstArgs, foldResult };
+export { foldConstArgs, foldResult, chosenArg };

package/src/lib/simplify/min-max.js

@@ -1,5 +1,5 @@
 import { call } from '../node.js';
-import { foldConstArgs, foldResult } from './fold.js';
+import { foldConstArgs, chosenArg } from './fold.js';
 
 /** @typedef {import('../node.js').Node} Node */
 
@@ -13,7 +13,7 @@ function simplifyMinMax(name, args) {
   if (fold !== null) {
     const fn = name.toLowerCase() === 'min' ? Math.min : Math.max;
     const value = fn(...fold.values);
-    return foldResult(fold, value);
+    return chosenArg(args, fold, value);
   }
   return call(name, args);
 }

package/src/lib/simplify/product.js

@@ -1,5 +1,6 @@
-import { mkSum, mkProduct, num, dim } from '../node.js';
+import { mkSum, mkProduct, mkGroup, num, dim } from '../node.js';
 import { tryCancelPair } from './cancel.js';
+import { isExact } from './exact.js';
 
 /**
  * @typedef {import('../node.js').Node} Node
@@ -9,12 +10,150 @@ import { tryCancelPair } from './cancel.js';
  */
 
 /**
- * @param {Product} product
+ * @param {number} a non-negative
+ * @param {number} b non-negative
+ * @return {number}
+ */
+function gcd(a, b) {
+  while (b !== 0) {
+    [a, b] = [b, a % b];
+  }
+  return a || 1;
+}
+
+/**
+ * @param {{exponent: 1 | -1, value: number}[]} chain
+ * @return {number}
+ */
+function chainValue(chain) {
+  let value = 1;
+  for (const f of chain) {
+    value = f.exponent === 1 ? value * f.value : value / f.value;
+  }
+  return value;
+}
+
+/**
+ * Whether the opaque factors are a single Sum of only Num/Dim terms.
+ * @param {ProductFactor[]} opaque
+ * @return {boolean}
+ */
+function isScalarSum(opaque) {
+  return (
+    opaque.length === 1 &&
+    opaque[0].exponent === 1 &&
+    opaque[0].node.type === 'Sum' &&
+    opaque[0].node.terms.every(
+      (t) => t.node.type === 'Num' || t.node.type === 'Dim'
+    )
+  );
+}
+
+/**
+ * Whether a folded quotient prints exactly. A quotient distributed over a
+ * scalar Sum is judged term by term, so `(3px + 6em) / 3` still folds.
+ * @param {number} value
+ * @param {ProductFactor[]} opaque
+ * @param {boolean} distributable
+ * @param {number | false} precision
+ * @return {boolean}
+ */
+function foldsExactly(value, opaque, distributable, precision) {
+  if (!Number.isFinite(value) || isExact(value, precision)) {
+    return true;
+  }
+  if (!distributable) {
+    return false;
+  }
+  const sum = /** @type {import('../node.js').Sum} */ (opaque[0].node);
+  return sum.terms.every((t) =>
+    isExact(
+      value *
+        /** @type {import('../node.js').Num | import('../node.js').Dim} */ (
+          t.node
+        ).value,
+      precision
+    )
+  );
+}
+
+/**
+ * Emit an inexact quotient as `numerator * dims * opaque / denominator`, with
+ * integer parts reduced by their gcd. A lone Dim absorbs the numerator.
+ * @param {number} numerator
+ * @param {number} denominator
+ * @param {{value: number, unit: string, rawUnit?: string} | null} loneDim
+ * @param {{exponent: 1 | -1, value: number, unit: string, rawUnit?: string}[]} dims
+ * @param {ProductFactor[]} opaque
+ * @param {number | false} precision
+ * @return {Node | null} null when a part would be rounded on output
+ */
+function rationalProduct(
+  numerator,
+  denominator,
+  loneDim,
+  dims,
+  opaque,
+  precision
+) {
+  // Drop float noise (`1.9999999999999993 * 100`) so the parts print as
+  // written and the gcd below can reduce them.
+  let n = Number(
+    (loneDim === null ? numerator : numerator * loneDim.value).toPrecision(15)
+  );
+  let d = Number(denominator.toPrecision(15));
+  if (!isExact(n, precision) || !isExact(d, precision)) {
+    return null;
+  }
+  if (Number.isSafeInteger(n) && Number.isSafeInteger(d)) {
+    const g = gcd(Math.abs(n), Math.abs(d));
+    n /= g;
+    d /= g;
+  }
+  if (d < 0) {
+    n = -n;
+    d = -d;
+  }
+  /** @type {ProductFactor[]} */
+  const factors = [];
+  if (loneDim !== null) {
+    factors.push({
+      exponent: 1,
+      node: dim(n, loneDim.unit, loneDim.rawUnit),
+    });
+  } else {
+    if (n !== 1) {
+      factors.push({ exponent: 1, node: num(n) });
+    }
+    for (const dm of dims) {
+      factors.push({
+        exponent: dm.exponent,
+        node: dim(dm.value, dm.unit, dm.rawUnit),
+      });
+    }
+  }
+  factors.push(...opaque);
+  if (d !== 1) {
+    factors.push({ exponent: -1, node: num(d) });
+  }
+  return mkProduct(factors);
+}
+
+/**
+ * Fold a run of factors that contains no substitution barrier.
+ * @param {ProductFactor[]} items Simplified factors, flattened by the caller.
+ * @param {number} start
+ * @param {number} end
  * @param {SimplifyFn} simplify
+ * @param {number | false} precision
  * @return {Node}
  */
-function simplifyProduct(product, simplify) {
+function foldFactors(items, start, end, simplify, precision) {
   let coeff = 1;
+  // Num factors by exponent, so an inexact quotient can be re-emitted as a
+  // reduced `numerator / denominator`.
+  let numerator = 1;
+  let denominator = 1;
   /** @type {{exponent: 1 | -1, value: number, unit: string, rawUnit?: string}[]} */
   const dims = [];
   /** @type {ProductFactor[]} */
@@ -28,27 +167,13 @@ function simplifyProduct(product, simplify) {
    * @return {void}
    */
   function processFactor(exponent, n) {
-    if (n.type === 'Product') {
-      for (const inner of n.factors) {
-        processFactor(
-          /** @type {1 | -1} */ (exponent * inner.exponent),
-          inner.node
-        );
-      }
-      return;
-    }
-    // Canonical negation form (see node.js's `negate`); flatten through it
-    // like a nested Product so cancellation below can see what's inside.
-    if (n.type === 'Sum' && n.terms.length === 1) {
-      processFactor(exponent, num(-1));
-      processFactor(exponent, n.terms[0].node);
-      return;
-    }
     if (n.type === 'Num') {
       if (exponent === 1) {
         coeff *= n.value;
+        numerator *= n.value;
       } else {
         coeff /= n.value; // §10.9.1: 1/0 → ±Infinity, 0/0 → NaN per IEEE-754
+        denominator *= n.value;
       }
       scalarChain.push({ exponent, value: n.value });
       return;
@@ -61,31 +186,50 @@ function simplifyProduct(product, simplify) {
     opaque.push({ exponent, node: n });
   }
 
-  for (const f of product.factors) {
-    processFactor(f.exponent, simplify(f.node));
+  for (let i = start; i < end; i++) {
+    processFactor(items[i].exponent, items[i].node);
   }
 
   // §10.2 typed division. Higher-power cancellation (`px^2 / px`) is left
   // unreduced — consumers don't rely on it and the spec doesn't require it.
-  const cancelled = tryCancelPair(dims);
+  const cancelled = tryCancelPair(dims, precision);
   if (cancelled !== null) {
-    coeff *= cancelled.factor;
+    coeff *= cancelled.numerator / cancelled.denominator;
+    numerator *= cancelled.numerator;
+    denominator *= cancelled.denominator;
   }
+  const divides = denominator !== 1 || cancelled !== null;
   const remainingDims = cancelled ? cancelled.remaining : dims;
+  const loneDim =
+    remainingDims.length === 1 &&
+    remainingDims[0].exponent === 1 &&
+    opaque.length === 0
+      ? remainingDims[0]
+      : null;
+  const value = loneDim === null ? coeff : chainValue(scalarChain);
+  const distributable = remainingDims.length === 0 && isScalarSum(opaque);
+
+  // An inexact quotient stays symbolic when its numerator and denominator
+  // print exactly; otherwise it is folded and rounded at serialization.
+  if (divides && !foldsExactly(value, opaque, distributable, precision)) {
+    const rational = rationalProduct(
+      numerator,
+      denominator,
+      loneDim,
+      remainingDims,
+      opaque,
+      precision
+    );
+    if (rational !== null) {
+      return rational;
+    }
+  }
 
   // §10.10 distributive multiplication: `0.5 * (100vw - 10px)` → `50vw - 5px`.
   // Only distribute when every Sum term is Num/Dim — partial distribution
   // over opaque terms matches neither the legacy implementation nor csstools.
-  if (
-    remainingDims.length === 0 &&
-    opaque.length === 1 &&
-    opaque[0].exponent === 1 &&
-    opaque[0].node.type === 'Sum' &&
-    opaque[0].node.terms.every(
-      (t) => t.node.type === 'Num' || t.node.type === 'Dim'
-    )
-  ) {
-    const sum = opaque[0].node;
+  if (distributable) {
+    const sum = /** @type {import('../node.js').Sum} */ (opaque[0].node);
     const distributed = sum.terms.map((t) => ({
       sign: t.sign,
       node: simplify(
@@ -98,21 +242,8 @@ function simplifyProduct(product, simplify) {
     return mkSum(distributed);
   }
 
-  if (
-    remainingDims.length === 1 &&
-    remainingDims[0].exponent === 1 &&
-    opaque.length === 0
-  ) {
-    const d = remainingDims[0];
-    let value = 1;
-    for (const f of scalarChain) {
-      if (f.exponent === 1) {
-        value = value * f.value;
-      } else {
-        value = value / f.value;
-      }
-    }
-    return dim(value, d.unit, d.rawUnit);
+  if (loneDim !== null) {
+    return dim(value, loneDim.unit, loneDim.rawUnit);
   }
 
   if (remainingDims.length === 0 && opaque.length === 0) {
@@ -135,4 +266,88 @@ function simplifyProduct(product, simplify) {
   return mkProduct(factors);
 }
 
+/**
+ * A substitution function (`var()`, `env()`, `attr()`, ...) is replaced by
+ * tokens, not by a value, so factors cannot move or cancel across it. Any
+ * function the parser does not recognise (`anchor()`, `foo()`, ...) is also an
+ * OpaqueCall and is treated the same, conservatively. A grouped Product is a
+ * parenthesized substitution and is equally opaque.
+ * @param {Node} node
+ * @return {boolean}
+ */
+function isBarrier(node) {
+  return (
+    node.type === 'OpaqueCall' ||
+    (node.type === 'Product' && node.grouped === true)
+  );
+}
+
+/**
+ * Flatten a simplified factor through nested ungrouped Products and the
+ * canonical negation form, so barriers are visible at the top level.
+ * @param {ProductFactor[]} out
+ * @param {1 | -1} exponent
+ * @param {Node} node
+ * @return {boolean} Whether a barrier was pushed.
+ */
+function flattenFactor(out, exponent, node) {
+  if (node.type === 'Product' && !node.grouped) {
+    let barrier = false;
+    for (const inner of node.factors) {
+      if (
+        flattenFactor(
+          out,
+          /** @type {1 | -1} */ (exponent * inner.exponent),
+          inner.node
+        )
+      )
+        barrier = true;
+    }
+    return barrier;
+  }
+  if (node.type === 'Sum' && node.terms.length === 1) {
+    out.push({ exponent, node: num(-1) });
+    return flattenFactor(out, exponent, node.terms[0].node);
+  }
+  out.push({ exponent, node });
+  return isBarrier(node);
+}
+
+/**
+ * @param {Product} product
+ * @param {SimplifyFn} simplify
+ * @param {number | false} [precision] A quotient that is not exact at this
+ *   precision stays symbolic (`100% / 3`) instead of being rounded.
+ * @return {Node}
+ */
+function simplifyProduct(product, simplify, precision = false) {
+  /** @type {ProductFactor[]} */
+  const items = [];
+  let hasBarrier = false;
+  for (const f of product.factors) {
+    if (flattenFactor(items, f.exponent, simplify(f.node))) hasBarrier = true;
+  }
+  if (!hasBarrier)
+    return foldFactors(items, 0, items.length, simplify, precision);
+
+  // Fold each run between barriers on its own; never move or cancel a factor
+  // across a barrier, and keep each barrier's own operator.
+  /** @type {ProductFactor[]} */
+  const factors = [];
+  let start = 0;
+  for (let i = 0; i <= items.length; i++) {
+    if (i < items.length && !isBarrier(items[i].node)) continue;
+    if (i - start === 1) factors.push(items[start]);
+    else if (i - start > 1)
+      factors.push({
+        exponent: 1,
+        node: foldFactors(items, start, i, simplify, precision),
+      });
+    if (i < items.length) factors.push(items[i]);
+    start = i + 1;
+  }
+  const result = mkProduct(factors);
+  return product.grouped === true ? mkGroup(result) : result;
+}
+
 export { simplifyProduct };

package/src/lib/simplify/sum.js

@@ -26,9 +26,10 @@ function denoise(total, scale) {
 /**
  * @param {Sum} sum
  * @param {SimplifyFn} simplify
+ * @param {number | false} [precision]
  * @return {Node}
  */
-function simplifySum(sum, simplify) {
+function simplifySum(sum, simplify, precision = false) {
   // §10.10 two-phase dim handling: phase 1 buckets by exact unit (`1em + 1em`
   // → `2em`); phase 2 merges convertible same-base buckets into the first-
   // encountered unit. `100vh - 5rem - 10rem - 100px` → `-15rem` in phase 1,
@@ -106,7 +107,10 @@ function simplifySum(sum, simplify) {
   const terms = hasNum
     ? [{ sign: /** @type {1} */ (1), node: num(denoise(numTotal, numScale)) }]
     : [];
-  for (const bucket of mergeConvertibleBuckets([...byUnit.values()])) {
+  for (const bucket of mergeConvertibleBuckets(
+    [...byUnit.values()],
+    precision
+  )) {
     terms.push({
       sign: 1,
       node: dim(

package/src/lib/simplify.js

@@ -6,7 +6,8 @@ import { simplifySum } from './simplify/sum.js';
 import { simplifyProduct } from './simplify/product.js';
 import { simplifyCall } from './simplify/call.js';
 import { simplifyComponents } from './opaque.js';
-import { opaqueCall } from './node.js';
+import { groupSubstitution, opaqueCall } from './node.js';
+import { isCalculationFunction } from './functions.js';
 import { assertDepth } from './limits.js';
 
 /**
@@ -17,17 +18,33 @@ import { assertDepth } from './limits.js';
  * @typedef {(node: Node) => Node} SimplifyFn
  */
 
+/**
+ * A nested calc() is a parenthesized group: with unresolved tokens inside,
+ * its operands must not merge into the surrounding sum or product.
+ * @param {Node} value
+ * @param {(value: Node) => Node} child
+ * @return {Node}
+ */
+function operand(value, child) {
+  const result = child(value);
+  return value.type === 'Call' && isCalculationFunction(value.name)
+    ? groupSubstitution(result)
+    : result;
+}
+
 /**
  * Simplify is an independent, composable AST transformation. It may
  * synthesize canonical nodes while preserving the Node -> Node contract.
  * @param {Node} node
+ * @param {number | false} [precision] When set, divisions and unit
+ *   conversions that are not exact at this precision stay symbolic.
  * @param {number} [depth]
  * @return {Node}
  */
-function simplify(node, depth = 0) {
+function simplify(node, precision = false, depth = 0) {
   assertDepth(depth);
   /** @param {Node} value */
-  const child = (value) => simplify(value, depth + 1);
+  const child = (value) => simplify(value, precision, depth + 1);
   switch (node.type) {
     case 'Num':
     case 'Dim':
@@ -42,9 +59,9 @@ function simplify(node, depth = 0) {
         node.rawName
       );
     case 'Sum':
-      return simplifySum(node, child);
+      return simplifySum(node, (value) => operand(value, child), precision);
     case 'Product':
-      return simplifyProduct(node, child);
+      return simplifyProduct(node, (value) => operand(value, child), precision);
   }
 }
 

package/src/reduce.js

@@ -61,11 +61,12 @@ function reduceCalc(value, opts) {
 
   /** @type {ResolvedReduceCalcOptions} */
   const options = {
-    precision: 5,
     warnWhenCannotResolve: false,
     unwrapSingleNegativeNumber: false,
     unwrapSingleValue: false,
     ...opts,
+    // An explicit `precision: undefined` keeps the default.
+    precision: opts?.precision ?? 5,
   };
   /** @type {import('@csstools/css-tokenizer').CSSToken[]} */
   let tokens;

package/types/lib/node.d.ts

@@ -42,6 +42,7 @@ export type ProductFactor = {
 export type Product = {
     type: 'Product';
     factors: ProductFactor[];
+    grouped?: boolean;
 };
 export type Node = Num | Dim | Ident | Call | OpaqueCall | Sum | Product;
 /**
@@ -54,7 +55,7 @@ export type Node = Num | Dim | Ident | Call | OpaqueCall | Sum | Product;
  * @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
  */
 /**
@@ -99,10 +100,24 @@ declare function mkSum(rawTerms: SumTerm[]): Node;
  * @return {Node}
  */
 declare function mkProduct(rawFactors: ProductFactor[]): Node;
+/**
+ * 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}
+ */
+declare function mkGroup(node: Node): Node;
+/**
+ * Group a parenthesized expression when its tokens must stay bound: a sum, or
+ * a product around a substitution function.
+ * @param {Node} node
+ * @return {Node}
+ */
+declare function groupSubstitution(node: Node): Node;
 /**
  * Negate any node, preserving canonical form.
  * @param {Node} node
  * @return {Node}
  */
 declare function negate(node: Node): Node;
-export { num, dim, ident, call, opaqueCall, mkSum, mkProduct, negate };
+export { num, dim, ident, call, opaqueCall, mkSum, mkProduct, mkGroup, groupSubstitution, negate, };

package/types/lib/parser/opaque.d.ts

@@ -0,0 +1,12 @@
+export type CSSToken = import('@csstools/css-tokenizer').CSSToken;
+export type Node = import('../node.js').Node;
+export type OpaqueComponent = import('../node.js').OpaqueComponent;
+export type ParseInput = import('./tokens.js').ParseInput;
+export type Cursor = import('./tokens.js').Cursor;
+export type FunctionToken = import('./tokens.js').FunctionToken;
+export type ParseRange = (input: ParseInput, start: number, end: number) => Node;
+/** @param {ParseInput} input @param {Cursor} cursor @param {FunctionToken} token @param {string} name @param {string} rawName @param {ParseRange} parseRange @return {Node} */
+declare function parseOpaqueCall(input: ParseInput, cursor: Cursor, token: FunctionToken, name: string, rawName: string, parseRange: ParseRange): Node;
+/** @param {ParseInput} input @param {Cursor} cursor @param {FunctionToken} token @param {string} name @param {string} rawName @param {ParseRange} parseRange @return {Node} */
+declare function parseVar(input: ParseInput, cursor: Cursor, token: FunctionToken, name: string, rawName: string, parseRange: ParseRange): Node;
+export { parseOpaqueCall, parseVar };