postcss-calc 11.0.3 → 11.1.0

package/README.md

@@ -13,7 +13,7 @@ statement is left as is, to fallback to the [W3C calc() implementation].
 npm install postcss-calc
 ```
 
-## Usage
+## PostCSS usage
 
 ```js
 // dependencies
@@ -52,6 +52,38 @@ h1 {
 
 Checkout [tests] for more examples.
 
+## Use the reducer without PostCSS
+
+For a single CSS component-value string, import the dedicated reducer entry
+point. It reduces `calc()` and the supported CSS math functions it finds while
+leaving all other text untouched.
+
+```js
+import reduceCalc from 'postcss-calc/reduce';
+
+reduceCalc('calc(1in + 10px)');
+// => '1.10417in'
+
+reduceCalc('min(50px, calc(2 * 40px))');
+// => '50px'
+```
+
+It accepts `precision`, `warnWhenCannotResolve`, `onParseError`, and `onWarn`:
+
+```js
+const result = reduceCalc('calc(100% + var(--gap))', {
+  precision: false,
+  warnWhenCannotResolve: true,
+  onWarn: console.warn,
+  onParseError(error, input) {
+    console.error(`Invalid calculation: ${input}`, error);
+  },
+});
+```
+
+Unlike the PostCSS plugin, the standalone reducer does not show warnings
+by default; provide `onParseError` and/or `onWarn` if you want diagnostics.
+
 ### Options
 
 #### `precision` (default: `5`)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "postcss-calc",
-  "version": "11.0.3",
+  "version": "11.1.0",
   "type": "module",
   "description": "PostCSS plugin to reduce calc()",
   "keywords": [
@@ -19,6 +19,10 @@
     ".": {
       "types": "./types/index.d.ts",
       "default": "./src/index.js"
+    },
+    "./reduce": {
+      "types": "./types/reduce.d.ts",
+      "default": "./src/reduce.js"
     }
   },
   "files": [
@@ -40,18 +44,18 @@
   "devDependencies": {
     "@csstools/css-calc": "^3.3.0",
     "@rmenke/css-tokenizer-tests": "^1.2.0",
-    "@types/node": "^26.4.0",
+    "@types/node": "^26.4.1",
     "fast-check": "^4.9.0",
-    "oxfmt": "^0.65.0",
-    "oxlint": "^1.80.0",
-    "postcss": "^8.5.26",
+    "oxfmt": "^0.66.0",
+    "oxlint": "^1.81.0",
+    "postcss": "^8.5.28",
     "typescript": "~7.0.2"
   },
   "dependencies": {
     "@csstools/css-tokenizer": "^4.0.0"
   },
   "peerDependencies": {
-    "postcss": "^8.5.25"
+    "postcss": "^8.5.28"
   },
   "scripts": {
     "lint": "oxlint . && tsc && oxfmt --check",

package/src/index.js

@@ -1,23 +1,5 @@
-// 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 {
-  tokenize as cssTokenize,
-  TokenType as CssType,
-} from '@csstools/css-tokenizer';
-import { tokenizeTokens } 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;
-
-const BLOCK_CLOSE = new Map([
-  [CssType.OpenParen, CssType.CloseParen],
-  [CssType.OpenSquare, CssType.CloseSquare],
-  [CssType.OpenCurly, CssType.CloseCurly],
-]);
+// PostCSS adapter over the standalone component-value reducer.
+import reduceCalc, { hasPotentialMathFunction } from './reduce.js';
 
 /**
  * @typedef {object} PostCssCalcOptions
@@ -31,144 +13,7 @@ const BLOCK_CLOSE = new Map([
 /** @typedef {Required<Omit<PostCssCalcOptions, 'onParseError'>> & Pick<PostCssCalcOptions, 'onParseError'>} ResolvedOptions */
 
 /**
- * Fields threaded unchanged through the token-range 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
- * @property {import('@csstools/css-tokenizer').CSSToken[]} tokens
- * @property {Replacement[]} replacements
- */
-
-/**
- * @typedef {object} Replacement
- * @property {number} start
- * @property {number} end
- * @property {import('./lib/node.js').Node} node
- * @property {string} calcName
- * @property {string} matchedName
- */
-
-/**
- * Walk one component-value level. Unsupported functions and simple blocks are
- * traversed, while a supported function is treated as one opaque calculation
- * even when parsing it fails. A missing closer consumes through EOF, matching
- * CSS component-value parsing's error recovery.
- *
- * @param {number} start
- * @param {import('@csstools/css-tokenizer').TokenType | undefined} expectedClose
- * @param {TransformContext} ctx
- * @param {boolean} transform
- * @return {number} Index of the matching closer, or the EOF token.
- */
-function walkTokens(start, expectedClose, ctx, transform) {
-  for (let i = start; i < ctx.tokens.length; i++) {
-    const token = ctx.tokens[i];
-    if (token[0] === CssType.EOF || token[0] === expectedClose) {
-      return i;
-    }
-
-    const blockClose = BLOCK_CLOSE.get(token[0]);
-    if (blockClose) {
-      i = walkTokens(i + 1, blockClose, ctx, transform);
-      continue;
-    }
-
-    if (token[0] !== CssType.Function) {
-      continue;
-    }
-
-    const name = token[4].value;
-    const isCalc = MATCH_CALC.test(name);
-    const isMath = !isCalc && isSupportedMathFunction(name);
-    if (!transform || (!isCalc && !isMath)) {
-      i = walkTokens(i + 1, CssType.CloseParen, ctx, transform);
-      continue;
-    }
-
-    // Locate the complete outer function without transforming its children.
-    const close = walkTokens(i + 1, CssType.CloseParen, ctx, false);
-    const closed = ctx.tokens[close][0] === CssType.CloseParen;
-    const end = closed ? ctx.tokens[close][3] + 1 : ctx.value.length;
-    const sliceStart = isCalc ? i + 1 : i;
-    const sliceEnd = closed ? close + (isCalc ? 0 : 1) : close;
-    const inputStart = isCalc ? token[3] + 1 : token[2];
-    const inputEnd = closed && isCalc ? ctx.tokens[close][2] : end;
-    const contents = ctx.value.slice(inputStart, inputEnd);
-    try {
-      const node = simplify(
-        parse(tokenizeTokens(ctx.tokens.slice(sliceStart, sliceEnd), end))
-      );
-      ctx.replacements.push({
-        start: token[2],
-        end,
-        node,
-        calcName: isCalc ? name : 'calc',
-        matchedName: name,
-      });
-    } 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 });
-      }
-    }
-    i = close;
-  }
-
-  return ctx.tokens.length - 1;
-}
-
-/**
- * @param {string} value
- * @param {ResolvedOptions} options
- * @param {import('postcss').Result} result
- * @param {import('postcss').ChildNode} item
- * @return {string}
- */
-function transformValue(value, options, result, item) {
-  const tokens = cssTokenize({ css: value });
-  /** @type {Replacement[]} */
-  const replacements = [];
-  const ctx = { options, result, item, value, tokens, replacements };
-  walkTokens(0, undefined, ctx, true);
-
-  /** @type {(Replacement & {text: string})[]} */
-  const serialized = replacements.map((replacement) => {
-    const text = serialize(replacement.node, {
-      precision: options.precision,
-      calcName: replacement.calcName,
-    });
-    if (
-      options.warnWhenCannotResolve &&
-      text.startsWith(`${replacement.matchedName}(`)
-    ) {
-      result.warn('Could not reduce expression: ' + value, {
-        plugin: 'postcss-calc',
-        node: item,
-      });
-    }
-    return { ...replacement, text };
-  });
-
-  let output = value;
-  for (let i = serialized.length - 1; i >= 0; i--) {
-    const replacement = serialized[i];
-    output =
-      output.slice(0, replacement.start) +
-      replacement.text +
-      output.slice(replacement.end);
-  }
-  return output;
-}
-
-/**
- * Runs `transformValue` over one text property of a decl/atrule/rule node
+ * Runs `reduceCalc` 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
@@ -182,7 +27,24 @@ function transformValue(value, options, result, item) {
  * @return {void}
  */
 function applyTransform(node, current, setProp, options, result) {
-  setProp(node, transformValue(current, options, result, node));
+  if (!hasPotentialMathFunction(current)) {
+    return;
+  }
+  const transformed = reduceCalc(current, {
+    precision: options.precision,
+    warnWhenCannotResolve: options.warnWhenCannotResolve,
+    onParseError:
+      options.onParseError ??
+      ((error) => {
+        result.warn(error.message, { node });
+      }),
+    onWarn: (message) => {
+      result.warn(message, { plugin: 'postcss-calc', node });
+    },
+  });
+  if (transformed !== current) {
+    setProp(node, transformed);
+  }
 }
 
 /**

package/src/lib/node.js

@@ -71,7 +71,7 @@ function mkSum(rawTerms) {
     pushSumTerm(flat, t);
   }
   if (flat.length === 0) {
-    return { type: 'Num', value: 0 };
+    return num(0);
   }
   if (flat.length === 1 && flat[0].sign === 1) {
     return flat[0].node;
@@ -101,10 +101,10 @@ function pushSumTerm(out, term) {
   // canonical-form rule downstream code relies on.
   if (sign === -1) {
     if (node.type === 'Num') {
-      node = { type: 'Num', value: -node.value };
+      node = num(-node.value);
       sign = 1;
     } else if (node.type === 'Dim') {
-      node = { type: 'Dim', value: -node.value, unit: node.unit };
+      node = dim(-node.value, node.unit);
       sign = 1;
     }
   }
@@ -128,7 +128,7 @@ function mkProduct(rawFactors) {
     pushProductFactor(flat, f);
   }
   if (flat.length === 0) {
-    return { type: 'Num', value: 1 };
+    return num(1);
   }
   if (flat.length === 1 && flat[0].exponent === 1) {
     return flat[0].node;
@@ -184,7 +184,7 @@ function negate(node) {
   }
   // Opaque (Ident, Call, Product): wrap as a single negative-sign term —
   // the only case where sign=-1 remains on a SumTerm.
-  return { type: 'Sum', terms: [{ sign: -1, node }] };
+  return mkSum([{ sign: -1, node }]);
 }
 
 export { num, dim, ident, call, mkSum, mkProduct, negate };

package/src/lib/parser.js

@@ -10,15 +10,6 @@ import { mkSum, mkProduct, negate, num, dim, ident, call } from './node.js';
  * @typedef {(p: Parser, token: Token) => Node} PrefixParselet
  */
 
