postcss-calc 10.1.0 → 11.0.0-rc.0

package/src/lib/simplify/trig.js

@@ -0,0 +1,40 @@
+'use strict';
+
+// §10.4 — sin/cos/tan. <number> is radians; <angle> dim is converted.
+
+const { num } = require('../node.js');
+const { baseOf, convert } = require('../convertUnits.js');
+
+/** @typedef {import('../node.js').Node} Node */
+
+const TRIG_OPS = /** @type {const} */ ({
+  sin: Math.sin,
+  cos: Math.cos,
+  tan: Math.tan,
+});
+
+/**
+ * @param {'sin' | 'cos' | 'tan'} name
+ * @param {Node[]} args
+ * @return {Node}
+ */
+function simplifyTrig(name, args) {
+  if (args.length !== 1) {return { type: 'Call', name, args };}
+  const a = args[0];
+  /** @type {number | null} */ let radians = null;
+  if (a.type === 'Num') {
+    radians = a.value;
+  } else if (a.type === 'Dim' && a.unit !== '%' && baseOf(a.unit) === 'angle') {
+    // The `baseOf === 'angle'` check and the `inDeg !== null` guard below
+    // are observationally equivalent under current type tables (every
+    // angle unit has a TO_CANONICAL entry). Stryker flags both as
+    // equivalent-mutant survivors — keep them; they're load-bearing
+    // defense against future unit additions.
+    const inDeg = convert(a.value, a.unit, 'deg');
+    if (inDeg !== null) {radians = (inDeg * Math.PI) / 180;}
+  }
+  if (radians === null) {return { type: 'Call', name, args };}
+  return num(TRIG_OPS[name](radians));
+}
+
+module.exports = { simplifyTrig };

package/src/lib/simplify.js

@@ -0,0 +1,40 @@
+'use strict';
+
+// Spec: https://www.w3.org/TR/css-values-4/#calc-simplification
+// One top-down pass over a canonical AST. Per-concern fold modules in
+// ./simplify/; this file is the entry + dispatch only.
+
+const { simplifySum } = require('./simplify/sum.js');
+const { simplifyProduct } = require('./simplify/product.js');
+const { simplifyCall } = require('./simplify/call.js');
+
+/**
+ * @typedef {import('./node.js').Node} Node
+ *
+ * Recursive simplifier reference, threaded into Sum/Product/Call. Lets
+ * leaf fold modules avoid circular imports of the entry function.
+ * @typedef {(node: Node) => Node} SimplifyFn
+ */
+
+/**
+ * @param {Node} node
+ * @return {Node}
+ */
+function simplify(node) {
+  switch (node.type) {
+    case 'Num':
+    case 'Dim':
+    case 'Ident':
+      return node;
+    case 'Call':
+      return simplifyCall(node, simplify);
+    case 'Sum':
+      return simplifySum(node, simplify);
+    case 'Product':
+      return simplifyProduct(node, simplify);
+  }
+}
+
+// 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 = { simplify };

package/src/lib/tokenizer.js

@@ -0,0 +1,115 @@
+'use strict';
+
+// Folds @csstools/css-tokenizer output into the calc() token subset.
+
+// @csstools/css-tokenizer is ESM-only and this package is CJS. require(esm)
+// must happen at first use, not at module evaluation — a consumer's ESM
+// graph may also link the tokenizer (other csstools plugins do), and a
+// load-time require would hit ERR_REQUIRE_CYCLE_MODULE there.
+/** @type {typeof import('@csstools/css-tokenizer') | undefined} */
+let cssTokenizer;
+
+/**
+ * @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[]}
+ */
+function tokenize(input) {
+  cssTokenizer ??= require('@csstools/css-tokenizer');
+  const { tokenize: tokenizeCss, TokenType: CssType } = cssTokenizer;
+  /** @type {Token[]} */
+  const tokens = [];
+  let ws = true;
+
+  // CSS absorbs leading signs (`-5px` is one token); the parser expects
+  // punct sign + unsigned numeric, so split them back out.
+  /**
+   * @param {string} raw
+   * @param {string | undefined} unit
+   * @param {number} pos
+   * @return {void}
+   */
+  function pushNumeric(raw, unit, pos) {
+    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 });
+    }
+    ws = false;
+  }
+
+  for (const t of tokenizeCss({ css: input })) {
+    switch (t[0]) {
+      case CssType.Whitespace:
+      case CssType.Comment:
+        ws = true;
+        continue;
+      case CssType.Number:
+        pushNumeric(t[1], undefined, t[2]);
+        continue;
+      case CssType.Dimension:
+        pushNumeric(t[1], t[4].unit, t[2]);
+        continue;
+      case CssType.Percentage:
+        pushNumeric(t[1], '%', t[2]);
+        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:
+        tokens.push({ type: 'eof', value: '', pos: input.length, ws });
+        break;
+      default:
+        throw new Error(
+          `Unexpected character "${t[1][0] ?? ''}" at position ${t[2]}`
+        );
+    }
+    ws = false;
+  }
+
+  return tokens;
+}
+
+module.exports = { tokenize };

