purgetss 7.7.1 → 7.9.0

package/src/shared/helpers/utils.js

@@ -1,5 +1,6 @@
 import fs from 'fs'
 import _ from 'lodash'
+import { deriveAlphaKey } from '../semantic-helpers.js'
 
 // Internal variables and constants
 const _applyClasses = {}
@@ -530,15 +531,38 @@ export function compileApplyDirectives(twClasses) {
           const opacityIndex = findIndexOfClassName(`'.${opacityValue.classNameWithTransparency}`, twClassesArray)
 
           if (opacityIndex > -1) {
-            const defaultHexValue = (twClassesArray[opacityIndex].includes('from')) ? twClassesArray[opacityIndex].match(/#[0-9a-f]{6}/g)[1] : twClassesArray[opacityIndex].match(/#[0-9a-f]{6}/i)[0]
-            const classWithoutDecimalOpacity = `${twClassesArray[opacityIndex].replace(new RegExp(defaultHexValue.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'), 'g'), `#${opacityValue.transparency}${defaultHexValue.substring(1)}`)}`
+            const targetLine = twClassesArray[opacityIndex]
+            const hexMatches = targetLine.match(/#[0-9a-f]{6}/gi)
+
+            if (!hexMatches || (targetLine.includes('from') && hexMatches.length < 2)) {
+              const derivedLine = tryDeriveSemanticOpacity(targetLine, opacityValue.decimalValue)
+              if (derivedLine) {
+                compoundClasses.push(justProperties(derivedLine))
+                return
+              }
+              throw new Error(
+                `Opacity "/${opacityValue.decimalValue}" can't apply to semantic color ".${opacityValue.classNameWithTransparency}" (in apply of "${className}"). Use a PurgeTSS built-in color, an arbitrary value bg-(#AARRGGBB), or set alpha via "purgetss semantic --single ... --alpha ${opacityValue.decimalValue}".`
+              )
+            }
+
+            const defaultHexValue = targetLine.includes('from') ? hexMatches[1] : hexMatches[0]
+            const classWithoutDecimalOpacity = `${targetLine.replace(new RegExp(defaultHexValue.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'), 'g'), `#${opacityValue.transparency}${defaultHexValue.substring(1)}`)}`
 
             compoundClasses.push(justProperties(classWithoutDecimalOpacity))
           }
         })
       }
 
-      twClassesArray[indexOfModifier] = _.replace(twClassesArray[indexOfModifier], /{_applyProperties_}/, fixDuplicateKeys(compoundClasses).join(', '))
+      let mergedProperties
+      try {
+        mergedProperties = fixDuplicateKeys(compoundClasses).join(', ')
+      } catch (mergeError) {
+        const classList = [...values].join(' ')
+        throw new Error(
+          `Failed to merge apply directive of "${className}".\n   Classes: "${classList}".\n   Hint: this usually means an unsupported combination — e.g. "bg-gradient-to-X" together with "from-X to-Y" in the same apply (gradient direction is dropped on merge), or two utilities that map to the same property in incompatible shapes. Try splitting the rule or removing one of the conflicting classes.\n   Internal: ${mergeError.message}`
+        )
+      }
+      twClassesArray[indexOfModifier] = _.replace(twClassesArray[indexOfModifier], /{_applyProperties_}/, mergedProperties)
       twClassesArray[indexOfModifier] = deduplicateLineProperties(twClassesArray[indexOfModifier])
     }
   })
@@ -546,6 +570,26 @@ export function compileApplyDirectives(twClasses) {
   return twClassesArray.join('\n')
 }
 
