postcss-calc 11.1.1 → 11.2.0

package/src/lib/simplify/abs.js

@@ -15,7 +15,7 @@ function simplifyAbs(args) {
     return num(Math.abs(a.value));
   }
   if (a.type === 'Dim' && a.unit !== '%') {
-    return dim(Math.abs(a.value), a.unit);
+    return dim(Math.abs(a.value), a.unit, a.rawUnit);
   }
   return call('abs', [a]);
 }

package/src/lib/simplify/bucket.js

@@ -9,10 +9,10 @@ import { convert } from '../convertUnits.js';
 /**
  * @typedef {object} UnitBucket
  * @property {string} unit
+ * @property {string} [rawUnit]
  * @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
@@ -21,32 +21,27 @@ import { convert } from '../convertUnits.js';
  * @return {UnitBucket[]}
  */
 function mergeConvertibleBuckets(buckets) {
-  const ordered = buckets.sort((a, b) => a.order - b.order);
-  /** @type {Set<string>} */ const merged = new Set();
+  /** @type {Map<import('../convertUnits.js').BaseType, UnitBucket>} */ const representative =
+    new Map();
   /** @type {UnitBucket[]} */ const out = [];
-  for (const b of ordered) {
-    const keyB = b.unit.toLowerCase();
-    if (merged.has(keyB)) {
+  for (const b of buckets) {
+    if (b.base === null) {
+      out.push(b);
       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);
-        }
-      }
+    const first = representative.get(b.base);
+    if (!first) {
+      representative.set(b.base, b);
+      out.push(b);
+      continue;
+    }
+    const converted = convert(b.total, b.unit, first.unit);
+    if (converted === null) {
+      out.push(b);
+      continue;
     }
-    out.push(b);
+    first.total += converted;
+    first.scale = Math.max(first.scale, Math.abs(converted));
   }
   return out;
 }

package/src/lib/simplify/call.js

@@ -1,89 +1,13 @@
 // Pre-simplify args once, route by name. Leaf folds receive simplified
 // args so they don't need to recurse into `simplify` themselves.
 
-import { simplifyMinMax } from './min-max.js';
-import { simplifyClamp } from './clamp.js';
-import { simplifyAbs } from './abs.js';
-import { simplifySign } from './sign.js';
-import { simplifyModRem } from './mod-rem.js';
-import { simplifyRound } from './round.js';
-import { simplifyTrig } from './trig.js';
-import { simplifyInverseTrig } from './inverse-trig.js';
-import { simplifyAtan2 } from './atan2.js';
-import { simplifyPow } from './pow.js';
-import { simplifySqrt } from './sqrt.js';
-import { simplifyExp } from './exp.js';
-import { simplifyLog } from './log.js';
-import { simplifyHypot } from './hypot.js';
-
 import { call } from '../node.js';
+import { mathFunctions, isCalculationFunction } from '../functions.js';
 
 /** @typedef {import('../node.js').Node} Node */
 /** @typedef {import('../simplify.js').SimplifyFn} SimplifyFn */
-
 /** @typedef {(name: string, args: Node[]) => Node} MathSimplifier */
 
