postcss-calc 11.1.2 → 11.2.1

package/src/lib/compile.js

@@ -0,0 +1,80 @@
+import { parse } from './parser.js';
+import { simplify } from './simplify.js';
+import { analyze } from './analyze.js';
+
+/** @typedef {import('./scan.js').Candidate} Candidate */
+/** @typedef {import('../reduce.js').ResolvedReduceCalcOptions} ResolvedReduceCalcOptions */
+/** @typedef {import('../reduce.js').Replacement} Replacement */
+/** @typedef {import('@csstools/css-tokenizer').CSSToken} CSSToken */
+/** @typedef {ReturnType<typeof import('./block-index.js').indexBlocks>} BlockIndex */
+/** @typedef {{options: ResolvedReduceCalcOptions, value: string, tokens: CSSToken[], index: BlockIndex}} CompileContext */
+
+/**
+ * Parse, analyze, and simplify one candidate. Analysis is the validity/status
+ * gate over the original tree; simplification then runs independently as a
+ * composable AST transformation that may synthesize nodes.
+ *
+ * @param {Candidate} candidate
+ * @param {CompileContext} ctx
+ * @return {Replacement}
+ */
+function compileCandidate(candidate, ctx) {
+  if (!candidate.closed) {
+    throw new Error(
+      `Unclosed ${candidate.name}( at position ${candidate.start}`
+    );
+  }
+  const parsed = parse(
+    ctx.tokens,
+    candidate.sliceStart,
+    candidate.sliceEnd,
+    ctx.index
+  );
+  const analysis = analyze(parsed);
+  if (!analysis.valid) {
+    throw new Error('Invalid CSS calculation type');
+  }
+  const tree = simplify(parsed);
+  const original =
+    analysis.unresolved && !candidate.calculation
+      ? ctx.value.slice(candidate.start, candidate.end)
+      : undefined;
+  return {
+    start: candidate.start,
+    end: candidate.end,
+    result: {
+      tree,
+      status: analysis.unresolved ? 'unresolved' : 'resolved',
+      rootName: candidate.normalizedName,
+      rootSpelling: candidate.rootSpelling,
+      calculation: candidate.calculation,
+      original,
+    },
+  };
+}
+
+/**
+ * Compile candidates independently so one malformed calculation is preserved
+ * without preventing unrelated candidates from being reduced.
+ *
+ * @param {Candidate[]} candidates
+ * @param {CompileContext} ctx
+ * @return {Replacement[]}
+ */
+function compileCandidates(candidates, ctx) {
+  /** @type {Replacement[]} */
+  const replacements = [];
+  for (const candidate of candidates) {
+    try {
+      replacements.push(compileCandidate(candidate, ctx));
+    } catch (error) {
+      ctx.options.onParseError?.(
+        error instanceof Error ? error : new Error('Error', { cause: error }),
+        ctx.value.slice(candidate.start, candidate.end)
+      );
+    }
+  }
+  return replacements;
+}
+
+export { compileCandidate, compileCandidates };

package/src/lib/functions.js

