@thejaredwilcurt/csslop 0.0.49 → 0.0.51

package/src/value/math/functions.js

@@ -0,0 +1,302 @@
+/**
+ * @file Resolves the CSS math functions whose arguments are arithmetic, such as `min()`, `clamp()`, and `round()`, once their arguments are known.
+ */
+
+import {
+  createUnitTotals,
+  readSingleQuantity,
+  UNITLESS
+} from './unit-totals.js';
+
+/**
+ * How each rounding strategy of `round()` turns the number of intervals it is
+ * given into the whole number of them it keeps.
+ *
+ * @type {Map<string, function(number): number>}
+ */
+const ROUNDING_STRATEGIES = new Map([
+  ['nearest', Math.round],
+  ['up', Math.ceil],
+  ['down', Math.floor],
+  ['to-zero', Math.trunc]
+]);
+
+/**
+ * Reads the arguments of a function as the numbers of one shared unit, which
+ * is what a function comparing or rounding its arguments needs them to be.
+ * Arguments carrying different units are only comparable once they are
+ * resolved against the element, which is long after minification.
+ *
+ * @param  {Array}       argumentList  The arguments the function was called with.
+ * @return {object|null}               The shared unit and the numbers the arguments state, or null when they do not share one.
+ */
+function readComparableArguments (argumentList) {
+  const numbers = [];
+  let sharedUnit = null;
+  for (const argument of argumentList) {
+    if (!argument.value) {
+      return null;
+    }
+    const quantity = readSingleQuantity(argument.value);
+    if (!quantity) {
+      return null;
+    }
+    if (sharedUnit !== null && quantity.unit !== sharedUnit) {
+      return null;
+    }
+    sharedUnit = quantity.unit;
+    numbers.push(quantity.number);
+  }
+  if (!numbers.length) {
+    return null;
+  }
+  return { numbers, unit: sharedUnit };
+}
+
+/**
+ * Reads the single value argument a function takes, which no keyword may
+ * stand in for.
+ *
+ * @param  {Array}    argumentList  The arguments the function was called with.
+ * @return {Map|null}               The unit totals of the lone argument, or null when the function was called with anything else.
+ */
+function readLoneArgument (argumentList) {
+  if (argumentList.length !== 1) {
+    return null;
+  }
+  return argumentList[0].value;
+}
+
+/**
+ * Resolves `calc()`, which states the value its one argument works out to.
+ *
+ * @param  {Array}    argumentList  The arguments the function was called with.
+ * @return {Map|null}               The unit totals the calculation states, or null when it cannot be resolved.
+ */
+function evaluateCalculation (argumentList) {
+  return readLoneArgument(argumentList);
+}
+
+/**
+ * Resolves `min()`, which states the smallest of the values it compares.
+ *
+ * @param  {Array}    argumentList  The arguments the function was called with.
+ * @return {Map|null}               The unit totals of the smallest argument, or null when the arguments are not comparable.
+ */
+function evaluateMinimum (argumentList) {
+  const comparable = readComparableArguments(argumentList);
+  if (!comparable) {
+    return null;
+  }
+  const winningIndex = comparable.numbers.indexOf(Math.min(...comparable.numbers));
+  return argumentList[winningIndex].value;
+}
+
+/**
+ * Resolves `max()`, which states the largest of the values it compares.
+ *
+ * @param  {Array}    argumentList  The arguments the function was called with.
+ * @return {Map|null}               The unit totals of the largest argument, or null when the arguments are not comparable.
+ */
+function evaluateMaximum (argumentList) {
+  const comparable = readComparableArguments(argumentList);
+  if (!comparable) {
+    return null;
+  }
+  const winningIndex = comparable.numbers.indexOf(Math.max(...comparable.numbers));
+  return argumentList[winningIndex].value;
+}
+
+/**
+ * Reports whether an end of a `clamp()` range is left open, which the `none`
+ * keyword does, leaving that end to bound nothing.
+ *
+ * @param  {object}  argument  The argument written at that end of the range.
+ * @return {boolean}           Whether that end of the range is open.
+ */
+function boundsNothing (argument) {
+  return argument.keyword === 'none';
+}
+
+/**
+ * Resolves `clamp()`, which holds its preferred value inside the range its
+ * other two arguments bound. The smallest value wins a range written back to
+ * front, since the preferred value is held below the maximum before it is
+ * held above the minimum.
+ *
+ * @param  {Array}    argumentList  The arguments the function was called with.
+ * @return {Map|null}               The unit totals of the clamped value, or null when the arguments are not comparable.
+ */
+function evaluateClamp (argumentList) {
+  if (argumentList.length !== 3) {
+    return null;
+  }
+  const [lowerBound, preferred, upperBound] = argumentList;
+  const boundedArguments = argumentList.filter((argument) => {
+    return !boundsNothing(argument);
+  });
+  const comparable = readComparableArguments(boundedArguments);
+  if (!comparable || !preferred.value) {
+    return null;
+  }
+  let clamped = readSingleQuantity(preferred.value).number;
+  if (!boundsNothing(upperBound)) {
+    clamped = Math.min(clamped, readSingleQuantity(upperBound.value).number);
+  }
+  if (!boundsNothing(lowerBound)) {
+    clamped = Math.max(clamped, readSingleQuantity(lowerBound.value).number);
+  }
+  return createUnitTotals(clamped, comparable.unit);
+}
+
+/**
+ * Resolves `abs()`, which states its argument's distance from zero.
+ *
+ * @param  {Array}    argumentList  The arguments the function was called with.
+ * @return {Map|null}               The unit totals of the absolute value, or null when the argument states more than one quantity.
+ */
+function evaluateAbsolute (argumentList) {
+  const comparable = readComparableArguments(argumentList);
+  if (!comparable || comparable.numbers.length !== 1) {
+    return null;
+  }
+  return createUnitTotals(Math.abs(comparable.numbers[0]), comparable.unit);
+}
+
+/**
+ * Resolves `sign()`, which states which side of zero its argument lies on as
+ * a plain number.
+ *
+ * @param  {Array}    argumentList  The arguments the function was called with.
+ * @return {Map|null}               The unit totals of the sign, or null when the argument states more than one quantity.
+ */
+function evaluateSign (argumentList) {
+  const comparable = readComparableArguments(argumentList);
+  if (!comparable || comparable.numbers.length !== 1) {
+    return null;
+  }
+  return createUnitTotals(Math.sign(comparable.numbers[0]), UNITLESS);
+}
+
+/**
+ * Resolves `hypot()`, which states the length of the vector its arguments
+ * measure the sides of.
+ *
+ * @param  {Array}    argumentList  The arguments the function was called with.
+ * @return {Map|null}               The unit totals of the hypotenuse, or null when the arguments are not comparable.
+ */
+function evaluateHypotenuse (argumentList) {
+  const comparable = readComparableArguments(argumentList);
+  if (!comparable) {
+    return null;
+  }
+  return createUnitTotals(Math.hypot(...comparable.numbers), comparable.unit);
+}
+
+/**
+ * Reads the two comparable numbers a function divides one of by the other,
+ * refusing a divisor of zero, which no division resolves against.
+ *
+ * @param  {Array}       argumentList  The arguments the function was called with.
+ * @return {object|null}               The shared unit with the dividend and the divisor, or null when the arguments cannot be divided.
+ */
+function readDivisionArguments (argumentList) {
+  const comparable = readComparableArguments(argumentList);
+  if (!comparable || comparable.numbers.length !== 2 || comparable.numbers[1] === 0) {
+    return null;
+  }
+  return {
+    dividend: comparable.numbers[0],
+    divisor: comparable.numbers[1],
+    unit: comparable.unit
+  };
+}
+
+/**
+ * Resolves `mod()`, which states what is left of its first argument after
+ * taking out whole multiples of its second, carrying the sign of the divisor.
+ *
+ * @param  {Array}    argumentList  The arguments the function was called with.
+ * @return {Map|null}               The unit totals of the modulus, or null when the arguments cannot be divided.
+ */
+function evaluateModulus (argumentList) {
+  const division = readDivisionArguments(argumentList);
+  if (!division) {
+    return null;
+  }
+  const { dividend, divisor, unit } = division;
+  return createUnitTotals(((dividend % divisor) + divisor) % divisor, unit);
+}
+
+/**
+ * Resolves `rem()`, which states what is left of its first argument after
+ * taking out whole multiples of its second, carrying the sign of the dividend.
+ *
+ * @param  {Array}    argumentList  The arguments the function was called with.
+ * @return {Map|null}               The unit totals of the remainder, or null when the arguments cannot be divided.
+ */
+function evaluateRemainder (argumentList) {
+  const division = readDivisionArguments(argumentList);
+  if (!division) {
+    return null;
+  }
+  const { dividend, divisor, unit } = division;
+  return createUnitTotals(dividend % divisor, unit);
+}
+
+/**
+ * Resolves `round()`, which states the multiple of its rounding interval that
+ * the strategy it is given rounds its value to. A call written without a
+ * strategy rounds to the nearest multiple.
+ *
+ * @param  {Array}    argumentList  The arguments the function was called with.
+ * @return {Map|null}               The unit totals of the rounded value, or null when the arguments cannot be rounded.
+ */
+function evaluateRound (argumentList) {
+  let strategyName = 'nearest';
+  let valueArguments = argumentList;
+  if (argumentList.length === 3) {
+    strategyName = argumentList[0].keyword;
+    valueArguments = argumentList.slice(1);
+  }
+  const roundIntervals = ROUNDING_STRATEGIES.get(strategyName);
+  const division = readDivisionArguments(valueArguments);
+  if (!roundIntervals || !division) {
+    return null;
+  }
+  const { dividend, divisor, unit } = division;
+  return createUnitTotals(roundIntervals(dividend / divisor) * divisor, unit);
+}
+
+/**
+ * How each math function resolves the arguments it is called with. The
+ * functions listed here are the ones whose arguments are arithmetic, so that
+ * `*` and `/` between them are operators rather than characters of some other
+ * syntax.
+ *
+ * @type {Map<string, function(Array): (Map|null)>}
+ */
+const MATH_FUNCTION_EVALUATORS = new Map([
+  ['abs', evaluateAbsolute],
+  ['calc', evaluateCalculation],
+  ['clamp', evaluateClamp],
+  ['hypot', evaluateHypotenuse],
+  ['max', evaluateMaximum],
+  ['min', evaluateMinimum],
+  ['mod', evaluateModulus],
+  ['rem', evaluateRemainder],
+  ['round', evaluateRound],
+  ['sign', evaluateSign]
+]);
+
+/**
+ * The names of the functions whose arguments are a math expression.
+ *
+ * @type {Set<string>}
+ */
+const MATH_FUNCTION_NAMES = new Set(MATH_FUNCTION_EVALUATORS.keys());
+
+export {
+  MATH_FUNCTION_EVALUATORS,
+  MATH_FUNCTION_NAMES
+};

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