postcss-calc 10.1.1 → 11.0.0-rc.1

package/src/lib/parser.js

@@ -0,0 +1,314 @@
+'use strict';
+
+// Pratt parser. +/- emit Sum nodes; */÷ emit Product nodes. node.js
+// constructors flatten and normalize on construction, so the parser
+// never produces a Binary node.
+
+const { mkSum, mkProduct, negate } = require('./node.js');
+
+/**
+ * @typedef {import('./tokenizer.js').Token} Token
+ * @typedef {import('./tokenizer.js').TokenType} TokenType
+ * @typedef {import('./node.js').Node} Node
+ * @typedef {(p: Parser, token: Token) => Node} PrefixParselet
+ * @typedef {{lbp: number, parse: (p: Parser, left: Node, token: Token) => Node}} InfixParselet
+ */
+
+/**
+ * @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
+ * @return {Node | null}
+ */
+function foldCalcKeyword(name) {
+  // `NaN` and `-NaN` are spec-defined math constants (§10.7.1). The signed
+  // form arrives as a single ident because CSS Syntax tokenizes leading
+  // `-` + ident-start as one ident-token.
+  if (name === 'NaN' || name === '-NaN') {
+    return { type: 'Num', value: NaN };
+  }
+  switch (name.toLowerCase()) {
+    case 'pi':
+      return { type: 'Num', value: Math.PI };
+    case 'e':
+      return { type: 'Num', value: Math.E };
+    case 'infinity':
+      return { type: 'Num', value: Infinity };
+    case '-infinity':
+      return { type: 'Num', value: -Infinity };
+  }
+  return null;
+}
+
+class Parser {
+  /**
+   * @param {Token[]} tokens
+   */
+  constructor(tokens) {
+    /** @private */
+    this.i = 0;
+    /** @private @readonly */
+    this.tokens = tokens;
+  }
+
+  /** @return {Token} */
+  peek() {
+    return this.tokens[this.i];
+  }
+
+  /** @return {Token} */
+  next() {
+    return this.tokens[this.i++];
+  }
+
+  /**
+   * @param {TokenType} type
+   * @param {string} [value]
+   * @return {Token}
+   */
+  expect(type, value) {
+    const t = this.next();
+    if (t.type !== type || (value !== undefined && t.value !== value)) {
+      const want = value ?? type;
+      throw new Error(
+        `Expected ${want} at position ${t.pos}, got "${t.value}"`
+      );
+    }
+    return t;
+  }
+
+  /**
+   * @param {number} [minBp]
+   * @return {Node}
+   */
+  parseExpr(minBp = 0) {
+    const t = this.next();
+    const key = t.type === 'punct' ? t.value : t.type;
+    const prefix = PREFIX[key];
+    if (!prefix) {
+      throw new Error(`Unexpected token "${t.value}" at position ${t.pos}`);
+    }
+    let left = prefix(this, t);
+
+    while (true) {
+      const nxt = this.peek();
+      const infixKey = nxt.type === 'punct' ? nxt.value : nxt.type;
+      const rule = INFIX[infixKey];
+      if (!rule || rule.lbp < minBp) {
+        break;
+      }
+      this.next();
+      left = rule.parse(this, left, nxt);
+    }
+
+    return left;
+  }
+}
+
+/**
+ * @param {Node} left
+ * @param {Node} right
+ * @param {1 | -1} rightSign
+ * @return {Node}
+ */
+function addTerm(left, right, rightSign) {
+  return mkSum([
+    { sign: 1, node: left },
+    { sign: rightSign, node: right },
+  ]);
+}
+
+/**
+ * @param {Node} left
+ * @param {Node} right
+ * @param {1 | -1} rightExp
+ * @return {Node}
+ */
+function mulFactor(left, right, rightExp) {
+  return mkProduct([
+    { exponent: 1, node: left },
+    { exponent: rightExp, node: right },
+  ]);
+}
+
+const ADD_BP = 1;
+const MUL_BP = 3;
+const UNARY_BP = 7;
+
+/**
+ * Functions whose argument list isn't a comma-separated list of calc
+ * expressions. Their bodies are slurped as opaque space-separated tokens
+ * and round-tripped verbatim. anchor() / anchor-size() use the
+ * `<anchor-name> <anchor-side>` shape (CSS Anchor Positioning).
+ */
+const OPAQUE_ARG_FUNCTIONS = new Set(['anchor', 'anchor-size']);
+
+/**
+ * Reconstruct a token's source text for opaque-arg slurping.
+ * @param {Token} t
+ * @return {string}
+ */
+function tokenText(t) {
+  if (t.type === 'dimension') {return `${t.value}${t.unit ?? ''}`;}
+  return t.value;
+}
+
+/**
+ * Parse the body of an opaque-arg call, with `(` already consumed.
+ * @param {Parser} p
+ * @param {string} name
+ * @return {Node}
+ */
+function parseOpaqueCall(p, name) {
+  /** @type {Node[]} */
+  const args = [];
+  let buf = '';
+  let depth = 1;
+  const flush = () => {
+    const trimmed = buf.trim();
+    if (trimmed) {args.push({ type: 'Ident', name: trimmed });}
+    buf = '';
+  };
+  while (true) {
+    const tk = p.peek();
+    if (tk.type === 'eof') {
+      throw new Error(`Unclosed ${name}( at position ${tk.pos}`);
+    }
+    if (tk.type === 'punct') {
+      if (tk.value === '(') {depth++;}
+      else if (tk.value === ')') {
+        depth--;
+        if (depth === 0) {
+          p.next();
+          flush();
+          return { type: 'Call', name, args };
+        }
+      } else if (tk.value === ',' && depth === 1) {
+        p.next();
+        flush();
+        continue;
+      }
+    }
+    if (tk.ws && buf) {buf += ' ';}
+    buf += tokenText(tk);
+    p.next();
+  }
+}
+
+/**
+ * §10.1 requires whitespace on both sides of a binary `+` / `-`. Without
+ * it, CSS tokenization treats `1px+2px` as two tokens with no operator
+ * between them (browsers reject this). We enforce the rule here by
+ * checking the token's `ws` flag (whitespace before the `+`/`-`) and the
+ * following token's flag (whitespace after).
+ * @param {Parser} p
+ * @param {Token} token
+ * @return {void}
+ */
+function requireSurroundingWs(p, token) {
+  const next = p.peek();
+  if (!token.ws || !next.ws) {
+    throw new Error(
+      `"${token.value}" must be surrounded by whitespace at position ${token.pos}`
+    );
+  }
+}
+
+/** @type {Record<string, PrefixParselet>} */
+const PREFIX = {
+  number: (_p, t) => ({ type: 'Num', value: parseFloat(t.value) }),
+
+  // Unit case normalization per §10.12: `1PX` serializes as `1px`.
+  dimension: (_p, t) => ({
+    type: 'Dim',
+    value: parseFloat(t.value),
+    unit: t.unit === '%' ? '%' : /** @type {string} */ (t.unit).toLowerCase(),
+  }),
+
+  ident: (p, t) => {
+    const nxt = p.peek();
+    if (nxt.type === 'punct' && nxt.value === '(') {
+      p.next();
+      if (OPAQUE_ARG_FUNCTIONS.has(t.value.toLowerCase())) {
+        return parseOpaqueCall(p, t.value);
+      }
+      /** @type {Node[]} */
+      const args = [];
+      if (!isPunct(p.peek(), ')')) {
+        args.push(p.parseExpr(0));
+        while (isPunct(p.peek(), ',')) {
+          p.next();
+          args.push(p.parseExpr(0));
+        }
+      }
+      p.expect('punct', ')');
+      return { type: 'Call', name: t.value, args };
+    }
+    const kw = foldCalcKeyword(t.value);
+    if (kw) {
+      return kw;
+    }
+    return { type: 'Ident', name: t.value };
+  },
+
+  '(': (p) => {
+    const e = p.parseExpr(0);
+    p.expect('punct', ')');
+    return e;
+  },
+
+  '-': (p) => negate(p.parseExpr(UNARY_BP)),
+  '+': (p) => p.parseExpr(UNARY_BP),
+};
+
+/** @type {Record<string, InfixParselet>} */
+const INFIX = {
+  '+': {
+    lbp: ADD_BP,
+    parse: (p, left, token) => {
+      requireSurroundingWs(p, token);
+      return addTerm(left, p.parseExpr(ADD_BP + 1), 1);
+    },
+  },
+  '-': {
+    lbp: ADD_BP,
+    parse: (p, left, token) => {
+      requireSurroundingWs(p, token);
+      return addTerm(left, p.parseExpr(ADD_BP + 1), -1);
+    },
+  },
+  '*': {
+    lbp: MUL_BP,
+    parse: (p, left) => mulFactor(left, p.parseExpr(MUL_BP + 1), 1),
+  },
+  '/': {
+    lbp: MUL_BP,
+    parse: (p, left) => mulFactor(left, p.parseExpr(MUL_BP + 1), -1),
+  },
+};
+
+/**
+ * @param {Token[]} tokens
+ * @return {Node}
+ */
+function parse(tokens) {
+  const p = new Parser(tokens);
+  const ast = p.parseExpr(0);
+  const trailing = p.peek();
+  if (trailing.type !== 'eof') {
+    throw new Error(
+      `Unexpected token "${trailing.value}" at position ${trailing.pos}`
+    );
+  }
+  return ast;
+}
+
+module.exports = { parse };

