postcss-calc 11.2.1 → 11.2.3

package/src/lib/node.js

@@ -8,7 +8,11 @@
 //   - No ungrouped Sum directly contains another Sum (flattened on
 //     construction). A grouped Sum is retained so a later negative sign
 //     cannot be distributed across opaque terms.
-//   - No Product directly contains another Product (flattened).
+//   - No Product directly contains another ungrouped Product (flattened). A
+//     grouped Product is retained: it is a parenthesized group around a
+//     substitution function (`var()`, `env()`, ...), whose tokens must not
+//     merge with the surrounding factors. A grouped Product may hold a single
+//     factor.
 //   - A Sum/Product with one positive element collapses to that element.
 //   - A Sum/Product with no elements collapses to Num(0) / Num(1).
 //   - Positive zero-valued Nums are dropped from all-number sums. They are
@@ -28,7 +32,7 @@
  * @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 {{type: 'Product', factors: ProductFactor[], grouped?: boolean}} Product
  * @typedef {Num | Dim | Ident | Call | OpaqueCall | Sum | Product} Node
  */
 
@@ -185,7 +189,7 @@ function mkProduct(rawFactors) {
  */
 function pushProductFactor(out, f) {
   const n = f.node;
-  if (n.type === 'Product') {
+  if (n.type === 'Product' && !n.grouped) {
     for (const inner of n.factors) {
       out.push({
         exponent: /** @type {1 | -1} */ (f.exponent * inner.exponent),
@@ -201,6 +205,48 @@ function pushProductFactor(out, f) {
   out.push(f);
 }
 
+/**
+ * Mark a node as a source parenthesized group. A Sum or Product keeps its
+ * structure; any other node becomes a single-factor grouped Product.
+ * @param {Node} node
+ * @return {Node}
+ */
+function mkGroup(node) {
+  if (node.type === 'Sum' || node.type === 'Product') {
+    return { ...node, grouped: true };
+  }
+  return {
+    type: 'Product',
+    factors: [{ exponent: 1, node }],
+    grouped: true,
+  };
+}
+
+/**
+ * Whether a node is a substitution function call (`var()`, `env()`, ...), or
+ * an ungrouped Product that directly contains one. Nested groups are not
+ * inspected: they already bound their own tokens.
+ * @param {Node} node
+ * @return {boolean}
+ */
+function isSubstitutionNode(node) {
+  if (node.type === 'OpaqueCall') return true;
+  if (node.type === 'Product' && !node.grouped) {
+    return node.factors.some((factor) => isSubstitutionNode(factor.node));
+  }
+  return false;
+}
+
+/**
+ * Group a parenthesized expression when its tokens must stay bound: a sum, or
+ * a product around a substitution function.
+ * @param {Node} node
+ * @return {Node}
+ */
+function groupSubstitution(node) {
+  return node.type === 'Sum' || isSubstitutionNode(node) ? mkGroup(node) : node;
+}
+
 /**
  * Negate any node, preserving canonical form.
  * @param {Node} node
@@ -233,4 +279,15 @@ function negate(node) {
   return mkSum([{ sign: -1, node }]);
 }
 
-export { num, dim, ident, call, opaqueCall, mkSum, mkProduct, negate };
+export {
+  num,
+  dim,
+  ident,
+  call,
+  opaqueCall,
+  mkSum,
+  mkProduct,
+  mkGroup,
+  groupSubstitution,
+  negate,
+};

package/src/lib/parser/opaque.js

@@ -0,0 +1,152 @@
+// Opaque function parsing: `var()`, unknown functions and their component trees.
+import { TokenType as CssType } from '@csstools/css-tokenizer';
+import { ident, opaqueCall } from '../node.js';
+import {
+  isCalculationFunction,
+  isSupportedMathFunction,
+} from '../functions.js';
+import { assertDepth } from '../limits.js';
+import { eofPositionAt, sourceSpelling } from './tokens.js';
+
+/** @typedef {import('@csstools/css-tokenizer').CSSToken} CSSToken */
+/** @typedef {import('../node.js').Node} Node */
+/** @typedef {import('../node.js').OpaqueComponent} OpaqueComponent */
+/** @typedef {import('./tokens.js').ParseInput} ParseInput */
+/** @typedef {import('./tokens.js').Cursor} Cursor */
+/** @typedef {import('./tokens.js').FunctionToken} FunctionToken */
+/** @typedef {(input: ParseInput, start: number, end: number) => Node} ParseRange */
+
+/** @param {OpaqueComponent[]} target @param {OpaqueComponent} part */
+function pushComponent(target, part) {
+  if (typeof part === 'string' && typeof target.at(-1) === 'string')
+    target[target.length - 1] += part;
+  else target.push(part);
+}
+
+/** @param {ParseInput} input @param {Cursor} cursor @param {FunctionToken} token @param {string} name @return {number} */
+function closeOfCall(input, cursor, token, name) {
+  const close = input.index.closeOf(token.index, input.end);
+  if (close === -1)
+    throw new Error(
+      `Unclosed ${name}( at position ${eofPositionAt(input, cursor.index)}`
+    );
+  return close;
+}
+
+/** @param {ParseInput} input @param {Cursor} cursor @param {FunctionToken} token @param {string} name @param {string} rawName @param {ParseRange} parseRange @return {Node} */
+function parseOpaqueCall(input, cursor, token, name, rawName, parseRange) {
+  const close = closeOfCall(input, cursor, token, name);
+  cursor.skipTo(close + 1);
+  return opaqueCall(
+    name,
+    componentTree(input, token.index + 1, close, parseRange, []),
+    sourceSpelling(rawName, name)
+  );
+}
+
+/** @param {CSSToken[]} tokens @param {number} start @param {number} end */
+function rawTokens(tokens, start, end) {
+  let raw = '';
+  for (let i = start; i < end; i++) raw += tokens[i][1];
+  return raw;
+}
+/** @param {CSSToken[]} tokens @param {number} start @param {number} end */
+function customProperty(tokens, start, end) {
+  /** @type {CSSToken | null} */
+  let found = null;
+  let foundIndex = -1;
+  for (let i = start; i < end; i++) {
+    const type = tokens[i][0];
+    if (type === CssType.Whitespace || type === CssType.Comment) continue;
+    if (found !== null) return null;
+    found = tokens[i];
+    foundIndex = i;
+  }
+  if (!found || found[0] !== CssType.Ident) return null;
+  const decoded = found[4].value;
+  return decoded.startsWith('--') && decoded !== '--'
+    ? { decoded, raw: found[1], index: foundIndex }
+    : null;
+}
+/**
+ * Append the component tree of `[start, end)` to `root` and return it.
+ * Callers seed `root` so leading components need no copy or spread.
+ * @param {ParseInput} input @param {number} start @param {number} rangeEnd @param {ParseRange} parseRange @param {OpaqueComponent[]} root @return {OpaqueComponent[]}
+ */
+function componentTree(input, start, rangeEnd, parseRange, root) {
+  /** @type {OpaqueComponent[]} */ let tree = root;
+  let end = rangeEnd;
+  /** @type {{parent: OpaqueComponent[], tree: OpaqueComponent[], close: number, end: number}[]} */
+  const frames = [];
+  const { tokens } = input;
+  let i = start;
+  while (true) {
+    if (i >= end) {
+      if (frames.length === 0) break;
+      const frame =
+        /** @type {{parent: OpaqueComponent[], tree: OpaqueComponent[], close: number, end: number}} */ (
+          frames.pop()
+        );
+      tree = frame.parent;
+      pushComponent(tree, frame.tree);
+      pushComponent(tree, tokens[frame.close][1]);
+      end = frame.end;
+      i = frame.close + 1;
+      continue;
+    }
+
+    const token = tokens[i];
+    const close = input.index.closeOf(i, end);
+    if (close === -1) {
+      pushComponent(tree, token[1]);
+      i++;
+      continue;
+    }
+
+    const isMathFunction =
+      token[0] === CssType.Function &&
+      (isCalculationFunction(token[4].value) ||
+        isSupportedMathFunction(token[4].value));
+    if (isMathFunction) {
+      try {
+        pushComponent(tree, parseRange(input, i, close + 1));
+      } catch {
+        pushComponent(tree, rawTokens(tokens, i, close + 1));
+      }
+      i = close + 1;
+      continue;
+    }
+
+    pushComponent(tree, token[1]);
+    assertDepth(frames.length + 1);
+    /** @type {OpaqueComponent[]} */
+    const child = [];
+    frames.push({ parent: tree, tree: child, close, end });
+    tree = child;
+    end = close;
+    i++;
+  }
+  return root;
+}
+/** @param {ParseInput} input @param {Cursor} cursor @param {FunctionToken} token @param {string} name @param {string} rawName @param {ParseRange} parseRange @return {Node} */
+function parseVar(input, cursor, token, name, rawName, parseRange) {
+  const { tokens } = input;
+  const start = token.index + 1;
+  const close = closeOfCall(input, cursor, token, name);
+  const comma = input.index.firstTopLevelComma(start, close);
+  const property = customProperty(tokens, start, comma === -1 ? close : comma);
+  if (!property)
+    throw new Error(
+      `Invalid custom property in ${name}() at position ${tokens[start]?.[2] ?? eofPositionAt(input, cursor.index)}`
+    );
+  cursor.skipTo(close + 1);
+  /** @type {OpaqueComponent[]} */
+  const components = [
+    ident(property.decoded, sourceSpelling(property.raw, property.decoded)),
+  ];
+  if (comma !== -1)
+    componentTree(input, property.index + 1, close, parseRange, components);
+  return opaqueCall(name, components, sourceSpelling(rawName, name));
+}
+
+export { parseOpaqueCall, parseVar };

package/src/lib/parser/tokens.js

@@ -0,0 +1,242 @@
+// Token scanning and cursor navigation for the Pratt parser.
+import { TokenType as CssType } from '@csstools/css-tokenizer';
+import { CSS_NUMBER_PREFIX } from '../regex.js';
+
+/** @typedef {import('@csstools/css-tokenizer').CSSToken} CSSToken */
+/** @typedef {ReturnType<typeof import('../block-index.js').indexBlocks>} BlockIndex */
+/** @typedef {{raw: string, pos: number, ws: boolean, index: number}} TokenBase */
+/** @typedef {TokenBase & {type: 'number', value: number, signCharacter?: '+' | '-'}} NumberToken */
+/** @typedef {TokenBase & {type: 'dimension', value: number, unit: string, rawUnit: string, signCharacter?: '+' | '-'}} DimensionToken */
+/** @typedef {TokenBase & {type: 'ident', value: string}} IdentToken */
+/** @typedef {TokenBase & {type: 'function', value: string}} FunctionToken */
+/** @typedef {'(' | ')' | ',' | '+' | '-' | '*' | '/'} Punctuator */
+/** @typedef {TokenBase & {type: 'punct', value: Punctuator}} PunctToken */
+/** @typedef {TokenBase & {type: 'eof', value: '', raw: ''}} EofToken */
+/** @typedef {NumberToken | DimensionToken | IdentToken | FunctionToken | PunctToken | EofToken} Token */
+/**
+ * Immutable bounds and shared block index for one parse range.
+ * @typedef {Readonly<{tokens: CSSToken[], end: number, index: BlockIndex}>} ParseInput
+ */
+
+/** @param {string} value @return {value is '+' | '-' | '*' | '/'} */
+function isOperator(value) {
+  return value === '+' || value === '-' || value === '*' || value === '/';
+}
+
+/** @param {string} raw @param {string} decoded */
+function sourceSpelling(raw, decoded) {
+  return raw === decoded ? undefined : raw;
+}
+
+/**
+ * Mutable navigation state only. `index` is always the next native token
+ * position; trivia is intentionally left visible to `scanToken`.
+ */
+class Cursor {
+  /** @param {number} start */
+  constructor(start) {
+    /** @type {number} */
+    this.index = start;
+    /** @type {boolean} */
+    this.firstToken = true;
+    /** @type {Token | null} */
+    this.lookahead = null;
+    /** @type {number} */
+    this.lookaheadNextIndex = start;
+  }
+
+  /** @param {number} index @return {void} */
+  skipTo(index) {
+    this.index = index;
+    this.lookaheadNextIndex = index;
+    this.firstToken = false;
+    this.lookahead = null;
+  }
+}
+
+/**
+ * Scan one token without consuming it. `firstToken` supplies the virtual
+ * leading trivia at a bounded parse boundary; all later whitespace state is
+ * derived from the native tokens encountered in this scan.
+ *
+ * @param {ParseInput} input
+ * @param {Cursor} cursor
+ * @return {Token}
+ */
+function scanToken(input, cursor) {
+  let i = cursor.index;
+  let ws = cursor.firstToken;
+  while (i < input.end) {
+    const native = input.tokens[i];
+    if (native[0] === CssType.Whitespace || native[0] === CssType.Comment) {
+      ws = true;
+      i++;
+      continue;
+    }
+    if (native[0] === CssType.EOF) break;
+    const token = normalizeToken(native, i, ws);
+    cursor.lookahead = token;
+    cursor.lookaheadNextIndex = i + 1;
+    return token;
+  }
+  /** @type {EofToken} */
+  const token = {
+    type: 'eof',
+    value: '',
+    raw: '',
+    pos: eofPositionAt(input, i),
+    ws,
+    index: i,
+  };
+  cursor.lookahead = token;
+  // Native EOF is a real token and is consumed past its array index. When
+  // the bounded range ends before native EOF, this is a virtual EOF and must
+  // remain at the range boundary.
+  cursor.lookaheadNextIndex =
+    i < input.end && input.tokens[i][0] === CssType.EOF ? i + 1 : input.end;
+  return token;
+}
+
+/** @param {CSSToken} t @param {number} index @param {boolean} ws @return {Token} */
+function normalizeToken(t, index, ws) {
+  const [type, raw, pos, , detail] = t;
+  switch (type) {
+    case CssType.Number:
+      return {
+        type: 'number',
+        value: detail.value,
+        raw,
+        pos,
+        ws,
+        index,
+        signCharacter: detail.signCharacter,
+      };
+    case CssType.Dimension: {
+      const match = CSS_NUMBER_PREFIX.exec(raw);
+      return {
+        type: 'dimension',
+        value: detail.value,
+        raw,
+        pos,
+        ws,
+        index,
+        unit: detail.unit,
+        rawUnit: match ? raw.slice(match[0].length) : detail.unit,
+        signCharacter: detail.signCharacter,
+      };
+    }
+    case CssType.Percentage:
+      return {
+        type: 'dimension',
+        value: detail.value,
+        raw,
+        pos,
+        ws,
+        index,
+        unit: '%',
+        rawUnit: '%',
+        signCharacter: detail.signCharacter,
+      };
+    case CssType.Ident:
+    case CssType.Function:
+      return {
+        type: type === CssType.Ident ? 'ident' : 'function',
+        value: detail.value,
+        raw,
+        pos,
+        ws,
+        index,
+      };
+    case CssType.OpenParen:
+      return { type: 'punct', value: '(', raw, pos, ws, index };
+    case CssType.CloseParen:
+      return { type: 'punct', value: ')', raw, pos, ws, index };
+    case CssType.Comma:
+      return { type: 'punct', value: ',', raw, pos, ws, index };
+    case CssType.Delim:
+      if (isOperator(detail.value))
+        return {
+          type: 'punct',
+          value: detail.value,
+          raw,
+          pos,
+          ws,
+          index,
+        };
+  }
+  throw new Error(`Unexpected character "${raw[0] ?? ''}" at position ${pos}`);
+}
+
+/** @param {ParseInput} input @param {number} index @return {number} */
+function eofPositionAt(input, index) {
+  if (index < input.end && input.tokens[index][0] !== CssType.EOF) {
+    return input.tokens[index][2];
+  }
+  if (
+    input.end < input.tokens.length &&
+    input.tokens[input.end][0] !== CssType.EOF
+  ) {
+    return input.tokens[input.end][2];
+  }
+  for (let i = Math.min(input.end, input.tokens.length) - 1; i >= 0; i--) {
+    const token = input.tokens[i];
+    if (token[0] !== CssType.EOF) return token[3] + 1;
+  }
+  return 0;
+}
+
+/** @param {ParseInput} input @param {Cursor} cursor @return {Token} */
+function peekToken(input, cursor) {
+  return cursor.lookahead ?? scanToken(input, cursor);
+}
+
+/**
+ * Consume the cached token and advance to its native next index. This is one
+ * of the only two operations allowed to advance `cursor.index`.
+ * @param {ParseInput} input
+ * @param {Cursor} cursor
+ * @return {Token}
+ */
+function takeToken(input, cursor) {
+  const token = peekToken(input, cursor);
+  cursor.index = cursor.lookaheadNextIndex;
+  cursor.firstToken = false;
+  cursor.lookahead = null;
+  return token;
+}
+
+/** @param {ParseInput} input @param {Cursor} cursor @param {Punctuator} value @param {Punctuator} [value2] @return {boolean} */
+function isPunct(input, cursor, value, value2) {
+  const t = peekToken(input, cursor);
+  return (
+    t.type === 'punct' &&
+    (t.value === value || (value2 !== undefined && t.value === value2))
+  );
+}
+
+/** @param {ParseInput} input @param {Cursor} cursor @param {Punctuator} value @return {boolean} */
+function matchPunct(input, cursor, value) {
+  if (!isPunct(input, cursor, value)) return false;
+  takeToken(input, cursor);
+  return true;
+}
+
+/** @param {ParseInput} input @param {Cursor} cursor @param {Punctuator} value @return {PunctToken} */
+function expectPunct(input, cursor, value) {
+  const t = takeToken(input, cursor);
+  if (t.type !== 'punct' || t.value !== value) {
+    throw new Error(`Expected ${value} at position ${t.pos}, got "${t.value}"`);
+  }
+  return t;
+}
+
+export {
+  Cursor,
+  eofPositionAt,
+  expectPunct,
+  isPunct,
+  matchPunct,
+  peekToken,
+  sourceSpelling,
+  takeToken,
+};