postcss-calc 11.0.3 → 11.1.1

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,7 +52,63 @@ h1 {
 
 Checkout [tests] for more examples.
 
-### Options
+## 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`, `unwrapSingleNegativeNumber`, `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.
+
+### Standalone reducer options
+
+#### `unwrapSingleNegativeNumber` (default: `false`)
+
+Controls whether a finite negative result is serialized as a bare value or
+wrapped in `calc()`. Keep the default when reducing declaration values; set it
+to `true` when the surrounding CSS context requires a bare negative value, such
+as a selector:
+
+```js
+reduceCalc('calc(5px - 10px)');
+// => 'calc(-5px)'
+
+reduceCalc('calc(5px - 10px)', { unwrapNegativeNumbers: true });
+// => '-5px'
+```
+
+### PostCSS plugin options
+
+These options apply when using the PostCSS plugin:
+
+```js
+postcss().use(calc({ precision: 10 }));
+```
 
 #### `precision` (default: `5`)
 
@@ -107,7 +163,11 @@ With `mediaQueries: true`, this becomes:
 
 #### `selectors` (default: `false`)
 
-Allows calc() usage as part of selectors.
+Reduces `calc()` functions found in selectors. Selectors do not accept
+`calc()` functions, so the plugin replaces them with their reduced values.
+Finite negative results are serialized as bare values because a selector cannot
+contain a `calc()` function; the plugin enables `unwrapSingleNegativeNumber` automatically
+for selectors.
 
 ```js
 var out = postcss()
@@ -131,11 +191,13 @@ Callback invoked when a `calc()` body fails to parse or simplify. Matches
 [`@csstools/css-calc`][csstools-css-calc]'s shape:
 
 ```js
-calc({
-  onParseError: (err, input) => {
-    throw err; // or log, route to a different channel, etc.
-  },
-});
+postcss().use(
+  calc({
+    onParseError: (err, input) => {
+      throw err; // or log, route to a different channel, etc.
+    },
+  })
+);
 ```
 
 When omitted, errors are reported via PostCSS `result.warn()` so the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "postcss-calc",
-  "version": "11.0.3",
+  "version": "11.1.1",
   "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
@@ -179,10 +24,36 @@ function transformValue(value, options, result, item) {
  * @param {(target: import('postcss').ChildNode, value: string) => void} setProp
  * @param {ResolvedOptions} options
  * @param {import('postcss').Result} result
+ * @param {boolean} unwrapSingleNegativeNumber
  * @return {void}
  */
-function applyTransform(node, current, setProp, options, result) {
-  setProp(node, transformValue(current, options, result, node));
+function applyTransform(
+  node,
+  current,
+  setProp,
+  options,
+  result,
+  unwrapSingleNegativeNumber
+) {
+  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 });
+    },
+    unwrapSingleNegativeNumber,
+  });
+  if (transformed !== current) {
+    setProp(node, transformed);
+  }
 }
 
 /**
@@ -215,7 +86,8 @@ function pluginCreator(opts) {
               /** @type {import('postcss').Declaration} */ (n).value = v;
             },
             options,
-            result
+            result,
+            false
           );
         }
         if (node.type === 'atrule' && options.mediaQueries) {
@@ -226,7 +98,8 @@ function pluginCreator(opts) {
               /** @type {import('postcss').AtRule} */ (n).params = v;
             },
             options,
-            result
+            result,
+            false
           );
         }
         if (node.type === 'rule' && options.selectors) {
@@ -239,7 +112,8 @@ function pluginCreator(opts) {
               /** @type {import('postcss').Rule} */ (n).selector = v;
             },
             options,
-            result
+            result,
+            true
           );
         }
       });

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;
   },