chocola 1.3.5 → 1.3.7

package/README.md

@@ -1,427 +1,41 @@
-# 🍫 Chocola JS
+# chocola
 
-> A Sweet Taste of Reactive Web Development
+Chocola is a JavaScript library for creating web user interfaces.
 
-Chocola is a lightweight, reactive component-based web framework that brings simplicity and modularity to modern web development. Build dynamic components with reactivity, global state management, and a developer experience as sweet as chocolate.
+`chocola` only contains the functionality to build and serve web static builds. For production you may want to implement `chocola` to your workflow with other frameworks as Vite until official workflows are provided.
 
-## ✨ Features
-
-- **🧩 Component-Based Architecture** - Build reusable, modular components with ease
-- **⚡ Reactive Runtime** - Components automatically update when reactive variables change
-- **🔄 Reactive Variables** - Mutable state with `&{sfx.var}` syntax and automatic re-rendering
-- **🎯 Context System** - Pass data to components using intuitive `ctx.*` attributes
-- **🌐 Global State Management** - Share state across components with `sfx` variables
-- **📡 Variable Subscription** - Subscribe to state changes across your application
-- **🎭 Conditional Rendering** - Show/hide components dynamically with `chif` attribute
-- **🔌 Component Lifecycle API** - Public APIs for mounting, manipulating, and removing components
-- **📦 Built-in Bundler** - Automatic compilation and optimization
-- **🔥 Hot Reload Development** - See changes instantly with the dev server
-- **🎨 Template Syntax** - Clean HTML templates with `{}` and `&{}` interpolation
-- **⚙️ Zero Config** - Works out of the box with sensible defaults
-
-## 🚀 Quick Start
-
-### Installation
-
-```bash
-npm install chocola
-```
-
-### Project Structure
-
-```
-my-chocola-app/
-├── src/
-│   ├── lib/
-│   │   ├── Counter.js
-│   │   ├── TodoItem.js
-│   │   └── html/
-│   │       ├── counter.body.html
-│   │       └── todoItem.body.html
-│   ├── styles/
-│   │   └── mainStyle.css
-│   └── index.html
-├── chocola.config.json
-├── chocola.server.js
-└── index.js
-```
-
-### Configuration
-
-Create a `chocola.config.json` file:
-
-```json
-{
-  "bundle": {
-    "srcDir": "/src",
-    "outDir": "/dist",
-    "libDir": "/lib",
-    "emptyOutDir": true
-  },
-  "dev": {
-    "hostname": "localhost",
-    "port": 3000
-  }
-}
-```
-
-## 📝 Creating Components
-
-### 1. Define Your HTML Template
-
-> NOTE: Reactivity, component APIs and global variables are not implemented yet.
-> Any of these features displayed here are for future references and may be modified.
-
-Create `src/lib/html/counter.html`:
+## Usage
 
 ```html
-<div class="counter">
-  <h2>{ctx.title}</h2>
-  <!-- Use & to set reactivity -->
-  <p>Count: &{sfx.count}</p>
-  <button class="increment">+</button>
-  <button class="decrement">-</button>
+<!-- counter.html -->
+<div>
+  <button title={title}>{text}</button>
+
+  <div class="main">
+    <div class="number">${count}</div>
+  </div>
 </div>
 ```
 
-### 2. Create the Component Logic
-
-Create `src/lib/Counter.js`:
-
-```javascript
-import { lib } from "chocola";
+```js
 import HTML from "./html/counter.html";
