@thejaredwilcurt/csslop 0.0.49 → 0.0.50

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

package/src/value/math/tokenizer.js

@@ -0,0 +1,160 @@
+/**
+ * @file Splits a CSS math function into the numbers, identifiers, function names, operators, and punctuation it is written from.
+ */
+
+import {
+  PERCENTAGE,
+  UNITLESS
+} from './unit-totals.js';
+
+/**
+ * Matches a CSS number where the scanner stands: the digits it is written
+ * from, together with the fraction and the exponent it may be written with.
+ * A sign is left to the parser, which tells the sign of a number from an
+ * operator by whether whitespace stands between the two.
+ *
+ * @type {RegExp}
+ */
+const NUMBER_AT_INDEX = /(?:\d+\.\d+|\.\d+|\d+)(?:e[+-]?\d+)?/iy;
+
+/**
+ * Matches a CSS identifier where the scanner stands: a name of letters,
+ * digits, underscores, and hyphens that does not begin with a digit. A numeric
+ * constant, a function name, and a keyword argument are all written as
+ * identifiers.
+ *
+ * @type {RegExp}
+ */
+const IDENTIFIER_AT_INDEX = /[a-z_][a-z0-9_-]*/iy;
+
+/**
+ * Matches the unit written against a number where the scanner stands. Every
+ * CSS unit is named in letters alone, so a name holding anything else is a
+ * token of its own that a number cannot carry.
+ *
+ * @type {RegExp}
+ */
+const UNIT_AT_INDEX = /[a-z]+/iy;
+
+/**
+ * The characters CSS counts as whitespace, which separates the tokens of a
+ * calculation and tells an operator apart from the sign of a number.
+ *
+ * @type {Set<string>}
+ */
+const WHITESPACE_CHARACTERS = new Set([' ', '\t', '\n', '\r', '\f']);
+
+/**
+ * The characters that punctuate a calculation, and the kind of token each of
+ * them stands for.
+ *
+ * @type {Map<string, string>}
+ */
+const PUNCTUATION_TOKEN_TYPES = new Map([
+  ['(', 'open'],
+  [')', 'close'],
+  [',', 'comma']
+]);
+
+/**
+ * The arithmetic operators a calculation is written with.
+ *
+ * @type {Set<string>}
+ */
+const OPERATOR_CHARACTERS = new Set(['+', '-', '*', '/']);
+
+/**
+ * Reads the unit written directly against the number that ends at the given
+ * index, which is a percent sign or an identifier naming the unit. A number
+ * with nothing written against it carries no unit.
+ *
+ * @param  {string} text   The math function being tokenized.
+ * @param  {number} index  The index just past the number's digits.
+ * @return {object}        The unit read and the index just past it.
+ */
+function readUnitAtIndex (text, index) {
+  if (text[index] === PERCENTAGE) {
+    return { unit: PERCENTAGE, nextIndex: index + 1 };
+  }
+  UNIT_AT_INDEX.lastIndex = index;
+  const unitMatch = UNIT_AT_INDEX.exec(text);
+  if (!unitMatch) {
+    return { unit: UNITLESS, nextIndex: index };
+  }
+  return { unit: unitMatch[0], nextIndex: index + unitMatch[0].length };
+}
+
+/**
+ * Splits a math function into the tokens it is written from: its numbers with
+ * the units they carry, its identifiers, its function names, its operators,
+ * and its punctuation. Each token records whether whitespace precedes it,
+ * since that is what tells the sign of a number from an operator.
+ *
+ * @param  {string}     text  The math function as it is written.
+ * @return {Array|null}       The tokens of the math function, or null when it holds a character no calculation is written with.
+ */
+function tokenizeMathExpression (text) {
+  const tokens = [];
+  let index = 0;
+  let precededBySpace = false;
+
+  while (index < text.length) {
+    const character = text[index];
+
+    if (WHITESPACE_CHARACTERS.has(character)) {
+      precededBySpace = true;
+      index++;
+      continue;
+    }
+
+    NUMBER_AT_INDEX.lastIndex = index;
+    const numberMatch = NUMBER_AT_INDEX.exec(text);
+    if (numberMatch) {
+      const { unit, nextIndex } = readUnitAtIndex(text, index + numberMatch[0].length);
+      tokens.push({
+        type: 'number',
+        number: Number(numberMatch[0]),
+        unit,
+        precededBySpace
+      });
+      index = nextIndex;
+      precededBySpace = false;
+      continue;
+    }
+
+    if (OPERATOR_CHARACTERS.has(character) || PUNCTUATION_TOKEN_TYPES.has(character)) {
+      tokens.push({
+        type: PUNCTUATION_TOKEN_TYPES.get(character) || 'operator',
+        operator: character,
+        precededBySpace
+      });
+      index++;
+      precededBySpace = false;
+      continue;
+    }
+
+    IDENTIFIER_AT_INDEX.lastIndex = index;
+    const identifierMatch = IDENTIFIER_AT_INDEX.exec(text);
+    if (!identifierMatch) {
+      return null;
+    }
+    index = index + identifierMatch[0].length;
+    // A name written directly against an opening parenthesis calls a function
+    const callsFunction = text[index] === '(';
+    if (callsFunction) {
+      index++;
+    }
+    tokens.push({
+      type: callsFunction ? 'function' : 'identifier',
+      name: identifierMatch[0].toLowerCase(),
+      precededBySpace
+    });
+    precededBySpace = false;
+  }
+
+  return tokens;
+}
+
+export {
+  tokenizeMathExpression
+};

