@thejaredwilcurt/csslop 0.0.19 → 0.0.21

package/src/declarations/shorthand-values.js

@@ -0,0 +1,374 @@
+/**
+ * @file Serializes the collected longhand values of a shorthand into the shortest valid shorthand value, one builder per shorthand family.
+ */
+
+import { collapseShorthandParts } from '../value/shared.js';
+import { splitTopLevelComponents } from '../value/syntax.js';
+
+import { buildBackgroundShorthandValue } from './background.js';
+
+/**
+ * @typedef  {object} ShorthandComponents
+ * @property {Array}  properties           The longhand property names being merged, in shorthand order.
+ * @property {Map}    valueMap             A map of each longhand property name to its cleaned value.
+ * @property {Array}  cleanValues          The cleaned longhand values, in the same order as `properties`.
+ * @property {string} importantSuffix      A trailing `!important` suffix, or an empty string.
+ */
+
+/**
+ * Builds a `position-try` value, which only collapses while the order component
+ * is at its `normal` default.
+ *
+ * @param  {ShorthandComponents} components  The collected longhand values.
+ * @return {string|null}                     The shorthand value, or null when it cannot be built.
+ */
+function buildPositionTryValue ({ valueMap, importantSuffix }) {
+  const order = valueMap.get('position-try-order');
+  const fallbacks = valueMap.get('position-try-fallbacks');
+  if (order === 'normal' && fallbacks) {
+    return fallbacks + importantSuffix;
+  }
+  return null;
+}
+
+/**
+ * Builds a `transition` value, omitting the trailing components that already
+ * hold their initial value.
+ *
+ * @param  {ShorthandComponents} components  The collected longhand values.
+ * @return {string|null}                     The shorthand value, or null when it cannot be built.
+ */
+function buildTransitionValue ({ valueMap, importantSuffix }) {
+  const transitionProperty = valueMap.get('transition-property');
+  const duration = valueMap.get('transition-duration');
+  const timing = valueMap.get('transition-timing-function');
+  const delay = valueMap.get('transition-delay');
+  if (!transitionProperty || !duration) {
+    return null;
+  }
+  const result = [transitionProperty, duration];
+  if (timing && timing !== 'ease') {
+    result.push(timing);
+  }
+  if (delay && delay !== '0' && delay !== '0s') {
+    result.push(delay);
+  }
+  return result.join(' ') + importantSuffix;
+}
+
+/**
+ * Builds an `animation` value, omitting the components that already hold their
+ * initial value.
+ *
+ * @param  {ShorthandComponents} components  The collected longhand values.
+ * @return {string|null}                     The shorthand value, or null when it cannot be built.
+ */
+function buildAnimationValue ({ valueMap, importantSuffix }) {
+  const animationName = valueMap.get('animation-name');
+  const duration = valueMap.get('animation-duration');
+  if (!animationName || !duration) {
+    return null;
+  }
+  const result = [animationName, duration];
+  const timing = valueMap.get('animation-timing-function');
+  const delay = valueMap.get('animation-delay');
+  const iteration = valueMap.get('animation-iteration-count');
+  const direction = valueMap.get('animation-direction');
+  const fillMode = valueMap.get('animation-fill-mode');
+  const playState = valueMap.get('animation-play-state');
+  if (timing && timing !== 'ease') {
+    result.push(timing);
+  }
+  if (delay && delay !== '0' && delay !== '0s') {
+    result.push(delay);
+  }
+  if (iteration && iteration !== '1') {
+    result.push(iteration);
+  }
+  if (direction && direction !== 'normal') {
+    result.push(direction);
+  }
+  if (fillMode && fillMode !== 'none') {
+    result.push(fillMode);
+  }
+  if (playState && playState !== 'running') {
+    result.push(playState);
+  }
+  return result.join(' ') + importantSuffix;
+}
+
+/**
+ * Builds a `background-position` value from its two axis longhands.
+ *
+ * @param  {ShorthandComponents} components  The collected longhand values.
+ * @return {string|null}                     The shorthand value, or null when it cannot be built.
+ */
+function buildBackgroundPositionValue ({ valueMap, importantSuffix }) {
+  const positionX = valueMap.get('background-position-x');
+  const positionY = valueMap.get('background-position-y');
+  if (!positionX || !positionY) {
+    return null;
+  }
+  return positionX + ' ' + positionY + importantSuffix;
+}
+
+/**
+ * Builds a `background` value from its component longhands.
+ *
+ * @param  {ShorthandComponents} components  The collected longhand values.
+ * @return {string|null}                     The shorthand value, or null when it cannot be built.
+ */
+function buildBackgroundValue ({ valueMap, importantSuffix }) {
+  return buildBackgroundShorthandValue(valueMap, importantSuffix);
+}
+
+/**
+ * Builds a `mask` value, attaching the size after the position separator.
+ *
+ * @param  {ShorthandComponents} components  The collected longhand values.
+ * @return {string|null}                     The shorthand value, or null when it cannot be built.
+ */
+function buildMaskValue ({ valueMap, importantSuffix }) {
+  const image = valueMap.get('mask-image');
+  const repeat = valueMap.get('mask-repeat');
+  const size = valueMap.get('mask-size');
+  if (!image) {
+    return null;
+  }
+  let result = image;
+  if (repeat) {
+    result += ' ' + repeat;
+  }
+  if (size) {
+    result += '/' + size;
+  }
+  return result + importantSuffix;
+}
+
+/**
+ * Builds a `border-image` value, which requires a source to be meaningful.
+ *
+ * @param  {ShorthandComponents} components  The collected longhand values.
+ * @return {string|null}                     The shorthand value, or null when it cannot be built.
+ */
+function buildBorderImageValue ({ valueMap, importantSuffix }) {
+  const source = valueMap.get('border-image-source');
+  const slice = valueMap.get('border-image-slice');
+  const repeat = valueMap.get('border-image-repeat');
+  if (!source) {
+    return null;
+  }
+  const result = [source];
+  if (slice) {
+    result.push(slice);
+  }
+  if (repeat) {
+    result.push(repeat);
+  }
+  return result.join(' ') + importantSuffix;
+}
+
+/**
+ * Builds a `text-decoration` value, omitting the default style and color.
+ *
+ * @param  {ShorthandComponents} components  The collected longhand values.
+ * @return {string|null}                     The shorthand value, or null when it cannot be built.
+ */
+function buildTextDecorationValue ({ valueMap, importantSuffix }) {
+  const line = valueMap.get('text-decoration-line');
+  const style = valueMap.get('text-decoration-style');
+  const color = valueMap.get('text-decoration-color');
+  if (!line) {
+    return null;
+  }
+  const result = [line];
+  if (style && style !== 'solid') {
+    result.push(style);
+  }
+  if (color && color !== 'currentcolor') {
+    result.push(color);
+  }
+  return result.join(' ') + importantSuffix;
+}
+
+/**
+ * Builds a `columns` value, which keeps both components even when they match,
+ * because the width and count are not interchangeable.
+ *
+ * @param  {ShorthandComponents} components  The collected longhand values.
+ * @return {string|null}                     The shorthand value, or null when it cannot be built.
+ */
+function buildColumnsValue ({ cleanValues, importantSuffix }) {
+  return cleanValues.join(' ') + importantSuffix;
+}
+
+/**
+ * Builds a `list-style` value, omitting default components and falling back to
+ * `inside` when every component holds its initial value.
+ *
+ * @param  {ShorthandComponents} components  The collected longhand values.
+ * @return {string|null}                     The shorthand value, or null when it cannot be built.
+ */
+function buildListStyleValue ({ valueMap, importantSuffix }) {
+  const position = valueMap.get('list-style-position');
+  const image = valueMap.get('list-style-image');
+  const type = valueMap.get('list-style-type');
+  const result = [];
+  if (position && position !== 'outside') {
+    result.push(position);
+  }
+  if (image && image !== 'none') {
+    result.push(image);
+  }
+  if (type && type !== 'disc') {
+    result.push(type);
+  }
+  const joined = result.join(' ') || 'inside';
+  return joined + importantSuffix;
+}
+
+/**
+ * Builds a `font` value, which requires both a size and a family, and attaches
+ * any line height after the size separator.
+ *
+ * @param  {ShorthandComponents} components  The collected longhand values.
+ * @return {string|null}                     The shorthand value, or null when it cannot be built.
+ */
+function buildFontValue ({ valueMap, importantSuffix }) {
+  const fontSize = valueMap.get('font-size');
+  const fontFamily = valueMap.get('font-family');
+  if (!fontSize || !fontFamily) {
+    return null;
+  }
+  const result = [];
+  const fontStyle = valueMap.get('font-style');
+  const fontWeight = valueMap.get('font-weight');
+  const lineHeight = valueMap.get('line-height');
+  if (fontStyle && fontStyle !== 'normal') {
+    result.push(fontStyle);
+  }
+  if (fontWeight && fontWeight !== '400' && fontWeight !== 'normal') {
+    result.push(fontWeight);
+  }
+  if (lineHeight) {
+    result.push(fontSize + '/' + lineHeight);
+  } else {
+    result.push(fontSize);
+  }
+  result.push(fontFamily);
+  return result.join(' ') + importantSuffix;
+}
+
+/**
+ * Builds a `flex` value from its three required components.
+ *
+ * @param  {ShorthandComponents} components  The collected longhand values.
+ * @return {string|null}                     The shorthand value, or null when it cannot be built.
+ */
+function buildFlexValue ({ valueMap, importantSuffix }) {
+  const grow = valueMap.get('flex-grow');
+  const shrink = valueMap.get('flex-shrink');
+  const basis = valueMap.get('flex-basis');
+  if (!grow || !shrink || !basis) {
+    return null;
+  }
+  return [grow, shrink, basis].join(' ') + importantSuffix;
+}
+
+/**
+ * Determines whether a shorthand takes a single width, style, and color, as
+ * `border` and `outline` do.
+ *
+ * @param  {Array}   properties  The longhand property names being merged.
+ * @return {boolean}             Whether the longhands form a width/style/color trio.
+ */
+function isWidthStyleColorTrio (properties) {
+  return (
+    properties.length === 3 &&
+    (properties.includes('border-width') || properties.includes('outline-width')) &&
+    properties.some((property) => {
+      // Check if one longhand ends with "-style" (e.g. border-style, outline-style)
+      return /-style$/.test(property);
+    }) &&
+    properties.some((property) => {
+      // Check if one longhand ends with "-color" (e.g. border-color, outline-color)
+      return /-color$/.test(property);
+    })
+  );
+}
+
+/**
+ * Builds the value of a shorthand whose components are positional: two-value
+ * logical pairs, four-value box sides, and width/style/color trios.
+ *
+ * @param  {ShorthandComponents} components  The collected longhand values.
+ * @return {string|null}                     The shorthand value, or null when it cannot be built.
+ */
+function buildPositionalShorthandValue ({ properties, cleanValues, importantSuffix }) {
+  if (properties.length === 2) {
+    // A logical pair collapses to one value when both sides match
+    if (cleanValues[0] === cleanValues[1]) {
+      return cleanValues[0] + importantSuffix;
+    }
+    return cleanValues.join(' ') + importantSuffix;
+  }
+
+  if (properties.length === 4) {
+    // Box sides collapse from top/right/bottom/left down to as few values as possible
+    return collapseShorthandParts([...cleanValues]).join(' ') + importantSuffix;
+  }
+
+  if (isWidthStyleColorTrio(properties)) {
+    // Every component of a border/outline shorthand accepts a single value, so a
+    // per-edge value such as `border-color:#0000 red` cannot be merged directly.
+    const hasOnlySingleComponentValues = cleanValues.every((value) => {
+      return splitTopLevelComponents(value).length === 1;
+    });
+    if (!hasOnlySingleComponentValues) {
+      return null;
+    }
+    return cleanValues.join(' ') + importantSuffix;
+  }
+
+  return null;
+}
+
+/**
+ * Builders for shorthands whose components are identified by name rather than by
+ * position, keyed by shorthand property name.
+ *
+ * @type {{[key: string]: function(ShorthandComponents): (string|null)}}
+ */
+const NAMED_SHORTHAND_BUILDERS = {
+  animation: buildAnimationValue,
+  background: buildBackgroundValue,
+  'background-position': buildBackgroundPositionValue,
+  'border-image': buildBorderImageValue,
+  columns: buildColumnsValue,
+  flex: buildFlexValue,
+  font: buildFontValue,
+  'list-style': buildListStyleValue,
+  mask: buildMaskValue,
+  'position-try': buildPositionTryValue,
+  'text-decoration': buildTextDecorationValue,
+  transition: buildTransitionValue
+};
+
+/**
+ * Serializes the collected longhand values of a shorthand into its minified
+ * shorthand value, using the builder registered for that shorthand and falling
+ * back to positional assembly for box-model style shorthands.
+ *
+ * @param  {string}              shorthandName  The target shorthand property name.
+ * @param  {ShorthandComponents} components     The collected longhand values.
+ * @return {string|null}                        The shorthand value, or null when it cannot be built.
+ */
+function buildShorthandValue (shorthandName, components) {
+  const namedBuilder = NAMED_SHORTHAND_BUILDERS[shorthandName];
+  if (namedBuilder) {
+    return namedBuilder(components);
+  }
+  return buildPositionalShorthandValue(components);
+}
+
+export { buildShorthandValue };

