@melcanz85/chaincss 1.7.3 → 1.9.0

package/README.md

@@ -1,473 +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:
 
-## 🚀 Installation
+**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.js --exec 'node processor.js'\""
+    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 modes:
+    // chaincss/layout.jcss (build-time)
+    const grid = $().display('grid').gap('1rem').block('.grid');
 
-### 1. Lightweight Mode (Default, ~50KB)
+    // components/Card.jsx (runtime)
+    function Card({ isHighlighted }) {
+      const styles = useChainStyles({
+        card: () => $()
+          .backgroundColor(isHighlighted ? '#fffacd' : 'white')
+          .padding('1rem')
+          .block()
+      });
+    }
+```
 
-Built-in prefixer that handles the most common CSS properties:
-- Flexbox & Grid
-- Transforms & Animations
-- Filters & Effects
-- Text effects
-- Box properties
+## Features at a Glance
 
-No additional installation needed!
+Feature             Status      Description
 
-### 2. Full Mode (Uses Autoprefixer)
+Zero Runtime        ✅          Pure CSS output, no JS in browser
 
-For complete prefixing coverage of all CSS properties:
+React Hooks         ✅          Dynamic runtime styles when needed
 
-```bash
-    npm install autoprefixer postcss browserslist caniuse-db
-```
-Project Structure
+Atomic CSS          ✅          90% smaller CSS files
 
-Create this folder structure in your project:
+TypeScript          ✅          First-class type support
 
-    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
-
-
-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);
-    }
+Design Tokens       ✅          Centralized design system
 
-💻 Code Examples
-
-    //--Chaining File (chaincss/chain.jcss):
-
-### 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 
-    and the exception of the background property which is shorten to 'bg' only for
-    example background-color is bgColor() in chaincss. The value of the block() 
-    method is the css selector which is always at the end of the chain or block.
-
-    // Variables for consistent styling
-    const bodyBg = 'linear-gradient(135deg, #667eea 0%, #764ba2 100%)';
-    const headerBg = 'rgba(255, 255, 255, 0.95)';
-    const bodyFontFamily = "-apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Oxygen, 
-                            Ubuntu, sans-serif";
-    const headerBoxShadow = '0 2px 20px rgba(0,0,0,0.1)';
-    const logoFontSize = '1.8rem';
-
-    const reset = chain
-      .margin('0')
-        .padding('0')
-        .boxSizing('border-box')
-        .block('*');
-
-    const body = chain
-        .fontFamily(bodyFontFamily)
-        .lineHeight('1.6')
-        .color('#1e293b')
-        .bg(bodyBg)
-        .block('body');
-
-        /* Header/Navigation */
-    const navbar = chain
-        .bg(headerBg)
-        .backdropFilter('blur(10px)')
-        .padding('1rem 5%')
-        .position('fixed')
-        .width('100%')
-        .top('0')
-        .zIndex('1000')
-        .boxShadow(headerBoxShadow)
-        .block('.navbar');
-
-    const nav_container = chain
-        .maxWidth('1200px')
-        .margin('0 auto')
-        .display('flex')
-        .justifyContent('space-between')
-        .alignItems('center')
-        .block('.nav-container');
-
-    const logo = chain
-        .fontSize(logoFontSize)
-        .fontWeight('700')
-        .bg('linear-gradient(135deg, #667eea, #764ba2)')
-        .backgroundClip('text')
-        .textFillColor('transparent')
-        .letterSpacing('-0.5px')
-        .block('.logo');
+Auto-prefixing      ✅          Built-in + full Autoprefixer
 
-    module.exports = {
-      reset,
-      navbar,
-      nav_container,
-      logo
-    };
+Source Maps         ✅          Debug your .jcss files
 
+Watch Mode          ✅          Instant recompilation
 
-//--Main File (chaincss/main.jcss):
+VM Security         ✅          Safe code execution
 
-    <@
-      // Import chaining definitions
-      const style = get('./chain.jcss');
 
-      // Override specific styles
-      style.logo.fontSize = '2rem';
-      
-      // Compile to CSS
-      compile(style);
-    @>
+## The ChainCSS API
 
-    @keyframes fadeInUp {
-    <@
-      run(
-        chain.opacity('0').transform('translateY(20px)').block('from'),
-        chain.opacity('1').transform('translateY(0)').block('to'),
-      );
-    @>
-    }
+### The Chain Builder
 
-    /* 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')
-      );
-    @>
-    }
+```javascript
+    // jQuery-like fluent API
+    const style = $()
+      .propertyName('value')      // camelCase → kebab-case
+      .anotherProperty('value')
+      .block('.selector');         // End the chain with selector(s)
 
+    // 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
 
-## ⚛️ Using ChainCSS with React
+```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
 
-ChainCSS works great with React and Vite! Here's how to set it up:
+**chaincss/button.jcss**
 
-### Quick Start with React + Vite
+```javascript
+    const button = $()
+      .backgroundColor('#667eea')
+      .color('white')
+      .padding('0.75rem 1.5rem')
+      .borderRadius('0.375rem')
+      .fontWeight('600')
+      .block('.btn');
 