+import CSS from "./css/counter.css";
 
 function RUNTIME(self, ctx) {
-  // Acces to component effects 
-  let sfx = self.sfx;
-
-  // Event handlers
-  self.querySelector(".increment").addEventListener("click", () => {
-    sfx.incrementCount(); // Automatically updates the UI
-  });
-  
-  self.querySelector(".decrement").addEventListener("click", () => {
-    sfx.decrementCount(); // Automatically updates the UI
-  });
-}
-
-function EFFECTS(self, sfx) {
-  // Component lifecycle effects
-  sfx.onMount: () => {
-      console.log("Counter mounted with count:", sfx.count);
-  },
-  sfx.onUpdate: () => {
-    // Log updated variables
-    console.log("Counter updated:", sfx.diff);
-  },
-  sfx.onRemove: () => {
-    console.log("Counter removed");
-  };
-
-  // Create the component public API
-  const api = lib.api(self, sfx);
-
-  // Create methods to expose
-  api.incrementCount = () => {
-    sfx.count++
-  }
-  api.decrementCount = () => {
-    sfx.count--
-  }
-
-  // Expose the component API
-  return api
+  self.querySelector("button").addEventListener("click", () => {
+    ctx.count++;
+  })
 }
 
 export default function Counter() {
   return {
     body: HTML,
-    script: RUNTIME,
-    effects: EFFECTS
-  };
-}
-```
-
-### 3. Use the Component
-
-In your `src/index.html`:
-
-```html
-<html>
-  <head>
-    <title>Chocola Counter App</title>
-  </head>
-  <body>
-    <app>
-      <Counter ctx.title="My Counter" sfx.initialCount="0"></Counter>
-    </app>
-  </body>
-</html>
-```
-
-## 🎭 Component Anatomy
-
-### Template (`body`)
-- Standard HTML with template variables
-- **Static context**: `{ctx.propertyName}`, `{sfx.propertyName}`  - rendered once at initialization
-- **Reactive state**: `&{sfx.propertyName}` - automatically updates on change
-- Clean separation of markup and logic
-
-### Runtime (`script`) - Optional
-- Function that receives `self` (component API, properties and DOM element), `ctx` (static context), and `sfx` (dynamic context)
-- Initialize runtime script and event handlers
-- Full access to DOM APIs and browser features
-- Executes when the component mounts
-
-### Effects (`effects`) - Optional
-- Function that receives `self` and `sfx`
-- Returns lifecycle hooks: `onMount`, `onUpdate`, `onRemove`
-- Manage side effects and component lifecycle
-- Clean up resources when component is removed
-
-## ⚡ Reactivity System
-
-### Mutable Reactive Variables
-
-Use `&{sfx.varName}` in templates for automatic reactivity:
-
-```html
-<div>
-  <p>Username: &{sfx.username}</p>
-  <p>Online: &{sfx.isOnline}</p>
-</div>
-```
-
-```javascript
-function RUNTIME(self, ctx) {
-  let sfx = self.sfx;
-  
-  // Changes automatically update the UI
-  setTimeout(() => {
-    sfx.username = "Alice";
-    sfx.isOnline = true;
-  }, 2000);
-}
-```
-
-### Variable Subscription
-
-Subscribe to changes in reactive variables across components:
-
-```javascript
-import { app } from "chocola";
-
-function RUNTIME(self, ctx) {
-    let sfx = self.sfx;
-
-  // Subscribe to global state
-  app.watch("globalCounter", (newValue) => {
-    console.log("Global counter changed to:", newValue);
-    sfx.localCount = newValue * 2;
-  });
-}
-```
-
-### Conditional Rendering
-
-Use the `chif` attribute to conditionally render components:
-
-```html
-<app>
-  <!-- Based on ctx variable (static) -->
-  <LoginForm chif="ctx.isLoggedOut"></LoginForm>
-  
-  <!-- Based on sfx variable (reactive with &) -->
-  <Dashboard chif="sfx.&isAuthenticated"></Dashboard>
-  <LoadingSpinner chif="sfx.&isLoading"></LoadingSpinner>
-</app>
-```
-
-```javascript
-function RUNTIME(self, ctx) {
-  let sfx = self.sfx;
-
-  // Simulate authentication
-  setTimeout(() => {
-    sfx.isLoading = false;
-    sfx.isAuthenticated = true;
-    // Dashboard appears, LoadingSpinner disappears
-  }, 2000);
-}
-```
-
-## 🌐 Global State Management
-
-Share state across your entire application:
-
-```javascript
-// In any component
-import * as globals from "path/to/globals.js";
-
-function RUNTIME(self, ctx) {
-  // Set global variables
-  globals.userTheme = "dark";
-  globals.notifications = [];
-  
-  // Access global variables from other components
-  console.log(globals.userTheme);
-}
-```
-
-## 🔌 Component Public API
-
-### Mounting Components Dynamically
-
-```javascript
-// In any component
-import { lib } from "chocola";
-import Counter from "./lib/Counter.js";
-
-// Mount a component programmatically in RUNTIME and/or EFFECTS
-function RUNTIME(self, ctx) {
- const counterInstance = lib.mount(Counter)
-   .defCtx({
-      title: "Dynamic Counter",
-      initialCount: "10"
-   })
-   .render() // Render accepts a DOM element or component
-             // instance as a target parameter; default
-             // target is set as your <app> element
-}
-```
-
-### Manipulating Components
-
-```javascript
-// Acces and modify variables
-console.log(counterInstance.ctx.title);
-counterInstance.sfx.count = 1;
-
-// Call component API methods
-counterInstance.reset();
-console.log(counterInstance.getCount())
-```
-
-### Removing Components
-
-```javascript
-// Remove and clean up
-counterInstance.remove();
-```
-
-## 🔧 Development
-
-### Start Development Server
-
-Create `chocola.server.js`:
-
-```javascript
-import { dev } from "chocola";
-import path from "path";
-import { fileURLToPath } from "url";
-
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = path.dirname(__filename);
-
-dev.server(__dirname);
-```
-
-Run:
-```bash
-node chocola.server.js
-```
-
-Visit `http://localhost:3000` to see your app with hot reload enabled.
-
-### Build for Production
-
-Create `index.js`:
-
-```javascript
-import { app } from "chocola";
-import path from "path";
-import { fileURLToPath } from "url";
-
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = path.dirname(__filename);
-
-app.build(__dirname);
-```
-
-Build:
-```bash
-node index.js
-```
-
-Your optimized app will be in the `dist/` directory.
-
----
-
-## 🏗️ Build Output
-
-Chocola automatically:
-- ✅ Compiles components into optimized JavaScript
-- ✅ Generates unique component IDs (`chid`)
-- ✅ Bundles scripts with proper dependency resolution
-- ✅ Processes templates and injects runtime code
-- ✅ Sets up reactivity system for `&{sfx.*}` variables
-- ✅ Optimizes conditional rendering with `chif` attributes
-- ✅ Generates component API wrappers for mounting/unmounting
-- ✅ Optimizes assets for production
-
-## 🎯 Best Practices
-
-### When to Use `ctx` vs `sfx`
-
-- **Use `ctx`** for static configuration that won't change (titles, labels, initial values)
-- **Use `sfx`** for dynamic data that updates over time and its configurations (counts, user input, API responses)
-
-### Component Lifecycle
-
-```javascript
-function EFFECTS(self, sfx) {
-  return {
-    onMount: () => {
-      // Initialize, fetch data, set up subscriptions
-    },
-    onUpdate: () => {
-      // React to specific state changes
-      // Only runs when sfx variables change
-    },
-    onRemove: () => {
-      // Clean up timers, subscriptions, event listeners
-    }
-  };
+    styles: CSS,
+    script: RUNTIME
+  }
 }
 ```
 