@@ -0,0 +1,394 @@
+import { simplifyMinMax } from './simplify/min-max.js';
+import { simplifyClamp } from './simplify/clamp.js';
+import { simplifyAbs } from './simplify/abs.js';
+import { simplifySign } from './simplify/sign.js';
+import { simplifyModRem } from './simplify/mod-rem.js';
+import { ROUND_STRATEGIES, simplifyRound } from './simplify/round.js';
+import { simplifyTrig } from './simplify/trig.js';
+import { simplifyInverseTrig } from './simplify/inverse-trig.js';
+import { simplifyAtan2 } from './simplify/atan2.js';
+import { simplifyPow } from './simplify/pow.js';
+import { simplifySqrt } from './simplify/sqrt.js';
+import { simplifyExp } from './simplify/exp.js';
+import { simplifyLog } from './simplify/log.js';
+import { simplifyHypot } from './simplify/hypot.js';
+
+/** @typedef {import('./node.js').Node} Node */
+/**
+ * `percent` marks a value that resolves in the same percentage context as its
+ * peers (a pure percentage). It is only produced at leaves, by abs(), and by
+ * homogeneous sums and calls — never by a product, where an unpaired
+ * percentage could no longer cancel against anything.
+ * @typedef {{kind: 'number'} | {kind: 'dimension', base: string | null} | {kind: 'unknown', percent?: true} | {kind: 'failure'}} CalculationType
+ */
+/** @typedef {(name: string, args: Node[]) => Node} MathSimplifier */
+/** @typedef {(args: CalculationType[], nodes: Node[]) => CalculationType} TypeAnalyzer */
+/** @typedef {{analyze: TypeAnalyzer, simplify?: MathSimplifier, isKeyword?: (node: Node, index: number) => boolean, calculation?: boolean}} MathFunction */
+
+/** @type {CalculationType} */ const numberType = { kind: 'number' };
+/** @type {CalculationType} */ const unknownType = { kind: 'unknown' };
+/** @type {CalculationType} */ const percentageType = {
+  kind: 'unknown',
+  percent: true,
+};
+/** @type {CalculationType} */ const failureType = { kind: 'failure' };
+
+/** @param {CalculationType} type @return {boolean} */
+function isFailure(type) {
+  return type.kind === 'failure';
+}
+
+/** @param {CalculationType} type @return {boolean} */
+function isPercentage(type) {
+  return type.kind === 'unknown' && type.percent === true;
+}
+
+/** @param {CalculationType} a @param {CalculationType} b @return {CalculationType} */
+function addTypes(a, b) {
+  if (isFailure(a) || isFailure(b)) return failureType;
+  if (a.kind === 'unknown' || b.kind === 'unknown') {
+    // A pure percentage keeps its contextual type so a surrounding product
+    // can cancel `% / %`; mixing it with any other opaque operand loses the
+    // guarantee that it resolves in the same context as its peers. A known
+    // number + percentage sum is likewise kept unknown and valid: the spec
+    // resolves the percentage against its surrounding context, which this
+    // coarse type model does not track.
+    return isPercentage(a) && isPercentage(b) ? percentageType : unknownType;
+  }
+  if (a.kind === 'number' && b.kind === 'number') return numberType;
+  if (a.kind === 'dimension' && b.kind === 'dimension') {
+    if (a.base === null || b.base === null) return unknownType;
+    return a.base === b.base ? a : failureType;
+  }
+  return failureType;
+}
+
+/**
+ * Check an all-number function without assuming anything about an unresolved
+ * operand. A concrete dimension can never become a number, so it is still a
+ * definite error when another argument is opaque.
+ * @param {CalculationType[]} args
+ * @param {number} min
+ * @param {number} max
+ * @return {CalculationType}
+ */
+function numberArguments(args, min, max) {
+  if (args.length < min || args.length > max) return failureType;
+  let hasUnknown = false;
+  for (const arg of args) {
+    if (arg.kind === 'dimension') return failureType;
+    hasUnknown = hasUnknown || arg.kind === 'unknown';
+  }
+  return hasUnknown ? unknownType : numberType;
+}
+
+/**
+ * Check values that must share a calculation type. Unknown operands remain
+ * unknown: they might resolve to the concrete type required by their peers.
+ * @param {CalculationType[]} args
+ * @param {number} min
+ * @param {number} max
+ * @return {CalculationType}
+ */
+function matchingArguments(args, min, max) {
+  if (args.length < min || args.length > max) return failureType;
+  let result = args[0];
+  for (let index = 1; index < args.length; index++) {
+    result = addTypes(result, args[index]);
+    if (isFailure(result)) return failureType;
+  }
+  return result;
+}
+
+/** @param {CalculationType[]} args @return {CalculationType} */
+function analyzeTrig(args) {
+  return args.length === 1 &&
+    (args[0].kind === 'unknown' ||
+      args[0].kind === 'number' ||
+      (args[0].kind === 'dimension' && args[0].base === 'angle'))
+    ? numberType
+    : failureType;
+}
+
+/** @param {CalculationType[]} args @return {CalculationType} */
+function analyzeInverseTrig(args) {
+  if (args.length !== 1 || args[0].kind === 'dimension') {
+    return failureType;
+  }
+  return args[0].kind === 'unknown'
+    ? unknownType
+    : { kind: 'dimension', base: 'angle' };
+}
+
+/** @param {CalculationType[]} args @return {CalculationType} */
+function analyzeIdentity(args) {
+  return args.length === 1 ? args[0] : failureType;
+}
+
+/** @param {CalculationType[]} args @return {CalculationType} */
+function analyzeSign(args) {
+  return args.length === 1 ? numberType : failureType;
+}
+
+/** @param {CalculationType[]} args @param {Node[]} nodes @return {CalculationType} */
+function analyzeRound(args, nodes) {
+  const strategy = nodes[0];
+  const hasStrategy =
+    strategy?.type === 'Ident' &&
+    ROUND_STRATEGIES.has(strategy.name.toLowerCase());
+  const start = hasStrategy ? 1 : 0;
+  const valueCount = args.length - start;
+  if (valueCount === 1) {
+    const value = args[start];
+    if (value.kind === 'dimension') return failureType;
+    if (value.kind === 'unknown') return unknownType;
+    return numberType;
+  }
+  if (valueCount !== 2) return failureType;
+  const type = addTypes(args[start], args[start + 1]);
+  return isFailure(type) ? failureType : type;
+}
+
+/** @param {CalculationType[]} args @return {CalculationType} */
+function analyzeAtan2(args) {
+  const type = matchingArguments(args, 2, 2);
+  if (isFailure(type)) return type;
+  // The type table gives atan2() «["angle" → 1]»; an unresolved result is
+  // plain unknown, never the percentage of its arguments.
+  if (type.kind === 'unknown') return unknownType;
+  return { kind: 'dimension', base: 'angle' };
+}
+
+/** @param {CalculationType[]} args @return {CalculationType} */
+function analyzeCalc(args) {
+  return args.length === 1 ? args[0] : failureType;
+}
+
+/** @param {Node} node @return {boolean} */
+function isRoundStrategy(node) {
+  return node.type === 'Ident' && ROUND_STRATEGIES.has(node.name.toLowerCase());
+}
+
+/** @param {Node} node @param {number} index @return {boolean} */
+function isClampKeyword(node, index) {
+  return (
+    (index === 0 || index === 2) &&
+    node.type === 'Ident' &&
+    node.name.toLowerCase() === 'none'
+  );
+}
+
+/** @param {CalculationType[]} args @param {Node[]} nodes @return {CalculationType} */
+function analyzeClamp(args, nodes) {
+  if (args.length !== 3) return failureType;
+  let valueCount = 0;
+  /** @type {CalculationType} */ let result = failureType;
+  for (let index = 0; index < args.length; index++) {
+    if (isClampKeyword(nodes[index], index)) continue;
+    result = valueCount === 0 ? args[index] : addTypes(result, args[index]);
+    valueCount++;
+  }
+  if (valueCount < 1 || isFailure(result)) return failureType;
+  return result;
+}
+
+const mathFunctions = new Map(
+  /** @type {[string, MathFunction][]} */ ([
+    ['calc', { analyze: analyzeCalc, calculation: true }],
+    ['-webkit-calc', { analyze: analyzeCalc, calculation: true }],
+    ['-moz-calc', { analyze: analyzeCalc, calculation: true }],
+    [
+      'min',
+      {
+        analyze: (args) => matchingArguments(args, 1, Infinity),
+        simplify: simplifyMinMax,
+      },
+    ],
+    [
+      'max',
+      {
+        analyze: (args) => matchingArguments(args, 1, Infinity),
+        simplify: simplifyMinMax,
+      },
+    ],
+    [
+      'clamp',
+      {
+        analyze: analyzeClamp,
+        simplify: (_name, args) => simplifyClamp(args),
+        isKeyword: isClampKeyword,
+      },
+    ],
+    [
+      'abs',
+      {
+        analyze: analyzeIdentity,
+        simplify: (_name, args) => simplifyAbs(args),
+      },
+    ],
+    [
+      'sign',
+      {
+        analyze: analyzeSign,
+        simplify: (_name, args) => simplifySign(args),
+      },
+    ],
+    [
+      'mod',
+      {
+        analyze: (args) => matchingArguments(args, 2, 2),
+        simplify: (_name, args) => simplifyModRem('mod', args),
+      },
+    ],
+    [
+      'rem',
+      {
+        analyze: (args) => matchingArguments(args, 2, 2),
+        simplify: (_name, args) => simplifyModRem('rem', args),
+      },
+    ],
+    [
+      'round',
+      {
+        analyze: analyzeRound,
+        simplify: (_name, args) => simplifyRound(args),
+        isKeyword: (node, index) => index === 0 && isRoundStrategy(node),
+      },
+    ],
+    [
+      'sin',
+      {
+        analyze: analyzeTrig,
+        simplify: (_name, args) => simplifyTrig('sin', args),
+      },
+    ],
+    [
+      'cos',
+      {
+        analyze: analyzeTrig,
+        simplify: (_name, args) => simplifyTrig('cos', args),
+      },
+    ],
+    [
+      'tan',
+      {
+        analyze: analyzeTrig,
+        simplify: (_name, args) => simplifyTrig('tan', args),
+      },
+    ],
+    [
+      'asin',
+      {
+        analyze: analyzeInverseTrig,
+        simplify: (_name, args) => simplifyInverseTrig('asin', args),
+      },
+    ],
+    [
+      'acos',
+      {
+        analyze: analyzeInverseTrig,
+        simplify: (_name, args) => simplifyInverseTrig('acos', args),
+      },
+    ],
+    [
+      'atan',
+      {
+        analyze: analyzeInverseTrig,
+        simplify: (_name, args) => simplifyInverseTrig('atan', args),
+      },
+    ],
+    [
+      'atan2',
+      {
+        analyze: analyzeAtan2,
+        simplify: (_name, args) => simplifyAtan2(args),
+      },
+    ],
+    [
+      'pow',
+      {
+        analyze: (args) => numberArguments(args, 2, 2),
+        simplify: (_name, args) => simplifyPow(args),
+      },
+    ],
+    [
+      'sqrt',
+      {
+        analyze: (args) => numberArguments(args, 1, 1),
+        simplify: (_name, args) => simplifySqrt(args),
+      },
+    ],
+    [
+      'hypot',
+      {
+        analyze: (args) => matchingArguments(args, 1, Infinity),
+        simplify: (_name, args) => simplifyHypot(args),
+      },
+    ],
+    [
+      'log',
+      {
+        analyze: (args) => numberArguments(args, 1, 2),
+        simplify: (_name, args) => simplifyLog(args),
+      },
+    ],
+    [
+      'exp',
+      {
+        analyze: (args) => numberArguments(args, 1, 1),
+        simplify: (_name, args) => simplifyExp(args),
+      },
+    ],
+  ])
+);
+
+/**
+ * @param {string} name
+ * @return {{normalizedName: string, definition: MathFunction} | undefined}
+ */
+function lookupMathFunction(name) {
+  const normalizedName = name.toLowerCase();
+  const definition = mathFunctions.get(normalizedName);
+  return definition === undefined ? undefined : { normalizedName, definition };
+}
+
+const mathFunctionNames = [...mathFunctions.keys()];
+const QUICK_MATH_TEST = new RegExp(
+  `(?:${mathFunctionNames.join('|')})\\(`,
+  'i'
+);
+
+/** @param {string} name @return {boolean} */
+function isCalculationFunction(name) {
+  return mathFunctions.get(name.toLowerCase())?.calculation === true;
+}
+
+/** @param {string} name @return {boolean} */
+function isSupportedMathFunction(name) {
+  const normalizedName = name.toLowerCase();
+  const definition = mathFunctions.get(normalizedName);
+  return definition !== undefined && definition.calculation !== true;
+}
+
+/** @param {string} value @return {boolean} */
+function hasPotentialMathFunction(value) {
+  return (
+    value.includes('(') && (QUICK_MATH_TEST.test(value) || value.includes('\\'))
+  );
+}
+
+export {
+  addTypes,
+  failureType,
+  hasPotentialMathFunction,
+  isCalculationFunction,
+  isFailure,
+  isPercentage,
+  isSupportedMathFunction,
+  lookupMathFunction,
+  mathFunctions,
+  numberType,
+  percentageType,
+  QUICK_MATH_TEST,
+  unknownType,
+};

