@thejaredwilcurt/csslop 0.0.20 → 0.0.22

package/src/declarations/css-wide-keywords.js

@@ -0,0 +1,285 @@
+/**
+ * @file Rewrites longhand declarations that share a CSS-wide keyword into a shorthand carrying that keyword, followed by the longhands that override it.
+ */
+
+import { minifyValue } from '../value/minify.js';
+
+import {
+  CSS_WIDE_KEYWORDS,
+  shorthandMap,
+  shorthandOverrideMap
+} from './config.js';
+
+/**
+ * Expands a property into the set of leaf longhands it ultimately sets, so that
+ * different groupings of the same box, such as `border-width` and
+ * `border-top-width`, can be compared for equivalent coverage.
+ *
+ * @param  {string} property        The property name to expand.
+ * @param  {Set}    leafProperties  The set collecting the leaf longhand names.
+ * @return {Set}                    The set of leaf longhand property names.
+ */
+function expandToLeafProperties (property, leafProperties = new Set()) {
+  const longhands = shorthandMap[property];
+  if (!longhands) {
+    leafProperties.add(property);
+    return leafProperties;
+  }
+  for (const longhand of longhands) {
+    expandToLeafProperties(longhand, leafProperties);
+  }
+  return leafProperties;
+}
+
+/**
+ * Checks whether a group of longhands sets every leaf longhand that the
+ * shorthand sets. A CSS-wide keyword may only move into the shorthand when the
+ * group covers all of them, otherwise the keyword would also land on a longhand
+ * the author never declared.
+ *
+ * @param  {string}  shorthandName  The target shorthand property name.
+ * @param  {Array}   properties     The longhand property names in the group.
+ * @return {boolean}                Whether the group covers the whole shorthand.
+ */
+function coversEveryLonghandOfShorthand (shorthandName, properties) {
+  const coveredLeaves = new Set();
+  for (const property of properties) {
+    expandToLeafProperties(property, coveredLeaves);
+  }
+  return [...expandToLeafProperties(shorthandName)].every((leafProperty) => {
+    return coveredLeaves.has(leafProperty);
+  });
+}
+
+/**
+ * @typedef  {object}  LonghandEntry
+ * @property {object}  declaration    The original declaration object.
+ * @property {number}  index          The declaration's index within the rule.
+ * @property {string}  property       The longhand property name.
+ * @property {string}  text           The minified `property:value` text.
+ * @property {string}  value          The minified value, without any `!important`.
+ * @property {boolean} isImportant    Whether the declaration carries `!important`.
+ */
+
+/**
+ * Collects the declarations of a rule that set one of a shorthand's longhands,
+ * in source order.
+ *
+ * @param  {Array}  declarations   The declarations of a single rule.
+ * @param  {string} shorthandName  The shorthand whose longhands to collect.
+ * @return {Array}                 The matching longhand entries, in source order.
+ */
+function collectLonghandEntries (declarations, shorthandName) {
+  const longhands = shorthandMap[shorthandName];
+  const entries = [];
+  declarations.forEach((declaration, index) => {
+    if (!declaration.property || !longhands.includes(declaration.property)) {
+      return;
+    }
+    const minifiedValue = minifyValue(declaration);
+    const isImportant = minifiedValue.includes('!important');
+    entries.push({
+      declaration,
+      index,
+      property: declaration.property,
+      text: declaration.property + ':' + minifiedValue,
+      value: minifiedValue.replace('!important', '').trim(),
+      isImportant
+    });
+  });
+  return entries;
+}
+
+/**
+ * Checks whether a group declares the same property more than once, which
+ * happens when an intentional fallback was kept. Rewriting such a group would
+ * drop one of the two declarations, so it is left alone.
+ *
+ * @param  {Array}   entries  The longhand entries of the group.
+ * @return {boolean}          Whether any property appears more than once.
+ */
+function hasRepeatedProperty (entries) {
+  const seenProperties = new Set();
+  return entries.some((entry) => {
+    if (seenProperties.has(entry.property)) {
+      return true;
+    }
+    seenProperties.add(entry.property);
+    return false;
+  });
+}
+
+/**
+ * Resolves the `!important` suffix the shorthand must carry. A group that mixes
+ * important and normal longhands cannot be rewritten, because the shorthand
+ * would either lose or gain priority over the longhands it replaces.
+ *
+ * @param  {Array}       entries  The longhand entries of the group.
+ * @return {string|null}          The suffix to append, or null when the group cannot be rewritten.
+ */
+function resolveImportantSuffix (entries) {
+  const allImportant = entries.every((entry) => {
+    return entry.isImportant;
+  });
+  if (allImportant) {
+    return '!important';
+  }
+  const noneImportant = entries.every((entry) => {
+    return !entry.isImportant;
+  });
+  if (noneImportant) {
+    return '';
+  }
+  return null;
+}
+
+/**
+ * Resolves the single CSS-wide keyword shared by the longhands that use one.
+ * A group with no keyword has nothing to hoist, and a group mixing different
+ * keywords has no single value the shorthand could carry.
+ *
+ * @param  {Array}       entries  The longhand entries of the group.
+ * @return {string|null}          The shared keyword, or null when there is none.
+ */
+function resolveSharedKeyword (entries) {
+  const keywords = entries.filter((entry) => {
+    return CSS_WIDE_KEYWORDS.has(entry.value.toLowerCase());
+  }).map((entry) => {
+    return entry.value.toLowerCase();
+  });
+  if (!keywords.length) {
+    return null;
+  }
+  const isSharedByAll = keywords.every((keyword) => {
+    return keyword === keywords[0];
+  });
+  if (!isSharedByAll) {
+    return null;
+  }
+  return keywords[0];
+}
+
+/**
+ * Checks whether a property the shorthand also resets, such as `border-image`
+ * for `border`, is declared before the point where the shorthand would be
+ * inserted. Inserting the shorthand there would discard that declaration.
+ *
+ * @param  {Array}   declarations    The declarations of a single rule.
+ * @param  {string}  shorthandName   The target shorthand property name.
+ * @param  {number}  insertionIndex  The index the shorthand would be inserted at.
+ * @return {boolean}                 Whether an earlier declaration would be discarded.
+ */
+function resetsEarlierDeclaration (declarations, shorthandName, insertionIndex) {
+  const resetProperties = shorthandOverrideMap[shorthandName] || [];
+  if (!resetProperties.length) {
+    return false;
+  }
+  return declarations.slice(0, insertionIndex).some((declaration) => {
+    return resetProperties.includes(declaration.property);
+  });
+}
+
+/**
+ * Rewrites one longhand group into a shorthand holding the shared CSS-wide
+ * keyword, followed by the longhands that override it, when that is shorter
+ * than the group of longhands it replaces.
+ *
+ * @param  {Array}      declarations   The declarations of a single rule.
+ * @param  {string}     shorthandName  The target shorthand property name.
+ * @return {Array|null}                The rewritten declarations, or null when the rewrite does not apply.
+ */
+function rewriteGroupAsKeywordShorthand (declarations, shorthandName) {
+  const shorthandAlreadyExists = declarations.some((declaration) => {
+    return declaration.property === shorthandName;
+  });
+  if (shorthandAlreadyExists) {
+    return null;
+  }
+
+  const entries = collectLonghandEntries(declarations, shorthandName);
+  if (entries.length < 2 || hasRepeatedProperty(entries)) {
+    return null;
+  }
+  const properties = entries.map((entry) => {
+    return entry.property;
+  });
+  if (!coversEveryLonghandOfShorthand(shorthandName, properties)) {
+    return null;
+  }
+
+  const importantSuffix = resolveImportantSuffix(entries);
+  const sharedKeyword = resolveSharedKeyword(entries);
+  if (importantSuffix === null || !sharedKeyword) {
+    return null;
+  }
+
+  const insertionIndex = entries[0].index;
+  if (resetsEarlierDeclaration(declarations, shorthandName, insertionIndex)) {
+    return null;
+  }
+
+  // The longhands whose value is not the shared keyword have to be restated
+  // after the shorthand, because the shorthand also set them to the keyword.
+  const overrideEntries = entries.filter((entry) => {
+    return entry.value.toLowerCase() !== sharedKeyword;
+  });
+  const shorthandDeclaration = {
+    property: shorthandName,
+    value: sharedKeyword + importantSuffix,
+    isAssembledShorthand: true
+  };
+  const rewrittenLength = [shorthandDeclaration.property + ':' + shorthandDeclaration.value, ...overrideEntries.map((entry) => {
+    return entry.text;
+  })].join(';').length;
+  const longhandLength = entries.map((entry) => {
+    return entry.text;
+  }).join(';').length;
+  if (rewrittenLength >= longhandLength) {
+    return null;
+  }
+
+  const groupIndexes = new Set(entries.map((entry) => {
+    return entry.index;
+  }));
+  const result = [];
+  declarations.forEach((declaration, index) => {
+    if (index === insertionIndex) {
+      result.push(shorthandDeclaration);
+      for (const entry of overrideEntries) {
+        result.push(entry.declaration);
+      }
+      return;
+    }
+    if (groupIndexes.has(index)) {
+      return;
+    }
+    result.push(declaration);
+  });
+  return result;
+}
+
+/**
+ * Hoists a CSS-wide keyword such as `inherit` out of a group of longhands into
+ * their shorthand. A CSS-wide keyword is only valid as a declaration's whole
+ * value, so `border-style:inherit;border-color:inherit;border-width:2px` cannot
+ * become `border:2px inherit inherit`. It can however become `border:inherit`
+ * followed by `border-width:2px`, which inherits every border property and then
+ * overrides the one that differs.
+ *
+ * @param  {Array} declarations  The declarations of a single rule.
+ * @return {Array}               The declarations, with eligible groups rewritten.
+ */
+function hoistCssWideKeywordsIntoShorthands (declarations) {
+  let result = declarations;
+  // Shorthands are visited in declaration order, so the widest shorthand of a
+  // family is rewritten before the narrower shorthands it contains.
+  for (const shorthandName of Object.keys(shorthandMap)) {
+    const rewritten = rewriteGroupAsKeywordShorthand(result, shorthandName);
+    if (rewritten) {
+      result = rewritten;
+    }
+  }
+  return result;
+}
+
+export { hoistCssWideKeywordsIntoShorthands };

