eleva 1.0.0-rc.10 → 1.0.0-rc.12

package/README.md

@@ -1,8 +1,8 @@
-# eleva.js 🚀
+# Eleva.js 🚀
 
-> **Version:** 1.0.0-rc.10 | **Size:** ~6KB min (~2KB gzip) | **Dependencies:** Zero | **TypeScript:** Yes
+> **Version:** `1.0.0-rc.12` | **Size:** ~6KB min (~2.3KB gzip) | **Dependencies:** Zero | **TypeScript:** Yes
 
-Pure JavaScript, Pure Performance, Simply Elegant.
+**Best DX for Building the Best UX** — 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)
@@ -18,7 +18,7 @@ Pure JavaScript, Pure Performance, Simply Elegant.
 <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>
+  <a href="https://tarekraafat.github.io/eleva/"><img src="./docs/imgs/eleva.js Full Logo.png" alt="Eleva.js - Lightweight JavaScript Framework Logo" width="50%"></a>
 </p>
 
 <p align="center">
@@ -28,7 +28,7 @@ Pure JavaScript, Pure Performance, Simply Elegant.
 </p>
 
 <p align="center">
-  <em>Eleva.js is proudly supported by Canonical - the company behind Ubuntu.</em>
+  <em>Eleva is proudly supported by Canonical - the company behind Ubuntu.</em>
 </p>
 
 <p align="center">
@@ -39,12 +39,12 @@ Pure JavaScript, Pure Performance, Simply Elegant.
 <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!_ 😊