package/src/lib/limits.js

@@ -0,0 +1,49 @@
+/** @typedef {import('./node.js').Node} Node */
+
+const MAX_CALCULATION_DEPTH = 1024;
+
+/** @param {number} depth @return {void} */
+function assertDepth(depth) {
+  if (depth > MAX_CALCULATION_DEPTH) {
+    throw new Error(
+      `Calculation nesting exceeds the limit of ${MAX_CALCULATION_DEPTH}`
+    );
+  }
+}
+
+/** @param {unknown} part @param {number} depth @return {void} */
+function checkOpaquePartDepth(part, depth) {
+  assertDepth(depth);
+  if (typeof part === 'string') return;
+  if (Array.isArray(part)) {
+    for (const child of part) checkOpaquePartDepth(child, depth + 1);
+    return;
+  }
+  checkCalculationDepth(/** @type {Node} */ (part), depth + 1);
+}
+
+/** @param {Node} node @param {number} [depth] @return {void} */
+function checkCalculationDepth(node, depth = 0) {
+  assertDepth(depth);
+  switch (node.type) {
+    case 'Sum':
+      for (const term of node.terms) {
+        checkCalculationDepth(term.node, depth + 1);
+      }
+      return;
+    case 'Product':
+      for (const factor of node.factors) {
+        checkCalculationDepth(factor.node, depth + 1);
+      }
+      return;
+    case 'Call':
+      for (const child of node.args) checkCalculationDepth(child, depth + 1);
+      return;
+    case 'OpaqueCall':
+      for (const part of node.components) {
+        checkOpaquePartDepth(part, depth + 1);
+      }
+  }
+}
+
+export { MAX_CALCULATION_DEPTH, assertDepth, checkCalculationDepth };