+// Attempt to derive an alpha-applied semantic key from a TSS line whose value
+// is a semantic name (e.g. `'.bg-surface': { backgroundColor: 'surfaceColor' }`).
+// Returns the rewritten line with the derived key in place of the base name,
+// or `null` when no candidate matches an entry in semantic.colors.json.
+// Conflict errors from `deriveAlphaKey` propagate naturally.
+function tryDeriveSemanticOpacity(targetLine, alphaPercent) {
+  const bodyMatch = targetLine.match(/\{([^}]*)\}/)
+  if (!bodyMatch) return null
+  const candidates = (bodyMatch[1].match(/'([^']+)'/g) || [])
+    .map(m => m.slice(1, -1))
+    .filter(v => !v.startsWith('#'))
+  for (const candidate of candidates) {
+    const derivedKey = deriveAlphaKey(candidate, alphaPercent)
+    if (derivedKey) {
+      return targetLine.replace(new RegExp(`'${candidate}'`, 'g'), `'${derivedKey}'`)
+    }
+  }
+  return null
+}
+
 /**
  * Remove duplicate property keys in a TSS line, keeping the last occurrence.
  * This ensures apply directives override static defaults (e.g. backgroundColor).
@@ -593,13 +637,20 @@ export function justProperties(_foundClass) {
 
 export function formatArbitraryValues(arbitraryValue, fromXMLs = false) {
   const sign = (arbitraryValue.startsWith('-')) ? '-' : ''
-  const splitedContent = (arbitraryValue.startsWith('-')) ? arbitraryValue.substring(1).split('-') : arbitraryValue.split('-')
+  const stripped = sign ? arbitraryValue.substring(1) : arbitraryValue
 
-  if (splitedContent.length === 1) {
-    return ''
-  } else if (splitedContent.length === 2) {
-    let rule = splitedContent.slice(0, 1).join('-')
-    let value = splitedContent[1].match(/(?<=\().*(?=\))/).pop()
+  // Extract the value inside the last (...) so a negative value like top-(-10)
+  // is not mis-split by the hyphen inside the parentheses.
+  const parenMatch = stripped.match(/^(.+)-\(([^()]*)\)$/)
+  if (!parenMatch || parenMatch[2].trim() === '') {
+    return (fromXMLs) ? `// Property not yet supported: ${arbitraryValue}` : null
+  }
+
+  const ruleParts = parenMatch[1].split('-')
+  let value = parenMatch[2]
+
+  if (ruleParts.length === 1) {
+    let rule = ruleParts[0]
 
     if (rule === 'text') {
       rule = (value.includes('#') || value.includes('rgb')) ? 'text-color' : 'text-size'
@@ -630,13 +681,12 @@ export function formatArbitraryValues(arbitraryValue, fromXMLs = false) {
         ? `'.${arbitraryValue}': { ` + _.replace(properties, /{value}/g, parseValue(value, sign)) + ' }'
         : _.replace(properties, /{value}/g, parseValue(value, sign))
     }
-  } else if (splitedContent.length === 3) {
-    const rule = splitedContent.slice(0, 2).join('-')
-    const value = splitedContent[2].match(/(?<=\().*(?=\))/).pop()
+  } else if (ruleParts.length === 2) {
+    const rule = ruleParts.join('-')
     let properties = arbitraryValuesTable[rule]
 
     if (properties) {
-      if (splitedContent[0] === 'rounded') {
+      if (ruleParts[0] === 'rounded') {
         if (!value.includes(',')) {
           properties = _.replace(properties, /{value1}/g, parseValue(parseValue(value) / 2, sign))
         } else {
@@ -651,9 +701,8 @@ export function formatArbitraryValues(arbitraryValue, fromXMLs = false) {
         ? `'.${arbitraryValue}': { ` + _.replace(properties, /{value}/g, parseValue(value, sign)) + ' }'
         : _.replace(properties, /{value}/g, parseValue(value, sign))
     }
-  } else if (splitedContent.length === 4) {
-    const rule = splitedContent.slice(0, 3).join('-')
-    const value = splitedContent[3].match(/(?<=\().*(?=\))/).pop()
+  } else if (ruleParts.length === 3) {
+    const rule = ruleParts.join('-')
     let properties = arbitraryValuesTable[rule]
 
     if (properties) {
@@ -665,9 +714,8 @@ export function formatArbitraryValues(arbitraryValue, fromXMLs = false) {
         ? `'.${arbitraryValue}': { ` + _.replace(properties, /{value}/g, parseValue(value, sign)) + ' }'
         : _.replace(properties, /{value}/g, parseValue(value, sign))
     }
-  } else if (splitedContent.length === 5) {
-    const rule = splitedContent.slice(0, 4).join('-')
-    const value = splitedContent[4].match(/(?<=\().*(?=\))/).pop()
+  } else if (ruleParts.length === 4) {
+    const rule = ruleParts.join('-')
     const properties = arbitraryValuesTable[rule]
 
     if (properties) {
@@ -726,13 +774,22 @@ export function fixDuplicateKeys(compoundClasses) {
   const cleanedStyles = []
   const paddingObject = []
   const backgroundGradientObject = []
+  const backgroundGradientDirection = []
 
   _.each(compoundClasses, value => {
     if (compoundClasses.length > 1) {
       if (value.includes('font:')) {
         fontObject.push(value.replace('font: ', '').replace(/{(.*)}/, '$1').trim())
-      } else if (value.includes('backgroundGradient: { colors')) {
-        backgroundGradientObject.push(value.replace('backgroundGradient: ', '').replace(/{(.*)}/, '$1').trim())
+      } else if (value.includes('backgroundGradient:')) {
+        // Split into 2 buckets: colors (from-X/to-X) vs direction (bg-gradient-to-X with type/startPoint/endPoint).
+        // Both share the same property name `backgroundGradient` so they MUST be merged into a single object,
+        // otherwise the later one overwrites the earlier one in the emitted JS object literal.
+        const inner = value.replace('backgroundGradient: ', '').replace(/{(.*)}/, '$1').trim()
+        if (inner.startsWith('colors')) {
+          backgroundGradientObject.push(inner)
+        } else {
+          backgroundGradientDirection.push(inner)
+        }
       } else if (value.includes('padding:')) {
         paddingObject.push(value.replace('padding: ', '').replace(/{(.*)}/, '$1').trim())
       } else {
@@ -763,13 +820,28 @@ export function fixDuplicateKeys(compoundClasses) {
     cleanedStyles.push(`font: { ${fontObject.sort().join(', ')} }`)
   }
 
-  if (backgroundGradientObject.length === 1) {
-    cleanedStyles.push(`backgroundGradient: { ${backgroundGradientObject} }`)
-  } else if (backgroundGradientObject.length === 2) {
-    const toColor = backgroundGradientObject[1].replace('colors: ', '').replace(/[[\]']+/g, '').trim().split(',')
-    const fromToColors = backgroundGradientObject[0].replace('colors: ', '').replace(/[[\]']+/g, '').trim().split(',')
-    fromToColors[0] = toColor[0]
-    cleanedStyles.push(`backgroundGradient: { colors: [ '${fromToColors[0]}', '${fromToColors[1].trim()}' ] }`)
+  // Merge gradient direction (bg-gradient-to-X) and gradient colors (from-X/to-X)
+  // into a single backgroundGradient object. They share the same property name,
+  // so emitting them as separate entries causes the later one to overwrite the earlier.
+  if (backgroundGradientDirection.length || backgroundGradientObject.length) {
+    let colorsPart = ''
+    if (backgroundGradientObject.length === 1) {
+      colorsPart = backgroundGradientObject[0]
+    } else if (backgroundGradientObject.length === 2) {
+      // from-X emits 2 colors (placeholder + actual), to-X emits 1.
+      // After sort() above, indices may swap depending on color name ordering,
+      // so identify by array length instead of position.
+      const colorsA = backgroundGradientObject[0].replace('colors: ', '').replace(/[[\]']+/g, '').trim().split(',').map(c => c.trim())
+      const colorsB = backgroundGradientObject[1].replace('colors: ', '').replace(/[[\]']+/g, '').trim().split(',').map(c => c.trim())
+      const fromEntry = colorsA.length === 2 ? colorsA : colorsB
+      const toEntry = colorsA.length === 1 ? colorsA : colorsB
+      colorsPart = `colors: [ '${toEntry[0]}', '${fromEntry[1]}' ]`
+    }
+
+    const parts = []
+    if (backgroundGradientDirection.length) parts.push(backgroundGradientDirection[0])
+    if (colorsPart) parts.push(colorsPart)
+    cleanedStyles.push(`backgroundGradient: { ${parts.join(', ')} }`)
   }
 
   // Missing properties to process

package/src/shared/semantic-helpers.js

@@ -0,0 +1,143 @@
+/**
+ * PurgeTSS - Semantic Colors Helpers
+ *
+ * Auto-derivation of semantic color keys with applied alpha for opacity
+ * modifiers (e.g. `bg-surface/65`). Mutates `semantic.colors.json` idempotently
+ * by adding `<originalKey>_<alphaPercent>` entries with `{ color, alpha }` for
+ * `light` and `dark`.
+ *
+ * Lifecycle:
+ *   - Names of semantic colors are tracked via `registerSemanticName()` while
+ *     the utilities builder expands `theme.extend.colors`.
+ *   - Hooks in `tailwind-purger` and `compileApplyDirectives` call
+ *     `deriveAlphaKey()` before falling back to warn/throw on missing hex.
+ *   - CLI commands flush the cached JSON to disk via `flushSemanticColors()`
+ *     at the end of their run.
+ *
+ * @fileoverview Semantic color auto-derivation for opacity modifiers
+ * @since 7.9.0
+ */
+
+import fs from 'fs'
+import { getSemanticColorsPath } from '../cli/utils/project-detection.js'
+
+const _semanticNames = new Set()
+let _cache = null
+let _dirty = false
+let _lastMtime = 0
+let _lastPath = null
+
+/**
+ * Reset all in-memory state. Intended for tests; not part of the public API.
+ */
+export function _resetSemanticHelpersState() {
+  _semanticNames.clear()
+  _cache = null
+  _dirty = false
+  _lastMtime = 0
+  _lastPath = null
+}
+
+/**
+ * Track a name that resolves to a semantic color (string, non-hex). Called by
+ * the utilities builder while expanding `theme.extend.colors`.
+ *
+ * @param {string} name
+ */
+export function registerSemanticName(name) {
+  if (typeof name === 'string' && name.length > 0) _semanticNames.add(name)
+}
+
+/**
+ * @param {string} name
+ * @returns {boolean}
+ */
+export function isSemanticColorName(name) {
+  return _semanticNames.has(name)
+}
+
+/**
+ * Load `semantic.colors.json` for the current project. Cached by mtime so
+ * repeated calls in the same build are cheap. The cache is invalidated when
+ * the file mtime changes on disk (relevant for watch-mode cycles where the
+ * JSON gets rewritten between runs).
+ *
+ * @returns {Object} parsed JSON, or `{}` when the file doesn't exist
+ */
+export function loadSemanticColors() {
+  const p = getSemanticColorsPath()
+  if (!fs.existsSync(p)) {
+    _cache = {}
+    _lastMtime = 0
+    _lastPath = p
+    return _cache
+  }
+  const mtime = fs.statSync(p).mtimeMs
+  if (_cache && _lastPath === p && mtime === _lastMtime) return _cache
+  _cache = JSON.parse(fs.readFileSync(p, 'utf8'))
+  _lastMtime = mtime
+  _lastPath = p
+  return _cache
+}
+
+/**
+ * Derive a semantic key with the requested alpha applied. Idempotent: if the
+ * derived key already exists with matching values it's reused; if it exists
+ * with conflicting values an Error is thrown so manual edits aren't silently
+ * overwritten.
+ *
+ * @param {string} baseKey - The original semantic key (e.g. `surfaceColor`).
+ * @param {number|string} alphaPercent - Integer 0..100 (e.g. 65).
+ * @returns {string|null} The derived key, or `null` if `baseKey` isn't in the JSON.
+ */
+export function deriveAlphaKey(baseKey, alphaPercent) {
+  const semantic = loadSemanticColors()
+  const base = semantic[baseKey]
+  if (!base) return null
+
+  const alphaStr = String(alphaPercent)
+  const newKey = `${baseKey}_${alphaStr}`
+
+  const lightHex = typeof base.light === 'string' ? base.light : base.light?.color
+  const darkHex = typeof base.dark === 'string' ? base.dark : base.dark?.color
+
+  if (semantic[newKey]) {
+    const existing = semantic[newKey]
+    const existingLightHex = typeof existing.light === 'string' ? existing.light : existing.light?.color
+    const existingDarkHex = typeof existing.dark === 'string' ? existing.dark : existing.dark?.color
+    const existingLightAlpha = typeof existing.light === 'string' ? null : existing.light?.alpha
+    const existingDarkAlpha = typeof existing.dark === 'string' ? null : existing.dark?.alpha
+
+    if (
+      existingLightHex !== lightHex ||
+      existingDarkHex !== darkHex ||
+      existingLightAlpha !== alphaStr ||
+      existingDarkAlpha !== alphaStr
+    ) {
+      throw new Error(
+        `Conflict: "${newKey}" already exists in semantic.colors.json with different values. Manual edit detected — resolve before continuing.`
+      )
+    }
+    return newKey
+  }
+
+  semantic[newKey] = {
+    light: { color: lightHex, alpha: alphaStr },
+    dark: { color: darkHex, alpha: alphaStr }
+  }
+  _dirty = true
+  return newKey
+}
+
+/**
+ * Persist any pending derivations back to `semantic.colors.json`. No-op when
+ * nothing changed. Writes a trailing newline for clean git diffs.
+ */
+export function flushSemanticColors() {
+  if (!_dirty) return
+  const p = getSemanticColorsPath()
+  fs.writeFileSync(p, JSON.stringify(_cache, null, 2) + '\n')
+  _dirty = false
+  _lastMtime = fs.statSync(p).mtimeMs
+  _lastPath = p
+}

package/src/dev/builders/tailwind-builder.js

@@ -1,26 +0,0 @@
-/**
- * PurgeTSS v7.1 - Tailwind Builder (Development)
- *
- * Builds Tailwind CSS files for development/distribution using auto-generation.
- * COPIED from lib/build-tailwind.js - NO CHANGES to logic.
- *
- * Generates: ./dist/utilities.tss
- *
- * @since 7.1.0 (refactored from lib/)
- * @author César Estrada
- */
-
-import { autoBuildUtilitiesTSS } from '../../../experimental/completions2.js'
-
-/**
- * Main builder function
- * COPIED exactly from original constructor() function
- */
-export function buildTailwind() {
-  autoBuildUtilitiesTSS()
-}
-
-// Execute if run directly
-if (import.meta.url === `file://${process.argv[1]}`) {
-  buildTailwind()
-}