postcss-calc 11.2.0 → 11.2.2

package/types/lib/parser/tokens.d.ts

@@ -0,0 +1,83 @@
+export type CSSToken = import('@csstools/css-tokenizer').CSSToken;
+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 {string} raw @param {string} decoded */
+declare function sourceSpelling(raw: string, decoded: string): string | undefined;
+/**
+ * Mutable navigation state only. `index` is always the next native token
+ * position; trivia is intentionally left visible to `scanToken`.
+ */
+declare class Cursor {
+    /** @type {number} */
+    index: number;
+    /** @type {boolean} */
+    firstToken: boolean;
+    /** @type {Token | null} */
+    lookahead: Token | null;
+    /** @type {number} */
+    lookaheadNextIndex: number;
+    /** @param {number} start */
+    constructor(start: number);
+    /** @param {number} index @return {void} */
+    skipTo(index: number): void;
+}
+/** @param {ParseInput} input @param {number} index @return {number} */
+declare function eofPositionAt(input: ParseInput, index: number): number;
+/** @param {ParseInput} input @param {Cursor} cursor @return {Token} */
+declare function peekToken(input: ParseInput, cursor: Cursor): Token;
+/**
+ * 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}
+ */
+declare function takeToken(input: ParseInput, cursor: Cursor): Token;
+/** @param {ParseInput} input @param {Cursor} cursor @param {Punctuator} value @param {Punctuator} [value2] @return {boolean} */
+declare function isPunct(input: ParseInput, cursor: Cursor, value: Punctuator, value2?: Punctuator): boolean;
+/** @param {ParseInput} input @param {Cursor} cursor @param {Punctuator} value @return {boolean} */
+declare function matchPunct(input: ParseInput, cursor: Cursor, value: Punctuator): boolean;
+/** @param {ParseInput} input @param {Cursor} cursor @param {Punctuator} value @return {PunctToken} */
+declare function expectPunct(input: ParseInput, cursor: Cursor, value: Punctuator): PunctToken;
+export { Cursor, eofPositionAt, expectPunct, isPunct, matchPunct, peekToken, sourceSpelling, takeToken, };

package/types/lib/parser.d.ts

@@ -1,49 +1,9 @@
 export type CSSToken = import('@csstools/css-tokenizer').CSSToken;
 export type Node = import('./node.js').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;