-// Bare CSS math functions with implemented simplification semantics, keyed
-// by lowercase name. calc() and its vendor-prefixed forms are handled
-// separately as wrappers in simplifyCall. This map is the single source of
-// truth for dispatch, `isSupportedMathFunction`, and `QUICK_MATH_TEST`.
-/** @type {Map<string, MathSimplifier>} */
-const MATH_SIMPLIFIERS = new Map([
-  ['min', simplifyMinMax],
-  ['max', simplifyMinMax],
-  ['clamp', (_name, args) => simplifyClamp(args)],
-  ['abs', (_name, args) => simplifyAbs(args)],
-  ['sign', (_name, args) => simplifySign(args)],
-  ['mod', (_name, args) => simplifyModRem('mod', args)],
-  ['rem', (_name, args) => simplifyModRem('rem', args)],
-  ['round', (_name, args) => simplifyRound(args)],
-  ['sin', (_name, args) => simplifyTrig('sin', args)],
-  ['cos', (_name, args) => simplifyTrig('cos', args)],
-  ['tan', (_name, args) => simplifyTrig('tan', args)],
-  ['asin', (_name, args) => simplifyInverseTrig('asin', args)],
-  ['acos', (_name, args) => simplifyInverseTrig('acos', args)],
-  ['atan', (_name, args) => simplifyInverseTrig('atan', args)],
-  ['atan2', (_name, args) => simplifyAtan2(args)],
-  ['pow', (_name, args) => simplifyPow(args)],
-  ['sqrt', (_name, args) => simplifySqrt(args)],
-  ['hypot', (_name, args) => simplifyHypot(args)],
-  ['log', (_name, args) => simplifyLog(args)],
-  ['exp', (_name, args) => simplifyExp(args)],
-]);
-
-const mathFnNames = [...MATH_SIMPLIFIERS.keys()].sort(
-  (a, b) => b.length - a.length
-);
-
-const QUICK_MATH_TEST = new RegExp(
-  `(?:-(?:webkit|moz)-)?(?:calc|${mathFnNames.join('|')})\\(`,
-  'i'
-);
-
-/**
- * Fast check to determine whether a CSS component value could contain
- * a supported calculation or math function call (or an escape sequence
- * that could decode to one).
- *
- * @param {string} value
- * @return {boolean}
- */
-function hasPotentialMathFunction(value) {
-  return (
-    value.includes('(') && (QUICK_MATH_TEST.test(value) || value.includes('\\'))
-  );
-}
-
-/**
- * Whether a bare CSS math function has an implemented simplifier.
- *
- * @param {string} name
- * @return {boolean}
- */
-function isSupportedMathFunction(name) {
-  return MATH_SIMPLIFIERS.has(name.toLowerCase());
-}
-
 /**
  * @param {Extract<Node, { type: 'Call' }>} node
  * @param {SimplifyFn} simplify
@@ -92,7 +16,7 @@ function isSupportedMathFunction(name) {
 function simplifyCall(node, simplify) {
   const name = node.name.toLowerCase();
 
-  if (name === 'calc' || name === '-webkit-calc' || name === '-moz-calc') {
+  if (isCalculationFunction(name)) {
     if (node.args.length !== 1) {
       throw new Error(`${node.name}() takes exactly one argument`);
     }
@@ -101,22 +25,12 @@ function simplifyCall(node, simplify) {
 
   const args = node.args.map((a) => simplify(a));
 
-  const simplifier = MATH_SIMPLIFIERS.get(name);
+  const simplifier = mathFunctions.get(name)?.simplify;
   if (simplifier) {
-    // min/max preserve the call's original casing in their opaque-args
-    // fallback; the rest normalize to lowercase internally.
-    return simplifier(
-      name === 'min' || name === 'max' ? node.name : name,
-      args
-    );
+    return simplifier(name, args);
   }
 
-  return call(node.name, args);
+  return call(node.name, args, node.rawName);
 }
 
-export {
-  isSupportedMathFunction,
-  simplifyCall,
-  hasPotentialMathFunction,
-  QUICK_MATH_TEST,
-};
+export { simplifyCall };

package/src/lib/simplify/product.js

@@ -15,7 +15,7 @@ import { tryCancelPair } from './cancel.js';
  */
 function simplifyProduct(product, simplify) {
   let coeff = 1;
-  /** @type {{exponent: 1 | -1, value: number, unit: string}[]} */
+  /** @type {{exponent: 1 | -1, value: number, unit: string, rawUnit?: string}[]} */
   const dims = [];
   /** @type {ProductFactor[]} */
   const opaque = [];
@@ -54,7 +54,7 @@ function simplifyProduct(product, simplify) {
       return;
     }
     if (n.type === 'Dim') {
-      dims.push({ exponent, value: n.value, unit: n.unit });
+      dims.push({ exponent, value: n.value, unit: n.unit, rawUnit: n.rawUnit });
       scalarChain.push({ exponent, value: n.value });
       return;
     }
@@ -112,7 +112,7 @@ function simplifyProduct(product, simplify) {
         value = value / f.value;
       }
     }
