postcss-calc 11.1.2 → 11.2.1

package/types/lib/limits.d.ts

@@ -0,0 +1,8 @@
+/** @typedef {import('./node.js').Node} Node */
+export type Node = import('./node.js').Node;
+declare const MAX_CALCULATION_DEPTH = 1024;
+/** @param {number} depth @return {void} */
+declare function assertDepth(depth: number): void;
+/** @param {Node} node @param {number} [depth] @return {void} */
+declare function checkCalculationDepth(node: Node, depth?: number): void;
+export { MAX_CALCULATION_DEPTH, assertDepth, checkCalculationDepth };

package/types/lib/node.d.ts

@@ -19,6 +19,13 @@ export type Call = {
     args: Node[];
     rawName?: string;
 };
+export type OpaqueComponent = string | Node | OpaqueComponent[];
+export type OpaqueCall = {
+    type: 'OpaqueCall';
+    name: string;
+    components: OpaqueComponent[];
+    rawName?: string;
+};
 export type SumTerm = {
     sign: 1 | -1;
     node: Node;
@@ -36,17 +43,19 @@ export type Product = {
     type: 'Product';
     factors: ProductFactor[];
 };
-export type Node = Num | Dim | Ident | Call | Sum | Product;
+export type Node = Num | Dim | Ident | Call | OpaqueCall | Sum | Product;
 /**
  * @typedef {{type: 'Num', value: number}} Num
  * @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
  */
 /**
  * @param {number} value
@@ -73,6 +82,13 @@ declare function ident(name: string, rawName?: string): Ident;
  * @return {Call}
  */
 declare function call(name: string, args: Node[], rawName?: string): Call;
+/**
+ * @param {string} name
+ * @param {OpaqueComponent[]} components
+ * @param {string} [rawName]
+ * @return {OpaqueCall}
+ */
+declare function opaqueCall(name: string, components: OpaqueComponent[], rawName?: string): OpaqueCall;
 /**
  * @param {SumTerm[]} rawTerms
  * @return {Node}
@@ -89,4 +105,4 @@ declare function mkProduct(rawFactors: ProductFactor[]): Node;
  * @return {Node}
  */
 declare function negate(node: Node): Node;
-export { num, dim, ident, call, mkSum, mkProduct, negate };
+export { num, dim, ident, call, opaqueCall, mkSum, mkProduct, negate };

package/types/lib/opaque.d.ts

@@ -1,15 +1,9 @@
+/** @typedef {import('./node.js').Node} Node */
+/** @typedef {import('./node.js').OpaqueComponent} OpaqueComponent */
 export type Node = import('./node.js').Node;
-export type Component = string | Node | Component[];
-/** @param {Extract<Node, {type: 'Call'}>} node @param {Component[]} tree */
-declare function setComponents(node: Extract<Node, {
-    type: 'Call';
-}>, tree: Component[]): import("./node.js").Call;
-/** @param {Extract<Node, {type: 'Call'}>} node */
-declare function getComponents(node: Extract<Node, {
-    type: 'Call';
-}>): Component[] | undefined;
-/** @param {Component[]} tree @param {(node: Node) => Node} simplify @return {Component[]} */
-declare function simplifyComponents(tree: Component[], simplify: (node: Node) => Node): Component[];
-/** @param {Component[]} tree @param {(node: Node) => string} serialize @return {string} */
-declare function serializeComponents(tree: Component[], serialize: (node: Node) => string): string;
-export { getComponents, setComponents, simplifyComponents, serializeComponents, };
+export type OpaqueComponent = import('./node.js').OpaqueComponent;
+/** @param {OpaqueComponent[]} components @param {(node: Node) => Node} simplify @return {OpaqueComponent[]} */
+declare function simplifyComponents(components: OpaqueComponent[], simplify: (node: Node) => Node): OpaqueComponent[];
+/** @param {OpaqueComponent[]} components @param {string[]} buffer @param {(node: Node, buffer: string[]) => void} serialize @return {void} */
+declare function serializeComponents(components: OpaqueComponent[], buffer: string[], serialize: (node: Node, buffer: string[]) => void): void;
+export { simplifyComponents, serializeComponents };

package/types/lib/parser.d.ts

@@ -1,55 +1,49 @@
 export type CSSToken = import('@csstools/css-tokenizer').CSSToken;
 export type Node = import('./node.js').Node;
-export type Component = string | Node | Component[];
-export type Token = {
-    type: 'number' | 'dimension' | 'ident' | 'function' | 'punct' | 'eof';
-    value: string | number;
+export type OpaqueComponent = import('./node.js').OpaqueComponent;
+export type BlockIndex = ReturnType<typeof import('./block-index.js').indexBlocks>;
+export type TokenBase = {
     raw: string;
-    unit?: string;
-    rawUnit?: string;
-    signCharacter?: '+' | '-';
     pos: number;
     ws: boolean;
+    index: number;
+};
+export type NumberToken = TokenBase & {
+    type: 'number';
+    value: number;
+    signCharacter?: '+' | '-';
+};
+export type DimensionToken = TokenBase & {
+    type: 'dimension';
+    value: number;
+    unit: string;
+    rawUnit: string;
+    signCharacter?: '+' | '-';
+};
+export type IdentToken = TokenBase & {
+    type: 'ident';
+    value: string;
+};
+export type FunctionToken = TokenBase & {
+    type: 'function';
+    value: string;
+};
+export type Punctuator = '(' | ')' | ',' | '+' | '-' | '*' | '/';
+export type PunctToken = TokenBase & {
+    type: 'punct';
+    value: Punctuator;
+};
+export type EofToken = TokenBase & {
+    type: 'eof';
+    value: '';
+    raw: '';
 };
-export type PrefixParselet = (p: Parser, token: Token) => Node;
-/** Bounded cursor that skips trivia but records whether it preceded a token. */
-declare class Parser {
-    #private;
-    /**
-     * @param {CSSToken[]} tokens
-     * @param {number} start
-     * @param {number} end
-     * @param {Map<number, number>} [ends]
-     */
-    constructor(tokens: CSSToken[], start: number, end: number, ends?: Map<number, number>);
-    /** @return {Map<number, number>} */
-    get ends(): Map<number, number>;
-    /** @return {number} */
-    eofPosition(): number;
-    /** @return {Token} */
-    read(): Token;
-    /** @return {Token} */
-    peek(): Token;
-    /** @return {Token} */
-    next(): Token;
-    /** @return {{start: number, close: number, tokens: CSSToken[], ends: Map<number, number>}} */
-    functionRange(): {
-        start: number;
-        close: number;
-        tokens: CSSToken[];
-        ends: Map<number, number>;
-    };
-    /** @param {number} index */
-    consumeThrough(index: number): void;
-    /** @param {string} value @param {string} [value2] @return {boolean} */
-    isPunct(value: string, value2?: string): boolean;
-    /** @param {string} value @return {boolean} */
-    matchPunct(value: string): boolean;
-    /** @param {string} value @return {Token} */
-    expectPunct(value: string): Token;
-    /** @param {number} [minBp] @return {Node} */
-    parseExpr(minBp?: number): Node;
-}
-/** @param {CSSToken[]} tokens @param {number} [start] @param {number} [end] @return {Node} */
-declare function parse(tokens: CSSToken[], start?: number, end?: number): Node;
+export type Token = NumberToken | DimensionToken | IdentToken | FunctionToken | PunctToken | EofToken;
+export type ParseInput = Readonly<{
+    tokens: CSSToken[];
+    end: number;
+    index: BlockIndex;
+}>;
+/** @param {CSSToken[]} tokens @param {number} start @param {number} end @param {BlockIndex} index @return {Node} */
+declare function parse(tokens: CSSToken[], start: number, end: number, index: BlockIndex): Node;
 export { parse };

package/types/lib/print.d.ts

@@ -0,0 +1,16 @@
+export type ResolvedReduceCalcOptions = import('../reduce.js').ResolvedReduceCalcOptions;
+export type Replacement = import('../reduce.js').Replacement;
+export type SerializeOptions = import('./serialize.js').SerializeOptions;
+/**
+ * Serialize compiled candidates and splice the resulting text into the
+ * original source. Replacements are already non-overlapping because the
+ * finder treats a supported outer function as one range.
+ *
+ * @param {string} value
+ * @param {Replacement[]} replacements
+ * @param {ResolvedReduceCalcOptions} options
+ * @param {SerializeOptions} serializeOptions
+ * @return {string}
+ */
+declare function applyReplacements(value: string, replacements: Replacement[], options: ResolvedReduceCalcOptions, serializeOptions: SerializeOptions): string;
+export { applyReplacements };

package/types/lib/regex.d.ts

@@ -0,0 +1,2 @@
+declare const CSS_NUMBER_PREFIX: RegExp;
+export { CSS_NUMBER_PREFIX };

package/types/lib/scan.d.ts

@@ -0,0 +1,35 @@
+export type Candidate = {
+    name: string;
+    normalizedName: string;
+    start: number;
+    end: number;
+    rootSpelling: string;
+    calculation: boolean;
+    sliceStart: number;
+    sliceEnd: number;
+    closed: boolean;
+};
+/**
+ * @typedef {object} Candidate
+ * @property {string} name
+ * @property {string} normalizedName
+ * @property {number} start
+ * @property {number} end
+ * @property {string} rootSpelling
+ * @property {boolean} calculation
+ * @property {number} sliceStart
+ * @property {number} sliceEnd
+ * @property {boolean} closed
+ */
+/**
+ * Find complete supported math-function ranges. A supported function is
+ * treated as one candidate even when parsing it later fails, so nested
+ * calculations cannot produce partial output for an invalid outer function.
+ *
+ * @param {string} value
+ * @param {import('@csstools/css-tokenizer').CSSToken[]} tokens
+ * @param {ReturnType<typeof import('./block-index.js').indexBlocks>} index
+ * @return {Candidate[]}
+ */
+declare function findCalculations(value: string, tokens: import('@csstools/css-tokenizer').CSSToken[], index: ReturnType<typeof import('./block-index.js').indexBlocks>): Candidate[];
+export { findCalculations };

package/types/lib/serialize.d.ts

@@ -12,9 +12,13 @@ export type SerializeOptions = {
      */
     calcName?: string;
     /**
-     * Serialize finite negative scalars without a wrapper. Internal selector-only mode.
+     * Deprecated alias for `unwrapSingleValue`.
      */
     unwrapSingleNegativeNumber?: boolean;
+    /**
+     * Serialize fully resolved finite scalar results without calculation syntax.
+     */
+    unwrapSingleValue?: boolean;
 };
 /**
  * @param {Node} node
@@ -22,4 +26,17 @@ export type SerializeOptions = {
  * @return {string}
  */
 declare function serialize(node: Node, opts?: SerializeOptions): string;
-export { serialize };
+/**
+ * @param {{tree: Node, status: 'resolved' | 'unresolved', rootName: string, rootSpelling: string, calculation?: boolean, original?: string}} result
+ * @param {SerializeOptions} [opts]
+ * @return {string}
+ */
+declare function serializeResult(result: {
+    tree: Node;
+    status: 'resolved' | 'unresolved';
+    rootName: string;
+    rootSpelling: string;
+    calculation?: boolean;
+    original?: string;
+}, opts?: SerializeOptions): string;
+export { serialize, serializeResult };

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

@@ -1,23 +1,9 @@
 export type Node = import('../node.js').Node;
 export type SimplifyFn = import('../simplify.js').SimplifyFn;
 export type MathSimplifier = (name: string, args: Node[]) => Node;
-declare const QUICK_MATH_TEST: RegExp;
-/**
- * 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}
- */
-declare function hasPotentialMathFunction(value: string): boolean;
-/**
- * Whether a bare CSS math function has an implemented simplifier.
- *
- * @param {string} name
- * @return {boolean}
- */
-declare function isSupportedMathFunction(name: string): boolean;
+/** @typedef {import('../node.js').Node} Node */
+/** @typedef {import('../simplify.js').SimplifyFn} SimplifyFn */
+/** @typedef {(name: string, args: Node[]) => Node} MathSimplifier */
 /**
  * @param {Extract<Node, { type: 'Call' }>} node
  * @param {SimplifyFn} simplify
@@ -26,4 +12,4 @@ declare function isSupportedMathFunction(name: string): boolean;
 declare function simplifyCall(node: Extract<Node, {
     type: 'Call';
 }>, simplify: SimplifyFn): Node;
-export { isSupportedMathFunction, simplifyCall, hasPotentialMathFunction, QUICK_MATH_TEST, };
+export { simplifyCall };

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

@@ -1,4 +1,6 @@
 export type Node = import('../node.js').Node;
+/** @typedef {import('../node.js').Node} Node */
+declare const ROUND_STRATEGIES: Set<string>;
 export type RoundStrategy = 'nearest' | 'up' | 'down' | 'to-zero';
 /** @typedef {'nearest' | 'up' | 'down' | 'to-zero'} RoundStrategy */
 /**
@@ -6,4 +8,4 @@ export type RoundStrategy = 'nearest' | 'up' | 'down' | 'to-zero';
  * @return {Node}
  */
 declare function simplifyRound(args: Node[]): Node;
-export { simplifyRound };
+export { ROUND_STRATEGIES, simplifyRound };

package/types/lib/simplify.d.ts

@@ -3,13 +3,16 @@ export type SimplifyFn = (node: Node) => Node;
 /**
  * @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}
  */
-declare function simplify(node: Node): Node;
+declare function simplify(node: Node, depth?: number): Node;
 export { simplify };

package/types/reduce.d.ts

@@ -1,11 +1,14 @@
-import { hasPotentialMathFunction, QUICK_MATH_TEST } from './lib/simplify/call.js';
 export type ReduceCalcOptions = {
     precision?: number | false;
     warnWhenCannotResolve?: boolean;
     /**
-     * Serialize finite negative results without a `calc()` wrapper. Defaults to `false`.
+     * Deprecated alias for `unwrapSingleValue`.
      */
     unwrapSingleNegativeNumber?: boolean;
+    /**
+     * Serialize fully resolved finite scalar results without calculation syntax. Defaults to `false`.
+     */
+    unwrapSingleValue?: boolean;
     /**
      * Invoked when parse/simplify throws.
      */
@@ -20,14 +23,53 @@ export type TransformContext = {
     options: ResolvedReduceCalcOptions;
     value: string;
     tokens: import('@csstools/css-tokenizer').CSSToken[];
-    replacements: Replacement[];
 };
 export type Replacement = {
     start: number;
     end: number;
-    node: import('./lib/node.js').Node;
-    calcName: string;
+    result: CalculationResult;
+};
+export type CalculationResult = {
+    tree: import('./lib/node.js').Node;
+    status: 'resolved' | 'unresolved';
+    rootName: string;
+    rootSpelling: string;
+    calculation: boolean;
+    original: string | undefined;
 };
+/**
+ * @typedef {object} ReduceCalcOptions
+ * @property {number | false} [precision]
+ * @property {boolean} [warnWhenCannotResolve]
+ * @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.
+ */
+/** @typedef {Required<Omit<ReduceCalcOptions, 'onParseError' | 'onWarn'>> & Pick<ReduceCalcOptions, 'onParseError' | 'onWarn'>} ResolvedReduceCalcOptions */
+/**
+ * Fields threaded through the internal token-range walk.
+ *
+ * @typedef {object} TransformContext
+ * @property {ResolvedReduceCalcOptions} options
+ * @property {string} value
+ * @property {import('@csstools/css-tokenizer').CSSToken[]} tokens
+ */
+/**
+ * @typedef {object} Replacement
+ * @property {number} start
+ * @property {number} end
+ * @property {CalculationResult} result
+ */
+/**
+ * @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
+ */
 /**
  * Simplify every supported CSS math function in a component-value string.
  * Text outside those functions is preserved byte-for-byte.
@@ -37,5 +79,4 @@ export type Replacement = {
  * @return {string}
  */
 declare function reduceCalc(value: string, opts?: ReduceCalcOptions): string;
-export { QUICK_MATH_TEST, hasPotentialMathFunction };
 export default reduceCalc;

package/src/lib/tokenizer.js

@@ -1,10 +0,0 @@
-// Thin project-local entry point for the CSS Syntax tokenizer. The parser
-// consumes native tokens directly so decoded values and source spelling remain available.
-import { tokenize as tokenizeCss } from '@csstools/css-tokenizer';
-
-/** @param {string} input @return {import('@csstools/css-tokenizer').CSSToken[]} */
-function tokenize(input) {
-  return tokenizeCss({ css: input });
-}
-
-export { tokenize };

package/types/lib/tokenizer.d.ts

@@ -1,3 +0,0 @@
-/** @param {string} input @return {import('@csstools/css-tokenizer').CSSToken[]} */
-declare function tokenize(input: string): import('@csstools/css-tokenizer').CSSToken[];
-export { tokenize };