@thejaredwilcurt/csslop 0.0.49 → 0.0.51

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
+};

package/src/value/math/rewrite.js

@@ -0,0 +1,222 @@
+/**
+ * @file Rewrites the contents of CSS math functions into shorter equivalents, such as dropping redundant zeros from decimals and turning reciprocal multiplications into divisions.
+ */
+
+import { findMatchingParenthesis } from '../../parser/source-search.js';
+
+import { MATH_FUNCTION_NAMES } from './functions.js';
+
+/**
+ * Matches a single character that may appear in a CSS function name.
+ *
+ * @type {RegExp}
+ */
+const FUNCTION_NAME_CHARACTER = /[a-zA-Z-]/;
+
+/**
+ * Finds where the function name that ends at an opening parenthesis begins.
+ *
+ * @param  {string} value      The CSS value string being scanned.
+ * @param  {number} openIndex  The index of the opening parenthesis.
+ * @return {number}            The index of the function name's first character.
+ */
+function findFunctionNameStart (value, openIndex) {
+  let index = openIndex;
+  while (index > 0 && FUNCTION_NAME_CHARACTER.test(value[index - 1])) {
+    index--;
+  }
+  return index;
+}
+
+/**
+ * Rewrites the contents of every math function in a value, leaving the rest of
+ * the value untouched. A `*` only means multiplication inside these functions,
+ * so an arithmetic rewrite may only reach the text between their parentheses.
+ * The whole of a math function is handed over at once, so a math function
+ * nested in another is rewritten as part of its parent.
+ *
+ * @param  {function(string): string} rewriteExpression  Receives a math function's contents and returns its replacement.
+ * @param  {string}                   value              The CSS value string to rewrite.
+ * @return {string}                                      The value with every math function's contents rewritten.
+ */
+function rewriteMathFunctionContents (rewriteExpression, value) {
+  let result = '';
+  let index = 0;
+  while (index < value.length) {
+    const openIndex = value.indexOf('(', index);
+    if (openIndex === -1) {
+      break;
+    }
+    const functionName = value.slice(findFunctionNameStart(value, openIndex), openIndex).toLowerCase();
+    const closeIndex = findMatchingParenthesis(value, openIndex);
+    if (!MATH_FUNCTION_NAMES.has(functionName) || closeIndex === -1) {
+      result += value.slice(index, openIndex + 1);
+      index = openIndex + 1;
+      continue;
+    }
+    result += value.slice(index, openIndex + 1);
+    result += rewriteExpression(value.slice(openIndex + 1, closeIndex));
+    index = closeIndex;
+  }
+  return result + value.slice(index);
+}
+
+/**
+ * Matches a number written with a decimal point that begins a token of its
+ * own, capturing its sign, the digits before its decimal point, and the digits
+ * after it. The lookbehind keeps the match from starting partway through an
+ * identifier (`--x0.5`) or another number, and the lookahead keeps it from
+ * matching a fragment of a dotted name such as `0.5.png`.
+ *
+ * @type {RegExp}
+ */
+const DECIMAL_NUMBER = /(?<![\w.-])([+-]?)(\d*)\.(\d+)(?![\d.])/g;
+
+/**
+ * Writes a decimal number in the fewest characters that state the same value,
+ * dropping the zeros before its whole part (`0.25` → `.25`) and after its
+ * fraction (`1.50` → `1.5`), along with a decimal point left with no fraction
+ * behind it (`2.0` → `2`). The digits that remain are kept as written, so no
+ * precision is lost.
+ *
+ * @param  {string} sign            The sign written before the number, empty when there is none.
+ * @param  {string} wholeDigits     The digits written before the decimal point.
+ * @param  {string} fractionDigits  The digits written after the decimal point.
+ * @return {string}                 The number written as compactly as it can be.
+ */
+function shortenDecimalNumber (sign, wholeDigits, fractionDigits) {
+  // Leading zeros of the whole part
+  const wholePart = wholeDigits.replace(/^0+/, '');
+  // Trailing zeros of the fraction
+  const fractionPart = fractionDigits.replace(/0+$/, '');
+  if (!fractionPart) {
+    return sign + (wholePart || '0');
+  }
+  return sign + wholePart + '.' + fractionPart;
+}
+
+/**
+ * Shortens every decimal number in the contents of a math function. Numbers
+ * that follow an operator written without whitespace (`x*0.25s`) are out of
+ * reach of the general number shortening, which only looks past a separator.
+ *
+ * @param  {string} expression  The contents of a math function.
+ * @return {string}             The expression with every decimal number written as compactly as it can be.
+ */
+function shortenDecimalNumbers (expression) {
+  return expression.replace(DECIMAL_NUMBER, (match, sign, wholeDigits, fractionDigits) => {
+    return shortenDecimalNumber(sign, wholeDigits, fractionDigits);
+  });
+}
+
+/**
+ * Matches a multiplication by a decimal below one, capturing the digits after
+ * its decimal point and the unit written on it (so a multiplier with a unit
+ * can be recognized and left alone). The trailing lookahead keeps
+ * the match away from numbers that only begin this way, such as the exponent
+ * of `.5e3` or a unit name that is still being read.
+ *
+ * @type {RegExp}
+ */
+const FRACTIONAL_MULTIPLIER = /\s*\*\s*0*\.(\d+)([a-z%]*)(?![\w.%(])/gi;
+
+/**
+ * The most decimal places a fraction may be built from while the power of ten
+ * it needs is still exactly representable as an integer.
+ *
+ * @type {number}
+ */
+const MAXIMUM_FRACTION_DIGITS = 15;
+
+/**
+ * Computes the greatest common divisor of two non-negative integers, which is
+ * what a fraction has to be divided by to be stated in lowest terms.
+ *
+ * @param  {number} first   The first integer.
+ * @param  {number} second  The second integer.
+ * @return {number}         The greatest common divisor of both integers.
+ */
+function greatestCommonDivisor (first, second) {
+  let dividend = first;
+  let divisor = second;
+  while (divisor) {
+    const remainder = dividend % divisor;
+    dividend = divisor;
+    divisor = remainder;
+  }
+  return dividend;
+}
+
+/**
+ * Converts the digits behind a decimal point into the whole number that
+ * dividing by scales a value exactly as multiplying by that decimal does.
+ * The digits `25` (of `.25`) state the fraction 25/100, which reduces to 1/4,
+ * so the divisor is `4`. A fraction that does not reduce to a numerator of one
+ * cannot be stated as a single division, and so has no divisor to give.
+ *
+ * @param  {string}      fractionDigits  The digits written after the decimal point.
+ * @return {number|null}                 The equivalent whole number divisor, or null when there is none.
+ */
+function reciprocalOfDecimalFraction (fractionDigits) {
+  if (fractionDigits.length > MAXIMUM_FRACTION_DIGITS) {
+    return null;
+  }
+  const numerator = Number(fractionDigits);
+  const denominator = 10 ** fractionDigits.length;
+  const commonFactor = greatestCommonDivisor(numerator, denominator);
+  if (numerator / commonFactor !== 1) {
+    return null;
+  }
+  return denominator / commonFactor;
+}
+
+/**
+ * Builds the division that scales a value exactly as multiplying it by a
+ * unitless decimal below one does, when that division is no longer to write
+ * than the multiplication. A multiplier carrying a unit is never rewritten:
+ * dividing by a dimension inverts its unit in the type of the result
+ * (`x*.25s` is a time, while `x/4s` is per unit of time), so the two would not
+ * be equivalent.
+ *
+ * @param  {string}      fractionDigits  The digits written after the decimal point of the multiplier.
+ * @param  {string}      unit            The unit written on the multiplier, empty when it is unitless.
+ * @return {string|null}                 The equivalent division, or null when there is none worth using.
+ */
+function divisionEquivalentToFractionalMultiplier (fractionDigits, unit) {
+  if (unit) {
+    return null;
+  }
+  const divisor = reciprocalOfDecimalFraction(fractionDigits);
+  if (divisor === null) {
+    return null;
+  }
+  const division = '/' + divisor;
+  // Compared against the shortest the multiplication could have been written
+  const multiplication = '*.' + fractionDigits;
+  if (division.length > multiplication.length) {
+    return null;
+  }
+  return division;
+}
+
+/**
+ * Rewrites a multiplication by a unitless decimal below one as a division by
+ * the whole number that decimal is the reciprocal of, which is never longer to
+ * write and usually shorter (`calc(var(--x)*.25)` → `calc(var(--x)/4)`).
+ * Multipliers with a unit are left as written, since dividing by a dimension
+ * would invert its unit.
+ *
+ * @param  {string} expression  The contents of a math function.
+ * @return {string}             The expression with reciprocal multipliers stated as divisions.
+ */
+function convertReciprocalMultiplicationToDivision (expression) {
+  return expression.replace(FRACTIONAL_MULTIPLIER, (match, fractionDigits, unit) => {
+    return divisionEquivalentToFractionalMultiplier(fractionDigits, unit) ?? match;
+  });
+}
+
+export {
+  convertReciprocalMultiplicationToDivision,
+  rewriteMathFunctionContents,
+  shortenDecimalNumbers
+};