postcss-calc 11.1.0 → 11.1.2

package/src/lib/serialize.js

@@ -1,9 +1,9 @@
 // Spec: https://www.w3.org/TR/css-values-4/#serialize-a-calculation-tree
-// Outer calc() is added only when the top-level result contains an
-// arithmetic operator. A Sum inside a Product is the only place parens
-// are ever required on valid canonical input.
+// Outer calc() is added when the top-level result contains an arithmetic
+// operator, or when a finite scalar is negative.
 
 import { num, dim } from './node.js';
+import { getComponents, serializeComponents } from './opaque.js';
 
 /**
  * @typedef {import('./node.js').Node} Node
@@ -13,6 +13,7 @@ import { num, dim } from './node.js';
  * @typedef {object} SerializeOptions
  * @property {number | false} [precision] Decimal places for numbers. `false` disables rounding. Default 5.
  * @property {string} [calcName] Wrapper name to use when `calc()` is needed. Default `'calc'`.
+ * @property {boolean} [unwrapSingleNegativeNumber] Serialize finite negative scalars without a wrapper. Internal selector-only mode.
  */
 
 // Below this is float noise, not a value: `0.1 + 0.2 - 0.3` is 5.5e-17.
@@ -80,6 +81,20 @@ function serializeNumber(v) {
   return text;
 }
 
+/**
+ * Round and serialize a finite scalar once so callers can use the same value
+ * to decide its syntactic context and render its text.
+ *
+ * @param {import('./node.js').Num | import('./node.js').Dim} node
+ * @param {number | false} prec
+ * @return {{value: number, text: string}}
+ */
+function serializeScalar(node, prec) {
+  const value = round(node.value, prec);
+  const text = `${serializeNumber(value)}${node.type === 'Dim' ? (node.rawUnit ?? node.unit) : ''}`;
+  return { value, text };
+}
+
 /**
  * @param {Node} node
  * @param {SerializeOptions} [opts]
@@ -95,7 +110,23 @@ function serialize(node, opts = {}) {
     return `${calcName}(${degenerateKeyword(node.value)})`;
   }
   if (node.type === 'Dim' && isDegenerate(node.value)) {
-    return `${calcName}(${degenerateKeyword(node.value)} * 1${node.unit})`;
+    return `${calcName}(${degenerateKeyword(node.value)} * 1${node.rawUnit ?? node.unit})`;
+  }
+
+  if (node.type === 'Num' || node.type === 'Dim') {
+    const scalar = serializeScalar(node, prec);
+
+    // A finite negative scalar must stay inside calc() so CSS parses it as a
+    // calculation result (and can apply range clamping) rather than as an
+    // invalid bare value. Base this on the serialized value so tiny negative
+    // floating-point noise that rounds to zero does not get wrapped.
+    if (scalar.value < 0) {
+      return opts.unwrapSingleNegativeNumber
+        ? scalar.text
+        : `${calcName}(${scalar.text})`;
+    }
+
+    return scalar.text;
   }
 
   // A grouped sum with a leading negative term is the canonical result of
@@ -114,12 +145,7 @@ function serialize(node, opts = {}) {
     return `${calcName}(-(${serializeSumTerms(invertedTerms, prec)}))`;
   }
 
-  if (
-    node.type === 'Num' ||
-    node.type === 'Dim' ||
-    node.type === 'Ident' ||
-    node.type === 'Call'
-  ) {
+  if (node.type === 'Ident' || node.type === 'Call') {
     return serializeExpr(node, prec);
   }
 
@@ -145,20 +171,27 @@ function serializeExpr(node, prec) {
       if (isDegenerate(node.value)) {
         return degenerateKeyword(node.value);
       }
-      return serializeNumber(round(node.value, prec));
+      return serializeScalar(node, prec).text;
     case 'Dim':
       if (isDegenerate(node.value)) {
         // Nested degenerate Dim wraps in calc() so the `<kw> * 1<unit>` form
         // parses back as one Dim factor. The bare form round-trips wrong
         // inside a Product — `0 * Dim(Infinity, px)` would re-fold as NaN.
-        return `calc(${degenerateKeyword(node.value)} * 1${node.unit})`;
+        return `calc(${degenerateKeyword(node.value)} * 1${node.rawUnit ?? node.unit})`;
       }
-      return `${serializeNumber(round(node.value, prec))}${node.unit}`;
+      return serializeScalar(node, prec).text;
     case 'Ident':
-      return node.name;
+      return node.rawName ?? node.name;
     case 'Call': {
+      const components = getComponents(node);
+      if (components) {
+        const args = node.args
+          .map((arg) => serializeExpr(arg, prec))
+          .join(', ');
+        return `${node.rawName ?? node.name}(${args}${serializeComponents(components, (child) => serialize(child, { precision: prec }))})`;
+      }
       const args = node.args.map((a) => serializeExpr(a, prec)).join(', ');
-      return `${node.name}(${args})`;
+      return `${node.rawName ?? node.name}(${args})`;
     }
     case 'Sum':
       return serializeSum(node, prec);
@@ -187,7 +220,7 @@ function displaySign(term) {
   if (node.type === 'Dim' && Number.isFinite(node.value) && node.value < 0) {
     return {
       sign: /** @type {1 | -1} */ (-sign),
