postcss-calc 11.0.0-rc.2 → 11.0.0

package/README.md

@@ -56,7 +56,8 @@ Checkout [tests] for more examples.
 
 #### `precision` (default: `5`)
 
-Allow you to define the precision for decimal numbers.
+Allows you to define the precision for decimal numbers. Set it to `false` to
+disable rounding.
 
 ```js
 var out = postcss()
@@ -64,17 +65,6 @@ var out = postcss()
   .process(css).css;
 ```
 
-#### `preserve` (default: `false`)
-
-Allow you to preserve calc() usage in output so browsers will handle decimal
-precision themselves.
-
-```js
-var out = postcss()
-  .use(calc({ preserve: true }))
-  .process(css).css;
-```
-
 #### `warnWhenCannotResolve` (default: `false`)
 
 Adds warnings when calc() are not reduced to a single value.
@@ -87,7 +77,7 @@ var out = postcss()
 
 #### `mediaQueries` (default: `false`)
 
-Allows calc() usage as part of media query declarations.
+Allows calc() usage in media query parameters.
 
 ```js
 var out = postcss()
@@ -95,6 +85,26 @@ var out = postcss()
   .process(css).css;
 ```
 
+Example:
+
+```css
+@media (min-width: calc(100px + 100px)) {
+  div {
+    width: 100px;
+  }
+}
+```
+
+With `mediaQueries: true`, this becomes:
+
+```css
+@media (min-width: 200px) {
+  div {
+    width: 100px;
+  }
+}
+```
+
 #### `selectors` (default: `false`)
 
 Allows calc() usage as part of selectors.
@@ -108,11 +118,13 @@ var out = postcss()
 Example:
 
 ```css
-div[data-size='calc(3*3)'] {
+div:nth-child(calc(1 + 2)) {
   width: 100px;
 }
 ```
 
+With `selectors: true`, this becomes `div:nth-child(3)`.
+
 #### `onParseError`
 
 Callback invoked when a `calc()` body fails to parse or simplify. Matches