package/types/index.d.ts

@@ -1,25 +1,23 @@
 export = pluginCreator;
 /**
- * @typedef {{precision?: number | false,
- *          preserve?: boolean,
- *          warnWhenCannotResolve?: boolean,
- *          mediaQueries?: boolean,
- *          selectors?: boolean}} PostCssCalcOptions
- */
-/**
- * @type {import('postcss').PluginCreator<PostCssCalcOptions>}
- * @param {PostCssCalcOptions} opts
+ * @type {import('postcss').PluginCreator<PluginOptions>}
+ * @param {PluginOptions} [opts]
  * @return {import('postcss').Plugin}
  */
-declare function pluginCreator(opts: PostCssCalcOptions): import("postcss").Plugin;
+declare function pluginCreator(opts?: PluginOptions): import("postcss").Plugin;
 declare namespace pluginCreator {
-    export { postcss, PostCssCalcOptions };
+    export { postcss, PluginOptions, ResolvedOptions };
 }
 declare var postcss: true;
-type PostCssCalcOptions = {
-    precision?: number | false;
-    preserve?: boolean;
-    warnWhenCannotResolve?: boolean;
-    mediaQueries?: boolean;
-    selectors?: boolean;
+type PluginOptions = {
+    precision?: number | false | undefined;
+    preserve?: boolean | undefined;
+    warnWhenCannotResolve?: boolean | undefined;
+    mediaQueries?: boolean | undefined;
+    selectors?: boolean | undefined;
+    /**
+     * Invoked when parse/simplify throws. Replaces the default `result.warn`.
+     */
+    onParseError?: ((error: Error, input: string) => void) | undefined;
 };
+type ResolvedOptions = Required<Omit<PluginOptions, "onParseError">> & Pick<PluginOptions, "onParseError">;

package/types/lib/convertUnits.d.ts

@@ -0,0 +1,16 @@
+export type BaseType = "length" | "angle" | "time" | "frequency" | "resolution" | "flex" | "percentage";
+/**
+ * @param {string} unit
+ * @return {BaseType | null}
+ */
+export function baseOf(unit: string): BaseType | null;
+/**
+ * Convert a value within a single conversion family. Returns null when
+ * either unit is missing from the table (em/rem/vw need runtime context)
+ * or when the units belong to different base types.
+ * @param {number} value
+ * @param {string} from
+ * @param {string} to
+ * @return {number | null}
+ */
+export function convert(value: number, from: string, to: string): number | null;

package/types/lib/node.d.ts

@@ -0,0 +1,90 @@
+export type Num = {
+    type: "Num";
+    value: number;
+};
+export type Dim = {
+    type: "Dim";
+    value: number;
+    unit: string;
+};
+export type Ident = {
+    type: "Ident";
+    name: string;
+};
+export type Call = {
+    type: "Call";
+    name: string;
+    args: Node[];
+};
+/**
+ * Sign is always +1 when node is Num or Dim.
+ */
+export type SumTerm = {
+    sign: 1 | -1;
+    node: Node;
+};
+export type Sum = {
+    type: "Sum";
+    terms: SumTerm[];
+};
+/**
+ * exponent +1 = numerator, -1 = denominator.
+ */
+export type ProductFactor = {
+    exponent: 1 | -1;
+    node: Node;
+};
+export type Product = {
+    type: "Product";
+    factors: ProductFactor[];
+};
+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 {{sign: 1 | -1, node: Node}} SumTerm Sign is always +1 when node is Num or Dim.
+ * @typedef {{type: 'Sum', terms: SumTerm[]}} 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
+ */
+/**
+ * @param {number} value
+ * @return {Num}
+ */
+export function num(value: number): Num;
+/**
+ * @param {number} value
+ * @param {string} unit
+ * @return {Dim}
+ */
+export function dim(value: number, unit: string): Dim;
+/**
+ * @param {string} name
+ * @return {Ident}
+ */
+export function ident(name: string): Ident;
+/**
+ * @param {string} name
+ * @param {Node[]} args
+ * @return {Call}
+ */
+export function call(name: string, args: Node[]): Call;
+/**
+ * @param {SumTerm[]} rawTerms
+ * @return {Node}
+ */
+export function mkSum(rawTerms: SumTerm[]): Node;
+/**
+ * @param {ProductFactor[]} rawFactors
+ * @return {Node}
+ */
+export function mkProduct(rawFactors: ProductFactor[]): Node;
+/**
+ * Negate any node, preserving canonical form.
+ * @param {Node} node
+ * @return {Node}
+ */
+export function negate(node: Node): Node;

package/types/lib/parser.d.ts

@@ -0,0 +1,39 @@
+export type Token = import("./tokenizer.js").Token;
+export type TokenType = import("./tokenizer.js").TokenType;
+export type Node = import("./node.js").Node;
+export type PrefixParselet = (p: Parser, token: Token) => Node;
+export type InfixParselet = {
+    lbp: number;
+    parse: (p: Parser, left: Node, token: Token) => Node;
+};
+/**
+ * @param {Token[]} tokens
+ * @return {Node}
+ */
+export function parse(tokens: Token[]): Node;
+declare class Parser {
+    /**
+     * @param {Token[]} tokens
+     */
+    constructor(tokens: Token[]);
+    /** @private */
+    private i;
+    /** @private @readonly */
+    private readonly tokens;
+    /** @return {Token} */
+    peek(): Token;
+    /** @return {Token} */
+    next(): Token;
+    /**
+     * @param {TokenType} type
+     * @param {string} [value]
+     * @return {Token}
+     */
+    expect(type: TokenType, value?: string): Token;
+    /**
+     * @param {number} [minBp]
+     * @return {Node}
+     */
+    parseExpr(minBp?: number): Node;
+}
+export {};

package/types/lib/serialize.d.ts

@@ -0,0 +1,20 @@
+export type Node = import("./node.js").Node;
+export type Sum = import("./node.js").Sum;
+export type Product = import("./node.js").Product;
+export type ProductFactor = import("./node.js").ProductFactor;
+export type SerializeOptions = {
+    /**
+     * Decimal places for numbers. `false` disables rounding. Default 5.
+     */
+    precision?: number | false | undefined;
+    /**
+     * Wrapper name to use when `calc()` is needed. Default `'calc'`.
+     */
+    calcName?: string | undefined;
+};
+/**
+ * @param {Node} node
+ * @param {SerializeOptions} [opts]
+ * @return {string}
+ */
+export function serialize(node: Node, opts?: SerializeOptions): string;

package/types/lib/simplify/abs.d.ts

@@ -0,0 +1,7 @@
+export type Node = import("../node.js").Node;
+/** @typedef {import('../node.js').Node} Node */
+/**
+ * @param {Node[]} args
+ * @return {Node}
+ */
+export function simplifyAbs(args: Node[]): Node;

package/types/lib/simplify/atan2.d.ts

@@ -0,0 +1,7 @@
+export type Node = import("../node.js").Node;
+/** @typedef {import('../node.js').Node} Node */
+/**
+ * @param {Node[]} args
+ * @return {Node}
+ */
+export function simplifyAtan2(args: Node[]): Node;

package/types/lib/simplify/bucket.d.ts

@@ -0,0 +1,19 @@
+export type UnitBucket = {
+    unit: string;
+    total: number;
+    base: import("../convertUnits.js").BaseType | null;
+    order: number;
+};
+/**
+ * @typedef {object} UnitBucket
+ * @property {string} unit
+ * @property {number} total
+ * @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[]}
+ */
+export function mergeConvertibleBuckets(buckets: UnitBucket[]): UnitBucket[];

package/types/lib/simplify/call.d.ts

@@ -0,0 +1,12 @@
+export type Node = import("../node.js").Node;
+export type SimplifyFn = import("../simplify.js").SimplifyFn;
+/** @typedef {import('../node.js').Node} Node */
+/** @typedef {import('../simplify.js').SimplifyFn} SimplifyFn */
+/**
+ * @param {Extract<Node, { type: 'Call' }>} node
+ * @param {SimplifyFn} simplify
+ * @return {Node}
+ */
+export function simplifyCall(node: Extract<Node, {
+    type: "Call";
+}>, simplify: SimplifyFn): Node;

package/types/lib/simplify/cancel.d.ts

@@ -0,0 +1,19 @@
+/**
+ * If `dims` contain exactly one numerator / one denominator pair with the
+ * same base type and convertible units, return the numeric factor produced
+ * by cancelling them and the list of remaining (uncancelled) dims.
+ * Otherwise return null. Used by `simplifyProduct` for typed division
+ * (§10.2). More complex cancellation (e.g. `px^2 / px`) is left
+ * unreduced — consumers rarely rely on it and the spec doesn't require it.
+ * @template {{ exponent: 1 | -1, value: number, unit: string }} D
+ * @param {D[]} dims
+ * @return {{ factor: number, remaining: D[] } | null}
+ */
+export function tryCancelPair<D extends {
+    exponent: 1 | -1;
+    value: number;
+    unit: string;
+}>(dims: D[]): {
+    factor: number;
+    remaining: D[];
+} | null;

package/types/lib/simplify/clamp.d.ts

@@ -0,0 +1,7 @@
+export type Node = import("../node.js").Node;
+/** @typedef {import('../node.js').Node} Node */
+/**
+ * @param {Node[]} args
+ * @return {Node}
+ */
+export function simplifyClamp(args: Node[]): Node;

package/types/lib/simplify/exp.d.ts

@@ -0,0 +1,7 @@
+export type Node = import("../node.js").Node;
+/** @typedef {import('../node.js').Node} Node */
+/**
+ * @param {Node[]} args
+ * @return {Node}
+ */
+export function simplifyExp(args: Node[]): Node;

package/types/lib/simplify/fold.d.ts

@@ -0,0 +1,12 @@
+export type Node = import("../node.js").Node;
+export type BaseType = import("../convertUnits.js").BaseType;
+/** @typedef {import('../node.js').Node} Node */
+/** @typedef {import('../convertUnits.js').BaseType} BaseType */
+/**
+ * @param {Node[]} args
+ * @return {{ values: number[], unit: string } | null}
+ */
+export function foldConstArgs(args: Node[]): {
+    values: number[];
+    unit: string;
+} | null;

package/types/lib/simplify/hypot.d.ts

@@ -0,0 +1,7 @@
+export type Node = import("../node.js").Node;
+/** @typedef {import('../node.js').Node} Node */
+/**
+ * @param {Node[]} args
+ * @return {Node}
+ */
+export function simplifyHypot(args: Node[]): Node;

package/types/lib/simplify/inverse-trig.d.ts

@@ -0,0 +1,7 @@
+export type Node = import("../node.js").Node;
+/**
+ * @param {'asin' | 'acos' | 'atan'} name
+ * @param {Node[]} args
+ * @return {Node}
+ */
+export function simplifyInverseTrig(name: "asin" | "acos" | "atan", args: Node[]): Node;

package/types/lib/simplify/log.d.ts

@@ -0,0 +1,7 @@
+export type Node = import("../node.js").Node;
+/** @typedef {import('../node.js').Node} Node */
+/**
+ * @param {Node[]} args
+ * @return {Node}
+ */
+export function simplifyLog(args: Node[]): Node;

package/types/lib/simplify/min-max.d.ts

@@ -0,0 +1,8 @@
+export type Node = import("../node.js").Node;
+/** @typedef {import('../node.js').Node} Node */
+/**
+ * @param {string} name
+ * @param {Node[]} args
+ * @return {Node}
+ */
+export function simplifyMinMax(name: string, args: Node[]): Node;

package/types/lib/simplify/mod-rem.d.ts

@@ -0,0 +1,8 @@
+export type Node = import("../node.js").Node;
+/** @typedef {import('../node.js').Node} Node */
+/**
+ * @param {'mod' | 'rem'} name
+ * @param {Node[]} args
+ * @return {Node}
+ */
+export function simplifyModRem(name: "mod" | "rem", args: Node[]): Node;

package/types/lib/simplify/pow.d.ts

@@ -0,0 +1,7 @@
+export type Node = import("../node.js").Node;
+/** @typedef {import('../node.js').Node} Node */
+/**
+ * @param {Node[]} args
+ * @return {Node}
+ */
+export function simplifyPow(args: Node[]): Node;

package/types/lib/simplify/product.d.ts

@@ -0,0 +1,16 @@
+export type Node = import("../node.js").Node;
+export type Product = import("../node.js").Product;
+export type ProductFactor = import("../node.js").ProductFactor;
+export type SimplifyFn = import("../simplify.js").SimplifyFn;
+/**
+ * @typedef {import('../node.js').Node} Node
+ * @typedef {import('../node.js').Product} Product
+ * @typedef {import('../node.js').ProductFactor} ProductFactor
+ * @typedef {import('../simplify.js').SimplifyFn} SimplifyFn
+ */
+/**
+ * @param {Product} product
+ * @param {SimplifyFn} simplify
+ * @return {Node}
+ */
+export function simplifyProduct(product: Product, simplify: SimplifyFn): Node;

package/types/lib/simplify/round.d.ts

@@ -0,0 +1,8 @@
+export type RoundStrategy = "nearest" | "up" | "down" | "to-zero";
+export type Node = import("../node.js").Node;
+/** @typedef {'nearest' | 'up' | 'down' | 'to-zero'} RoundStrategy */
+/**
+ * @param {Node[]} args
+ * @return {Node}
+ */
+export function simplifyRound(args: Node[]): Node;

package/types/lib/simplify/sign.d.ts

@@ -0,0 +1,7 @@
+export type Node = import("../node.js").Node;
+/** @typedef {import('../node.js').Node} Node */
+/**
+ * @param {Node[]} args
+ * @return {Node}
+ */
+export function simplifySign(args: Node[]): Node;

package/types/lib/simplify/sqrt.d.ts

@@ -0,0 +1,7 @@
+export type Node = import("../node.js").Node;
+/** @typedef {import('../node.js').Node} Node */
+/**
+ * @param {Node[]} args
+ * @return {Node}
+ */
+export function simplifySqrt(args: Node[]): Node;

package/types/lib/simplify/sum.d.ts

@@ -0,0 +1,18 @@
+export type Node = import("../node.js").Node;
+export type Sum = import("../node.js").Sum;
+export type SumTerm = import("../node.js").SumTerm;
+export type SimplifyFn = import("../simplify.js").SimplifyFn;
+export type UnitBucket = import("./bucket.js").UnitBucket;
+/**
+ * @typedef {import('../node.js').Node} Node
+ * @typedef {import('../node.js').Sum} Sum
+ * @typedef {import('../node.js').SumTerm} SumTerm
+ * @typedef {import('../simplify.js').SimplifyFn} SimplifyFn
+ * @typedef {import('./bucket.js').UnitBucket} UnitBucket
+ */
+/**
+ * @param {Sum} sum
+ * @param {SimplifyFn} simplify
+ * @return {Node}
+ */
+export function simplifySum(sum: Sum, simplify: SimplifyFn): Node;

package/types/lib/simplify/trig.d.ts

@@ -0,0 +1,7 @@
+export type Node = import("../node.js").Node;
+/**
+ * @param {'sin' | 'cos' | 'tan'} name
+ * @param {Node[]} args
+ * @return {Node}
+ */
+export function simplifyTrig(name: "sin" | "cos" | "tan", args: Node[]): Node;

package/types/lib/simplify.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Recursive simplifier reference, threaded into Sum/Product/Call. Lets
+ * leaf fold modules avoid circular imports of the entry function.
+ */
+export type Node = import("./node.js").Node;
+export type SimplifyFn = (node: Node) => Node;
+/**
+ * @typedef {import('./node.js').Node} Node
+ *
+ * Recursive simplifier reference, threaded into Sum/Product/Call. Lets
+ * leaf fold modules avoid circular imports of the entry function.
+ * @typedef {(node: Node) => Node} SimplifyFn
+ */
+/**
+ * @param {Node} node
+ * @return {Node}
+ */
+export function simplify(node: Node): Node;