chocola 1.1.20 → 1.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) SadGabi.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,428 @@
+# 🍫 Chocola JS
+
+> A Sweet Taste of Reactive Web Development
+
+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.
+
+## ✨ 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 this features displayed here are for future references and may be modified.
+
+Create `src/lib/html/counter.body.html`:
+
+```html
+<div class="counter">
+  <h2>${ctx.title}</h2>
+  <!-- Use & instead of $ to set reactivity -->
+  <p>Count: &{sfx.count}</p>
+  <button class="increment">+</button>
+  <button class="decrement">-</button>
+</div>
+```
+
+### 2. Create the Component Logic
+
+Create `src/lib/Counter.js`:
+
+```javascript
+import { lib } from "chocola";
+import HTML from "./html/counter.body.html";
+
+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
+}
+
+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>
+      <!-- Set mutable sfx variables with & -->
+      <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, sfx) {
+  // 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, "src", "dist");
+```
+
+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
+    }
+  };
+}
+```
+
+### 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 ❤️
+
+**Start building sweet reactive web apps today!**

package/compiler/component-processor.js

@@ -0,0 +1,95 @@
+import { JSDOM } from "jsdom";
+import { extractContextFromElement } from "./dom-processor.js";
+import { genRandomId, incrementAlfabet } from "./utils.js";
+import chalk from "chalk";
+
+/**
+ * Processes a single component element and inserts it into the DOM
+ * @param {Element} element
+ * @param {Map} loadedComponents
+ * @param {Array} runtimeChunks
+ * @param {Array} compIdColl
+ * @param {object} letterState - { value: string }
+ * @returns {boolean} - true if component was processed, false if not found
+ */
+export function processComponentElement(
+  element,
+  loadedComponents,
+  runtimeChunks,
+  compIdColl,
+  letterState
+) {
+  const tagName = element.tagName.toLowerCase();
+  const compName = tagName + ".js";
+  const ctx = extractContextFromElement(element);
+
+  const instance = loadedComponents.get(compName);
+  if (!instance || instance === undefined) return false;
+
+  if (instance && instance.body) {
+    let body = instance.body;
+    body = body.replace(/\$\{ctx\.(\w+)\}/g, (_, key) => ctx[key] || "");
+    const fragment = JSDOM.fragment(body);
+    const firstChild = fragment.firstChild;
+
+    if (firstChild && firstChild.nodeType === 1) {
+      if (instance.script || instance.effects) {
+        const compId = "chid-" + genRandomId(compIdColl);
+        firstChild.setAttribute("chid", compId);
+
+        let script = instance.script && instance.script.toString();
+        const letter = getNextLetter(letterState);
+
+        script = script.replace(/RUNTIME/g, `${letter}RUNTIME`);
+
+        runtimeChunks.push(`
+const ${letter} = document.querySelector('[chid="${compId}"]');
+${script}
+${letter}RUNTIME(${letter}, ${JSON.stringify(ctx)});`);
+      }
+    }
+    element.replaceWith(fragment);
+    return true;
+  }
+
+  console.warn(chalk.yellow(`${compName} component could not be loaded`));
+  return false;
+}
+
+/**
+ * Processes all components in the app container
+ * @param {Element[]} appElements
+ * @param {Map} loadedComponents
+ * @returns {{
+ *   runtimeScript: string,
+ *   hasComponents: boolean
+ * }}
+ */
+export function processAllComponents(appElements, loadedComponents) {
+  const runtimeChunks = [];
+  const compIdColl = [];
+  const letterState = { value: null };
+
+  appElements.forEach(el => {
+    processComponentElement(el, loadedComponents, runtimeChunks, compIdColl, letterState);
+  });
+
+  const runtimeScript = runtimeChunks.join("\n");
+  const hasComponents = runtimeChunks.length > 0;
+
+  return { runtimeScript, hasComponents };
+}
+
+/**
+ * Gets the next letter in sequence or starts with 'a'
+ * @param {object} letterState - { value: string }
+ * @returns {string}
+ */
+function getNextLetter(letterState) {
+  if (!letterState.value) {
+    letterState.value = "a";
+  } else {
+    letterState.value = incrementAlfabet(letterState.value);
+  }
+  return letterState.value;
+}

package/compiler/config.js

@@ -0,0 +1,66 @@
+import path from "path";
+import chalk from "chalk";
+import { getChocolaConfig } from "../utils.js";
+
+/**
+ * Loads and merges Chocola configuration with defaults
+ * @param {import("fs").PathLike} rootDir
+ * @returns {Promise<{
+ *   srcDir: string,
+ *   outDir: string,
+ *   libDir: string,
+ *   emptyOutDir: boolean
+ * }>}
+ */
+export async function loadConfig(rootDir) {
+  const config = await getChocolaConfig(rootDir);
+  const bundleConfig = config.bundle || {};
+
+  const srcDir = bundleConfig.srcDir || "src";
+  const outDir = bundleConfig.outDir || "dist";
+  const libDir = bundleConfig.libDir || "lib";
+  const emptyOutDir = bundleConfig.emptyOutDir !== false;
+
+  logConfigWarnings(bundleConfig, emptyOutDir);
+
+  return { srcDir, outDir, libDir, emptyOutDir };
+}
+
+function logConfigWarnings(bundleConfig, emptyOutDir) {
+  if (!bundleConfig.srcDir) {
+    console.warn(
+      chalk.bold.yellow("WARNING!"),
+      'srcDir not defined in chocola.config.json file: using default "src" directory.'
+    );
+  }
+
+  if (!bundleConfig.outDir) {
+    console.warn(
+      chalk.bold.yellow("WARNING!"),
+      'outDir not defined in chocola.config.json file: using default "dist" directory.'
+    );
+  }
+
+  if (!bundleConfig.libDir) {
+    console.warn(
+      chalk.bold.yellow("WARNING!"),
+      'libDir not defined in chocola.config.json file: using default "lib" directory.'
+    );
+  }
+
+  console.log(`> using emptyOutDir = ${emptyOutDir}`);
+}
+
+/**
+ * Resolves all path directories based on configuration
+ * @param {import("fs").PathLike} rootDir
+ * @param {object} config
+ * @returns {object}
+ */
+export function resolvePaths(rootDir, config) {
+  return {
+    outDir: path.join(rootDir, config.outDir),
+    src: path.join(rootDir, config.srcDir),
+    components: path.join(rootDir, config.srcDir, config.libDir),
+  };
+}

package/compiler/dom-processor.js

@@ -0,0 +1,96 @@
+import { JSDOM } from "jsdom";
+import { promises as fs } from "fs";
+import path from "path";
+import { throwError } from "./utils.js";
+import { readMyFile } from "./fs.js";
+
+/**
+ * Creates a JSDOM instance from source index file
+ * @param {string} srcIndexContent
+ * @returns {JSDOM}
+ */
+export function createDOM(srcIndexContent) {
+  return new JSDOM(srcIndexContent);
+}
+
+/**
+ * Validates that the index file has an <app> root element
+ * @param {Document} doc
+ * @throws {Error} if <app> element not found
+ */
+export function validateAppContainer(doc) {
+  const appContainer = doc.querySelector("app");
+  if (!appContainer) {
+    throwError("Index page must have an <app> element");
+  }
+  return appContainer;
+}
+
+/**
+ * Extracts all child elements from app container
+ * @param {Element} appContainer
+ * @returns {Element[]}
+ */
+export function getAppElements(appContainer) {
+  return Array.from(appContainer.querySelectorAll("*"));
+}
+
+/**
+ * Extracts context attributes from element (ctx.* attributes)
+ * @param {Element} element
+ * @returns {object}
+ */
+export function extractContextFromElement(element) {
+  const ctx = {};
+  for (const attr of element.attributes) {
+    if (attr.name.startsWith("ctx.")) {
+      const key = attr.name.slice(4);
+      ctx[key] = attr.value;
+    }
+  }
+  return ctx;
+}
+
+/**
+ * Serializes and formats DOM to pretty HTML
+ * @param {JSDOM} dom
+ * @returns {string}
+ */
+export async function serializeDOM(dom) {
+  const beautify = (await import("js-beautify")).default;
+  const finalHtml = dom.serialize();
+  return beautify.html(finalHtml, { indent_size: 2 });
+}
+
+/**
+ * Writes the final HTML to output directory
+ * @param {string} html
+ * @param {import("fs").PathLike} outDirPath
+ */
+export async function writeHTMLOutput(html, outDirPath) {
+  await fs.writeFile(path.join(outDirPath, "index.html"), html);
+}
+
+/**
+ * Gets all stylesheet and icon links from document
+ * @param {Document} doc
+ * @returns {{stylesheets: HTMLLinkElement[], icons: HTMLLinkElement[]}}
+ */
+export function getAssetLinks(doc) {
+  const docLinks = Array.from(doc.querySelectorAll("link"));
+  const stylesheets = docLinks.filter(link => link.rel === "stylesheet");
+  const icons = docLinks.filter(link => link.rel === "icon");
+  return { stylesheets, icons };
+}
+
+/**
+ * Appends a script element to document body
+ * @param {Document} doc
+ * @param {string} filename
+ */
+export function appendRuntimeScript(doc, filename) {
+  const runtimeScriptEl = doc.createElement("script");
+  runtimeScriptEl.type = "module";
+  runtimeScriptEl.src = "./" + filename;
+  doc.body.appendChild(runtimeScriptEl);
+}