-1. **Create a new React project**
-```bash
-    npm create vite@latest my-app -- --template react
-    cd my-app
+    module.exports = { button };
 ```
+**chaincss/main.jcss**
 
-### Project Structure (Component-First Approach)
+```javascript
+    <@
+      const { button } = get('./button.jcss');
+      compile({ button });
+    @>
+````
 
-    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
+**chaincss/processor.js**
 
-### How It Works
+```javascript
 
-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
+const chaincss = require('@melcanz85/chaincss');
 
-### Example: Navbar & Hero Components
+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');
+```
 
-**src/components/Nav/navbar.jcss**
+## Atomic CSS Optimization
 
-    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');
+```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!**
 
-    module.exports = {navbar}
+### Built-in Security
 
-**src/components/Hero/hero.jcss**
+ChainCSS uses **secure VM sandboxing** to safely execute your .jcss files. No eval, no global leaks, no security risks.
 
-    const hero = chain
-    .padding('120px 5% 80px')
-    .bg('linear-gradient(135deg, #667eea 0%, #764ba2 100%)')
-    .color('white')
-    .textAlign('center')
-    .block('.hero');
 
-    module.exports = {hero}
+## Quick Start Guides
 
-**chaincss/main.jcss**
+### With Node.js (Vanilla)
 
-    // 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')
-    );
-    @>
+```bash
+    # 1. Install
+    npm install @melcanz85/chaincss
 
-    .button {
-      background-color: #667eea;
-      color: white;
-      padding: 0.5rem 1rem;
-      border-radius: 4px;
-      border: none;
-      cursor: pointer;
-    }
+    # 2. Create processor.cjs
+    echo "const chaincss = require('@melcanz85/chaincss');
+    chaincss.processor('./chaincss/main.jcss', './dist');" > processor.js
 
-    <@
-    // Import all component styles
-    const nav = get('./src/components/Navbar/navbar.jcss');
-    const hero = get('./src/components/Hero/hero.jcss');
+    # 3. Create your first .jcss file
+    mkdir chaincss
+    echo "const hello = $().color('red').block('.hello');
+    compile({ hello });" > chaincss/main.jcss
 
-    // Merge for one compilation
-    const allStyles = Object.assign({},nav,hero);
+    # 4. Build
+    node processor.js
+    # ✅ ./dist/global.css generated!
+```
+### With React + Vite
 
-    // Overwrite padding in navbar chain!
-    nav.navbar.padding = '1rem 5%';
+```bash
+    # 1. Create React app
+    npm create vite@latest my-app -- --template react
+    cd my-app
 
-    compile(allStyles);
-    @>
+    # 2. Install ChainCSS
+    npm install @melcanz85/chaincss
 
-    // 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'),
-    );
-    @>
+    # 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>;
     }
+```
 
-    /* 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
+## Performance Comparison
 
-    ✅ Component Co-location: Styles live next to their components
+Approach                Runtime Cost        Bundle Size         Dynamic Styles      Learning Curve
 
-    ✅ Single Source of Truth: Each component manages its own styles
+**ChainCSS (Build)**  **Zero**            **Just CSS**          Build-time          Low
 
-    ✅ Easy to Maintain: Add/remove components without touching a central style file
+**ChainCSS (Runtime)**  Minimal             Small runtime       ✅ Full             Low
 
-    ✅ Scalable: Perfect for large React applications
+Styled Components       5-10KB runtime      CSS + runtime       ✅ Full             Medium
 
-    ✅ No Redundancy: Styles are automatically merged and optimized
+Emotion                 8-12KB runtime      CSS + runtime       ✅ Full             Medium
 
-**This structure is much cleaner and follows React best practices! Each component owns its styles, and `main.jcss` simply orchestrates the compilation.**
+Tailwind                Zero                Just CSS            ⚠️ Limited          High
 
-🎯 Best Practices with React
+CSS Modules             Zero                Just CSS            ❌ None             Low
 
-    1. Component-Specific Styles
+**ChainCSS is the ONLY library that gives you BOTH worlds!**
 
-        * Keep styles close to components: Button/button.jcss
 
-        * Use descriptive class names that match your components
+## Configuration
 
-    2. Global Styles
+Create chaincss.config.js in your project root:
 
-        * Use main.jcss for global resets and animations
+```javascript
 
-        * 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
+
+```vim
+    au BufRead,BufNewFile `*.jcss` setfiletype javascript
+```
 
-    "*":
-      core:
-        customFileTypes:
-          "source.js": [
-            "jcss"
-          ]
 
+## Roadmap
 
-Other Editors
+* Zero-runtime compilation
 
-Most modern editors allow you to associate file extensions with language modes. Simply configure your editor to treat .jcss files as JavaScript.
+* React hooks
 
+* Atomic CSS optimization
 
-✨ Features
+* Design tokens
 
-Status               Feature             Description
+* TypeScript support
 
-✅ Basic             JS → CSS            Convert plain JS objects to CSS
+* Vue/Svelte integrations (coming soon)
 
-✅ Vendor            prefixing           Auto-add -webkit-, -moz-, etc.
+* Plugin system (coming soon)
 
-✅ Keyframe          animations          @keyframes 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.