-      magnitude: dim(-node.value, node.unit),
+      magnitude: dim(-node.value, node.unit, node.rawUnit),
     };
   }
   return { sign, magnitude: node };

package/src/lib/simplify/abs.js

@@ -15,7 +15,7 @@ function simplifyAbs(args) {
     return num(Math.abs(a.value));
   }
   if (a.type === 'Dim' && a.unit !== '%') {
-    return dim(Math.abs(a.value), a.unit);
+    return dim(Math.abs(a.value), a.unit, a.rawUnit);
   }
   return call('abs', [a]);
 }

package/src/lib/simplify/bucket.js

@@ -9,10 +9,10 @@ import { convert } from '../convertUnits.js';
 /**
  * @typedef {object} UnitBucket
  * @property {string} unit
+ * @property {string} [rawUnit]
  * @property {number} total
  * @property {number} scale largest |term| accumulated into `total`, for noise detection
  * @property {import('../convertUnits.js').BaseType | null} base
- * @property {number} order
  */
 
 /** Mutates `buckets` in place — totals of survivor buckets accumulate the
@@ -21,32 +21,27 @@ import { convert } from '../convertUnits.js';
  * @return {UnitBucket[]}
  */
 function mergeConvertibleBuckets(buckets) {
-  const ordered = buckets.sort((a, b) => a.order - b.order);
-  /** @type {Set<string>} */ const merged = new Set();
+  /** @type {Map<import('../convertUnits.js').BaseType, UnitBucket>} */ const representative =
+    new Map();
   /** @type {UnitBucket[]} */ const out = [];
-  for (const b of ordered) {
-    const keyB = b.unit.toLowerCase();
-    if (merged.has(keyB)) {
+  for (const b of buckets) {
+    if (b.base === null) {
+      out.push(b);
       continue;
     }
-    merged.add(keyB);
-    if (b.base !== null) {
-      for (const other of ordered) {
-        const keyO = other.unit.toLowerCase();
-        if (merged.has(keyO)) {
-          continue;
-        }
-        if (other.base !== b.base) {
-          continue;
-        }
-        const converted = convert(other.total, other.unit, b.unit);
-        if (converted !== null) {
-          b.total += converted;
-          merged.add(keyO);
-        }
-      }
+    const first = representative.get(b.base);
+    if (!first) {
+      representative.set(b.base, b);
+      out.push(b);
+      continue;
+    }
+    const converted = convert(b.total, b.unit, first.unit);
+    if (converted === null) {
+      out.push(b);
+      continue;
     }
-    out.push(b);
+    first.total += converted;
+    first.scale = Math.max(first.scale, Math.abs(converted));
   }
   return out;
 }

package/src/lib/simplify/call.js

@@ -17,6 +17,7 @@ import { simplifyLog } from './log.js';
 import { simplifyHypot } from './hypot.js';
 
 import { call } from '../node.js';
+import { getComponents, setComponents, simplifyComponents } from '../opaque.js';
 
 /** @typedef {import('../node.js').Node} Node */
 /** @typedef {import('../simplify.js').SimplifyFn} SimplifyFn */
@@ -101,6 +102,12 @@ function simplifyCall(node, simplify) {
 
   const args = node.args.map((a) => simplify(a));
 
+  const components = getComponents(node);
+  if (components) {
+    const result = call(node.name, args, node.rawName);
+    return setComponents(result, simplifyComponents(components, simplify));
+  }
+
   const simplifier = MATH_SIMPLIFIERS.get(name);
   if (simplifier) {
     // min/max preserve the call's original casing in their opaque-args
@@ -111,7 +118,7 @@ function simplifyCall(node, simplify) {
     );
   }
 
-  return call(node.name, args);
+  return call(node.name, args, node.rawName);
 }
 
 export {

package/src/lib/simplify/product.js

@@ -15,7 +15,7 @@ import { tryCancelPair } from './cancel.js';
  */
 function simplifyProduct(product, simplify) {
   let coeff = 1;
-  /** @type {{exponent: 1 | -1, value: number, unit: string}[]} */
+  /** @type {{exponent: 1 | -1, value: number, unit: string, rawUnit?: string}[]} */
   const dims = [];
   /** @type {ProductFactor[]} */
   const opaque = [];
@@ -54,7 +54,7 @@ function simplifyProduct(product, simplify) {
       return;
     }
     if (n.type === 'Dim') {
-      dims.push({ exponent, value: n.value, unit: n.unit });
+      dims.push({ exponent, value: n.value, unit: n.unit, rawUnit: n.rawUnit });
       scalarChain.push({ exponent, value: n.value });
       return;
     }
@@ -112,7 +112,7 @@ function simplifyProduct(product, simplify) {
         value = value / f.value;
       }
     }
-    return dim(value, d.unit);
+    return dim(value, d.unit, d.rawUnit);
   }
 
   if (remainingDims.length === 0 && opaque.length === 0) {
@@ -125,7 +125,10 @@ function simplifyProduct(product, simplify) {
     factors.push({ exponent: 1, node: num(coeff) });
   }
   for (const d of remainingDims) {
-    factors.push({ exponent: d.exponent, node: dim(d.value, d.unit) });
+    factors.push({
+      exponent: d.exponent,
+      node: dim(d.value, d.unit, d.rawUnit),
+    });
   }
   factors.push(...opaque);
 

package/src/lib/simplify/sum.js

@@ -1,5 +1,5 @@
 import { mkSum, num, dim } from '../node.js';
-import { baseOf } from '../convertUnits.js';
+import { staticBaseOf } from '../convertUnits.js';
 import { mergeConvertibleBuckets } from './bucket.js';
 
 /**
@@ -39,7 +39,6 @@ function simplifySum(sum, simplify) {
   const byUnit = new Map();
   /** @type {SumTerm[]} */
   const opaque = [];
-  let bucketOrder = 0;
 
   /**
    * @param {1 | -1} sign
@@ -78,10 +77,10 @@ function simplifySum(sum, simplify) {
       } else {
         byUnit.set(key, {
           unit: n.unit,
+          rawUnit: n.rawUnit,
           total: sign * n.value,
           scale: Math.abs(n.value),
-          base: baseOf(n.unit),
-          order: bucketOrder++,
+          base: staticBaseOf(n.unit),
         });
       }
       return;
@@ -101,7 +100,11 @@ function simplifySum(sum, simplify) {
   for (const bucket of mergeConvertibleBuckets([...byUnit.values()])) {
     terms.push({
       sign: 1,
-      node: dim(denoise(bucket.total, bucket.scale), bucket.unit),
+      node: dim(
+        denoise(bucket.total, bucket.scale),
+        bucket.unit,
+        bucket.rawUnit
+      ),
     });
   }
   terms.push(...opaque);

package/src/lib/tokenizer.js

@@ -1,139 +1,10 @@
-// Folds @csstools/css-tokenizer output into the calc() token subset.
+// Thin project-local entry point for the CSS Syntax tokenizer. The parser
+// consumes native tokens directly so decoded values and source spelling remain available.
+import { tokenize as tokenizeCss } from '@csstools/css-tokenizer';
 
-import {
-  tokenize as tokenizeCss,
-  TokenType as CssType,
-} from '@csstools/css-tokenizer';
-/**
- * @typedef {'number' | 'dimension' | 'ident' | 'punct' | 'eof'} TokenType
- * @typedef {object} Token
- * @property {TokenType} type
- * @property {string} value
- * @property {string} [unit] Present on `dimension` tokens; `%` for percentages.
- * @property {number} pos
- * @property {boolean} ws Whitespace immediately before — drives the §10.1 `+`/`-` rule.
- */
-
-const PUNCT_DELIMS = new Set(['+', '-', '*', '/']);
-
-const NUMERIC_RAW = /^[+-]?(?:\d+(?:\.\d+)?|\.\d+)(?:[eE][+-]?\d+)?/;
-
-/**
- * @param {string} input
- * @return {Token[]}
- */
+/** @param {string} input @return {import('@csstools/css-tokenizer').CSSToken[]} */
 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
- * source text, which keeps parse errors useful to adapter callers.
- *
- * @param {import('@csstools/css-tokenizer').CSSToken[]} cssTokens
- * @param {number} eofPosition
- * @param {number} [start]
- * @param {number} [end]
- * @return {Token[]}
- */
-function tokenizeTokens(
-  cssTokens,
-  eofPosition,
-  start = 0,
-  end = cssTokens.length
-) {
-  /** @type {Token[]} */
-  const tokens = [];
-  let ws = true;
-
-  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(tokens, t[1], undefined, t[2], ws);
-        ws = false;
-        continue;
-      case CssType.Dimension:
-        pushNumeric(tokens, t[1], t[4].unit, t[2], ws);
-        ws = false;
-        continue;
-      case CssType.Percentage:
-        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 });
-        break;
-      case CssType.Function:
-        tokens.push({ type: 'ident', value: t[4].value, pos: t[2], ws });
-        tokens.push({
-          type: 'punct',
-          value: '(',
-          pos: t[2] + t[1].length - 1,
-          ws: false,
-        });
-        break;
-      case CssType.OpenParen:
-        tokens.push({ type: 'punct', value: '(', pos: t[2], ws });
-        break;
-      case CssType.CloseParen:
-        tokens.push({ type: 'punct', value: ')', pos: t[2], ws });
-        break;
-      case CssType.Comma:
-        tokens.push({ type: 'punct', value: ',', pos: t[2], ws });
-        break;
-      case CssType.Delim:
-        if (!PUNCT_DELIMS.has(t[4].value)) {
-          throw new Error(
-            `Unexpected character "${t[4].value}" at position ${t[2]}`
-          );
-        }
-        tokens.push({ type: 'punct', value: t[4].value, pos: t[2], ws });
-        break;
-      case CssType.EOF:
-        continue;
-      default:
-        throw new Error(
-          `Unexpected character "${t[1][0] ?? ''}" at position ${t[2]}`
-        );
-    }
-    ws = false;
-  }
-
-  tokens.push({ type: 'eof', value: '', pos: eofPosition, ws });
-
-  return tokens;
+  return tokenizeCss({ css: input });
 }
 