-### Conditional Rendering Performance
-
-- Use `chif` with reactive variables for dynamic show/hide
-- Use `chif` with static variables for static conditional rendering
-- Components with `chif="false"` are not mounted at all (performance optimization)
-
-## 🤝 Contributing
-
-Contributions are welcome! Chocola is in active development and we'd love your input.
-
-## 📄 License
-
-MIT License - feel free to use Chocola in your projects!
-
-## 🍫 Why Chocola?
-
-- **Simple**: No complex build configurations or CLI tools to learn
-- **Reactive**: Built-in reactivity without the complexity of larger frameworks
-- **Fast**: Minimal runtime overhead with efficient reactive updates
-- **Flexible**: Use as much or as little as you need
-- **Modern**: Built with ES modules and modern JavaScript features
-- **Powerful**: Global state, subscriptions, and lifecycle hooks out of the box
-- **Sweet**: Developer experience that's actually enjoyable
-
----
-
-Made with 🍫 and ❤️
+## Documentation
 
-**Start building sweet reactive web apps today!**
+See https://github.com/sad-gabi/chocola/wiki

package/compiler/component-processor.js

@@ -2,6 +2,21 @@ import { JSDOM } from "jsdom";
 import { extractContextFromElement } from "./dom-processor.js";
 import { genRandomId, incrementAlfabet } from "./utils.js";
 import chalk from "chalk";