package/src/lib/serialize.js

@@ -0,0 +1,239 @@
+'use strict';
+
+// 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.
+
+/**
+ * @typedef {import('./node.js').Node} Node
+ * @typedef {import('./node.js').Sum} Sum
+ * @typedef {import('./node.js').Product} Product
+ * @typedef {import('./node.js').ProductFactor} ProductFactor
+ * @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'`.
+ */
+
+// Below this is float noise, not a value: `0.1 + 0.2 - 0.3` is 5.5e-17.
+const NOISE_FLOOR = 1e-12;
+
+/**
+ * Rounding to `prec` decimal places turns `calc(1/1000000)` into `0`, and a
+ * `0` in CSS is often a switch, not a small number (`flex-grow: 0` never
+ * grows). So when a value is too small for `prec`, keep its significant digits
+ * instead: `1/1000000` -> `0.000001`, `1/3000000` -> `3.3333e-7`.
+ *
+ * @param {number} v
+ * @param {number | false} prec
+ * @return {number}
+ */
+function round(v, prec) {
+  if (prec === false) {
+    return v;
+  }
+  const m = Math.pow(10, prec);
+  const rounded = Math.round(v * m) / m;
+  if (rounded === 0 && Math.abs(v) > NOISE_FLOOR) {
+    // toPrecision needs at least one significant digit; `prec` may be 0.
+    return Number(v.toPrecision(Math.max(prec, 1)));
+  }
+  return rounded;
+}
+
+// §10.13 / §10.7.2: Infinity/NaN serialize as canonical keywords.
+/**
+ * @param {number} v
+ * @return {boolean}
+ */
+function isDegenerate(v) {
+  return !isFinite(v) || isNaN(v);
+}
+
+/**
+ * @param {number} v
+ * @return {string}
+ */
+function degenerateKeyword(v) {
+  if (isNaN(v)) {return 'NaN';}
+  return v > 0 ? 'infinity' : '-infinity';
+}
+
+/**
+ * @param {Node} node
+ * @param {SerializeOptions} [opts]
+ * @return {string}
+ */
+function serialize(node, opts = {}) {
+  const prec = opts.precision ?? 5;
+  const calcName = opts.calcName ?? 'calc';
+
+  // §10.13: top-level Infinity/NaN wrap in calc(); dim degenerates carry
+  // the unit as `<keyword> * 1<unit>` so the result keeps its type.
+  if (node.type === 'Num' && isDegenerate(node.value)) {
+    return `${calcName}(${degenerateKeyword(node.value)})`;
+  }
+  if (node.type === 'Dim' && isDegenerate(node.value)) {
+    return `${calcName}(${degenerateKeyword(node.value)} * 1${node.unit})`;
+  }
+
+  if (
+    node.type === 'Num' ||
+    node.type === 'Dim' ||
+    node.type === 'Ident' ||
+    node.type === 'Call'
+  ) {
+    return serializeExpr(node, prec);
+  }
+
+  // Single-term Sum is the canonical form for `-var(--x)` / `-(a*b)` —
+  // sign=-1 around an opaque node. Signed leaves live in Num/Dim directly.
+  if (node.type === 'Sum' && node.terms.length === 1) {
+    return `${calcName}(${serializeLeadingNeg(node.terms[0].node, prec)})`;
+  }
+
+  return `${calcName}(${serializeExpr(node, prec)})`;
+}
+
+// --- Inside calc() expression --------------------------------------------
+
+/**
+ * @param {Node} node
+ * @param {number | false} prec
+ * @return {string}
+ */
+function serializeExpr(node, prec) {
+  switch (node.type) {
+    case 'Num':
+      if (isDegenerate(node.value)) {return degenerateKeyword(node.value);}
+      return String(round(node.value, prec));
+    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 `${round(node.value, prec)}${node.unit}`;
+    case 'Ident':
+      return node.name;
+    case 'Call': {
+      const args = node.args.map((a) => serializeExpr(a, prec)).join(', ');
+      return `${node.name}(${args})`;
+    }
+    case 'Sum':
+      return serializeSum(node, prec);
+    case 'Product':
+      return serializeProduct(node, prec);
+  }
+}
+
+/**
+ * Combine the term's sign with a negative Num/Dim value's sign so
+ * `{sign:+1, Num(-5)}` renders as `-5`, not `+ -5`. Skip degenerate
+ * (Infinity/NaN) values — the `degenerateKeyword` path emits `-infinity`
+ * inline, and a leading minus on `calc(infinity*1<unit>)` would now
+ * tokenize as a `-calc` function.
+ * @param {{sign: 1 | -1, node: Node}} term
+ * @return {{sign: 1 | -1, magnitude: Node}}
+ */
+function displaySign(term) {
+  const { sign, node } = term;
+  if (node.type === 'Num' && isFinite(node.value) && node.value < 0) {
+    return {
+      sign: /** @type {1 | -1} */ (-sign),
+      magnitude: { type: 'Num', value: -node.value },
+    };
+  }
+  if (node.type === 'Dim' && isFinite(node.value) && node.value < 0) {
+    return {
+      sign: /** @type {1 | -1} */ (-sign),
+      magnitude: { type: 'Dim', value: -node.value, unit: node.unit },
+    };
+  }
+  return { sign, magnitude: node };
+}
+
+/**
+ * @param {Sum} sum
+ * @param {number | false} prec
+ * @return {string}
+ */
+function serializeSum(sum, prec) {
+  let out = '';
+  sum.terms.forEach((t, i) => {
+    const { sign, magnitude } = displaySign(t);
+    if (i === 0) {
+      out = sign === 1
+        ? serializeExpr(magnitude, prec)
+        : serializeLeadingNeg(magnitude, prec);
+    } else {
+      // `-` binds looser than `*`/`/` so the right side never needs parens.
+      const body = serializeExpr(magnitude, prec);
+      out += sign === 1 ? ` + ${body}` : ` - ${body}`;
+    }
+  });
+  return out;
+}
+
+/**
+ * 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`.
+ * @param {Node} node
+ * @param {number | false} prec
+ * @return {string}
+ */
+function serializeLeadingNeg(node, prec) {
+  if (
+    node.type === 'Product' &&
+    node.factors.length > 0 &&
+    node.factors[0].exponent === 1 &&
+    node.factors[0].node.type === 'Num' &&
+    isFinite(node.factors[0].node.value) &&
+    node.factors[0].node.value !== 0
+  ) {
+    const head = node.factors[0].node;
+    const negatedValue = -head.value;
+    const rest = node.factors.slice(1);
+    // A coefficient of 1 is a no-op factor, matching mkProduct.
+    /** @type {ProductFactor[]} */
+    const negatedFactors =
+      negatedValue === 1
+        ? rest
+        : [
+            { exponent: 1, node: { type: 'Num', value: negatedValue } },
+            ...rest,
+          ];
+    return serializeProduct({ type: 'Product', factors: negatedFactors }, prec);
+  }
+  const body = serializeExpr(node, prec);
+  return node.type === 'Sum' || node.type === 'Product' ? `-(${body})` : `-${body}`;
+}
+
+/**
+ * @param {Product} product
+ * @param {number | false} prec
+ * @return {string}
+ */
+function serializeProduct(product, prec) {
+  let out = '';
+  product.factors.forEach((f, 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.
+    if (f.node.type === 'Sum') {
+      body = `(${body})`;
+    }
+    if (i === 0) {
+      // Leading denominator: implicit 1 so we emit `1 / 2px`, not `/ 2px`.
+      out = f.exponent === 1 ? body : `1 / ${body}`;
+    } else {
+      out += f.exponent === 1 ? ` * ${body}` : ` / ${body}`;
+    }
+  });
+  return out;
+}
+
+// Stryker disable next-line all: instrumenting this line breaks Node's
+// cjs-module-lexer named-export detection for .mjs `import { x } from` consumers.
+module.exports = { serialize };