-/**
- * @param {Token} t
- * @param {string} value
- * @return {boolean}
- */
-function isPunct(t, value) {
-  return t.type === 'punct' && t.value === value;
-}
-
 /**
  * §10.9 — case-insensitive except for NaN.
  * @param {string} name
@@ -81,6 +72,39 @@ class Parser {
     return t;
   }
 
+  /**
+   * @param {string} value
+   * @param {string} [value2]
+   * @return {boolean}
+   */
+  isPunct(value, value2) {
+    const t = this.peek();
+    return (
+      t.type === 'punct' &&
+      (t.value === value || (value2 !== undefined && t.value === value2))
+    );
+  }
+
+  /**
+   * @param {string} value
+   * @return {boolean}
+   */
+  matchPunct(value) {
+    if (this.isPunct(value)) {
+      this.next();
+      return true;
+    }
+    return false;
+  }
+
+  /**
+   * @param {string} value
+   * @return {Token}
+   */
+  expectPunct(value) {
+    return this.expect('punct', value);
+  }
+
   /**
    * @param {number} [minBp]
    * @return {Node}
@@ -111,14 +135,7 @@ class Parser {
             sign: /** @type {1 | -1} */ (token.value === '+' ? 1 : -1),
             node: this.parseExpr(ADD_BP + 1),
           });
