postcss-calc 11.1.1 → 11.2.0

package/types/lib/calculation-type.d.ts

@@ -0,0 +1,18 @@
+import { analyze } from './analyze.js';
+import { MAX_CALCULATION_DEPTH, checkCalculationDepth } from './limits.js';
+export type Node = import('./node.js').Node;
+export type CalculationType = {
+    kind: 'number';
+} | {
+    kind: 'dimension';
+    base: string | null;
+} | {
+    kind: 'unknown';
+} | {
+    kind: 'failure';
+};
+/** @typedef {import('./node.js').Node} Node */
+/** @typedef {{kind: 'number'} | {kind: 'dimension', base: string | null} | {kind: 'unknown'} | {kind: 'failure'}} CalculationType */
+/** @param {Node} node @return {CalculationType} */
+declare function checkCalculationType(node: Node): CalculationType;
+export { MAX_CALCULATION_DEPTH, checkCalculationDepth, checkCalculationType, analyze, };

package/types/lib/compile.d.ts

@@ -0,0 +1,37 @@
+export type Candidate = import('./scan.js').Candidate;
+export type ResolvedReduceCalcOptions = import('../reduce.js').ResolvedReduceCalcOptions;
+export type Replacement = import('../reduce.js').Replacement;
+export type CSSToken = import('@csstools/css-tokenizer').CSSToken;
+export type BlockIndex = ReturnType<typeof import('./block-index.js').indexBlocks>;
+export type CompileContext = {
+    options: ResolvedReduceCalcOptions;
+    value: string;
+    tokens: CSSToken[];
+    index: BlockIndex;
+};
+/** @typedef {import('./scan.js').Candidate} Candidate */
+/** @typedef {import('../reduce.js').ResolvedReduceCalcOptions} ResolvedReduceCalcOptions */
+/** @typedef {import('../reduce.js').Replacement} Replacement */
+/** @typedef {import('@csstools/css-tokenizer').CSSToken} CSSToken */
+/** @typedef {ReturnType<typeof import('./block-index.js').indexBlocks>} BlockIndex */
+/** @typedef {{options: ResolvedReduceCalcOptions, value: string, tokens: CSSToken[], index: BlockIndex}} CompileContext */
+/**
+ * Parse, analyze, and simplify one candidate. Analysis is the validity/status
+ * gate over the original tree; simplification then runs independently as a
+ * composable AST transformation that may synthesize nodes.
+ *
+ * @param {Candidate} candidate
+ * @param {CompileContext} ctx
+ * @return {Replacement}
+ */
+declare function compileCandidate(candidate: Candidate, ctx: CompileContext): Replacement;
+/**
+ * Compile candidates independently so one malformed calculation is preserved
+ * without preventing unrelated candidates from being reduced.
+ *
+ * @param {Candidate[]} candidates
+ * @param {CompileContext} ctx
+ * @return {Replacement[]}
+ */
+declare function compileCandidates(candidates: Candidate[], ctx: CompileContext): Replacement[];
+export { compileCandidate, compileCandidates };

package/types/lib/convertUnits.d.ts

@@ -14,4 +14,11 @@ declare function baseOf(unit: string): BaseType | null;
  * @return {number | null}
  */
 declare function convert(value: number, from: string, to: string): number | null;
-export { baseOf, convert };
+/**
+ * Return a base type only for units present in the static conversion table.
+ * Units with context-dependent values (em, rem, vw, etc.) return null.
+ * @param {string} unit
+ * @return {BaseType | null}
+ */
+declare function staticBaseOf(unit: string): BaseType | null;
+export { baseOf, staticBaseOf, convert };

package/types/lib/functions.d.ts