-}>;
+export type BlockIndex = import('./parser/tokens.js').BlockIndex;
+export type ParseInput = import('./parser/tokens.js').ParseInput;
+export type Token = import('./parser/tokens.js').Token;
+export type FunctionToken = import('./parser/tokens.js').FunctionToken;
 /** @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/serialize/expression.d.ts

@@ -0,0 +1,95 @@
+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 SerializeSession = import('./precision.js').SerializeSession;
+/**
+ * @typedef {import('../node.js').Node} Node
+ * @typedef {import('../node.js').Sum} Sum
+ * @typedef {import('../node.js').Product} Product
+ * @typedef {import('../node.js').ProductFactor} ProductFactor
+ * @typedef {import('./precision.js').SerializeSession} SerializeSession
+ */
+declare const SUM_PRECEDENCE = 1;
+declare const PRODUCT_PRECEDENCE = 2;
+declare const ATOMIC_PRECEDENCE = 3;
+declare const UNARY_PRECEDENCE = 3;
+/** @param {Node} node @return {number} */
+declare function precedence(node: Node): number;
+/**
+ * @param {Node} node
+ * @param {number} parentPrecedence
+ * @param {boolean} groupedRequired
+ * @return {boolean}
+ */
+declare function needsParentheses(node: Node, parentPrecedence: number, groupedRequired: boolean): boolean;
+/**
+ * @param {Node} node
+ * @param {SerializeSession} session
+ * @param {number} [parentPrecedence]
+ * @param {boolean} [groupedRequired]
+ * @return {void}
+ */
+declare function emitNode(node: Node, session: SerializeSession, parentPrecedence?: number, groupedRequired?: boolean): void;
+/**
+ * @param {import('../node.js').Call} node
+ * @param {SerializeSession} session
+ * @param {string} [callNameOverride]
+ * @return {void}
+ */
+declare function emitCall(node: import('../node.js').Call, session: SerializeSession, callNameOverride?: string): void;
+/**
+ * @param {import('../node.js').OpaqueCall} node
+ * @param {SerializeSession} session
+ * @param {string} [callNameOverride]
+ * @return {void}
+ */
+declare function emitOpaqueCall(node: import('../node.js').OpaqueCall, session: SerializeSession, callNameOverride?: string): void;
+/**
+ * @param {import('../node.js').SumTerm} term
+ * @param {1 | -1} multiplier
+ * @param {number | false} precision
+ * @return {1 | -1}
+ */
+declare function termSign(term: import('../node.js').SumTerm, multiplier: 1 | -1, precision: number | false): 1 | -1;
+/**
+ * @param {import('../node.js').SumTerm[]} terms
+ * @param {SerializeSession} session
+ * @param {1 | -1} [multiplier]
+ * @return {void}
+ */
+declare function emitSumTerms(terms: import('../node.js').SumTerm[], session: SerializeSession, multiplier?: 1 | -1): void;
+/** @param {Sum} sum @param {SerializeSession} session @return {void} */
+declare function emitSum(sum: Sum, session: SerializeSession): void;
+/**
+ * @param {Node} node
+ * @param {SerializeSession} session
+ * @return {void}
+ */
+declare function emitLeadingNeg(node: Node, session: SerializeSession): void;
+/**
+ * @param {ProductFactor[]} factors
+ * @param {SerializeSession} session
+ * @param {number} [start]
+ * @param {number} [coefficientValue]
+ * @param {import('../node.js').Num} [coefficientNode]
+ * @return {void}
+ */
+declare function emitProductFactors(factors: ProductFactor[], session: SerializeSession, start?: number, coefficientValue?: number, coefficientNode?: import('../node.js').Num): void;
+/** @param {Product} product @param {SerializeSession} session @return {void} */
+declare function emitProduct(product: Product, session: SerializeSession): void;
+/**
+ * @param {Node} node
+ * @param {SerializeSession} session
+ * @param {string} wrapper
+ * @return {void}
+ */
+declare function emitMathResult(node: Node, session: SerializeSession, wrapper: string): void;
+/**
+ * @param {Node} node
+ * @param {SerializeSession} session
+ * @param {string[]} [buffer]
+ * @return {void}
+ */
+declare function emitNestedMathResult(node: Node, session: SerializeSession, buffer?: string[]): void;
+export { SUM_PRECEDENCE, PRODUCT_PRECEDENCE, ATOMIC_PRECEDENCE, UNARY_PRECEDENCE, precedence, needsParentheses, emitNode, emitCall, emitOpaqueCall, termSign, emitSumTerms, emitSum, emitLeadingNeg, emitProductFactors, emitProduct, emitMathResult, emitNestedMathResult, };

package/types/lib/serialize/precision.d.ts

