@melcanz85/chaincss 1.8.0 → 1.9.0

package/README.md

@@ -1,446 +1,448 @@
-# @melcanz85/chaincss
+# ChainCSS
 
 [![npm version](https://img.shields.io/npm/v/@melcanz85/chaincss.svg)](https://www.npmjs.com/package/@melcanz85/chaincss)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-**Compile-time CSS-in-JS** - Runs during build, not in the browser!
+**Write CSS with JavaScript. The only CSS-in-JS library that lets you CHOOSE your runtime cost.**
 
-A simple JavaScript-to-CSS transpiler that converts JS objects into optimized CSS **without runtime overhead**.
+ChainCSS is a revolutionary CSS-in-JS solution that gives you **two powerful modes** in one package:
 
+**Build-time compilation** → Pure CSS, zero JavaScript in browser
+
+**Runtime hooks** → Dynamic, prop-based styles when you need them
+
+"The performance of vanilla CSS with the power of JavaScript — now with **CHOICE.**"
+
+```javascript
+    // Same beautiful API, two powerful modes
+    const button = $()
+      .color('white')
+      .backgroundColor('#667eea')
+      .padding('1rem')
+      .borderRadius('4px')
+      .block('.btn');
+````
 ## Installation
 
 ```bash
+
     npm install @melcanz85/chaincss
 ```
 
-**Usage (Node.js)**
+## Two Powerful Modes - One API
 
-Quick Setup
+### Mode 1: Build-time (Zero Runtime)
 
-### Install development dependencies:
+**Perfect for:** Static styles, layouts, design systems — anything that doesn't change.
 
-```bash
-    npm install --save-dev nodemon concurrently
-```
-
-### Update your package.json scripts:
+```javascript
+    // chaincss/button.jcss
+    const button = $()
+      .backgroundColor('#667eea')
+      .color('white')
+      .padding('0.5rem 1rem')
+      .borderRadius('4px')
+      .block('.btn');
 
-    "scripts": {
-      "start": "concurrently \"nodemon server.js\" \"nodemon --watch chaincss/*.jcss --watch processor.cjs --exec 'node processor.cjs'\""
+    module.exports = { button };
+````
+
+```javascript
+    // chaincss/processor.js
+    const chaincss = require('@melcanz85/chaincss');
+
+    chaincss.processor('./chaincss/main.jcss', './dist/style.css');
+    //  Outputs pure CSS: .btn { background: #667eea; color: white; ... }
+    //  Zero JavaScript sent to browser
+    //  Max performance, smallest bundle
+````
+### Mode 2: Runtime (React Hooks)
+
+**Perfect for:** Dynamic styles that respond to props, state, or themes.
+
+```jsx
+    // components/DynamicButton.jsx
+    import { useChainStyles } from '@melcanz85/chaincss';
+
+    function DynamicButton({ variant = 'primary', children }) {
+      const styles = useChainStyles({
+        button: () => $()
+          .backgroundColor(variant === 'primary' ? '#667eea' : '#48bb78')
+          .color('white')
+          .padding('0.5rem 1rem')
+          .borderRadius('4px')
+          .hover()
+            .transform('translateY(-2px)')
+            .boxShadow('0 4px 6px rgba(0,0,0,0.1)')
+          .block()
+      });
+      
+      return <button className={styles.button}>{children}</button>;
     }
+    //  Styles injected at runtime
+    //  Automatic cleanup on unmount
+    //  Fully dynamic based on props
+```
 
+## Use BOTH in the Same Project!
 
-## CSS Prefixing
+```jsx
+    // Best of both worlds:
+    // - Layout styles → Build-time (zero cost)
+    // - Interactive styles → Runtime (dynamic)
 
-ChainCSS offers two prefixing approaches:
+    // chaincss/layout.jcss (build-time)
+    const grid = $().display('grid').gap('1rem').block('.grid');
 
-### 1. Built-in Prefixer (Auto Mode, Default)
+    // components/Card.jsx (runtime)
+    function Card({ isHighlighted }) {
+      const styles = useChainStyles({
+        card: () => $()
+          .backgroundColor(isHighlighted ? '#fffacd' : 'white')
+          .padding('1rem')
+          .block()
+      });
+    }
+```
 
-Our lightweight built-in prefixer handles the most common CSS properties:
-- Flexbox & Grid
-- Transforms & Animations
-- Filters & Effects
-- Text effects
-- Box properties
+## Features at a Glance
 
-**No additional installation needed!** Just run:
-```bash
-    npx chaincss input.jcss output.css --watch
-```
-### 2. Full Autoprefixer Mode (Complete Coverage)
+Feature             Status      Description
 
-For complete prefixing coverage of all CSS properties:
+Zero Runtime        ✅          Pure CSS output, no JS in browser
 
-```bash
-    npm install autoprefixer postcss browserslist caniuse-db
-    
-    # then run this command 
-    npx chaincss input.jcss output.css --watch --prefixer-mode full
+React Hooks         ✅          Dynamic runtime styles when needed
 
-```
+Atomic CSS          ✅          90% smaller CSS files
 
-### 3. Make Full Mode Permanent
+TypeScript          ✅          First-class type support
 
-Edit your package.json script:
+Design Tokens       ✅          Centralized design system
 
-    "scripts": {
-        "css:watch": "chaincss src/styles.jcss dist/styles.css --watch --prefixer-mode full",
-        "start": "concurrently \"npm run dev\" \"npm run css:watch\""
-    }
+Auto-prefixing      ✅          Built-in + full Autoprefixer
 
+Source Maps         ✅          Debug your .jcss files
 
-**Project Structure (vanillajs, vanilla nodejs)**
+Watch Mode          ✅          Instant recompilation
 
-Create this folder structure in your vanillaJS project:
+VM Security         ✅          Safe code execution
 
-    your-project/
-    ├── chaincss/                 # ChainCSS source files
-    │   ├── main.jcss             # Main entry file
-    │   ├── chain.jcss            # Chaining definitions
-    │   └── processor.js         # Processing script
-    ├── public/                   # Output files
-    │   ├── index.html
-    │   └── style.css             # Generated CSS
-    ├── node_modules/
-    ├── package.json
-    ├── package.lock.json
-    └── server.js
-
-
-**The Initialization processor Setup**
-
-In chaincss/processor.js:
-
-    const chain = require("@melcanz85/chaincss");
-
-    try {
-      // Process main file and output CSS
-      chain.processor('./chaincss/main.jcss', './public/style.css');
-    } catch (err) {
-      console.error('Error processing chainCSS file:', err.stack);
-      process.exit(1);
-    }
 
-## Code Examples
+## The ChainCSS API
 
-    //--Chaining File (chaincss/chain.jcss):
+### The Chain Builder
 
-**This is where the chaining happens all codes must be in javascript syntax. 
-    The chain methods are the same as the css properties but in camelCase mode. 
-    The value of the block() method is the css selector which is always at the 
-    end of the chain or block.**
+```javascript
+    // jQuery-like fluent API
+    const style = $()
+      .propertyName('value')      // camelCase → kebab-case
+      .anotherProperty('value')
+      .block('.selector');         // End the chain with selector(s)
 
-       /* Header/Navigation */
-    const navbar = $().backdropFilter('blur(10px)').padding('1rem 5%')
-        .position('fixed').width('100%').top('0').zIndex('1000').boxShadow(headerBoxShadow)
-        .block('.navbar');
+    // Pseudo-classes & nested styles
+    const button = $()
+      .color('white')
+      .backgroundColor('#667eea')
+      .hover()
+        .backgroundColor('#5a67d8')
+        .transform('scale(1.05)')
+      .focus()
+        .boxShadow('0 0 0 3px rgba(102,126,234,0.5)')
+      .block('.btn');
+````
+### File Structure
 
-    const nav_container = $().maxWidth('1200px').margin('0 auto').display('flex')
-        .justifyContent('space-between').alignItems('center').block('.nav-container');
+```text
+    your-project/
+    ├── chaincss/
+    │   ├── main.jcss           # Entry point - imports & compiles
+    │   ├── processor.cjs        # Build script
+    │   └── *.jcss              # Your style definitions
+    ├── src/
+    │   └── style/
+    │       └── global.css      # Generated CSS
+    └── package.json
+```
+### Basic Example
 
-    module.exports = {
-      navbar,
-      nav_container
-    };
+**chaincss/button.jcss**
 
+```javascript
+    const button = $()
+      .backgroundColor('#667eea')
+      .color('white')
+      .padding('0.75rem 1.5rem')
+      .borderRadius('0.375rem')
+      .fontWeight('600')
+      .block('.btn');
 
-**Main File (chaincss/main.jcss):**
+    module.exports = { button };
+```
+**chaincss/main.jcss**
 
+```javascript
     <@
-      // Import chaining definitions
-      const style = get('./chain.jcss');
-
-      // Override specific styles
-      style.navbar.padding = '2rem 5%';
-      
-      // Compile to CSS
-      compile(style);
+      const { button } = get('./button.jcss');
+      compile({ button });
     @>
+````
 
-    @keyframes fadeInUp {
-        <@
-            const from = $().opacity('0').transform('translateY(20px)').block('from');
-            const to = $().chain.opacity('1').transform('translateY(0)').block('to');
-            run(from,to);
-        @>
-    }
-
-    /* Responsive */
-    @media (max-width: 768px) {
-        <@
-            const hero_h1 = $().fontSize('2.5rem').block('.hero h1');
-            const stats = $().flexDirection('column').gap('1rem').block('.stats');
-            const cta_buttons = $().flexDirection('column').alignItems('center').block('.cta-buttons');
-            const ex_container = $().gridTemplateColumns('1fr').block('.example-container');
-            const nav_links = $().display('none').block('.nav-links');
-            run(hero_h1,stats,cta_buttons,ex_container,nav_links);
-        @>
-    }
-
+**chaincss/processor.js**
 
-## ⚛️ Using ChainCSS with React
+```javascript
 
-ChainCSS works great with React and Vite! Here's how to set it up:
+const chaincss = require('@melcanz85/chaincss');
 
-### Quick Start with React + Vite
-
-1. **Create a new React project**
-```bash
-    npm create vite@latest my-app -- --template react
-    cd my-app
+chaincss.processor('./chaincss/main.jcss', './src/style');
+// Generates ./src/style/global.css
+```
+## Advanced Features
+
+### Design Tokens
+
+```javascript
+
+    // tokens.js
+    const { createTokens } = require('@melcanz85/chaincss');
+
+    module.exports = createTokens({
+      colors: {
+        primary: '#667eea',
+        secondary: '#764ba2'
+      },
+      spacing: {
+        sm: '0.5rem',
+        md: '1rem',
+        lg: '1.5rem'
+      }
+    });
+
+    // In your styles
+    const button = $()
+      .color('$colors.primary')     // ← Token syntax!
+      .padding('$spacing.md')
+      .block('.btn');
 ```
 
-### Project Structure (Component-First Approach)
+## Atomic CSS Optimization
 
-    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
+```javascript
+    // chaincss.config.js
+    module.exports = {
+      atomic: {
+        enabled: true,      // Enable 90% CSS size reduction
+        threshold: 3,        // Styles used 3+ times become atomic
+        naming: 'hash'       // Smallest class names
+      }
+    };
+```
+**Before (standard CSS):** 4,823 chars
+**After (atomic CSS):** 499 chars → **90% smaller!**
 
-### How It Works
+### Built-in Security
 
-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
+ChainCSS uses **secure VM sandboxing** to safely execute your .jcss files. No eval, no global leaks, no security risks.
 
-### Example: Navbar & Hero Components
 
-**src/components/Nav/navbar.jcss**
+## Quick Start Guides
 
-    const navbar = $()
-    .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');
+### With Node.js (Vanilla)
 
-    module.exports = {navbar}
+```bash
+    # 1. Install
+    npm install @melcanz85/chaincss
 
-**src/components/Hero/hero.jcss**
+    # 2. Create processor.cjs
+    echo "const chaincss = require('@melcanz85/chaincss');
+    chaincss.processor('./chaincss/main.jcss', './dist');" > processor.js
 
-    const hero = chain
-    .padding('120px 5% 80px')
-    .bg('linear-gradient(135deg, #667eea 0%, #764ba2 100%)')
-    .color('white')
-    .textAlign('center')
-    .block('.hero');
+    # 3. Create your first .jcss file
+    mkdir chaincss
+    echo "const hello = $().color('red').block('.hello');
+    compile({ hello });" > chaincss/main.jcss
 
-    module.exports = {hero}
+    # 4. Build
+    node processor.js
+    # ✅ ./dist/global.css generated!
+```
+### With React + Vite
 
-**chaincss/main.jcss**
+```bash
+    # 1. Create React app
+    npm create vite@latest my-app -- --template react
+    cd my-app
 
-    // You can mix a default style using run() method or even vanilla css (without delimeters)
-    <@
-    const reset =  $().margin('0').padding('0').boxSizing('border-box').block('*');
-    const body =  $().fontFamily("-apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, 
-                Oxygen, Ubuntu, sans-serif").lineHeight('1.6').color('#1e293b')
-                .background('linear-gradient(135deg, #667eea 0%, #764ba2 100%)').block('body');
-    run(reset, body);
-    @>
+    # 2. Install ChainCSS
+    npm install @melcanz85/chaincss
 
-    .button {
-      background-color: #667eea;
-      color: white;
-      padding: 0.5rem 1rem;
-      border-radius: 4px;
-      border: none;
-      cursor: pointer;
+    # 3. Create component with styles
+    mkdir -p src/components/Button
+```
+**src/components/Button/Button.jsx**
+
+```jsx
+
+    import { useChainStyles } from '@melcanz85/chaincss';
+
+    export function Button({ variant = 'primary', children }) {
+      const styles = useChainStyles({
+        button: () => $()
+          .backgroundColor(variant === 'primary' ? '#667eea' : '#48bb78')
+          .color('white')
+          .padding('0.5rem 1rem')
+          .borderRadius('0.375rem')
+          .hover()
+            .transform('translateY(-2px)')
+            .boxShadow('0 4px 6px rgba(0,0,0,0.1)')
+          .block()
+      });
+      
+      return <button className={styles.button}>{children}</button>;
     }
+```
 
-    <@
-    // Import all component styles
-    const nav = get('./src/components/nav/nav.jcss');
-    const hero = get('./src/components/sect_hero/hero.jcss');
-    const feature = get('./src/components/sect_feature/feature.jcss');
-    const example = get('./src/components/sect_example/example.jcss');
-    const gstart = get('./src/components/sect_gStart/gStart.jcss');
-    const footer = get('./src/components/footer/footer.jcss');
-
-    const merged = Object.assign({},nav,hero,feature,example,gstart,footer);
-
-        // Overwrite your chaining file
-        nav.logo.textDecoration = 'none';
-        //example.css_output.overflowWrap = 'break-word';
-        
-    compile(merged);
-    @>
-
-    // you can add keyframes and media queries in this setup
-    @keyframes fadeInUp {
-    <@
-        const from =  $().opacity('0').transform('translateY(20px)').block('from');
-        const to =  $().opacity('1').transform('translateY(0)').block('to');
-        run(from,to);
-    @>
-}
 
-    /* Responsive */
-    @media (max-width: 768px) {
-    <@
-        const hero =  $().fontSize('2.5rem').block('.hero h1');
-        const stats =  $().flexDirection('column').gap('1rem').block('.stats');
-        const ctaButtons =  $().flexDirection('column').alignItems('center').block('.cta-buttons');
-        const exampleContainer =  $().gridTemplateColumns('1fr').block('.example-container');
-        const navLinks =  $().display('none').block('.nav-links');
-        run(hero,stats,ctaButtons,exampleContainer,navLinks);
-    @>
-}
+## Performance Comparison
 
-**Benefits of This Approach**
+Approach                Runtime Cost        Bundle Size         Dynamic Styles      Learning Curve
 
-    ✅ Component Co-location: Styles live next to their components
+**ChainCSS (Build)**  **Zero**            **Just CSS**          Build-time          Low
 
-    ✅ Single Source of Truth: Each component manages its own styles
+**ChainCSS (Runtime)**  Minimal             Small runtime       ✅ Full             Low
 
-    ✅ Easy to Maintain: Add/remove components without touching a central style file
+Styled Components       5-10KB runtime      CSS + runtime       ✅ Full             Medium
 
-    ✅ Scalable: Perfect for large React applications
+Emotion                 8-12KB runtime      CSS + runtime       ✅ Full             Medium
 
-    ✅ No Redundancy: Styles are automatically merged and optimized
+Tailwind                Zero                Just CSS            ⚠️ Limited          High
 
-This structure is much cleaner and follows React best practices! Each component owns its styles, and 
-    `main.jcss` simply orchestrates the compilation.
+CSS Modules             Zero                Just CSS            ❌ None             Low
 
-## 🎯 Best Practices with React
+**ChainCSS is the ONLY library that gives you BOTH worlds!**
 
-    1. Component-Specific Styles
 
-        * Keep styles close to components: Button/button.jcss
+## Configuration
 
-        * Use descriptive class names that match your components
+Create chaincss.config.js in your project root:
 
-    2. Global Styles
+```javascript
 
-        * Use main.jcss for global resets and animations
-
-        * Import generated CSS once in your root component
+    module.exports = {
+      // Atomic CSS optimization
+      atomic: {
+        enabled: true,
+        threshold: 3,        // Min usage for atomic conversion
+        naming: 'hash'       // 'hash' | 'readable' | 'short'
+      },
+      
+      // Prefixer options
+      prefixer: {
+        mode: 'auto',        // 'auto' or 'full'
+        browsers: ['> 0.5%', 'last 2 versions']
+      },
+      
+      // Source maps
+      sourceMaps: true
+    };
+```
 
-    3. Dynamic Styles
 
-    // In your .jcss file
-    const theme = {
-      primary: '#667eea',
-      secondary: '#764ba2'
-    };
+## API Reference
 
-    const button = chain
-      .backgroundColor(theme.primary)
-      .block('.btn');
-      
-    const buttonHover = chain
-      .backgroundColor(theme.secondary)
-      .block('.btn:hover');
+### Core Functions
 
-## 📝 Notes
-    
-    You can directly put css syntax code on your main.jcss file.
+Function                        Description
 
-    But chainCSS syntax must be wrapped in <@ @> delimiters.
+`$()`                           Create a new chain builder
 
-    run() and compile() method should be separate block <@ run() @> <@ compile @>
+`.block(selector)`              End chain and assign selector(s)
 
-    The get() function imports chaining definitions from your chain.jcss file
+`compile(styles)`               Compile style objects to CSS
 
-    You can modify your style in between get() and compile() in the 
-    main file it will overwrite the styles in the chain file.
+`run(...styles)`                Process inline styles
 
-## 🎨 Editor Support
+`get(filename)`                 Import .jcss files
 
-Since .jcss files are just JavaScript files with ChainCSS syntax, you can 
-easily enable proper syntax highlighting in your editor:
+`processor(input, output)`      Build-time processor
 
-**VS Code**
 
-Add this to your project's .vscode/settings.json:
+### React Hooks
 
-    {
-        "files.associations": {
-            "*.jcss": "javascript"
-        }
-    }
+Hook                                        Description
 
-**WebStorm / IntelliJ IDEA**
+`useChainStyles(styles, options)`           Basic styles hook
 
-    Go to Settings/Preferences → Editor → File Types
+`useDynamicChainStyles(factory, deps)`      Styles that depend on props/state
 
-    Select JavaScript in the list
+`useThemeChainStyles(styles, theme)`        Theme-aware styles
 
-    Click + and add *.jcss to the registered patterns
+`ChainCSSGlobal`                            Global styles component
 
-**Vim / Neovim**
+`cx(...classes)`                            Conditional class merging
 
-Add to your .vimrc or init.vim:
 
-    au BufRead,BufNewFile *.jcss setfiletype javascript
+## Editor Support
 
-**Sublime Text**
+### VS Code
 
-    Create or edit ~/Library/Application Support/Sublime Text/Packages/User/JCSS.sublime-settings:
+```json
+    {
+      "files.associations": {
+        "*.jcss": "javascript"
+      }
+    }
+```
 
-json
+### WebStorm
 
-{
-    "extensions": ["jcss"],
-    "syntax": "Packages/JavaScript/JavaScript.sublime-syntax"
-}
+* Settings → Editor → File Types
 
-**Atom**
+* Add `*.jcss` as JavaScript
 
-Add to your config.cson:
-coffeescript
+### Vim
 
-    "*":
-      core:
-        customFileTypes:
-          "source.js": [
-            "jcss"
-          ]
+```vim
+    au BufRead,BufNewFile `*.jcss` setfiletype javascript
+```
 
 
-Other Editors
+## Roadmap
 
-Most modern editors allow you to associate file extensions with language modes. 
-Simply configure your editor to treat .jcss files as JavaScript.
+* Zero-runtime compilation
 
+* React hooks
 
-## Features
+* Atomic CSS optimization
 
-Status               Feature             Description
+* Design tokens
 
-✅ Basic             JS → CSS            Convert plain JS objects to CSS
+* TypeScript support
 
-✅ Vendor            prefixing           Auto-add -webkit-, -moz-, etc.
+* Vue/Svelte integrations (coming soon)
 
-✅ Keyframe          animations          @keyframes support
+* Plugin system (coming soon)
 
-✅ Media queries     responsive          @media support
-                     
-✅ Source maps       Debug               generated CSS
 
-✅ Watch             mode                Auto-recompile on file changes
+## Contributing
 
+Contributions are welcome! Whether it's:
 
-### Key Differentiators
+* Bug fixes
 
-- ** Compile-time, not runtime** - chaincss processes your styles during build, generating pure CSS files. Zero JavaScript execution in the browser means faster page loads!
+* Documentation improvements
 
-- ** Performance by design** - Unlike runtime CSS-in-JS libraries, chaincss adds no bundle weight and causes no layout shifts
+* New features
 
-- ** Build-time processing** - Your `.jcss` files are transformed before deployment, not in the user's browser
+* Test cases
 
+Please see CONTRIBUTING.md for guidelines.
 
-### chaincss vs Other Approaches
 
-|    Feature     |     chaincss      |  Runtime CSS-in-JS  | Tailwind      | Vanilla CSS |
-|----------------|-------------------|---------------------|---------------|-------------|
-| **When CSS is generated** |  **Build time** |  Runtime (browser) |  Build time |  Already written |
-| **Browser work**| None - just serves CSS | Executes JS to generate CSS | None - just serves CSS | None |
-| **Dynamic values**|  Via JS at build time |  Via props at runtime | ⚠ Limited  |  Manual |
-| **Bundle size** | Just the CSS | CSS + JS runtime | Just the CSS | Just the CSS |
+## License
 
-### 👨‍💻 Contributing
+MIT © [Rommel Caneos]('https://github.com/melcanz08')
 
-    Contributions are welcome! Feel free to open issues or submit pull requests.
 
-### License
+## Star Us on GitHub!
 
-MIT © Rommel Caneos
+If ChainCSS helps you, please [give it a star!]('https://github.com/melcanz08/chaincss') It helps others discover it.