@@ -186,6 +198,14 @@ npm install
 npm test
 ```
 
+The normal test run uses a deterministic structural sample of the harvested
+real-world corpus. Run the complete differential corpus before releases or
+when changing parsing/simplification behavior:
+
+```bash
+pnpm test:corpus:full
+```
+
 ## [Changelog](CHANGELOG.md)
 
 ## [License](LICENSE)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "postcss-calc",
-  "version": "11.0.0-rc.2",
+  "version": "11.0.0",
   "type": "module",
   "description": "PostCSS plugin to reduce calc()",
   "keywords": [
@@ -29,21 +29,27 @@
   "author": "Andy Jansson",
   "license": "MIT",
   "engines": {
-    "node": "^22.18 || ^24.11 || >=26.0"
+    "node": "^22.22.3 || ^24.15 || >=26.0"
+  },
+  "devEngines": {
+    "packageManager": {
+      "name": "pnpm",
+      "version": "11.22.0"
+    }
   },
   "devDependencies": {
     "@csstools/css-calc": "^3.3.0",
     "@rmenke/css-tokenizer-tests": "^1.2.0",
-    "@types/node": "^26.1.2",
+    "@types/node": "^26.2.0",
     "fast-check": "^4.9.0",
-    "oxfmt": "^0.61.0",
-    "oxlint": "^1.76.0",
-    "postcss": "^8.5.25",
+    "oxfmt": "^0.64.0",
+    "oxlint": "^1.79.0",
+    "postcss": "^8.5.26",
     "typescript": "~7.0.2"
   },
   "dependencies": {
-    "@csstools/css-tokenizer": "^4.0.0",
-    "postcss-value-parser": "^4.2.0"
+    "@csstools/css-parser-algorithms": "^4.0.0",
+    "@csstools/css-tokenizer": "^4.0.0"
   },
   "peerDependencies": {
     "postcss": "^8.5.25"
@@ -51,6 +57,8 @@
   "scripts": {
     "lint": "oxlint . && tsc && oxfmt --check",
     "fmt": "oxfmt",
-    "test": "node --test"
+    "test": "node --test --test-reporter=dot 'test/**/*.test.mjs' test/index.cjs test/convertUnit.cjs",
+    "test:mutation:corpus": "node test/mutation/corpus-selection.mjs",
+    "test:corpus:full": "POSTCSS_CALC_FULL_CORPUS=1 node --test test/conformance/corpus.test.mjs"
   }
 }

package/src/index.js

@@ -1,50 +1,111 @@
 // PostCSS adapter. Walks declaration values (and optionally @rule params
 // and selectors), feeds calc() bodies through tokenize → parse → simplify
 // → serialize, and writes the result back.
-import valueParser from 'postcss-value-parser';
+import { tokenize as cssTokenize } from '@csstools/css-tokenizer';
+import {
+  isFunctionNode,
+  isSimpleBlockNode,
+  parseListOfComponentValues,
+} from '@csstools/css-parser-algorithms';
 import { tokenize } from './lib/tokenizer.js';
 import { parse } from './lib/parser.js';
 import { simplify } from './lib/simplify.js';
+import { isSupportedMathFunction } from './lib/simplify/call.js';
 import { serialize } from './lib/serialize.js';
 
-const MATCH_CALC = /^(?:-(?:moz|webkit)-)?calc$/i;
+// The outer walk is deliberately forgiving: it only needs to locate calc()/
+// math-function boundaries in otherwise arbitrary (and possibly non-standard)
+// CSS values, so parse errors from the outer tokenizer/parser are swallowed.
+// Genuine syntax problems inside a matched call are
+// caught below via our own tokenize/parse/simplify pipeline.
+const NOOP_PARSE_ERROR = { onParseError: () => {} };
 
-// 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',
-]);
+const MATCH_CALC = /^(?:-(?:moz|webkit)-)?calc$/i;
 
 /**
- * @typedef {object} PluginOptions
+ * @typedef {object} PostCssCalcOptions
  * @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 */
+/** @typedef {Required<Omit<PostCssCalcOptions, 'onParseError'>> & Pick<PostCssCalcOptions, 'onParseError'>} ResolvedOptions */
+
+/**
+ * Fields threaded unchanged through the recursive `transformList` walk.
+ * `value` is the original full property text, used only for the
+ * warnWhenCannotResolve message.
+ *
+ * @typedef {object} TransformContext
+ * @property {ResolvedOptions} options
+ * @property {import('postcss').Result} result
+ * @property {import('postcss').ChildNode} item
+ * @property {string} value
+ */
+
+/**
+ * Walks a list of component values in place, replacing matched calc()/math
+ * function nodes with their simplified form. Unlike the library's generic
+ * `walk` helper, this recurses manually so a matched node's own (stale,
+ * pre-simplification) children are never independently re-visited.
+ *
+ * @param {import('@csstools/css-parser-algorithms').ComponentValue[]} list
+ * @param {TransformContext} ctx
+ * @return {void}
+ */
+function transformList(list, ctx) {
+  for (let i = 0; i < list.length; i++) {
+    const node = list[i];
+    if (!isFunctionNode(node)) {
+      if (isSimpleBlockNode(node)) {
+        transformList(node.value, ctx);
+      }
+      continue;
+    }
+
+    const name = node.getName();
+    const isCalc = MATCH_CALC.test(name);
+    const isMath = !isCalc && isSupportedMathFunction(name);
+    if (!isCalc && !isMath) {
+      transformList(node.value, ctx);
+      continue;
+    }
+
+    // calc(): feed the body. Bare math: feed the whole call.
+    const inner = node.value.map((child) => child.toString()).join('');
+    const contents = isCalc ? inner : `${name}(${inner})`;
+    try {
+      const simplified = simplify(parse(tokenize(contents)));
+      const str = serialize(simplified, {
+        precision: ctx.options.precision,
+        calcName: isCalc ? name : 'calc', // preserve vendor prefix on calc()
+      });
+
+      if (ctx.options.warnWhenCannotResolve && str.startsWith(`${name}(`)) {
+        ctx.result.warn('Could not reduce expression: ' + ctx.value, {
+          plugin: 'postcss-calc',
+          node: ctx.item,
+        });
+      }
+
+      const replacement = parseListOfComponentValues(
+        cssTokenize({ css: str }),
+        NOOP_PARSE_ERROR
+      );
+      list.splice(i, 1, ...replacement);
+      i += replacement.length - 1;
+    } catch (error) {
+      const err = error instanceof Error ? error : new Error('Error');
+      if (ctx.options.onParseError) {
+        ctx.options.onParseError(err, contents);
+      } else {
+        ctx.result.warn(err.message, { node: ctx.item });
+      }
+    }
+  }
+}
 
 /**
  * @param {string} value
@@ -54,60 +115,42 @@ const MATH_FUNCTIONS = new Set([
  * @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;
-      }
+  const componentValues = parseListOfComponentValues(
+    cssTokenize({ css: value }),
+    NOOP_PARSE_ERROR
+  );
 
-      // 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()
-        });
+  transformList(componentValues, { options, result, item, value });
 
-        if (options.warnWhenCannotResolve && str.startsWith(`${node.value}(`)) {
-          result.warn('Could not reduce expression: ' + value, {
-            plugin: 'postcss-calc',
-            node: item,
-          });
-        }
+  return componentValues.map((node) => node.toString()).join('');
+}
 
-        // 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();
+/**
+ * Runs `transformValue` over one text property of a decl/atrule/rule node
+ * and updates it in place.
+ * `setProp` closes over the property name and the concrete node type at
+ * each call site, since `Declaration`/`AtRule`/`Rule` don't share a typed
+ * "text property" name to index generically.
+ *
+ * @param {import('postcss').ChildNode} node
+ * @param {string} current
+ * @param {(target: import('postcss').ChildNode, value: string) => void} setProp
+ * @param {ResolvedOptions} options
+ * @param {import('postcss').Result} result
+ * @return {void}
+ */
+function applyTransform(node, current, setProp, options, result) {
+  setProp(node, transformValue(current, options, result, node));
 }
 
 /**
- * @param {PluginOptions} [opts]
+ * @param {PostCssCalcOptions} [opts]
  * @return {import('postcss').Plugin}
  */
 function pluginCreator(opts) {
   /** @type {ResolvedOptions} */
   const options = {
     precision: 5,
-    preserve: false,
     warnWhenCannotResolve: false,
     mediaQueries: false,
     selectors: false,
@@ -123,45 +166,49 @@ function pluginCreator(opts) {
     OnceExit(css, { result }) {
       css.walk((node) => {
         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;
-          }
+          applyTransform(
+            node,
+            node.value,
+            (n, v) => {
+              /** @type {import('postcss').Declaration} */ (n).value = v;
+            },
+            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;
-          }
+          applyTransform(
+            node,
+            node.params,
+            (n, v) => {
+              /** @type {import('postcss').AtRule} */ (n).params = v;
+            },
+            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;
-          }
+          applyTransform(
+            node,
+            node.selector,
+            (n, v) => {
+              /** @type {import('postcss').Rule} */ (n).selector = v;
+            },
+            options,
+            result
+          );
         }
       });
     },
   };
 }
 
+/** @type {true} */
 pluginCreator.postcss = true;
 
-export default /** @type import('postcss').PluginCreator<PluginOptions>*/ (
+export default /** @type import('postcss').PluginCreator<PostCssCalcOptions>*/ (
   pluginCreator
 );
 export { pluginCreator as 'module.exports' };

package/src/lib/node.js

@@ -5,7 +5,9 @@
 //     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 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).
 //   - A Sum/Product with one positive element collapses to that element.
 //   - A Sum/Product with no elements collapses to Num(0) / Num(1).
@@ -18,7 +20,7 @@
  * @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 {{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 {Num | Dim | Ident | Call | Sum | Product} Node
@@ -85,7 +87,7 @@ function mkSum(rawTerms) {
 function pushSumTerm(out, term) {
   let { sign, node } = term;
 
-  if (node.type === 'Sum') {
+  if (node.type === 'Sum' && !node.grouped) {
     for (const inner of node.terms) {
       pushSumTerm(out, {
         sign: /** @type {1 | -1} */ (sign * inner.sign),
@@ -170,12 +172,15 @@ function negate(node) {
     return dim(-node.value, node.unit);
   }
   if (node.type === 'Sum') {
-    return mkSum(
+    const result = mkSum(
       node.terms.map((t) => ({
         sign: /** @type {1 | -1} */ (-t.sign),
         node: t.node,
       }))
     );
+    return node.grouped && result.type === 'Sum'
+      ? { ...result, grouped: true }
+      : result;
   }
   // Opaque (Ident, Call, Product): wrap as a single negative-sign term —
   // the only case where sign=-1 remains on a SumTerm.

package/src/lib/parser.js

@@ -1,7 +1,7 @@
 // Pratt parser. +/- emit Sum nodes; */÷ emit Product nodes. node.js
-// constructors flatten and normalize on construction, so the parser
-// never produces a Binary node.
-import { mkSum, mkProduct, negate } from './node.js';
+// constructors flatten and normalize on construction, while parenthesized
+// sums retain a grouping marker for the opaque-subtraction invariant.
+import { mkSum, mkProduct, negate, ident, call } from './node.js';
 
 /**
  * @typedef {import('./tokenizer.js').Token} Token
@@ -30,7 +30,7 @@ function foldCalcKeyword(name) {
   // form arrives as a single ident because CSS Syntax tokenizes leading
   // `-` + ident-start as one ident-token.
   if (name === 'NaN' || name === '-NaN') {
-    return { type: 'Num', value: NaN };
+    return { type: 'Num', value: Number.NaN };
   }
   switch (name.toLowerCase()) {
     case 'pi':
@@ -174,7 +174,7 @@ function parseOpaqueCall(p, name) {
   const flush = () => {
     const trimmed = buf.trim();
     if (trimmed) {
-      args.push({ type: 'Ident', name: trimmed });
+      args.push(ident(trimmed));
     }
     buf = '';
   };
@@ -191,7 +191,7 @@ function parseOpaqueCall(p, name) {
         if (depth === 0) {
           p.next();
           flush();
-          return { type: 'Call', name, args };
+          return call(name, args);
         }
       } else if (tk.value === ',' && depth === 1) {
         p.next();
@@ -228,12 +228,12 @@ function requireSurroundingWs(p, token) {
 
 /** @type {Record<string, PrefixParselet>} */
 const PREFIX = {
-  number: (_p, t) => ({ type: 'Num', value: parseFloat(t.value) }),
+  number: (_p, t) => ({ type: 'Num', value: Number.parseFloat(t.value) }),
 
   // Unit case normalization per §10.12: `1PX` serializes as `1px`.
   dimension: (_p, t) => ({
     type: 'Dim',
-    value: parseFloat(t.value),
+    value: Number.parseFloat(t.value),
     unit: t.unit === '%' ? '%' : /** @type {string} */ (t.unit).toLowerCase(),
   }),
 
@@ -254,19 +254,19 @@ const PREFIX = {
         }
       }
       p.expect('punct', ')');
-      return { type: 'Call', name: t.value, args };
+      return call(t.value, args);
     }
     const kw = foldCalcKeyword(t.value);
     if (kw) {
       return kw;
     }
-    return { type: 'Ident', name: t.value };
+    return ident(t.value);
   },
 
   '(': (p) => {
     const e = p.parseExpr(0);
     p.expect('punct', ')');
-    return e;
+    return e.type === 'Sum' ? { ...e, grouped: true } : e;
   },
 
   '-': (p) => negate(p.parseExpr(UNARY_BP)),

package/src/lib/serialize.js

@@ -45,7 +45,7 @@ function round(v, prec) {
  * @return {boolean}
  */
 function isDegenerate(v) {
-  return !isFinite(v) || isNaN(v);
+  return !Number.isFinite(v) || Number.isNaN(v);
 }
 
 /**
@@ -53,7 +53,7 @@ function isDegenerate(v) {
  * @return {string}
  */
 function degenerateKeyword(v) {
-  if (isNaN(v)) {
+  if (Number.isNaN(v)) {
     return 'NaN';
   }
   return v > 0 ? 'infinity' : '-infinity';
@@ -77,6 +77,25 @@ function serialize(node, opts = {}) {
     return `${calcName}(${degenerateKeyword(node.value)} * 1${node.unit})`;
   }
 
+  // A grouped sum with a leading negative term is the canonical result of
+  // negating a parenthesized expression. Re-invert its terms for the body so
+  // the grouping survives as `-(...)` instead of becoming `-a - b`.
+  if (
+    node.type === 'Sum' &&
+    node.grouped &&
+    node.terms.length > 1 &&
+    displaySign(node.terms[0]).sign === -1
+  ) {
+    const body = /** @type {Sum} */ ({
+      type: 'Sum',
+      terms: node.terms.map((t) => ({
+        sign: /** @type {1 | -1} */ (-t.sign),
+        node: t.node,
+      })),
+    });
+    return `${calcName}(-(${serializeExpr(body, prec)}))`;
+  }
+
   if (
     node.type === 'Num' ||
     node.type === 'Dim' ||
@@ -141,13 +160,13 @@ function serializeExpr(node, prec) {
  */
 function displaySign(term) {
   const { sign, node } = term;
-  if (node.type === 'Num' && isFinite(node.value) && node.value < 0) {
+  if (node.type === 'Num' && Number.isFinite(node.value) && node.value < 0) {
     return {
       sign: /** @type {1 | -1} */ (-sign),
       magnitude: { type: 'Num', value: -node.value },
     };
   }
-  if (node.type === 'Dim' && isFinite(node.value) && node.value < 0) {
+  if (node.type === 'Dim' && Number.isFinite(node.value) && node.value < 0) {
     return {
       sign: /** @type {1 | -1} */ (-sign),
       magnitude: { type: 'Dim', value: -node.value, unit: node.unit },
@@ -166,13 +185,21 @@ function serializeSum(sum, prec) {
   for (const [i, t] of sum.terms.entries()) {
     const { sign, magnitude } = displaySign(t);
     if (i === 0) {
+      if (magnitude.type === 'Sum' && magnitude.grouped) {
+        const body = `(${serializeExpr(magnitude, prec)})`;
+        out = sign === 1 ? body : `-${body}`;
+        continue;
+      }
       out =
         sign === 1
           ? serializeExpr(magnitude, prec)
           : serializeLeadingNeg(magnitude, prec);
     } else {
       // `-` binds looser than `*`/`/` so the right side never needs parens.
-      const body = serializeExpr(magnitude, prec);
+      let body = serializeExpr(magnitude, prec);
+      if (magnitude.type === 'Sum' && magnitude.grouped) {
+        body = `(${body})`;
+      }
       out += sign === 1 ? ` + ${body}` : ` - ${body}`;
     }
   }
@@ -192,7 +219,7 @@ function serializeLeadingNeg(node, prec) {
     node.factors.length > 0 &&
     node.factors[0].exponent === 1 &&
     node.factors[0].node.type === 'Num' &&
-    isFinite(node.factors[0].node.value) &&
+    Number.isFinite(node.factors[0].node.value) &&
     node.factors[0].node.value !== 0
   ) {
     const head = node.factors[0].node;

package/src/lib/simplify/abs.js

@@ -1,4 +1,4 @@
-import { num, dim } from '../node.js';
+import { num, dim, call } from '../node.js';
 
 /** @typedef {import('../node.js').Node} Node */
 
@@ -8,7 +8,7 @@ import { num, dim } from '../node.js';
  */
 function simplifyAbs(args) {
   if (args.length !== 1) {
-    return { type: 'Call', name: 'abs', args };
+    return call('abs', args);
   }
   const a = args[0];
   if (a.type === 'Num') {
@@ -17,7 +17,7 @@ function simplifyAbs(args) {
   if (a.type === 'Dim' && a.unit !== '%') {
     return dim(Math.abs(a.value), a.unit);
   }
-  return { type: 'Call', name: 'abs', args: [a] };
+  return call('abs', [a]);
 }
 
 export { simplifyAbs };

package/src/lib/simplify/atan2.js

@@ -1,7 +1,7 @@
 /* §10.4 — atan2. foldConstArgs already rejects percentages (property-
  context-resolved) and enforces shared base + static convertibility. */
 
-import { num, dim } from '../node.js';
+import { num, dim, call } from '../node.js';
 import { foldConstArgs } from './fold.js';
 
 /** @typedef {import('../node.js').Node} Node */
@@ -12,16 +12,16 @@ import { foldConstArgs } from './fold.js';
  */
 function simplifyAtan2(args) {
   if (args.length !== 2) {
-    return { type: 'Call', name: 'atan2', args };
+    return call('atan2', args);
   }
   const fold = foldConstArgs(args);
   if (fold === null) {
-    return { type: 'Call', name: 'atan2', args };
+    return call('atan2', args);
   }
   const [y, x] = /** @type {[number, number]} */ (fold.values);
   const radians = Math.atan2(y, x);
-  if (isNaN(radians)) {
-    return num(NaN);
+  if (Number.isNaN(radians)) {
+    return num(Number.NaN);
   }
   return dim((radians * 180) / Math.PI, 'deg');
 }

package/src/lib/simplify/call.js

@@ -16,9 +16,51 @@ import { simplifyExp } from './exp.js';
 import { simplifyLog } from './log.js';
 import { simplifyHypot } from './hypot.js';
 
+import { call } from '../node.js';
+
 /** @typedef {import('../node.js').Node} Node */
 /** @typedef {import('../simplify.js').SimplifyFn} SimplifyFn */
 
+/** @typedef {(name: string, args: Node[]) => Node} MathSimplifier */
+
+// Bare CSS math functions with implemented simplification semantics, keyed
+// by lowercase name. calc() and its vendor-prefixed forms are handled
+// separately as wrappers in simplifyCall. This map is the single source of
+// truth for both dispatch and `isSupportedMathFunction`.
+/** @type {Map<string, MathSimplifier>} */
+const MATH_SIMPLIFIERS = new Map([
+  ['min', simplifyMinMax],
+  ['max', simplifyMinMax],
+  ['clamp', (_name, args) => simplifyClamp(args)],
+  ['abs', (_name, args) => simplifyAbs(args)],
+  ['sign', (_name, args) => simplifySign(args)],
+  ['mod', (_name, args) => simplifyModRem('mod', args)],
+  ['rem', (_name, args) => simplifyModRem('rem', args)],
+  ['round', (_name, args) => simplifyRound(args)],
+  ['sin', (_name, args) => simplifyTrig('sin', args)],
+  ['cos', (_name, args) => simplifyTrig('cos', args)],
+  ['tan', (_name, args) => simplifyTrig('tan', args)],
+  ['asin', (_name, args) => simplifyInverseTrig('asin', args)],
+  ['acos', (_name, args) => simplifyInverseTrig('acos', args)],
+  ['atan', (_name, args) => simplifyInverseTrig('atan', args)],
+  ['atan2', (_name, args) => simplifyAtan2(args)],
+  ['pow', (_name, args) => simplifyPow(args)],
+  ['sqrt', (_name, args) => simplifySqrt(args)],
+  ['hypot', (_name, args) => simplifyHypot(args)],
+  ['log', (_name, args) => simplifyLog(args)],
+  ['exp', (_name, args) => simplifyExp(args)],
+]);
+
+/**
+ * Whether a bare CSS math function has an implemented simplifier.
+ *
+ * @param {string} name
+ * @return {boolean}
+ */
+function isSupportedMathFunction(name) {
+  return MATH_SIMPLIFIERS.has(name.toLowerCase());
+}
+
 /**
  * @param {Extract<Node, { type: 'Call' }>} node
  * @param {SimplifyFn} simplify
@@ -36,50 +78,17 @@ function simplifyCall(node, simplify) {
 
   const args = node.args.map((a) => simplify(a));
 
-  if (name === 'min' || name === 'max') {
-    return simplifyMinMax(node.name, args);
-  }
-  if (name === 'clamp') {
-    return simplifyClamp(args);
-  }
-  if (name === 'abs') {
-    return simplifyAbs(args);
-  }
-  if (name === 'sign') {
-    return simplifySign(args);
-  }
-  if (name === 'mod' || name === 'rem') {
-    return simplifyModRem(name, args);
-  }
-  if (name === 'round') {
-    return simplifyRound(args);
-  }
-  if (name === 'sin' || name === 'cos' || name === 'tan') {
-    return simplifyTrig(name, args);
-  }
-  if (name === 'asin' || name === 'acos' || name === 'atan') {
-    return simplifyInverseTrig(name, args);
-  }
-  if (name === 'atan2') {
-    return simplifyAtan2(args);
-  }
-  if (name === 'pow') {
-    return simplifyPow(args);
-  }
-  if (name === 'sqrt') {
-    return simplifySqrt(args);
-  }
-  if (name === 'hypot') {
-    return simplifyHypot(args);
-  }
-  if (name === 'log') {
-    return simplifyLog(args);
-  }
-  if (name === 'exp') {
-    return simplifyExp(args);
+  const simplifier = MATH_SIMPLIFIERS.get(name);
+  if (simplifier) {
+    // min/max preserve the call's original casing in their opaque-args
+    // fallback; the rest normalize to lowercase internally.
+    return simplifier(
+      name === 'min' || name === 'max' ? node.name : name,
+      args
+    );
   }
 
-  return { type: 'Call', name: node.name, args };
+  return call(node.name, args);
 }
 
-export { simplifyCall };
+export { isSupportedMathFunction, simplifyCall };

package/src/lib/simplify/clamp.js

@@ -1,4 +1,4 @@
-import { num, dim } from '../node.js';
+import { num, dim, call } from '../node.js';
 import { foldConstArgs } from './fold.js';
 
 /** @typedef {import('../node.js').Node} Node */
@@ -18,7 +18,7 @@ function simplifyClamp(args) {
       return fold.unit === '' ? num(clamped) : dim(clamped, fold.unit);
     }
   }
-  return { type: 'Call', name: 'clamp', args };
+  return call('clamp', args);
 }
 
 export { simplifyClamp };

package/src/lib/simplify/exp.js

@@ -1,4 +1,4 @@
-import { num } from '../node.js';
+import { num, call } from '../node.js';
 
 /** @typedef {import('../node.js').Node} Node */
 
@@ -8,7 +8,7 @@ import { num } from '../node.js';
  */
 function simplifyExp(args) {
   if (args.length !== 1 || args[0].type !== 'Num') {
-    return { type: 'Call', name: 'exp', args };
+    return call('exp', args);
   }
   return num(Math.exp(args[0].value));
 }

package/src/lib/simplify/hypot.js

@@ -1,6 +1,6 @@
 // §10.5 — hypot. Empty args return null from foldConstArgs naturally.
 
-import { num, dim } from '../node.js';
+import { num, dim, call } from '../node.js';
 import { foldConstArgs } from './fold.js';
 
 /** @typedef {import('../node.js').Node} Node */
@@ -12,7 +12,7 @@ import { foldConstArgs } from './fold.js';
 function simplifyHypot(args) {
   const fold = foldConstArgs(args);
   if (fold === null) {
-    return { type: 'Call', name: 'hypot', args };
+    return call('hypot', args);
   }
   const sumSq = fold.values.reduce((acc, v) => acc + v * v, 0);
   const result = Math.sqrt(sumSq);

package/src/lib/simplify/inverse-trig.js

@@ -1,6 +1,6 @@
 // §10.4 — asin/acos/atan. Bare <number> in, <angle> in degrees out.
 
-import { num, dim } from '../node.js';
+import { num, dim, call } from '../node.js';
 
 /** @typedef {import('../node.js').Node} Node */
 
@@ -17,15 +17,15 @@ const INVERSE_TRIG_OPS = /** @type {const} */ ({
  */
 function simplifyInverseTrig(name, args) {
   if (args.length !== 1) {
-    return { type: 'Call', name, args };
+    return call(name, args);
   }
   const a = args[0];
   if (a.type !== 'Num') {
-    return { type: 'Call', name, args };
+    return call(name, args);
   }
   const radians = INVERSE_TRIG_OPS[name](a.value);
-  if (isNaN(radians)) {
-    return num(NaN);
+  if (Number.isNaN(radians)) {
+    return num(Number.NaN);
   }
   return dim((radians * 180) / Math.PI, 'deg');
 }

package/src/lib/simplify/log.js

@@ -1,4 +1,4 @@
-import { num } from '../node.js';
+import { num, call } from '../node.js';
 
 /** @typedef {import('../node.js').Node} Node */
 
@@ -13,7 +13,7 @@ function simplifyLog(args) {
   if (args.length === 2 && args[0].type === 'Num' && args[1].type === 'Num') {
     return num(Math.log(args[0].value) / Math.log(args[1].value));
   }
-  return { type: 'Call', name: 'log', args };
+  return call('log', args);
 }
 
 export { simplifyLog };

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

@@ -1,4 +1,4 @@
-import { num, dim } from '../node.js';
+import { num, dim, call } from '../node.js';
 import { foldConstArgs } from './fold.js';
 
 /** @typedef {import('../node.js').Node} Node */
@@ -15,7 +15,7 @@ function simplifyMinMax(name, args) {
     const value = fn(...fold.values);
     return fold.unit === '' ? num(value) : dim(value, fold.unit);
   }
-  return { type: 'Call', name, args };
+  return call(name, args);
 }
 
 export { simplifyMinMax };

package/src/lib/simplify/mod-rem.js

@@ -1,4 +1,4 @@
-import { num, dim } from '../node.js';
+import { num, dim, call } from '../node.js';
 import { foldConstArgs } from './fold.js';
 
 /** @typedef {import('../node.js').Node} Node */
@@ -10,18 +10,18 @@ import { foldConstArgs } from './fold.js';
  */
 function simplifyModRem(name, args) {
   if (args.length !== 2) {
-    return { type: 'Call', name, args };
+    return call(name, args);
   }
   const fold = foldConstArgs(args);
   if (fold === null) {
-    return { type: 'Call', name, args };
+    return call(name, args);
   }
   const [a, b] = /** @type {[number, number]} */ (fold.values);
   const result = applyModRem(name, a, b);
   // NaN results drop the unit (`mod(5px, 0px)` → `calc(NaN)`, not
   // `calc(NaN * 1px)`). §10.12 unit-preserving form is a known divergence.
-  if (isNaN(result)) {
-    return num(NaN);
+  if (Number.isNaN(result)) {
+    return num(Number.NaN);
   }
   return fold.unit === '' ? num(result) : dim(result, fold.unit);
 }
@@ -34,16 +34,16 @@ function simplifyModRem(name, args) {
  */
 function applyModRem(name, a, b) {
   if (b === 0) {
-    return NaN;
+    return Number.NaN;
   }
-  if (!isFinite(a)) {
-    return NaN;
+  if (!Number.isFinite(a)) {
+    return Number.NaN;
   }
-  if (!isFinite(b)) {
+  if (!Number.isFinite(b)) {
     // mod: result is NaN when A has opposite sign to B; otherwise A.
     // rem: result is A regardless of signs.
     if (name === 'mod' && a !== 0 && Math.sign(a) !== Math.sign(b)) {
-      return NaN;
+      return Number.NaN;
     }
     return a;
   }

package/src/lib/simplify/pow.js

@@ -1,6 +1,6 @@
 // §10.5 — pow is <number>-only.
 
-import { num } from '../node.js';
+import { num, call } from '../node.js';
 
 /** @typedef {import('../node.js').Node} Node */
 
@@ -10,7 +10,7 @@ import { num } from '../node.js';
  */
 function simplifyPow(args) {
   if (args.length !== 2 || args[0].type !== 'Num' || args[1].type !== 'Num') {
-    return { type: 'Call', name: 'pow', args };
+    return call('pow', args);
   }
   return num(Math.pow(args[0].value, args[1].value));
 }

package/src/lib/simplify/round.js

@@ -1,4 +1,4 @@
-import { num, dim } from '../node.js';
+import { num, dim, ident, call } from '../node.js';
 import { foldConstArgs } from './fold.js';
 
 /** @typedef {import('../node.js').Node} Node */
@@ -18,21 +18,15 @@ function simplifyRound(args) {
     const n = first.name.toLowerCase();
     if (!ROUND_STRATEGIES.has(n)) {
       // Unrecognized strategy ident — opaque rather than guessing intent.
-      return { type: 'Call', name: 'round', args };
+      return call('round', args);
     }
     strategy = /** @type {RoundStrategy} */ (n);
     rest = args.slice(1);
   }
 
   /** @type {() => Node} */
-  const passthrough = () => ({
-    type: 'Call',
-    name: 'round',
-    args:
-      strategy === 'nearest'
-        ? rest
-        : [{ type: 'Ident', name: strategy }, ...rest],
-  });
+  const passthrough = () =>
+    call('round', strategy === 'nearest' ? rest : [ident(strategy), ...rest]);
 
   // B omitted: defaults to 1 when A is <number>; else opaque.
   const argsForFold = argsForRoundFold(rest);
@@ -49,12 +43,12 @@ function simplifyRound(args) {
   // case folds to ±0 carrying A's sign. Infinite-A / finite-B falls through
   // to applyRound, where floor*b===ceil*b===±∞ collapses back to A
   // (§10.3.1 "result is the same infinity").
-  if (isNaN(b)) {
-    return num(NaN);
+  if (Number.isNaN(b)) {
+    return num(Number.NaN);
   }
-  if (!isFinite(b)) {
-    if (!isFinite(a)) {
-      return num(NaN);
+  if (!Number.isFinite(b)) {
+    if (!Number.isFinite(a)) {
+      return num(Number.NaN);
     }
     let result;
     if (strategy === 'up' && a > 0) {
@@ -68,8 +62,8 @@ function simplifyRound(args) {
   }
 
   const result = applyRound(strategy, a, b);
-  if (isNaN(result)) {
-    return num(NaN);
+  if (Number.isNaN(result)) {
+    return num(Number.NaN);
   }
   return fold.unit === '' ? num(result) : dim(result, fold.unit);
 }
@@ -96,7 +90,7 @@ function argsForRoundFold(args) {
  */
 function applyRound(strategy, a, b) {
   if (b === 0) {
-    return NaN;
+    return Number.NaN;
   }
   const q = a / b;
   const c1 = Math.floor(q) * b;

package/src/lib/simplify/sign.js

@@ -1,4 +1,4 @@
-import { num } from '../node.js';
+import { num, call } from '../node.js';
 
 /** @typedef {import('../node.js').Node} Node */
 
@@ -8,7 +8,7 @@ import { num } from '../node.js';
  */
 function simplifySign(args) {
   if (args.length !== 1) {
-    return { type: 'Call', name: 'sign', args };
+    return call('sign', args);
   }
   const a = args[0];
   if (a.type === 'Num') {
@@ -18,7 +18,7 @@ function simplifySign(args) {
   if (a.type === 'Dim' && a.unit !== '%') {
     return num(Math.sign(a.value));
   }
-  return { type: 'Call', name: 'sign', args: [a] };
+  return call('sign', [a]);
 }
 
 export { simplifySign };

package/src/lib/simplify/sqrt.js

@@ -1,4 +1,4 @@
-import { num } from '../node.js';
+import { num, call } from '../node.js';
 
 /** @typedef {import('../node.js').Node} Node */
 /**
@@ -7,7 +7,7 @@ import { num } from '../node.js';
  */
 function simplifySqrt(args) {
   if (args.length !== 1 || args[0].type !== 'Num') {
-    return { type: 'Call', name: 'sqrt', args };
+    return call('sqrt', args);
   }
   return num(Math.sqrt(args[0].value));
 }

package/src/lib/simplify/sum.js

@@ -48,6 +48,17 @@ function simplifySum(sum, simplify) {
    */
   function processTerm(sign, n) {
     if (n.type === 'Sum') {
+      // Parentheses around a sum are normally algebraically disposable. Keep
+      // them only for an opaque sum used negatively: distributing that sign
+      // changes the CSS value when a var() contains a sum of its own.
+      if (
+        n.grouped &&
+        sign === -1 &&
+        n.terms.some((t) => t.node.type !== 'Num' && t.node.type !== 'Dim')
+      ) {
+        opaque.push({ sign, node: n });
+        return;
+      }
       for (const inner of n.terms) {
         processTerm(/** @type {1 | -1} */ (sign * inner.sign), inner.node);
       }
@@ -95,7 +106,13 @@ function simplifySum(sum, simplify) {
   }
   terms.push(...opaque);
 
-  return mkSum(terms);
+  const result = mkSum(terms);
+  // Keep the source grouping available to an enclosing subtraction. Numeric
+  // groups have already folded and therefore do not need the marker.
+  if (sum.grouped && result.type === 'Sum' && opaque.length > 0) {
+    return { ...result, grouped: true };
+  }
+  return result;
 }
 
 export { simplifySum };

package/src/lib/simplify/trig.js

@@ -1,6 +1,6 @@
 // §10.4 — sin/cos/tan. <number> is radians; <angle> dim is converted.
 
-import { num } from '../node.js';
+import { num, call } from '../node.js';
 import { baseOf, convert } from '../convertUnits.js';
 
 /** @typedef {import('../node.js').Node} Node */
@@ -18,7 +18,7 @@ const TRIG_OPS = /** @type {const} */ ({
  */
 function simplifyTrig(name, args) {
   if (args.length !== 1) {
-    return { type: 'Call', name, args };
+    return call(name, args);
   }
   const a = args[0];
   /** @type {number | null} */ let radians = null;
@@ -36,7 +36,7 @@ function simplifyTrig(name, args) {
     }
   }
   if (radians === null) {
-    return { type: 'Call', name, args };
+    return call(name, args);
   }
   return num(TRIG_OPS[name](radians));
 }

package/types/index.d.ts

@@ -1,6 +1,5 @@
-export type PluginOptions = {
+export type PostCssCalcOptions = {
     precision?: number | false;
-    preserve?: boolean;
     warnWhenCannotResolve?: boolean;
     mediaQueries?: boolean;
     selectors?: boolean;
@@ -9,15 +8,21 @@ export type PluginOptions = {
      */
     onParseError?: (error: Error, input: string) => void;
 };
-export type ResolvedOptions = Required<Omit<PluginOptions, 'onParseError'>> & Pick<PluginOptions, 'onParseError'>;
+export type ResolvedOptions = Required<Omit<PostCssCalcOptions, 'onParseError'>> & Pick<PostCssCalcOptions, 'onParseError'>;
+export type TransformContext = {
+    options: ResolvedOptions;
+    result: import('postcss').Result;
+    item: import('postcss').ChildNode;
+    value: string;
+};
 /**
- * @param {PluginOptions} [opts]
+ * @param {PostCssCalcOptions} [opts]
  * @return {import('postcss').Plugin}
  */
-declare function pluginCreator(opts?: PluginOptions): import('postcss').Plugin;
+declare function pluginCreator(opts?: PostCssCalcOptions): import('postcss').Plugin;
 declare namespace pluginCreator {
-    var postcss: boolean;
+    var postcss: true;
 }
-declare const _default: import('postcss').PluginCreator<PluginOptions>;
+declare const _default: import('postcss').PluginCreator<PostCssCalcOptions>;
 export default _default;
 export { pluginCreator as 'module.exports' };

package/types/lib/node.d.ts

@@ -23,6 +23,7 @@ export type SumTerm = {
 export type Sum = {
     type: 'Sum';
     terms: SumTerm[];
+    grouped?: boolean;
 };
 export type ProductFactor = {
     exponent: 1 | -1;
@@ -39,7 +40,7 @@ export type Node = Num | Dim | Ident | Call | Sum | Product;
  * @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 {{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 {Num | Dim | Ident | Call | Sum | Product} Node

package/types/lib/simplify/call.d.ts

@@ -1,7 +1,13 @@
 export type Node = import('../node.js').Node;
 export type SimplifyFn = import('../simplify.js').SimplifyFn;
-/** @typedef {import('../node.js').Node} Node */
-/** @typedef {import('../simplify.js').SimplifyFn} SimplifyFn */
+export type MathSimplifier = (name: string, args: Node[]) => Node;
+/**
+ * Whether a bare CSS math function has an implemented simplifier.
+ *
+ * @param {string} name
+ * @return {boolean}
+ */
+declare function isSupportedMathFunction(name: string): boolean;
 /**
  * @param {Extract<Node, { type: 'Call' }>} node
  * @param {SimplifyFn} simplify
@@ -10,4 +16,4 @@ export type SimplifyFn = import('../simplify.js').SimplifyFn;
 declare function simplifyCall(node: Extract<Node, {
     type: 'Call';
 }>, simplify: SimplifyFn): Node;
-export { simplifyCall };
+export { isSupportedMathFunction, simplifyCall };

package/types/lib/type.d.ts

@@ -1,4 +1,11 @@
-export type BaseType = "length" | "angle" | "time" | "frequency" | "resolution" | "flex" | "percentage";
+export type BaseType =
+  | 'length'
+  | 'angle'
+  | 'time'
+  | 'frequency'
+  | 'resolution'
+  | 'flex'
+  | 'percentage';
 /**
  * @param {string} unit
  * @return {BaseType | null}