package/src/lib/simplify/abs.js

@@ -0,0 +1,21 @@
+'use strict';
+
+const { num, dim } = require('../node.js');
+
+/** @typedef {import('../node.js').Node} Node */
+
+/**
+ * @param {Node[]} args
+ * @return {Node}
+ */
+function simplifyAbs(args) {
+  if (args.length !== 1) {
+    return { type: 'Call', name: 'abs', args };
+  }
+  const a = args[0];
+  if (a.type === 'Num') {return num(Math.abs(a.value));}
+  if (a.type === 'Dim' && a.unit !== '%') {return dim(Math.abs(a.value), a.unit);}
+  return { type: 'Call', name: 'abs', args: [a] };
+}
+
+module.exports = { simplifyAbs };

package/src/lib/simplify/atan2.js

@@ -0,0 +1,25 @@
+'use strict';
+
+// §10.4 — atan2. foldConstArgs already rejects percentages (property-
+// context-resolved) and enforces shared base + static convertibility.
+
+const { num, dim } = require('../node.js');
+const { foldConstArgs } = require('./fold.js');
+
+/** @typedef {import('../node.js').Node} Node */
+
+/**
+ * @param {Node[]} args
+ * @return {Node}
+ */
+function simplifyAtan2(args) {
+  if (args.length !== 2) {return { type: 'Call', name: 'atan2', args };}
+  const fold = foldConstArgs(args);
+  if (fold === null) {return { type: 'Call', name: 'atan2', args };}
+  const [y, x] = /** @type {[number, number]} */ (fold.values);
+  const radians = Math.atan2(y, x);
+  if (isNaN(radians)) {return num(NaN);}
+  return dim((radians * 180) / Math.PI, 'deg');
+}
+
+module.exports = { simplifyAtan2 };