+**A minimalist, lightweight, pure vanilla JavaScript frontend runtime framework.**
+_Designed for the best Developer Experience (DX) to help you build exceptional User Experiences (UX). Built with love for native JavaScript and 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.10` - The core functionality is stable. Seeking community feedback before the final v1.0.0 release.
+> **Stability Notice**: This is `v1.0.0-rc.12` - The core functionality is stable. Seeking community feedback before the final v1.0.0 release.
 
-**Version:** `1.0.0-rc.10`
+**Version:** `1.0.0-rc.12`
 
 
 
@@ -52,14 +52,30 @@ Welcome to Eleva! This is my humble, experimental playground for a fresh approac
 
 ---
 
+## What is Eleva.js?
+
+**Eleva** is a minimalist, lightweight (6KB), pure vanilla JavaScript frontend framework crafted for **exceptional Developer Experience (DX)**. When developers enjoy building, users enjoy using — Eleva makes it effortless to create beautiful, responsive, and performant User Interfaces (UI) without the complexity, bundle size, or build tool requirements of traditional frameworks.
+
+Unlike React, Vue, or Angular, Eleva:
+- **Has zero dependencies** - No node_modules bloat
+- **Requires no build step** - Works directly in browsers via CDN
+- **Uses real DOM** - No virtual DOM overhead for simple apps
+- **Provides signal-based reactivity** - Fine-grained updates like Solid.js
+- **Includes TypeScript support** - Built-in type declarations
+
+Eleva is ideal for developers building lightweight web applications, prototypes, micro-frontends, or anyone seeking a simpler alternative to React, Vue, or Angular.
+
+---
+
 ## Table of Contents
 
-- [eleva.js 🚀](#elevajs-)
+- [Eleva.js 🚀](#elevajs-)
+  - [What is Eleva.js?](#what-is-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)
+  - [Best-in-Class Developer Experience (DX)](#best-in-class-developer-experience-dx)
   - [Features](#features)
   - [When to Use Eleva](#when-to-use-eleva)
   - [Version Strategy](#version-strategy)
@@ -67,6 +83,7 @@ Welcome to Eleva! This is my humble, experimental playground for a fresh approac
   - [Performance](#performance)
   - [Performance Benchmarks](#performance-benchmarks)
   - [Eleva vs. Popular Frameworks](#eleva-vs-popular-frameworks)
+  - [Browser Support](#browser-support)
   - [Installation](#installation)
   - [Usage](#usage)
     - [ES Module Example](#es-module-example)
@@ -79,10 +96,10 @@ Welcome to Eleva! This is my humble, experimental playground for a fresh approac
     - [Eleva (Core)](#eleva-core)
     - [Plugins](#plugins)
       - [Core Framework Only (Lightweight)](#core-framework-only-lightweight)
-      - [AttrPlugin](#attrplugin)
-      - [RouterPlugin](#routerplugin)
-      - [PropsPlugin](#propsplugin)
-      - [StorePlugin](#storeplugin)
+      - [Attr Plugin](#attr-plugin)
+      - [Router Plugin](#router-plugin)
+      - [Props Plugin](#props-plugin)
+      - [Store Plugin](#store-plugin)
   - [Development](#development)
   - [Testing](#testing)
   - [Contributing](#contributing)
@@ -121,12 +138,14 @@ app.mount(document.getElementById("app"), "Counter");
 
 ### Template Syntax
 
-| Syntax | Use |
-|--------|-----|
-| `${expr}` | Static value |
-| `{{ expr }}` | Reactive value |
-| `@click` | Event handler |
-| `:prop` | Pass to child |
+> **Quick Rule:** `${}` needs `ctx.` — `{{ }}` and `@events` don't.
+
+| Syntax | Use | `ctx.`? |
+|--------|-----|:-------:|
+| `${expr}` | Static value | ✓ |
+| `{{ expr }}` | Reactive value | ✗ |
+| `@click` | Event handler | ✗ |
+| `:prop` | Pass to child | ✓ |
 
 ---
 
@@ -161,16 +180,27 @@ This unopinionated approach makes Eleva versatile and ideal for developers who w
 
 ---
 
-## Handcrafted & Developer-Centric Design
+## Best-in-Class Developer Experience (DX)
 
-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.
+Eleva is built on a simple principle: **great DX leads to great UX**. When developers have intuitive tools, they build better interfaces. Every aspect of Eleva's design prioritizes your productivity and enjoyment.
+
+**Why Eleva's DX Stands Out:**
+
+| DX Feature | How It Helps You Build Better UX |
+|------------|----------------------------------|
+| **Zero Config** | Start building immediately — no webpack, no bundlers, no setup |
+| **Intuitive API** | Learn in minutes, master in hours — more time for polishing UI |
+| **Pure JavaScript** | No JSX, no compilation — what you write is what runs |
+| **Instant Feedback** | Signal-based reactivity shows changes immediately |
+| **TypeScript Built-in** | Full autocomplete and type safety out of the box |
+| **Tiny Bundle** | ~2.3KB gzipped means instant page loads for your users |
 
 - **🎨 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.
+- **🛠️ Developer-First:** Intuitive API and minimal core mean you spend less time wrestling with the framework and more time perfecting your UI.
+- **🌟 No Magic:** Pure vanilla JavaScript with no hidden abstractions — debug easily, ship confidently.
+- **🏗️ Scales With You:** From prototype to production, Eleva grows with your project without added complexity.
 
-This unique, developer-first approach makes Eleva a standout choice for building high-performance frontend applications without compromising on simplicity or control.
+> _"The best UX comes from developers who love their tools."_ — Eleva's DX philosophy
 
 ---
 
@@ -184,7 +214,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
+- **🎯 Built-in Plugins:** Attr for advanced attributes, Props for complex data handling, Router for client-side routing, and Store 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
@@ -201,9 +231,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.
+- **🚀 Built-in Routing:** Advanced client-side routing with navigation guards and reactive state via Router plugin.
+- **🎯 Advanced Attributes:** Sophisticated attribute handling with ARIA support via Attr plugin.
+- **🏪 Reactive State Management:** Centralized, reactive data store with persistence and namespacing via Store plugin.
 - **📦 Module Format Flexibility:** Choose from ESM, CommonJS, or UMD formats based on your project's needs.
 
 ---
@@ -212,7 +242,7 @@ 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 (RC):** Release candidate versions like `1.0.0-rc.10` indicate the API is stable but still gathering community feedback before the final release.
+- **Pre-release Versions (RC):** Release candidate versions like `1.0.0-rc.12` 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.
 
 ---
@@ -232,7 +262,7 @@ I follow [Semantic Versioning (SemVer)](https://semver.org/):
 
 Eleva is crafted for performance:
 
-- **Lightweight:** Approximately ~6 KB minified and ~2 KB gzipped.
+- **Lightweight:** Approximately ~6 KB minified and ~2.3 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.
@@ -243,23 +273,50 @@ Eleva is crafted for performance:
 
 ## Performance Benchmarks
 
-Preliminary benchmarks illustrate Eleva's efficiency compared to popular frameworks:
+Benchmarks using [js-framework-benchmark](https://krausest.github.io/js-framework-benchmark/) methodology (1,000 rows):
+
+| **Framework**                 | **Bundle Size (min+gzip)** | **Create 1K Rows** (ms) | **Partial Update** (ms) | **Memory** (MB) |
+| ----------------------------- | -------------------------- | ----------------------- | ----------------------- | --------------- |
+| **Eleva 1.0** (Direct DOM)    | **~2.3 KB**                | **~30**                 | ~105*                   | ~15             |
+| **React 19** (Virtual DOM)    | ~44 KB                     | 40-70                   | 10-20                   | 2-5             |
+| **Vue 3.5** (Reactive)        | ~45 KB                     | 25-45                   | 5-15                    | 2-4             |
+| **Angular 19** (Signals)      | ~90 KB                     | 50-80                   | 15-25                   | 3-6             |
+
+_*Eleva uses DOM diffing & patching, but templates generate HTML strings that require parsing. For large frequently-updating lists, use granular components or the `key` attribute for optimal diffing._
 
-| **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's Strengths:**
+- **Smallest bundle size** (~2.3 KB vs 44-90 KB)
+- **Competitive initial render** (~30ms for 1K rows)
+- **Zero dependencies** and minimal runtime overhead
+- **Direct DOM diffing** without virtual DOM overhead
 
-Detailed [Benchmark Metrics Report](BENCHMARK.md)
+**Performance Tips:**
+- Use `key` attribute on list items for optimal diffing
+- Split large lists into smaller components
+- Eleva excels at initial renders and small-to-medium updates
 
-> ⚠️ **Disclaimer:** Benchmarks are based on internal tests and may vary by project and environment.
+> 💡 **Run benchmarks yourself:** `bun run test:benchmark`
+
+> ⚠️ **Disclaimer:** Benchmarks vary by application complexity, browser, and hardware. Eleva results from internal test suite using Bun runtime. Other framework data from [js-framework-benchmark](https://krausest.github.io/js-framework-benchmark/).
 
 ---
 
 ## Eleva vs. Popular Frameworks
 
+How does Eleva compare to popular JavaScript frameworks like React, Vue, Svelte, and Angular?
+
+| Feature | Eleva 1.0 | React 19 | Vue 3.5 | Svelte 5 | Angular 19 |
+|---------|-----------|----------|---------|----------|------------|
+| **Bundle Size** | ~6KB | ~44KB | ~45KB | ~3KB* | ~90KB |
+| **Dependencies** | 0 | 3+ | 0 | 0 | 10+ |
+| **Virtual DOM** | No | Yes | Yes | No | No |
+| **Reactivity** | Signals | useState/Hooks | Refs/Reactive | Compiler | Zone.js |
+| **TypeScript** | Built-in | Optional | Optional | Built-in | Built-in |
+| **Build Required** | No | Yes | Optional | Yes | Yes |
+| **Learning Curve** | Low | Medium | Medium | Low | High |
+
+_*Svelte 5 compiles away with a ~3KB signals runtime, so bundle is minimal but build step is required._
+
 Eleva offers a refreshing alternative to frameworks like React, Vue, and Angular:
 
 - **Simplicity:** No virtual DOM, JSX, or complex state management-just plain JavaScript.
@@ -271,6 +328,26 @@ _Note:_ Eleva isn't trying to replace these giants but provides a lightweight op
 
 ---
 
+## Browser Support
+
+Eleva targets **modern evergreen browsers** and requires no polyfills.
+
+| Browser | Minimum Version |
+|---------|-----------------|
+| Chrome | 71+ |
+| Firefox | 69+ |
+| Safari | 12.1+ |
+| Edge | 79+ (Chromium) |
+| iOS Safari | 12.2+ |
+
+**Not Supported:** Internet Explorer, Legacy Edge (< 79)
+
+**Why?** Eleva uses modern JavaScript features (`queueMicrotask`, ES6 Classes, async/await) to maintain its tiny footprint. These browsers cover **96%+ of global web traffic**.
+
+> 💡 For legacy browser support, use Babel with appropriate polyfills.
+
+---
+
 ## Installation
 
 Eleva is available on npm. Try it out and share your thoughts!
@@ -318,10 +395,10 @@ app.component("HelloWorld", {
       }
     };
   },
-  template: ({ count }) => `
+  template: (ctx) => `
     <div>
       <h1>Hello, Eleva! 👋</h1>
-      <p>Count: ${count.value}</p>
+      <p>Count: ${ctx.count.value}</p>
       <button @click="() => count.value++">Increment</button>
     </div>
   `
