ladrillosjs 2.0.0-beta.1 → 2.0.0-beta.10

package/README.md

@@ -1,899 +1,672 @@
 # LadrillosJS
 
-<img src="https://raw.githubusercontent.com/drubiodev/LadrillosJS/refs/heads/main/LadrillosJS.png" alt="LadrillosJS" width="400"/>
-
-A lightweight, zero-dependency web component framework for building modular web applications.
-
-**Version 2.0** - Now rewritten in TypeScript with enhanced performance, better developer experience, and powerful new features.
-
-"I designed this framework to empower developers with the ability to componentize their code efficiently and effectively, without the need for a full-scale framework. By focusing on simplicity and leveraging core web fundamentals, my goal was to create a lightweight and accessible solution that enhances development while staying true to the basics."
-
-## Table of Contents
-
-- [Features](#features)
-- [Getting Started](#getting-started)
-  - [Prerequisites](#prerequisites)
-  - [What's New in v2.0](#whats-new-in-v20)
-  - [Example Applications](#example-applications)
-- [Installation](#installation)
-- [Your First Component](#your-first-component)
-- [Core Concepts](#core-concepts)
-  - [Component Registration](#component-registration)
-  - [State Management](#state-management)
-  - [Event Handling](#event-handling)
-  - [Data Binding](#data-binding)
-  - [Conditional Rendering](#conditional-rendering)
-  - [Slots](#slots)
-- [Advanced Features](#advanced-features)
-  - [External Scripts](#external-scripts)
-  - [Global Event Bus](#global-event-bus)
-  - [Shadow DOM](#shadow-dom)
-  - [Performance & Caching](#performance--caching)
-- [API Reference](#api-reference)
-- [Examples](#examples)
-  - [Component Communication](#component-communication)
-  - [Dynamic Component Creation](#dynamic-component-creation)
-  - [Passing Complex Data](#passing-complex-data)
-- [Migration Guide (v1.x to v2.0)](#migration-guide-v1x-to-v20)
-- [Contributing](#contributing)
-- [License](#license)
-
-## Features
-
-- 🚀 **Zero Dependencies** - Pure JavaScript, no build tools required
-- 📦 **Single-File Components** - HTML, CSS, and JavaScript in one file
-- ⚡ **Reactive State** - Automatic re-rendering on state changes with optimized proxies
-- 🎯 **Event System** - Built-in event emission and global event bus for component communication
-- 🔄 **Two-Way Data Binding** - Seamless binding for form inputs with `$bind`
-- 🎨 **Scoped Styles** - Component styles with optional Shadow DOM
-- 🏪 **Global Event Bus** - Cross-component communication without prop drilling
-- 🔌 **Slots Support** - Content projection with named and default slots
-- 📝 **TypeScript Support** - Full type definitions and TypeScript source code
-- 🎭 **Conditional Rendering** - `data-if`, `data-else-if`, and `data-else` directives
-- 🚄 **Smart Caching** - LRU cache for components and compiled functions
-- 🔧 **Framework Utilities** - `$state`, `$setState`, `$emit`, `$listen`, `$querySelector` helpers
-- ⚙️ **Automatic Reactivity** - Variable assignments automatically trigger re-renders
-- 🧩 **External Scripts** - Load and bind external JavaScript with your components
-
-## Getting Started
-
-### Prerequisites
-
-- **Node.js**: Version 20.19+ or 22.12+ is required for development
-- **TypeScript**: v5.8+ (included in devDependencies)
-
-### What's New in v2.0
-
-- **🔄 Complete TypeScript Rewrite** - Full type safety and improved IDE support
-- **⚡ Performance Enhancements** - LRU caching for components and compiled functions
-- **🎯 Global Event Bus** - New `$emit` and `$listen` for cross-component communication
-- **🔧 Framework Utilities** - New `$state`, `$setState`, `$querySelector` helpers
-- **🚀 Automatic Reactivity** - Variable assignments like `count++` automatically trigger re-renders
-- **📦 Better Build System** - Vite-powered builds with sourcemaps and multiple output formats (ESM, UMD, CJS)
-- **🧪 Testing** - Vitest with coverage reporting
-- **🎭 Enhanced Conditionals** - More robust `data-if`, `data-else-if`, `data-else` rendering
-- **🔄 Two-Way Binding** - Simplified with `$bind` prefix for automatic state synchronization
-- **🧹 Memory Management** - Automatic cleanup of event listeners on component disconnect
-
-### Example Applications
-
-The repository includes several example applications that demonstrate various features:
-
-- **[Todo App](samples/apps/todo)** - Classic todo list with component composition
-- **[Notes App](samples/apps/notes)** - Multi-component app with global event bus
-- **[Markdown Editor](samples/apps/markdown)** - Real-time markdown preview
-- **[API Example](samples/apps/api)** - Fetching and displaying external data
-- **[Business Card](samples/apps/biz)** - Editable form with two-way data binding using `$bind`
-- **[Button Game](samples/apps/button-game)** - Interactive game with component events
-- **[Slideshow](samples/apps/slideshow)** - Multi-slide presentation system
-- **[Document Chat](samples/apps/document-chat)** - Chat interface with component communication
-- **[Docs](samples/apps/docs)** - Documentation viewer with syntax highlighting
-
-To run the examples:
+<p align="center">
+  <img src="https://raw.githubusercontent.com/drubiodev/LadrillosJS/refs/heads/main/LadrillosJS.jpg" alt="LadrillosJS" width="300"/>
+</p>
 
-```bash
-# Clone the repository
-git clone https://github.com/drubiodev/LadrillosJS.git
-cd LadrillosJS
+<p align="center">
+  <strong>A lightweight, zero-dependency web component framework.</strong>
+</p>
 
-# Install dependencies
-npm install
+<p align="center">
+  <a href="https://www.npmjs.com/package/ladrillosjs"><img src="https://img.shields.io/npm/v/ladrillosjs.svg" alt="npm version"></a>
+  <a href="https://github.com/drubiodev/LadrillosJS/blob/main/LICENSE"><img src="https://img.shields.io/npm/l/ladrillosjs.svg" alt="license"></a>
+  <a href="https://bundlephobia.com/package/ladrillosjs"><img src="https://img.shields.io/bundlephobia/minzip/ladrillosjs" alt="bundle size"></a>
+  <a href="https://github.com/drubiodev/LadrillosJS"><img src="https://img.shields.io/github/stars/drubiodev/LadrillosJS?style=social" alt="GitHub stars"></a>
+</p>
 
-# Start the development server (Vite)
-npm run dev
+<p align="center">
+  Build modular web apps with simple HTML components. No virtual DOM, no complex tooling required.
+</p>
 
-# Build the library
-npm run build
-
-# Run tests
-npm test
-
-# Run tests with coverage
-npm run test:coverage
-```
+---
 
-## Installation
+## 📑 Table of Contents
+
+- [Quick Start](#-quick-start)
+- [Installation](#-installation)
+- [Core Concepts](#-core-concepts)
+- [Directives](#-directives)
+- [Event Bus](#-event-bus)
+- [Element References](#-element-references)
+- [Lazy Loading](#-lazy-loading)
+- [API Reference](#-api-reference)
+- [Using with Vite](#-using-with-vite)
+- [Browser Support](#-browser-support)
+- [Examples](#-examples)
+- [Contributing](#-contributing)
+- [License](#-license)
 
-### NPM
+---
 
-```bash
-npm install ladrillosjs
-```
+## 🚀 Quick Start
 
-### CDN
+### 1. Add the Script
 
 ```html
-<!-- Latest version -->
 <script type="module">
-  import { registerComponent } from "https://cdn.jsdelivr.net/npm/ladrillosjs/dist/ladrillosjs.es.js";
-  registerComponent("my-component", "./my-component.html");
-</script>
-
-<!-- UMD (for legacy browsers) -->
-<script src="https://cdn.jsdelivr.net/npm/ladrillosjs/dist/ladrillosjs.umd.js"></script>
-<script>
-  // Access via global ladrillosjs object
-  ladrillosjs.registerComponent("my-component", "./my-component.html");
+  import ladrillosjs from "https://cdn.jsdelivr.net/npm/ladrillosjs@2/dist/index.js";
+  window.ladrillosjs = ladrillosjs;
 </script>
 ```
 
-## Your First Component
-
-A component in LadrillosJS is a reusable custom HTML element that bundles its own template, logic, and styles into a single file.
+### 2. Create a Component
 
-### 1. Create a Component File
-
-Create `hello-world.html`:
+Save this as `counter.html`:
 
 ```html
-<!-- hello-world.html -->
-<div class="greeting">
-  <h1>{title}</h1>
-  <p>Hello, {name}!</p>
-  <button onclick="greet">Click me ({count})</button>
+<div class="counter">
+  <div class="count-display">{count}</div>
+  <div class="buttons">
+    <button onclick="count--">−</button>
+    <button onclick="count = 0">Reset</button>
+    <button onclick="count++">+</button>
+  </div>
+  <p>Double: {count * 2} | Squared: {count * count}</p>
 </div>
 
 <script>
-  // Component state
-  let title = "Welcome to LadrillosJS";
-  let name = "World";
   let count = 0;
-
-  // Event handler
-  const greet = () => {
-    count++;
-    name = prompt("What's your name?") || "World";
-  };
 </script>
 
 <style>
-  .greeting {
+  .counter {
     text-align: center;
     padding: 2rem;
-    background: #f0f0f0;
-    border-radius: 8px;
   }
-
+  .count-display {
+    font-size: 4rem;
+    font-weight: bold;
+  }
   button {
     padding: 0.5rem 1rem;
-    font-size: 1rem;
+    margin: 0.25rem;
     cursor: pointer;
   }
 </style>
 ```
 
-### 2. Register and Use the Component
+### 3. Use It
 
 ```html
 <!DOCTYPE html>
 <html>
   <head>
-    <title>My App</title>
-  </head>
-  <body>
-    <!-- Use your component -->
-    <hello-world></hello-world>
-
-    <!-- Register component -->
     <script type="module">
-      import { registerComponent } from "ladrillosjs";
-      registerComponent("hello-world", "./hello-world.html");
+      import { registerComponent } from "https://cdn.jsdelivr.net/npm/ladrillosjs@2/dist/index.js";
+      registerComponent("my-counter", "./counter.html");
     </script>
+  </head>
+  <body>
+    <my-counter></my-counter>
   </body>
 </html>
 ```
 
-## Core Concepts
+That's it! Your reactive component is ready. 🎉
+
+---
+
+## 📦 Installation
 
-### Component Registration
+### CDN (No Build Step)
 
-Register single or multiple components:
+LadrillosJS v2 is distributed as native ES modules. Import directly from a CDN:
+
+```html
+<!-- ES Module (recommended) -->
+<script type="module">
+  import {
+    registerComponent,
+    registerComponents,
+  } from "https://cdn.jsdelivr.net/npm/ladrillosjs@2/dist/index.js";
+
+  registerComponent("my-component", "./component.html");
+</script>
+
+<!-- Also available on unpkg -->
+<script type="module">
+  import { registerComponent } from "https://unpkg.com/ladrillosjs@2/dist/index.js";
+</script>
+```
+
+> **Note:** LadrillosJS v2 is ESM-only. Legacy UMD/IIFE global builds are not published to npm.
+
+### NPM (With Build Tools)
+
+```bash
+npm install ladrillosjs
+```
 
 ```javascript
+import { registerComponent, registerComponents } from "ladrillosjs";
+
 // Single component
-import { registerComponent } from "ladrillosjs";
-await registerComponent("my-component", "./my-component.html");
+registerComponent("my-counter", "./components/counter.html");
 
-// Multiple components (v2.0 feature - currently in development)
-import { registerComponents } from "ladrillosjs";
+// Multiple components
 await registerComponents([
   { name: "app-header", path: "./components/header.html" },
   { name: "app-footer", path: "./components/footer.html" },
-  { name: "user-card", path: "./components/user-card.html" },
 ]);
-
-// Using CDN
-ladrillosjs.registerComponent("my-component", "./my-component.html");
 ```
 
-**Note:** The `registerComponents` function is planned for v2.0 to enable bulk registration with concurrency control.
+### Granular Imports (Tree-Shaking)
 
-### State Management
+```javascript
+// Full API
+import { registerComponent, $emit, $listen } from "ladrillosjs";
 
-Components have reactive state that automatically triggers re-renders. In v2.0, variable assignments are automatically tracked and trigger reactivity:
+// Core only (no lazy loading, no event bus)
+import { registerComponent } from "ladrillosjs/core";
 
-```html
-<div>
-  <h2>User: {user.name}</h2>
-  <p>Score: {score}</p>
-  <button onclick="updateScore">Add Point</button>
-  <button onclick="increment">Count: {count}</button>
-</div>
+// Lazy loading strategies only
+import { lazyOnVisible, lazyOnIdle } from "ladrillosjs/lazy";
 
-<script>
-  // Initial state - automatically tracked
-  let score = 0;
-  let count = 0;
-  let user = {
-    name: "Player 1",
-  };
-
-  const updateScore = () => {
-    // Direct assignment triggers re-render automatically
-    score++;
-  };
-
-  const increment = () => {
-    // All these automatically trigger re-renders in v2.0
-    count++; // Increment
-    count += 5; // Compound assignment
-    count = count * 2; // Direct assignment
-  };
-
-  // You can also use the explicit setState method
-  const updateUser = () => {
-    $setState({ user: { name: "Jane", age: 30 } });
-  };
-</script>
+// Event bus only
+import { $emit, $listen } from "ladrillosjs/events";
 ```
 
-**New in v2.0:**
+---
 
-- **Automatic Reactivity**: `count++`, `count += 5`, and direct assignments automatically trigger re-renders
-- **`$state`**: Direct access to component state within scripts
-- **`$setState(updates)`**: Explicit state updates (merges with existing state)
+## 📖 Core Concepts
 
-### Event Handling
+### Template Bindings
 
-Multiple ways to handle events:
+Use `{expression}` to display reactive data. Any JavaScript expression works:
 
 ```html
-<!-- Method reference -->
-<button onclick="handleClick">Click me: {count}</button>
-
-<!-- Function with arguments -->
-<button onclick="addItem('Hello', 123)">Add Item</button>
+<h1>{title}</h1>
+<p>Hello, {user.name}!</p>
+<span>Total: {items.length} items</span>
+<p>Is adult: {age >= 18 ? 'Yes' : 'No'}</p>
+```
 
-<!-- Inline arrow function -->
-<button onclick="(e) => console.log(e.target)">Log Target</button>
+### Reactive State
 
-<!-- Component communication with event bus (v2.0) -->
-<button onclick="notifyOthers">Emit Event</button>
+Just declare variables with `let` — changes automatically update the DOM:
 
+```html
 <script>
   let count = 0;
-  let items = [];
-
-  const handleClick = (event) => {
-    console.log("Clicked!", event);
-    count++;
-  };
-
-  const addItem = (name, value) => {
-    items = [...items, { name, value }];
-  };
-
-  // v2.0: Use $emit to send events to other components
-  const notifyOthers = () => {
-    $emit("item-added", { count, timestamp: Date.now() });
-  };
-
-  // v2.0: Listen for events from other components
-  $listen("user-logged-in", (data) => {
-    console.log("User logged in:", data);
-    count = 0; // Reset count
-  });
+  let user = { name: "Alice", role: "Developer" };
+  let items = ["Apple", "Banana", "Cherry"];
 </script>
 ```
 
-**New in v2.0:**
-
-- **`$emit(eventName, data)`**: Send events to other components via global event bus
-- **`$listen(eventName, callback)`**: Listen for events from any component
-- **Automatic Cleanup**: Event listeners are automatically removed when component is disconnected
+### Event Handlers
 
-### Data Binding
-
-LadrillosJS supports both one-way and two-way data binding:
-
-#### One-Way Binding (Template Interpolation)
+Attach events directly in HTML with inline expressions or function calls:
 
 ```html
-<div>
-  <h1>{title}</h1>
-  <p>{user.name} - {user.email}</p>
-  <span>Items: {items.length}</span>
-</div>
-
-<script>
-  let title = "My App";
-  let user = { name: "John", email: "john@example.com" };
-  let items = [1, 2, 3];
-</script>
+<button onclick="count++">Increment</button>
+<button onclick="handleClick()">Click me</button>
+<input onkeyup="search(event.target.value)" />
+<form onsubmit="handleSubmit(event)">...</form>
 ```
 
-#### Two-Way Binding (v2.0 Enhanced)
+### Two-Way Binding
 
-Use the `$bind` prefix to create automatic two-way bindings with form inputs:
+Use `$bind` to sync form inputs with state:
 
 ```html
-<div>
-  <h2>Hello, {$name}!</h2>
-  <input type="text" $bind="name" placeholder="Enter your name" />
-
-  <p>Email: {$email}</p>
-  <input type="email" $bind="email" />
+<input type="text" $bind="username" placeholder="Enter name" />
+<p>Hello, {username}!</p>
 
-  <p>Bio: {$bio}</p>
-  <textarea $bind="bio"></textarea>
+<textarea $bind="bio"></textarea>
 
-  <p>Country: {$country}</p>
-  <select $bind="country">
-    <option value="us">United States</option>
-    <option value="uk">United Kingdom</option>
-    <option value="ca">Canada</option>
-  </select>
-</div>
+<select $bind="country">
+  <option value="us">United States</option>
+  <option value="uk">United Kingdom</option>
+</select>
 
 <script>
-  // Variables with $bind are automatically synced with inputs
-  let $name = "World";
-  let $email = "";
-  let $bio = "";
-  let $country = "us";
+  let username = "";
+  let bio = "";
+  let country = "us";
 </script>
 ```
 
-**New in v2.0:**
+---
 
-- **`$bind` attribute**: Simplified two-way binding syntax
-- **Automatic State Sync**: Input changes automatically update component state
-- **All Input Types**: Works with text inputs, textareas, selects, checkboxes, and radio buttons
-- **Nested Paths**: Supports nested object bindings like `$bind="user.email"`
+## 🧩 Built-in Elements & Directives
 
 ### Conditional Rendering
 
-Control element visibility with conditional directives:
+Use `<if>`, `<else-if>`, and `<else>` to conditionally render elements:
 
 ```html
-<div>
-  <h1>Shopping Cart ({items.length} items)</h1>
-
-  <div data-if="items.length === 0">
-    <p>Your cart is empty</p>
-  </div>
+<if condition="status === 'loading'">Loading...</if>
+<else-if condition="status === 'error'">Something went wrong!</else-if>
+<else>Content loaded successfully!</else>
 
-  <div data-else-if="items.length < 3">
-    <p>You have a few items</p>
-  </div>
+<script>
+  let status = "loading";
+</script>
+```
 
-  <div data-else>
-    <p>You have many items!</p>
-  </div>
+### Show/Hide (CSS Toggle)
 
-  <button data-if="!isLoggedIn" onclick="login">Login</button>
-  <button data-else onclick="logout">Logout</button>
-</div>
+Use `<show>` to toggle visibility without removing from DOM (uses `display: none`):
 
-<script>
-  let items = ["apple", "banana"];
-  let isLoggedIn = false;
+```html
+<show condition="isVisible">I can be shown or hidden</show>
 
-  const login = () => {
-    isLoggedIn = true;
-  };
+<button onclick="isVisible = !isVisible">Toggle</button>
 
-  const logout = () => {
-    isLoggedIn = false;
-  };
+<script>
+  let isVisible = true;
 </script>
 ```
 
-**Conditional Directives:**
+> **`<show>` vs `<if>`:** `<show>` toggles CSS display (children stay in DOM), `<if>` adds/removes children entirely.
 
-- **`data-if="expression"`**: Show element if expression is truthy
-- **`data-else-if="expression"`**: Chain multiple conditions
-- **`data-else`**: Fallback when all previous conditions are false
+### List Rendering
 
-### Slots
-
-Content projection using slots:
+Use `<for>` to render lists with optional index and key:
 
 ```html
-<!-- card.html -->
-<div class="card">
-  <div class="card-header">
-    <slot name="header">Default Header</slot>
-  </div>
-  <div class="card-body">
-    <slot></slot>
-    <!-- Default slot -->
-  </div>
-  <div class="card-footer">
-    <slot name="footer"></slot>
+<!-- Simple list -->
+<ul>
+  <for each="fruit in fruits">
+    <li>🍎 {fruit}</li>
+  </for>
+</ul>
+
+<!-- With index -->
+<for each="(item, index) in items">
+  <div>#{index + 1}: {item}</div>
+</for>
+
+<!-- Object array with key -->
+<for each="user in users" key="user.id">
+  <div>
+    <span>{user.avatar}</span>
+    <span>{user.name}</span>
+    <span>{user.role}</span>
   </div>
-</div>
+</for>
 
-<!-- Usage -->
-<my-card>
-  <h2 slot="header">User Profile</h2>
-  <p>This goes in the default slot</p>
-  <button slot="footer">Save</button>
-</my-card>
+<script>
+  let fruits = ["Apple", "Banana", "Cherry"];
+  let items = ["First", "Second", "Third"];
+  let users = [
+    { id: 1, name: "Alice", role: "Developer", avatar: "👩‍💻" },
+    { id: 2, name: "Bob", role: "Designer", avatar: "👨‍🎨" },
+  ];
+</script>
 ```
 
-## Advanced Features
+### Lazy Loading
 
-### External Scripts
-
-Load external JavaScript with components and bind them to the component context:
+Use `<lazy>` to defer rendering until a trigger fires (viewport, idle, delay, interaction, media):
 
 ```html
-<!-- With 'bind' attribute for component context -->
-<script src="./helpers.js" bind></script>
-
-<!-- ES modules with bind -->
-<script src="./component-logic.js" type="module" bind></script>
+<lazy margin="100px">
+  <heavy-chart></heavy-chart>
+</lazy>
 
-<!-- Regular external script (global scope) -->
-<script src="https://cdn.example.com/library.js"></script>
+<lazy interaction="click,focus">
+  <support-chat></support-chat>
+</lazy>
 ```
 
-For modules with `bind`, export a default function that receives the component context:
+### Cheat Sheet
+
+| Element / Directive | Purpose                  | Example                                                |
+| ------------------- | ------------------------ | ------------------------------------------------------ |
+| `<if>`              | Conditional render       | `<if condition="isLoggedIn">Welcome!</if>`             |
+| `<else-if>`         | Chained condition        | `<else-if condition="isGuest">Hello Guest</else-if>`   |
+| `<else>`            | Fallback                 | `<else>Please log in</else>`                           |
+| `<show>`            | CSS visibility toggle    | `<show condition="isOpen">Menu</show>`                 |
+| `<for>`             | Loop rendering           | `<for each="item in items"><li>{item}</li></for>`      |
+| `<for>` (indexed)   | Loop with index          | `<for each="(item, i) in items">…</for>`               |
+| `<for key="…">`     | List optimization        | `<for each="u in users" key="u.id">…</for>`            |
+| `<lazy>`            | Defer rendering          | `<lazy idle><analytics-pixel /></lazy>`                |
+| `$bind`             | Two-way binding          | `<input $bind="email" />`                              |
+| `$ref`              | Element reference        | `<input $ref="inputEl" />`                             |
 
-```javascript
-// component-logic.js
-export default function () {
-  // 'this' refers to the component instance
-  // Access component utilities
-  const { $state, $setState, $emit, $listen } = this;
-
-  this.formatDate = (date) => {
-    return new Intl.DateTimeFormat("en-US").format(date);
-  };
-
-  this.loadData = async () => {
-    const response = await fetch("/api/data");
-    const data = await response.json();
-    $setState({ data });
-  };
-
-  // Listen for events from other components
-  $listen("refresh-data", () => {
-    this.loadData();
-  });
+---
 
-  // Called automatically if defined
-  if (this.init) {
-    this.init();
-  }
-}
-```
+## 📡 Event Bus
 
-**New in v2.0:**
+Communicate between components using `$emit` and `$listen`:
 
-- **Better Context Binding**: External scripts get full access to component utilities
-- **`$emit` and `$listen`**: Available in external scripts for event communication
-- **Automatic Initialization**: Functions are auto-attached to component context
+### Sender Component
 
-### Global Event Bus
+```html
+<button onclick="sendMessage()">Send Message</button>
 
-**New in v2.0:** The global event bus enables cross-component communication without prop drilling or shared state.
+<script>
+  let message = "Hello from sender!";
 
-```javascript
-// In any component script
-// Emit an event
-$emit("user-logged-in", { userId: 123, username: "john" });
-
-// Listen for events
-$listen("user-logged-in", (data) => {
-  console.log(`User ${data.username} logged in`);
-  // Update local state
-  isLoggedIn = true;
-  currentUser = data;
-});
+  function sendMessage() {
+    $emit("my-event", { text: message, time: new Date().toLocaleTimeString() });
+  }
+</script>
 ```
 
-#### Example: Header & Login Components
+### Receiver Component
 
 ```html
-<!-- header.html -->
-<header>
-  <span data-if="isLoggedIn">Welcome, {username}!</span>
-  <button data-else onclick="showLogin">Login</button>
-</header>
+<div>
+  <p>Received: {receivedMessage}</p>
+</div>
 
 <script>
-  let isLoggedIn = false;
-  let username = "";
+  let receivedMessage = "Waiting...";
 
-  // Listen for login event from other components
-  $listen("user-logged-in", (user) => {
-    isLoggedIn = true;
-    username = user.username;
+  $listen("my-event", (data) => {
+    receivedMessage = data.text;
   });
-
-  const showLogin = () => {
-    $emit("show-login-modal");
-  };
 </script>
 ```
 
-```html
-<!-- login-form.html -->
-<form onsubmit="handleLogin">
-  <input type="text" $bind="username" placeholder="Username" />
-  <input type="password" $bind="password" placeholder="Password" />
-  <button type="submit">Login</button>
-</form>
+---
 
-<script>
-  let $username = "";
-  let $password = "";
-
-  const handleLogin = (e) => {
-    e.preventDefault();
-
-    // Emit login success event
-    $emit("user-logged-in", {
-      userId: 123,
-      username: $username,
-    });
-
-    // Clear form
-    $username = "";
-    $password = "";
-  };
-</script>
-```
+## 🏷️ Element References
 
-**Event Bus Benefits:**
+Use `$ref` to get direct DOM access for advanced manipulation:
 
-- **No Prop Drilling**: Components can communicate directly
-- **Decoupled Architecture**: Components don't need to know about each other
-- **Automatic Cleanup**: Listeners are removed when components disconnect
-- **Promise Support**: `$emit` returns a promise when listeners are async
+```html
+<input type="text" $ref="inputEl" placeholder="Click button to focus" />
+<button onclick="focusInput()">Focus Input</button>
 
-### Removed: Global State Stores
+<canvas $ref="canvas" width="200" height="100"></canvas>
+<button onclick="draw()">Draw on Canvas</button>
 
-**Breaking Change in v2.0:** The `createStore` API has been removed in favor of the more powerful global event bus pattern. Instead of shared stores, use the event bus for cross-component communication:
+<script>
+  function focusInput() {
+    $refs.inputEl.focus();
+    $refs.inputEl.select();
+  }
 
-**Before (v1.x with stores):**
+  function draw() {
+    const ctx = $refs.canvas.getContext("2d");
+    ctx.fillStyle = "blue";
+    ctx.fillRect(10, 10, 100, 50);
+  }
+</script>
+```
 
-```javascript
-import { createStore } from "ladrillosjs";
+---
 
-export const userStore = createStore({
-  user: null,
-  isAuthenticated: false,
-});
+## ⏳ Lazy Loading
 
-userStore.subscribe((state) => {
-  this.setState(state);
-});
-```
+Load components only when needed to improve initial page load:
 
-**After (v2.0 with event bus):**
+### Lazy Loading Strategies
 
 ```javascript
-// Emit events to notify components of changes
-$emit("user-updated", { user: userData, isAuthenticated: true });
-
-// Listen for changes in components that need them
-$listen("user-updated", ({ user, isAuthenticated }) => {
-  // Update local component state
-  currentUser = user;
-  loggedIn = isAuthenticated;
-});
+import {
+  registerComponents,
+  lazyOnVisible,
+  lazyOnIdle,
+  lazyOnInteraction,
+  lazyOnMedia,
+  lazyOnDelay,
+} from "ladrillosjs";
+
+await registerComponents([
+  // Load when visible in viewport
+  {
+    name: "lazy-footer",
+    path: "./footer.html",
+    lazy: lazyOnVisible({ rootMargin: "100px" }),
+  },
+
+  // Load when browser is idle
+  {
+    name: "analytics-widget",
+    path: "./analytics.html",
+    lazy: lazyOnIdle(5000), // timeout: 5s max wait
+  },
+
+  // Load on user interaction
+  {
+    name: "modal-dialog",
+    path: "./modal.html",
+    lazy: lazyOnInteraction(["click", "focusin"]),
+  },
+
+  // Load based on media query
+  {
+    name: "mobile-nav",
+    path: "./mobile-nav.html",
+    lazy: lazyOnMedia("(max-width: 768px)"),
+  },
+
+  // Load after delay
+  {
+    name: "chat-widget",
+    path: "./chat.html",
+    lazy: lazyOnDelay(3000), // 3 second delay
+  },
+]);
 ```
 
-### Shadow DOM
+| Strategy            | Use Case                                     |
+| ------------------- | -------------------------------------------- |
+| `lazyOnVisible`     | Below-fold content, footers, image galleries |
+| `lazyOnIdle`        | Non-critical features, analytics             |
+| `lazyOnInteraction` | Modals, dropdowns, tooltips                  |
+| `lazyOnMedia`       | Mobile/desktop specific components           |
+| `lazyOnDelay`       | Chat widgets, notifications                  |
 
-Components use Shadow DOM by default for style encapsulation. To disable:
+### Eager Override
 
-```javascript
-// Disable Shadow DOM for a component
-await registerComponent("my-component", "./my-component.html", false);
+Force a lazy component to load immediately by adding the `eager` attribute:
 
-// With Shadow DOM enabled (default)
-await registerComponent("isolated-widget", "./widget.html", true);
+```html
+<lazy-footer eager></lazy-footer>
 ```
 
-**Shadow DOM Benefits:**
-
-- **Style Isolation**: Component styles don't leak to global scope
-- **Encapsulation**: Internal DOM structure is hidden from parent
-- **Cleaner DOM**: Styles and scripts are scoped to component
-
-**When to Disable:**
+---
 
-- Need global CSS styles to apply
-- Using third-party CSS frameworks
-- Debugging with browser dev tools (easier without shadow DOM)
+## 📋 API Reference
 
-### Performance & Caching
+### `registerComponent`
 
-**New in v2.0:** LRU (Least Recently Used) caching for improved performance:
+```javascript
+registerComponent(name, path, useShadowDOM?, lazy?)
+```
 
-#### Component Caching
+| Parameter      | Type                    | Default  | Description                     |
+| -------------- | ----------------------- | -------- | ------------------------------- |
+| `name`         | string                  | required | Tag name (must include hyphen)  |
+| `path`         | string                  | required | Path to `.html` component file  |
+| `useShadowDOM` | boolean                 | `true`   | Enable Shadow DOM encapsulation |
+| `lazy`         | boolean \| LazyStrategy | `false`  | Lazy loading configuration      |
 
-- **25 Components**: Automatically caches up to 25 component HTML files
-- **LRU Eviction**: Least recently used components are removed when cache is full
-- **Faster Re-renders**: Cached components load instantly on re-use
+```javascript
+// Basic usage
+registerComponent("my-button", "./button.html");
 
-#### Function Caching
+// Without Shadow DOM (for global CSS)
+registerComponent("my-nav", "./nav.html", false);
 
-- **100 Functions**: Caches up to 100 compiled template expressions
-- **Prevents Memory Leaks**: Reuses Function objects for identical expressions
-- **Example**: `{formatName("John")}` compiles once and is reused on every render
+// With lazy loading
+registerComponent("my-footer", "./footer.html", true, lazyOnVisible());
+```
 
-**Performance Improvements:**
+### `registerComponents`
 
-- Reduced HTTP requests for components
-- Faster template rendering with cached functions
-- Optimized state updates with change detection
-- Efficient re-rendering with minimal DOM updates
+Register multiple components with parallel fetching:
 
-## API Reference
+```javascript
+const result = await registerComponents([
+  { name: "app-header", path: "./header.html" },
+  { name: "app-footer", path: "./footer.html", lazy: lazyOnVisible() },
+  { name: "user-card", path: "./user-card.html", useShadowDOM: false },
+]);
 
-### Component Methods
+// Returns: { success: [...], failed: [...], skipped: [...] }
+```
 
-| Method              | Description                                                               |
-| ------------------- | ------------------------------------------------------------------------- |
-| `setState(partial)` | Update component state and trigger re-render (merges with existing state) |
+### `$use`
 
-### Framework Utilities (v2.0)
+Infer the component tag name from the file path:
 
-Available within component `<script>` tags:
+```javascript
+await $use("./components/user-card.html"); // Registers as <user-card>
+```
 
-| Utility                        | Description                                                          |
-| ------------------------------ | -------------------------------------------------------------------- |
-| `$state`                       | Direct access to component state object                              |
-| `$setState(updates)`           | Update state explicitly (alternative to direct assignments)          |
-| `$emit(eventName, data?)`      | Emit event to other components via global event bus                  |
-| `$listen(eventName, callback)` | Listen for events from other components (auto-cleanup on disconnect) |
-| `$querySelector(selector)`     | Query element within component's DOM (respects Shadow DOM)           |
-| `$querySelectorAll(selector)`  | Query all matching elements within component                         |
+### `loadLazyComponent`
 
-### Component Attributes
+Force a lazy component to load immediately from JavaScript:
 
-| Attribute                   | Description                                                                         |
-| --------------------------- | ----------------------------------------------------------------------------------- |
-| `$bind="variableName"`      | Create two-way data binding with form inputs                                        |
-| `data-if="expression"`      | Conditionally render element if expression is truthy                                |
-| `data-else-if="expression"` | Chain multiple conditional expressions                                              |
-| `data-else`                 | Render when all previous conditions are false                                       |
-| `onclick="handler"` (etc.)  | Attach event handlers (supports method names, inline functions, or arrow functions) |
+```javascript
+import { loadLazyComponent } from "ladrillosjs";
 
-### Registration Functions
+await loadLazyComponent("my-lazy-footer");
+```
 
-| Function                                       | Description                                            |
-| ---------------------------------------------- | ------------------------------------------------------ |
-| `registerComponent(name, path, useShadowDOM?)` | Register a single component (returns Promise)          |
-| `registerComponents(components)`               | **Coming soon** - Register multiple components at once |
+### `configure`
 
-## Examples
+Configure framework-level options (optional):
 
-### Component Communication
+```javascript
+import { configure } from "ladrillosjs";
 
-**v2.0 uses the global event bus instead of custom events:**
+configure({
+  cacheSize: 50, // Component LRU cache size (default: 25)
+  onError: (err) => telemetry.capture(err), // Custom error handler
+});
+```
 
-```html
-<!-- parent.html -->
-<div>
-  <h2>Parent Component</h2>
-  <p>Messages received: {messageCount}</p>
-  <child-component></child-component>
-</div>
+### Event Bus
 
-<script>
-  let messageCount = 0;
+| Function                   | Description                         |
+| -------------------------- | ----------------------------------- |
+| `$emit(event, data)`       | Broadcast an event to all listeners |
+| `$listen(event, callback)` | Subscribe to an event               |
 
-  // Listen for events from child
-  $listen("child-message", (data) => {
-    console.log("Received from child:", data);
-    messageCount++;
-  });
-</script>
-```
+---
 
-```html
-<!-- child.html -->
-<div>
-  <h3>Child Component</h3>
-  <button onclick="sendMessage">Send Message to Parent</button>
-</div>
+## 🛠️ Using with Vite
 
-<script>
-  let count = 0;
+LadrillosJS works seamlessly with Vite for production builds:
 
-  const sendMessage = () => {
-    count++;
-    // Emit event that parent (or any component) can listen to
-    $emit("child-message", {
-      message: `Hello from child! (${count})`,
-      timestamp: Date.now(),
-    });
-  };
-</script>
+```bash
+npm install ladrillosjs vite
 ```
 
-### Dynamic Component Creation
-
 ```javascript
-// Create components programmatically
-const createCard = (userData) => {
-  const card = document.createElement("user-card");
-  card.setAttribute("user-id", userData.id);
-  card.setAttribute("name", userData.name);
-  card.setAttribute("email", userData.email);
-  document.querySelector("#user-list").appendChild(card);
-};
-
-// Fetch and create multiple components
-fetch("/api/users")
-  .then((res) => res.json())
-  .then((users) => users.forEach(createCard));
-```
+// vite.config.js
+import { defineConfig } from "vite";
 
-### Passing Complex Data
+export default defineConfig({
+  // LadrillosJS components work out of the box!
+});
+```
 
-Use JSON.stringify for passing objects/arrays as attributes:
+```javascript
+// main.js
+import { registerComponent } from "ladrillosjs";
 
-```html
-<!-- In parent component -->
-<script>
-  const user = { id: 1, name: "John", roles: ["admin", "user"] };
-  const items = [1, 2, 3, 4, 5];
-
-  // Create HTML with stringified data
-  const cardHtml = `
-    <user-card data-user='${JSON.stringify(user)}'></user-card>
-    <list-component data-items='${JSON.stringify(items)}'></list-component>
-  `;
-
-  // Or use the built-in stringify helper in v2.0
-  const cardHtml2 = `
-    <user-card data-user="${this.stringify(user)}"></user-card>
-  `;
-</script>
+registerComponent("my-counter", "./components/counter.html", false);
 ```
 
-```html
-<!-- In child component (user-card.html) -->
-<div>
-  <h3>{user.name}</h3>
-  <p>ID: {user.id}</p>
-  <p>Roles: {user.roles.join(", ")}</p>
-</div>
+See the [samples/](samples/) directory for complete examples:
 
-<script>
-  // data-user is automatically parsed from JSON
-  let user = this.state["data-user"];
-</script>
-```
+- `samples/vite-sample/` — Basic Vite setup
+- `samples/vite-basic-site/` — Multi-component site
+- `samples/ladrillos-demo/` — Full feature showcase
 
-## Migration Guide (v1.x to v2.0)
+---
 
-### Breaking Changes
+## 📚 Examples
 
-1. **Global State Stores Removed**
+### Todo List
 
-   - **Before:** `createStore()` API
-   - **After:** Use global event bus with `$emit` and `$listen`
+A complete CRUD example combining all directives:
 
-2. **Component Registration**
+```html
+<div class="todo-app">
+  <form onsubmit="addTodo(event)">
+    <input type="text" $bind="newTodo" placeholder="What needs to be done?" />
+    <button type="submit">Add</button>
+  </form>
+
+  <ul>
+    <for each="todo in todos" key="todo.id">
+      <li>
+        <input type="checkbox" onclick="toggleTodo({todo.id})" />
+        <span class="{todo.completed ? 'done' : ''}">{todo.text}</span>
+        <button onclick="removeTodo({todo.id})">🗑️</button>
+      </li>
+    </for>
+  </ul>
+
+  <if condition="todos.length === 0"><p>No todos yet!</p></if>
+</div>
 
-   - **Before:** `registerComponent()` was synchronous
-   - **After:** Returns a Promise, use `await` or `.then()`
+<script>
+  let todos = [
+    { id: 1, text: "Learn LadrillosJS", completed: false },
+    { id: 2, text: "Build something awesome", completed: false },
+  ];
+  let newTodo = "";
+  let nextId = 3;
+
+  function addTodo(event) {
+    event.preventDefault();
+    if (newTodo.trim()) {
+      todos = [...todos, { id: nextId++, text: newTodo, completed: false }];
+      newTodo = "";
+    }
+  }
 
-3. **Framework Utilities**
+  function toggleTodo(id) {
+    todos = todos.map((t) =>
+      t.id === id ? { ...t, completed: !t.completed } : t,
+    );
+  }
 
-   - **Before:** `this.emit()`, `this.listen()`, `this.setState()`
-   - **After:** Use `$emit()`, `$listen()`, `$setState()` in scripts (legacy methods still available for compatibility)
+  function removeTodo(id) {
+    todos = todos.filter((t) => t.id !== id);
+  }
+</script>
+```
 
-4. **Two-Way Binding**
-   - **Before:** No built-in support (manual implementation)
-   - **After:** Use `$bind` attribute for automatic two-way binding
+> 💡 Check the [samples/](samples/) folder for more examples including lazy loading, event bus communication, and real-world patterns.
 
-### New Features to Adopt
+---
 
-- ✅ Use `$bind` for two-way data binding instead of manual input handling
-- ✅ Replace store subscriptions with `$emit`/`$listen` event patterns
-- ✅ Direct variable assignments now trigger reactivity (`count++`)
-- ✅ Use `$state` for direct state access in scripts
-- ✅ Leverage conditional directives: `data-if`, `data-else-if`, `data-else`
+## 🤝 Contributing
 
-## Contributing
+Contributions are welcome! Here's how you can help:
 
-Contributions are welcome! Please feel free to submit a Pull Request.
+1. **Fork** the repository
+2. **Create** a feature branch: `git checkout -b feature/amazing-feature`
+3. **Commit** your changes: `git commit -m 'Add amazing feature'`
+4. **Push** to the branch: `git push origin feature/amazing-feature`
+5. **Open** a Pull Request
 
-### Development
+### Development Setup
 
 ```bash
-# Install dependencies
+git clone https://github.com/drubiodev/LadrillosJS.git
+cd LadrillosJS
 npm install
-
-# Run development server with hot reload
-npm run dev
-
-# Run tests
-npm test
-
-# Run tests with coverage
-npm run test:coverage
-
-# Build the library
-npm run build
-
-# Build TypeScript types
-npm run build:types
+npm run dev        # Watch mode for development
+npm run build      # Build for production
 ```
 
-### Project Structure
-
-```
-src/
-├── index.ts              # Main entry point
-├── core/
-│   ├── main.ts          # Core Ladrillos class
-│   ├── webcomponent.ts  # Web component definition
-│   ├── componentParser.ts  # Component file parser
-│   ├── componentSource.ts  # Component fetching with cache
-│   ├── eventBus.ts      # Global event bus
-│   ├── css/
-│   │   └── cssParser.ts
-│   ├── html/
-│   │   ├── htmlparser.ts
-│   │   └── htmlRenderer.ts
-│   └── js/
-│       └── scriptParser.ts
-├── cache/
-│   ├── index.ts         # LRU cache for components
-│   └── functionCache.ts # LRU cache for compiled functions
-├── types/
-│   └── LadrilloTypes.ts # TypeScript type definitions
-└── utils/
-    ├── logger.ts        # Logging utilities
-    └── regex.ts         # Regex patterns
-```
+---
 
-## License
+## 📄 License
 
-MIT License - see [LICENSE](LICENSE) file for details.
+MIT License — see [LICENSE](LICENSE) for details.
 
 ---
 
-**LadrillosJS v2.0** - Built with ❤️ by [Daniel Rubio](https://github.com/drubiodev)
+<p align="center">
+  <strong>Built with ❤️ by <a href="https://github.com/drubiodev">Daniel Rubio</a></strong>
+</p>
 
-Rewritten in TypeScript for better performance, developer experience, and maintainability.
+<p align="center">
+  <a href="https://github.com/drubiodev/LadrillosJS">GitHub</a> •
+  <a href="https://www.npmjs.com/package/ladrillosjs">NPM</a> •
+  <a href="https://github.com/drubiodev/LadrillosJS/issues">Issues</a>
+</p>