package/src/declarations/merge.js

@@ -0,0 +1,323 @@
+/**
+ * @file Decides whether a group of longhand declarations may collapse into a shorthand and produces the merged value when it is safe.
+ */
+
+import { minifyValue } from '../value/minify.js';
+
+import {
+  BORDER_EDGE_PROPERTIES,
+  CSS_WIDE_KEYWORDS,
+  EDGE_SHORTHANDS,
+  shorthandMap,
+  shorthandOverrideMap
+} from './config.js';
+import { buildShorthandValue } from './shorthand-values.js';
+
+/**
+ * Shorthands that may still be built when only some of their longhands carry
+ * `!important`, because the remaining longhands stay in the output.
+ *
+ * @type {Set<string>}
+ */
+const MIXED_IMPORTANT_SHORTHANDS = new Set(['margin', 'padding', 'inset', 'position-try']);
+
+/**
+ * Determines which longhand properties are present and eligible for merging into a given shorthand. Returns null when the required longhands for the shorthand are not all available.
+ *
+ * @param  {string}     shorthand     The CSS shorthand property name.
+ * @param  {Array}      longhands     The expected longhand property names for this shorthand.
+ * @param  {Array}      declarations  The current array of CSS declaration objects.
+ * @return {Array|null}               The list of longhand names to merge, or null if merging is not possible.
+ */
+function getMergeProps (shorthand, longhands, declarations) {
+  const presentLonghands = longhands.filter((longhand) => {
+    return declarations.some((declaration) => {
+      return declaration.property === longhand;
+    });
+  });
+  if (presentLonghands.length === 0) {
+    return null;
+  }
+  if (shorthand === 'font') {
+    const hasRequiredFontProps = presentLonghands.includes('font-size') && presentLonghands.includes('font-family');
+    if (hasRequiredFontProps) {
+      return presentLonghands;
+    }
+    return null;
+  }
+  if (shorthand === 'background-position') {
+    const hasBothAxes = presentLonghands.includes('background-position-x') && presentLonghands.includes('background-position-y');
+    if (hasBothAxes) {
+      return presentLonghands;
+    }
+    return null;
+  }
+  if (shorthand === 'background') {
+    const hasBackgroundProp = presentLonghands.includes('background-color') || presentLonghands.includes('background-image');
+    if (hasBackgroundProp) {
+      return presentLonghands;
+    }
+    return null;
+  }
+  if (shorthand === 'mask') {
+    if (presentLonghands.includes('mask-image')) {
+      return presentLonghands;
+    }
+    return null;
+  }
+  if (shorthand === 'border-image') {
+    if (presentLonghands.includes('border-image-source')) {
+      return presentLonghands;
+    }
+    return null;
+  }
+  if (shorthand === 'border') {
+    const hasAllBorderParts = (
+      presentLonghands.includes('border-width') &&
+      presentLonghands.includes('border-style') &&
+      presentLonghands.includes('border-color')
+    );
+    if (hasAllBorderParts) {
+      return ['border-width', 'border-style', 'border-color'];
+    }
+    const hasAllBorderEdges = BORDER_EDGE_PROPERTIES.every((edgeProperty) => {
+      return presentLonghands.includes(edgeProperty);
+    });
+    if (hasAllBorderEdges) {
+      return [...BORDER_EDGE_PROPERTIES];
+    }
+    return null;
+  }
+  if (shorthand === 'flex') {
+    const hasAllFlexParts = (
+      presentLonghands.includes('flex-grow') &&
+      presentLonghands.includes('flex-shrink') &&
+      presentLonghands.includes('flex-basis')
+    );
+    if (hasAllFlexParts) {
+      return ['flex-grow', 'flex-shrink', 'flex-basis'];
+    }
+    return null;
+  }
+  if (presentLonghands.length === longhands.length) {
+    return longhands;
+  }
+  return null;
+}
+
+/**
+ * Check if a value contains var() - don't merge if it does (safest approach).
+ *
+ * @param  {string}  value  The minified CSS value string to check.
+ * @return {boolean}        True if the value contains a var() with a fallback comma.
+ */
+function hasVarFallback (value) {
+  // Match var() containing a comma (indicating a fallback value)
+  return /var\([^)]*,/.test(value);
+}
+
+/**
+ * Determines whether a value containing var() references can safely be merged into a shorthand. Values with fallback commas or unregistered custom properties are not mergeable.
+ *
+ * @param  {string}  value    The minified CSS value string to check.
+ * @param  {object}  context  The minification context with registered custom property data.
+ * @return {boolean}          True if the value is safe to merge into a shorthand.
+ */
+function canMergeVarValue (value, context) {
+  // Check if the value contains any var() reference
+  const containsVar = /var\(/.test(value);
+  if (!containsVar || hasVarFallback(value)) {
+    return !hasVarFallback(value);
+  }
+  // Extract all var() references with their custom property names
+  const matches = [...value.matchAll(/var\((--[A-Za-z0-9_-]+)\)/g)];
+  if (!matches.length) {
+    return false;
+  }
+  return matches.every(([, propertyName]) => {
+    return context.registeredCustomProperties.has(propertyName);
+  });
+}
+
+/**
+ * Checks whether a shorthand affects nothing beyond the longhands being merged.
+ * When a shorthand also resets unrelated properties (for example `border` resets
+ * `border-image`), replacing the longhands with a bare shorthand value would
+ * change the rendered result.
+ *
+ * @param  {string}  shorthandName  The target shorthand property name.
+ * @param  {Array}   properties     The longhand property names being merged.
+ * @return {boolean}                True when the shorthand only affects the merged longhands.
+ */
+function shorthandAffectsOnlyMergedLonghands (shorthandName, properties) {
+  const overrides = shorthandOverrideMap[shorthandName] || [];
+  if (overrides.length) {
+    return false;
+  }
+  const longhands = shorthandMap[shorthandName] || [];
+  return longhands.every((longhand) => {
+    return properties.includes(longhand);
+  });
+}
+
+/**
+ * Resolves how a set of longhand values that contain CSS-wide keywords such as
+ * `inherit` may be merged. A CSS-wide keyword is only valid as a declaration's
+ * entire value, so it can never appear as one component of a shorthand value:
+ * `border-width:0;border-style:inherit;border-color:inherit` cannot become
+ * `border:0 inherit inherit`. Only a set where every longhand carries the same
+ * keyword can merge, and then only into a shorthand that affects nothing else.
+ *
+ * @param  {Array}       values         The cleaned longhand values, in longhand order.
+ * @param  {string}      shorthandName  The target shorthand property name.
+ * @param  {Array}       properties     The longhand property names being merged.
+ * @return {string|null}                The shared keyword to use as the whole shorthand value, or null when merging is unsafe.
+ */
+function resolveCssWideKeywordMerge (values, shorthandName, properties) {
+  const normalizedValues = values.map((value) => {
+    return value.toLowerCase();
+  });
+  const sharedKeyword = normalizedValues[0];
+  const isSharedByAll = normalizedValues.every((value) => {
+    return value === sharedKeyword;
+  });
+  if (!isSharedByAll || !shorthandAffectsOnlyMergedLonghands(shorthandName, properties)) {
+    return null;
+  }
+  return sharedKeyword;
+}
+
+/**
+ * Collects the minified value of every longhand being merged, in shorthand
+ * order. Returns null when any longhand is missing a declaration.
+ *
+ * @param  {Array}      properties    The longhand property names to merge.
+ * @param  {Array}      declarations  The CSS declaration objects to draw values from.
+ * @return {Array|null}               The minified longhand values, or null when one is missing.
+ */
+function collectLonghandValues (properties, declarations) {
+  const values = properties.map((property) => {
+    const declaration = declarations.find((candidate) => {
+      return candidate.property === property;
+    });
+    if (declaration) {
+      return minifyValue(declaration);
+    }
+    return null;
+  });
+  const hasNullValue = values.some((value) => {
+    return value === null;
+  });
+  if (hasNullValue) {
+    return null;
+  }
+  return values;
+}
+
+/**
+ * Resolves the `!important` suffix for a merged shorthand. A shorthand only
+ * keeps `!important` when every longhand carried it, and a mixed set is only
+ * allowed for shorthands whose remaining important longhands stay in the output.
+ *
+ * @param  {Array}       values         The minified longhand values.
+ * @param  {string}      shorthandName  The target shorthand property name.
+ * @return {string|null}                The suffix to append, or null when the mix forbids merging.
+ */
+function resolveImportantSuffix (values, shorthandName) {
+  const importantFlags = values.map((value) => {
+    return value.includes('!important');
+  });
+  const allImportant = importantFlags.every((flag) => {
+    return flag;
+  });
+  const noneImportant = importantFlags.every((flag) => {
+    return !flag;
+  });
+  if (allImportant) {
+    return '!important';
+  }
+  if (noneImportant || MIXED_IMPORTANT_SHORTHANDS.has(shorthandName)) {
+    return '';
+  }
+  return null;
+}
+
+/**
+ * Try to merge longhand properties into a shorthand.
+ *
+ * @param  {Array}       properties     The longhand property names to merge.
+ * @param  {Array}       declarations   The CSS declaration objects to draw values from.
+ * @param  {string}      shorthandName  The target shorthand property name.
+ * @param  {object}      context        The minification context with registered custom property data.
+ * @return {string|null}                The merged shorthand value string, or null if merging is not possible.
+ */
+function tryMergeToShorthand (properties, declarations, shorthandName = '', context) {
+  if (properties.length < 2) {
+    return null;
+  }
+
+  const values = collectLonghandValues(properties, declarations);
+  if (!values) {
+    return null;
+  }
+
+  // Don't merge if any value has var() with fallback or unknown custom properties
+  const hasUnmergeableVar = values.some((value) => {
+    return !canMergeVarValue(value, context);
+  });
+  if (hasUnmergeableVar) {
+    return null;
+  }
+
+  const importantSuffix = resolveImportantSuffix(values, shorthandName);
+  if (importantSuffix === null) {
+    return null;
+  }
+
+  const cleanValues = values.map((value) => {
+    return value
+      .replace('!important', '')
+      .trim();
+  });
+  const valueMap = new Map(properties.map((property, index) => {
+    return [property, cleanValues[index]];
+  }));
+
+  const usesCssWideKeyword = cleanValues.some((value) => {
+    return CSS_WIDE_KEYWORDS.has(value.toLowerCase());
+  });
+  if (usesCssWideKeyword) {
+    const sharedKeyword = resolveCssWideKeywordMerge(cleanValues, shorthandName, properties);
+    if (!sharedKeyword) {
+      return null;
+    }
+    return sharedKeyword + importantSuffix;
+  }
+
+  // Each edge shorthand holds a complete width/style/color value, so the edges
+  // only collapse into their parent shorthand when they are all identical.
+  const mergesEdgeShorthands = properties.every((property) => {
+    return EDGE_SHORTHANDS.has(property);
+  });
+  if (mergesEdgeShorthands) {
+    const allEdgesMatch = cleanValues.every((value) => {
+      return value === cleanValues[0];
+    });
+    if (!allEdgesMatch) {
+      return null;
+    }
+    return cleanValues[0] + importantSuffix;
+  }
+
+  return buildShorthandValue(shorthandName, {
+    properties,
+    valueMap,
+    cleanValues,
+    importantSuffix
+  });
+}
+
+export {
+  getMergeProps,
+  tryMergeToShorthand
+};

package/src/declarations/order.js

@@ -0,0 +1,77 @@
+/**
+ * @file Orders declarations within a rule so that shorthands stay ahead of the longhands they reset.
+ */
+
+import {
+  shorthandMap,
+  shorthandOverrideMap
+} from './config.js';
+
+/**
+ * Pairs of properties where the first must be emitted before the second, because
+ * the first resets the second and a merged shorthand is appended after the
+ * longhands it was built from.
+ *
+ * @type {Array}
+ */
+const REQUIRED_PROPERTY_ORDER = [
+  ['border', 'border-image'],
+  ['font', 'font-feature-settings'],
+  ['font', 'font-variant-ligatures'],
+  ['font', 'font-kerning'],
+  ['font', 'font-variation-settings'],
+  ['mask', 'mask-border'],
+  ['margin', 'margin-top'],
+  ['margin', 'margin-right'],
+  ['margin', 'margin-bottom'],
+  ['margin', 'margin-left']
+];
+
+/**
+ * Reorders declarations so that shorthands appear before any related longhands they would override, preventing cascade issues in the minified output.
+ *
+ * @param  {Array} declarations  The array of CSS declaration objects to reorder.
+ * @return {Array}               A new array with declarations in the corrected order.
+ */
+function orderDeclarations (declarations) {
+  const ordered = [...declarations];
+  const findPropertyIndex = (property) => {
+    return ordered.findIndex((declaration) => {
+      return declaration?.property === property;
+    });
+  };
+
+  for (const [property, followingProperty] of REQUIRED_PROPERTY_ORDER) {
+    const fromIndex = findPropertyIndex(property);
+    const toIndex = findPropertyIndex(followingProperty);
+    if (fromIndex === -1 || toIndex === -1 || fromIndex < toIndex) {
+      continue;
+    }
+    const [movedDeclaration] = ordered.splice(fromIndex, 1);
+    ordered.splice(toIndex, 0, movedDeclaration);
+  }
+
+  return ordered;
+}
+
+/**
+ * Get all longhands that a shorthand would override.
+ *
+ * @param  {string} shorthandProperty  The CSS shorthand property name.
+ * @return {Array}                     A deduplicated array of all longhand property names that the shorthand overrides, including nested longhands.
+ */
+function getOverriddenLonghands (shorthandProperty) {
+  const direct = shorthandMap[shorthandProperty] || [];
+  const overrides = shorthandOverrideMap[shorthandProperty] || [];
+  const all = [...direct, ...overrides];
+  for (const property of direct) {
+    const nested = shorthandMap[property] || [];
+    all.push(...nested);
+  }
+  return [...new Set(all)];
+}
+
+export {
+  getOverriddenLonghands,
+  orderDeclarations
+};