-          const next = this.peek();
-          if (
-            next.type !== 'punct' ||
-            (next.value !== '+' && next.value !== '-')
-          ) {
-            break;
-          }
-        } while (ADD_BP >= minBp);
+        } while (this.isPunct('+', '-'));
         left = mkSum(terms);
         continue;
       }
@@ -132,14 +149,7 @@ class Parser {
             exponent: /** @type {1 | -1} */ (token.value === '*' ? 1 : -1),
             node: this.parseExpr(MUL_BP + 1),
           });
-          const next = this.peek();
-          if (
-            next.type !== 'punct' ||
-            (next.value !== '*' && next.value !== '/')
-          ) {
-            break;
-          }
-        } while (MUL_BP >= minBp);
+        } while (this.isPunct('*', '/'));
         left = mkProduct(factors);
         continue;
       }
@@ -255,22 +265,19 @@ const PREFIX = {
     ),
 
   ident: (p, t) => {
-    const nxt = p.peek();
-    if (nxt.type === 'punct' && nxt.value === '(') {
-      p.next();
+    if (p.matchPunct('(')) {
       if (OPAQUE_ARG_FUNCTIONS.has(t.value.toLowerCase())) {
         return parseOpaqueCall(p, t.value);
       }
       /** @type {Node[]} */
       const args = [];
-      if (!isPunct(p.peek(), ')')) {
+      if (!p.isPunct(')')) {
         args.push(p.parseExpr(0));
-        while (isPunct(p.peek(), ',')) {
-          p.next();
+        while (p.matchPunct(',')) {
           args.push(p.parseExpr(0));
         }
       }
-      p.expect('punct', ')');
+      p.expectPunct(')');
       return call(t.value, args);
     }
     const kw = foldCalcKeyword(t.value);
@@ -282,7 +289,7 @@ const PREFIX = {
 
   '(': (p) => {
     const e = p.parseExpr(0);
-    p.expect('punct', ')');
+    p.expectPunct(')');
     return e.type === 'Sum' ? { ...e, grouped: true } : e;
   },
 

package/src/lib/serialize.js

@@ -3,6 +3,8 @@
 // arithmetic operator. A Sum inside a Product is the only place parens
 // are ever required on valid canonical input.
 
+import { num, dim } from './node.js';
+
 /**
  * @typedef {import('./node.js').Node} Node
  * @typedef {import('./node.js').Sum} Sum
@@ -105,14 +107,11 @@ function serialize(node, opts = {}) {
     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)}))`;
+    const invertedTerms = node.terms.map((t) => ({
+      sign: /** @type {1 | -1} */ (-t.sign),
+      node: t.node,
+    }));
+    return `${calcName}(-(${serializeSumTerms(invertedTerms, prec)}))`;
   }
 
   if (
@@ -182,27 +181,27 @@ function displaySign(term) {
   if (node.type === 'Num' && Number.isFinite(node.value) && node.value < 0) {
     return {
       sign: /** @type {1 | -1} */ (-sign),
-      magnitude: { type: 'Num', value: -node.value },
+      magnitude: num(-node.value),
     };
   }
   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 },
+      magnitude: dim(-node.value, node.unit),
     };
   }
   return { sign, magnitude: node };
 }
 
 /**
- * @param {Sum} sum
+ * @param {import('./node.js').SumTerm[]} terms
  * @param {number | false} prec
  * @return {string}
  */