package/src/rules/normalize.js

@@ -70,7 +70,21 @@ function normalizeMedia (media) {
       return fullMatch;
     }
   );
-  return media;
+  return compactLogicalOperators(media.trim());
+}
+
+/**
+ * Removes the whitespace between a closing parenthesis and a following `and`/`or`
+ * logical operator, which a closing parenthesis already separates unambiguously.
+ * The space after the operator is required, since it separates the operator from
+ * the next condition's opening parenthesis.
+ *
+ * @param  {string} condition  A normalized `@media` or `@supports` condition string.
+ * @return {string}            The condition with tightened logical operator spacing.
+ */
+function compactLogicalOperators (condition) {
+  // Compact logical operator spacing: ") and (" → ")and (", ") or (" → ")or ("
+  return condition.replace(/\)\s*(and|or)\s*\(/gi, ')$1 (');
 }
 
 /**
@@ -83,10 +97,7 @@ function normalizeSupports (supports) {
   // Collapse whitespace and strip spaces around punctuation
   supports = supports.replace(/\s+/g, ' ').replace(/\s*([:,])\s*/g, '$1').replace(/\s*([=<>])\s*/g, '$1').replace(/\(\s+/g, '(').replace(/\s+\)/g, ')').trim();
   supports = supports.replace(/\s+and\s+/g, ' and ').replace(/\s+or\s+/g, ' or ').replace(/\s+not\s+/g, ' not ');