@@ -0,0 +1,101 @@
+export type Node = import('../node.js').Node;
+export type Num = import('../node.js').Num;
+export type Dim = import('../node.js').Dim;
+export type SerializeSession = {
+    buffer: string[];
+    precision: number | false;
+    scalarPolicy: 'standard' | 'unwrap-all';
+};
+/**
+ * @typedef {import('../node.js').Node} Node
+ * @typedef {import('../node.js').Num} Num
+ * @typedef {import('../node.js').Dim} Dim
+ * @typedef {object} SerializeSession
+ * @property {string[]} buffer
+ * @property {number | false} precision
+ * @property {'standard' | 'unwrap-all'} scalarPolicy
+ */
+declare const NOISE_FLOOR = 1e-12;
+/**
+ * Divide a decimal digit string by 10^k, rounding half away from zero, and
+ * return the resulting integer digit string. `digits` has no leading zeros.
+ * @param {string} digits
+ * @param {number} k
+ * @return {string}
+ */
+declare function divideByPowerOfTen(digits: string, k: number): string;
+/**
+ * Round the shortest decimal representation of a non-negative double to `p`
+ * fractional digits, half away from zero.
+ *
+ * `Number(text + 'e' + p)` reads the exact intended decimal (so `1.005` at
+ * precision 2 becomes `1.01`), but it is only exact while the shifted value
+ * fits in `Number.MAX_SAFE_INTEGER`; beyond that the intermediate double
+ * rounds and can move the rounding boundary (e.g. `312834450754803.44` at
+ * precision 1 or 6 drifted to `312834450754803.5`). Round the decimal digits
+ * directly instead.
+ *
+ * @param {number} abs
+ * @param {number} p
+ * @return {number}
+ */
+declare function roundDecimal(abs: number, p: number): number;
+/**
+ * @param {number} v
+ * @param {number | false} prec
+ * @return {number}
+ */
+declare function round(v: number, prec: number | false): number;
+/** @param {number} v @return {boolean} */
+declare function isDegenerate(v: number): boolean;
+/** @param {number} v @return {string} */
+declare function degenerateKeyword(v: number): string;
+/** @param {number} v @return {string} */
+declare function serializeNumber(v: number): string;
+/**
+ * @param {import('../node.js').Num | import('../node.js').Dim} node
+ * @param {number | false} precision
+ * @param {number} [value]
+ * @return {number}
+ */
+declare function roundedScalarValue(node: import('../node.js').Num | import('../node.js').Dim, precision: number | false, value?: number): number;
+/**
+ * @param {import('../node.js').Num | import('../node.js').Dim} node
+ * @param {string[]} buffer
+ * @param {number} value
+ * @return {void}
+ */
+declare function emitRoundedScalar(node: import('../node.js').Num | import('../node.js').Dim, buffer: string[], value: number): void;
+/**
+ * @param {import('../node.js').Num | import('../node.js').Dim} node
+ * @param {SerializeSession} session
+ * @param {number} [value]
+ * @return {number}
+ */
+declare function emitFiniteScalar(node: import('../node.js').Num | import('../node.js').Dim, session: SerializeSession, value?: number): number;
+/**
+ * @param {import('../node.js').Num | import('../node.js').Dim} node
+ * @param {SerializeSession} session
+ * @param {number} [value]
+ * @return {void}
+ */
+declare function emitScalar(node: import('../node.js').Num | import('../node.js').Dim, session: SerializeSession, value?: number): void;
+/**
+ * @param {string[]} buffer
+ * @param {import('../node.js').Num | import('../node.js').Dim} node
+ * @return {void}
+ */
+declare function emitSignedZero(buffer: string[], node: import('../node.js').Num | import('../node.js').Dim): void;
+/** @param {Node} node @return {node is import('../node.js').Num | import('../node.js').Dim} */
+declare function isScalar(node: Node): node is import('../node.js').Num | import('../node.js').Dim;
+/** @param {Node} node @return {node is import('../node.js').Num | import('../node.js').Dim} */
+declare function isSignedZero(node: Node): node is import('../node.js').Num | import('../node.js').Dim;
+/**
+ * Whether a scalar node is strictly negative after precision rounding
+ * (excluding signed zero and sub-precision values that round to zero).
+ * @param {Node} node
+ * @param {number | false} precision
+ * @return {node is import('../node.js').Num | import('../node.js').Dim}
+ */
+declare function isEffectivelyNegative(node: Node, precision: number | false): node is import('../node.js').Num | import('../node.js').Dim;
+export { NOISE_FLOOR, divideByPowerOfTen, roundDecimal, round, isDegenerate, degenerateKeyword, serializeNumber, roundedScalarValue, emitRoundedScalar, emitFiniteScalar, emitScalar, emitSignedZero, isScalar, isSignedZero, isEffectivelyNegative, };

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

