chaincss 2.0.7 → 2.1.1

package/src/plugins/webpack.ts

@@ -0,0 +1,416 @@
+// chaincss/src/plugins/webpack.ts
+
+import path from 'path';
+import { execSync, spawn } from 'child_process';
+import fs from 'fs';
+import { fileURLToPath } from 'url';
+import crypto from 'crypto';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+export interface ChainCSSLoaderOptions {
+  /**
+   * Mode: 'build' for production (zero-runtime), 'runtime' for development
+   * @default process.env.NODE_ENV === 'production' ? 'build' : 'runtime'
+   */
+  mode?: 'build' | 'runtime';
+  
+  /**
+   * Enable atomic CSS optimization
+   * @default false
+   */
+  atomic?: boolean;
+  
+  /**
+   * Enable CSS minification
+   * @default process.env.NODE_ENV === 'production'
+   */
+  minify?: boolean;
+  
+  /**
+   * Enable source maps
+   * @default false
+   */
+  sourceMap?: boolean;
+  
+  /**
+   * Output directory for compiled CSS
+   * @default '.chaincss-cache'
+   */
+  outputDir?: string;
+  
+  /**
+   * Verbose logging
+   * @default false
+   */
+  verbose?: boolean;
+  
+  /**
+   * Enable CSS extraction to separate file
+   * @default false
+   */
+  extractCSS?: boolean;
+  
+  /**
+   * Enable Hot Module Replacement
+   * @default true in development
+   */
+  hmr?: boolean;
+  
+  /**
+   * Custom cache key for compilation
+   */
+  cacheKey?: string;
+  
+  /**
+   * Framework to generate components for
+   * @default 'auto'
+   */
+  framework?: 'react' | 'vue' | 'svelte' | 'solid' | 'auto';
+}
+
+interface LoaderContext {
+  async: () => (err: Error | null, code?: string) => void;
+  getOptions: () => ChainCSSLoaderOptions;
+  resourcePath: string;
+  context: string;
+  cacheable: (flag: boolean) => void;
+  addDependency: (file: string) => void;
+  emitFile: (name: string, content: string, sourceMap?: any) => void;
+  emitWarning: (warning: Error) => void;
+  emitError: (error: Error) => void;
+}
+
+interface StyleExport {
+  name: string;
+  className: string;
+}
+
+/**
+ * Generate a unique hash for cache busting
+ */
+function generateHash(content: string): string {
+  return crypto.createHash('md5').update(content).digest('hex').slice(0, 8);
+}
+
+/**
+ * Extract style variable names and their values from source code
+ */
+function extractStyleExports(source: string): StyleExport[] {
+  const exports: StyleExport[] = [];
+  
+  // Match const declarations that use chain() or $()
+  const constRegex = /const\s+(\w+)\s*=\s*(?:chain|\$)\(\s*\)\s*(?:\.\w+\([^)]*\)\s*)*\.\$el\(['"`]([^'"`]+)['"`]\)/g;
+  let match;
+  
+  while ((match = constRegex.exec(source)) !== null) {
+    exports.push({
+      name: match[1],
+      className: match[2]
+    });
+  }
+  
+  // Also match export declarations
+  const exportRegex = /export\s+const\s+(\w+)\s*=\s*(?:chain|\$)\(\s*\)\s*(?:\.\w+\([^)]*\)\s*)*\.\$el\(['"`]([^'"`]+)['"`]\)/g;
+  while ((match = exportRegex.exec(source)) !== null) {
+    exports.push({
+      name: match[1],
+      className: match[2]
+    });
+  }
+  
+  return exports;
+}
+
+/**
+ * Generate runtime code for development mode
+ */
+function generateRuntimeCode(source: string, styleExports: StyleExport[], resourcePath: string, options: ChainCSSLoaderOptions): string {
+  const styleNames = styleExports.map(e => e.name).join(', ');
+  const hmrEnabled = options.hmr !== false && process.env.NODE_ENV !== 'production';
+  
+  // Generate class mapping
+  const classMapping = styleExports.map(exp => `  ${exp.name}: '${exp.className}'`).join(',\n');
+  
+  return `
+    // Generated by ChainCSS Webpack Loader (Runtime Mode)
+    // Source: ${path.basename(resourcePath)}
+    
+    import { chain, enableDebug } from 'chaincss/runtime';
+    
+    ${hmrEnabled ? `// Enable debug in development
+    if (process.env.NODE_ENV !== 'production') {
+      enableDebug(${options.verbose || false});
+    }` : ''}
+    
+    // Original source for reference
+    ${source}
+    
+    // Compiled style exports
+    export const styles = {
+    ${classMapping}
+    };
+    
+    export default styles;
+    
+    ${hmrEnabled ? `
+    // HMR Support
+    if (module.hot) {
+      module.hot.accept();
+      module.hot.dispose(() => {
+        // Cleanup on reload
+        const styleId = 'chaincss-${generateHash(resourcePath)}';
+        const style = document.getElementById(styleId);
+        if (style) style.remove();
+      });
+    }
+    ` : ''}
+  `;
+}
+
+/**
+ * Generate production code with CSS extraction
+ */
+function generateProductionCode(
+  css: string,
+  styleExports: StyleExport[],
+  resourcePath: string,
+  options: ChainCSSLoaderOptions
+): string {
+  const styleNames = styleExports.map(e => e.name).join(', ');
+  const classMapping = styleExports.map(exp => `  ${exp.name}: '${exp.className}'`).join(',\n');
+  
+  // Escape CSS for injection
+  const escapedCSS = css
+    .replace(/\\/g, '\\\\')
+    .replace(/`/g, '\\`')
+    .replace(/\$/g, '\\$');
+  
+  if (options.extractCSS) {
+    // CSS will be extracted to separate file
+    return `
+      // Generated by ChainCSS Webpack Loader (Build Mode - Extracted)
+      // Source: ${path.basename(resourcePath)}
+      
+      export const styles = {
+      ${classMapping}
+      };
+      
+      export default styles;
+    `;
+  } else {
+    // CSS will be injected via JavaScript
+    return `
+      // Generated by ChainCSS Webpack Loader (Build Mode - Injected)
+      // Source: ${path.basename(resourcePath)}
+      
+      export const styles = {
+      ${classMapping}
+      };
+      
+      // Inject CSS
+      const css = \`${escapedCSS}\`;
+      if (typeof document !== 'undefined' && css && css.trim()) {
+        const styleId = 'chaincss-${generateHash(resourcePath)}';
+        let style = document.getElementById(styleId);
+        if (!style) {
+          style = document.createElement('style');
+          style.id = styleId;
+          style.setAttribute('data-chaincss', 'true');
+          style.setAttribute('data-source', ${JSON.stringify(path.basename(resourcePath))});
+          document.head.appendChild(style);
+        }
+        style.textContent = css;
+      }
+      
+      export default styles;
+    `;
+  }
+}
+
+/**
+ * Compile ChainCSS file using the compiler
+ */
+async function compileChainCSS(
+  source: string,
+  filePath: string,
+  options: ChainCSSLoaderOptions,
+  context: LoaderContext
+): Promise<{ css: string; classMap: Record<string, string> }> {
+  const tempFile = path.join(context.context, `.temp.${generateHash(source)}.chain.js`);
+  const outputDir = options.outputDir || path.join(process.cwd(), '.chaincss-cache');
+  const baseName = path.basename(filePath, path.extname(filePath));
+  
+  try {
+    // Ensure temp directory exists
+    const tempDir = path.dirname(tempFile);
+    if (!fs.existsSync(tempDir)) {
+      fs.mkdirSync(tempDir, { recursive: true });
+    }
+    
+    // Write temp file
+    fs.writeFileSync(tempFile, source, 'utf8');
+    context.addDependency(tempFile);
+    
+    // Ensure output directory exists
+    if (!fs.existsSync(outputDir)) {
+      fs.mkdirSync(outputDir, { recursive: true });
+    }
+    
+    // Build CLI command using the compiler
+    const chaincssCli = path.join(__dirname, '../cli/index.js');
+    
+    // Check if CLI exists
+    if (!fs.existsSync(chaincssCli)) {
+      throw new Error(`ChainCSS CLI not found at ${chaincssCli}. Please ensure chaincss is built.`);
+    }
+    
+    const args = [
+      chaincssCli,
+      'compile',
+      tempFile,
+      outputDir,
+      '--framework', options.framework || 'auto'
+    ];
+    
+    if (options.atomic) args.push('--atomic');
+    if (options.minify) args.push('--minify');
+    if (options.sourceMap) args.push('--source-map');
+    if (options.verbose) args.push('--verbose');
+    
+    if (options.verbose) {
+      console.log(`[chaincss-loader] Executing: node ${args.join(' ')}`);
+    }
+    
+    // Execute compilation with timeout
+    const result = await new Promise<{ stdout: string; stderr: string }>((resolve, reject) => {
+      const proc = spawn('node', args, {
+        cwd: process.cwd(),
+        timeout: 30000
+      });
+      
+      let stdout = '';
+      let stderr = '';
+      
+      proc.stdout.on('data', (data) => { stdout += data.toString(); });
+      proc.stderr.on('data', (data) => { stderr += data.toString(); });
+      
+      proc.on('close', (code) => {
+        if (code === 0) {
+          resolve({ stdout, stderr });
+        } else {
+          reject(new Error(`Compilation failed with code ${code}: ${stderr}`));
+        }
+      });
+      
+      proc.on('error', reject);
+    });
+    
+    if (options.verbose && result.stdout) {
+      console.log(result.stdout);
+    }
+    
+    if (result.stderr) {
+      context.emitWarning(new Error(result.stderr));
+    }
+    
+    // Read generated CSS
+    const cssPath = path.join(outputDir, `${baseName}.css`);
+    let css = '';
+    if (fs.existsSync(cssPath)) {
+      css = fs.readFileSync(cssPath, 'utf8');
+      if (options.verbose) {
+        console.log(`[chaincss-loader] Read CSS: ${css.length} bytes from ${cssPath}`);
+      }
+    }
+    
+    // Read generated class map
+    const classMapPath = path.join(outputDir, `${baseName}.class.js`);
+    let classMap: Record<string, string> = {};
+    if (fs.existsSync(classMapPath)) {
+      const classMapContent = fs.readFileSync(classMapPath, 'utf8');
+      // Parse the exported class map
+      const exportMatch = classMapContent.match(/export const (\w+) = '([^']+)'/g);
+      if (exportMatch) {
+        exportMatch.forEach(line => {
+          const match = line.match(/export const (\w+) = '([^']+)'/);
+          if (match) {
+            classMap[match[1]] = match[2];
+          }
+        });
+      }
+    }
+    
+    return { css, classMap };
+    
+  } finally {
+    // Clean up temp file
+    try {
+      if (fs.existsSync(tempFile)) {
+        fs.unlinkSync(tempFile);
+      }
+    } catch (e) {
+      // Ignore cleanup errors
+    }
+  }
+}
+
+/**
+ * Webpack loader for ChainCSS
+ * Converts .chain.js / .chain.ts files to static CSS at build time
+ */
+export default function chaincssLoader(this: LoaderContext, source: string): void {
+  const callback = this.async();
+  const options = this.getOptions() || {};
+  
+  // Make loader cacheable
+  this.cacheable(true);
+  
+  // Determine mode: default to 'build' in production, 'runtime' in development
+  const mode = options.mode || (process.env.NODE_ENV === 'production' ? 'build' : 'runtime');
+  
+  // Extract style exports from source
+  const styleExports = extractStyleExports(source);
+  
+  if (options.verbose) {
+    console.log(`[chaincss-loader] Processing ${path.basename(this.resourcePath)} in ${mode} mode`);
+    console.log(`[chaincss-loader] Found exports: ${styleExports.map(e => e.name).join(', ')}`);
+  }
+  
+  // DEVELOPMENT MODE: Use runtime (fast iteration, but has runtime cost)
+  if (mode === 'runtime') {
+    const code = generateRuntimeCode(source, styleExports, this.resourcePath, options);
+    callback(null, code);
+    return;
+  }
+  
+  // PRODUCTION MODE: Build-time compilation (zero-runtime)
+  compileChainCSS(source, this.resourcePath, options, this)
+    .then(({ css, classMap }) => {
+      // Emit CSS as separate asset if extractCSS is enabled
+      if (options.extractCSS && css) {
+        const cssFileName = `${path.basename(this.resourcePath, path.extname(this.resourcePath))}.css`;
+        this.emitFile(cssFileName, css);
+        if (options.verbose) {
+          console.log(`[chaincss-loader] Emitted CSS: ${cssFileName} (${css.length} bytes)`);
+        }
+      }
+      
+      // Generate final code
+      const code = generateProductionCode(css, styleExports, this.resourcePath, options);
+      
+      if (options.verbose) {
+        console.log(`[chaincss-loader] ✓ Compiled ${path.basename(this.resourcePath)}`);
+        console.log(`[chaincss-loader]   CSS size: ${css.length} bytes`);
+        console.log(`[chaincss-loader]   Exports: ${styleExports.length}`);
+      }
+      
+      callback(null, code);
+    })
+    .catch((err: Error) => {
+      console.error(`[chaincss-loader] Error compiling ${this.resourcePath}:`, err.message);
+      this.emitError(err);
+      callback(err);
+    });
+}

package/src/runtime/Chain.ts

@@ -0,0 +1,242 @@
+// chaincss/src/runtime/Chain.ts
+
+import { macros as coreMacros, shorthandMap } from '../compiler/shorthands.js';
+
+let debugMode = false;
+
+export function enableDebug(enabled: boolean = true): void {
+  debugMode = enabled;
+}
+
+
+/**
+ * The mutable registry for runtime plugins.
+ */
+const runtimeMacros: Record<string, any> = { ...coreMacros };
+
+/**
+ * HYDRATION BRIDGE
+ * This stores the mapping between "prop:value" and "atomic-class-name".
+ * It is populated at app-start by the user.
+ */
+let globalManifest: Record<string, string> = {};
+
+// Update setManifest to use debug flag
+export const setManifest = (manifest: any) => {
+  if (manifest.atomicMap) {
+    globalManifest = manifest.atomicMap;
+  } else if (manifest.atomicClasses) {
+    globalManifest = manifest.atomicClasses;
+  } else {
+    globalManifest = manifest || {};
+  }
+  
+  if (debugMode) {
+    console.log('[ChainCSS] Manifest loaded with', Object.keys(globalManifest).length, 'entries');
+  }
+};
+
+/**
+ * THE TOKEN STORE
+ * Stores user-defined design tokens (colors, spacing, etc.)
+ */
+let globalTokens: Record<string, any> = {};
+
+// Update setTokens to use debug flag
+export const setTokens = (tokens: any) => {
+  globalTokens = tokens;
+  if (debugMode) {
+    console.log('[ChainCSS] Tokens updated:', Object.keys(globalTokens));
+  }
+};
+
+export class RuntimeChain {
+  // catcher now tracks both raw styles and pre-baked class names
+  private catcher: Record<string, any> = { _classes: [] };
+  private componentName: string = '';
+  public proxy: any;
+
+  constructor(private useTokens: boolean = false) {
+    // Only these methods are public API
+    const PUBLIC_METHODS = new Set([
+      'use', 'hover', '$el', '$name', 'end', 'getCatcher'
+    ]);
+    
+    this.proxy = new Proxy(this, {
+      /**
+       * 1. TRAPS FOR EXTERNAL TOOLS (React, DevTools, JSON.stringify)
+       * This prevents the "cyclic object value" error.
+       */
+      get: (target, prop: string | symbol) => {
+        // Handle standard JS/React internal checks
+        if (prop === 'toJSON') return () => target.catcher;
+        if (prop === 'constructor') return RuntimeChain;
+        if (prop === Symbol.toStringTag) return 'RuntimeChain';
+        if (prop === '_isChain') return true; // Secret handshake for the hook
+
+        // If it's a symbol we don't handle, return it from the target
+        if (typeof prop !== 'string') return (target as any)[prop];
+
+        // 2. PUBLIC METHODS only ($el, use, hover, $name, end, getCatcher)
+        if (prop in target && PUBLIC_METHODS.has(prop)) {
+          const val = (target as any)[prop];
+          return typeof val === 'function' ? val.bind(target) : val;
+        }
+        
+        // Block internal methods from being called directly
+        if (prop in target && typeof (target as any)[prop] === 'function') {
+          if (debugMode) {
+            console.warn(`[ChainCSS] '${prop}' is an internal method, not part of the public API`);
+          }
+          return undefined;
+        }
+
+        // 3. SHORTHAND RESOLUTION (e.g., 'bg' -> 'backgroundColor')
+        const realProp = (shorthandMap as any)[prop] || prop;
+
+        // 4. MACRO CHECK (.center, .glass, etc.)
+        if (runtimeMacros[prop]) {
+          return (val: any) => {
+            runtimeMacros[prop](val, target.catcher, target.useTokens);
+            return target.proxy;
+          };
+        }
+
+        // 5. THE "BREAD AND BUTTER" CSS HANDLER
+        return (val: any) => {
+          // --- TOKEN RESOLUTION ---
+          let finalVal = val;
+          let valueWithUnit = val;
+          const unitless = ['opacity', 'zIndex', 'flex', 'fontWeight', 'flexGrow', 'flexShrink', 'flexBasis', 'order', 'lineHeight', 'animationIterationCount', 'orphans', 'widows', 'columnCount'];
+          if (typeof finalVal === 'number' && !unitless.includes(realProp)) {
+            valueWithUnit = `${val}px`;
+            finalVal = valueWithUnit; // Ensure the dynamic style also has px
+          }
+
+          // --- HYBRID LOOKUP (Static vs Dynamic) ---
+          // Match the compiler's format "property:value"
+          const lookupKey = `${realProp}:${valueWithUnit}`; 
+          const staticClass = globalManifest[lookupKey];
+
+          // In the RuntimeChain class, when adding to _classes, add debug
+          if (staticClass) {
+            if (!target.catcher._classes.includes(staticClass)) {
+              target.catcher._classes.push(staticClass);
+              if (debugMode) {
+                console.log(`[ChainCSS] Using atomic class: ${staticClass} for ${lookupKey}`);
+              }
+            }
+          } else {
+            if (debugMode) {
+              console.log(`[ChainCSS] No atomic class for ${lookupKey}, will inject at runtime`);
+            }
+            target.catcher[realProp] = finalVal;
+          }
+
+          // Return the proxy so we can keep chaining: .bg().color().br()
+          return target.proxy;
+        };
+      }
+    });
+  }
+
+  
+
+  use(plugin: any): any {
+    const { selectors, atRules, ...styles } = plugin;
+    
+    // Resolve shorthands for incoming plugin styles
+    Object.entries(styles).forEach(([key, val]) => {
+      const realProp = (shorthandMap as any)[key] || key;
+      this.catcher[realProp] = val;
+    });
+    
+    return this.proxy;
+  }
+
+  hover(): any {
+    const hoverCatcher: Record<string, any> = { _classes: [] };
+    const hoverHandler: ProxyHandler<object> = {
+      get: (_, prop: string) => {
+        if (prop === 'end') {
+          return () => {
+            this.catcher.hover = { ...this.catcher.hover, ...hoverCatcher };
+            return this.proxy;
+          };
+        }
+
+        const realProp = (shorthandMap as any)[prop] || prop;
+
+        return (val: any) => {
+          // ✅ FIXED: Use hover: prefix for hover state keys
+          const lookupKey = `hover:${realProp}:${val}`;
+          const staticClass = globalManifest[lookupKey];
+
+          if (staticClass) {
+            if (!hoverCatcher._classes.includes(staticClass)) {
+              hoverCatcher._classes.push(staticClass);
+            }
+          } else if (runtimeMacros[prop]) {
+            runtimeMacros[prop](val, hoverCatcher, this.useTokens);
+          } else {
+            hoverCatcher[realProp] = val;
+          }
+          return hoverProxy;
+        };
+      }
+    };
+    const hoverProxy = new Proxy({}, hoverHandler);
+    return hoverProxy;
+  }
+
+  /**
+   * Set the component name for class generation
+   */
+  $name(name: string): this {
+    this.componentName = name;
+    return this;
+  }
+
+  /**
+   * Finalizes the chain. Returns the style object and resets the catcher.
+   */
+  $el(name?: string): Record<string, any> {
+  // Deep clone to prevent reference sharing
+  const result = structuredClone(this.catcher);
+  
+  // Set component name
+  result._name = name || this.componentName || 'element';
+  
+  // Strip internal metadata
+  delete result._componentName;
+  delete result._generateComponent;
+  delete result._framework;
+  delete result._propsDefinition;
+  
+  // Full reset
+  this.catcher = { _classes: [] };
+  this.componentName = '';
+  
+  return result;
+}
+
+  end(name?: string) {
+    return this.$el(name);
+  }
+  
+  /**
+   * Get the current catcher (for debugging)
+   */
+  getCatcher(): Record<string, any> {
+    return { ...this.catcher };
+  }
+}
+
+/**
+ * --- EXPORTS ---
+ */
+
+export const $ = () => new RuntimeChain(false).proxy;
+export const $t = () => new RuntimeChain(true).proxy;
+export const chain = (useTokens: boolean = false) => new RuntimeChain(useTokens).proxy;
+export default chain;