package/src/value/math/unit-totals.js

@@ -0,0 +1,194 @@
+/**
+ * @file Represents the value of a CSS calculation as totals keyed by unit, and works out the sums, products, and quotients of such values.
+ */
+
+import { convertAbsoluteLengthToPx } from '../shared.js';
+
+/**
+ * The unit a plain number is totalled under. A number carries no unit, and the
+ * empty string is the unit it does not carry.
+ *
+ * @type {string}
+ */
+const UNITLESS = '';
+
+/**
+ * The unit a percentage is totalled under. A percentage is only resolved
+ * against its basis once the element is laid out, so it is totalled as a unit
+ * of its own rather than as the number it is written from.
+ *
+ * @type {string}
+ */
+const PERCENTAGE = '%';
+
+/**
+ * Creates the totals of a value that states a single quantity, holding the
+ * number it is written from under the unit it is written with. An absolute
+ * length is held as the pixels it measures, since every length stating the
+ * same measurement then totals under the same unit.
+ *
+ * @param  {number}  number                   The number the quantity is written from.
+ * @param  {string}  unit                     The unit the quantity is written with, or the empty string when it is a plain number.
+ * @param  {boolean} preserveWrittenQuantity  Whether to retain the original spelling for a standalone quantity.
+ * @return {Map}                              The unit totals the quantity states.
+ */
+function createUnitTotals (number, unit, preserveWrittenQuantity = false) {
+  const lowercasedUnit = unit.toLowerCase();
+  const pixels = convertAbsoluteLengthToPx(number, lowercasedUnit);
+  let totals;
+  if (pixels === null) {
+    totals = new Map([[lowercasedUnit, number]]);
+  } else {
+    totals = new Map([['px', pixels]]);
+  }
+  if (preserveWrittenQuantity) {
+    totals.writtenQuantity = {
+      number,
+      unit: lowercasedUnit,
+      canonicalUnit: pixels === null ? lowercasedUnit : 'px',
+      canonicalNumber: pixels === null ? number : pixels
+    };
+  }
+  return totals;
+}
+
+/**
+ * Reports whether a value states a plain number, which is what an operand has
+ * to be to scale or divide the quantity it is written against.
+ *
+ * @param  {Map}     value  The unit totals the value holds.
+ * @return {boolean}        Whether the value states a plain number.
+ */
+function isPlainNumber (value) {
+  return value.size === 1 && value.has(UNITLESS);
+}
+
+/**
+ * Reads a value as the single quantity it states, which is what a function
+ * comparing its arguments needs each of them to be. A value totalling more
+ * than one unit is only resolved once its units are resolved against the
+ * element, so it states no single number to read.
+ *
+ * @param  {Map}         value  The unit totals the value holds.
+ * @return {object|null}        The number and the unit the value states, or null when it states more than one quantity.
+ */
+function readSingleQuantity (value) {
+  if (value.size !== 1) {
+    return null;
+  }
+  const [[unit, number]] = [...value];
+  return { number, unit };
+}
+
+/**
+ * Scales every quantity a value states by a plain number, which is how a
+ * multiplication and a division are worked out.
+ *
+ * @param  {Map}    value   The unit totals the value holds.
+ * @param  {number} factor  The number every total is scaled by.
+ * @return {Map}            The scaled unit totals.
+ */
+function scaleUnitTotals (value, factor) {
+  const scaled = new Map();
+  for (const [unit, coefficient] of value) {
+    scaled.set(unit, coefficient * factor);
+  }
+  return scaled;
+}
+
+/**
+ * Adds one value to another, totalling the quantities they state under the
+ * units they are written with. A sum of a plain number and a quantity carrying
+ * a unit states nothing a stylesheet can hold, so such a sum has no total to
+ * give.
+ *
+ * @param  {Map}      left   The unit totals the value on the left holds.
+ * @param  {Map}      right  The unit totals the value on the right holds.
+ * @param  {number}   sign   The direction the right value is added in: 1 to add it, -1 to subtract it.
+ * @return {Map|null}        The totals of the sum, or null when the two cannot be added.
+ */
+function addUnitTotals (left, right, sign) {
+  const totals = new Map(left);
+  for (const [unit, coefficient] of right) {
+    totals.set(unit, (totals.get(unit) || 0) + (coefficient * sign));
+  }
+  const addsNumberToQuantity = totals.has(UNITLESS) && totals.size > 1;
+  if (addsNumberToQuantity) {
+    return null;
+  }
+  return totals;
+}
+
+/**
+ * Multiplies two values, which CSS only allows when one of them is a plain
+ * number: the product of two quantities carrying units measures an area or a
+ * rate, and no CSS property takes one.
+ *
+ * @param  {Map}      left   The unit totals the value on the left holds.
+ * @param  {Map}      right  The unit totals the value on the right holds.
+ * @return {Map|null}        The totals of the product, or null when neither side is a plain number.
+ */
+function multiplyUnitTotals (left, right) {
+  if (isPlainNumber(right)) {
+    return scaleUnitTotals(left, right.get(UNITLESS));
+  }
+  if (isPlainNumber(left)) {
+    return scaleUnitTotals(right, left.get(UNITLESS));
+  }
+  const leftQuantity = readSingleQuantity(left);
+  const rightQuantity = readSingleQuantity(right);
+  if (leftQuantity && rightQuantity) {
+    if (leftQuantity.unit.startsWith('reciprocal:') && leftQuantity.unit.slice('reciprocal:'.length) === rightQuantity.unit) {
+      return createUnitTotals(leftQuantity.number * rightQuantity.number, UNITLESS);
+    }
+    if (rightQuantity.unit.startsWith('reciprocal:') && rightQuantity.unit.slice('reciprocal:'.length) === leftQuantity.unit) {
+      return createUnitTotals(leftQuantity.number * rightQuantity.number, UNITLESS);
+    }
+  }
+  return null;
+}
+
+/**
+ * Divides a value by another, which CSS only allows when the divisor is a
+ * plain number. A division by zero resolves to an infinity that no property
+ * takes, so it is left for the stylesheet to state as written.
+ *
+ * @param  {Map}      left   The unit totals of the value being divided.
+ * @param  {Map}      right  The unit totals of the value dividing it.
+ * @return {Map|null}        The totals of the quotient, or null when the division cannot be worked out.
+ */
+function divideUnitTotals (left, right) {
+  if (isPlainNumber(right)) {
+    const divisor = right.get(UNITLESS);
+    if (divisor === 0) {
+      return null;
+    }
+    return scaleUnitTotals(left, 1 / divisor);
+  }
+  const dividendQuantity = readSingleQuantity(left);
+  const divisorQuantity = readSingleQuantity(right);
+  if (!dividendQuantity || !divisorQuantity || divisorQuantity.number === 0) {
+    return null;
+  }
+  if (dividendQuantity.unit === divisorQuantity.unit) {
+    return createUnitTotals(dividendQuantity.number / divisorQuantity.number, UNITLESS);
+  }
+  if (dividendQuantity.unit === UNITLESS) {
+    return createUnitTotals(
+      dividendQuantity.number / divisorQuantity.number,
+      'reciprocal:' + divisorQuantity.unit
+    );
+  }
+  return null;
+}
+
+export {
+  addUnitTotals,
+  createUnitTotals,
+  divideUnitTotals,
+  multiplyUnitTotals,
+  PERCENTAGE,
+  readSingleQuantity,
+  scaleUnitTotals,
+  UNITLESS
+};