package/src/lib/simplify/bucket.js

@@ -0,0 +1,49 @@
+'use strict';
+
+// §10.10 phase 2: merge convertible same-base unit buckets into the
+// first-encountered unit (px absorbs cm/in/pt/pc, deg absorbs
+// rad/grad/turn, …). Buckets with `base === null` (relative or unknown
+// units) keep their own slot.
+
+const { convert } = require('../convertUnits.js');
+
+/**
+ * @typedef {object} UnitBucket
+ * @property {string} unit
+ * @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
+ *  converted values of merged neighbors. Caller must not reuse the input.
+ * @param {UnitBucket[]} buckets
+ * @return {UnitBucket[]}
+ */
+function mergeConvertibleBuckets(buckets) {
+  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) {
+    const keyB = b.unit.toLowerCase();
+    if (merged.has(keyB)) {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);
+        }
+      }
+    }
+    out.push(b);
+  }
+  return out;
+}
+
+module.exports = { mergeConvertibleBuckets };

package/src/lib/simplify/call.js

@@ -0,0 +1,59 @@
+'use strict';
+
+// Pre-simplify args once, route by name. Leaf folds receive simplified
+// args so they don't need to recurse into `simplify` themselves.
+
+const { simplifyMinMax } = require('./min-max.js');
+const { simplifyClamp } = require('./clamp.js');
+const { simplifyAbs } = require('./abs.js');
+const { simplifySign } = require('./sign.js');
+const { simplifyModRem } = require('./mod-rem.js');
+const { simplifyRound } = require('./round.js');
+const { simplifyTrig } = require('./trig.js');
+const { simplifyInverseTrig } = require('./inverse-trig.js');
+const { simplifyAtan2 } = require('./atan2.js');
+const { simplifyPow } = require('./pow.js');
+const { simplifySqrt } = require('./sqrt.js');
+const { simplifyExp } = require('./exp.js');
+const { simplifyLog } = require('./log.js');
+const { simplifyHypot } = require('./hypot.js');
+
+/** @typedef {import('../node.js').Node} Node */
+/** @typedef {import('../simplify.js').SimplifyFn} SimplifyFn */
+
+/**
+ * @param {Extract<Node, { type: 'Call' }>} node
+ * @param {SimplifyFn} simplify
+ * @return {Node}
+ */
+function simplifyCall(node, simplify) {
+  const name = node.name.toLowerCase();
+
+  if (name === 'calc' || name === '-webkit-calc' || name === '-moz-calc') {
+    if (node.args.length !== 1) {
+      throw new Error(`${node.name}() takes exactly one argument`);
+    }
+    return simplify(node.args[0]);
+  }
+
+  const args = node.args.map((a) => simplify(a));
+
+  if (name === 'min' || name === 'max') {return simplifyMinMax(node.name, args);}
+  if (name === 'clamp') {return simplifyClamp(args);}
+  if (name === 'abs') {return simplifyAbs(args);}
+  if (name === 'sign') {return simplifySign(args);}
+  if (name === 'mod' || name === 'rem') {return simplifyModRem(name, args);}
+  if (name === 'round') {return simplifyRound(args);}
+  if (name === 'sin' || name === 'cos' || name === 'tan') {return simplifyTrig(name, args);}
+  if (name === 'asin' || name === 'acos' || name === 'atan') {return simplifyInverseTrig(name, args);}
+  if (name === 'atan2') {return simplifyAtan2(args);}
+  if (name === 'pow') {return simplifyPow(args);}
+  if (name === 'sqrt') {return simplifySqrt(args);}
+  if (name === 'hypot') {return simplifyHypot(args);}
+  if (name === 'log') {return simplifyLog(args);}
+  if (name === 'exp') {return simplifyExp(args);}
+
+  return { type: 'Call', name: node.name, args };
+}
+
+module.exports = { simplifyCall };