-  // Compact logical operator spacing: ") and (" → ")and ("
-  supports = supports.replace(/\)\s*and\s*\(/g, ')and (');
-  supports = supports.replace(/\)\s*or\s*\(/g, ')or (');
-  return supports;
+  return compactLogicalOperators(supports);
 }
 
 /**

package/src/rules/selectors.js

@@ -173,10 +173,77 @@ function mergeAdjacentWherePseudoClasses (selector) {
   return result;
 }
 
+/**
+ * Matches a compound selector built exclusively from long-established simple
+ * selectors: an optional type or universal selector, followed by any number of
+ * id and class selectors. Anything else (pseudo-classes, pseudo-elements,
+ * attribute matchers, combinators, descendant sequences) is excluded, because
+ * those may be unrecognized by a browser and `:is()` forgiving parsing is what
+ * keeps the remaining selectors in the rule alive.
+ *
+ * @type {RegExp}
+ */
+const BROWSER_SAFE_COMPOUND_SELECTOR = /^(?:\*|[a-zA-Z][a-zA-Z0-9_-]*)?(?:[#.][a-zA-Z_-][a-zA-Z0-9_-]*)*$/;
+
+/**
+ * Matches every id or class selector within a compound selector, used to count
+ * each one's specificity contribution.
+ *
+ * @type {RegExp}
+ */
+const ID_OR_CLASS_SELECTOR = /[#.][a-zA-Z_-][a-zA-Z0-9_-]*/g;
+
+/**
+ * Computes the specificity of a compound selector known to consist only of
+ * type, universal, id, and class selectors, as an "ids,classes,types" key.
+ *
+ * @param  {string} compoundSelector  A browser-safe compound selector.
+ * @return {string}                   The specificity key for equality comparison.
+ */
+function getSimpleCompoundSpecificityKey (compoundSelector) {
+  const idsAndClasses = compoundSelector.match(ID_OR_CLASS_SELECTOR) || [];
+  const identifierCount = idsAndClasses.filter((selector) => {
+    return selector.startsWith('#');
+  }).length;
+  const classCount = idsAndClasses.length - identifierCount;
+  // Whatever precedes the first id/class is the type or universal selector, if any
+  const typePortion = compoundSelector.split(/[#.]/)[0];
+  const typeCount = typePortion && typePortion !== '*' ? 1 : 0;
+  return identifierCount + ',' + classCount + ',' + typeCount;
+}
+
+/**
+ * Determines whether a `:is()` selector list can be decomposed into a plain
+ * comma-separated selector list. `:is()` applies the highest specificity of its
+ * arguments to every match, so decomposing is only equivalent when all
+ * arguments share one specificity. It also parses forgivingly, so every
+ * argument must additionally be a selector every browser understands.
+ *
+ * @param  {Array}   parts  The selector strings inside the `:is()`.
+ * @return {boolean}        True when the `:is()` wrapper can be dropped.
+ */
+function canDecomposeIsSelector (parts) {
+  if (parts.length < 2) {
+    return false;
+  }
+  const allBrowserSafe = parts.every((part) => {
+    return part !== '' && BROWSER_SAFE_COMPOUND_SELECTOR.test(part);
+  });
+  if (!allBrowserSafe) {
+    return false;
+  }
+  const specificityKeys = parts.map((part) => {
+    return getSimpleCompoundSpecificityKey(part);
+  });
+  return specificityKeys.every((key) => {
+    return key === specificityKeys[0];
+  });
+}
+
 /**
  * Processes a bare `:is()` selector by merging `:link`+`:visited` into `:any-link`,
- * de-duplicating, sorting alphabetically, and conditionally expanding into individual
- * selectors when all parts are simple type/universal selectors with no modifications.
+ * de-duplicating, sorting alphabetically, and decomposing into individual selectors
+ * when the remaining parts are browser-safe and share one level of specificity.
  *
  * @param  {string} selector  A minified CSS selector string.
  * @return {Array}            An array of one or more processed selector strings.
@@ -223,7 +290,6 @@ function processIsSelector (selector) {
     }
   }
   parts.push(currentPart);
-  const originalCount = parts.length;
   // Replace :link + :visited with :any-link
   const hasLink = parts.includes(':link');
   const hasVisited = parts.includes(':visited');
@@ -243,11 +309,8 @@ function processIsSelector (selector) {
   if (parts.length === 1) {
     return parts;
   }
-  // Expand if all parts are simple type/universal selectors and no dedup/replacement occurred
-  const allSimple = parts.every((part) => {
-    return /^[a-z*][a-z0-9-]*$/i.test(part);
-  });
-  if (allSimple && parts.length === originalCount) {
+  // Drop the :is() wrapper when the parts are equivalent as a plain selector list
+  if (canDecomposeIsSelector(parts)) {
     return parts;
   }
   return [':is(' + parts.join(',') + ')'];

package/src/rules/stringify.js

@@ -121,12 +121,11 @@ function stringifyAtRule (rule, context) {
 /**
  * Converts a parsed CSS AST rule node into a minified CSS string, dispatching to specialized handlers for each rule type including selectors, `@media`, `@keyframes`, `@layer`, and other at-rules.
  *
- * @param  {object}  rule     The AST rule node to stringify.
- * @param  {object}  context  The minification context with registered custom property data.
- * @param  {boolean} nested   Whether this rule is nested inside another rule, affecting spacing.
- * @return {string}           The minified CSS string for this rule, or an empty string if the rule is empty.
+ * @param  {object} rule     The AST rule node to stringify.
+ * @param  {object} context  The minification context with registered custom property data.
+ * @return {string}          The minified CSS string for this rule, or an empty string if the rule is empty.
  */
-function stringifyRule (rule, context, nested = false) {
+function stringifyRule (rule, context) {
   if (rule.type === 'rule') {
     let declarations = rule.declarations
       ?.filter((declaration) => {
@@ -308,7 +307,7 @@ function stringifyRule (rule, context, nested = false) {
       .join(';');
 
     let renderedNested = nestedRules.map((nestedRule) => {
-      return stringifyRule(nestedRule, context, true);
+      return stringifyRule(nestedRule, context);
     }).join('');
 
     output.push(renderedDeclarations);
@@ -323,11 +322,11 @@ function stringifyRule (rule, context, nested = false) {
 
   if (rule.type === 'media') {
     const normalizedMedia = normalizeMedia(rule.media);
-    // A custom-media reference is a parenthesized dashed-ident like (--modern);
-    // no space is needed after @media when the query begins with such a token.
-    const isCustomMediaReference = normalizedMedia.startsWith('(--');
+    // An opening parenthesis unambiguously starts the first media condition
+    // (including custom-media references like `(--modern)`), so the space after
+    // `@media` is only required when the query begins with an identifier.
     let separator;
-    if ((nested && normalizedMedia.startsWith('(')) || isCustomMediaReference) {
+    if (normalizedMedia.startsWith('(')) {
       separator = '';
     } else {
       separator = ' ';
@@ -343,7 +342,7 @@ function stringifyRule (rule, context, nested = false) {
       return [unescapeIdent(declaration.property), ':', minifyValue(declaration)].join('');
     }).join(';');
     const renderedRules = subRules.map((childRule) => {
-      return stringifyRule(childRule, context, false);
+      return stringifyRule(childRule, context);
     }).join('');
     const children = [renderedDeclarations, renderedRules].filter(Boolean).join('');
     if (!children) {

package/src/value/color-mix.js

@@ -3,6 +3,7 @@
  */
 
 import {
+  convertOklchToHex,
   oklabToRgb,
   parseColor,
   rgbToOklab,
@@ -372,6 +373,11 @@ function evaluateColorMix (expr) {
     const C = lch1.C * t1 + lch2.C * t2;
     const H = interpolateHueShorter(lch1.H, lch2.H, t2);
     const alpha = (a1 * t1 + a2 * t2) * alphaMultiplier;
+    // In-gamut results have an exact sRGB equivalent, which is always shorter than oklch()
+    const hex = convertOklchToHex(L, C, H, alpha >= 1 ? 1 : alpha);
+    if (hex) {
+      return hex;
+    }
     return formatOklch(L, C, H, alpha);
   }
 

package/src/value/colors.js

@@ -508,6 +508,20 @@ function convertOklabToHex (L, a, b, alpha) {
   return rgbaToHex(r, g, bl, alpha !== undefined ? alpha : 1);
 }
 
+/**
+ * Convert a standalone oklch() value to hex if it fits in the sRGB gamut; returns null if out-of-gamut.
+ *
+ * @param  {number}      L      The OKLCH lightness component, 0 to 1.
+ * @param  {number}      C      The OKLCH chroma component.
+ * @param  {number}      H      The OKLCH hue angle in degrees.
+ * @param  {number}      alpha  The alpha value from 0 to 1.
+ * @return {string|null}        A hex color string, or null if the color is outside the sRGB gamut.
+ */
+function convertOklchToHex (L, C, H, alpha) {
+  const lab = oklchToOklab(L, C, H);
+  return convertOklabToHex(lab.L, lab.a, lab.b, alpha);
+}
+
 export {
   hslToRgbChannels,
   rgbaToHex,
@@ -517,6 +531,7 @@ export {
   parseHex,
   convertLabToHex,
   convertOklabToHex,
+  convertOklchToHex,
   shortestColor,
   srgbToOklab,
   oklabToSrgb,