package/src/lib/node.js

@@ -11,7 +11,11 @@
 //   - No Product directly contains another Product (flattened).
 //   - A Sum/Product with one positive element collapses to that element.
 //   - A Sum/Product with no elements collapses to Num(0) / Num(1).
-//   - Zero-valued Nums are dropped from sums (they contribute nothing).
+//   - Positive zero-valued Nums are dropped from all-number sums. They are
+//     retained in mixed or unresolved sums because they constrain the other
+//     terms to <number>. Negative zero is retained until calculation
+//     evaluation has finished, because it is an IEEE-754 value with observable
+//     math-function behavior.
 //     Zero-valued Dims are kept — the unit carries type info.
 
 /**
@@ -19,11 +23,13 @@
  * @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 {string | Node | OpaqueComponent[]} OpaqueComponent
+ * @typedef {{type: 'OpaqueCall', name: string, components: OpaqueComponent[], rawName?: string}} OpaqueCall
  * @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.
  * @typedef {{type: 'Product', factors: ProductFactor[]}} Product
- * @typedef {Num | Dim | Ident | Call | Sum | Product} Node
+ * @typedef {Num | Dim | Ident | Call | OpaqueCall | Sum | Product} Node
  */
 
 /**
@@ -69,6 +75,18 @@ function call(name, args, rawName) {
     : { type: 'Call', name, args, rawName };
 }
 
+/**
+ * @param {string} name
+ * @param {OpaqueComponent[]} components
+ * @param {string} [rawName]
+ * @return {OpaqueCall}
+ */
+function opaqueCall(name, components, rawName) {
+  return rawName === undefined
+    ? { type: 'OpaqueCall', name, components }
+    : { type: 'OpaqueCall', name, components, rawName };
+}
+
 /**
  * @param {SumTerm[]} rawTerms
  * @return {Node}
@@ -76,13 +94,32 @@ function call(name, args, rawName) {
 function mkSum(rawTerms) {
   /** @type {SumTerm[]} */
   const flat = [];
