@melcanz85/chaincss 1.6.3 → 1.7.0

package/README.md

@@ -3,13 +3,16 @@
 [![npm version](https://badge.fury.io/js/@melcanz85%2Fchaincss.svg?v=2)](https://badge.fury.io/js/@melcanz85%2Fchaincss)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-A simple JavaScript-to-CSS transpiler that converts JS objects into optimized CSS.
+⚡ **Compile-time CSS-in-JS** - Runs during build, not in the browser!
+
+A simple JavaScript-to-CSS transpiler that converts JS objects into optimized CSS **without runtime overhead**.
 
 ## 🚀 Installation
 
 ```bash
     npm install @melcanz85/chaincss
 ```
+
 📦 Usage (Node.js)
 
 Quick Setup
@@ -22,11 +25,9 @@ Quick Setup
 
 ### Update your package.json scripts:
 
-json
-
-"scripts": {
-  "start": "concurrently \"nodemon server.js\" \"nodemon --watch chaincss/*.jcss --watch processor.js --exec 'node processor.js'\""
-}
+    "scripts": {
+      "start": "concurrently \"nodemon server.js\" \"nodemon --watch chaincss/*.jcss --watch processor.js --exec 'node processor.js'\""
+    }
 
 
 ## 🔧 CSS Prefixing
@@ -49,7 +50,7 @@ No additional installation needed!
 For complete prefixing coverage of all CSS properties:
 
 ```bash
-npm install autoprefixer postcss browserslist caniuse-db
+    npm install autoprefixer postcss browserslist caniuse-db
 ```
 Project Structure
 
@@ -185,12 +186,188 @@ In chaincss/processor.js:
     @>
     }
 
+
+## ⚛️ Using ChainCSS with React
+
+ChainCSS works great with React and Vite! Here's how to set it up:
+
+### Quick Start with React + Vite
+
+1. **Create a new React project**
+```bash
+    npm create vite@latest my-app -- --template react
+    cd my-app
+```
+
+### Project Structure (Component-First Approach)
+
+    my-react-app/
+    ├── src/
+    │   ├── components/
+    │   │   ├── Navbar/
+    │   │   │   ├── Navbar.jsx
+    │   │   │   └── navbar.jcss             # Chain definitions with fluent API
+    │   │   ├── Button/
+    │   │   │   ├── Button.jsx
+    │   │   │   └── button.jcss             # Chain definitions with fluent API
+    │   │   └── ...
+    │   ├── style/
+    │   │   └── global.css                  # Generated CSS
+    │   ├── App.jsx
+    │   └── main.jsx
+    ├── chaincss/
+    │   ├── main.jcss                        # Entry point - imports and compiles
+    │   └── processor.js                     # Processing script
+    └── package.json
+
+### How It Works
+
+1. **Each component has its own `.jcss` file** with style definitions as JavaScript objects
+2. **`main.jcss` imports all component styles** using `get()` function
+3. **Styles are merged and compiled** into a single `global.css` file
+4. **React components import the generated CSS** and use the class names
+
+### Example: Button Component
+
+**src/components/Nav/navbar.jcss**
+
+    const navbar = chain
+    .bg('rgba(255, 255, 255, 0.95)')
+    .backdropFilter('blur(10px)')
+    .padding('1rem 5%')
+    .position('fixed')
+    .width('100%')
+    .top('0')
+    .zIndex('1000')
+    .boxShadow('0 2px 20px rgba(0,0,0,0.1)')
+    .block('.navbar');
+
+    module.exports = {navbar}
+
+**src/components/Hero/hero.jcss**
+
+    const hero = chain
+    .padding('120px 5% 80px')
+    .bg('linear-gradient(135deg, #667eea 0%, #764ba2 100%)')
+    .color('white')
+    .textAlign('center')
+    .block('.hero');
+
+    module.exports = {hero}
+
+**chaincss/main.jcss**
+
+    // You can mix a default style using run() method or even vanilla css (without delimeters)
+    <@
+    run(
+        chain.margin('0').padding('0').boxSizing('border-box').block('*'),
+        chain
+        .fontFamily("-apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Oxygen, Ubuntu, sans-serif")
+        .lineHeight('1.6')
+        .color('#1e293b')
+        .bg('linear-gradient(135deg, #667eea 0%, #764ba2 100%)')
+        .block('body')
+    );
+    @>
+
+    .button {
+      background-color: #667eea;
+      color: white;
+      padding: 0.5rem 1rem;
+      border-radius: 4px;
+      border: none;
+      cursor: pointer;
+    }
+
+    <@
+    // Import all component styles
+    const nav = get('./src/components/Navbar/navbar.jcss');
+    const hero = get('./src/components/Hero/hero.jcss');
+
+    // Merge for one compilation
+    const allStyles = Object.assign({},nav,hero);
+
+    // Overwrite padding in navbar chain!
+    nav.navbar.padding = '1rem 5%';
+
+    compile(allStyles);
+    @>
+
+    // you can add keyframes and media queries in this setup
+    @keyframes fadeInUp {
+    <@
+    run(
+        chain.opacity('0').transform('translateY(20px)').block('from'),
+        chain.opacity('1').transform('translateY(0)').block('to'),
+    );
+    @>
+    }
+
+    /* Responsive */
+    @media (max-width: 768px) {
+    <@
+    run(
+        chain.fontSize('2.5rem').block('.hero h1'),
+        chain.flexDirection('column').gap('1rem').block('.stats'),
+        chain.flexDirection('column').alignItems('center').block('.cta-buttons'),
+        chain.gridTemplateColumns('1fr').block('.example-container'),
+        chain.display('none').block('.nav-links')
+    );
+    @>
+    }
+
+Benefits of This Approach
+
+    ✅ Component Co-location: Styles live next to their components
+
+    ✅ Single Source of Truth: Each component manages its own styles
+
+    ✅ Easy to Maintain: Add/remove components without touching a central style file
+
+    ✅ Scalable: Perfect for large React applications
+
+    ✅ No Redundancy: Styles are automatically merged and optimized
+
+**This structure is much cleaner and follows React best practices! Each component owns its styles, and `main.jcss` simply orchestrates the compilation.**
+
+🎯 Best Practices with React
+
+    1. Component-Specific Styles
+
+        * Keep styles close to components: Button/button.jcss
+
+        * Use descriptive class names that match your components
+
+    2. Global Styles
+
+        * Use main.jcss for global resets and animations
+
+        * Import generated CSS once in your root component
+
+    3. Dynamic Styles
+
+    // In your .jcss file
+    const theme = {
+      primary: '#667eea',
+      secondary: '#764ba2'
+    };
+
+    const button = chain
+      .backgroundColor(theme.primary)
+      .block('.btn');
+      
+    const buttonHover = chain
+      .backgroundColor(theme.secondary)
+      .block('.btn:hover');
+
 📝 Notes
     
-    You can directly put css syntax code on your main file.
+    You can directly put css syntax code on your main.jcss file.
 
     But chainCSS syntax must be wrapped in <@ @> delimiters.
 
+    run() and compile() method should be separate block <@ run() @> <@ compile @>
+
     The get() function imports chaining definitions from your chain.jcss file
 
     You can modify your style in between get() and compile() in the 
@@ -205,11 +382,11 @@ VS Code
 
 Add this to your project's .vscode/settings.json:
 
-{
-    "files.associations": {
-        "*.jcss": "javascript"
+    {
+        "files.associations": {
+            "*.jcss": "javascript"
+        }
     }
-}
 
 WebStorm / IntelliJ IDEA
 
@@ -268,10 +445,35 @@ Status               Feature             Description
 
 ✅ Watch             mode                Auto-recompile on file changes
 
+
+## 🚀 Key Differentiators
+
+- **⚙️ Compile-time, not runtime** - chaincss processes your styles during build, generating pure CSS files. Zero JavaScript execution in the browser means faster page loads!
+
+- **🏎️ Performance by design** - Unlike runtime CSS-in-JS libraries, chaincss adds no bundle weight and causes no layout shifts
+
+- **🔧 Build-time processing** - Your `.jcss` files are transformed before deployment, not in the user's browser
+
+
+## 🔄 chaincss vs Other Approaches
+
+|    Feature     |     chaincss      |  Runtime CSS-in-JS  | Tailwind      | Vanilla CSS |
+|----------------|-------------------|---------------------|---------------|-------------|
+| **When CSS is  | ⚙️ **Build time** | 🕒 Runtime (browser)| ⚙️ Build time | 📁 Already written |
+    generated**  
+
+| **Browser work**| None - just      | Executes JS to      | None - just   | None         |
+                    serves CSS          generate CSS            serves CSS
+
+| **Dynamic values**| ✅ Via JS at   | ✅ Via props at     | ⚠️ Limited    | ❌ Manual    |
+                         build time         runtime
+
+| **Bundle size** | Just the CSS     | CSS + JS runtime    | Just the CSS  | Just the CSS |
+
 👨‍💻 Contributing
 
     Contributions are welcome! Feel free to open issues or submit pull requests.
 
 📄 License
 
-MIT © Rommel E. Caneos
+MIT © Rommel Caneos

package/chaincss.js

@@ -1,6 +1,5 @@
 #!/usr/bin/env node
 
-// INCLUDE SEVERAL NODEJS MODULES
 const vm = require('vm');
 const path = require('path');
 const fs = require('fs');
@@ -18,21 +17,16 @@ let prefixerConfig = {
 const prefixer = new ChainCSSPrefixer(prefixerConfig);
 
 const processScript = (scriptBlock) => {
-  const context = vm.createContext({ 
-    ...transpilerModule
-  });
-
+  const context = vm.createContext({ ...transpilerModule});
   const jsCode = scriptBlock.trim();
   const chainScript = new vm.Script(jsCode);
   chainScript.runInContext(context);
   return context.chain.cssOutput;
 };
 
-// FUNCTION TO CONVERT JS CODES TO CSS CODE (FIRST STEP)
 const processJavascriptBlocks = (content) => {
   const blocks = content.split(/<@([\s\S]*?)@>/gm);
   let outputCSS = '';
-
   for (let i = 0; i < blocks.length; i++) {
     if (i % 2 === 0) {
       outputCSS += blocks[i]; // Write the existing CSS as is
@@ -49,15 +43,13 @@ const processJavascriptBlocks = (content) => {
       }
     }
   }
-  
   return outputCSS.trim();
 };
 
-// NEW: Validate CSS (check for unclosed blocks)
+// Validate CSS (check for unclosed blocks)
 const validateCSS = (css) => {
   const openBraces = (css.match(/{/g) || []).length;
   const closeBraces = (css.match(/}/g) || []).length;
-  
   if (openBraces !== closeBraces) {
     console.error(`CSS syntax error: Unclosed blocks (${openBraces} opening vs ${closeBraces} closing braces)`);
     return false;
@@ -66,17 +58,14 @@ const validateCSS = (css) => {
 };
 
 // Modified minification function with source map support
-
 const processAndMinifyCss = async (css, inputFile, outputFile) => {
-  // First validate the CSS
   if (!validateCSS(css)) {
     throw new Error('Invalid CSS syntax - check for missing braces');
   }
-  
+
   // Step 1: Apply prefixer (if enabled)
   let processedCss = css;
   let sourceMap = null;
-  
   if (prefixerConfig.enabled) {
     try {
       const result = await prefixer.process(css, {
@@ -84,10 +73,8 @@ const processAndMinifyCss = async (css, inputFile, outputFile) => {
         to: outputFile,
         map: prefixerConfig.sourceMap !== false
       });
-      
       processedCss = result.css;
       sourceMap = result.map;
-      
     } catch (err) {
       console.error('⚠Prefixer error:', err.message);
       processedCss = css;
@@ -100,19 +87,15 @@ const processAndMinifyCss = async (css, inputFile, outputFile) => {
     console.error('CSS Minification Errors:', output.errors);
     return { css: null, map: null };
   }
-  
   let finalCss = output.styles;
-  
   if (sourceMap && !prefixerConfig.sourceMapInline) {
     const mapFileName = path.basename(`${outputFile}.map`);
     finalCss += `\n/*# sourceMappingURL=${mapFileName} */`;
   }
-  
   return { css: finalCss, map: sourceMap };
 };
 
 // Main processor function - FIXED ORDER
-
 const processor = async (inputFile, outputFile) => {
   try {
     const input = path.resolve(inputFile);
@@ -126,19 +109,18 @@ const processor = async (inputFile, outputFile) => {
     if (!validateCSS(processedCSS)) {
       throw new Error('Invalid CSS syntax');
     }
-    
+
     // STEP 3: Apply prefixer and minify with source maps
-   
-    const result = await processAndMinifyCss(processedCSS, input, output);
+    const stylePath = output + '/global.css';
+    const result = await processAndMinifyCss(processedCSS, input, stylePath);
     if (result.css) {
-      fs.writeFileSync(output, result.css, 'utf8');
-      
+      fs.writeFileSync(stylePath, result.css, 'utf8');
+
       //Write source map if generated
       if (result.map) {
-        const mapFile = `${output}.map`;
+        const mapFile = `${stylePath}.map`;
         fs.writeFileSync(mapFile, result.map, 'utf8');
       }
-      
       if (prefixerConfig.enabled) {
         console.log(`   Prefixer: ${prefixerConfig.mode} mode (${prefixerConfig.browsers.join(', ')})`);
       }
@@ -155,9 +137,7 @@ const processor = async (inputFile, outputFile) => {
 
 // Watch function
 function watch(inputFile, outputFile) {
-  console.log(`Watching for changes in ${inputFile}...`);
   chokidar.watch(inputFile).on('change', async () => {
-    console.log(`File changed: ${inputFile}`);
     try {
       await processor(inputFile, outputFile);
     } catch (err) {
@@ -167,7 +147,6 @@ function watch(inputFile, outputFile) {
 }
 
 // Parse CLI arguments
-
 function parseArgs(args) {
   const result = {
     inputFile: null,
@@ -213,7 +192,6 @@ function parseArgs(args) {
 if (require.main === module) {
   const args = process.argv.slice(2);
   const cliOptions = parseArgs(args);
-  
   if (!cliOptions.inputFile || !cliOptions.outputFile) {
     console.log(`
 ChainCSS - JavaScript-powered CSS preprocessor

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@melcanz85/chaincss",
-  "version": "1.6.3",
+  "version": "1.7.0",
   "description": "A simple package transpiler for js to css",
   "main": "chaincss.js",
   "publishConfig": {

package/prefixer.js

@@ -105,7 +105,7 @@ class ChainCSSPrefixer {
     }
   }
 
-  // 🚀 Full mode with Autoprefixer
+  // Full mode with Autoprefixer
    async processWithAutoprefixer(cssString, options, mapOptions) {
     const from = options.from || 'input.css';
     const to = options.to || 'output.css';
@@ -124,7 +124,7 @@ class ChainCSSPrefixer {
     };
   }
 
-  // 🔧 Lightweight mode with built-in prefixer
+  // Lightweight mode with built-in prefixer
   async processWithBuiltIn(cssString, options, mapOptions) {
     if (!this.hasBuiltInDeps) {
       return { css: cssString, map: null };

package/transpiler.js

@@ -209,7 +209,6 @@ const compile = (obj) => {
       let selectors = element.selectors || []; // Provide default empty array if selectors is undefined
       let elementCSS = '';
       for (let prop in element) {
-
         if (element.hasOwnProperty(prop) && prop !== 'selectors') {
           // Convert camelCase to kebab-case
           const kebabKey = prop.replace(/([a-z])([A-Z])/g, '$1-$2').toLowerCase();
@@ -218,7 +217,6 @@ const compile = (obj) => {
       }
       selectors = selectors.join();
       cssString += `${selectors} {\n${elementCSS}}\n`;
-      
     }
   }
 
@@ -230,7 +228,6 @@ const get = (filename) => {
   if (fileExt !== '.jcss') {
     throw new Error(`Import error: ${filename} must have .jcss extension`);
   }
-  
   // Try to resolve the path
   const resolvedPath = path.resolve(process.cwd(), filename);
   
@@ -238,7 +235,7 @@ const get = (filename) => {
   const exists = fs.existsSync(resolvedPath);
   
   if (!exists) {
-    throw new Error(`File not found: ${filename} (resolved to: ${resolvedPath})`);
+    throw new Error('File not found: '+filename+'(resolved to: '+resolvedPath+')');
   }
   
   return require(resolvedPath);