eleva 1.1.0-alpha → 1.2.1-alpha

package/README.md

@@ -1,7 +1,6 @@
-# Eleva
+# Eleva 🚀
 
-**A minimalist, lightweight, pure vanilla JavaScript frontend runtime framework.**  
-_Built with love for native JavaScript—because sometimes, less really is more!_ 😊
+Pure JavaScript, Pure Performance, Simply Elegant.
 
 [![License](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
 [![Version](https://img.shields.io/npm/v/eleva.svg?style=flat)](https://www.npmjs.com/package/eleva)
@@ -10,12 +9,25 @@ _Built with love for native JavaScript—because sometimes, less really is more!
 [![Minified Size](https://badgen.net/bundlephobia/min/eleva@latest)](https://bundlephobia.com/package/eleva@latest)
 [![Gzipped Size](https://badgen.net/bundlephobia/minzip/eleva@latest)](https://bundlephobia.com/package/eleva@latest)
 
+<br>
+<br>
+
+<p align="center">
+  <img src="./docs/imgs/Eleva Logo.png" alt="Eleva Logo" width="50%">
+</p>
+
+<br>
+<br>
+
+**A minimalist, lightweight, pure vanilla JavaScript frontend runtime framework.**  
+_Built with love for native JavaScript—because sometimes, less really is more!_ 😊
+
 <!-- [![](https://data.jsdelivr.com/v1/package/npm/eleva/badge)](https://www.jsdelivr.com/package/npm/eleva) -->
 
-> **Stability Notice**: This is `v1.1.0-alpha` - APIs may change significantly until the stable release.  
+> **Stability Notice**: This is `v1.2.0-alpha` - APIs may change significantly until the stable release.  
 > Not recommended for production use yet. Follow the [versioning guide](#version-guide) for updates.
 
-**Version:** `1.1.0-alpha`
+**Version:** `1.2.0-alpha`
 
 Welcome to Eleva! This is my humble, experimental playground for a fresh approach to frontend development. Eleva was born out of my genuine passion for pure vanilla JavaScript—no frameworks, no bloat, just the power of native code. I hope you'll have fun exploring, testing, and contributing to make Eleva even better. 🚀
 
@@ -23,7 +35,7 @@ Welcome to Eleva! This is my humble, experimental playground for a fresh approac
 
 ## Table of Contents
 
-- [Eleva](#eleva)
+- [Eleva 🚀](#eleva-)
   - [Table of Contents](#table-of-contents)
   - [Introduction](#introduction)
   - [Design Philosophy](#design-philosophy)
@@ -127,9 +139,9 @@ Eleva is ideal for developers seeking a lightweight, flexible, and high-performa
 
 I believe in clear versioning that reflects the maturity of the project:
 
-- **Pre-release Versions (Alpha/Beta):** Early versions like `1.1.0-alpha` indicate the API is still evolving. Expect frequent updates and share your feedback!
+- **Pre-release Versions (Alpha/Beta):** Early versions like `1.2.0-alpha` indicate the API is still evolving. Expect frequent updates and share your feedback!
 - **Semantic Versioning:** Once stable, I’ll follow semantic versioning strictly to clearly communicate any breaking changes.
-- **Fresh Start:** This release (`1.1.0-alpha`) marks a significant update with new features and improvements.
+- **Fresh Start:** This release (`1.2.0-alpha`) marks a significant update with enhanced inline documentation, improved JSDoc annotations, and a refined mounting context that now includes an `emitter` property.
 
 ---
 
@@ -138,9 +150,9 @@ I believe in clear versioning that reflects the maturity of the project:
 I follow [Semantic Versioning (SemVer)](https://semver.org/):
 
 - **🔢 Major Version:** Breaking changes or major overhauls (e.g., from `1.0.0` to `2.0.0`).
-- **🔢 Minor Version:** New features in a backward-compatible manner (e.g., from `1.0.0` to `1.1.0`).
+- **🔢 Minor Version:** New features in a backward-compatible manner (e.g., from `1.1.0` to `1.2.0`).
 - **🔢 Patch Version:** Backward-compatible bug fixes and minor improvements (e.g., `1.0.1`).
-- **📌 Pre-release Identifiers:** Suffixes like `-alpha`, `-beta`, or `-rc` denote unstable releases (e.g., `1.1.0-alpha`).
+- **📌 Pre-release Identifiers:** Suffixes like `-alpha`, `-beta`, or `-rc` denote unstable releases (e.g., `1.2.0-alpha`).
 
 ---
 
@@ -148,7 +160,7 @@ I follow [Semantic Versioning (SemVer)](https://semver.org/):
 
 Eleva is crafted for performance:
 
-- **Lightweight:** Approximately ~4 KB minified and ~1.9 KB gzipped.
+- **Lightweight:** Approximately ~4 KB minified and ~1.8 KB gzipped.
 - **Efficient Reactivity:** Signal-based updates ensure only necessary DOM parts are updated.
 - **Optimized Diffing:** Renderer efficiently patches changes without the overhead of a virtual DOM.
 - **No Bloat:** Pure vanilla JavaScript with zero dependencies keeps your project nimble.
@@ -159,14 +171,16 @@ Eleva is crafted for performance:
 
 Preliminary benchmarks illustrate Eleva’s efficiency compared to popular frameworks:
 
-| Framework | Bundle Size (minified) | Initial Load Time | DOM Update Speed |
-| --------- | ---------------------- | ----------------- | ---------------- |
-| **Eleva** | **~4 KB**              | **~35 ms**        | **~2 ms**        |
-| React     | ~110 KB                | ~100 ms           | ~4 ms            |
-| Vue       | ~80 KB                 | ~80 ms            | ~3 ms            |
-| Angular   | ~500 KB                | ~250 ms           | ~6 ms            |
+| **Framework**                 | **Bundle Size** (KB) | **Initial Load Time** (ms) | **DOM Update Speed** (s) | **Peak Memory Usage** (KB) | **Overall Performance Score** (lower is better) |
+| ----------------------------- | -------------------- | -------------------------- | ------------------------ | -------------------------- | ----------------------------------------------- |
+| **Eleva** (Direct DOM)        | **1.8**              | **10**                     | **0.018**                | **0.25**                   | **3.02 (Best)**                                 |
+| **React** (Virtual DOM)       | 42                   | 40                         | 0.020                    | 0.25                       | 20.57                                           |
+| **Vue** (Reactive State)      | 33                   | 35                         | 0.021                    | 3.10                       | 17.78                                           |
+| **Angular** (Two-way Binding) | 80                   | 100                        | 0.021                    | 0.25                       | 45.07 (Slowest)                                 |
 
-> ⚠️ **Disclaimer:** Benchmarks are based on internal tests with a minimal counter component and may vary by project and environment.
+Detailed [Benchmark Metrics Report](BENCHMARK.md)
+
+> ⚠️ **Disclaimer:** Benchmarks are based on internal tests and may vary by project and environment.
 
 ---
 
@@ -226,8 +240,8 @@ app.component("HelloWorld", {
   template: ({ count }) => `
     <div>
       <h1>Hello, Eleva! 👋</h1>
-      <p>Count: ${count}</p>
-      <button @click="() => count++">Increment</button>
+      <p>Count: ${count.value}</p>
+      <button @click="() => count.value++">Increment</button>
     </div>
   `,
 });
@@ -236,6 +250,8 @@ app.component("HelloWorld", {
 app.mount(document.getElementById("app"), "HelloWorld");
 ```
 
+Interactive Demo: [CodePen](https://codepen.io/tarekraafat/pen/GgRrxdY?editors=1010)
+
 ### UMD Example
 
 Include Eleva via a script tag and use the global variable:
@@ -249,7 +265,7 @@ Include Eleva via a script tag and use the global variable:
   </head>
   <body>
     <div id="app"></div>
-    <script src="https://unpkg.com/eleva/dist/eleva.min.js"></script>
+    <script src="https://cdn.jsdelivr.net/npm/eleva/dist/eleva.min.js"></script>
     <script>
       const app = new Eleva("MyApp");
       app.component("HelloWorld", {
@@ -260,8 +276,8 @@ Include Eleva via a script tag and use the global variable:
         template: ({ count }) => `
           <div>
             <h1>Hello, Eleva! 👋</h1>
-            <p>Count: ${count}</p>
-            <button @click="() => count++">Increment</button>
+            <p>Count: ${count.value}</p>
+            <button @click="() => count.value++">Increment</button>
           </div>
         `,
       });
@@ -271,6 +287,8 @@ Include Eleva via a script tag and use the global variable:
 </html>
 ```
 
+Interactive Demo: [CodePen](https://codepen.io/tarekraafat/pen/jEOyzYN?editors=1010)
+
 ---
 
 ## API Reference
@@ -303,11 +321,11 @@ Include Eleva via a script tag and use the global variable:
 ### Renderer
 
 - **`patchDOM(container, newHtml)`**  
-  Efficiently update the DOM.
+  Efficiently updates the DOM.
 - **`diff(oldParent, newParent)`**  
-  Compare and update DOM trees.
+  Compares and updates DOM trees.
 - **`updateAttributes(oldEl, newEl)`**  
-  Sync element attributes.
+  Synchronizes element attributes.
 
 ### Eleva (Core)
 
@@ -319,7 +337,7 @@ Include Eleva via a script tag and use the global variable:
   Register a component.
 - **`.mount(container, compName, props)`**  
   Mount a component to the DOM.  
-  _Note:_ This method now expects a DOM element (not a CSS selector) and supports both global component names (strings) and direct component definitions (objects). It returns a Promise, ensuring consistent asynchronous handling.
+  _Note:_ The mounting context now includes an `emitter` property (the full event emitter instance) for simplified event handling. Use `context.emitter.on(...)` and `context.emitter.emit(...)` for event management.
 
 For detailed API documentation, please check the [docs](docs/index.md) folder.
 
@@ -348,7 +366,7 @@ I welcome developers to dive in and experiment with Eleva! Here’s how to get s
    npm run dev
    ```
 
-4. **Build for Production:**
+4. **Build for Production without TypeScript Declarations:**
 
    ```bash
    npm run build
@@ -361,6 +379,12 @@ I welcome developers to dive in and experiment with Eleva! Here’s how to get s
    npm run build:types:bundle
    ```
 
+6. **Build for Production with TypeScript Declarations:**
+
+   ```bash
+   npm run build:all
+   ```
+
 ---
 
 ## Testing
@@ -405,5 +429,5 @@ Eleva is open-source and available under the [MIT License](LICENSE).
 
 [Documentation](/docs/index.md) |
 [Examples](/examples) |
-[Changelog](/changelog.md) |
+[Changelog](/CHANGELOG.md) |
 [GitHub Discussions](https://github.com/TarekRaafat/eleva/discussions)

package/dist/eleva.d.ts

@@ -1,77 +1,25 @@
 /**
- * @class 🎙️ Emitter
- * @classdesc Robust inter-component communication with event bubbling.
- * Implements a basic publish-subscribe pattern for event handling, allowing components
- * to communicate through custom events.
- */
-declare class Emitter {
-    /** @type {Object.<string, Function[]>} */
-    events: {
-        [x: string]: Function[];
-    };
-    /**
-     * Registers an event handler for the specified event.
-     *
-     * @param {string} event - The name of the event.
-     * @param {function(...any): void} handler - The function to call when the event is emitted.
-     */
-    on(event: string, handler: (...args: any[]) => void): void;
-    /**
-     * Removes a previously registered event handler.
-     *
-     * @param {string} event - The name of the event.
-     * @param {function(...any): void} handler - The handler function to remove.
-     */
-    off(event: string, handler: (...args: any[]) => void): void;
-    /**
-     * Emits an event, invoking all handlers registered for that event.
-     *
-     * @param {string} event - The event name.
-     * @param {...any} args - Additional arguments to pass to the event handlers.
-     */
-    emit(event: string, ...args: any[]): void;
-}
-
-/**
- * @class 🎨 Renderer
- * @classdesc Handles DOM patching, diffing, and attribute updates.
- * Provides methods for efficient DOM updates by diffing the new and old DOM structures
- * and applying only the necessary changes.
- */
-declare class Renderer {
-    /**
-     * Patches the DOM of a container element with new HTML content.
-     *
-     * @param {HTMLElement} container - The container element to patch.
-     * @param {string} newHtml - The new HTML content to apply.
-     */
-    patchDOM(container: HTMLElement, newHtml: string): void;
-    /**
-     * Diffs two DOM trees (old and new) and applies updates to the old DOM.
-     *
-     * @param {HTMLElement} oldParent - The original DOM element.
-     * @param {HTMLElement} newParent - The new DOM element.
-     */
-    diff(oldParent: HTMLElement, newParent: HTMLElement): void;
-    /**
-     * Updates the attributes of an element to match those of a new element.
-     *
-     * @param {HTMLElement} oldEl - The element to update.
-     * @param {HTMLElement} newEl - The element providing the updated attributes.
-     */
-    updateAttributes(oldEl: HTMLElement, newEl: HTMLElement): void;
-}
-
-/**
+ * Defines the structure and behavior of a component.
  * @typedef {Object} ComponentDefinition
  * @property {function(Object<string, any>): (Object<string, any>|Promise<Object<string, any>>)} [setup]
- *           A setup function that initializes the component state and returns an object or a promise that resolves to an object.
+ *           Optional setup function that initializes the component's reactive state and lifecycle.
+ *           Receives props and context as an argument and should return an object containing the component's state.
+ *           Can return either a synchronous object or a Promise that resolves to an object for async initialization.
+ *
  * @property {function(Object<string, any>): string} template
- *           A function that returns the HTML template string for the component.
+ *           Required function that defines the component's HTML structure.
+ *           Receives the merged context (props + setup data) and must return an HTML template string.
+ *           Supports dynamic expressions using {{ }} syntax for reactive data binding.
+ *
  * @property {function(Object<string, any>): string} [style]
- *           An optional function that returns scoped CSS styles as a string.
+ *           Optional function that defines component-scoped CSS styles.
+ *           Receives the merged context and returns a CSS string that will be automatically scoped to the component.
+ *           Styles are injected into the component's container and only affect elements within it.
+ *
  * @property {Object<string, ComponentDefinition>} [children]
- *           An optional mapping of CSS selectors to child component definitions.
+ *           Optional object that defines nested child components.
+ *           Keys are CSS selectors that match elements in the template where child components should be mounted.
+ *           Values are ComponentDefinition objects that define the structure and behavior of each child component.
  */
 /**
  * @class 🧩 Eleva
@@ -88,24 +36,26 @@ declare class Eleva {
     constructor(name: string, config?: {
         [x: string]: any;
     });
-    /** @type {string} */
+    /** @type {string} The unique identifier name for this Eleva instance */
     name: string;
-    /** @type {Object<string, any>} */
+    /** @type {Object<string, any>} Optional configuration object for the Eleva instance */
     config: {
         [x: string]: any;
     };
-    /** @type {Object<string, ComponentDefinition>} */
+    /** @type {Object<string, ComponentDefinition>} Object storing registered component definitions by name */
     _components: {
         [x: string]: ComponentDefinition;
     };
-    /** @type {Array<Object>} */
-    _plugins: Array<Object>;
-    /** @private */
+    /** @private {Array<Object>} Collection of installed plugin instances */
+    private _plugins;
+    /** @private {string[]} Array of lifecycle hook names supported by the component */
     private _lifecycleHooks;
-    /** @private {boolean} */
+    /** @private {boolean} Flag indicating if component is currently mounted */
     private _isMounted;
-    emitter: Emitter;
-    renderer: Renderer;
+    /** @private {Emitter} Instance of the event emitter for handling component events */
+    private emitter;
+    /** @private {Renderer} Instance of the renderer for handling DOM updates and patching */
+    private renderer;
     /**
      * Integrates a plugin with the Eleva framework.
      *
@@ -171,9 +121,14 @@ declare class Eleva {
      */
     private _mountChildren;
 }
+/**
+ * Defines the structure and behavior of a component.
+ */
 type ComponentDefinition = {
     /**
-     * A setup function that initializes the component state and returns an object or a promise that resolves to an object.
+     * Optional setup function that initializes the component's reactive state and lifecycle.
+     * Receives props and context as an argument and should return an object containing the component's state.
+     * Can return either a synchronous object or a Promise that resolves to an object for async initialization.
      */
     setup?: ((arg0: {
         [x: string]: any;
@@ -183,19 +138,25 @@ type ComponentDefinition = {
         [x: string]: any;
     }>)) | undefined;
     /**
-     *           A function that returns the HTML template string for the component.
+     *           Required function that defines the component's HTML structure.
+     *           Receives the merged context (props + setup data) and must return an HTML template string.
+     *           Supports dynamic expressions using {{ }} syntax for reactive data binding.
      */
     template: (arg0: {
         [x: string]: any;
     }) => string;
     /**
-     * An optional function that returns scoped CSS styles as a string.
+     * Optional function that defines component-scoped CSS styles.
+     * Receives the merged context and returns a CSS string that will be automatically scoped to the component.
+     * Styles are injected into the component's container and only affect elements within it.
      */
     style?: ((arg0: {
         [x: string]: any;
     }) => string) | undefined;
     /**
-     * An optional mapping of CSS selectors to child component definitions.
+     * Optional object that defines nested child components.
+     * Keys are CSS selectors that match elements in the template where child components should be mounted.
+     * Values are ComponentDefinition objects that define the structure and behavior of each child component.
      */
     children?: {
         [x: string]: ComponentDefinition;

package/dist/eleva.esm.js

@@ -56,7 +56,9 @@ class Signal {
    * @param {*} value - The initial value of the signal.
    */
   constructor(value) {
+    /** @private {*} Internal storage for the signal's current value */
     this._value = value;
+    /** @private {Set<function>} Collection of callback functions to be notified when value changes */
     this._watchers = new Set();
   }
 
@@ -104,7 +106,7 @@ class Emitter {
    * Creates a new Emitter instance.
    */
   constructor() {
-    /** @type {Object.<string, Function[]>} */
+    /** @type {Object.<string, Function[]>} Storage for event handlers mapped by event name */
     this.events = {};
   }
 
@@ -254,15 +256,27 @@ class Renderer {
 }
 
 /**
+ * Defines the structure and behavior of a component.
  * @typedef {Object} ComponentDefinition
  * @property {function(Object<string, any>): (Object<string, any>|Promise<Object<string, any>>)} [setup]
- *           A setup function that initializes the component state and returns an object or a promise that resolves to an object.
+ *           Optional setup function that initializes the component's reactive state and lifecycle.
+ *           Receives props and context as an argument and should return an object containing the component's state.
+ *           Can return either a synchronous object or a Promise that resolves to an object for async initialization.
+ *
  * @property {function(Object<string, any>): string} template
- *           A function that returns the HTML template string for the component.
+ *           Required function that defines the component's HTML structure.
+ *           Receives the merged context (props + setup data) and must return an HTML template string.
+ *           Supports dynamic expressions using {{ }} syntax for reactive data binding.
+ *
  * @property {function(Object<string, any>): string} [style]
- *           An optional function that returns scoped CSS styles as a string.
+ *           Optional function that defines component-scoped CSS styles.
+ *           Receives the merged context and returns a CSS string that will be automatically scoped to the component.
+ *           Styles are injected into the component's container and only affect elements within it.
+ *
  * @property {Object<string, ComponentDefinition>} [children]
- *           An optional mapping of CSS selectors to child component definitions.
+ *           Optional object that defines nested child components.
+ *           Keys are CSS selectors that match elements in the template where child components should be mounted.
+ *           Values are ComponentDefinition objects that define the structure and behavior of each child component.
  */
 
 /**
@@ -278,19 +292,21 @@ class Eleva {
    * @param {Object<string, any>} [config={}] - Optional configuration for the instance.
    */
   constructor(name, config = {}) {
-    /** @type {string} */
+    /** @type {string} The unique identifier name for this Eleva instance */
     this.name = name;
-    /** @type {Object<string, any>} */
+    /** @type {Object<string, any>} Optional configuration object for the Eleva instance */
     this.config = config;
-    /** @type {Object<string, ComponentDefinition>} */
+    /** @type {Object<string, ComponentDefinition>} Object storing registered component definitions by name */
     this._components = {};
-    /** @type {Array<Object>} */
+    /** @private {Array<Object>} Collection of installed plugin instances */
     this._plugins = [];
-    /** @private */
+    /** @private {string[]} Array of lifecycle hook names supported by the component */
     this._lifecycleHooks = ["onBeforeMount", "onMount", "onBeforeUpdate", "onUpdate", "onUnmount"];
-    /** @private {boolean} */
+    /** @private {boolean} Flag indicating if component is currently mounted */
     this._isMounted = false;
+    /** @private {Emitter} Instance of the event emitter for handling component events */
     this.emitter = new Emitter();
+    /** @private {Renderer} Instance of the renderer for handling DOM updates and patching */
     this.renderer = new Renderer();
   }
 
@@ -341,16 +357,33 @@ class Eleva {
     } else {
       throw new Error("Invalid component parameter.");
     }
+
+    /**
+     * Destructure the component definition to access core functionality.
+     * - setup: Optional function for component initialization and state management
+     * - template: Required function that returns the component's HTML structure
+     * - style: Optional function for component-scoped CSS styles
+     * - children: Optional object defining nested child components
+     */
     const {
       setup,
       template,
       style,
       children
     } = definition;
+
+    /**
+     * Creates the initial context object for the component instance.
+     * This context provides core functionality and will be merged with setup data.
+     * @type {Object<string, any>}
+     * @property {Object<string, any>} props - Component properties passed during mounting
+     * @property {Emitter} emitter - Event emitter instance for component event handling
+     * @property {function(any): Signal} signal - Factory function to create reactive Signal instances
+     * @property {Object<string, function(): void>} ...lifecycleHooks - Prepared lifecycle hook functions
+     */
     const context = {
       props,
-      emit: this.emitter.emit.bind(this.emitter),
-      on: this.emitter.on.bind(this.emitter),
+      emitter: this.emitter,
       signal: v => new Signal(v),
       ...this._prepareLifecycleHooks()
     };
@@ -391,6 +424,12 @@ class Eleva {
           mergedContext.onUpdate && mergedContext.onUpdate();
         }
       };
+
+      /**
+       * Sets up reactive watchers for all Signal instances in the component's data.
+       * When a Signal's value changes, the component will re-render to reflect the updates.
+       * Stores unsubscribe functions to clean up watchers when component unmounts.
+       */
       Object.values(data).forEach(val => {
         if (val instanceof Signal) watcherUnsubscribers.push(val.watch(render));
       });