+  let hasNegativeZero = false;
   for (const t of rawTerms) {
-    pushSumTerm(flat, t);
+    if (pushSumTerm(flat, t)) hasNegativeZero = true;
   }
-  if (flat.length === 0) {
+  const zeroIsTypeAnchor = flat.some((term) => term.node.type !== 'Num');
+  // `+0 + -0` evaluates to +0. Keep positive zero terms when the sum also
+  // contains -0 so simplification can perform that IEEE-754 operation before
+  // the canonical zero-elision below.
+  let length = 0;
+  for (let i = 0; i < flat.length; i++) {
+    const term = flat[i];
+    if (
+      !hasNegativeZero &&
+      !zeroIsTypeAnchor &&
+      term.node.type === 'Num' &&
+      term.node.value === 0
+    ) {
+      continue;
+    }
+    flat[length++] = term;
+  }
+  flat.length = length;
+  if (length === 0) {
     return num(0);
   }
-  if (flat.length === 1 && flat[0].sign === 1) {
+  if (length === 1 && flat[0].sign === 1) {
     return flat[0].node;
   }
   return { type: 'Sum', terms: flat };
@@ -91,19 +128,24 @@ function mkSum(rawTerms) {
 /**
  * @param {SumTerm[]} out
  * @param {SumTerm} term
- * @return {void}
+ * @return {boolean} Whether the appended terms contain negative zero.
  */
 function pushSumTerm(out, term) {
   let { sign, node } = term;
 
   if (node.type === 'Sum' && !node.grouped) {
+    let hasNegativeZero = false;
     for (const inner of node.terms) {
-      pushSumTerm(out, {
-        sign: /** @type {1 | -1} */ (sign * inner.sign),
-        node: inner.node,
-      });
+      if (
+        pushSumTerm(out, {
+          sign: /** @type {1 | -1} */ (sign * inner.sign),
+          node: inner.node,
+        })
+      ) {
+        hasNegativeZero = true;
+      }
     }
-    return;
+    return hasNegativeZero;
   }
 
   // sign=-1 around a Num/Dim leaf collapses into the value's sign — the
@@ -113,12 +155,8 @@ function pushSumTerm(out, term) {
     sign = 1;
   }
 
-  // Drop zero-valued Nums. Dims with value 0 stay — the unit carries type.
-  if (node.type === 'Num' && node.value === 0) {
-    return;
-  }
-
   out.push({ sign, node });
+  return node.type === 'Num' && Object.is(node.value, -0);
 }
 
 /**
@@ -176,19 +214,23 @@ function negate(node) {
     return dim(-node.value, node.unit, node.rawUnit);
   }
   if (node.type === 'Sum') {
+    // A grouped sum may contain opaque terms whose meaning depends on the
+    // surrounding context. Keep the group intact so `-1 * (a + b)` cannot turn
+    // into `-a - b` while it is still unresolved.
+    if (node.grouped) {
+      return mkSum([{ sign: -1, node }]);
+    }
     const result = mkSum(
       node.terms.map((t) => ({
         sign: /** @type {1 | -1} */ (-t.sign),
         node: t.node,
       }))
     );
-    return node.grouped && result.type === 'Sum'
-      ? { ...result, grouped: true }
-      : result;
+    return result;
   }
-  // Opaque (Ident, Call, Product): wrap as a single negative-sign term —
+  // Opaque (Ident, Call, OpaqueCall, Product): wrap as a single negative-sign term —
   // the only case where sign=-1 remains on a SumTerm.
   return mkSum([{ sign: -1, node }]);
 }
 
-export { num, dim, ident, call, mkSum, mkProduct, negate };
+export { num, dim, ident, call, opaqueCall, mkSum, mkProduct, negate };