@thejaredwilcurt/csslop 0.0.49 → 0.0.50

package/src/value/math/index.js

@@ -0,0 +1,219 @@
+/**
+ * @file Simplifies CSS math functions (calc, min, max) by folding constant expressions, flattening nested calcs, and converting absolute lengths to pixels.
+ */
+
+import {
+  convertAbsoluteLengthToPx,
+  formatResolvedNumber,
+  roundCompactNumber
+} from '../shared.js';
+
+import { simplifyCalc } from './evaluate.js';
+import {
+  foldStandaloneCalc,
+  resolveCalcExpression
+} from './fold.js';
+import { MATH_FUNCTION_NAMES } from './functions.js';
+import { clampResolvedValueToPropertyRange } from './property-ranges.js';
+import {
+  convertReciprocalMultiplicationToDivision,
+  rewriteMathFunctionContents,
+  shortenDecimalNumbers
+} from './rewrite.js';
+
+/**
+ * Characters that start a token able to sit directly against a value that
+ * precedes them, so no whitespace is needed to keep the two tokens apart:
+ * whitespace already separates, and openers like `#`, `!`, or any bracket or
+ * punctuation mark their own token's start. Mirrors the tokenizer's notion of
+ * tokens marking their own start, with `/` on top since it delimits a size
+ * from a position in layered shorthands.
+ *
+ * @type {Set<string>}
+ */
+const SELF_DELIMITING_FOLLOWERS = new Set([
+  ' ',
+  '\t',
+  '\n',
+  '\r',
+  '\f',
+  '#',
+  '!',
+  '"',
+  '\'',
+  '(',
+  ')',
+  '[',
+  ']',
+  '{',
+  '}',
+  ',',
+  ':',
+  ';',
+  '/'
+]);
+
+/**
+ * Reports whether a math function's replacement glues itself to the character
+ * following the matched function, merging two values into one token. A
+ * replacement that keeps its function form ends with a parenthesis, which
+ * closes itself; only a bare resolved value needs the whitespace that the
+ * parenthesis padding removal took away.
+ *
+ * @param  {string}  replacement         The string the math function resolved to.
+ * @param  {string}  followingCharacter  The character directly after the matched function.
+ * @return {boolean}                     Whether a separating space must be restored.
+ */
+function mergesWithFollowingCharacter (replacement, followingCharacter) {
+  if (replacement.endsWith(')') || !followingCharacter) {
+    return false;
+  }
+  return !SELF_DELIMITING_FOLLOWERS.has(followingCharacter);
+}
+
+/**
+ * Wraps a math-function replacer so a function that dissolves into a bare
+ * value does not lose the whitespace separating it from the value behind it.
+ * The values were once told apart by where the function's parentheses sat, so
+ * when the parentheses go, the separator has to stay.
+ *
+ * @param  {function(string, ...(string|number|undefined)): string} replacer  The replacement callback for `String.prototype.replace`.
+ * @return {function(string, ...(string|number|undefined)): string}           A replacer that keeps the trailing separator intact.
+ */
+function keepSeparatorAfterDissolvedFunction (replacer) {
+  return (match, ...rest) => {
+    const replacement = replacer(match, ...rest);
+    // A replace callback's trailing arguments are the match offset and the full string
+    const fullText = rest[rest.length - 1];
+    const matchOffset = rest[rest.length - 2];
+    const followingCharacter = fullText[matchOffset + match.length];
+    if (mergesWithFollowingCharacter(replacement, followingCharacter)) {
+      return replacement + ' ';
+    }
+    return replacement;
+  };
+}
+
+/**
+ * Matches a math function other than `calc()` whose arguments hold no further
+ * parentheses, so that the whole of the function is matched. A `calc()` is
+ * left to its own pass, which weighs what the calculation resolves to against
+ * the calculation itself.
+ *
+ * @type {RegExp}
+ */
+const RESOLVABLE_MATH_FUNCTION = new RegExp(
+  '\\b(?:' +
+  [...MATH_FUNCTION_NAMES].filter((name) => {
+    return name !== 'calc';
+  }).join('|') +
+  ')\\([^()]+\\)',
+  'gi'
+);
+
+/**
+ * Runs one pass of the math simplifications over a value: the rewrites that
+ * state a calculation more compactly, and the resolutions that replace a math
+ * function with the value it works out to.
+ *
+ * @param  {string} value     The CSS value string containing math functions to simplify.
+ * @param  {string} property  The CSS property name, whose range every resolved result is clamped into.
+ * @return {string}           The value with its math functions simplified where possible.
+ */
+function simplifyMathFunctionsOnce (value, property) {
+  let result = rewriteMathFunctionContents(shortenDecimalNumbers, value);
+  result = rewriteMathFunctionContents(convertReciprocalMultiplicationToDivision, result);
+
+  // Unwrap calc(1 / (1 / x)) → x (double-reciprocal identity)
+  result = result.replace(/calc\(\s*1\s*\/\s*\(\s*1\s*\/\s*([^()]+)\s*\)\s*\)/gi, keepSeparatorAfterDissolvedFunction((match, inner) => {
+    return inner.trim();
+  }));
+  // Flatten calc(calc(a) ± b) → calc(a ± b)
+  result = result.replace(/calc\(\s*calc\(([^()]+)\)\s*([+-])\s*([^()]+)\s*\)/gi, keepSeparatorAfterDissolvedFunction((match, inner, operator, tail) => {
+    return 'calc(' + inner + ' ' + operator + ' ' + tail + ')';
+  }));
+  // Unwrap calc(calc(x)) → calc(x)
+  result = result.replace(/calc\(\s*calc\(([^()]+)\)\s*\)/gi, keepSeparatorAfterDissolvedFunction((match, inner) => {
+    return 'calc(' + inner + ')';
+  }));
+
+  // Resolve every math function that compares or rounds its arguments
+  result = result.replace(RESOLVABLE_MATH_FUNCTION, keepSeparatorAfterDissolvedFunction((match) => {
+    const simplified = simplifyCalc(match);
+    if (simplified === null) {
+      return match;
+    }
+    return clampResolvedValueToPropertyRange(simplified, property);
+  }));
+
+  // Simplify calc() expressions using constant folding and expression resolution
+  result = result.replace(/calc\(([^()]+)\)/gi, keepSeparatorAfterDissolvedFunction((match, inner) => {
+    // Collapse whitespace inside calc expression
+    const compactInner = inner.replace(/\s+/g, ' ').trim();
+    const resolved = resolveCalcExpression(match, compactInner);
+    return clampResolvedValueToPropertyRange(resolved, property);
+  }));
+
+  return result;
+}
+
+/**
+ * Simplifies every math function within a CSS value string, resolving the ones
+ * whose operands are all known and stating the rest as compactly as they can
+ * be written.
+ *
+ * @param  {string} value          The CSS value string containing math functions to simplify.
+ * @param  {string} property       The CSS property name, whose range every resolved result is clamped into.
+ * @param  {string} originalValue  The value as it was authored, which tells whether a result was ever part of a calculation.
+ * @return {string}                The value with math functions simplified where possible.
+ */
+function normalizeMathFunctions (value, property, originalValue = '') {
+  let result = value;
+  let previous;
+
+  do {
+    previous = result;
+    // Resolving a math function leaves a plain value where it stood, which can
+    // bring the function it was nested in within reach of the next pass, so
+    // the value is simplified until it settles
+    result = simplifyMathFunctionsOnce(result, property);
+  } while (result !== previous);
+
+  // When calc() folded to an absolute-length unit (pt, pc, in, cm, mm, q), convert to pixels
+  if (originalValue.includes('calc(') && /^-?(?:\d+|\d*\.\d+)(pt|pc|in|cm|mm|q)$/i.test(result)) {
+    // Extract the absolute-length unit from the folded result
+    const [, unit] = result.match(/^-?(?:\d+|\d*\.\d+)(pt|pc|in|cm|mm|q)$/i);
+    const numeric = parseFloat(result);
+    const pxValue = convertAbsoluteLengthToPx(numeric, unit);
+    if (pxValue !== null) {
+      result = roundCompactNumber(pxValue) + 'px';
+    }
+  }
+
+  // Round a result whose decimal places run past the budget a resolved number is written within
+  result = result.replace(/(-?(?:\d+|\d*\.\d+)\.\d{4,})([a-z%]+)/gi, (match, number, unit) => {
+    return formatResolvedNumber(number) + unit;
+  });
+  return result;
+}
+
+/**
+ * Simplifies a value that is a single `calc()`, holding whatever it resolves
+ * to inside the range the property it is declared on accepts.
+ *
+ * @param  {string} value     The CSS value string that may be a standalone calc() expression.
+ * @param  {string} property  The CSS property the value is declared on.
+ * @return {string}           The simplified value, or the original value if simplification is not applicable.
+ */
+function simplifyStandaloneCalc (value, property = '') {
+  // Check if value starts with calc( and ends with )
+  if (!/^calc\(/i.test(value) || !value.endsWith(')')) {
+    return value;
+  }
+  return clampResolvedValueToPropertyRange(foldStandaloneCalc(value), property);
+}
+
+export {
+  normalizeMathFunctions,
+  simplifyStandaloneCalc
+};

package/src/value/math/parser.js

@@ -0,0 +1,301 @@
+/**
+ * @file Reads the tokens of a CSS math function as sums, products, and operands, resolving each into the unit totals it states.
+ */
+
+import { MATH_FUNCTION_EVALUATORS } from './functions.js';
+import {
+  addUnitTotals,
+  createUnitTotals,
+  divideUnitTotals,
+  multiplyUnitTotals,
+  scaleUnitTotals,
+  UNITLESS
+} from './unit-totals.js';
+
+/**
+ * The numeric constants a calculation may name instead of writing out, as the
+ * keywords section of the CSS Values specification defines them:
+ * https://drafts.csswg.org/css-values/#calc-keywords.
+ *
+ * @type {Map<string, number>}
+ */
+const NUMERIC_CONSTANTS = new Map([
+  ['e', Math.E],
+  ['infinity', Infinity],
+  ['nan', NaN],
+  ['pi', Math.PI]
+]);
+
+/**
+ * The deepest a calculation may nest one set of parentheses inside another
+ * before the evaluator gives up on it. Every level of nesting is a level of
+ * recursion, and a stylesheet states nothing at a depth anywhere near this.
+ *
+ * @type {number}
+ */
+const MAXIMUM_NESTING_DEPTH = 32;
+
+/**
+ * @typedef  {object} ExpressionReader
+ * @property {Array}  tokens            The tokens of the math function, in the order they are written.
+ * @property {number} index             The token the parser reads next.
+ * @property {number} depth             How many sets of parentheses the parser is reading inside of.
+ */
+
+/**
+ * Reads the token the parser stands on, or one of the tokens after it.
+ *
+ * @param  {ExpressionReader} reader  The token reader.
+ * @param  {number}           offset  How many tokens past the current one to read.
+ * @return {object|undefined}         The token read, or undefined past the end of the expression.
+ */
+function peekToken (reader, offset = 0) {
+  return reader.tokens[reader.index + offset];
+}
+
+/**
+ * Reports whether the parser stands on an operator that adds or subtracts what
+ * follows it from what precedes it. A sign written directly against its number
+ * is part of that number rather than an operator, so a value written with one
+ * sits against the value before it with no operator between them, which is not
+ * a calculation any browser reads.
+ *
+ * @param  {ExpressionReader} reader  The token reader.
+ * @return {boolean}                  Whether an addition or a subtraction follows.
+ */
+function readsAdditiveOperator (reader) {
+  const token = peekToken(reader);
+  const isAdditive = token?.type === 'operator' && (token.operator === '+' || token.operator === '-');
+  if (!isAdditive) {
+    return false;
+  }
+  const operandToken = peekToken(reader, 1);
+  const signsItsNumber = operandToken?.type === 'number' && !operandToken.precededBySpace;
+  return !signsItsNumber;
+}
+
+/**
+ * Reads a sum: the terms a calculation adds together, in the order they are
+ * written.
+ *
+ * @param  {ExpressionReader} reader  The token reader.
+ * @return {Map|null}                 The unit totals the sum states, or null when it cannot be resolved.
+ */
+function parseSum (reader) {
+  let value = parseProduct(reader);
+  if (!value) {
+    return null;
+  }
+  while (readsAdditiveOperator(reader)) {
+    const subtracts = peekToken(reader).operator === '-';
+    reader.index++;
+    const term = parseProduct(reader);
+    if (!term) {
+      return null;
+    }
+    value = addUnitTotals(value, term, subtracts ? -1 : 1);
+    if (!value) {
+      return null;
+    }
+  }
+  return value;
+}
+
+/**
+ * Reads a product: the operands a calculation multiplies and divides, which
+ * bind more tightly than the terms of a sum do.
+ *
+ * @param  {ExpressionReader} reader  The token reader.
+ * @return {Map|null}                 The unit totals the product states, or null when it cannot be resolved.
+ */
+function parseProduct (reader) {
+  let value = parseOperand(reader);
+  if (!value) {
+    return null;
+  }
+  let token = peekToken(reader);
+  while (token?.type === 'operator' && (token.operator === '*' || token.operator === '/')) {
+    reader.index++;
+    const operand = parseOperand(reader);
+    if (!operand) {
+      return null;
+    }
+    if (token.operator === '*') {
+      value = multiplyUnitTotals(value, operand);
+    } else {
+      value = divideUnitTotals(value, operand);
+    }
+    if (!value) {
+      return null;
+    }
+    token = peekToken(reader);
+  }
+  return value;
+}
+
+/**
+ * Reads the number a sign is written against, which is the only place a
+ * calculation states a sign: CSS has no operator that negates what follows it,
+ * so a sign standing apart from its number, or a second sign written in front
+ * of the first, is not a calculation any browser reads.
+ *
+ * @param  {ExpressionReader} reader  The token reader.
+ * @return {Map|null}                 The unit totals the signed number states, or null when the sign signs nothing.
+ */
+function parseSignedNumber (reader) {
+  const signToken = peekToken(reader);
+  const signedToken = peekToken(reader, 1);
+  const signsItsValue = (
+    (signedToken?.type === 'number' || signedToken?.type === 'identifier') &&
+    !signedToken.precededBySpace
+  );
+  if (!signsItsValue) {
+    return null;
+  }
+  reader.index++;
+  const value = parseOperand(reader);
+  if (!value) {
+    return null;
+  }
+  if (signToken.operator === '-') {
+    return scaleUnitTotals(value, -1);
+  }
+  return value;
+}
+
+/**
+ * Reads a single operand: a signed number, a number, a numeric constant, a
+ * parenthesized sum, or another math function.
+ *
+ * @param  {ExpressionReader} reader  The token reader.
+ * @return {Map|null}                 The unit totals the operand states, or null when it cannot be resolved.
+ */
+function parseOperand (reader) {
+  const token = peekToken(reader);
+  if (!token) {
+    return null;
+  }
+  if (token.type === 'operator' && (token.operator === '+' || token.operator === '-')) {
+    return parseSignedNumber(reader);
+  }
+  if (token.type === 'number') {
+    reader.index++;
+    return createUnitTotals(token.number, token.unit, true);
+  }
+  if (token.type === 'identifier') {
+    reader.index++;
+    const constant = NUMERIC_CONSTANTS.get(token.name);
+    if (constant === undefined) {
+      return null;
+    }
+    return createUnitTotals(constant, UNITLESS);
+  }
+  if (token.type === 'function') {
+    reader.index++;
+    return parseMathFunction(reader, token.name);
+  }
+  if (token.type === 'open') {
+    reader.index++;
+    return parseGroup(reader);
+  }
+  return null;
+}
+
+/**
+ * Reads a sum written inside parentheses, which is read as one operand of the
+ * calculation around it.
+ *
+ * @param  {ExpressionReader} reader  The token reader.
+ * @return {Map|null}                 The unit totals the group states, or null when it cannot be resolved.
+ */
+function parseGroup (reader) {
+  if (reader.depth >= MAXIMUM_NESTING_DEPTH) {
+    return null;
+  }
+  reader.depth++;
+  const value = parseSum(reader);
+  reader.depth--;
+  if (!value || peekToken(reader)?.type !== 'close') {
+    return null;
+  }
+  reader.index++;
+  return value;
+}
+
+/**
+ * Reads one argument of a math function, which is either a sum or a lone
+ * keyword such as the rounding strategy of `round()` or the open end of a
+ * `clamp()` range.
+ *
+ * @param  {ExpressionReader} reader  The token reader.
+ * @return {object|null}              The argument read, or null when it cannot be resolved.
+ */
+function parseFunctionArgument (reader) {
+  const token = peekToken(reader);
+  const followingToken = peekToken(reader, 1);
+  const standsAlone = followingToken?.type === 'comma' || followingToken?.type === 'close';
+  const isKeyword = token?.type === 'identifier' && standsAlone && !NUMERIC_CONSTANTS.has(token.name);
+  if (isKeyword) {
+    reader.index++;
+    return { keyword: token.name, value: null };
+  }
+  const value = parseSum(reader);
+  if (!value) {
+    return null;
+  }
+  return { keyword: null, value };
+}
+
+/**
+ * Reads the comma-separated arguments a math function is called with, up to
+ * the parenthesis that closes the call.
+ *
+ * @param  {ExpressionReader} reader  The token reader.
+ * @return {Array|null}               The arguments read, or null when the call cannot be resolved.
+ */
+function parseFunctionArguments (reader) {
+  const argumentList = [];
+  while (reader.index < reader.tokens.length) {
+    const argument = parseFunctionArgument(reader);
+    if (!argument) {
+      return null;
+    }
+    argumentList.push(argument);
+    const token = peekToken(reader);
+    if (token?.type === 'close') {
+      reader.index++;
+      return argumentList;
+    }
+    if (token?.type !== 'comma') {
+      return null;
+    }
+    reader.index++;
+  }
+  return null;
+}
+
+/**
+ * Reads the arguments of a math function and works out the value the function
+ * resolves to.
+ *
+ * @param  {ExpressionReader} reader  The token reader.
+ * @param  {string}           name    The lowercased name of the function being called.
+ * @return {Map|null}                 The unit totals the function resolves to, or null when it cannot be resolved.
+ */
+function parseMathFunction (reader, name) {
+  const resolveFunction = MATH_FUNCTION_EVALUATORS.get(name);
+  if (!resolveFunction || reader.depth >= MAXIMUM_NESTING_DEPTH) {
+    return null;
+  }
+  reader.depth++;
+  const argumentList = parseFunctionArguments(reader);
+  reader.depth--;
+  if (!argumentList) {
+    return null;
+  }
+  return resolveFunction(argumentList);
+}
+
+export {
+  parseSum
+};

package/src/value/math/property-ranges.js

@@ -0,0 +1,174 @@
+/**
+ * @file Holds what a math function resolved to inside the range of values the property it is declared on accepts.
+ */
+
+import { formatResolvedNumber } from '../shared.js';
+
+/**
+ * The properties whose values every CSS specification defines as
+ * non-negative, so that a math function declared on one of them has its
+ * result clamped rather than read as written.
+ *
+ * @type {Set<string>}
+ */
+const NON_NEGATIVE_PROPERTIES = new Set([
+  'animation-duration',
+  'animation-iteration-count',
+  'background-size',
+  'block-size',
+  'border-block-end-width',
+  'border-block-start-width',
+  'border-block-width',
+  'border-bottom-left-radius',
+  'border-bottom-right-radius',
+  'border-bottom-width',
+  'border-end-end-radius',
+  'border-end-start-radius',
+  'border-image-outset',
+  'border-image-width',
+  'border-inline-end-width',
+  'border-inline-start-width',
+  'border-inline-width',
+  'border-left-width',
+  'border-radius',
+  'border-right-width',
+  'border-start-end-radius',
+  'border-start-start-radius',
+  'border-top-left-radius',
+  'border-top-right-radius',
+  'border-top-width',
+  'border-width',
+  'column-count',
+  'column-gap',
+  'column-rule-width',
+  'column-width',
+  'flex-basis',
+  'flex-grow',
+  'flex-shrink',
+  'font-size',
+  'gap',
+  'height',
+  'inline-size',
+  'line-height',
+  'mask-size',
+  'max-block-size',
+  'max-height',
+  'max-inline-size',
+  'max-width',
+  'min-block-size',
+  'min-height',
+  'min-inline-size',
+  'min-width',
+  'outline-width',
+  'padding',
+  'padding-block',
+  'padding-block-end',
+  'padding-block-start',
+  'padding-bottom',
+  'padding-inline',
+  'padding-inline-end',
+  'padding-inline-start',
+  'padding-left',
+  'padding-right',
+  'padding-top',
+  'perspective',
+  'row-gap',
+  'shape-margin',
+  'stroke-width',
+  'tab-size',
+  'transition-duration',
+  'width'
+]);
+
+/**
+ * Properties whose computed math values must be integers.
+ *
+ * @type {Set<string>}
+ */
+const INTEGER_VALUE_PROPERTIES = new Set([
+  'column-count',
+  'order',
+  'orphans',
+  'widows',
+  'z-index'
+]);
+
+/**
+ * The inclusive bounds that CSS applies to numeric property values after
+ * resolving a math expression.
+ *
+ * @type {Map<string, {minimum?: number, maximum?: number}>}
+ */
+const NUMERIC_PROPERTY_RANGES = new Map([
+  ['column-count', { minimum: 1 }],
+  ['opacity', { minimum: 0, maximum: 1 }]
+]);
+
+/**
+ * Matches a value written as a single negative number, with or without the
+ * unit or percent sign that follows its digits.
+ *
+ * @type {RegExp}
+ */
+const NEGATIVE_NUMBER_VALUE = /^-(?:\d+|\d*\.\d+)(?:[a-z]+|%)?$/i;
+
+/**
+ * Matches a resolved unitless number whose value can be rounded or clamped by
+ * a property's numeric range.
+ *
+ * @type {RegExp}
+ */
+const UNIT_LESS_NUMBER_VALUE = /^[+-]?(?:\d+|\d*\.\d+)$/;
+
+/**
+ * Clamps what a math function resolved to into the range its property
+ * accepts. A negative length written out directly makes the declaration
+ * invalid and the CSS engine throws it away, but a math function is allowed
+ * to resolve to one: its result is clamped to the nearest value the property
+ * does take, which on a property that only accepts non-negative values is
+ * zero, as the range checking section of the CSS Values specification
+ * describes: https://drafts.csswg.org/css-values/#calc-range.
+ *
+ * @param  {string} resolvedValue  The value the math function resolved to.
+ * @param  {string} property       The property the math function is declared on.
+ * @return {string}                The resolved value, held inside the property's range.
+ */
+function clampResolvedValueToPropertyRange (resolvedValue, property) {
+  const normalizedProperty = String(property).toLowerCase();
+  const acceptsNegativeValues = !NON_NEGATIVE_PROPERTIES.has(normalizedProperty);
+  const hasPropertyRange = NUMERIC_PROPERTY_RANGES.has(normalizedProperty);
+  const range = NUMERIC_PROPERTY_RANGES.get(normalizedProperty) || {};
+  const isNegativeNonNegativeValue = !acceptsNegativeValues && NEGATIVE_NUMBER_VALUE.test(resolvedValue);
+  if (isNegativeNonNegativeValue) {
+    const isUnitlessNumber = UNIT_LESS_NUMBER_VALUE.test(resolvedValue);
+    if (!isUnitlessNumber) {
+      return formatResolvedNumber(range.minimum === undefined ? 0 : range.minimum);
+    }
+    if (!hasPropertyRange && !INTEGER_VALUE_PROPERTIES.has(normalizedProperty)) {
+      return '0';
+    }
+  }
+  if (!hasPropertyRange && !INTEGER_VALUE_PROPERTIES.has(normalizedProperty)) {
+    return resolvedValue;
+  }
+  if (!UNIT_LESS_NUMBER_VALUE.test(resolvedValue)) {
+    return resolvedValue;
+  }
+
+  const shouldRoundToInteger = INTEGER_VALUE_PROPERTIES.has(normalizedProperty);
+  let numericValue = Number(resolvedValue);
+  if (shouldRoundToInteger) {
+    numericValue = Math.round(numericValue);
+  }
+  if (range.minimum !== undefined) {
+    numericValue = Math.max(range.minimum, numericValue);
+  }
+  if (range.maximum !== undefined) {
+    numericValue = Math.min(range.maximum, numericValue);
+  }
+  return formatResolvedNumber(numericValue);
+}
+
+export {
+  clampResolvedValueToPropertyRange
+};