@@ -19,7 +19,10 @@ export type UnitBucket = {
 /** Mutates `buckets` in place — totals of survivor buckets accumulate the
  *  converted values of merged neighbors. Caller must not reuse the input.
  * @param {UnitBucket[]} buckets
+ * @param {number | false} [precision] A conversion that is not exact at this
+ *   precision is not merged. When only the reverse direction is exact, the
+ *   survivor switches to the other bucket's unit.
  * @return {UnitBucket[]}
  */
-declare function mergeConvertibleBuckets(buckets: UnitBucket[]): UnitBucket[];
+declare function mergeConvertibleBuckets(buckets: UnitBucket[], precision?: number | false): UnitBucket[];
 export { mergeConvertibleBuckets };

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

@@ -1,20 +1,24 @@
 /**
  * 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
+ * same base type and convertible units, return the two sides expressed in a
+ * common unit, so the caller can fold them into its own numerator and
+ * denominator. 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}
+ * @param {number | false} [precision] The denominator is converted into the
+ *   numerator's unit when that is exact at this precision (`1px / 1in` →
+ *   `1 / 96`); otherwise the numerator is converted (`1in / 1px` → `96 / 1`).
+ * @return {{ numerator: number, denominator: number, remaining: D[] } | null}
  */
 declare function tryCancelPair<D extends {
     exponent: 1 | -1;
     value: number;
     unit: string;
-}>(dims: D[]): {
-    factor: number;
+}>(dims: D[], precision?: number | false): {
+    numerator: number;
+    denominator: number;
     remaining: D[];
 } | null;
 export { tryCancelPair };

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

@@ -0,0 +1,9 @@
+/**
+ * A value is exact at `precision` when rounding it for output loses nothing
+ * beyond float noise.
+ * @param {number} value
+ * @param {number | false} precision
+ * @return {boolean}
+ */
+declare function isExact(value: number, precision: number | false): boolean;
+export { isExact };

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

@@ -15,6 +15,19 @@ export type BaseType = import('../convertUnits.js').BaseType;
 declare function foldResult(fold: {
     unit: string;
 }, value: number): Num | Dim;
+/**
+ * Return the argument that produced a folded min/max/clamp value, so the
+ * result keeps its own unit, spelling and zero sign. Falls back to a fresh
+ * node when no argument matches (NaN).
+ * @param {Node[]} args
+ * @param {{ values: number[], unit: string }} fold
+ * @param {number} value
+ * @return {Node}
+ */
+declare function chosenArg(args: Node[], fold: {
+    values: number[];
+    unit: string;
+}, value: number): Node;
 /**
  * @param {Node[]} args
  * @return {{ values: number[], unit: string } | null}
@@ -23,4 +36,4 @@ declare function foldConstArgs(args: Node[]): {
     values: number[];
     unit: string;
 } | null;
-export { foldConstArgs, foldResult };
+export { foldConstArgs, foldResult, chosenArg };

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

@@ -2,16 +2,12 @@ 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
+ * @param {number | false} [precision] A quotient that is not exact at this
+ *   precision stays symbolic (`100% / 3`) instead of being rounded.
  * @return {Node}
  */
-declare function simplifyProduct(product: Product, simplify: SimplifyFn): Node;
+declare function simplifyProduct(product: Product, simplify: SimplifyFn, precision?: number | false): Node;
 export { simplifyProduct };

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

@@ -6,7 +6,8 @@ export type UnitBucket = import('./bucket.js').UnitBucket;
 /**
  * @param {Sum} sum
  * @param {SimplifyFn} simplify
+ * @param {number | false} [precision]
  * @return {Node}
  */
-declare function simplifySum(sum: Sum, simplify: SimplifyFn): Node;
+declare function simplifySum(sum: Sum, simplify: SimplifyFn, precision?: number | false): Node;
 export { simplifySum };

package/types/lib/simplify.d.ts

@@ -1,18 +1,13 @@
 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/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 | false} [precision] When set, divisions and unit
+ *   conversions that are not exact at this precision stay symbolic.
  * @param {number} [depth]
  * @return {Node}
  */
-declare function simplify(node: Node, depth?: number): Node;
+declare function simplify(node: Node, precision?: number | false, depth?: number): Node;
 export { simplify };

package/src/lib/calculation-type.js

@@ -1,25 +0,0 @@
-// Compatibility facade for the former calculation-type module. New code uses
-// analyze() for the complete result and limits.js for depth policy.
-
-import { analyze } from './analyze.js';
-import { MAX_CALCULATION_DEPTH, checkCalculationDepth } from './limits.js';
-
-/** @typedef {import('./node.js').Node} Node */
-
-/** @typedef {{kind: 'number'} | {kind: 'dimension', base: string | null} | {kind: 'unknown'} | {kind: 'failure'}} CalculationType */
-
-/** @param {Node} node @return {CalculationType} */
-function checkCalculationType(node) {
-  const result = analyze(node);
-  if (!result.valid) return { kind: 'failure' };
-  if (result.type === 'number') return { kind: 'number' };
-  if (result.type === 'unknown') return { kind: 'unknown' };
-  return { kind: 'dimension', base: result.type.dimension };
-}
-
-export {
-  MAX_CALCULATION_DEPTH,
-  checkCalculationDepth,
-  checkCalculationType,
-  analyze,
-};