postcss-calc 11.1.2 → 11.2.1

package/README.md

@@ -43,10 +43,10 @@ you will get:
 
 ```css
 h1 {
-  font-size: 32px;
+  font-size: calc(32px);
   height: calc(100px - 2em);
   width: calc(2 * var(--base-width));
-  margin-bottom: 24px;
+  margin-bottom: calc(24px);
 }
 ```
 
@@ -62,14 +62,15 @@ leaving all other text untouched.
 import reduceCalc from 'postcss-calc/reduce';
 
 reduceCalc('calc(1in + 10px)');
-// => '1.10417in'
+// => 'calc(1.10417in)'
 
 reduceCalc('min(50px, calc(2 * 40px))');
-// => '50px'
+// => 'calc(50px)'
 ```
 
-It accepts `precision`, `unwrapSingleNegativeNumber`, `warnWhenCannotResolve`, `onParseError`,
-and `onWarn`:
+It accepts `precision`, `unwrapSingleValue`, the deprecated
+`unwrapSingleNegativeNumber` alias,
+`warnWhenCannotResolve`, `onParseError`, and `onWarn`:
 
 ```js
 const result = reduceCalc('calc(100% + var(--gap))', {
@@ -87,21 +88,27 @@ by default; provide `onParseError` and/or `onWarn` if you want diagnostics.
 
 ### Standalone reducer options
 
-#### `unwrapSingleNegativeNumber` (default: `false`)
+#### `unwrapSingleValue` (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:
+Serializes a fully resolved finite scalar result without calculation syntax.
+Keep the default for standard CSS so the browser can perform range clamping
+and integer rounding. Set it to `true` for a non-standard context that requires
+a bare value, such as a selector:
 
 ```js
 reduceCalc('calc(5px - 10px)');
 // => 'calc(-5px)'
 
-reduceCalc('calc(5px - 10px)', { unwrapNegativeNumbers: true });
+reduceCalc('calc(5px - 10px)', { unwrapSingleValue: true });
 // => '-5px'
+
+reduceCalc('calc(1 / 2)', { unwrapSingleValue: true });
+// => '.5'
 ```
 
+The published `unwrapSingleNegativeNumber` option is retained as a deprecated
+alias for `unwrapSingleValue`.
+
 ### PostCSS plugin options
 
 These options apply when using the PostCSS plugin:
@@ -113,7 +120,8 @@ postcss().use(calc({ precision: 10 }));
 #### `precision` (default: `5`)
 
 Allows you to define the precision for decimal numbers. Set it to `false` to
-disable rounding.
+disable rounding and preserve full IEEE-754 floating-point precision (emitting
+the shortest round-tripping decimal representation).
 
 ```js
 var out = postcss()
@@ -121,6 +129,12 @@ var out = postcss()
   .process(css).css;
 ```
 
+#### `unwrapSingleValue` (default: `false`)
+
+Serializes fully resolved finite scalar results without calculation syntax.
+This can discard browser-applied range clamping or integer rounding. Selectors
+enable it automatically because selectors cannot contain `calc()`.
+
 #### `warnWhenCannotResolve` (default: `false`)
 
 Adds warnings when calc() are not reduced to a single value.
@@ -165,9 +179,9 @@ With `mediaQueries: true`, this becomes:
 
 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.
+Finite negative and fractional unitless results are serialized as bare values
+because a selector cannot contain a `calc()` function; the plugin enables the
+`unwrapSingleValue` automatically for selectors.
 
 ```js
 var out = postcss()
@@ -268,7 +282,15 @@ when changing parsing/simplification behavior:
 pnpm test:corpus:full
 ```
 
-Profile long arithmetic parser chains with `pnpm benchmark:arithmetic-chains`.
+Profile parser chains with `pnpm benchmark:arithmetic-chains` or
+`pnpm benchmark:nested-fallbacks`; both use 20 fresh paired blocks by default
+and write ignored schema-v2 reports. Compare a saved report with
+`node scripts/compare-parser-benchmarks.js <report>`. Run the correctness-aware
+corpus benchmark with `pnpm benchmark:corpus`.
+
+The PostCSS benchmark awaits `postcss().process(...)`, and that await already
+triggers result stringification. It therefore does not add a redundant
+`result.css` access.
 
 ## [Changelog](CHANGELOG.md)
 
@@ -281,5 +303,5 @@ Profile long arithmetic parser chains with `pnpm benchmark:arithmetic-chains`.
 [PostCSS]: https://github.com/postcss
 [PostCSS Calc]: https://github.com/postcss/postcss-calc
 [PostCSS Custom Properties]: https://github.com/postcss/postcss-custom-properties
-[tests]: test/index.js
+[tests]: test/
 [W3C calc() implementation]: https://www.w3.org/TR/css3-values/#calc-notation

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "postcss-calc",
-  "version": "11.1.2",
+  "version": "11.2.1",
   "type": "module",
   "description": "PostCSS plugin to reduce calc()",
   "keywords": [
@@ -38,21 +38,20 @@
   "devEngines": {
     "packageManager": {
       "name": "pnpm",
-      "version": "12.3.4"
+      "version": "12.4.2"
     }
   },
   "devDependencies": {
-    "@csstools/css-calc": "^3.3.0",
-    "@rmenke/css-tokenizer-tests": "^1.2.0",
-    "@types/node": "^26.5.0",
-    "fast-check": "^4.9.0",
-    "oxfmt": "^0.67.0",
-    "oxlint": "^1.82.0",
+    "@csstools/css-calc": "^3.4.0",
+    "@types/node": "^26.6.1",
+    "fast-check": "^4.10.1",
+    "oxfmt": "^0.68.0",
+    "oxlint": "^1.83.0",
     "postcss": "^8.5.28",
     "typescript": "~7.0.2"
   },
   "dependencies": {
-    "@csstools/css-tokenizer": "^4.0.0"
+    "@csstools/css-tokenizer": "^4.0.1"
   },
   "peerDependencies": {
     "postcss": "^8.5.28"
@@ -60,10 +59,15 @@
   "scripts": {
     "lint": "oxlint . && tsc && oxfmt --check",
     "fmt": "oxfmt",
-    "benchmark:arithmetic-chains": "node scripts/benchmark-arithmetic-chains.mjs",
-    "benchmark:nested-fallbacks": "node scripts/benchmark-nested-fallbacks.mjs",
-    "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"
+    "benchmark:arithmetic-chains": "node scripts/benchmark-arithmetic-chains.js",
+    "benchmark:nested-fallbacks": "node scripts/benchmark-nested-fallbacks.js",
+    "benchmark:corpus": "node scripts/benchmark.js",
+    "benchmark:serialization": "node scripts/benchmark-serialization.js",
+    "test:benchmark": "node --test 'test/unit/benchmark-*.test.js' test/unit/compare-parser-benchmarks.test.js test/unit/corpus-benchmark.test.js",
+    "test:benchmark:simulation": "node test/benchmark/statistical-simulation.js",
+    "benchmark:reanalyze": "node scripts/compare-parser-benchmarks.js",
+    "test": "node --test --test-reporter=dot 'test/**/*.test.js' 'test/**/*.test.cjs'",
+    "test:mutation:corpus": "node test/mutation/corpus-selection.js",
+    "test:corpus:full": "POSTCSS_CALC_FULL_CORPUS=1 node --test test/conformance/corpus.test.js"
   }
 }

package/src/index.js

@@ -1,12 +1,13 @@
 // PostCSS adapter over the standalone component-value reducer.
-import reduceCalc, { hasPotentialMathFunction } from './reduce.js';
-
+import reduceCalc from './reduce.js';
+import { hasPotentialMathFunction } from './lib/functions.js';
 /**
  * @typedef {object} PostCssCalcOptions
  * @property {number | false} [precision]
  * @property {boolean} [warnWhenCannotResolve]
  * @property {boolean} [mediaQueries]
  * @property {boolean} [selectors]
+ * @property {boolean} [unwrapSingleValue] Serialize fully resolved finite scalar results without calculation syntax. Defaults to `false`.
  * @property {(error: Error, input: string) => void} [onParseError] Invoked when parse/simplify throws. Replaces the default `result.warn`.
  */
 
@@ -24,7 +25,7 @@ import reduceCalc, { hasPotentialMathFunction } from './reduce.js';
  * @param {(target: import('postcss').ChildNode, value: string) => void} setProp
  * @param {ResolvedOptions} options
  * @param {import('postcss').Result} result
- * @param {boolean} unwrapSingleNegativeNumber
+ * @param {boolean} selectorContext
  * @return {void}
  */
 function applyTransform(
@@ -33,7 +34,7 @@ function applyTransform(
   setProp,
   options,
   result,
-  unwrapSingleNegativeNumber
+  selectorContext
 ) {
   if (!hasPotentialMathFunction(current)) {
     return;
@@ -49,7 +50,8 @@ function applyTransform(
     onWarn: (message) => {
       result.warn(message, { plugin: 'postcss-calc', node });
     },
-    unwrapSingleNegativeNumber,
+    // Selectors cannot contain calc(), so they always unwrap resolved values.
+    unwrapSingleValue: selectorContext || options.unwrapSingleValue,
   });
   if (transformed !== current) {
     setProp(node, transformed);
@@ -67,6 +69,7 @@ function pluginCreator(opts) {
     warnWhenCannotResolve: false,
     mediaQueries: false,
     selectors: false,
+    unwrapSingleValue: false,
     ...opts,
   };
 

package/src/lib/analyze.js

@@ -0,0 +1,272 @@
+import { baseOf } from './convertUnits.js';
+import {
+  addTypes,
+  failureType,
+  isFailure,
+  isPercentage,
+  mathFunctions,
+  numberType,
+  percentageType,
+  unknownType,
+} from './functions.js';
+import { assertDepth } from './limits.js';
+
+/** @typedef {import('./node.js').Node} Node */
+/** @typedef {import('./functions.js').CalculationType} CalculationType */
+/** @typedef {Extract<CalculationType, {kind: 'dimension'}>} DimensionType */
+
+/** @typedef {'number' | 'unknown' | {dimension: string | null}} AnalysisType */
+/** @typedef {{type: AnalysisType, valid: boolean, unresolved: boolean}} Analysis */
+/**
+ * @typedef {Object} ProductFactors
+ * @property {boolean} valid
+ * @property {boolean} structurallyValid
+ * @property {boolean} hasUnresolved
+ * @property {DimensionType | null} numerator
+ * @property {DimensionType | null} denominator
+ * @property {boolean} hasOpaqueNumerator
+ * @property {boolean} hasOpaqueDenominator
+ */
+
+/**
+ * Analyze the original complete tree and return its root summary. Analysis
+ * validates and classifies the tree; it is not a rewrite plan.
+ * @param {Node} node
+ * @return {Analysis}
+ */
+function analyze(node) {
+  const result = analyzeType(node);
+  return {
+    type: publicType(result.type),
+    valid: result.valid,
+    unresolved: result.unresolved,
+  };
+}
+
+/** @param {Node} node @param {number} [depth] @return {{type: CalculationType, valid: boolean, unresolved: boolean}} */
+function analyzeType(node, depth = 0) {
+  assertDepth(depth);
+  switch (node.type) {
+    case 'Num':
+      return resolved(numberType);
+    case 'Dim':
+      // Percentages are contextual; their percent-ness is tracked so a
+      // `% / %` product cancels to a number. Unknown units are opaque, while
+      // known families can still reject px + seconds.
+      return node.unit === '%'
+        ? finish(percentageType, true, true)
+        : resolved({ kind: 'dimension', base: baseOf(node.unit) });
+    case 'Ident':
+      return markUnresolved(unknownType);
+    case 'Sum':
+      return analyzeSum(node, depth);
+    case 'Product':
+      return analyzeProduct(node, depth);
+    case 'Call':
+      return analyzeCall(node, depth);
+    case 'OpaqueCall':
+      return finish(unknownType, true, true);
+  }
+}
+
+/** @param {Extract<Node, {type: 'Sum'}>} node @param {number} depth @return {{type: CalculationType, valid: boolean, unresolved: boolean}} */
+function analyzeSum(node, depth) {
+  let type = null;
+  let hasUnknown = false;
+  let hasPercentage = false;
+  let valid = true;
+  let hasUnresolved = false;
+  for (const term of node.terms) {
+    const child = analyzeType(term.node, depth + 1);
+    valid = valid && child.valid;
+    hasUnresolved = hasUnresolved || child.unresolved;
+    if (isFailure(child.type)) {
+      type = failureType;
+    } else if (child.type.kind === 'unknown') {
+      // A pure percentage sum stays percentage-typed so a surrounding
+      // product can cancel `% / %`; any other opaque term must widen the
+      // sum back to unknown.
+      if (isPercentage(child.type)) hasPercentage = true;
+      else hasUnknown = true;
+    } else if (type === null) {
+      type = child.type;
+    } else if (!isFailure(type)) {
+      type = addTypes(type, child.type);
+    }
+  }
+  if (type !== null && isFailure(type)) {
+    return finish(failureType, false, hasUnresolved);
+  }
+  let fallback = numberType;
+  if (hasUnknown) fallback = unknownType;
+  else if (hasPercentage) fallback = percentageType;
+  return finish(type ?? fallback, valid, hasUnresolved);
+}
+
+/** @param {Extract<Node, {type: 'Product'}>} node @param {number} depth @return {{type: CalculationType, valid: boolean, unresolved: boolean}} */
+function analyzeProduct(node, depth) {
+  let numerator = null;
+  let denominator = null;
+  let valid = true;
+  let structurallyValid = true;
+  // Opaque factors (unknowns and pure percentages) are counted per side so
+  // the pass below can decide whether any unknown remains after cancelling
+  // `% / %` pairs.
+  let opaqueNumerator = 0;
+  let opaqueDenominator = 0;
+  let percentageNumerator = 0;
+  let percentageDenominator = 0;
+  let hasUnresolved = false;
+  for (const factor of node.factors) {
+    const child = analyzeType(factor.node, depth + 1);
+    valid = valid && child.valid;
+    hasUnresolved = hasUnresolved || child.unresolved;
+    if (isFailure(child.type)) {
+      continue;
+    }
+    if (child.type.kind === 'unknown') {
+      if (factor.exponent === 1) {
+        opaqueNumerator++;
+        if (isPercentage(child.type)) percentageNumerator++;
+      } else {
+        opaqueDenominator++;
+        if (isPercentage(child.type)) percentageDenominator++;
+      }
+      continue;
+    }
+    if (child.type.kind !== 'dimension') continue;
+    if (factor.exponent === 1) {
+      if (numerator !== null) structurallyValid = false;
+      else numerator = child.type;
+    } else {
+      if (denominator !== null) structurallyValid = false;
+      else denominator = child.type;
+    }
+  }
+  // A percentage divided by a percentage is always a plain number: both
+  // operands resolve in the same context, so their contextual type cancels.
+  // Consume one such pair before judging the remaining unknowns so a
+  // surrounding sum does not mistake `% / %` for a length-compatible term.
+  const cancelled = Math.min(percentageNumerator, percentageDenominator);
+  const hasOpaqueNumerator = opaqueNumerator - cancelled > 0;
+  const hasOpaqueDenominator = opaqueDenominator - cancelled > 0;
+  return finishProduct({
+    valid,
+    structurallyValid,
+    hasUnresolved,
+    numerator,
+    denominator,
+    hasOpaqueNumerator,
+    hasOpaqueDenominator,
+  });
+}
+
+/**
+ * Classify a product once its factors are analyzed. Opaque factors can supply
+ * missing type information, but they cannot make an already-invalid
+ * combination of known dimensions valid.
+ * @param {ProductFactors} factors
+ * @return {{type: CalculationType, valid: boolean, unresolved: boolean}}
+ */
+function finishProduct(factors) {
+  const { valid, structurallyValid, hasUnresolved } = factors;
+  if (!valid) return finish(failureType, false, hasUnresolved);
+  if (!structurallyValid) return finish(failureType, false, hasUnresolved);
+  const { numerator, denominator } = factors;
+  if (
+    numerator !== null &&
+    denominator !== null &&
+    numerator.base !== denominator.base
+  ) {
+    return finish(failureType, false, hasUnresolved);
+  }
+  // An unresolved numerator multiplied by one known numerator dimension can
+  // only leave that dimension in place (when it resolves to a number) or make
+  // the product invalid. It can never make the product a bare number. Keep
+  // that known constraint so a surrounding sum can reject `1px * 1% + 1`.
+  const constrained = constrainedNumerator(factors);
+  if (constrained !== null) {
+    return finish(constrained, true, hasUnresolved);
+  }
+  // Other opaque factors may supply type information that changes how the
+  // known dimensions combine once the known factors are structurally valid.
+  if (factors.hasOpaqueNumerator || factors.hasOpaqueDenominator) {
+    return finish(unknownType, true, hasUnresolved);
+  }
+  if (numerator !== null && denominator !== null) {
+    return finish(
+      numerator.base === denominator.base ? numberType : failureType,
+      valid && numerator.base === denominator.base,
+      hasUnresolved
+    );
+  }
+  if (denominator !== null) return finish(failureType, false, hasUnresolved);
+  return finish(numerator ?? numberType, valid, hasUnresolved);
+}
+
+/**
+ * @param {ProductFactors} factors
+ * @return {DimensionType | null}
+ */
+function constrainedNumerator(factors) {
+  return factors.hasOpaqueNumerator &&
+    !factors.hasOpaqueDenominator &&
+    factors.numerator !== null &&
+    factors.denominator === null
+    ? factors.numerator
+    : null;
+}
+
+/** @param {Extract<Node, {type: 'Call'}>} node @param {number} depth @return {{type: CalculationType, valid: boolean, unresolved: boolean}} */
+function analyzeCall(node, depth) {
+  const name = node.name.toLowerCase();
+  const definition = mathFunctions.get(name);
+  /** @type {CalculationType[]} */
+  const childTypes = [];
+  let valid = true;
+  let unresolvedArgs = false;
+  for (let index = 0; index < node.args.length; index++) {
+    const child = analyzeType(node.args[index], depth + 1);
+    childTypes.push(child.type);
+    valid = valid && child.valid;
+    if (!definition?.isKeyword?.(node.args[index], index) && child.unresolved) {
+      unresolvedArgs = true;
+    }
+  }
+  if (!definition) return finish(unknownType, valid, true);
+  const type = definition.analyze(childTypes, node.args);
+  const unresolvedType = type.kind === 'unknown';
+  return finish(
+    type,
+    valid && !isFailure(type),
+    unresolvedArgs || unresolvedType
+  );
+}
+
+/** @param {CalculationType} type @param {boolean} valid @param {boolean} unresolved @return {{type: CalculationType, valid: boolean, unresolved: boolean}} */
+function finish(type, valid, unresolved) {
+  return {
+    type,
+    valid: valid && !isFailure(type),
+    unresolved,
+  };
+}
+
+/** @param {CalculationType} type @return {{type: CalculationType, valid: boolean, unresolved: boolean}} */
+function resolved(type) {
+  return finish(type, true, false);
+}
+
+/** @param {CalculationType} type @return {{type: CalculationType, valid: boolean, unresolved: boolean}} */
+function markUnresolved(type) {
+  return finish(type, true, true);
+}
+
+/** @param {CalculationType} type @return {AnalysisType} */
+function publicType(type) {
+  if (type.kind === 'number') return 'number';
+  if (type.kind === 'unknown' || type.kind === 'failure') return 'unknown';
+  return { dimension: type.base };
+}
+
+export { analyze };

package/src/lib/block-index.js

@@ -0,0 +1,118 @@
+import { TokenType as CssType } from '@csstools/css-tokenizer';
+
+/** @typedef {import('@csstools/css-tokenizer').CSSToken} CSSToken */
+
+const BLOCK_CLOSE = new Map([
+  [CssType.Function, CssType.CloseParen],
+  [CssType.OpenParen, CssType.CloseParen],
+  [CssType.OpenSquare, CssType.CloseSquare],
+  [CssType.OpenCurly, CssType.CloseCurly],
+]);
+
+/**
+ * Read-only delimiter navigation for one native token stream range.
+ */
+class BlockIndex {
+  /** @type {CSSToken[]} */
+  #tokens;
+  /** @type {number} */
+  #rangeStart;
+  /** @type {number} */
+  #rangeEnd;
+  /** @type {Map<number, number>} */
+  #closes = new Map();
+  /** @type {number} */
+  #maxDepth = 0;
+
+  /**
+   * Build the delimiter index once for a token stream range. Matching remains
+   * LIFO: a mismatched closer is ignored and does not disturb the open stack.
+   *
+   * @param {CSSToken[]} tokens
+   * @param {number} start
+   * @param {number} end
+   */
+  constructor(tokens, start, end) {
+    this.#tokens = tokens;
+    this.#rangeStart = Math.max(0, start);
+    this.#rangeEnd = Math.min(tokens.length, Math.max(this.#rangeStart, end));
+    /** @type {{index: number, close: import('@csstools/css-tokenizer').TokenType}[]} */
+    const stack = [];
+
+    for (let i = this.#rangeStart; i < this.#rangeEnd; i++) {
+      const type = tokens[i][0];
+      const close = BLOCK_CLOSE.get(type);
+      if (close !== undefined) {
+        stack.push({ index: i, close });
+        this.#maxDepth = Math.max(this.#maxDepth, stack.length);
+        continue;
+      }
+
+      if (
+        type === CssType.CloseParen ||
+        type === CssType.CloseSquare ||
+        type === CssType.CloseCurly
+      ) {
+        const open = stack.at(-1);
+        if (open === undefined || open.close !== type) {
+          continue;
+        }
+        stack.pop();
+        this.#closes.set(open.index, i);
+      }
+    }
+  }
+
+  /** @return {number} */
+  get maxDepth() {
+    return this.#maxDepth;
+  }
+
+  /** @param {number | undefined} end @return {number} */
+  #boundedEnd(end) {
+    return Math.min(
+      this.#rangeEnd,
+      Math.max(this.#rangeStart, end ?? this.#rangeEnd)
+    );
+  }
+
+  /** @param {number} openPosition @param {number} [endPosition] @return {number} */
+  closeOf(openPosition, endPosition) {
+    const close = this.#closes.get(openPosition) ?? -1;
+    const bound = this.#boundedEnd(endPosition);
+    return close >= this.#rangeStart && close < bound ? close : -1;
+  }
+
+  /** @param {number} position @param {number} endPosition @return {number} */
+  nextComponent(position, endPosition) {
+    const bound = this.#boundedEnd(endPosition);
+    if (position < this.#rangeStart || position >= bound) return bound;
+    const close = this.closeOf(position, bound);
+    return close === -1 ? position + 1 : close + 1;
+  }
+
+  /** @param {number} startPosition @param {number} endPosition @return {number} */
+  firstTopLevelComma(startPosition, endPosition) {
+    const bound = this.#boundedEnd(endPosition);
+    for (let i = Math.max(this.#rangeStart, startPosition); i < bound;) {
+      if (this.#tokens[i][0] === CssType.Comma) return i;
+      i = this.nextComponent(i, bound);
+    }
+    return -1;
+  }
+}
+
+/**
+ * Build the delimiter index once for a token stream range. Matching remains
+ * LIFO: a mismatched closer is ignored and does not disturb the open stack.
+ *
+ * @param {CSSToken[]} tokens
+ * @param {number} [start]
+ * @param {number} [end]
+ * @return {BlockIndex}
+ */
+function indexBlocks(tokens, start = 0, end = tokens.length) {
+  return new BlockIndex(tokens, start, end);
+}
+
+export { indexBlocks };