@@ -359,10 +436,10 @@ Include Eleva via a script tag and use the global variable:
           const count = signal(0);
           return { count };
         },
-        template: ({ count }) => `
+        template: (ctx) => `
           <div>
             <h1>Hello, Eleva! 👋</h1>
-            <p>Count: ${count.value}</p>
+            <p>Count: ${ctx.count.value}</p>
             <button @click="() => count.value++">Increment</button>
           </div>
         `,
@@ -428,6 +505,15 @@ Interactive Demo: [CodePen](https://codepen.io/tarekraafat/pen/jEOyzYN?editors=1
 
 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.
 
+**Plugin Types:**
+
+| Type | Source | Installation |
+|------|--------|--------------|
+| **Core Plugins** | Bundled with Eleva | `import { X } from "eleva/plugins"` |
+| **External Plugins** | Community/Ecosystem | `npm install eleva-plugin-x` |
+
+> **Core plugins** (Attr, Props, Router, Store) are official, tested, and documented. **External plugins** are community-created and installed separately. See [Plugin Documentation](docs/plugins/index.md) for details.
+
 #### Core Framework Only (Lightweight)
 
 ```javascript
@@ -437,7 +523,7 @@ const app = new Eleva("myApp");
 // Core framework only - ~6KB minified
 ```
 
-#### AttrPlugin
+#### Attr Plugin
 
 Advanced attribute handling for ARIA, data attributes, boolean properties, and dynamic property detection:
 
@@ -470,7 +556,7 @@ app.component("myComponent", {
 
 📚 **[Full Attr Documentation →](docs/plugins/attr.md)** - Comprehensive guide with ARIA attributes, data attributes, boolean handling, and dynamic properties.
 
-#### RouterPlugin
+#### Router Plugin
 
 🚀 **Advanced client-side routing** with multiple modes, navigation guards, reactive state, and component resolution:
 
@@ -531,7 +617,7 @@ 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
+#### Props Plugin
 
 🎯 **Advanced props handling** with automatic type detection, parsing, and reactivity for complex data structures:
 
@@ -579,7 +665,7 @@ app.component("UserInfo", {
 
 📚 **[Full Props Documentation →](docs/plugins/props.md)** - Comprehensive guide with type parsing, reactive props, signal linking, complex data structures, and error handling.
 
-#### StorePlugin
+#### Store Plugin
 
 🏪 **Reactive state management** with centralized data store, persistence, namespacing, and cross-component reactive updates:
 
@@ -706,17 +792,17 @@ app.dispatch("increment");          // Dispatch actions globally
 
 **Bundle Sizes:**
 - Core framework only: ~6KB (minified)
-- Core + AttrPlugin: ~8KB (minified)
-- Core + PropsPlugin: ~10KB (minified)
-- Core + RouterPlugin: ~19KB (minified)
-- Core + StorePlugin: ~12KB (minified)
+- Core + Attr: ~8KB (minified)
+- Core + Props: ~10KB (minified)
+- Core + Router: ~21KB (minified)
+- Core + Store: ~12KB (minified)
 - Core + All plugins: ~25KB (minified)
 
 **Individual Plugin Sizes:**
-- AttrPlugin: ~2.4KB (minified)
-- PropsPlugin: ~4.2KB (minified)
-- RouterPlugin: ~13KB (minified)
-- StorePlugin: ~6KB (minified)
+- Attr: ~2.2KB (minified)
+- Props: ~4.2KB (minified)
+- Router: ~15KB (minified)
+- Store: ~6KB (minified)
 
 **Available Plugin Formats:**
 
@@ -725,11 +811,11 @@ app.dispatch("increment");          // Dispatch actions globally
 - 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>`
