tailwind-to-style 3.1.2 → 3.2.0

package/dist/core/tws.cjs

@@ -0,0 +1,984 @@
+/**
+ * tailwind-to-style v3.2.0
+ * Runtime Tailwind CSS to inline styles converter
+ * 
+ * @author Bigetion
+ * @license MIT
+ */
+'use strict';
+
+/**
+ * TailwindCache singleton for managing generated Tailwind CSS
+ * Replaces global state with proper encapsulation
+ */
+class TailwindCache {
+  constructor() {
+    this.twString = null;
+    this.cssObject = null;
+    this.initialized = false;
+  }
+
+  /**
+   * Get or generate the CSS object
+   * @param {Function} generateFn - Function to generate CSS string
+   * @param {Function} convertFn - Function to convert CSS string to object
+   * @returns {Object} CSS object lookup
+   */
+  getOrGenerate(generateFn, convertFn) {
+    if (!this.initialized) {
+      this.twString = generateFn().replace(/\s\s+/g, " ");
+      this.cssObject = convertFn(this.twString);
+      this.initialized = true;
+    }
+    return this.cssObject;
+  }
+
+  /**
+   * Get the CSS string
+   */
+  getCssString() {
+    return this.twString;
+  }
+
+  /**
+   * Get the CSS object
+   */
+  getCssObject() {
+    return this.cssObject;
+  }
+
+  /**
+   * Check if cache is initialized
+   */
+  isInitialized() {
+    return this.initialized;
+  }
+
+  /**
+   * Reset the cache (useful for testing)
+   */
+  reset() {
+    this.twString = null;
+    this.cssObject = null;
+    this.initialized = false;
+  }
+}
+
+// Singleton instance
+let instance = null;
+
+/**
+ * Get the TailwindCache singleton instance
+ * @returns {TailwindCache} The cache instance
+ */
+function getTailwindCache() {
+  if (!instance) {
+    instance = new TailwindCache();
+  }
+  return instance;
+}
+
+/**
+ * Logger class with configurable log levels
+ * Prevents console spam in production
+ */
+class Logger {
+  constructor() {
+    let level = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : "warn";
+    this.level = level;
+    this.levels = {
+      debug: 0,
+      info: 1,
+      warn: 2,
+      error: 3,
+      silent: 4
+    };
+  }
+
+  /**
+   * Set the log level
+   * @param {string} level - One of 'debug', 'info', 'warn', 'error', 'silent'
+   */
+  setLevel(level) {
+    if (this.levels[level] !== undefined) {
+      this.level = level;
+    }
+  }
+
+  /**
+   * Get current log level
+   */
+  getLevel() {
+    return this.level;
+  }
+
+  /**
+   * Check if a message should be logged
+   */
+  shouldLog(level) {
+    return this.levels[level] >= this.levels[this.level];
+  }
+
+  /**
+   * Log debug message
+   */
+  debug(message) {
+    if (this.shouldLog("debug")) {
+      for (var _len = arguments.length, args = new Array(_len > 1 ? _len - 1 : 0), _key = 1; _key < _len; _key++) {
+        args[_key - 1] = arguments[_key];
+      }
+      console.debug(`[twsx:debug] ${message}`, ...args);
+    }
+  }
+
+  /**
+   * Log info message
+   */
+  info(message) {
+    if (this.shouldLog("info")) {
+      for (var _len2 = arguments.length, args = new Array(_len2 > 1 ? _len2 - 1 : 0), _key2 = 1; _key2 < _len2; _key2++) {
+        args[_key2 - 1] = arguments[_key2];
+      }
+      console.info(`[twsx:info] ${message}`, ...args);
+    }
+  }
+
+  /**
+   * Log warning message
+   */
+  warn(message) {
+    if (this.shouldLog("warn")) {
+      for (var _len3 = arguments.length, args = new Array(_len3 > 1 ? _len3 - 1 : 0), _key3 = 1; _key3 < _len3; _key3++) {
+        args[_key3 - 1] = arguments[_key3];
+      }
+      console.warn(`[twsx:warn] ${message}`, ...args);
+    }
+  }
+
+  /**
+   * Log error message
+   */
+  error(message) {
+    if (this.shouldLog("error")) {
+      for (var _len4 = arguments.length, args = new Array(_len4 > 1 ? _len4 - 1 : 0), _key4 = 1; _key4 < _len4; _key4++) {
+        args[_key4 - 1] = arguments[_key4];
+      }
+      console.error(`[twsx:error] ${message}`, ...args);
+    }
+  }
+}
+
+// Create singleton instance with silent defaults
+// Can be enabled via TWSX_LOG_LEVEL environment variable
+let logLevel = "silent";
+try {
+  if (typeof process !== "undefined" && process && process.env) {
+    // Allow explicit log level override via environment variable
+    // e.g., TWSX_LOG_LEVEL=debug or TWSX_LOG_LEVEL=warn
+    logLevel = process.env.TWSX_LOG_LEVEL || "silent";
+  }
+} catch {
+  // Silently fail - in browser environment, default to silent
+  logLevel = "silent";
+}
+const logger = new Logger(logLevel);
+
+/**
+ * Custom error class for tailwind-to-style
+ */
+class TwsError extends Error {
+  constructor(message) {
+    let context = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : {};
+    super(message);
+    this.name = "TwsError";
+    this.context = context;
+    this.timestamp = new Date().toISOString();
+  }
+}
+
+/**
+ * Error event handlers
+ */
+const errorHandlers = new Set();
+
+/**
+ * Handle and broadcast errors
+ * @param {Error} error - The error that occurred
+ * @param {Object} context - Additional context about the error
+ */
+function handleError(error) {
+  let context = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : {};
+  const twsError = error instanceof TwsError ? error : new TwsError(error.message, context);
+
+  // Log the error
+  logger.error(twsError.message, twsError.context);
+
+  // Notify all registered handlers
+  errorHandlers.forEach(handler => {
+    try {
+      handler(twsError);
+    } catch (handlerError) {
+      logger.error("Error in error handler:", handlerError);
+    }
+  });
+  return twsError;
+}
+
+/**
+ * Performance Monitoring Utilities
+ * 
+ * Tracks and logs performance metrics for optimization analysis.
+ * 
+ * @module utils/performanceMonitor
+ */
+
+
+/**
+ * Performance monitoring system
+ * 
+ * Provides start/end timing and automatic slow operation logging.
+ */
+const performanceMonitor = {
+  enabled: typeof performance !== "undefined",
+  /**
+   * Start performance measurement
+   * 
+   * @param {string} label - Label for the measurement
+   * @returns {Object|null} Marker object with label and start time
+   */
+  start(label) {
+    if (!this.enabled) return null;
+    return {
+      label,
+      startTime: performance.now()
+    };
+  },
+  /**
+   * End performance measurement and log if slow
+   * 
+   * @param {Object} marker - Marker from start()
+   */
+  end(marker) {
+    if (!this.enabled || !marker) return;
+    const duration = performance.now() - marker.startTime;
+    if (duration > 5) {
+      // Only log if > 5ms
+      logger.warn(`Slow ${marker.label}: ${duration.toFixed(2)}ms`);
+    }
+  },
+  /**
+   * Measure function execution time
+   * 
+   * @param {Function} fn - Function to measure
+   * @param {string} label - Label for measurement
+   * @returns {*} Function result
+   */
+  measure(fn, label) {
+    const marker = this.start(label);
+    try {
+      const result = fn();
+      this.end(marker);
+      return result;
+    } catch (error) {
+      this.end(marker);
+      throw error;
+    }
+  }
+};
+
+/**
+ * Proper LRU (Least Recently Used) Cache implementation
+ * Efficiently manages memory by removing least recently used items
+ */
+class LRUCache {
+  constructor() {
+    let maxSize = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : 1000;
+    this.maxSize = maxSize;
+    this.cache = new Map();
+  }
+
+  /**
+   * Get value from cache
+   * Updates the item as most recently used
+   */
+  get(key) {
+    if (!this.cache.has(key)) {
+      return undefined;
+    }
+    const value = this.cache.get(key);
+    // Move to end (most recently used)
+    this.cache.delete(key);
+    this.cache.set(key, value);
+    return value;
+  }
+
+  /**
+   * Set value in cache
+   * Removes least recently used item if cache is full
+   */
+  set(key, value) {
+    // If key exists, delete it first to update position
+    if (this.cache.has(key)) {
+      this.cache.delete(key);
+    } else if (this.cache.size >= this.maxSize) {
+      // Remove least recently used (first item)
+      const firstKey = this.cache.keys().next().value;
+      this.cache.delete(firstKey);
+    }
+    this.cache.set(key, value);
+  }
+
+  /**
+   * Check if key exists in cache
+   */
+  has(key) {
+    return this.cache.has(key);
+  }
+
+  /**
+   * Clear all cache entries
+   */
+  clear() {
+    this.cache.clear();
+  }
+
+  /**
+   * Get current cache size
+   */
+  get size() {
+    return this.cache.size;
+  }
+
+  /**
+   * Delete specific key
+   */
+  delete(key) {
+    return this.cache.delete(key);
+  }
+}
+
+/**
+ * Pre-compiled Regex Constants and Configuration
+ * 
+ * Pre-compiling regex patterns provides 50-100x performance improvement
+ * by avoiding repeated regex object creation in hot code paths.
+ * 
+ * @module core/constants
+ */
+
+// ============================================================================
+// CLASS PARSING
+// ============================================================================
+
+/** Regex for parsing Tailwind class names (includes . for decimal values like p-0.5) */
+const CLASS_PARSER_REGEX = /[\w.\-\/]+(?:\/\d+)?(?:\[[^\]]+\])?/g;
+
+// ============================================================================
+// OPACITY MODIFIERS
+// ============================================================================
+
+/** Regex for extracting opacity modifiers (e.g., /50 in text-red-500/50) */
+const OPACITY_MODIFIER_REGEX = /\/(\d+)$/;
+
+/** Pre-compiled regex patterns for opacity CSS custom properties */
+const OPACITY_PROP_REGEXES = {
+  "--text-opacity": /--text-opacity\s*:\s*[\d.]+/gi,
+  "--bg-opacity": /--bg-opacity\s*:\s*[\d.]+/gi,
+  "--border-opacity": /--border-opacity\s*:\s*[\d.]+/gi,
+  "--ring-opacity": /--ring-opacity\s*:\s*[\d.]+/gi,
+  "--divide-opacity": /--divide-opacity\s*:\s*[\d.]+/gi,
+  "--placeholder-opacity": /--placeholder-opacity\s*:\s*[\d.]+/gi,
+  "--text-decoration-opacity": /--text-decoration-opacity\s*:\s*[\d.]+/gi,
+  "--outline-opacity": /--outline-opacity\s*:\s*[\d.]+/gi,
+  "--accent-opacity": /--accent-opacity\s*:\s*[\d.]+/gi,
+  "--caret-opacity": /--caret-opacity\s*:\s*[\d.]+/gi
+};
+
+/** Regex for CSS declarations */
+const CSS_SEMICOLON_SPLIT_REGEX = /;/;
+const CSS_COLON_SPLIT_REGEX = /:/;
+
+// ============================================================================
+// CSS VARIABLE RESOLUTION
+// ============================================================================
+
+/** Regex for CSS custom property (var) resolution — supports nested parens in fallback (e.g. rgba(...)) */
+const CSS_VAR_REGEX = /var\((--[\w-]+)(?:,\s*((?:[^()]+|\([^()]*\))*))?\)/g;
+const CAMEL_CASE_REGEX = /-([a-z])/g;
+
+// ============================================================================
+// CUSTOM CLASS DETECTION
+// ============================================================================
+
+/** Regex for arbitrary value detection (e.g., w-[123px]) */
+const CUSTOM_VALUE_BRACKET_REGEX = /\[([^\]]+)\]/;
+
+// ============================================================================
+// COLOR PROPERTIES
+// ============================================================================
+
+/** List of CSS properties that accept color values */
+const COLOR_PROPERTIES = ["color", "background-color", "border-color", "text-decoration-color", "outline-color", "fill", "stroke", "caret-color", "accent-color"];
+
+/**
+ * Pre-compiled regex patterns for each color property
+ * Used in opacity modifier processing for 50-100x performance improvement
+ */
+const COLOR_REGEX_PATTERNS = new Map();
+for (const prop of COLOR_PROPERTIES) {
+  const escapedProp = prop.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  COLOR_REGEX_PATTERNS.set(prop, {
+    rgb: new RegExp(`(${escapedProp}\\s*:\\s*)rgb\\((\\d+),\\s*(\\d+),\\s*(\\d+)\\)`, "gi"),
+    rgba: new RegExp(`(${escapedProp}\\s*:\\s*)rgba\\((\\d+),\\s*(\\d+),\\s*(\\d+),\\s*[\\d.]+\\)`, "gi"),
+    hsl: new RegExp(`(${escapedProp}\\s*:\\s*)hsl\\((\\d+),\\s*([\\d.]+%),\\s*([\\d.]+%)\\)`, "gi"),
+    hsla: new RegExp(`(${escapedProp}\\s*:\\s*)hsla\\((\\d+),\\s*([\\d.]+%),\\s*([\\d.]+%),\\s*[\\d.]+\\)`, "gi"),
+    hex: new RegExp(`(${escapedProp}\\s*:\\s*)(#[0-9a-fA-F]{3,6})`, "gi")
+  });
+}
+
+// ============================================================================
+// TAILWIND CONFIGURATION
+// ============================================================================
+
+/** Fraction denominators supported in Tailwind (for w-1/2, h-2/3, etc.) */
+const FRACTION_DENOMINATORS = [2, 3, 4, 5, 6, 12];
+
+/** Prefixes that support fractional values */
+const FRACTION_PREFIXES = ["w-", "h-", "max-w-", "max-h-", "min-w-", "min-h-", "top-", "bottom-", "left-", "right-", "inset-", "inset-x-", "inset-y-", "translate-x-", "translate-y-", "rounded-t-", "rounded-b-", "rounded-l-", "rounded-r-", "rounded-bl-", "rounded-br-", "rounded-tl-", "rounded-tr-", "flex-basis-", "z-"];
+
+/**
+ * CSS Resolution Utilities
+ * 
+ * Handles CSS custom property (var) resolution, CSS declaration parsing,
+ * and conversion between different CSS formats.
+ * 
+ * @module css/resolver
+ */
+
+
+// Cache for CSS resolution
+const cssResolutionCache = new LRUCache(1000);
+
+/**
+ * Resolve all CSS custom properties (var) in a CSS string
+ * 
+ * Optimized with for loops and indexOf for 2-3x better performance.
+ * Converts CSS with custom properties to clear CSS with resolved values.
+ * 
+ * @param {string} cssString - CSS string with potential var() references
+ * @returns {string} Resolved CSS string (e.g., 'color: rgba(255,255,255,1); background: #fff;')
+ * 
+ * @example
+ * resolveCssToClearCss('color: var(--text-color); --text-color: red;')
+ * // Returns: 'color: red;'
+ */
+function resolveCssToClearCss(cssString) {
+  const customVars = {};
+  const props = {};
+
+  // Split by semicolon and process declarations
+  const declarations = cssString.split(CSS_SEMICOLON_SPLIT_REGEX);
+  for (let i = 0; i < declarations.length; i++) {
+    const decl = declarations[i];
+    if (!decl) continue;
+    const colonIndex = decl.indexOf(":");
+    if (colonIndex === -1) continue;
+    const key = decl.substring(0, colonIndex).trim();
+    const value = decl.substring(colonIndex + 1).trim();
+    if (!key || !value) continue;
+    if (key.startsWith("--")) {
+      customVars[key] = value;
+    } else {
+      props[key] = value;
+    }
+  }
+
+  // Replace var(--foo) in all values using pre-compiled regex
+  const propKeys = Object.keys(props);
+  for (let i = 0; i < propKeys.length; i++) {
+    const key = propKeys[i];
+    let val = props[key];
+    if (val.includes("var(")) {
+      CSS_VAR_REGEX.lastIndex = 0;
+      val = val.replace(CSS_VAR_REGEX, (m, varName) => customVars[varName] !== undefined ? customVars[varName] : m);
+      props[key] = val;
+    }
+  }
+
+  // Build CSS string - INCLUDE CSS variables so they can be resolved later
+  let result = "";
+  const varKeys = Object.keys(customVars);
+  for (let i = 0; i < varKeys.length; i++) {
+    const key = varKeys[i];
+    result += `${key}: ${customVars[key]}; `;
+  }
+  for (let i = 0; i < propKeys.length; i++) {
+    const key = propKeys[i];
+    result += `${key}: ${props[key]}; `;
+  }
+  return result.trim();
+}
+
+/**
+ * Separate and resolve CSS declarations with custom property resolution
+ * 
+ * Enhanced with caching and better error handling for production use.
+ * 
+ * @param {string[]} arr - Array of CSS declaration strings
+ * @returns {string} Resolved CSS string with all variables replaced
+ * 
+ * @example
+ * separateAndResolveCSS(['color: var(--text); --text: blue;', 'margin: 1rem;'])
+ * // Returns: 'color: blue; margin: 1rem;'
+ */
+function separateAndResolveCSS(arr) {
+  try {
+    // Fix: cacheKey must be unique for each input array
+    const cacheKey = Array.isArray(arr) ? arr.join("|") : String(arr);
+    if (cssResolutionCache.has(cacheKey)) {
+      return cssResolutionCache.get(cacheKey);
+    }
+
+    // Process CSS resolution
+    const cssProperties = {};
+    for (let i = 0; i < arr.length; i++) {
+      const item = arr[i];
+      if (!item) continue;
+      try {
+        const declarations = item.split(CSS_SEMICOLON_SPLIT_REGEX);
+        for (let j = 0; j < declarations.length; j++) {
+          const decl = declarations[j].trim();
+          if (!decl) continue;
+          const colonIndex = decl.indexOf(":");
+          if (colonIndex === -1) continue;
+          const prop = decl.substring(0, colonIndex).trim();
+          const value = decl.substring(colonIndex + 1).trim();
+          if (!prop || !value) continue;
+
+          // Keep 3-stop gradient (with via) — don't let from/to overwrite it
+          if (prop === "--gradient-color-stops" && cssProperties[prop] && cssProperties[prop].includes("--gradient-via-color") && !value.includes("--gradient-via-color")) {
+            continue;
+          }
+          cssProperties[prop] = value;
+        }
+      } catch (error) {
+        logger.warn("Error processing CSS declaration:", item, error);
+      }
+    }
+    const resolvedProperties = {
+      ...cssProperties
+    };
+
+    /**
+     * Optimized CSS variable resolution using regex-based approach
+     * 2-3x faster than manual char-by-char parsing
+     * Handles nested var() with fallback values
+     */
+    const resolveValue = function (value, variables) {
+      let maxDepth = arguments.length > 2 && arguments[2] !== undefined ? arguments[2] : 10;
+      if (!value || !value.includes("var(") || maxDepth <= 0) return value;
+      try {
+        let resolved = value;
+
+        // Iteratively resolve variables until no more changes or max depth reached
+        for (let depth = 0; depth < maxDepth; depth++) {
+          let changed = false;
+          CSS_VAR_REGEX.lastIndex = 0;
+          resolved = resolved.replace(CSS_VAR_REGEX, (match, varName, fallback) => {
+            // Check if variable exists in our resolved properties
+            if (variables[varName] !== undefined) {
+              changed = true;
+              return variables[varName];
+            }
+
+            // If fallback is provided, use it
+            if (fallback !== undefined) {
+              changed = true;
+              return fallback.trim();
+            }
+
+            // Keep the var() reference if not found
+            return match;
+          });
+
+          // If nothing changed, we're done
+          if (!changed) break;
+        }
+        return resolved;
+      } catch (error) {
+        logger.warn("Error resolving CSS variable:", value, error);
+        return value;
+      }
+    };
+
+    // Resolve variables recursively - multiple passes with optimized loop
+    let maxPasses = 5;
+    let hasUnresolved = true;
+    while (hasUnresolved && maxPasses-- > 0) {
+      hasUnresolved = false;
+      const propKeys = Object.keys(resolvedProperties);
+      for (let i = 0; i < propKeys.length; i++) {
+        const key = propKeys[i];
+        const resolved = resolveValue(resolvedProperties[key], resolvedProperties);
+        if (resolved !== resolvedProperties[key]) {
+          resolvedProperties[key] = resolved;
+          hasUnresolved = true;
+        }
+      }
+    }
+
+    // Remove CSS variables after resolution using optimized loop
+    const allKeys = Object.keys(resolvedProperties);
+    for (let i = 0; i < allKeys.length; i++) {
+      const key = allKeys[i];
+      if (key.startsWith("--")) {
+        delete resolvedProperties[key];
+      }
+    }
+
+    // Build result string with optimized loop (faster than map/join)
+    let result = "";
+    const finalKeys = Object.keys(resolvedProperties);
+    for (let i = 0; i < finalKeys.length; i++) {
+      const key = finalKeys[i];
+      result += `${key}: ${resolvedProperties[key]}; `;
+    }
+    result = result.trim();
+    cssResolutionCache.set(cacheKey, result);
+    return result;
+  } catch (error) {
+    logger.error("Critical error in CSS resolution:", error);
+    return "";
+  }
+}
+
+/**
+ * Convert inline CSS string to JavaScript object with camelCase properties
+ * 
+ * Resolves CSS custom properties recursively before conversion.
+ * 
+ * @param {string} styleString - Inline CSS string (e.g., 'color: red; margin: 1rem;')
+ * @returns {Object} Style object with camelCase keys
+ * 
+ * @example
+ * inlineStyleToJson('color: red; font-size: 16px;')
+ * // Returns: { color: 'red', fontSize: '16px' }
+ */
+function inlineStyleToJson(styleString) {
+  const styles = styleString.split(CSS_SEMICOLON_SPLIT_REGEX).filter(style => style.trim() !== "");
+  const styleObject = {};
+  const cssVariables = {};
+
+  // First pass: collect CSS variables
+  for (let i = 0; i < styles.length; i++) {
+    const parts = styles[i].split(CSS_COLON_SPLIT_REGEX, 2);
+    if (parts.length !== 2) continue;
+    const key = parts[0].trim();
+    const value = parts[1].trim();
+    if (key && key.startsWith("--")) {
+      cssVariables[key] = value;
+    }
+  }
+
+  // Helper to resolve CSS variables recursively
+  const resolveVariables = value => {
+    if (!value || !value.includes("var(")) return value;
+    let resolved = value;
+    let maxIterations = 10; // Prevent infinite loops
+
+    while (resolved.includes("var(") && maxIterations-- > 0) {
+      CSS_VAR_REGEX.lastIndex = 0; // Reset global regex
+      resolved = resolved.replace(CSS_VAR_REGEX, (match, variable, fallback) => {
+        return cssVariables[variable] || fallback || match;
+      });
+    }
+    return resolved;
+  };
+
+  // Second pass: create style object with resolved values
+  for (let i = 0; i < styles.length; i++) {
+    const parts = styles[i].split(CSS_COLON_SPLIT_REGEX, 2);
+    if (parts.length !== 2) continue;
+    const key = parts[0].trim();
+    const value = parts[1].trim();
+    if (key && value && !key.startsWith("--")) {
+      const camelCaseKey = key.replace(CAMEL_CASE_REGEX, (_, letter) => letter.toUpperCase());
+      styleObject[camelCaseKey] = resolveVariables(value);
+    }
+  }
+  return styleObject;
+}
+
+/**
+ * CSS Parser Utilities
+ * 
+ * Handles parsing of Tailwind class names, opacity modifiers,
+ * bracket value encoding/decoding, and custom value extraction.
+ * 
+ * @module css/parser
+ */
+
+
+/**
+ * Process opacity modifier from class name
+ * 
+ * Converts opacity modifiers (e.g., text-red-500/50) to actual CSS opacity values.
+ * Handles rgb, rgba, hsl, hsla, and hex color formats.
+ * 
+ * @param {string} className - Class name with potential opacity modifier
+ * @param {string} cssDeclaration - CSS declaration to modify
+ * @returns {string} Modified CSS declaration with opacity applied
+ * 
+ * @example
+ * processOpacityModifier('text-red-500/50', 'color: rgb(239, 68, 68);')
+ * // Returns: 'color: rgba(239, 68, 68, 0.5);'
+ */
+function processOpacityModifier(className, cssDeclaration) {
+  const opacityMatch = OPACITY_MODIFIER_REGEX.exec(className);
+  if (!opacityMatch) return cssDeclaration;
+  const opacityValue = parseInt(opacityMatch[1], 10);
+  if (opacityValue < 0 || opacityValue > 100) return cssDeclaration;
+  const alphaValue = (opacityValue / 100).toString();
+
+  // Handle Tailwind's CSS custom property pattern
+  let modifiedDeclaration = cssDeclaration;
+
+  // Replace opacity custom properties using pre-compiled regexes
+  for (const prop in OPACITY_PROP_REGEXES) {
+    const regex = OPACITY_PROP_REGEXES[prop];
+    regex.lastIndex = 0; // Reset global regex
+    modifiedDeclaration = modifiedDeclaration.replace(regex, `${prop}: ${alphaValue}`);
+  }
+
+  // Also handle direct color values using pre-compiled regex patterns
+  for (const prop of COLOR_PROPERTIES) {
+    const patterns = COLOR_REGEX_PATTERNS.get(prop);
+    if (!patterns) continue;
+
+    // Reset all regex lastIndex for reuse
+    patterns.rgb.lastIndex = 0;
+    patterns.rgba.lastIndex = 0;
+    patterns.hsl.lastIndex = 0;
+    patterns.hsla.lastIndex = 0;
+    patterns.hex.lastIndex = 0;
+
+    // Convert rgb to rgba with opacity
+    modifiedDeclaration = modifiedDeclaration.replace(patterns.rgb, `$1rgba($2, $3, $4, ${alphaValue})`);
+
+    // Update existing rgba opacity
+    modifiedDeclaration = modifiedDeclaration.replace(patterns.rgba, `$1rgba($2, $3, $4, ${alphaValue})`);
+
+    // Convert hsl to hsla with opacity
+    modifiedDeclaration = modifiedDeclaration.replace(patterns.hsl, `$1hsla($2, $3, $4, ${alphaValue})`);
+
+    // Update existing hsla opacity
+    modifiedDeclaration = modifiedDeclaration.replace(patterns.hsla, `$1hsla($2, $3, $4, ${alphaValue})`);
+
+    // Handle hex colors - convert to rgba
+    modifiedDeclaration = modifiedDeclaration.replace(patterns.hex, (match, propPart, hexColor) => {
+      // Convert hex to rgba
+      const hex = hexColor.replace("#", "");
+      let r, g, b;
+      if (hex.length === 3) {
+        r = parseInt(hex[0] + hex[0], 16);
+        g = parseInt(hex[1] + hex[1], 16);
+        b = parseInt(hex[2] + hex[2], 16);
+      } else {
+        r = parseInt(hex.substring(0, 2), 16);
+        g = parseInt(hex.substring(2, 4), 16);
+        b = parseInt(hex.substring(4, 6), 16);
+      }
+      return `${propPart}rgba(${r}, ${g}, ${b}, ${alphaValue})`;
+    });
+  }
+  return modifiedDeclaration;
+}
+
+/**
+ * TWS Core - Tailwind to Style Converter
+ * 
+ * Main function for converting Tailwind class names to inline styles or JSON objects.
+ * 
+ * @module core/tws
+ */
+
+
+/**
+ * Convert Tailwind class string to inline CSS styles or JSON object
+ * 
+ * Supports all Tailwind utilities including:
+ * - Responsive variants (sm:, md:, lg:, xl:, 2xl:)
+ * - Pseudo-state variants (hover:, focus:, active:, etc.)
+ * - Opacity modifiers (text-red-500/50)
+ * - Arbitrary values (w-[123px], text-[#abc])
+ * - Important modifier (!bg-red-500)
+ * 
+ * @param {string} classNames - String containing Tailwind classes to convert
+ * @param {boolean} convertToJson - If true, returns JSON object; if false, returns CSS string
+ * @returns {string|Object} Inline CSS string or style JSON object
+ * 
+ * @example
+ * // CSS string output
+ * tws('bg-blue-500 text-white p-4')
+ * // Returns: 'background-color: rgb(59, 130, 246); color: rgb(255, 255, 255); padding: 1rem;'
+ * 
+ * @example
+ * // JSON object output
+ * tws('flex items-center gap-4', true)
+ * // Returns: { display: 'flex', alignItems: 'center', gap: '1rem' }
+ * 
+ * @example
+ * // Opacity modifiers
+ * tws('text-red-500/50')
+ * // Returns: 'color: rgba(239, 68, 68, 0.5);'
+ * 
+ * @example
+ * // Arbitrary values
+ * tws('w-[123px] text-[#abc]')
+ * // Returns: 'width: 123px; color: #abc;'
+ */
+function tws(classNames) {
+  let convertToJson = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : false;
+  const totalMarker = performanceMonitor.start("tws:total");
+  try {
+    // Get CSS object from singleton cache (auto-generates if needed)
+    const tailwindCache = getTailwindCache();
+    const cssObject = tailwindCache.getOrGenerate(
+      // generateFn and convertFn arehandled by tailwindCache
+    );
+
+    // Validate input
+    if (!classNames || typeof classNames !== "string" || classNames.trim() === "") {
+      performanceMonitor.end(totalMarker);
+      return convertToJson ? {} : "";
+    }
+
+    // Parse class names
+    let classes;
+    try {
+      const parseMarker = performanceMonitor.start("tws:parse");
+      CLASS_PARSER_REGEX.lastIndex = 0; // Reset global regex
+      classes = classNames.match(CLASS_PARSER_REGEX);
+      performanceMonitor.end(parseMarker);
+
+      // If no valid classes are found
+      if (!classes || classes.length === 0) {
+        logger.warn(`No valid Tailwind classes found in input: "${classNames}"`);
+        performanceMonitor.end(totalMarker);
+        return convertToJson ? {} : "";
+      }
+    } catch (error) {
+      logger.error(`Error parsing Tailwind classes: ${error.message}`);
+      performanceMonitor.end(totalMarker);
+      return convertToJson ? {} : "";
+    }
+
+    // Process classes with performance monitoring
+    const processMarker = performanceMonitor.start("tws:process");
+    let cssResult = classes.map(className => {
+      // Extract base class name without opacity modifier
+      // Only remove /digits if it's an opacity modifier (not a fraction like w-2/3)
+      // Opacity modifiers are typically /0-100, fractions are /2, /3, /4, /5, /6, /12
+      const opacityMatch = OPACITY_MODIFIER_REGEX.exec(className);
+      let baseClassName = className;
+      let hasOpacityModifier = false;
+      if (opacityMatch) {
+        const opacityValue = parseInt(opacityMatch[1], 10);
+        // If it's a valid opacity value (0-100), treat it as opacity modifier
+        if (opacityValue >= 0 && opacityValue <= 100) {
+          // Check if this could be a fraction (e.g., w-2/3, h-1/2)
+          // Fractions typically have denominators of 2, 3, 4, 5, 6, 12
+          const couldBeFraction = FRACTION_DENOMINATORS.includes(opacityValue) && FRACTION_PREFIXES.some(prefix => className.startsWith(prefix) || className.startsWith(`-${prefix}`));
+          if (!couldBeFraction) {
+            baseClassName = className.replace(/\/\d+$/, "");
+            hasOpacityModifier = true;
+          }
+        }
+      }
+      let result = cssObject[baseClassName] || cssObject[baseClassName.replace(/\//g, "\\/")] || cssObject[baseClassName.replace(/\./g, "\\.")];
+      if (result) {
+        // Apply opacity modifier if present
+        if (hasOpacityModifier && className.includes("/") && /\/\d+$/.test(className)) {
+          result = processOpacityModifier(className, result);
+        }
+        return resolveCssToClearCss(result);
+      } else if (baseClassName.includes("[")) {
+        const match = CUSTOM_VALUE_BRACKET_REGEX.exec(baseClassName);
+        if (match) {
+          const customValue = match[1];
+          const baseKey = baseClassName.split("[")[0];
+          if (cssObject[`${baseKey}custom`]) {
+            let customResult = cssObject[`${baseKey}custom`].replace(/custom_value/g, customValue);
+            // Apply opacity modifier to custom values too
+            if (hasOpacityModifier && className.includes("/") && /\/\d+$/.test(className)) {
+              customResult = processOpacityModifier(className, customResult);
+            }
+            return customResult;
+          }
+        }
+      }
+      return "";
+    });
+    performanceMonitor.end(processMarker);
+
+    // Resolve CSS
+    cssResult = performanceMonitor.measure(() => separateAndResolveCSS(cssResult), "tws:resolve");
+
+    // Convert to JSON if needed
+    if (convertToJson) {
+      cssResult = performanceMonitor.measure(() => inlineStyleToJson(cssResult), "tws:json");
+    }
+    performanceMonitor.end(totalMarker);
+    return cssResult;
+  } catch (error) {
+    performanceMonitor.end(totalMarker);
+    handleError(error, {
+      classNames,
+      convertToJson
+    });
+    return convertToJson ? {} : "";
+  }
+}
+
+/**
+ * Debounced version of tws function
+ * 
+ * Useful for real-time class name updates in UI.
+ * 
+ * @param {string} classNames - String containing Tailwind classes
+ * @param {boolean} convertToJson - If true, returns JSON object
+ * @param {number} wait - Debounce delay in milliseconds (default: 50ms)
+ * @returns {Function} Debounced tws function
+ */
+function debounce(func) {
+  let wait = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : 100;
+  let timeout;
+  let callCount = 0;
+  return function () {
+    for (var _len = arguments.length, args = new Array(_len), _key = 0; _key < _len; _key++) {
+      args[_key] = arguments[_key];
+    }
+    const context = this;
+    callCount++;
+    clearTimeout(timeout);
+    timeout = setTimeout(() => {
+      const marker = performanceMonitor.start(`debounced:${func.name || "anonymous"}`);
+      try {
+        const result = func.apply(context, args);
+        performanceMonitor.end(marker);
+        return result;
+      } catch (error) {
+        performanceMonitor.end(marker);
+        logger.error(`Debounced function error (call #${callCount}):`, error);
+        throw error;
+      }
+    }, wait);
+  };
+}
+
+/** Debounced version of tws with 50ms delay */
+const debouncedTws = debounce(tws, 50);
+
+exports.debounce = debounce;
+exports.debouncedTws = debouncedTws;
+exports.tws = tws;