chocola 1.1.20 → 1.1.21

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);
+}

package/compiler/fs.js

@@ -1,20 +1,31 @@
 import { promises as fs } from "fs";
 import { throwError } from "./utils.js";
 
+/**
+ * Reads a file and returns its contents as a UTF-8 string
+ * @param {import("fs").PathLike} filePath - Path to the file
+ * @returns {Promise<string>} - File contents
+ * @throws {Error} - If file cannot be read
+ */
 export async function readMyFile(filePath) {
-    try {
-        const data = await fs.readFile(filePath, "utf-8");
-        return data;
-    } catch (error) {
-        throwError(`Got an error trying to read the file: ${error.message}`);
-    }
+  try {
+    const data = await fs.readFile(filePath, "utf-8");
+    return data;
+  } catch (error) {
+    throwError(`Got an error trying to read the file: ${error.message}`);
+  }
 }
 
+/**
+ * Checks if a file exists
+ * @param {import("fs").PathLike} filePath - Path to check
+ * @returns {Promise<boolean>} - True if file exists, false otherwise
+ */
 export async function checkFile(filePath) {
-    try {
-        await fs.access(filePath);
-        return true;
-    } catch {
-        return false;
-    }
+  try {
+    await fs.access(filePath);
+    return true;
+  } catch {
+    return false;
+  }
 }

package/compiler/index.js

@@ -1,27 +1,48 @@
-import { throwError, genRandomId, incrementAlfabet, isWebLink } from "./utils.js";
-import { JSDOM } from "jsdom";
 import path from "path";
 import { promises as fs } from "fs";
-import { copyResources, getComponents, getSrcIndex, processIcons, processStylesheet } from "./pipeline.js";
-import chalk from 'chalk';
-import beautify from "js-beautify";
-import { getChocolaConfig } from "../utils.js";
-
+import chalk from "chalk";
+
+// Configuration
+import { loadConfig, resolvePaths } from "./config.js";
+
+// DOM Processing
+import {
+  createDOM,
+  validateAppContainer,
+  getAppElements,
+  getAssetLinks,
+  appendRuntimeScript,
+  serializeDOM,
+  writeHTMLOutput,
+} 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 {
+  copyResources,
+  getComponents,
+  getSrcIndex,
+  processIcons,
+  processStylesheet,
+} from "./pipeline.js";
+
+
+// ===== Logging & Banners =====
 
 const logSeparation = chalk.yellow(`
 ________________________________________________________________________
 ========================================================================
         `);
 