-export { tokenize, tokenizeTokens };
+export { tokenize };

package/src/reduce.js

@@ -5,7 +5,6 @@ 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 {
@@ -27,6 +26,7 @@ const BLOCK_CLOSE = new Map([
  * @typedef {object} ReduceCalcOptions
  * @property {number | false} [precision]
  * @property {boolean} [warnWhenCannotResolve]
+ * @property {boolean} [unwrapSingleNegativeNumber] Serialize finite negative results without a `calc()` wrapper. Defaults to `false`.
  * @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.
  */
@@ -34,9 +34,7 @@ const BLOCK_CLOSE = new Map([
 /** @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.
+ * Fields threaded through the internal token-range walk.
  *
  * @typedef {object} TransformContext
  * @property {ResolvedReduceCalcOptions} options
@@ -51,7 +49,6 @@ const BLOCK_CLOSE = new Map([
  * @property {number} end
  * @property {import('./lib/node.js').Node} node
  * @property {string} calcName
- * @property {string} matchedName
  */
 
 /**
@@ -97,15 +94,12 @@ function walkTokens(start, expectedClose, ctx, transform) {
     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))
-      );
+      const node = simplify(parse(ctx.tokens, 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');
@@ -117,6 +111,17 @@ function walkTokens(start, expectedClose, ctx, transform) {
   return ctx.tokens.length - 1;
 }
 
+/**
+ * @param {import('./lib/node.js').Node} node
+ * @return {boolean}
+ */
+function isUnresolvedResult(node) {
+  if (node.type === 'Sum' || node.type === 'Product') {
+    return true;
+  }
+  return node.type === 'Call' && isSupportedMathFunction(node.name);
+}
+
 /**
  * Simplify every supported CSS math function in a component-value string.
  * Text outside those functions is preserved byte-for-byte.
@@ -131,7 +136,12 @@ function reduceCalc(value, opts) {
   }
 
   /** @type {ResolvedReduceCalcOptions} */
-  const options = { precision: 5, warnWhenCannotResolve: false, ...opts };
+  const options = {
+    precision: 5,
+    warnWhenCannotResolve: false,
+    unwrapSingleNegativeNumber: false,
+    ...opts,
+  };
   const tokens = cssTokenize({ css: value });
   /** @type {Replacement[]} */
   const replacements = [];
@@ -147,11 +157,9 @@ function reduceCalc(value, opts) {
     const text = serialize(replacement.node, {
       precision: options.precision,
       calcName: replacement.calcName,
+      unwrapSingleNegativeNumber: options.unwrapSingleNegativeNumber,
     });
-    if (
-      options.warnWhenCannotResolve &&
-      text.startsWith(`${replacement.matchedName}(`)
-    ) {
+    if (options.warnWhenCannotResolve && isUnresolvedResult(replacement.node)) {
       options.onWarn?.('Could not reduce expression: ' + value);
     }
     output += value.slice(lastIndex, replacement.start) + text;

package/types/lib/convertUnits.d.ts

@@ -14,4 +14,11 @@ declare function baseOf(unit: string): BaseType | null;
  * @return {number | null}
  */
 declare function convert(value: number, from: string, to: string): number | null;
-export { baseOf, convert };
+/**
+ * Return a base type only for units present in the static conversion table.
+ * Units with context-dependent values (em, rem, vw, etc.) return null.
+ * @param {string} unit
+ * @return {BaseType | null}
+ */
+declare function staticBaseOf(unit: string): BaseType | null;
+export { baseOf, staticBaseOf, convert };

package/types/lib/node.d.ts

@@ -6,15 +6,18 @@ export type Dim = {
     type: 'Dim';
     value: number;
     unit: string;
+    rawUnit?: string;
 };
 export type Ident = {
     type: 'Ident';
     name: string;
+    rawName?: string;
 };
 export type Call = {
     type: 'Call';
     name: string;
     args: Node[];
+    rawName?: string;
 };
 export type SumTerm = {
     sign: 1 | -1;
@@ -36,9 +39,9 @@ export type Product = {
 export type Node = Num | Dim | Ident | Call | Sum | Product;
 /**
  * @typedef {{type: 'Num', value: number}} Num
- * @typedef {{type: 'Dim', value: number, unit: string}} Dim
- * @typedef {{type: 'Ident', name: string}} Ident
- * @typedef {{type: 'Call', name: string, args: Node[]}} Call
+ * @typedef {{type: 'Dim', value: number, unit: string, rawUnit?: string}} Dim
+ * @typedef {{type: 'Ident', name: string, rawName?: string}} Ident
+ * @typedef {{type: 'Call', name: string, args: Node[], rawName?: string}} Call
  * @typedef {{sign: 1 | -1, node: Node}} SumTerm Sign is always +1 when node is Num or Dim.
  * @typedef {{type: 'Sum', terms: SumTerm[], grouped?: boolean}} Sum
  * @typedef {{exponent: 1 | -1, node: Node}} ProductFactor exponent +1 = numerator, -1 = denominator.
@@ -53,20 +56,23 @@ declare function num(value: number): Num;
 /**
  * @param {number} value
  * @param {string} unit
+ * @param {string} [rawUnit]
  * @return {Dim}
  */
-declare function dim(value: number, unit: string): Dim;
+declare function dim(value: number, unit: string, rawUnit?: string): Dim;
 /**
  * @param {string} name
+ * @param {string} [rawName]
  * @return {Ident}
  */
-declare function ident(name: string): Ident;
+declare function ident(name: string, rawName?: string): Ident;
 /**
  * @param {string} name
  * @param {Node[]} args
+ * @param {string} [rawName]
  * @return {Call}
  */
-declare function call(name: string, args: Node[]): Call;
+declare function call(name: string, args: Node[], rawName?: string): Call;
 /**
  * @param {SumTerm[]} rawTerms
  * @return {Node}

package/types/lib/opaque.d.ts

@@ -0,0 +1,15 @@
+export type Node = import('./node.js').Node;
+export type Component = string | Node | Component[];
+/** @param {Extract<Node, {type: 'Call'}>} node @param {Component[]} tree */
+declare function setComponents(node: Extract<Node, {
+    type: 'Call';
+}>, tree: Component[]): import("./node.js").Call;
+/** @param {Extract<Node, {type: 'Call'}>} node */
+declare function getComponents(node: Extract<Node, {
+    type: 'Call';
+}>): Component[] | undefined;
+/** @param {Component[]} tree @param {(node: Node) => Node} simplify @return {Component[]} */
+declare function simplifyComponents(tree: Component[], simplify: (node: Node) => Node): Component[];
+/** @param {Component[]} tree @param {(node: Node) => string} serialize @return {string} */
+declare function serializeComponents(tree: Component[], serialize: (node: Node) => string): string;
+export { getComponents, setComponents, simplifyComponents, serializeComponents, };