-    return dim(value, d.unit);
+    return dim(value, d.unit, d.rawUnit);
   }
 
   if (remainingDims.length === 0 && opaque.length === 0) {
@@ -125,7 +125,10 @@ function simplifyProduct(product, simplify) {
     factors.push({ exponent: 1, node: num(coeff) });
   }
   for (const d of remainingDims) {
-    factors.push({ exponent: d.exponent, node: dim(d.value, d.unit) });
+    factors.push({
+      exponent: d.exponent,
+      node: dim(d.value, d.unit, d.rawUnit),
+    });
   }
   factors.push(...opaque);
 

package/src/lib/simplify/round.js

@@ -44,11 +44,11 @@ function simplifyRound(args) {
   // to applyRound, where floor*b===ceil*b===±∞ collapses back to A
   // (§10.3.1 "result is the same infinity").
   if (Number.isNaN(b)) {
-    return num(Number.NaN);
+    return foldResult(fold, Number.NaN);
   }
   if (!Number.isFinite(b)) {
     if (!Number.isFinite(a)) {
-      return num(Number.NaN);
+      return foldResult(fold, Number.NaN);
     }
     let result;
     if (strategy === 'up' && a > 0) {
@@ -63,7 +63,7 @@ function simplifyRound(args) {
 
   const result = applyRound(strategy, a, b);
   if (Number.isNaN(result)) {
-    return num(Number.NaN);
+    return foldResult(fold, Number.NaN);
   }
   return foldResult(fold, result);
 }
@@ -116,4 +116,4 @@ function applyRound(strategy, a, b) {
   }
 }
 
-export { simplifyRound };
+export { ROUND_STRATEGIES, simplifyRound };

package/src/lib/simplify/sum.js

@@ -1,5 +1,5 @@
 import { mkSum, num, dim } from '../node.js';
-import { baseOf } from '../convertUnits.js';
+import { staticBaseOf } from '../convertUnits.js';
 import { mergeConvertibleBuckets } from './bucket.js';
 
 /**
@@ -34,12 +34,12 @@ function simplifySum(sum, simplify) {
   // encountered unit. `100vh - 5rem - 10rem - 100px` → `-15rem` in phase 1,
   // then vh/rem/px stay separate in phase 2 (none convert to each other).
   let numTotal = 0;
+  let hasNum = false;
   let numScale = 0;
   /** @type {Map<string, UnitBucket>} */
   const byUnit = new Map();
   /** @type {SumTerm[]} */
   const opaque = [];
-  let bucketOrder = 0;
 
   /**
    * @param {1 | -1} sign
@@ -65,7 +65,11 @@ function simplifySum(sum, simplify) {
       return;
     }
     if (n.type === 'Num') {
-      numTotal += sign * n.value;
+      // Do not add an artificial +0 before the first value: `+0 + -0`
+      // becomes +0 in IEEE-754 and would discard a parsed/simplified -0.
+      const value = sign * n.value;
+      numTotal = hasNum ? numTotal + value : value;
+      hasNum = true;
       numScale = Math.max(numScale, Math.abs(n.value));
       return;
     }
@@ -78,10 +82,10 @@ function simplifySum(sum, simplify) {
       } else {
         byUnit.set(key, {
           unit: n.unit,
+          rawUnit: n.rawUnit,
           total: sign * n.value,
           scale: Math.abs(n.value),
-          base: baseOf(n.unit),
-          order: bucketOrder++,
+          base: staticBaseOf(n.unit),
         });
       }
       return;
@@ -93,15 +97,23 @@ function simplifySum(sum, simplify) {
     processTerm(t.sign, simplify(t.node));
   }
 
-  // mkSum drops zero-valued Nums, so pushing the numeric total
-  // unconditionally is harmless. Zero-valued unit buckets are kept for
-  // type info (WPT calc-serialization-002).
+  // Keep a numeric total, including zero, when the source sum contained a
+  // number. In a mixed or unresolved sum that value constrains the other
+  // terms to <number>; mkSum retains it as a type anchor. A negative zero is
+  // also deliberately retained. Zero-valued unit buckets are kept for type
+  // info (WPT calc-serialization-002).
   /** @type {SumTerm[]} */
-  const terms = [{ sign: 1, node: num(denoise(numTotal, numScale)) }];
+  const terms = hasNum
+    ? [{ sign: /** @type {1} */ (1), node: num(denoise(numTotal, numScale)) }]
+    : [];
   for (const bucket of mergeConvertibleBuckets([...byUnit.values()])) {
     terms.push({
       sign: 1,
-      node: dim(denoise(bucket.total, bucket.scale), bucket.unit),
+      node: dim(
+        denoise(bucket.total, bucket.scale),
+        bucket.unit,
+        bucket.rawUnit
+      ),
     });
   }
   terms.push(...opaque);

package/src/lib/simplify.js

@@ -5,31 +5,46 @@
 import { simplifySum } from './simplify/sum.js';
 import { simplifyProduct } from './simplify/product.js';
 import { simplifyCall } from './simplify/call.js';
+import { simplifyComponents } from './opaque.js';
+import { opaqueCall } from './node.js';
+import { assertDepth } from './limits.js';
 
 /**
  * @typedef {import('./node.js').Node} Node
  *
- * Recursive simplifier reference, threaded into Sum/Product/Call. Lets
+ * Recursive simplifier reference, threaded into Sum/Product/Call/OpaqueCall. Lets
  * leaf fold modules avoid circular imports of the entry function.
  * @typedef {(node: Node) => Node} SimplifyFn
  */
 
 /**
+ * Simplify is an independent, composable AST transformation. It may
+ * synthesize canonical nodes while preserving the Node -> Node contract.
  * @param {Node} node
+ * @param {number} [depth]
  * @return {Node}
  */
-function simplify(node) {
+function simplify(node, depth = 0) {
+  assertDepth(depth);
+  /** @param {Node} value */
+  const child = (value) => simplify(value, depth + 1);
   switch (node.type) {
     case 'Num':
     case 'Dim':
     case 'Ident':
       return node;
     case 'Call':
-      return simplifyCall(node, simplify);
+      return simplifyCall(node, child);
+    case 'OpaqueCall':
+      return opaqueCall(
+        node.name,
+        simplifyComponents(node.components, child),
+        node.rawName
+      );
     case 'Sum':
-      return simplifySum(node, simplify);
+      return simplifySum(node, child);
     case 'Product':
-      return simplifyProduct(node, simplify);
+      return simplifyProduct(node, child);
   }
 }
 

package/src/reduce.js

@@ -1,33 +1,20 @@
 // CSS component-value reducer. This module deliberately has no PostCSS
 // dependency so it can also be used for individual declaration values,
 // at-rule parameters, or selector text.
-import {
-  tokenize as cssTokenize,
-  TokenType as CssType,
-} from '@csstools/css-tokenizer';
-import { tokenizeTokens } from './lib/tokenizer.js';
-import { parse } from './lib/parser.js';
-import { simplify } from './lib/simplify.js';
-import {
-  isSupportedMathFunction,
-  hasPotentialMathFunction,
-  QUICK_MATH_TEST,
-} from './lib/simplify/call.js';
-import { serialize } from './lib/serialize.js';
-
-const MATCH_CALC = /^(?:-(?:moz|webkit)-)?calc$/i;
-
-const BLOCK_CLOSE = new Map([
-  [CssType.OpenParen, CssType.CloseParen],
-  [CssType.OpenSquare, CssType.CloseSquare],
-  [CssType.OpenCurly, CssType.CloseCurly],
-]);
+import { tokenize as cssTokenize } from '@csstools/css-tokenizer';
+import { indexBlocks } from './lib/block-index.js';
+import { hasPotentialMathFunction } from './lib/functions.js';
+import { assertDepth } from './lib/limits.js';
+import { findCalculations } from './lib/scan.js';
+import { compileCandidates } from './lib/compile.js';
+import { applyReplacements } from './lib/print.js';
 
 /**
  * @typedef {object} ReduceCalcOptions
  * @property {number | false} [precision]
  * @property {boolean} [warnWhenCannotResolve]
- * @property {boolean} [unwrapSingleNegativeNumber] Serialize finite negative results without a `calc()` wrapper. Defaults to `false`.
+ * @property {boolean} [unwrapSingleNegativeNumber] Deprecated alias for `unwrapSingleValue`.
+ * @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.
  * @property {(message: string) => void} [onWarn] Invoked when `warnWhenCannotResolve` is set and an expression cannot be reduced to a single value.
  */
@@ -41,89 +28,23 @@ const BLOCK_CLOSE = new Map([
  * @property {ResolvedReduceCalcOptions} options
  * @property {string} value
  * @property {import('@csstools/css-tokenizer').CSSToken[]} tokens
- * @property {Replacement[]} replacements
  */
 
 /**
  * @typedef {object} Replacement
  * @property {number} start
  * @property {number} end
- * @property {import('./lib/node.js').Node} node
- * @property {string} calcName
+ * @property {CalculationResult} result
  */
-
 /**
- * Walk one component-value level. Unsupported functions and simple blocks are
- * traversed, while a supported function is treated as one opaque calculation
- * even when parsing it fails. A missing closer consumes through EOF, matching
- * CSS component-value parsing's error recovery.
- *
- * @param {number} start
- * @param {import('@csstools/css-tokenizer').TokenType | undefined} expectedClose
- * @param {TransformContext} ctx
- * @param {boolean} transform
- * @return {number} Index of the matching closer, or the EOF token.
+ * @typedef {object} CalculationResult
+ * @property {import('./lib/node.js').Node} tree
+ * @property {'resolved' | 'unresolved'} status
+ * @property {string} rootName
+ * @property {string} rootSpelling
+ * @property {boolean} calculation
+ * @property {string | undefined} original
  */
-function walkTokens(start, expectedClose, ctx, transform) {
-  for (let i = start; i < ctx.tokens.length; i++) {
-    const token = ctx.tokens[i];
-    if (token[0] === CssType.EOF || token[0] === expectedClose) return i;
-
-    const blockClose = BLOCK_CLOSE.get(token[0]);
-    if (blockClose) {
-      i = walkTokens(i + 1, blockClose, ctx, transform);
-      continue;
-    }
-
-    if (token[0] !== CssType.Function) continue;
-
-    const name = token[4].value;
-    const isCalc = MATCH_CALC.test(name);
-    const isMath = !isCalc && isSupportedMathFunction(name);
-    if (!transform || (!isCalc && !isMath)) {
-      i = walkTokens(i + 1, CssType.CloseParen, ctx, transform);
-      continue;
-    }
-
-    // Locate the complete outer function without transforming its children.
-    const close = walkTokens(i + 1, CssType.CloseParen, ctx, false);
-    const closed = ctx.tokens[close][0] === CssType.CloseParen;
-    const end = closed ? ctx.tokens[close][3] + 1 : ctx.value.length;
-    const sliceStart = isCalc ? i + 1 : i;
-    const sliceEnd = closed ? close + (isCalc ? 0 : 1) : close;
-    const inputStart = isCalc ? token[3] + 1 : token[2];
-    const inputEnd = closed && isCalc ? ctx.tokens[close][2] : end;
-    const contents = ctx.value.slice(inputStart, inputEnd);
-    try {
-      const node = simplify(
-        parse(tokenizeTokens(ctx.tokens, end, sliceStart, sliceEnd))
-      );
-      ctx.replacements.push({
-        start: token[2],
-        end,
-        node,
-        calcName: isCalc ? name : 'calc',
-      });
-    } catch (error) {
-      const err = error instanceof Error ? error : new Error('Error');
-      ctx.options.onParseError?.(err, contents);
-    }
-    i = close;
-  }
-
-  return ctx.tokens.length - 1;
-}
-
-/**
- * @param {import('./lib/node.js').Node} node
- * @return {boolean}
- */
-function isUnresolvedResult(node) {
-  if (node.type === 'Sum' || node.type === 'Product') {
-    return true;
-  }
-  return node.type === 'Call' && isSupportedMathFunction(node.name);
-}
 
 /**
  * Simplify every supported CSS math function in a component-value string.
@@ -143,34 +64,41 @@ function reduceCalc(value, opts) {
     precision: 5,
     warnWhenCannotResolve: false,
     unwrapSingleNegativeNumber: false,
+    unwrapSingleValue: false,
     ...opts,
   };
-  const tokens = cssTokenize({ css: value });
-  /** @type {Replacement[]} */
-  const replacements = [];
-  walkTokens(0, undefined, { options, value, tokens, replacements }, true);
-
-  if (replacements.length === 0) {
+  /** @type {import('@csstools/css-tokenizer').CSSToken[]} */
+  let tokens;
+  /** @type {ReturnType<typeof indexBlocks>} */
+  let index;
+  try {
+    tokens = cssTokenize({ css: value });
+    index = indexBlocks(tokens);
+    assertDepth(index.maxDepth);
+  } catch (error) {
+    options.onParseError?.(
+      error instanceof Error ? error : new Error('Error', { cause: error }),
+      value
+    );
     return value;
   }
 
-  let output = '';
-  let lastIndex = 0;
-  for (const replacement of replacements) {
-    const text = serialize(replacement.node, {
-      precision: options.precision,
-      calcName: replacement.calcName,
-      unwrapSingleNegativeNumber: options.unwrapSingleNegativeNumber,
-    });
-    if (options.warnWhenCannotResolve && isUnresolvedResult(replacement.node)) {
-      options.onWarn?.('Could not reduce expression: ' + value);
-    }
-    output += value.slice(lastIndex, replacement.start) + text;
-    lastIndex = replacement.end;
+  const candidates = findCalculations(value, tokens, index);
+  const replacements = compileCandidates(candidates, {
+    options,
+    value,
+    tokens,
+    index,
+  });
+  if (replacements.length === 0) {
+    return value;
   }
-  output += value.slice(lastIndex);
-  return output;
+  const serializationOptions = {
+    precision: options.precision,
+    unwrapSingleNegativeNumber: options.unwrapSingleNegativeNumber,
+    unwrapSingleValue: options.unwrapSingleValue,
+  };
+  return applyReplacements(value, replacements, options, serializationOptions);
 }
 
-export { QUICK_MATH_TEST, hasPotentialMathFunction };
 export default reduceCalc;

package/types/index.d.ts

@@ -3,6 +3,10 @@ export type PostCssCalcOptions = {
     warnWhenCannotResolve?: boolean;
     mediaQueries?: boolean;
     selectors?: boolean;
+    /**
+     * Serialize fully resolved finite scalar results without calculation syntax. Defaults to `false`.
+     */
+    unwrapSingleValue?: boolean;
     /**
      * Invoked when parse/simplify throws. Replaces the default `result.warn`.
      */

package/types/lib/analyze.d.ts

@@ -0,0 +1,18 @@
+export type Node = import('./node.js').Node;
+export type CalculationType = import('./functions.js').CalculationType;
+export type AnalysisType = 'number' | 'unknown' | {
+    dimension: string | null;
+};
+export type Analysis = {
+    type: AnalysisType;
+    valid: boolean;
+    unresolved: boolean;
+};
+/**
+ * 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}
+ */
+declare function analyze(node: Node): Analysis;
+export { analyze };

package/types/lib/block-index.d.ts

@@ -0,0 +1,35 @@
+export type CSSToken = import('@csstools/css-tokenizer').CSSToken;
+/**
+ * Read-only delimiter navigation for one native token stream range.
+ */
+declare class BlockIndex {
+    #private;
+    /**
+     * 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: CSSToken[], start: number, end: number);
+    /** @return {number} */
+    get maxDepth(): number;
+    /** @param {number} openPosition @param {number} [endPosition] @return {number} */
+    closeOf(openPosition: number, endPosition?: number): number;
+    /** @param {number} position @param {number} endPosition @return {number} */
+    nextComponent(position: number, endPosition: number): number;
+    /** @param {number} startPosition @param {number} endPosition @return {number} */
+    firstTopLevelComma(startPosition: number, endPosition: number): number;
+}
+/**
+ * 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}
+ */
+declare function indexBlocks(tokens: CSSToken[], start?: number, end?: number): BlockIndex;
+export { indexBlocks };