-/**
- * Compiles a static build of your Chocola project from the directory provided.
- * @param {import("fs").PathLike} __rootdir 
- * @param {string} __srcdir 
- */
-export default async function runtime(__rootdir) {
-    console.log(chalk.bold.hex("#945e33")(`\n                     RUNNING CHOCOLA BUNDLER`))
-    console.log(logSeparation);
-    console.log(chalk.hex("#945e33")(`
+function logBanner() {
+  console.log(chalk.bold.hex("#945e33")(`\n                     RUNNING CHOCOLA BUNDLER`));
+  console.log(logSeparation);
+  console.log(
+    chalk.hex("#945e33")(`
 
 
      ▄████▄   ██░ ██  ▒█████   ▄████▄   ▒█████   ██▓    ▄▄▄      
@@ -30,171 +51,124 @@ export default async function runtime(__rootdir) {
      ▒▓▓▄ ▄██▒░▓█ ░██ ▒██   ██░▒▓▓▄ ▄██▒▒██   ██░▒██░   ░██▄▄▄▄██ 
      ▒ ▓███▀ ░░▓█▒░██▓░ ████▓▒░▒ ▓███▀ ░░ ████▓▒░░██████▒▓█   ▓██▒
      ░ ░▒ ▒  ░ ▒ ░░▒░▒░ ▒░▒░▒░ ░ ░▒ ▒  ░░ ▒░▒░▒░ ░ ▒░▓  ░▒▒   ▓▒█░
-     ░  ▒    ▒ ░▒░ ░  ░ ▒ ▒░   ░  ▒     ░ ▒ ▒░ ░ ░ ▒  ░ ▒   ▒▒ ░
-     ░         ░  ░░ ░░ ░ ░ ▒  ░        ░ ░ ░ ▒    ░ ░    ░   ▒   
+     ░  ▒    ▒ ░▒░ ░  ░ ░ ▒ ▒░   ░  ▒     ░ ░ ▒░ ░ ░ ▒  ░ ░   ▒▒ ░
+     ░         ░  ░░ ░░ ░ ░ ░ ▒  ░        ░ ░ ░ ░ ▒    ░ ░    ░   ▒   
      ░ ░       ░  ░  ░    ░ ░  ░ ░          ░ ░      ░  ░     ░  ░
     ░                         ░                                  
 
 
-        `));
-    let __srcdir = "src";
-    let __outDir = "dist";
-    let __libDir = "lib";
-    let __emptyOutDir = true;
-
-    const config = await getChocolaConfig(__rootdir);
-    const bundleConfig = config.bundle;
-
-    if (bundleConfig.srcDir) { __srcdir = bundleConfig.srcDir }
-    else { console.warn(chalk.bold.yellow("WARNING!"), 'srcDir not defined in chocola.config.json file: using default "src" directory.') }
-
-    if (bundleConfig.outDir) { __outDir = bundleConfig.outDir }
-    else { console.warn(chalk.bold.yellow("WARNING!"), 'outDir not defined in chocola.config.json file: using default "dist" directory.') }
-
-    if (bundleConfig.libDir) { __libDir = bundleConfig.libDir }
-    else { console.warn(chalk.bold.yellow("WARNING!"), 'libDir not defined in chocola.config.json file: using default "lib" directory.') }
-
-    if (bundleConfig.emptyOutDir) {
-        __emptyOutDir = bundleConfig.emptyOutDir;
-        console.log(`> using emptyOutDir = ${__emptyOutDir}`);
-    } else {
-        console.log(`> using default emptyOutDir = ${__emptyOutDir}`);
-    }
-
-    console.log(logSeparation);
-
-    const outDirPath = path.join(__rootdir, __outDir);
-    const srcPath = path.join(__rootdir, __srcdir);
-    const srcComponents = path.join(srcPath, __libDir);
-
-    if (__emptyOutDir) {
-        await fs.rm(path.join(outDirPath), { recursive: true, force: true });
-        await fs.mkdir(path.join(outDirPath));
-    }
-
-    let indexFiles = await getSrcIndex(srcPath);
-    let srcHtmlFile = indexFiles.srcHtmlFile;
-    let srcChocoFile = indexFiles.srcChocoFile;
-
-    console.log(`       LOADING COMPONENTS`)
-
-    const foundComponents = await getComponents(srcComponents);
-
-    let loadedComponents = foundComponents.loadedComponents;
-    let notDefComps = foundComponents.notDefComps;
-
-    const srcDirData = {
-        index: srcHtmlFile || srcChocoFile,
-        components: foundComponents.componentsLib,
-    };
-
-    console.log(chalk.bold.green(">"), "Components found in", chalk.green.underline(srcComponents) + ":");
-    console.log("   ", srcDirData.components, "\n");
-
-    if (notDefComps.length > 0) {
-        console.warn(chalk.bold.yellow("WARNING!"), "The following components don't include a default export:");
-        console.log("   ", notDefComps);
-    }
-
-    console.log(logSeparation);
-    console.log(`       BUNDLING STATIC BUILD`);
-    console.log(chalk.bold.green(">"), "Creating Chocola static build in directory", chalk.green.underline(outDirPath) + "\n");
-    console.log(logSeparation);
-
-    const dom = new JSDOM(srcDirData.index);
-    const doc = dom.window.document;
-    const appContainer = doc.querySelector("app");
-
-    if (!appContainer) {
-        throwError("Index page must have an " + chalk.blue("<app>") + " element");
-    }
-
-    const appElements = Array.from(appContainer.querySelectorAll('*'));
-
-    let runtimeChunks = [];
-    let runtimeScript = "";
-    let compIdColl = [];
-    let letter;
-
-    appElements.forEach(el => {
-        const tagName = el.tagName.toLowerCase();
-        const compName = tagName + ".js";
-
-        const ctx = {};
-        for (const attr of el.attributes) {
-            if (attr.name.startsWith("ctx.")) {
-                const key = attr.name.slice(4);
-                ctx[key] = attr.value;
-            }
-        }
-
-        const instance = loadedComponents.get(compName);
-        if (!instance || instance === undefined) return;
-        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) {
-                    let script;
-                    let effects;
-                    const compId = "chid-" + genRandomId(compIdColl);
-                    firstChild.setAttribute("chid", compId);
-                    instance.script && (script = instance.script.toString())
-
-                    if (!letter) {
-                        letter = "a";
-                    } else {
-                        letter = incrementAlfabet(letter);
-                    }
-
-                    script = script.replace(/RUNTIME/g, `${letter}RUNTIME`);
-
-                    runtimeChunks.push(`
-const ${letter} = document.querySelector('[chid="${compId}"]');
-${script}
-${letter}RUNTIME(${letter}, ${JSON.stringify(ctx)});`);
-                }
-            }
-            el.replaceWith(fragment);
-        } else {
-            console.warn(chalk.yellow(`${compName} component could not be loaded`));
-        }
-    });
-
-    runtimeScript = runtimeChunks.join("\n");
-
-    let fileIds = [];
-
-    const docLinks = Array.from(doc.querySelectorAll("link"));
-
-    for (const link of docLinks) {
-        const rel = link.rel;
-        if (rel === "stylesheet") await processStylesheet(link, __rootdir, __srcdir, outDirPath, fileIds);
-        if (rel === "icon") await processIcons(link, __rootdir, __srcdir, outDirPath, fileIds)
-    }
-
-
-    const runtimeFilename = "run-" + genRandomId(fileIds, 6) + ".js";
-    const runtimeFileContents = `document.addEventListener("DOMContentLoaded", () => {${runtimeScript}})`;
-    await fs.writeFile(path.join(outDirPath, runtimeFilename), runtimeFileContents);
-    const runtimeScriptEl = doc.createElement("script");
-    runtimeScriptEl.type = "module";
-    runtimeScriptEl.src = "./" + runtimeFilename;
-    doc.body.appendChild(runtimeScriptEl);
-    const finalHtml = dom.serialize();
-    const prettyHtml = beautify.html(finalHtml, { indent_size: 2 });
-
-    await fs.writeFile(path.join(outDirPath, "index.html"), prettyHtml);
-
-    await copyResources(__rootdir, __srcdir, outDirPath);
-
-    console.log(`
+        `)
+  );
+}
+
+function logSuccess(outDirPath) {
+  console.log(`
               ▄▄  ▄▄▄  ▄▄▄▄    ▄▄▄▄   ▄▄▄  ▄▄  ▄▄ ▄▄▄▄▄  ██ 
               ██ ██▀██ ██▄██   ██▀██ ██▀██ ███▄██ ██▄▄   ██ 
             ▄▄█▀ ▀███▀ ██▄█▀   ████▀ ▀███▀ ██ ▀██ ██▄▄▄  ▄▄ 
                                                 
         `);
-    console.log(chalk.bold.green(">"), "Project bundled succesfully at", chalk.green.underline(outDirPath) + "\n\n");
+  console.log(
+    chalk.bold.green(">"),
+    "Project bundled succesfully at",
+    chalk.green.underline(outDirPath) + "\n\n"
+  );
+}
+
+// ===== Directory Setup =====
+
+async function setupOutputDirectory(outDirPath, emptyOutDir) {
+  if (emptyOutDir) {
+    await fs.rm(outDirPath, { recursive: true, force: true });
+    await fs.mkdir(outDirPath);
+  }
+}
+
+// ===== Component Loading =====
+
+async function loadAndDisplayComponents(srcComponentsPath) {
+  const foundComponents = await getComponents(srcComponentsPath);
+  const { loadedComponents, notDefComps, componentsLib } = foundComponents;
+
+  console.log(`       LOADING COMPONENTS`);
+  console.log(chalk.bold.green(">"), "Components found in", chalk.green.underline(srcComponentsPath) + ":");
+  console.log("   ", componentsLib, "\n");
+
+  if (notDefComps.length > 0) {
+    console.warn(chalk.bold.yellow("WARNING!"), "The following components don't include a default export:");
+    console.log("   ", notDefComps);
+  }
+
+  return loadedComponents;
+}
+
+// ===== Asset Processing =====
+
+async function processAssets(doc, rootDir, srcDir, outDirPath) {
+  const { stylesheets, icons } = getAssetLinks(doc);
+  const fileIds = [];
+
+  for (const link of stylesheets) {
+    await processStylesheet(link, rootDir, srcDir, outDirPath, fileIds);
+  }
+
+  for (const link of icons) {
+    await processIcons(link, rootDir, srcDir, outDirPath, fileIds);
+  }
+}
+
+// ===== Main Compilation Function =====
+
+/**
+ * Compiles a static build of your Chocola project from the directory provided.
+ * @param {import("fs").PathLike} rootDir
+ */
+export default async function runtime(rootDir) {
+  logBanner();
+
+  // Load Configuration
+  const config = await loadConfig(rootDir);
+  const paths = resolvePaths(rootDir, config);
+  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);
+  console.log(logSeparation);
+
+  // Create and Validate DOM
+  console.log(`       BUNDLING STATIC BUILD`);
+  console.log(chalk.bold.green(">"), "Creating Chocola static build in directory", chalk.green.underline(paths.outDir) + "\n");
+  console.log(logSeparation);
+
+  const dom = createDOM(srcIndexContent);
+  const doc = dom.window.document;
+  const appContainer = validateAppContainer(doc);
+  const appElements = getAppElements(appContainer);
+
+  // Process Components
+  const { runtimeScript } = processAllComponents(appElements, loadedComponents);
+
+  // Generate Runtime File
+  const runtimeFilename = await generateRuntimeScript(runtimeScript, paths.outDir);
+
+  // Process Assets (stylesheets, icons)
+  await processAssets(doc, rootDir, config.srcDir, paths.outDir);
+
+  // Finalize HTML
+  appendRuntimeScript(doc, runtimeFilename);
+  const html = await serializeDOM(dom);
+  await writeHTMLOutput(html, paths.outDir);
+
+  // Copy Resources
+  await copyResources(rootDir, config.srcDir, paths.outDir);
+
+  // Success Message
+  logSuccess(paths.outDir);
 }

package/compiler/pipeline.js

@@ -4,146 +4,179 @@ import { readMyFile, checkFile } from "./fs.js";
 import { JSDOM } from "jsdom";
 import path from "path";
 
+// ===== Component Loading =====
+
 /**
- * Returns a collection with the found components, the loaded ones (unpacked) and the undefined ones.
- * @param {import("node:fs").PathLike} libDir 
- * @returns {{
- * componentsLib: PathLike[],
- * loadedComponents: Object[],
- * notDefComps: PathLike[]
- * }}
+ * Discovers and loads all components from a library directory
+ * Components are JavaScript files that start with an uppercase letter
+ * They must have a default export that is a function
+ * @param {import("node:fs").PathLike} libDir - Directory containing component files
+ * @returns {Promise<{
+ *   componentsLib: string[],
+ *   loadedComponents: Map<string, object>,
+ *   notDefComps: string[]
+ * }>}
+ * @throws {Error} if libDir cannot be found
  */
 export async function getComponents(libDir) {
-    try {
-        let componentsLib = [];
-        let loadedComponents = new Map();
-        let notDefComps = [];
+  try {
+    let componentsLib = [];
+    let loadedComponents = new Map();
+    let notDefComps = [];
 
-        const components = await fs.readdir(libDir);
+    const components = await fs.readdir(libDir);
 
-        if (!components) throw Error(`The specified components folder ${libDir} could not be found.`)
-
-        for (const comp of components) {
-            if (!comp.endsWith(".js") || comp[0] !== comp[0].toUpperCase()) continue;
+    if (!components) {
+      throw Error(`The specified components folder ${libDir} could not be found.`);
+    }
 
-            componentsLib.push(comp);
+    for (const comp of components) {
+      // Only load .js files that start with uppercase (component convention)
+      if (!comp.endsWith(".js") || comp[0] !== comp[0].toUpperCase()) continue;
 
-            const module = await loadWithAssets(path.join(libDir, comp));
+      componentsLib.push(comp);
 
-            if (typeof module.default !== "function") {
-                notDefComps.push(comp);
-                continue;
-            }
+      const module = await loadWithAssets(path.join(libDir, comp));
 
-            const instance = module.default();
+      if (typeof module.default !== "function") {
+        notDefComps.push(comp);
+        continue;
+      }
 
-            if (instance.bodyPath) {
-                instance.body = await fs.readFile(
-                    path.resolve(libDir, instance.bodyPath),
-                    "utf8"
-                );
-            }
+      const instance = module.default();
 
-            loadedComponents.set(comp.toLowerCase(), instance);
-        }
+      // Load external body template if specified
+      if (instance.bodyPath) {
+        instance.body = await fs.readFile(
+          path.resolve(libDir, instance.bodyPath),
+          "utf8"
+        );
+      }
 
-        return { componentsLib, loadedComponents, notDefComps };
-    } catch (err) {
-        throwError(err)
+      loadedComponents.set(comp.toLowerCase(), instance);
     }
+
+    return { componentsLib, loadedComponents, notDefComps };
+  } catch (err) {
+    throwError(err);
+  }
 }
 
+// ===== Index File Loading =====
+
 /**
- * Returns the Chocola project index HTML or .chocola file contents.
- * If both HTML and .choco index file exist, it will throw an error.
- * Note: It throws an error when using .choco files since it is not supported yet.
- * @param {PathLike} srcPath 
- * @returns {{
- * srcHtmlFile: string | null,
- * srcChocoFile: string | null
- * }}
+ * Loads the project index file (HTML or .choco)
+ * If both HTML and .choco files exist, throws an error
+ * @param {import("fs").PathLike} srcPath - Source directory
+ * @returns {Promise<{
+ *   srcHtmlFile: string | null,
+ *   srcChocoFile: string | null
+ * }>}
+ * @throws {Error} if both index files exist or .choco is used (not yet supported)
  */
 export async function getSrcIndex(srcPath) {
-    const srcHtmlPath = path.join(srcPath, "index.html");
-    const srcChocoPath = path.join(srcPath, "index.choco");
+  const srcHtmlPath = path.join(srcPath, "index.html");
+  const srcChocoPath = path.join(srcPath, "index.choco");
 
-    const htmlExists = await checkFile(srcHtmlPath);
-    const chocoExists = await checkFile(srcChocoPath);
+  const htmlExists = await checkFile(srcHtmlPath);
+  const chocoExists = await checkFile(srcChocoPath);
 
-    let srcHtmlFile = null;
-    let srcChocoFile = null;
+  let srcHtmlFile = null;
+  let srcChocoFile = null;
 
-    if (htmlExists && chocoExists) {
-        throwError("Can't have both .choco and .html source index files at a time: please remove one of the two");
-    }
+  if (htmlExists && chocoExists) {
+    throwError(
+      "Can't have both .choco and .html source index files at a time: please remove one of the two"
+    );
+  }
 
-    if (htmlExists) {
-        try {
-            srcHtmlFile = await readMyFile(srcHtmlPath);
-            return { srcHtmlFile: srcHtmlFile, srcChocoFile: srcChocoFile }
-        } catch (err) {
-            throwError(err);
-        }
+  if (htmlExists) {
+    try {
+      srcHtmlFile = await readMyFile(srcHtmlPath);
+      return { srcHtmlFile, srcChocoFile };
+    } catch (err) {
+      throwError(err);
     }
+  }
 
-    if (chocoExists) {
-        throwError(".choco files are not supported yet")
-    }
+  if (chocoExists) {
+    throwError(".choco files are not supported yet");
+  }
 }
 
+// ===== Asset Processing =====
+
 /**
- * Generates the new CSS files attached to the build index.html.
- * @param {HTMLLinkElement} link 
- * @param {PathLike} __rootdir 
- * @param {PathLike} __srcdir 
- * @param {PathLike} outDirPath 
- * @param {Array} fileIds 
+ * Processes stylesheet links: copies CSS files to output and updates link href
+ * @param {HTMLLinkElement} link - The link element to process
+ * @param {import("fs").PathLike} rootDir - Root project directory
+ * @param {string} srcDir - Source directory name
+ * @param {import("fs").PathLike} outDirPath - Output directory path
+ * @param {Array} fileIds - Array to track used file IDs
+ * @throws {Error} if stylesheet cannot be read or written
  */
-export async function processStylesheet(link, __rootdir, __srcdir, outDirPath, fileIds) {
-    try {
-        const href = link.href;
-        const stylesheetPath = path.join(__rootdir, __srcdir, href);
-        const css = await fs.readFile(stylesheetPath, { encoding: "utf8" });
-        const cssFileName = "css-" + genRandomId(fileIds, 6) + ".css";
-
-        await fs.writeFile(path.join(outDirPath, cssFileName), css);
-
-        link.setAttribute("href", "./" + cssFileName);
-    } catch (err) {
-        throwError(err)
-    }
+export async function processStylesheet(link, rootDir, srcDir, outDirPath, fileIds) {
+  try {
+    const href = link.href;
+    const stylesheetPath = path.join(rootDir, srcDir, href);
+    const css = await fs.readFile(stylesheetPath, { encoding: "utf8" });
+    const cssFileName = "css-" + genRandomId(fileIds, 6) + ".css";
+
+    await fs.writeFile(path.join(outDirPath, cssFileName), css);
+    link.setAttribute("href", "./" + cssFileName);
+  } catch (err) {
+    throwError(err);
+  }
 }
 
-export async function processIcons(link, __rootdir, __srcdir, outDirPath) {
-    try {
-        const href = link.href;
-        const iconPath = path.join(__rootdir, __srcdir, href);
-        await fs.copyFile(iconPath, path.join(outDirPath, href));
-    } catch (err) {
-        throwError(err)
-    }
+/**
+ * Processes icon links: copies icon files to output directory
+ * @param {HTMLLinkElement} link - The link element to process
+ * @param {import("fs").PathLike} rootDir - Root project directory
+ * @param {string} srcDir - Source directory name
+ * @param {import("fs").PathLike} outDirPath - Output directory path
+ * @throws {Error} if icon cannot be copied
+ */
+export async function processIcons(link, rootDir, srcDir, outDirPath) {
+  try {
+    const href = link.href;
+    const iconPath = path.join(rootDir, srcDir, href);
+    await fs.copyFile(iconPath, path.join(outDirPath, href));
+  } catch (err) {
+    throwError(err);
+  }
 }
 
-export async function copyResources(__rootdir, __srcdir, outDirPath) {
-    try {
-        const newIndex = await fs.readFile(path.join(outDirPath, "index.html"), "utf8");
-        const newDoc = new JSDOM(newIndex);
-        const newElements = Array.from(newDoc.window.document.querySelectorAll("*"));
-
-        for (const el of newElements) {
-            if (el.tagName === "LINK" || el.tagName === "SCRIPT") continue;
-
-            const src = el.getAttribute("src") || el.getAttribute("href");
-
-            if (src && !isWebLink(src)) {
-                const srcPath = path.join(__rootdir, __srcdir, src);
-                const destPath = path.join(outDirPath, src);
-
-                await fs.mkdir(path.dirname(destPath), { recursive: true });
-                await fs.copyFile(srcPath, destPath);
-            }
-        }
-    } catch (err) {
-        throwError(err)
+/**
+ * Copies all local resources (images, fonts, etc.) to output directory
+ * Excludes web links and script/link tags
+ * @param {import("fs").PathLike} rootDir - Root project directory
+ * @param {string} srcDir - Source directory name
+ * @param {import("fs").PathLike} outDirPath - Output directory path
+ * @throws {Error} if resources cannot be copied
+ */
+export async function copyResources(rootDir, srcDir, outDirPath) {
+  try {
+    const newIndex = await fs.readFile(path.join(outDirPath, "index.html"), "utf8");
+    const newDoc = new JSDOM(newIndex);
+    const newElements = Array.from(newDoc.window.document.querySelectorAll("*"));
+
+    for (const el of newElements) {
+      // Skip LINK and SCRIPT tags as they're already processed
+      if (el.tagName === "LINK" || el.tagName === "SCRIPT") continue;
+
+      const src = el.getAttribute("src") || el.getAttribute("href");
+
+      // Only copy local resources, not external web links
+      if (src && !isWebLink(src)) {
+        const srcPath = path.join(rootDir, srcDir, src);
+        const destPath = path.join(outDirPath, src);
+
+        await fs.mkdir(path.dirname(destPath), { recursive: true });
+        await fs.copyFile(srcPath, destPath);
+      }
     }
+  } catch (err) {
+    throwError(err);
+  }
 }

package/compiler/runtime-generator.js

@@ -0,0 +1,19 @@
+import { promises as fs } from "fs";
+import path from "path";
+import { genRandomId } from "./utils.js";
+
+/**
+ * Generates a runtime script file and returns its filename
+ * @param {string} runtimeScript - The JavaScript code for runtime
+ * @param {import("fs").PathLike} outDirPath
+ * @returns {Promise<string>} - filename of the generated runtime script
+ */
+export async function generateRuntimeScript(runtimeScript, outDirPath) {
+  const fileIds = [];
+  const runtimeFilename = "run-" + genRandomId(fileIds, 6) + ".js";
+  const runtimeFileContents = `document.addEventListener("DOMContentLoaded", () => {${runtimeScript}})`;
+
+  await fs.writeFile(path.join(outDirPath, runtimeFilename), runtimeFileContents);
+
+  return runtimeFilename;
+}

package/compiler/utils.js

@@ -3,68 +3,103 @@ import path from "path";
 import { pathToFileURL } from "url";
 import chalk from "chalk";
 
+/**
+ * Throws a formatted error message and exits
+ * @param {string|Error} err - Error message or Error object
+ * @throws {Error}
+ */
 export function throwError(err) {
-    console.log(chalk.red.bold("Error!"), "A fatal error has ocurred:\n");
-    throw new Error(err)
+  console.log(chalk.red.bold("Error!"), "A fatal error has occurred:\n");
+  throw new Error(err);
 }
 
 /**
- * Returns the given module function adjusted to work with NPM without any dependency.
- * @param {import("fs").PathLike} filePath 
- * @returns {Function}
+ * Loads a JavaScript module and inlines asset imports (HTML/CSS files)
+ * This allows components to import external template files as strings
+ * @param {import("fs").PathLike} filePath - Path to the JavaScript file
+ * @returns {Promise<object>} - The imported module
+ * @example
+ * // Component with asset import
+ * import template from "./button.html";
+ * export default function Button() { return { body: template }; }
  */
 export async function loadWithAssets(filePath) {
-    let code = await fs.readFile(filePath, "utf8");
-
-    const importRegex = /import\s+(\w+)\s+from\s+["'](.+?\.(html|css))["'];?/g;
+  let code = await fs.readFile(filePath, "utf8");
 
-    let match;
-    while ((match = importRegex.exec(code))) {
-        const varName = match[1];
-        const relPath = match[2];
+  // Find all `import varName from "*.html"` or `import varName from "*.css"`
+  const importRegex = /import\s+(\w+)\s+from\s+["'](.+?\.(html|css))["'];?/g;
 
-        const absPath = path.resolve(path.dirname(filePath), relPath);
-        let content = await fs.readFile(absPath, "utf8");
+  let match;
+  while ((match = importRegex.exec(code))) {
+    const varName = match[1];
+    const relPath = match[2];
 
-        const replacement = `const ${varName} = ${JSON.stringify(content)};`;
+    // Resolve relative path and read the asset file
+    const absPath = path.resolve(path.dirname(filePath), relPath);
+    let content = await fs.readFile(absPath, "utf8");
 
-        code = code.replace(match[0], replacement);
-    }
+    // Replace the import with a const assignment of the file contents
+    const replacement = `const ${varName} = ${JSON.stringify(content)};`;
+    code = code.replace(match[0], replacement);
+  }
 
-    const dataUrl =
-        "data:text/javascript;base64," +
-        Buffer.from(code).toString("base64");
+  // Convert to data URL and import dynamically to avoid filesystem restrictions
+  const dataUrl =
+    "data:text/javascript;base64," +
+    Buffer.from(code).toString("base64");
 
-    const mod = await import(dataUrl);
-    return mod;
+  const mod = await import(dataUrl);
+  return mod;
 }
 
-export function genRandomId(compIdColl, length = 10) {
-    const id = Math.random().toString(36).substring(2, length + 2);
-    if (compIdColl.includes(id)) { return genRandomCompId() }
-    else {
-        compIdColl.push(id);
-        return id
-    }
-};
+/**
+ * Generates a random ID string
+ * @param {Array} collection - Array to track used IDs (prevents duplicates)
+ * @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);
+  if (collection.includes(id)) {
+    return genRandomId(collection, length);
+  } else {
+    collection.push(id);
+    return id;
+  }
+}
 
+/**
+ * Increments a letter or sequence of letters like Excel columns (a → b, z → aa)
+ * @param {string} letters - Letter(s) to increment
+ * @returns {string} - Incremented letter(s)
+ * @example
+ * incrementAlfabet("a") // "b"
+ * incrementAlfabet("z") // "aa"
+ */
 export function incrementAlfabet(letters) {
-    const alfabet = "abcdefghijklmnopqrstuvwxyz";
-    let arr = letters.split("");
-    let i = arr.length - 1;
-    while (i >= 0) {
-        let pos = alfabet.indexOf(arr[i]);
-        if (pos < 25) {
-            arr[i] = alfabet[pos + 1];
-            return arr.join("");
-        } else {
-            arr[i] = "a";
-            i--;
-        }
+  const alfabet = "abcdefghijklmnopqrstuvwxyz";
+  let arr = letters.split("");
+  let i = arr.length - 1;
+
+  while (i >= 0) {
+    let pos = alfabet.indexOf(arr[i]);
+    if (pos < 25) {
+      arr[i] = alfabet[pos + 1];
+      return arr.join("");
+    } else {
+      arr[i] = "a";
+      i--;
     }
-    return "a" + arr.join("");
+  }
+
+  return "a" + arr.join("");
 }
 
+/**
+ * Checks if a string is a valid HTTP/HTTPS URL
+ * @param {string} str - String to check
+ * @returns {boolean} - True if valid web link, false otherwise
+ */
 export function isWebLink(str) {
   try {
     const url = new URL(str);

package/dev/index.js

@@ -32,13 +32,38 @@ export async function serve(__rootdir) {
     const extname = String(path.extname(filePath)).toLowerCase();
     const mimeTypes = {
       ".html": "text/html",
+      ".htm": "text/html",
       ".js": "text/javascript",
       ".css": "text/css",
+      ".csv": "text/csv",
       ".json": "application/json",
       ".png": "image/png",
       ".jpg": "image/jpg",
+      ".jpeg": "image/jpeg",
+      ".bmp": "image/bmp",
       ".gif": "image/gif",
-      ".svg": "svg+xml"
+      ".svg": "image/svg+xml",
+      ".icon": "image/vnd.microsoft.icon",
+      ".pdf": "application/pdf",
+      ".mp3": "audio/mpeg",
+      ".md": "text/markdown",
+      ".mp4": "video/mp4",
+      ".mpeg": "video/mpeg",
+      ".oga": "audio/ogg",
+      ".ogv": "video/ogg",
+      ".php": "application/x-httpd-php",
+      ".rar": "application/vnd.rar",
+      ".tar": "application/x-tar",
+      ".ttf": "font/ttf",
+      ".txt": "text/plain",
+      ".wav": "audio/wav",
+      ".weba": "audio/webm",
+      ".webm": "video/webm",
+      ".webmanifest": "application/manifest+json",
+      ".webp": "image/webp",
+      ".xhtml": "application/xhtml+xml",
+      ".xml": "application/xml",
+      ".zip": "application/zip"
     };
 
     const contentType = mimeTypes[extname] || "application/octet-stream";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "chocola",
-  "version": "1.1.20",
+  "version": "1.1.21",
   "description": "Chocola pipeline for web apps.",
   "keywords": [
     "web",
@@ -20,8 +20,9 @@
   },
   "dependencies": {
     "chalk": "^5.6.2",
-    "jsdom": "^27.4.0",
-    "js-beautify": "^1.15.4"
+    "chocola": "^1.1.20",
+    "js-beautify": "^1.15.4",
+    "jsdom": "^27.4.0"
   },
   "devDependencies": {
     "js-beautify": "^1.15.4"