+import beautify from "js-beautify";
+
+function scopeCss(cssString, cssId) {
+  return cssString.replace(/(^|\})([^{}]+)\{/g, (match, before, selector) => {
+    if (selector.trim().startsWith("@")) {
+      return match;
+    }
+    const scoped = selector
+      .split(",")
+      .map(sel => `.${cssId} ${sel.trim()}`)
+      .join(", ");
+    return `${before}${scoped}{`;
+  });
+}
+
 
 /**
  * Processes a single component element and inserts it into the DOM
@@ -18,7 +33,10 @@ export function processComponentElement(
   runtimeChunks,
   compIdColl,
   letterState,
-  runtimeMap
+  runtimeMap,
+  cssScopes,
+  cssScopesMap,
+  scopedStyles
 ) {
   const tagName = element.tagName.toLowerCase();
   const compName = tagName + ".js";
@@ -28,7 +46,7 @@ export function processComponentElement(
   const instance = loadedComponents.get(compName);
   if (!instance || instance === undefined) return false;
 
-  if (instance && instance.body) {
+  if (instance.body) {
     let body = instance.body;
     body = body.replace(
       /(?<!\b(?:if|del-if)=)\{(\w+)\}/g,
@@ -96,8 +114,18 @@ export function processComponentElement(
       slot.replaceWith(slotFragment);
     });
 
+    let style = instance.styles && instance.styles.toString();
+    if (style) {
+      let cssId = cssScopesMap && cssScopesMap.get(compName);
+      if (!cssId) {
+        cssId = genRandomId(cssScopes, 8, true);
+        cssScopesMap.set(compName, cssId);
+        fragment.firstChild.classList.add(cssId);
+      }
+      style = scopeCss(style, cssId);
+      scopedStyles.push(style);
+    }
     element.replaceWith(fragment);
-
     return true;
   }
 
@@ -112,22 +140,26 @@ export function processComponentElement(
  * @returns {{
  *   runtimeScript: string,
  *   hasComponents: boolean
+ *   scopesCss: CSSString
  * }}
  */
 export function processAllComponents(appElements, loadedComponents) {
-  const runtimeChunks = [];
-  const compIdColl = [];
-  const letterState = { value: null };
-  const runtimeMap = new Map();
+  let runtimeChunks = [];
+  let compIdColl = [];
+  let letterState = { value: null };
+  let runtimeMap = new Map();
+  let cssScopes = [];
+  let cssScopesMap = new Map();
+  let scopedStyles = [];
 
   appElements.forEach(el => {
-    processComponentElement(el, loadedComponents, runtimeChunks, compIdColl, letterState, runtimeMap);
+    processComponentElement(el, loadedComponents, runtimeChunks, compIdColl, letterState, runtimeMap, cssScopes, cssScopesMap, scopedStyles);
   });
-
   const runtimeScript = runtimeChunks.join("\n");
   const hasComponents = runtimeChunks.length > 0;
+  const scopesCss = beautify.css(scopedStyles.join("\n"));
 
-  return { runtimeScript, hasComponents };
+  return { runtimeScript, hasComponents, scopesCss };
 }
 
 /**

package/compiler/dom-processor.js

@@ -81,6 +81,28 @@ export function getAssetLinks(doc) {
   return { stylesheets, icons };
 }
 
+/**
+ * Writes CSS to output directory
+ * @param {string} css
+ * @param {import("fs").PathLike} outDirPath
+ * @param {string} filename
+ */
+export async function writeCSSOutput(css, outDirPath, filename = "scopes.css") {
+  await fs.writeFile(path.join(outDirPath, filename), css);
+}
+
+/**
+ * Appends a stylesheet link element to document head
+ * @param {Document} doc
+ * @param {string} filename
+ */
+export function appendStylesheetLink(doc, filename) {
+  const linkEl = doc.createElement("link");
+  linkEl.rel = "stylesheet";
+  linkEl.href = "./" + filename;
+  doc.head.appendChild(linkEl);
+}
+
 /**
  * Appends a script element to document body
  * @param {Document} doc

package/compiler/index.js

@@ -1,27 +1,21 @@
 import path from "path";
 import { promises as fs } from "fs";
 import chalk from "chalk";
-
-// Configuration
 import { loadConfig, resolvePaths } from "./config.js";
-
-// DOM Processing
 import {
     createDOM,
     validateAppContainer,
     getAppElements,
     getAssetLinks,
     appendRuntimeScript,
+    appendStylesheetLink,
     serializeDOM,
     writeHTMLOutput,
+    writeCSSOutput,
 } from "./dom-processor.js";
-
-// Component & Runtime Processing
 import { processAllComponents } from "./component-processor.js";
 import { generateRuntimeScript } from "./runtime-generator.js";
-
-// Utilities & Pipeline
-import { throwError } from "./utils.js";
+import { genRandomId, throwError } from "./utils.js";
 import {
     copyResources,
     getComponents,
@@ -31,8 +25,6 @@ import {
 } from "./pipeline.js";
 
 
-// ===== Logging & Banners =====
-
 const logSeparation = chalk.yellow(`
 ________________________________________________________________________
 ========================================================================
@@ -75,8 +67,6 @@ function logSuccess(outDirPath) {
     );
 }
 
-// ===== Directory Setup =====
-
 async function setupOutputDirectory(outDirPath, emptyOutDir) {
     if (emptyOutDir) {
         await fs.rm(outDirPath, { recursive: true, force: true });
@@ -84,8 +74,6 @@ async function setupOutputDirectory(outDirPath, emptyOutDir) {
     }
 }
 
-// ===== Component Loading =====
-
 async function loadAndDisplayComponents(srcComponentsPath) {
     const foundComponents = await getComponents(srcComponentsPath);
     const { loadedComponents, notDefComps, componentsLib } = foundComponents;
@@ -102,8 +90,6 @@ async function loadAndDisplayComponents(srcComponentsPath) {
     return loadedComponents;
 }
 
-// ===== Asset Processing =====
-
 async function processAssets(doc, rootDir, srcDir, outDirPath) {
     const { stylesheets, icons } = getAssetLinks(doc);
     const fileIds = [];
@@ -117,8 +103,6 @@ async function processAssets(doc, rootDir, srcDir, outDirPath) {
     }
 }
 
-// ===== Main Compilation Function =====
-
 /**
  * Compiles a static build of your Chocola project from the directory provided.
  * @param {import("fs").PathLike} rootDir
@@ -131,23 +115,17 @@ export default async function runtime(rootDir, buildConfig) {
     const isHotReload = buildConfig?.isHotReload || null;
     !isHotReload && logBanner();
 
-    // Load Configuration
     const config = await loadConfig(rootDir);
     const paths = resolvePaths(rootDir, config);
     !isHotReload && console.log(logSeparation);
 
-    // Setup Output Directory
     await setupOutputDirectory(paths.outDir, config.emptyOutDir);
 
-    // Load Index File
     const indexFiles = await getSrcIndex(paths.src);
     const srcIndexContent = indexFiles.srcHtmlFile || indexFiles.srcChocoFile;
 
-    // Load Components
     const loadedComponents = await loadAndDisplayComponents(paths.components);
     !isHotReload && console.log(logSeparation);
-
-    // Create and Validate DOM
     !isHotReload && console.log(`       BUNDLING STATIC BUILD`);
     !isHotReload && console.log(chalk.bold.green(">"), "Creating Chocola static build in directory", chalk.green.underline(paths.outDir) + "\n");
     !isHotReload && console.log(logSeparation);
@@ -157,24 +135,22 @@ export default async function runtime(rootDir, buildConfig) {
     const appContainer = validateAppContainer(doc);
     const appElements = getAppElements(appContainer);
 
-    // Process Components
-    const { runtimeScript } = processAllComponents(appElements, loadedComponents);
-
-    // Generate Runtime File
+    const { runtimeScript, scopesCss } = processAllComponents(appElements, loadedComponents);
     const runtimeFilename = await generateRuntimeScript(runtimeScript, paths.outDir);
-
-    // Process Assets (stylesheets, icons)
     await processAssets(doc, rootDir, config.srcDir, paths.outDir);
 
-    // Finalize HTML
+    if (scopesCss) {
+        const fileName = "sc-" + genRandomId(null, 6) + ".css";
+        await writeCSSOutput(scopesCss, paths.outDir, fileName);
+        appendStylesheetLink(doc, fileName);
+    };
+
     appendRuntimeScript(doc, runtimeFilename);
     const html = await serializeDOM(dom);
     await writeHTMLOutput(html, paths.outDir);
 
-    // Copy Resources
     await copyResources(rootDir, config.srcDir, paths.outDir);
 
-    // Success Message
     !isHotReload && logSuccess(paths.outDir);
     isHotReload && console.log("Dev server updated");
 }

package/compiler/pipeline.js

@@ -42,13 +42,6 @@ export async function getComponents(libDir) {
 
       const instance = module.default();
 
-      if (instance.bodyPath) {
-        instance.body = await fs.readFile(
-          path.resolve(libDir, instance.bodyPath),
-          "utf8"
-        );
-      }
-
       loadedComponents.set(comp.toLowerCase(), instance);
     }
 

package/compiler/utils.js

@@ -54,10 +54,17 @@ export async function loadWithAssets(filePath) {
  * @param {number} length - Desired length of the ID (default: 10)
  * @returns {string} - Unique random ID
  */
-export function genRandomId(collection, length = 10) {
-  const id = Math.random().toString(36).substring(2, length + 2);
+export function genRandomId(collection = null, length = 10, lettersOnly = false) {
+  let id;
+  if (lettersOnly) {
+    const letters = "abcdefghijklmnopqrstuvwxyz";
+    id = Array.from({ length }, () => letters[Math.floor(Math.random() * letters.length)]).join("");
+  } else {
+    id = Math.random().toString(36).substring(2, length + 2);
+  }
+  if (!collection) return id;
   if (collection.includes(id)) {
-    return genRandomId(collection, length);
+    return genRandomId(collection, length, lettersOnly);
   } else {
     collection.push(id);
     return id;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "chocola",
-  "version": "1.3.5",
+  "version": "1.3.7",
   "description": "The sweetest way to build reactive web apps",
   "keywords": [
     "web",