-function serializeSum(sum, prec) {
+function serializeSumTerms(terms, prec) {
   let out = '';
-  for (const [i, t] of sum.terms.entries()) {
-    const { sign, magnitude } = displaySign(t);
+  for (let i = 0; i < terms.length; i++) {
+    const { sign, magnitude } = displaySign(terms[i]);
     if (i === 0) {
       if (magnitude.type === 'Sum' && magnitude.grouped) {
         const body = `(${serializeExpr(magnitude, prec)})`;
@@ -225,6 +224,15 @@ function serializeSum(sum, prec) {
   return out;
 }
 
+/**
+ * @param {Sum} sum
+ * @param {number | false} prec
+ * @return {string}
+ */
+function serializeSum(sum, prec) {
+  return serializeSumTerms(sum.terms, prec);
+}
+
 /**
  * Fold a leading negation into a finite leading Num if there is one
  * (`-(0.5 * x)` → `-0.5 * x`); else use `-(…)` for Sum/Product or `-x`.
@@ -249,11 +257,8 @@ function serializeLeadingNeg(node, prec) {
     const negatedFactors =
       negatedValue === 1
         ? rest
-        : [
-            { exponent: 1, node: { type: 'Num', value: negatedValue } },
-            ...rest,
-          ];
-    return serializeProduct({ type: 'Product', factors: negatedFactors }, prec);
+        : [{ exponent: 1, node: num(negatedValue) }, ...rest];
+    return serializeFactors(negatedFactors, prec);
   }
   const body = serializeExpr(node, prec);
   return node.type === 'Sum' || node.type === 'Product'
@@ -262,13 +267,14 @@ function serializeLeadingNeg(node, prec) {
 }
 
 /**
- * @param {Product} product
+ * @param {ProductFactor[]} factors
  * @param {number | false} prec
  * @return {string}
  */
-function serializeProduct(product, prec) {
+function serializeFactors(factors, prec) {
   let out = '';
-  for (const [i, f] of product.factors.entries()) {
+  for (let i = 0; i < factors.length; i++) {
+    const f = factors[i];
     let body = serializeExpr(f.node, prec);
     // A Sum factor needs parens: `a * (b + c)`. Flat canonical form means
     // this is the only place parens are required.
@@ -285,4 +291,13 @@ function serializeProduct(product, prec) {
   return out;
 }
 
+/**
+ * @param {Product} product
+ * @param {number | false} prec
+ * @return {string}
+ */
+function serializeProduct(product, prec) {
+  return serializeFactors(product.factors, prec);
+}
+
 export { serialize };

package/src/lib/simplify/bucket.js

@@ -21,7 +21,7 @@ import { convert } from '../convertUnits.js';
  * @return {UnitBucket[]}
  */
 function mergeConvertibleBuckets(buckets) {
-  const ordered = [...buckets].sort((a, b) => a.order - b.order);
+  const ordered = buckets.sort((a, b) => a.order - b.order);
   /** @type {Set<string>} */ const merged = new Set();
   /** @type {UnitBucket[]} */ const out = [];
   for (const b of ordered) {

package/src/lib/simplify/call.js

@@ -26,7 +26,7 @@ import { call } from '../node.js';
 // 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`.
+// truth for dispatch, `isSupportedMathFunction`, and `QUICK_MATH_TEST`.
 /** @type {Map<string, MathSimplifier>} */
 const MATH_SIMPLIFIERS = new Map([
   ['min', simplifyMinMax],
@@ -51,6 +51,29 @@ const MATH_SIMPLIFIERS = new Map([
   ['exp', (_name, args) => simplifyExp(args)],
 ]);
 
+const mathFnNames = [...MATH_SIMPLIFIERS.keys()].sort(
+  (a, b) => b.length - a.length
+);
+
+const QUICK_MATH_TEST = new RegExp(
+  `(?:-(?:webkit|moz)-)?(?:calc|${mathFnNames.join('|')})\\(`,
+  'i'
+);
+
+/**
+ * Fast check to determine whether a CSS component value could contain
+ * a supported calculation or math function call (or an escape sequence
+ * that could decode to one).
+ *
+ * @param {string} value
+ * @return {boolean}
+ */
+function hasPotentialMathFunction(value) {
+  return (
+    value.includes('(') && (QUICK_MATH_TEST.test(value) || value.includes('\\'))
+  );
+}
+
 /**
  * Whether a bare CSS math function has an implemented simplifier.
  *
@@ -91,4 +114,9 @@ function simplifyCall(node, simplify) {
   return call(node.name, args);
 }
 
-export { isSupportedMathFunction, simplifyCall };
+export {
+  isSupportedMathFunction,
+  simplifyCall,
+  hasPotentialMathFunction,
+  QUICK_MATH_TEST,
+};

package/src/lib/simplify/clamp.js

@@ -1,5 +1,6 @@
-import { num, dim, call } from '../node.js';
-import { foldConstArgs } from './fold.js';
+import { call } from '../node.js';
+import { foldConstArgs, foldResult } from './fold.js';
+import { simplifyMinMax } from './min-max.js';
 
 /** @typedef {import('../node.js').Node} Node */
 
@@ -9,16 +10,37 @@ import { foldConstArgs } from './fold.js';
  */
 function simplifyClamp(args) {
   if (args.length === 3) {
+    const minNone = isNone(args[0]);
+    const maxNone = isNone(args[2]);
+
+    if (minNone && maxNone) {
+      return args[1];
+    }
+    if (minNone) {
+      return simplifyMinMax('min', [args[1], args[2]]);
+    }
+    if (maxNone) {
+      return simplifyMinMax('max', [args[0], args[1]]);
+    }
+
     const fold = foldConstArgs(args);
     if (fold !== null) {
       const [lo, v, hi] = /** @type {[number, number, number]} */ (fold.values);
       // 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 fold.unit === '' ? num(clamped) : dim(clamped, fold.unit);
+      return foldResult(fold, clamped);
     }
   }
   return call('clamp', args);
 }
 
+/**
+ * @param {Node} node
+ * @return {boolean}
+ */
+function isNone(node) {
+  return node.type === 'Ident' && node.name.toLowerCase() === 'none';
+}
+
 export { simplifyClamp };

package/src/lib/simplify/fold.js

@@ -1,8 +1,21 @@
+import { num, dim } from '../node.js';
 import { baseOf, convert } from '../convertUnits.js';
 
 /** @typedef {import('../node.js').Node} Node */
+/** @typedef {import('../node.js').Num} Num */
+/** @typedef {import('../node.js').Dim} Dim */
 /** @typedef {import('../convertUnits.js').BaseType} BaseType */
 
+/**
+ * Construct a Num or Dim node from a folded result.
+ * @param {{ unit: string }} fold
+ * @param {number} value
+ * @return {Num | Dim}
+ */
+function foldResult(fold, value) {
+  return fold.unit === '' ? num(value) : dim(value, fold.unit);
+}
+
 /**
  * @param {Node[]} args
  * @return {{ values: number[], unit: string } | null}
@@ -62,4 +75,4 @@ function foldDimArgs(args, unit, base) {
   return { values, unit };
 }
 
-export { foldConstArgs };
+export { foldConstArgs, foldResult };

package/src/lib/simplify/hypot.js

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

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

@@ -1,5 +1,5 @@
-import { num, dim, call } from '../node.js';
-import { foldConstArgs } from './fold.js';
+import { call } from '../node.js';
+import { foldConstArgs, foldResult } 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 fold.unit === '' ? num(value) : dim(value, fold.unit);
+    return foldResult(fold, value);
   }
   return call(name, args);
 }

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

@@ -1,5 +1,5 @@
-import { num, dim, call } from '../node.js';
-import { foldConstArgs } from './fold.js';
+import { num, call } from '../node.js';
+import { foldConstArgs, foldResult } from './fold.js';
 
 /** @typedef {import('../node.js').Node} Node */
 
@@ -23,7 +23,7 @@ function simplifyModRem(name, args) {
   if (Number.isNaN(result)) {
     return num(Number.NaN);
   }
-  return fold.unit === '' ? num(result) : dim(result, fold.unit);
+  return foldResult(fold, result);
 }
 
 /**

package/src/lib/simplify/round.js

@@ -1,5 +1,5 @@
-import { num, dim, ident, call } from '../node.js';
-import { foldConstArgs } from './fold.js';
+import { num, ident, call } from '../node.js';
+import { foldConstArgs, foldResult } from './fold.js';
 
 /** @typedef {import('../node.js').Node} Node */
 
@@ -58,14 +58,14 @@ function simplifyRound(args) {
     } else {
       result = a < 0 || Object.is(a, -0) ? -0 : 0;
     }
-    return fold.unit === '' ? num(result) : dim(result, fold.unit);
+    return foldResult(fold, result);
   }
 
   const result = applyRound(strategy, a, b);
   if (Number.isNaN(result)) {
     return num(Number.NaN);
   }
-  return fold.unit === '' ? num(result) : dim(result, fold.unit);
+  return foldResult(fold, result);
 }
 
 /**

package/src/lib/tokenizer.js

@@ -26,6 +26,32 @@ function tokenize(input) {
   return tokenizeTokens(tokenizeCss({ css: input }), input.length);
 }
 
+/**
+ * CSS absorbs leading signs (`-5px` is one token); the parser expects
+ * punct sign + unsigned numeric, so split them back out.
+ * @param {Token[]} tokens
+ * @param {string} raw
+ * @param {string | undefined} unit
+ * @param {number} pos
+ * @param {boolean} ws
+ * @return {void}
+ */
+function pushNumeric(tokens, raw, unit, pos, ws) {
+  let value = /** @type {RegExpExecArray} */ (NUMERIC_RAW.exec(raw))[0];
+  const sign = value[0];
+  if (sign === '+' || sign === '-') {
+    tokens.push({ type: 'punct', value: sign, pos, ws });
+    value = value.slice(1);
+    pos += 1;
+    ws = false;
+  }
+  if (unit === undefined) {
+    tokens.push({ type: 'number', value, pos, ws });
+  } else {
+    tokens.push({ type: 'dimension', value, unit, pos, ws });
+  }
+}
+
 /**
  * Convert a slice of an existing CSS token stream into the token subset used
  * by the calculation parser. Token positions remain relative to the original
@@ -33,52 +59,38 @@ function tokenize(input) {
  *
  * @param {import('@csstools/css-tokenizer').CSSToken[]} cssTokens
  * @param {number} eofPosition
+ * @param {number} [start]
+ * @param {number} [end]
  * @return {Token[]}
  */
-function tokenizeTokens(cssTokens, eofPosition) {
+function tokenizeTokens(
+  cssTokens,
+  eofPosition,
+  start = 0,
+  end = cssTokens.length
+) {
   /** @type {Token[]} */
   const tokens = [];
   let ws = true;
 
-  // CSS absorbs leading signs (`-5px` is one token); the parser expects
-  // punct sign + unsigned numeric, so split them back out.
-  /**
-   * @param {string} raw
-   * @param {string | undefined} unit
-   * @param {number} pos
-   * @return {void}
-   */
-  function pushNumeric(raw, unit, pos) {
-    let value = /** @type {RegExpExecArray} */ (NUMERIC_RAW.exec(raw))[0];
-    const sign = value[0];
-    if (sign === '+' || sign === '-') {
-      tokens.push({ type: 'punct', value: sign, pos, ws });
-      value = value.slice(1);
-      pos += 1;
-      ws = false;
-    }
-    if (unit === undefined) {
-      tokens.push({ type: 'number', value, pos, ws });
-    } else {
-      tokens.push({ type: 'dimension', value, unit, pos, ws });
-    }
-    ws = false;
-  }
-
-  for (const t of cssTokens) {
+  for (let i = start; i < end; i++) {
+    const t = cssTokens[i];
     switch (t[0]) {
       case CssType.Whitespace:
       case CssType.Comment:
         ws = true;
         continue;
       case CssType.Number:
-        pushNumeric(t[1], undefined, t[2]);
+        pushNumeric(tokens, t[1], undefined, t[2], ws);
+        ws = false;
         continue;
       case CssType.Dimension:
-        pushNumeric(t[1], t[4].unit, t[2]);
+        pushNumeric(tokens, t[1], t[4].unit, t[2], ws);
+        ws = false;
         continue;
       case CssType.Percentage:
-        pushNumeric(t[1], '%', t[2]);
+        pushNumeric(tokens, t[1], '%', t[2], ws);
+        ws = false;
         continue;
       case CssType.Ident:
         tokens.push({ type: 'ident', value: t[4].value, pos: t[2], ws });

package/src/reduce.js

@@ -0,0 +1,165 @@
+// CSS component-value reducer. This module deliberately has no PostCSS
+// dependency so it can also be used for individual declaration values,
+// at-rule parameters, or selector text.
+import {
+  tokenize as cssTokenize,
+  TokenType as CssType,
+} from '@csstools/css-tokenizer';
+import { tokenizeTokens } from './lib/tokenizer.js';
+import { parse } from './lib/parser.js';
+import { simplify } from './lib/simplify.js';
+import {
+  isSupportedMathFunction,
+  hasPotentialMathFunction,
+  QUICK_MATH_TEST,
+} from './lib/simplify/call.js';
+import { serialize } from './lib/serialize.js';
+
+const MATCH_CALC = /^(?:-(?:moz|webkit)-)?calc$/i;
+
+const BLOCK_CLOSE = new Map([
+  [CssType.OpenParen, CssType.CloseParen],
+  [CssType.OpenSquare, CssType.CloseSquare],
+  [CssType.OpenCurly, CssType.CloseCurly],
+]);
+
+/**
+ * @typedef {object} ReduceCalcOptions
+ * @property {number | false} [precision]
+ * @property {boolean} [warnWhenCannotResolve]
+ * @property {(error: Error, input: string) => void} [onParseError] Invoked when parse/simplify throws.
+ * @property {(message: string) => void} [onWarn] Invoked when `warnWhenCannotResolve` is set and an expression cannot be reduced to a single value.
+ */
+
+/** @typedef {Required<Omit<ReduceCalcOptions, 'onParseError' | 'onWarn'>> & Pick<ReduceCalcOptions, 'onParseError' | 'onWarn'>} ResolvedReduceCalcOptions */
+
+/**
+ * Fields threaded unchanged through the token-range walk.
+ * `value` is the original full property text, used only for the
+ * warnWhenCannotResolve message.
+ *
+ * @typedef {object} TransformContext
+ * @property {ResolvedReduceCalcOptions} options
+ * @property {string} value
+ * @property {import('@csstools/css-tokenizer').CSSToken[]} tokens
+ * @property {Replacement[]} replacements
+ */
+
+/**
+ * @typedef {object} Replacement
+ * @property {number} start
+ * @property {number} end
+ * @property {import('./lib/node.js').Node} node
+ * @property {string} calcName
+ * @property {string} matchedName
+ */
+
+/**
+ * Walk one component-value level. Unsupported functions and simple blocks are
+ * traversed, while a supported function is treated as one opaque calculation
+ * even when parsing it fails. A missing closer consumes through EOF, matching
+ * CSS component-value parsing's error recovery.
+ *
+ * @param {number} start
+ * @param {import('@csstools/css-tokenizer').TokenType | undefined} expectedClose
+ * @param {TransformContext} ctx
+ * @param {boolean} transform
+ * @return {number} Index of the matching closer, or the EOF token.
+ */
+function walkTokens(start, expectedClose, ctx, transform) {
+  for (let i = start; i < ctx.tokens.length; i++) {
+    const token = ctx.tokens[i];
+    if (token[0] === CssType.EOF || token[0] === expectedClose) return i;
+
+    const blockClose = BLOCK_CLOSE.get(token[0]);
+    if (blockClose) {
+      i = walkTokens(i + 1, blockClose, ctx, transform);
+      continue;
+    }
+
+    if (token[0] !== CssType.Function) continue;
+
+    const name = token[4].value;
+    const isCalc = MATCH_CALC.test(name);
+    const isMath = !isCalc && isSupportedMathFunction(name);
+    if (!transform || (!isCalc && !isMath)) {
+      i = walkTokens(i + 1, CssType.CloseParen, ctx, transform);
+      continue;
+    }
+
+    // Locate the complete outer function without transforming its children.
+    const close = walkTokens(i + 1, CssType.CloseParen, ctx, false);
+    const closed = ctx.tokens[close][0] === CssType.CloseParen;
+    const end = closed ? ctx.tokens[close][3] + 1 : ctx.value.length;
+    const sliceStart = isCalc ? i + 1 : i;
+    const sliceEnd = closed ? close + (isCalc ? 0 : 1) : close;
+    const inputStart = isCalc ? token[3] + 1 : token[2];
+    const inputEnd = closed && isCalc ? ctx.tokens[close][2] : end;
+    const contents = ctx.value.slice(inputStart, inputEnd);
+    try {
+      const node = simplify(
+        parse(tokenizeTokens(ctx.tokens, end, sliceStart, sliceEnd))
+      );
+      ctx.replacements.push({
+        start: token[2],
+        end,
+        node,
+        calcName: isCalc ? name : 'calc',
+        matchedName: name,
+      });
+    } catch (error) {
+      const err = error instanceof Error ? error : new Error('Error');
+      ctx.options.onParseError?.(err, contents);
+    }
+    i = close;
+  }
+
+  return ctx.tokens.length - 1;
+}
+
+/**
+ * Simplify every supported CSS math function in a component-value string.
+ * Text outside those functions is preserved byte-for-byte.
+ *
+ * @param {string} value
+ * @param {ReduceCalcOptions} [opts]
+ * @return {string}
+ */
+function reduceCalc(value, opts) {
+  if (!hasPotentialMathFunction(value)) {
+    return value;
+  }
+
+  /** @type {ResolvedReduceCalcOptions} */
+  const options = { precision: 5, warnWhenCannotResolve: false, ...opts };
+  const tokens = cssTokenize({ css: value });
+  /** @type {Replacement[]} */
+  const replacements = [];
+  walkTokens(0, undefined, { options, value, tokens, replacements }, true);
+
+  if (replacements.length === 0) {
+    return value;
+  }
+
+  let output = '';
+  let lastIndex = 0;
+  for (const replacement of replacements) {
+    const text = serialize(replacement.node, {
+      precision: options.precision,
+      calcName: replacement.calcName,
+    });
+    if (
+      options.warnWhenCannotResolve &&
+      text.startsWith(`${replacement.matchedName}(`)
+    ) {
+      options.onWarn?.('Could not reduce expression: ' + value);
+    }
+    output += value.slice(lastIndex, replacement.start) + text;
+    lastIndex = replacement.end;
+  }
+  output += value.slice(lastIndex);
+  return output;
+}
+
+export { QUICK_MATH_TEST, hasPotentialMathFunction };
+export default reduceCalc;

package/types/index.d.ts

@@ -9,21 +9,6 @@ export type PostCssCalcOptions = {
     onParseError?: (error: Error, input: string) => void;
 };
 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;
-    tokens: import('@csstools/css-tokenizer').CSSToken[];
-    replacements: Replacement[];
-};
-export type Replacement = {
-    start: number;
-    end: number;
-    node: import('./lib/node.js').Node;
-    calcName: string;
-    matchedName: string;
-};
 /**
  * @param {PostCssCalcOptions} [opts]
  * @return {import('postcss').Plugin}

package/types/lib/parser.d.ts

@@ -21,6 +21,22 @@ declare class Parser {
      * @return {Token}
      */
     expect(type: TokenType, value?: string): Token;
+    /**
+     * @param {string} value
+     * @param {string} [value2]
+     * @return {boolean}
+     */
+    isPunct(value: string, value2?: string): boolean;
+    /**
+     * @param {string} value
+     * @return {boolean}
+     */
+    matchPunct(value: string): boolean;
+    /**
+     * @param {string} value
+     * @return {Token}
+     */
+    expectPunct(value: string): Token;
     /**
      * @param {number} [minBp]
      * @return {Node}

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

@@ -1,6 +1,16 @@
 export type Node = import('../node.js').Node;
 export type SimplifyFn = import('../simplify.js').SimplifyFn;
 export type MathSimplifier = (name: string, args: Node[]) => Node;
+declare const QUICK_MATH_TEST: RegExp;
+/**
+ * Fast check to determine whether a CSS component value could contain
+ * a supported calculation or math function call (or an escape sequence
+ * that could decode to one).
+ *
+ * @param {string} value
+ * @return {boolean}
+ */
+declare function hasPotentialMathFunction(value: string): boolean;
 /**
  * Whether a bare CSS math function has an implemented simplifier.
  *
@@ -16,4 +26,4 @@ declare function isSupportedMathFunction(name: string): boolean;
 declare function simplifyCall(node: Extract<Node, {
     type: 'Call';
 }>, simplify: SimplifyFn): Node;
-export { isSupportedMathFunction, simplifyCall };
+export { isSupportedMathFunction, simplifyCall, hasPotentialMathFunction, QUICK_MATH_TEST, };

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

@@ -1,7 +1,20 @@
 export type Node = import('../node.js').Node;
+export type Num = import('../node.js').Num;
+export type Dim = import('../node.js').Dim;
 export type BaseType = import('../convertUnits.js').BaseType;
 /** @typedef {import('../node.js').Node} Node */
+/** @typedef {import('../node.js').Num} Num */
+/** @typedef {import('../node.js').Dim} Dim */
 /** @typedef {import('../convertUnits.js').BaseType} BaseType */
+/**
+ * Construct a Num or Dim node from a folded result.
+ * @param {{ unit: string }} fold
+ * @param {number} value
+ * @return {Num | Dim}
+ */
+declare function foldResult(fold: {
+    unit: string;
+}, value: number): Num | Dim;
 /**
  * @param {Node[]} args
  * @return {{ values: number[], unit: string } | null}
@@ -10,4 +23,4 @@ declare function foldConstArgs(args: Node[]): {
     values: number[];
     unit: string;
 } | null;
-export { foldConstArgs };
+export { foldConstArgs, foldResult };

package/types/lib/tokenizer.d.ts

@@ -24,7 +24,9 @@ declare function tokenize(input: string): Token[];
  *
  * @param {import('@csstools/css-tokenizer').CSSToken[]} cssTokens
  * @param {number} eofPosition
+ * @param {number} [start]
+ * @param {number} [end]
  * @return {Token[]}
  */
-declare function tokenizeTokens(cssTokens: import('@csstools/css-tokenizer').CSSToken[], eofPosition: number): Token[];
+declare function tokenizeTokens(cssTokens: import('@csstools/css-tokenizer').CSSToken[], eofPosition: number, start?: number, end?: number): Token[];
 export { tokenize, tokenizeTokens };

package/types/reduce.d.ts

@@ -0,0 +1,38 @@
+import { hasPotentialMathFunction, QUICK_MATH_TEST } from './lib/simplify/call.js';
+export type ReduceCalcOptions = {
+    precision?: number | false;
+    warnWhenCannotResolve?: boolean;
+    /**
+     * Invoked when parse/simplify throws.
+     */
+    onParseError?: (error: Error, input: string) => void;
+    /**
+     * Invoked when `warnWhenCannotResolve` is set and an expression cannot be reduced to a single value.
+     */
+    onWarn?: (message: string) => void;
+};
+export type ResolvedReduceCalcOptions = Required<Omit<ReduceCalcOptions, 'onParseError' | 'onWarn'>> & Pick<ReduceCalcOptions, 'onParseError' | 'onWarn'>;
+export type TransformContext = {
+    options: ResolvedReduceCalcOptions;
+    value: string;
+    tokens: import('@csstools/css-tokenizer').CSSToken[];
+    replacements: Replacement[];
+};
+export type Replacement = {
+    start: number;
+    end: number;
+    node: import('./lib/node.js').Node;
+    calcName: string;
+    matchedName: string;
+};
+/**
+ * Simplify every supported CSS math function in a component-value string.
+ * Text outside those functions is preserved byte-for-byte.
+ *
+ * @param {string} value
+ * @param {ReduceCalcOptions} [opts]
+ * @return {string}
+ */
+declare function reduceCalc(value: string, opts?: ReduceCalcOptions): string;
+export { QUICK_MATH_TEST, hasPotentialMathFunction };
+export default reduceCalc;

package/types/lib/type.d.ts

@@ -1,23 +0,0 @@
-export type BaseType =
-  | 'length'
-  | 'angle'
-  | 'time'
-  | 'frequency'
-  | 'resolution'
-  | 'flex'
-  | 'percentage';
-/**
- * @param {string} unit
- * @return {BaseType | null}
- */
-export function baseOf(unit: string): BaseType | null;
-/**
- * Convert a value within a single conversion family. Returns null when
- * either unit is missing from the table (em/rem/vw need runtime context)
- * or when the units belong to different base types.
- * @param {number} value
- * @param {string} from
- * @param {string} to
- * @return {number | null}
- */
-export function convert(value: number, from: string, to: string): number | null;