eleva 1.0.0-rc.1 → 1.0.0-rc.10

package/README.md

@@ -1,5 +1,7 @@
 # eleva.js 🚀
 
+> **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)
@@ -10,7 +12,7 @@ Pure JavaScript, Pure Performance, Simply Elegant.
 [![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)](https://www.jsdelivr.com/package/npm/eleva)
+[![](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>
@@ -38,11 +40,11 @@ Pure JavaScript, Pure Performance, Simply Elegant.
 <br>
 
 **A minimalist, lightweight, pure vanilla JavaScript frontend runtime framework.**  
-_Built with love for native JavaScript-because sometimes, less really is more!_ 😊
+_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-rc.1` - The core functionality is stable, but I'm seeking community feedback before the final v1.0.0 release.
+> **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-rc.1`
+**Version:** `1.0.0-rc.10`
 
 
 
@@ -54,6 +56,7 @@ Welcome to Eleva! This is my humble, experimental playground for a fresh approac
 
 - [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)
@@ -74,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)
@@ -82,17 +91,56 @@ 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 heavy frameworks or 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 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 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.
 
@@ -100,9 +148,9 @@ The idea behind Eleva comes from a deep appreciation for native JavaScript. I wa
 
 ## Design Philosophy
 
-**Eleva is an unopinionated framework.**
+**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:** 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.
@@ -136,6 +184,7 @@ This unique, developer-first approach makes Eleva a standout choice for building
 - **🔄 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
@@ -152,6 +201,9 @@ Eleva is ideal for developers seeking a lightweight, flexible, and high-performa
 - **🎯 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.
 
 ---
@@ -160,9 +212,8 @@ 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.2.0-alpha` indicate the API is still evolving. Expect frequent updates and share your feedback!
+- **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.
-- **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.
 
 ---
 
@@ -196,10 +247,10 @@ Preliminary benchmarks illustrate Eleva's efficiency compared to popular framewo
 
 | **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)                                 |
+| **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)                                 |
 
 Detailed [Benchmark Metrics Report](BENCHMARK.md)
 
@@ -373,6 +424,323 @@ Interactive Demo: [CodePen](https://codepen.io/tarekraafat/pen/jEOyzYN?editors=1
 - **`.mount(container, compName, props)`**  
   Mount a component to the DOM.
 
+### 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.
 
 ---
@@ -453,7 +821,7 @@ Eleva is open-source and available under the [MIT License](LICENSE).
 
 ---
 
-**Note:** This is a beta 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! 💪✨
 
 ---