@@ -0,0 +1,40 @@
+export type Node = import('./node.js').Node;
+export type CalculationType = {
+    kind: 'number';
+} | {
+    kind: 'dimension';
+    base: string | null;
+} | {
+    kind: 'unknown';
+} | {
+    kind: 'failure';
+};
+export type MathSimplifier = (name: string, args: Node[]) => Node;
+export type TypeAnalyzer = (args: CalculationType[], nodes: Node[]) => CalculationType;
+export type MathFunction = {
+    analyze: TypeAnalyzer;
+    simplify?: MathSimplifier;
+    isKeyword?: (node: Node, index: number) => boolean;
+    calculation?: boolean;
+};
+/** @param {CalculationType} type @return {boolean} */
+declare function isFailure(type: CalculationType): boolean;
+/** @param {CalculationType} a @param {CalculationType} b @return {CalculationType} */
+declare function addTypes(a: CalculationType, b: CalculationType): CalculationType;
+declare const mathFunctions: Map<string, MathFunction>;
+/**
+ * @param {string} name
+ * @return {{normalizedName: string, definition: MathFunction} | undefined}
+ */
+declare function lookupMathFunction(name: string): {
+    normalizedName: string;
+    definition: MathFunction;
+} | undefined;
+declare const QUICK_MATH_TEST: RegExp;
+/** @param {string} name @return {boolean} */
+declare function isCalculationFunction(name: string): boolean;
+/** @param {string} name @return {boolean} */
+declare function isSupportedMathFunction(name: string): boolean;
+/** @param {string} value @return {boolean} */
+declare function hasPotentialMathFunction(value: string): boolean;
+export { addTypes, mathFunctions, lookupMathFunction, QUICK_MATH_TEST, isFailure, isCalculationFunction, isSupportedMathFunction, hasPotentialMathFunction, };

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

@@ -6,15 +6,25 @@ export type Dim = {
     type: 'Dim';
     value: number;
     unit: string;
+    rawUnit?: string;
 };
 export type Ident = {
     type: 'Ident';
     name: string;
+    rawName?: string;
 };
 export type Call = {
     type: 'Call';
     name: string;
     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;
@@ -33,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}} Dim
- * @typedef {{type: 'Ident', name: string}} Ident
- * @typedef {{type: 'Call', name: string, args: Node[]}} Call
+ * @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
@@ -53,20 +65,30 @@ declare function num(value: number): Num;
 /**
  * @param {number} value
  * @param {string} unit
+ * @param {string} [rawUnit]
  * @return {Dim}
  */
-declare function dim(value: number, unit: string): Dim;
+declare function dim(value: number, unit: string, rawUnit?: string): Dim;
 /**
  * @param {string} name
+ * @param {string} [rawName]
  * @return {Ident}
  */
-declare function ident(name: string): Ident;
+declare function ident(name: string, rawName?: string): Ident;
 /**
  * @param {string} name
  * @param {Node[]} args
+ * @param {string} [rawName]
  * @return {Call}
  */
-declare function call(name: string, args: Node[]): 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}
@@ -83,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

@@ -0,0 +1,9 @@
+/** @typedef {import('./node.js').Node} Node */
+/** @typedef {import('./node.js').OpaqueComponent} OpaqueComponent */
+export type Node = import('./node.js').Node;
+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,51 +1,49 @@
-export type Token = import('./tokenizer.js').Token;
-export type TokenType = import('./tokenizer.js').TokenType;
+export type CSSToken = import('@csstools/css-tokenizer').CSSToken;
 export type Node = import('./node.js').Node;
-export type PrefixParselet = (p: Parser, token: Token) => Node;
-declare class Parser {
-    /** @private */
-    i;
-    /** @private @readonly */
-    tokens;
-    /**
-     * @param {Token[]} tokens
-     */
-    constructor(tokens: Token[]);
-    /** @return {Token} */
-    peek(): Token;
-    /** @return {Token} */
-    next(): Token;
-    /**
-     * @param {TokenType} type
-     * @param {string} [value]
-     * @return {Token}
-     */
-    expect(type: TokenType, value?: string): Token;
-    /**
-     * @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 {Token[]} tokens
- * @return {Node}
- */
-declare function parse(tokens: Token[]): Node;
+export type OpaqueComponent = import('./node.js').OpaqueComponent;
+export type BlockIndex = ReturnType<typeof import('./block-index.js').indexBlocks>;
+export type TokenBase = {
+    raw: string;
+    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 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/bucket.d.ts

@@ -1,20 +1,20 @@
 export type UnitBucket = {
     unit: string;
+    rawUnit?: string;
     total: number;
     /**
      * largest |term| accumulated into `total`, for noise detection
      */
     scale: number;
     base: import('../convertUnits.js').BaseType | null;
-    order: number;
 };
 /**
  * @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
  *  converted values of merged neighbors. Caller must not reuse the input.

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;