@thejaredwilcurt/csslop 0.0.49 → 0.0.51

package/src/value/math/fold.js

@@ -0,0 +1,315 @@
+/**
+ * @file Folds the constant arithmetic of a `calc()` into the shortest way of writing the value it states, weighing the resolved value against the calculation itself.
+ */
+
+import {
+  convertAbsoluteLengthToPx,
+  formatResolvedDimension,
+  formatResolvedNumber
+} from '../shared.js';
+
+import { simplifyCalc } from './evaluate.js';
+import { formatUnitTotals } from './format.js';
+
+/**
+ * Matches a whole expression that divides a percentage by a plain number,
+ * capturing the percentage and the divisor it is shared out between.
+ *
+ * @type {RegExp}
+ */
+const PERCENTAGE_DIVISION = /^([+-]?(?:\d+|\d*\.\d+))%\s*\/\s*([+-]?(?:\d+|\d*\.\d+))$/;
+
+/**
+ * Picks between what a calculation resolved to and the calculation itself,
+ * keeping whichever takes fewer characters to write. A tie goes to the
+ * resolved value, which states the same thing without the arithmetic.
+ *
+ * @param  {string} resolved     The value the calculation resolves to.
+ * @param  {string} calculation  The calculation, written as compactly as it can be.
+ * @return {string}              The shorter of the two.
+ */
+function shorterOfResolutionAndCalculation (resolved, calculation) {
+  if (resolved.length <= calculation.length) {
+    return resolved;
+  }
+  return calculation;
+}
+
+/**
+ * Writes a calculation as compactly as its syntax allows, squeezing out every
+ * space but the ones a `+` or a `-` needs to be read as an operator.
+ *
+ * @param  {string} inner  The contents of the `calc()`.
+ * @return {string}        The whole `calc()`, written as compactly as it can be.
+ */
+function compactCalculation (inner) {
+  // Remove whitespace around multiplication and division operators
+  const compactInner = inner.replace(/\s+/g, ' ').trim().replace(/\s*([*/])\s*/g, '$1');
+  return 'calc(' + compactInner + ')';
+}
+
+/**
+ * Picks between a calculation and what resolving its arithmetic came to. A
+ * resolved value states the same thing without any arithmetic, so it wins a
+ * tie, but a result that is itself a calculation only states the same terms
+ * another way, and writing them out again for no saving gains nothing.
+ *
+ * @param  {string} resolved     The value the calculation resolved to.
+ * @param  {string} calculation  The calculation, written as compactly as it can be.
+ * @return {string}              Whichever of the two the value is written as.
+ */
+function chooseResolvedCalculation (resolved, calculation) {
+  // A resolution that kept its function form left terms behind that only
+  // resolve once the element they are measured against is laid out
+  if (resolved.startsWith('calc(') && resolved.length >= calculation.length) {
+    return calculation;
+  }
+  return shorterOfResolutionAndCalculation(resolved, calculation);
+}
+
+/**
+ * Resolves a percentage divided by a number into the single percentage it
+ * equals, which is how `calc(100%/16)` comes to be written as `6.25%`. The
+ * division stays as it was written when the result is no shorter, and when
+ * the divisor is zero, since that resolves to nothing a stylesheet can state.
+ *
+ * @param  {string}      expression  The contents of a `calc()`, with its whitespace collapsed.
+ * @return {string|null}             The shorter of the resolved percentage and the division, or null when the expression is not one.
+ */
+function resolvePercentageDivision (expression) {
+  const division = expression.match(PERCENTAGE_DIVISION);
+  if (!division) {
+    return null;
+  }
+  const [, percentage, divisor] = division;
+  const calculation = 'calc(' + percentage + '%/' + divisor + ')';
+  if (Number(divisor) === 0) {
+    return calculation;
+  }
+  const resolved = formatResolvedNumber(Number(percentage) / Number(divisor)) + '%';
+  return shorterOfResolutionAndCalculation(resolved, calculation);
+}
+
+/**
+ * Attempts to simplify a calc() expression by combining like-unit terms and evaluating pure arithmetic, returning the simplified string or null if folding is not possible.
+ *
+ * @param  {string}      expression  The expression inside calc() to attempt folding.
+ * @return {string|null}             The simplified expression, or null if it cannot be folded.
+ */
+function tryFoldCalcExpression (expression) {
+  let folded = expression.trim();
+  let previous;
+
+  do {
+    previous = folded;
+    // Remove innermost non-nested parentheses (flatten simple grouping)
+    folded = folded.replace(/\(([^()]+)\)/g, '$1');
+    // Fold: <number> * <number><unit> → computed result in same unit
+    folded = folded.replace(/(-?(?:\d*\.\d+|\d+))\s*\*\s*(-?(?:\d*\.\d+|\d+))(px|pt|pc|in|cm|mm|q|%)/gi, (match, multiplier, amount, unit) => {
+      return formatResolvedDimension(parseFloat(multiplier) * parseFloat(amount), unit);
+    });
+    // Fold: <number><unit> * <number> → computed result in same unit
+    folded = folded.replace(/(-?(?:\d*\.\d+|\d+))(px|pt|pc|in|cm|mm|q|%)\s*\*\s*(-?(?:\d*\.\d+|\d+))/gi, (match, amount, unit, multiplier) => {
+      return formatResolvedDimension(parseFloat(multiplier) * parseFloat(amount), unit);
+    });
+    // Fold: <number><unit> / <number> → computed result in same unit
+    folded = folded.replace(/(-?(?:\d*\.\d+|\d+))(px|pt|pc|in|cm|mm|q)\s*\/\s*(-?(?:\d*\.\d+|\d+))/gi, (match, value, unit, divisor) => {
+      return formatResolvedDimension(parseFloat(value) / parseFloat(divisor), unit);
+    });
+    // Collapse zero-with-unit terms (e.g. 0px, 0%) to plain 0 or remove them
+    folded = folded.replace(/(^|[+-])\s*0(?:px|pt|pc|in|cm|mm|q|%)\b/g, (match, sign) => {
+      if (sign && sign !== '+') {
+        return sign + ' 0';
+      }
+      return '';
+    });
+    // Remove additive zero terms
+    folded = folded.replace(/\+\s*0\b/g, '');
+    // Remove subtractive zero terms
+    folded = folded.replace(/-\s*0\b/g, '');
+    // Collapse whitespace
+    folded = folded.replace(/\s+/g, ' ').trim();
+  } while (folded !== previous);
+
+  // Simplify trivial identity division: 1 / 1 / <dimension> → <dimension>
+  if (/^1\s*\/\s*1\s*\/\s*(-?(?:\d*\.\d+|\d+)(?:px|pt|pc|in|cm|mm|q))$/i.test(folded)) {
+    return folded.replace(/^1\s*\/\s*1\s*\/\s*/i, '');
+  }
+
+  // Remove all whitespace for validation
+  const normalized = folded.replace(/\s+/g, '');
+  // Validate that the expression is a simple sequence of signed terms with optional units
+  if (!/^[+-]?(?:\d*\.\d+|\d+)(?:[a-z%]+)?(?:[+-](?:\d*\.\d+|\d+)(?:[a-z%]+)?)*$/i.test(normalized)) {
+    return null;
+  }
+
+  // Extract each signed term with its optional unit
+  const terms = normalized.match(/[+-]?(?:\d*\.\d+|\d+)(?:[a-z%]+)?/gi) || [];
+  const totals = new Map();
+
+  for (const term of terms) {
+    // Parse each term into sign, number, and unit parts
+    const match = term.match(/^([+-]?)(\d*\.\d+|\d+)([a-z%]+)?$/i);
+    if (!match) {
+      return null;
+    }
+    const [, sign, rawNumber, rawUnit = ''] = match;
+    let number = parseFloat(rawNumber) * (sign === '-' ? -1 : 1);
+    let unit = rawUnit.toLowerCase();
+
+    if (unit && unit !== '%' && unit !== 'px') {
+      const pxValue = convertAbsoluteLengthToPx(number, unit);
+      if (pxValue === null) {
+        return null;
+      }
+      number = pxValue;
+      unit = 'px';
+    }
+
+    totals.set(unit, (totals.get(unit) || 0) + number);
+  }
+
+  return formatUnitTotals(totals);
+}
+
+/**
+ * Matches a whole expression that scales a percentage by a plain number,
+ * written either way around. Both operands are already as short as they can
+ * be, so the expression is only ever squeezed, never resolved.
+ *
+ * @type {RegExp}
+ */
+const PERCENTAGE_MULTIPLICATION = /^(?:-?(?:\d*\.\d+|\d+)%\s*\*\s*-?(?:\d*\.\d+|\d+)|-?(?:\d*\.\d+|\d+)\s*\*\s*-?(?:\d*\.\d+|\d+)%)$/;
+
+/**
+ * Matches a value that is a single percentage, which is all a calculation
+ * leaves behind once every term of it has resolved into one.
+ *
+ * @type {RegExp}
+ */
+const RESOLVED_PERCENTAGE = /^-?(?:\d+|\d*\.\d+)%$/;
+
+/**
+ * Chooses how a calculation that shares a percentage out resolves. The
+ * library states the result to the full precision a float carries, which is
+ * both longer than the calculation it replaces and finer than a stylesheet
+ * has any use for, so the result is rounded into the budget a resolved number
+ * is written within and kept only when it is the shorter of the two.
+ *
+ * @param  {string} simplified    The result the calculation library returned.
+ * @param  {string} compactInner  The contents of the `calc()`, with its whitespace collapsed.
+ * @param  {string} match         The whole `calc()` as it was written.
+ * @return {string}               How the resolved calculation is written.
+ */
+function chooseResolvedPercentage (simplified, compactInner, match) {
+  // A division sign written after a percentage, which is what the resolved percentage was shared out by
+  const dividesAPercentage = RESOLVED_PERCENTAGE.test(simplified) && /%\s*\//.test(match);
+  if (!dividesAPercentage) {
+    return simplified;
+  }
+  // Remove whitespace around division operator
+  const calculation = 'calc(' + compactInner.replace(/\s*\/\s*/g, '/') + ')';
+  const resolved = formatResolvedNumber(parseFloat(simplified)) + '%';
+  return shorterOfResolutionAndCalculation(resolved, calculation);
+}
+
+/**
+ * Resolves the contents of a `calc()` into the shortest way of writing the
+ * same value, which is either the value the arithmetic works out to or the
+ * calculation itself with the whitespace squeezed out of it.
+ *
+ * @param  {string} match         The whole `calc()` as it was written.
+ * @param  {string} compactInner  The contents of the `calc()`, with its whitespace collapsed.
+ * @return {string}               The shortest way of writing what the calculation states.
+ */
+function resolveCalcExpression (match, compactInner) {
+  if (PERCENTAGE_MULTIPLICATION.test(compactInner)) {
+    return compactCalculation(compactInner);
+  }
+
+  const dividedPercentage = resolvePercentageDivision(compactInner);
+  if (dividedPercentage) {
+    return dividedPercentage;
+  }
+
+  const folded = tryFoldCalcExpression(compactInner);
+  if (folded) {
+    return folded;
+  }
+
+  const simplified = simplifyCalc(match);
+  if (simplified === null) {
+    return match;
+  }
+  const resolved = chooseResolvedPercentage(simplified, compactInner, match);
+  return chooseResolvedCalculation(resolved, compactCalculation(compactInner));
+}
+
+/**
+ * Simplifies a standalone calc() value by resolving its arithmetic, flattening nested calc expressions, converting absolute length units to pixels, and folding constant terms.
+ *
+ * @param  {string} value  The CSS value string, already known to be a single `calc()`.
+ * @return {string}        The simplified value, or the original value if simplification is not applicable.
+ */
+function foldStandaloneCalc (value) {
+  let inner = value.slice(5, -1).trim();
+
+  // Preserve percent-times-number expressions, only stripping whitespace around operators
+  if (PERCENTAGE_MULTIPLICATION.test(inner.replace(/\s+/g, ' ').trim())) {
+    return compactCalculation(inner);
+  }
+
+  // Resolve the calculation as it was written, which is the only reading of it
+  // that keeps the grouping its parentheses state. Everything below reads a
+  // flattened copy of the expression, where that grouping is already gone.
+  const resolved = simplifyCalc(value);
+  if (resolved !== null) {
+    return chooseResolvedCalculation(resolved, compactCalculation(inner));
+  }
+
+  // If no nested function calls and no multiplication/division involving parens, try flattening
+  if (!/[A-Za-z-]+\(/.test(inner) && !/[*/]\s*\(|\)\s*[*/]/.test(inner)) {
+    // Remove all parentheses and collapse whitespace for folding
+    const flattened = inner.replace(/[()]/g, '').replace(/\s+/g, ' ').trim();
+    const foldedFlattened = tryFoldCalcExpression(flattened);
+    if (foldedFlattened) {
+      return foldedFlattened;
+    }
+  }
+
+  let previous;
+
+  do {
+    previous = inner;
+    // Fold innermost parenthesized sub-expressions that aren't function calls
+    inner = inner.replace(/(^|[^A-Za-z-])\(([^()]+)\)/g, (match, prefix, content) => {
+      const trimmed = content.trim();
+      const folded = tryFoldCalcExpression(trimmed);
+      if (folded) {
+        if (folded.startsWith('calc(') && folded.endsWith(')')) {
+          return prefix + trimmed;
+        }
+        return prefix + folded;
+      }
+      return prefix + trimmed;
+    });
+  } while (inner !== previous);
+
+  const folded = tryFoldCalcExpression(inner);
+  if (folded) {
+    return folded;
+  }
+
+  // Collapse whitespace and check for percent-division expressions
+  const dividedPercentage = resolvePercentageDivision(inner.replace(/\s+/g, ' ').trim());
+  if (dividedPercentage) {
+    return dividedPercentage;
+  }
+
+  return compactCalculation(inner);
+}
+
+export {
+  foldStandaloneCalc,
+  resolveCalcExpression
+};

package/src/value/math/format.js

@@ -0,0 +1,230 @@
+/**
+ * @file Writes the unit totals a calculation resolved to as the shortest CSS value that states them.
+ */
+
+import { formatResolvedNumber } from '../shared.js';
+
+import { PERCENTAGE } from './unit-totals.js';
+
+/**
+ * The smallest total a term is written with. A term totalling less than this
+ * is the rounding error binary floating point arithmetic leaves behind rather
+ * than a quantity the stylesheet states.
+ *
+ * @type {number}
+ */
+const NEGLIGIBLE_TOTAL = 1e-12;
+
+/**
+ * The unit each kind of quantity is canonically stated in, and how much of
+ * that unit one of the unit written measures. Absolute lengths are absent
+ * because every length is already totalled in the pixels it measures.
+ *
+ * @type {Map<string, {unit: string, perUnit: number}>}
+ */
+const CANONICAL_UNITS = new Map([
+  ['s', { unit: 's', perUnit: 1 }],
+  ['ms', { unit: 's', perUnit: 1 / 1000 }],
+  ['deg', { unit: 'deg', perUnit: 1 }],
+  ['grad', { unit: 'deg', perUnit: 360 / 400 }],
+  ['rad', { unit: 'deg', perUnit: 180 / Math.PI }],
+  ['turn', { unit: 'deg', perUnit: 360 }],
+  ['hz', { unit: 'hz', perUnit: 1 }],
+  ['khz', { unit: 'hz', perUnit: 1000 }],
+  ['dppx', { unit: 'dppx', perUnit: 1 }],
+  ['x', { unit: 'dppx', perUnit: 1 }],
+  ['dpi', { unit: 'dppx', perUnit: 1 / 96 }],
+  ['dpcm', { unit: 'dppx', perUnit: 2.54 / 96 }]
+]);
+
+/**
+ * Counts how many units of each kind of quantity a calculation totalled, so
+ * that the kinds it states in more than one unit can be told from the ones it
+ * states in a single unit.
+ *
+ * @param  {Map} totals  The unit totals the calculation resolved to.
+ * @return {Map}         How many units each canonical unit was totalled from.
+ */
+function countUnitsByKind (totals) {
+  const counts = new Map();
+  for (const unit of totals.keys()) {
+    const conversion = CANONICAL_UNITS.get(unit);
+    if (!conversion) {
+      continue;
+    }
+    counts.set(conversion.unit, (counts.get(conversion.unit) || 0) + 1);
+  }
+  return counts;
+}
+
+/**
+ * Restates the totals of every kind of quantity a calculation measured in two
+ * units of, so that terms measuring the same thing are totalled together
+ * (`calc(1s - 200ms)` comes to `.8s`). A kind measured in a single unit keeps
+ * that unit: restating `2ms` as `.002s` measures the same time in more
+ * characters than it was written with.
+ *
+ * @param  {Map} totals  The unit totals the calculation resolved to.
+ * @return {Map}         The totals, with each kind of quantity stated in one unit.
+ */
+function mergeUnitsOfSameKind (totals) {
+  const unitCounts = countUnitsByKind(totals);
+  const measuredInSeveralUnits = [...unitCounts.values()].some((count) => {
+    return count > 1;
+  });
+  if (!measuredInSeveralUnits) {
+    return totals;
+  }
+  const merged = new Map();
+  for (const [unit, total] of totals) {
+    const conversion = CANONICAL_UNITS.get(unit);
+    const restatesUnit = conversion && unitCounts.get(conversion.unit) > 1;
+    const mergedUnit = restatesUnit ? conversion.unit : unit;
+    const mergedTotal = restatesUnit ? total * conversion.perUnit : total;
+    merged.set(mergedUnit, (merged.get(mergedUnit) || 0) + mergedTotal);
+  }
+  return merged;
+}
+
+/**
+ * Collects the terms a resolved calculation is written from, leaving out the
+ * ones that totalled to nothing. A unit is totalled from where it is first
+ * written, so the terms keep the order the calculation states them in, which
+ * is both the order the author chose and one fewer difference between what
+ * was written and what is written back out.
+ *
+ * @param  {Map}   totals  The unit totals the calculation resolved to.
+ * @return {Array}         The terms to write, each holding its unit and its total.
+ */
+function collectOutputTerms (totals) {
+  const terms = [];
+  for (const [unit, total] of totals) {
+    if (Math.abs(total) < NEGLIGIBLE_TOTAL) {
+      continue;
+    }
+    terms.push({ total, unit });
+  }
+  return leadWithAddedTerm(terms);
+}
+
+/**
+ * Moves an added term to the front of a calculation that a subtracted one
+ * leads. Every term but the first is written after the operator adding or
+ * subtracting it, so a term written first states its own sign, and the minus
+ * sign of a subtracted one is a character the sum saves by being led by a
+ * term that is added instead.
+ *
+ * @param  {Array} terms  The terms to write, in the order the calculation states them.
+ * @return {Array}        The same terms, led by one that is added whenever any of them is.
+ */
+function leadWithAddedTerm (terms) {
+  if (!terms.length || terms[0].total > 0) {
+    return terms;
+  }
+  const leadingIndex = terms.findIndex((term) => {
+    return term.total > 0;
+  });
+  if (leadingIndex === -1) {
+    return terms;
+  }
+  const reordered = [...terms];
+  const [addedTerm] = reordered.splice(leadingIndex, 1);
+  reordered.unshift(addedTerm);
+  return reordered;
+}
+
+/**
+ * Reports whether writing only the terms collected would drop a percentage the
+ * calculation was written with. A percentage that cancels out still ties the
+ * value to the basis the percentage is resolved against, so a calculation
+ * keeping other terms cannot be written without it.
+ *
+ * @param  {Map}     totals       The unit totals the calculation resolved to.
+ * @param  {Array}   outputTerms  The terms that would be written.
+ * @return {boolean}              Whether a percentage the calculation states would be lost.
+ */
+function dropsPercentageBasis (totals, outputTerms) {
+  if (!totals.has(PERCENTAGE) || !outputTerms.length) {
+    return false;
+  }
+  return !outputTerms.some((term) => {
+    return term.unit === PERCENTAGE;
+  });
+}
+
+/**
+ * Writes the total of a term as the number a stylesheet states it with. A
+ * total that no written number states faithfully — one that is infinite, one
+ * beyond the integers a double holds exactly, and one that rounds away to
+ * nothing — has no number to be written as.
+ *
+ * @param  {number}      total  The total the term resolved to.
+ * @return {string|null}        The number as it is written into the stylesheet, or null when it cannot be written.
+ */
+function writeTermNumber (total) {
+  if (!Number.isFinite(total) || Math.abs(total) > Number.MAX_SAFE_INTEGER) {
+    return null;
+  }
+  const written = formatResolvedNumber(total);
+  const roundsAwayToNothing = total !== 0 && parseFloat(written) === 0;
+  if (roundsAwayToNothing) {
+    return null;
+  }
+  return written;
+}
+
+/**
+ * Writes the unit totals a calculation resolved to as the shortest value
+ * stating them: the lone quantity they came to, or, when units that only
+ * resolve against the element are left over, a `calc()` summing what remains.
+ *
+ * @param  {Map}         totals  The unit totals the calculation resolved to.
+ * @return {string|null}         The value the calculation resolved to, or null when it cannot be written faithfully.
+ */
+function formatUnitTotals (totals) {
+  const writtenQuantity = totals.writtenQuantity;
+  if (
+    writtenQuantity &&
+    totals.size === 1 &&
+    totals.has(writtenQuantity.canonicalUnit) &&
+    totals.get(writtenQuantity.canonicalUnit) === writtenQuantity.canonicalNumber
+  ) {
+    return formatResolvedNumber(writtenQuantity.number) + writtenQuantity.unit;
+  }
+  const mergedTotals = mergeUnitsOfSameKind(totals);
+  const hasUnrepresentableReciprocalUnit = [...mergedTotals.keys()].some((unit) => {
+    return unit.startsWith('reciprocal:');
+  });
+  if (hasUnrepresentableReciprocalUnit) {
+    return null;
+  }
+  const outputTerms = collectOutputTerms(mergedTotals);
+  if (dropsPercentageBasis(mergedTotals, outputTerms)) {
+    return null;
+  }
+  if (!outputTerms.length) {
+    return '0';
+  }
+  const [leadingTerm, ...trailingTerms] = outputTerms;
+  const leadingNumber = writeTermNumber(leadingTerm.total);
+  if (leadingNumber === null) {
+    return null;
+  }
+  let written = leadingNumber + leadingTerm.unit;
+  for (const term of trailingTerms) {
+    const number = writeTermNumber(Math.abs(term.total));
+    if (number === null) {
+      return null;
+    }
+    // Both operators have to be surrounded by whitespace to be read as one
+    written = written + (term.total < 0 ? ' - ' : ' + ') + number + term.unit;
+  }
+  if (trailingTerms.length) {
+    return 'calc(' + written + ')';
+  }
+  return written;
+}
+
+export {
+  formatUnitTotals
+};