eleva 1.0.0-alpha → 1.0.0-rc.10

package/README.md

@@ -1,25 +1,62 @@
-# Eleva
+# eleva.js 🚀
 
-**A minimalist, lightweight, pure vanilla JavaScript frontend runtime framework.**  
-_Built with love for native JavaScript—because sometimes, less really is more!_ 😊
+> **Version:** 1.0.0-rc.10 | **Size:** ~6KB min (~2KB gzip) | **Dependencies:** Zero | **TypeScript:** Yes
+
+Pure JavaScript, Pure Performance, Simply Elegant.
 
+[![License](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+[![GitHub package.json version](https://img.shields.io/github/package-json/v/tarekraafat/eleva?label=github)](https://github.com/TarekRaafat/eleva)
 [![Version](https://img.shields.io/npm/v/eleva.svg?style=flat)](https://www.npmjs.com/package/eleva)
-[![License](https://img.shields.io/npm/l/eleva.svg?style=flat)](LICENSE)
-[![Build Status](https://img.shields.io/travis/TarekRaafat/eleva.svg?style=flat)](https://travis-ci.org/TarekRaafat/eleva)
+![100% Javascript](https://img.shields.io/github/languages/top/TarekRaafat/eleva?color=yellow)
+![Zero Dependencies](https://img.shields.io/badge/dependencies-0-green.svg)
+[![codecov](https://codecov.io/gh/TarekRaafat/eleva/branch/master/graph/badge.svg?token=LFA6KENM24)](https://codecov.io/gh/TarekRaafat/eleva)
+[![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)
+[![](https://data.jsdelivr.com/v1/package/npm/eleva/badge?style=rounded)](https://www.jsdelivr.com/package/npm/eleva)
+[![Supported by Canonical](https://img.shields.io/badge/Supported%20by-Canonical-E95420?logo=ubuntu&logoColor=white)](https://canonical.com)
+
+<br>
+
+<p align="center">
+  <a href="https://tarekraafat.github.io/eleva/"><img src="./docs/imgs/eleva.js Full Logo.png" alt="eleva.js Full Logo" width="50%"></a>
+</p>
+
+<p align="center">
+  <a href="https://canonical.com" target="_blank" rel="noopener">
+    <img src="https://raw.githubusercontent.com/SebastJava/Ubuntu-logo/649d55eca403302fb06281d9dd94798bb0568e8d/logo-v2025-plain-450x708.svg" alt="Canonical Logo" width="80"/>
+  </a>
+</p>
+
+<p align="center">
+  <em>Eleva.js is proudly supported by Canonical - the company behind Ubuntu.</em>
+</p>
+
+<p align="center">
+  <a href="https://www.producthunt.com/posts/eleva?embed=true&utm_source=badge-featured&utm_medium=badge&utm_souce=badge-eleva" target="_blank"><img src="https://api.producthunt.com/widgets/embed-image/v1/featured.svg?post_id=938663&theme=light&t=1741247713068" alt="eleva.js - A&#0032;minimalist&#0044;&#0032;pure&#0032;vanilla&#0032;javascript&#0032;frontend&#0032;framework&#0046; | Product Hunt" style="width: 250px; height: 54px;" width="250" height="54" /></a>
+</p>
+
+<br>
+<br>
+<br>
+
+**A minimalist, lightweight, pure vanilla JavaScript frontend runtime framework.**  
+_Built with love for native JavaScript and designed with a minimal core that can be extended through a powerful plugin system-because sometimes, less really is more!_ 😊
 
-> **Stability Notice**: This is `v1.0.0-alpha` - APIs may change significantly until stable release.  
-> Not recommended for production use yet. Follow the [versioning guide](#versioning) for updates.
+> **Stability Notice**: This is `v1.0.0-rc.10` - The core functionality is stable. Seeking community feedback before the final v1.0.0 release.
 
-**Version:** `1.0.0-alpha`
+**Version:** `1.0.0-rc.10`
 
-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. 🚀
+
+
+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. 🚀
 
 ---
 
 ## Table of Contents
 
-- [Eleva](#eleva)
+- [eleva.js 🚀](#elevajs-)
   - [Table of Contents](#table-of-contents)
+  - [Quick Reference](#quick-reference)
   - [Introduction](#introduction)
   - [Design Philosophy](#design-philosophy)
   - [Handcrafted \& Developer-Centric Design](#handcrafted--developer-centric-design)
@@ -40,6 +77,12 @@ Welcome to Eleva! This is my humble, experimental playground for a fresh approac
     - [Emitter](#emitter)
     - [Renderer](#renderer)
     - [Eleva (Core)](#eleva-core)
+    - [Plugins](#plugins)
+      - [Core Framework Only (Lightweight)](#core-framework-only-lightweight)
+      - [AttrPlugin](#attrplugin)
+      - [RouterPlugin](#routerplugin)
+      - [PropsPlugin](#propsplugin)
+      - [StorePlugin](#storeplugin)
   - [Development](#development)
   - [Testing](#testing)
   - [Contributing](#contributing)
@@ -48,52 +91,84 @@ Welcome to Eleva! This is my humble, experimental playground for a fresh approac
 
 ---
 
+## Quick Reference
+
+### Minimal Setup (30 seconds)
+
+```javascript
+import Eleva from "eleva";
+
+const app = new Eleva("MyApp");
+
+app.component("Counter", {
+  setup: ({ signal }) => ({ count: signal(0) }),
+  template: (ctx) => `<button @click="() => count.value++">${ctx.count.value}</button>`
+});
+
+app.mount(document.getElementById("app"), "Counter");
+```
+
+### API at a Glance
+
+| Method | Purpose |
+|--------|---------|
+| `new Eleva(name)` | Create app |
+| `app.component(name, def)` | Register component |
+| `app.mount(el, name)` | Mount to DOM |
+| `app.use(plugin)` | Add plugin |
+| `signal(value)` | Reactive state |
+| `emitter.on/emit` | Events |
+
+### Template Syntax
+
+| Syntax | Use |
+|--------|-----|
+| `${expr}` | Static value |
+| `{{ expr }}` | Reactive value |
+| `@click` | Event handler |
+| `:prop` | Pass to child |
+
+---
+
 ## Introduction
 
-Eleva is a lightweight, no-nonsense runtime framework for frontend applications. Built with love for **pure vanilla JavaScript**, Eleva lets you create highly modular and scalable applications without the overhead of large frameworks. I built Eleva to prove that you don't need to rely on heavy libraries to build amazing user interfaces—sometimes, the simplest approach is the most powerful.
+Eleva is a lightweight, no-nonsense runtime framework for frontend applications. Built with love for **pure vanilla JavaScript**, Eleva features a minimal core with essential functionality that can be extended through a powerful plugin system. This approach lets you create highly modular and scalable applications without the overhead of large frameworks. I built Eleva to prove that you don't need heavy frameworks or libraries to build amazing user interfaces-sometimes, the simplest approach is the most powerful.
 
 **My Inspiration:**  
-The idea and concept behind Eleva came from my deep appreciation for native JavaScript. I wanted to create a tool that stays true to the language without introducing new syntax or complexity, making it easy for you to integrate into your projects without a steep learning curve.
+The idea behind Eleva comes from a deep appreciation for native JavaScript. I wanted to create a tool that stays true to the language without introducing new syntax or complexity, making it easy to integrate into your projects.
 
 **Core Principles:**
 
-- **🌱 Minimalism:** Only the essentials, so you can build without the clutter.
-- **🔌 Extensibility:** Plug in your own ideas—custom state management, routing, and more.
+- **🌱 Minimalism:** Only essential features in the core, keeping the framework lean and focused.
+- **🔌 Extensibility:** Extend functionality by plugging in your own ideas, such as custom state management, routing, and more.
 - **🚀 Performance:** Fast, efficient, and designed with modern browsers in mind.
-- **🍦 Pure Vanilla:** No dependencies, no magic—just plain JavaScript.
+- **🍦 Pure Vanilla:** No dependencies, no magic-just plain JavaScript.
 
 ---
 
 ## Design Philosophy
 
-**Eleva is an unopinionated library.**
+**Eleva is an unopinionated framework with a minimal core philosophy.**
 
-Unlike many frameworks that enforce a specific project structure or coding paradigm, Eleva provides a minimal core with a flexible plugin system. This means:
+Unlike monolithic frameworks that include everything out-of-the-box, Eleva intentionally provides only essential features in its core, relying on a powerful plugin system for extensibility. This architectural choice means:
 
-- **🔄 Flexibility:** You’re free to architect your application as you see fit, without being forced into a rigid structure.
-- **🎯 Native JavaScript:** Eleva is built using pure vanilla JavaScript, so it integrates seamlessly with your existing code without introducing unfamiliar syntax.
-- **⚙️ Configurability:** With a simple API and optional plugins, you can extend Eleva's functionality to suit your project's unique requirements.
-- **🆓 Freedom:** You decide the best way to implement features, allowing for both simple and complex applications without unnecessary constraints.
+- **🔄 Flexibility:** Architect your application your way-no rigid structure required.
+- **🎯 Native JavaScript:** Built using pure vanilla JavaScript, Eleva integrates seamlessly with your existing code without unfamiliar syntax.
+- **⚙️ Configurability:** Extend Eleva's functionality with a simple API and optional plugins.
+- **🆓 Freedom:** Decide the best way to implement features without unnecessary constraints.
 
-This unopinionated approach makes Eleva versatile and ideal for developers who prefer to have full control over their application's design.
+This unopinionated approach makes Eleva versatile and ideal for developers who want full control over their application's design.
 
 ---
 
 ## Handcrafted & Developer-Centric Design
 
-Eleva is built with a meticulous attention to detail and a deep passion for pure vanilla JavaScript. Every aspect of its design and architecture has been carefully handcrafted with the developer in mind. This approach makes Eleva not only a fresh and innovative choice but also a solid foundation for your projects.
-
-- **🎨 Craftsmanship:**  
-  Every line of code in Eleva is written with care, ensuring that the library remains lightweight, efficient, and easy to understand.
+Eleva is built with meticulous attention to detail and a deep passion for pure vanilla JavaScript. Every aspect of its design and architecture is handcrafted with the developer in mind. This makes Eleva not only innovative but also a solid foundation for your projects.
 
-- **🛠️ Developer-Centric:**  
-  Eleva is designed for you—the developer. Its intuitive API and minimalistic core mean you spend less time wrestling with the framework and more time building your application.
-
-- **🌟 Innovative & Fresh:**  
-  By sticking to pure vanilla JavaScript and avoiding unnecessary abstractions, Eleva offers a refreshing alternative to the complex and opinionated frameworks out there.
-
-- **🏗️ Solid & Reliable:**  
-  With a focus on performance and modularity, Eleva provides a robust yet flexible platform that scales with your project's needs.
+- **🎨 Craftsmanship:** Every line of code is written with care, keeping the framework lightweight, efficient, and easy to understand.
+- **🛠️ Developer-Centric:** Its intuitive API and minimal core mean you spend less time wrestling with the framework and more time building your application.
+- **🌟 Innovative & Fresh:** Stick to pure vanilla JavaScript and avoid unnecessary abstractions.
+- **🏗️ Solid & Reliable:** Focused on performance and modularity, Eleva scales with your project's needs.
 
 This unique, developer-first approach makes Eleva a standout choice for building high-performance frontend applications without compromising on simplicity or control.
 
@@ -101,40 +176,35 @@ This unique, developer-first approach makes Eleva a standout choice for building
 
 ## Features
 
-- **🧩 Component-Based Architecture:** Create reusable UI components effortlessly.
-- **⚡ Signal-Based Reactivity:** Fine-grained reactivity that updates only what’s needed.
-- **🔔 Event Handling:** Built-in event emitter for robust inter-component communication.
-- **📝 Template Parsing:** Secure and dynamic interpolation with a custom TemplateEngine.
-- **🔄 DOM Diffing & Patching:** High-performance updates without a virtual DOM.
-- **📦 UMD & ES Module Builds:** Designed for the browser, with modern build tool support.
-- **🤝 Friendly API:** A gentle learning curve for both beginners and seasoned developers.
-- **💎 Tiny Footprint & TypeScript Support:** At a fraction of the size of many mainstream frameworks (~4 KB minified) and with built-in TypeScript declarations, Eleva keeps your bundle lean and your codebase strongly typed.
+- **🧩 Component-Based Architecture:** Create reusable UI components with a rich context API
+- **⚡ Signal-Based Reactivity:** Fine-grained reactivity that updates only what's needed
+- **🔔 Event Handling:** Built-in event emitter for robust inter-component communication
+- **📝 Template Parsing:** Secure and dynamic interpolation with a custom TemplateEngine
+- **🔄 DOM Diffing & Patching:** High-performance updates without a virtual DOM
+- **🔄 Lifecycle Hooks:** Complete lifecycle management with before/after mount and update hooks
+- **🧹 Automatic Cleanup:** Proper cleanup of resources, watchers, and child components on unmount
+- **🔌 Plugin System:** Extensible architecture with a simple plugin API
+- **🎯 Built-in Plugins:** AttrPlugin for advanced attributes, PropsPlugin for complex data handling, RouterPlugin for client-side routing, and StorePlugin for reactive state management
+- **📦 UMD & ES Module Builds:** Supports modern build tools and browser environments
+- **🤝 Friendly API:** A gentle learning curve for both beginners and seasoned developers
+- **💎 Tiny Footprint & TypeScript Support:** Approximately ~6 KB minified with built-in TypeScript declarations
 
 ---
 
 ## When to Use Eleva
 
-Eleva is designed for developers who want a lightweight, flexible, and high-performance solution for building frontend applications. Here are some scenarios where Eleva shines:
-
-- **🚀 Small to Medium Projects:**  
-  If you're building a web app or website that doesn't require the overhead of a full-fledged framework, Eleva’s minimal footprint (~4 KB minified) keeps your project fast and efficient.
+Eleva is ideal for developers seeking a lightweight, flexible, and high-performance solution for building frontend applications. Here are some scenarios where Eleva shines:
 
-- **⚡ Performance-Critical Applications:**  
-  For projects where speed and low bundle size are paramount, Eleva's optimized reactivity and DOM diffing ensure your app runs smoothly without unnecessary bloat.
-
-- **🔄 Unopinionated and Flexible Design:**  
-  Eleva is unopinionated, meaning it doesn't force you into a rigid structure. You can architect your application your way while enjoying a straightforward API and a flexible plugin system.
-
-- **🎯 Developer-Friendly & Native JavaScript:**  
-  If you prefer working with pure vanilla JavaScript without the need to learn new syntax or complex abstractions, Eleva is built with you in mind. Plus, it comes with built-in TypeScript declarations for strong type support.
-
-- **🧪 Rapid Prototyping & Experimentation:**  
-  Eleva's simplicity and ease of integration make it a great choice for prototyping ideas quickly. Its modular architecture means you can start small and extend the functionality as your project evolves.
-
-- **🔌 Extensibility through Plugins:**  
-  With a robust plugin system, Eleva can be easily extended to include features like routing, state management, or custom behaviors, making it suitable for both simple and complex applications.
-
-In short, if you're looking for a solid, developer-centric framework that provides high performance, simplicity, and the freedom to build your application your way, Eleva is an excellent choice.
+- **🚀 Small to Medium Projects:** Perfect for web apps or websites that don't require the overhead of a full-fledged framework.
+- **⚡ Performance-Critical Applications:** Optimized reactivity and DOM diffing ensure smooth performance without bloat.
+- **🔄 Unopinionated & Flexible:** Architect your application your way with a straightforward API and plugin system.
+- **🎯 Developer-Friendly:** Stick to pure vanilla JavaScript with familiar syntax and built-in TypeScript support.
+- **🧪 Rapid Prototyping:** Quickly prototype ideas with a minimal and extendable framework.
+- **🔌 Extensible:** Easily add features like routing or state management through plugins.
+- **🚀 Built-in Routing:** Advanced client-side routing with navigation guards and reactive state via RouterPlugin.
+- **🎯 Advanced Attributes:** Sophisticated attribute handling with ARIA support via AttrPlugin.
+- **🏪 Reactive State Management:** Centralized, reactive data store with persistence and namespacing via StorePlugin.
+- **📦 Module Format Flexibility:** Choose from ESM, CommonJS, or UMD formats based on your project's needs.
 
 ---
 
@@ -142,80 +212,85 @@ In short, if you're looking for a solid, developer-centric framework that provid
 
 I believe in clear versioning that reflects the maturity of the project:
 
-- **Pre-release Versions (Alpha/Beta):** Early versions like `1.0.0-alpha` signal that the API is still evolving. Expect frequent updates, and please share your feedback!
-- **Semantic Versioning:** Once the API stabilizes, I'll follow semantic versioning strictly so that any breaking changes are clearly communicated.
-- **Fresh Start:** Since this is a complete overhaul and a fresh start, `1.0.0-alpha` represents my first major step forward.
+- **Pre-release Versions (RC):** Release candidate versions like `1.0.0-rc.10` indicate the API is stable but still gathering community feedback before the final release.
+- **Semantic Versioning:** Once stable, I'll follow semantic versioning strictly to clearly communicate any breaking changes.
 
 ---
 
 ## Version Guide
 
-I follow [Semantic Versioning (SemVer)](https://semver.org/) to manage Eleva's releases. Here's a quick guide to help you understand the version numbers:
-
-- **🔢 Major Version:**  
-  A change in the first digit (e.g., from `1.0.0` to `2.0.0`) indicates breaking changes or a major overhaul of the framework.
-- **🔢 Minor Version:**  
-  A change in the second digit (e.g., from `1.0.0` to `1.1.0`) signifies the addition of new features in a backward-compatible manner.
-- **🔢 Patch Version:**  
-  A change in the third digit (e.g., from `1.0.0` to `1.0.1`) reflects backward-compatible bug fixes and minor improvements.
-- **📌 Pre-release Identifiers:**  
-  Suffixes like `-alpha`, `-beta`, or `-rc` indicate that the release is not yet stable. For example, `1.0.0-alpha` means this is an experimental version of the upcoming stable `1.0.0` release.
+I follow [Semantic Versioning (SemVer)](https://semver.org/):
 
-This guide is intended to help you understand what to expect with each release and how Eleva is evolving over time.
+- **🔢 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.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.2.0-alpha`).
 
 ---
 
 ## Performance
 
-Eleva is crafted with performance in mind:
+Eleva is crafted for performance:
 
-- **Lightweight:** Designed to be ~4 KB minified so your app stays nimble.
-- **Efficient Reactivity:** Signal-based updates ensure only the necessary parts of the DOM are re-rendered.
-- **Optimized Diffing:** The Renderer efficiently patches changes without the overhead of a virtual DOM.
-- **No Bloat:** Pure vanilla JavaScript means no unnecessary dependencies slowing you down.
+- **Lightweight:** Approximately ~6 KB minified and ~2 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.
+- **Tree-Shakable:** ESM format allows bundlers to eliminate unused code.
+- **Format-Specific Optimizations:** Each module format is optimized for its target environment.
 
 ---
 
 ## Performance Benchmarks
 
-I've run some preliminary benchmarks to give you a rough idea of how Eleva stacks up against some popular frontend frameworks. These tests focus on bundle size, initial load time, and DOM update performance using a simple counter component scenario.
+Preliminary benchmarks illustrate Eleva's efficiency compared to popular frameworks:
+
+| **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)        | **2**                | **0.05**                   | **0.002**                | **0.25**                   | **0.58 (Best)**                                 |
+| **React** (Virtual DOM)       | 4.1                  | 5.34                       | 0.020                    | 0.25                       | 9.71                                            |
+| **Vue** (Reactive State)      | 45                   | 4.72                       | 0.021                    | 3.10                       | 13.21                                           |
+| **Angular** (Two-way Binding) | 62                   | 5.26                       | 0.021                    | 0.25                       | 16.88 (Slowest)                                 |
 
-| 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            |
+Detailed [Benchmark Metrics Report](BENCHMARK.md)
 
-> ⚠️ **Disclaimer:** These benchmarks are based on internal tests with a minimalistic counter component and may vary depending on project specifics and environments. They serve as a general indicator of Eleva’s lightweight and high-performance design.
+> ⚠️ **Disclaimer:** Benchmarks are based on internal tests and may vary by project and environment.
 
 ---
 
 ## Eleva vs. Popular Frameworks
 
-While frameworks like React, Vue, and Angular are powerful, Eleva offers a refreshing alternative:
+Eleva offers a refreshing alternative to frameworks like React, Vue, and Angular:
 
-- **Simplicity:** No virtual DOM, no JSX, and no complex state management—just plain JavaScript.
-- **Modularity:** Easily extend Eleva with plugins to fit your project's needs.
-- **Size:** At a fraction of the size of many mainstream frameworks, Eleva is perfect for projects where performance is key.
-- **Learning Curve:** With a familiar syntax and a clear API, Eleva is ideal for developers of all levels.
+- **Simplicity:** No virtual DOM, JSX, or complex state management-just plain JavaScript.
+- **Modularity:** Easily extend via plugins to suit your project's needs.
+- **Size:** A fraction of the size of mainstream frameworks.
+- **Learning Curve:** Familiar syntax and a clear API make it accessible to all developers.
 
-**Important:** Eleva is not trying to replace these giants but rather offers a lightweight option when you want to keep things simple and fast without introducing new syntax or unnecessary complexity. 🌟
+_Note:_ Eleva isn't trying to replace these giants but provides a lightweight option when you want simplicity and speed. 🌟
 
 ---
 
 ## Installation
 
-Eleva is available on npm. Since it's in alpha, I'm excited to have you try it out and share your thoughts!
+Eleva is available on npm. Try it out and share your thoughts!
 
 ```bash
 npm install eleva
 ```
 
-Or include it directly in your HTML via CDN:
+Or include it directly via CDN:
 
 ```html
-<script src="https://unpkg.com/eleva/dist/eleva.min.js"></script>
+<!-- jsDelivr (Recommended) -->
+<script src="https://cdn.jsdelivr.net/npm/eleva"></script>
+```
+
+or
+
+```html
+<!-- unpkg -->
+<script src="https://unpkg.com/eleva"></script>
 ```
 
 ---
@@ -226,33 +301,46 @@ Or include it directly in your HTML via CDN:
 
 ```js
 // Import Eleva (using ES modules)
-import { Eleva } from "eleva";
+import Eleva from "eleva";
 
 // Create a new Eleva instance
 const app = new Eleva("MyApp");
 
 // Define a component
 app.component("HelloWorld", {
+  // The setup method is optional; if omitted, an empty state is used.
   setup({ signal }) {
     const count = signal(0);
-    return { count };
+    return { 
+      count,
+      onMount: ({ container, context }) => {
+        console.log('Component mounted!');
+      }
+    };
   },
   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>
-  `,
+  `
 });
 
-// Mount the component to a DOM element with the id 'app'
-app.mount("#app", "HelloWorld");
+// Mount the component and handle the Promise
+app.mount(document.getElementById("app"), "HelloWorld")
+  .then(instance => {
+    console.log("Component mounted:", instance);
+    // Later...
+    // instance.unmount();
+  });
 ```
 
+Interactive Demo: [CodePen](https://codepen.io/tarekraafat/pen/GgRrxdY?editors=1010)
+
 ### UMD Example
 
-Include Eleva via a script tag, and it will be available as a global variable:
+Include Eleva via a script tag and use the global variable:
 
 ```html
 <!DOCTYPE html>
@@ -263,7 +351,7 @@ Include Eleva via a script tag, and it will be available as a 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"></script>
     <script>
       const app = new Eleva("MyApp");
       app.component("HelloWorld", {
@@ -272,56 +360,58 @@ Include Eleva via a script tag, and it will be available as a global variable:
           return { count };
         },
         template: ({ count }) => `
-        <div>
-          <h1>Hello, Eleva! 👋</h1>
-          <p>Count: ${count}</p>
-          <button @click="() => count++">Increment</button>
-        </div>
-      `,
+          <div>
+            <h1>Hello, Eleva! 👋</h1>
+            <p>Count: ${count.value}</p>
+            <button @click="() => count.value++">Increment</button>
+          </div>
+        `,
       });
-      app.mount("#app", "HelloWorld");
+      app.mount(document.getElementById("app"), "HelloWorld");
     </script>
   </body>
 </html>
 ```
 
+Interactive Demo: [CodePen](https://codepen.io/tarekraafat/pen/jEOyzYN?editors=1010)
+
 ---
 
 ## API Reference
 
 ### TemplateEngine
 
-- **`TemplateEngine.parse(template, data)`**  
+- **`TemplateEngine.parse(template, data)`**
   Replaces `{{ expression }}` patterns in the template with evaluated values.
-- **`TemplateEngine.evaluate(expr, data)`**  
+- **`TemplateEngine.evaluate(expr, data)`**
   Safely evaluates JavaScript expressions within a given context.
 
 ### Signal
 
-- **`new Signal(value)`**  
+- **`new Signal(initialValue)`**
   Creates a reactive data holder.
-- **`.value` (getter/setter)**  
+- **`.value` (getter/setter)**
   Get or update the current value and trigger watchers.
-- **`.watch(fn)`**  
+- **`.watch(callback)`**
   Registers a function to run when the value updates.
 
 ### Emitter
 
-- **`.on(event, handler)`**  
+- **`new Emitter()`**
+  Creates an Emitter instance.
+- **`.on(event, handler)`**
   Listen to events.
-- **`.off(event, handler)`**  
+- **`.off(event, handler)`**
   Remove event listeners.
-- **`.emit(event, ...args)`**  
+- **`.emit(event, ...args)`**
   Trigger events with additional arguments.
 
 ### Renderer
 
-- **`patchDOM(container, newHtml)`**  
-  Efficiently update the DOM.
-- **`diff(oldParent, newParent)`**  
-  Compare and update DOM trees.
-- **`updateAttributes(oldEl, newEl)`**  
-  Sync element attributes.
+- **`new Renderer()`**
+  Creates a Renderer instance.
+- **`.patchDOM(container, newHtml)`**:
+  Updates container content with the new HTML.
 
 ### Eleva (Core)
 
@@ -331,16 +421,333 @@ Include Eleva via a script tag, and it will be available as a global variable:
   Install plugins.
 - **`.component(name, definition)`**  
   Register a component.
-- **`.mount(selectorOrElement, compName, props)`**  
+- **`.mount(container, compName, props)`**  
   Mount a component to the DOM.
 
-For detailed API documentation, please check the [docs](docs/) folder.
+### Plugins
+
+Eleva's plugin system allows you to extend functionality as needed. Plugins are **separately bundled** from the core framework, ensuring optimal tree-shaking and minimal bundle sizes.
+
+#### Core Framework Only (Lightweight)
+
+```javascript
+import Eleva from 'eleva';
+
+const app = new Eleva("myApp");
+// Core framework only - ~6KB minified
+```
+
+#### AttrPlugin
+
+Advanced attribute handling for ARIA, data attributes, boolean properties, and dynamic property detection:
+
+```javascript
+import Eleva from 'eleva';
+import { Attr } from 'eleva/plugins';
+
+const app = new Eleva("myApp");
+app.use(Attr, {
+    enableAria: true,      // ARIA attribute handling
+    enableData: true,       // Data attribute management
+    enableBoolean: true,    // Boolean attribute processing
+    enableDynamic: true     // Dynamic property detection
+});
+
+// Use advanced attributes in components
+app.component("myComponent", {
+    template: (ctx) => `
+        <button 
+            aria-expanded="${ctx.isExpanded.value}"
+            data-user-id="${ctx.userId.value}"
+            disabled="${ctx.isLoading.value}"
+            class="btn ${ctx.variant.value}"
+        >
+            ${ctx.text.value}
+        </button>
+    `
+});
+```
+
+📚 **[Full Attr Documentation →](docs/plugins/attr.md)** - Comprehensive guide with ARIA attributes, data attributes, boolean handling, and dynamic properties.
+
+#### RouterPlugin
+
+🚀 **Advanced client-side routing** with multiple modes, navigation guards, reactive state, and component resolution:
+
+```javascript
+import Eleva from 'eleva';
+import { Router } from 'eleva/plugins';
+
+const app = new Eleva("myApp");
+
+// Define components
+const HomePage = { template: () => `<h1>Home</h1>` };
+const AboutPage = { template: () => `<h1>About</h1>` };
+const UserPage = { 
+    template: (ctx) => `<h1>User: ${ctx.router.params.id}</h1>` 
+};
+
+// Install router with advanced configuration
+const router = app.use(Router, {
+    mount: '#app',                    // Mount element selector
+    mode: 'hash',                     // 'hash', 'history', or 'query'
+    routes: [
+        { 
+            path: '/', 
+            component: HomePage,
+            meta: { title: 'Home' }
+        },
+        { 
+            path: '/about', 
+            component: AboutPage,
+            beforeEnter: (to, from) => {
+                // Navigation guard
+                return true;
+            }
+        },
+        { 
+            path: '/users/:id', 
+            component: UserPage,
+            afterEnter: (to, from) => {
+                // Lifecycle hook
+                console.log('User page entered');
+            }
+        }
+    ],
+    onBeforeEach: (to, from) => {
+        // Global navigation guard
+        return true;
+    }
+});
+
+// Access reactive router state
+router.currentRoute.subscribe(route => {
+    console.log('Route changed:', route);
+});
+
+// Programmatic navigation
+router.navigate('/users/123', { replace: true });
+```
+
+📚 **[Full Router Documentation →](docs/plugins/router.md)** - Comprehensive guide with 13 events, 7 reactive signals, navigation guards, scroll management, and more.
+
+#### PropsPlugin
+
+🎯 **Advanced props handling** with automatic type detection, parsing, and reactivity for complex data structures:
+
+```javascript
+import Eleva from 'eleva';
+import { Props } from 'eleva/plugins';
+
+const app = new Eleva("myApp");
+app.use(Props, {
+    enableAutoParsing: true,    // Enable automatic type detection
+    enableReactivity: true,     // Enable reactive prop updates
+    onError: (error, value) => {
+        console.error('Props parsing error:', error, value);
+    }
+});
+
+// Use complex props in components
+app.component("UserCard", {
+    template: (ctx) => `
+        <div class="user-container"
+             :user='${JSON.stringify(ctx.user.value)}'
+             :permissions='${JSON.stringify(ctx.permissions.value)}'>
+        </div>
+    `,
+    children: {
+        '.user-container': 'UserInfo'
+    }
+});
+
+app.component("UserInfo", {
+    setup({ props }) {
+        return {
+            user: props.user,              // Automatically parsed object
+            permissions: props.permissions  // Automatically parsed array
+        };
+    },
+    template: (ctx) => `
+        <div class="user-info">
+            <h3>${ctx.user.value.name}</h3>
+            <p>Role: ${ctx.user.value.role}</p>
+        </div>
+    `
+});
+```
+
+📚 **[Full Props Documentation →](docs/plugins/props.md)** - Comprehensive guide with type parsing, reactive props, signal linking, complex data structures, and error handling.
+
+#### StorePlugin
+
+🏪 **Reactive state management** with centralized data store, persistence, namespacing, and cross-component reactive updates:
+
+```javascript
+import Eleva from 'eleva';
+import { Store } from 'eleva/plugins';
+
+const app = new Eleva("myApp");
+
+// Install store with configuration
+app.use(Store, {
+    state: {
+        theme: "light",
+        counter: 0,
+        user: {
+            name: "John Doe",
+            email: "john@example.com"
+        }
+    },
+    actions: {
+        increment: (state) => state.counter.value++,
+        decrement: (state) => state.counter.value--,
+        toggleTheme: (state) => {
+            state.theme.value = state.theme.value === "light" ? "dark" : "light";
+        },
+        updateUser: (state, updates) => {
+            state.user.value = { ...state.user.value, ...updates };
+        }
+    },
+    // Optional: Namespaced modules
+    namespaces: {
+        auth: {
+            state: { token: null, isLoggedIn: false },
+            actions: {
+                login: (state, token) => {
+                    state.auth.token.value = token;
+                    state.auth.isLoggedIn.value = true;
+                },
+                logout: (state) => {
+                    state.auth.token.value = null;
+                    state.auth.isLoggedIn.value = false;
+                }
+            }
+        }
+    },
+    // Optional: State persistence
+    persistence: {
+        enabled: true,
+        key: "myApp-store",
+        storage: "localStorage",  // or "sessionStorage"
+        include: ["theme", "user"] // Only persist specific keys
+    }
+});
+
+// Use store in components
+app.component("Counter", {
+    setup({ store }) {
+        return {
+            count: store.state.counter,
+            theme: store.state.theme,
+            increment: () => store.dispatch("increment"),
+            decrement: () => store.dispatch("decrement")
+        };
+    },
+    template: (ctx) => `
+        <div class="${ctx.theme.value}">
+            <h3>Counter: ${ctx.count.value}</h3>
+            <button @click="decrement">-</button>
+            <button @click="increment">+</button>
+        </div>
+    `
+});
+
+// Create state and actions at runtime
+app.component("TodoManager", {
+    setup({ store }) {
+        // Register new module dynamically
+        store.registerModule("todos", {
+            state: { items: [], filter: "all" },
+            actions: {
+                addTodo: (state, text) => {
+                    state.todos.items.value.push({
+                        id: Date.now(),
+                        text,
+                        completed: false
+                    });
+                },
+                toggleTodo: (state, id) => {
+                    const todo = state.todos.items.value.find(t => t.id === id);
+                    if (todo) todo.completed = !todo.completed;
+                }
+            }
+        });
+
+        // Create individual state properties
+        const notification = store.createState("notification", null);
+
+        // Create individual actions
+        store.createAction("showNotification", (state, message) => {
+            state.notification.value = message;
+            setTimeout(() => state.notification.value = null, 3000);
+        });
+
+        return {
+            todos: store.state.todos.items,
+            notification,
+            addTodo: (text) => store.dispatch("todos.addTodo", text),
+            notify: (msg) => store.dispatch("showNotification", msg)
+        };
+    }
+});
+
+// Subscribe to store changes
+const unsubscribe = app.store.subscribe((mutation, state) => {
+    console.log('Store updated:', mutation.type, state);
+});
+
+// Access store globally
+console.log(app.store.getState()); // Get current state values
+app.dispatch("increment");          // Dispatch actions globally
+```
+
+📚 **[Full Store Documentation →](docs/plugins/store.md)** - Comprehensive guide with 10 API methods, persistence options, namespaces, subscriptions, and migration guides.
+
+**Bundle Sizes:**
+- Core framework only: ~6KB (minified)
+- Core + AttrPlugin: ~8KB (minified)
+- Core + PropsPlugin: ~10KB (minified)
+- Core + RouterPlugin: ~19KB (minified)
+- Core + StorePlugin: ~12KB (minified)
+- Core + All plugins: ~25KB (minified)
+
+**Individual Plugin Sizes:**
+- AttrPlugin: ~2.4KB (minified)
+- PropsPlugin: ~4.2KB (minified)
+- RouterPlugin: ~13KB (minified)
+- StorePlugin: ~6KB (minified)
+
+**Available Plugin Formats:**
+
+**For Bundlers (Tree-Shaking Supported):**
+- ESM: `import { Attr, Props, Router, Store } from 'eleva/plugins'`
+- CJS: `const { Attr, Props, Router, Store } = require('eleva/plugins')`
+
+**For CDN (Individual Plugins - Smaller Bundle Size):**
+- UMD: `<script src="https://unpkg.com/eleva@latest/dist/eleva.umd.min.js"></script>`
+- UMD: `<script src="https://unpkg.com/eleva@latest/dist/plugins/attr.umd.min.js"></script>`
+- UMD: `<script src="https://unpkg.com/eleva@latest/dist/plugins/props.umd.min.js"></script>`
+- UMD: `<script src="https://unpkg.com/eleva@latest/dist/plugins/router.umd.min.js"></script>`
+- UMD: `<script src="https://unpkg.com/eleva@latest/dist/plugins/store.umd.min.js"></script>`
+
+**Individual Plugin Imports (Best for Tree-Shaking):**
+- ESM: `import { Attr } from 'eleva/plugins/attr'`
+- ESM: `import { Props } from 'eleva/plugins/props'`
+- ESM: `import { Router } from 'eleva/plugins/router'`
+- ESM: `import { Store } from 'eleva/plugins/store'`
+- CJS: `const { Attr } = require('eleva/plugins/attr')`
+- CJS: `const { Props } = require('eleva/plugins/props')`
+- CJS: `const { Router } = require('eleva/plugins/router')`
+- CJS: `const { Store } = require('eleva/plugins/store')`
+
+For detailed API documentation, please check the [docs](docs/index.md) folder.
 
 ---
 
 ## Development
 
-I welcome developers to dive in and play around with Eleva! Here's how you can get started locally:
+I welcome developers to dive in and experiment with Eleva! Here's how to get started locally:
 
 1. **Clone the Repository:**
 
@@ -361,7 +768,7 @@ I welcome developers to dive in and play around with Eleva! Here's how you can g
    npm run dev
    ```
 
-4. **Build for Production:**
+4. **Build for Production without TypeScript Declarations:**
 
    ```bash
    npm run build
@@ -374,23 +781,29 @@ I welcome developers to dive in and play around with Eleva! Here's how you can g
    npm run build:types:bundle
    ```
 
+6. **Build for Production with TypeScript Declarations:**
+
+   ```bash
+   npm run build:all
+   ```
+
 ---
 
 ## Testing
 
-I use Jest for tests. Run the test suite with:
+I use Jest for testing. Run the test suite with:
 
 ```bash
 npm test
 ```
 
-Your contributions to tests are very welcome! 🧪
+Contributions to tests are very welcome! 🧪
 
 ---
 
 ## Contributing
 
-I’d love to have you onboard as a contributor! Whether you’re adding new features, squashing bugs, or sharing ideas, your input is invaluable. Please check out [CONTRIBUTING](CONTRIBUTING.md) for details on how to get started.
+I'd love to have you onboard as a contributor! Whether you're adding new features, squashing bugs, or sharing ideas, your input is invaluable. Please check out [CONTRIBUTING](CONTRIBUTING.md) for guidelines on getting started.
 
 ---
 
@@ -408,11 +821,15 @@ Eleva is open-source and available under the [MIT License](LICENSE).
 
 ---
 
-**Note:** This is an alpha release. I'm still polishing things up, so expect some bumps along the way. Your feedback and contributions will help shape Eleva into something truly amazing. Let’s build something great together! 💪✨
+**Note:** This is a release candidate (RC). The core functionality is stable and suitable for production use. Your feedback and contributions will help shape Eleva into something truly amazing. Let's build something great together! 💪✨
+
+---
+
+[![NPM](https://nodei.co/npm/eleva.png?downloads=true&downloadRank=true&stars=true)](https://nodei.co/npm/eleva/)
 
 ---
 
 [Documentation](/docs/index.md) |
 [Examples](/examples) |
-[Changelog](https://github.com/TarekRaafat/eleva/changelog) |
+[Changelog](/CHANGELOG.md) |
 [GitHub Discussions](https://github.com/TarekRaafat/eleva/discussions)