+- UMD: `<script src="https://cdn.jsdelivr.net/npm/eleva@latest/dist/eleva.umd.min.js"></script>`
+- UMD: `<script src="https://cdn.jsdelivr.net/npm/eleva@latest/dist/plugins/attr.umd.min.js"></script>`
+- UMD: `<script src="https://cdn.jsdelivr.net/npm/eleva@latest/dist/plugins/props.umd.min.js"></script>`
+- UMD: `<script src="https://cdn.jsdelivr.net/npm/eleva@latest/dist/plugins/router.umd.min.js"></script>`
+- UMD: `<script src="https://cdn.jsdelivr.net/npm/eleva@latest/dist/plugins/store.umd.min.js"></script>`
 
 **Individual Plugin Imports (Best for Tree-Shaking):**
 - ESM: `import { Attr } from 'eleva/plugins/attr'`
@@ -791,10 +877,20 @@ I welcome developers to dive in and experiment with Eleva! Here's how to get sta
 
 ## Testing
 
-I use Jest for testing. Run the test suite with:
+Eleva has a comprehensive test suite with **100% line coverage**:
+
+| Metric | Value |
+|--------|-------|
+| **Total Tests** | 273 |
+| **Line Coverage** | 100% |
+| **Test Runner** | Bun |
+
+Run the test suite:
 
 ```bash
-npm test
+bun test              # Run all tests
+bun test:coverage     # Run with coverage report
+bun test:benchmark    # Run performance benchmarks
 ```
 
 Contributions to tests are very welcome! 🧪