ladrillosjs 2.0.0-beta.4.4 → 2.0.0-beta.5.1

package/README.md

@@ -1,1902 +1,584 @@
 # LadrillosJS
 
-<img src="https://raw.githubusercontent.com/drubiodev/LadrillosJS/refs/heads/main/LadrillosJS.jpg" alt="LadrillosJS" width="400"/>
-
-A lightweight, zero-dependency web component framework for building modular web applications.
-
-**Version 2.0** - Rewritten in TypeScript with enhanced performance, improved developer experience, and powerful new features.
-
-> "Empower developers to componentize code efficiently without the complexity of a full-scale framework. Focus on simplicity while leveraging core web fundamentals."
-
-## Table of Contents
-
-- [Features](#features)
-- [Installation](#installation)
-- [Using with Vite](#using-with-vite)
-- [Quick Start](#quick-start)
-- [Core Concepts](#core-concepts)
-  - [Component Registration](#component-registration)
-  - [State Management](#state-management)
-  - [Event Handling](#event-handling)
-  - [Data Binding](#data-binding)
-  - [Conditional Rendering](#conditional-rendering)
-  - [List Rendering](#list-rendering)
-  - [Slots](#slots)
-  - [Component Props](#component-props)
-  - [Lifecycle Hooks](#lifecycle-hooks)
-- [Advanced Features](#advanced-features)
-  - [Lazy Loading](#lazy-loading)
-  - [Global Event Bus](#global-event-bus)
-  - [External Scripts](#external-scripts)
-  - [Shadow DOM](#shadow-dom)
-  - [Styling Components](#styling-components)
-  - [Performance & Caching](#performance--caching)
-- [Common Patterns](#common-patterns)
-  - [Keyboard Events](#keyboard-events)
-  - [Form Validation](#form-validation)
-  - [Loading States](#loading-states)
-- [API Reference](#api-reference)
-- [Development](#development)
-- [Attribution](#attribution)
-- [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
-- 🎯 **Event System** - Global event bus for component communication
-- 🔄 **Two-Way Data Binding** - Seamless form input binding with `$bind`
-- 🎨 **Scoped Styles** - Component styles with optional Shadow DOM
-- 🔌 **Slots** - Content projection with named and default slots
-- 📝 **TypeScript** - Full type definitions and TypeScript source code
-- 🎭 **Conditional Rendering** - `$if`, `$else-if`, and `$else` directives
-- 🔁 **List Rendering** - `$for` directive for rendering arrays
-- ⚡ **Lazy Loading** - Load components on-demand with Intersection Observer
-- 🚄 **Smart Caching** - LRU cache for components and compiled functions
-- 🔧 **Framework Utilities** - Helper functions for common tasks
-- 🧩 **External Scripts** - Load and bind external JavaScript modules
-
-## Installation
-
-### NPM
+<p align="center">
+  <img src="https://raw.githubusercontent.com/drubiodev/LadrillosJS/refs/heads/main/LadrillosJS.jpg" alt="LadrillosJS" width="300"/>
+</p>
 
-```bash
-npm install ladrillosjs
-```
-
-### CDN
-
-```html
-<!-- ES Module (Recommended) -->
-<script type="module">
-  import { registerComponent } from "https://cdn.jsdelivr.net/npm/ladrillosjs/dist/ladrillosjs.es.js";
-  registerComponent("my-component", "./my-component.html");
-</script>
-
-<!-- UMD (Browser Global) -->
-<script src="https://cdn.jsdelivr.net/npm/ladrillosjs/dist/ladrillosjs.umd.js"></script>
-<script>
-  ladrillosjs.registerComponent("my-component", "./my-component.html");
-</script>
-```
-
-## Using with Vite
-
-LadrillosJS includes a Vite plugin to automatically copy your component files to the distribution folder during build. This is useful when you have static component files that need to be served with your application.
-
-### Installation
-
-If you haven't already:
-
-```bash
-npm install --save-dev vite
-npm install ladrillosjs
-```
-
-### Setup
-
-Create or update your `vite.config.js`:
-
-```javascript
-import { defineConfig } from "vite";
-import { copyComponentsPlugin } from "ladrillosjs/vite";
-
-export default defineConfig({
-  plugins: [
-    copyComponentsPlugin({
-      src: "components", // Source directory with your components
-      dest: "components", // Destination in dist/ folder
-      copyOnDev: false, // Only copy during build (not dev server)
-    }),
-  ],
-});
-```
-
-### Basic Usage
-
-```javascript
-// vite.config.js with default settings
-import { defineConfig } from "vite";
-import { copyComponentsPlugin } from "ladrillosjs/vite";
-
-export default defineConfig({
-  plugins: [copyComponentsPlugin()],
-});
-```
-
-The plugin will:
-
-- 📁 Copy your `components/` folder to `dist/components/` during build
-- 🛡️ Handle errors gracefully with helpful logging
-- ⚙️ Use sensible defaults (src: 'components', dest: 'components')
-
-### Plugin Options
-
-```typescript
-interface CopyComponentsOptions {
-  /** Source directory containing components (default: 'components') */
-  src?: string;
-
-  /** Destination directory in dist/ (default: 'components') */
-  dest?: string;
-
-  /** Copy during development server (default: false) */
-  copyOnDev?: boolean;
-
-  /** Process component module scripts (default: true) */
-  processScripts?: boolean;
-}
-```
-
-### Processing Component Module Scripts
-
-When `processScripts` is enabled (default), the plugin automatically transforms component scripts using `type="module"` to work with the window scope. This is essential when building with Vite and using ES modules in your components.
-
-**What It Does:**
-
-- Converts ES module imports to window references
-- Wraps scripts in an async IIFE that waits for the library to load
-- Handles multiple components efficiently with a shared loading promise
-
-**Example:**
-
-Before build (in your component):
-
-```html
-<script type="module">
-  import { registerComponent } from "ladrillosjs";
-
-  let count = 0;
-
-  export const increment = () => {
-    count++;
-  };
-</script>
-```
-
-After build (automatically transformed):
-
-```html
-<script>
-  (async () => {
-    try {
-      if (!window.__ladrillosPromise__) {
-        window.__ladrillosPromise__ = new Promise((resolve) => {
-          // Wait for LadrillosJS to load...
-        });
-      }
-
-      await window.__ladrillosPromise__;
-
-      (async () => {
-        const { registerComponent } = window.ladrillosjs;
-
-        let count = 0;
-
-        // Component code...
-      })();
-    } catch (error) {
-      console.error("Failed to execute component module:", error);
-    }
-  })();
-</script>
-```
-
-**Disable Processing (if needed):**
-
-```javascript
-import { defineConfig } from "vite";
-import { copyComponentsPlugin } from "ladrillosjs/vite";
-
-export default defineConfig({
-  plugins: [
-    copyComponentsPlugin({
-      src: "components",
-      dest: "components",
-      processScripts: false, // Disable script processing
-    }),
-  ],
-});
-```
-
-### Complete Example
-
-Project structure:
-
-```
-my-app/
-├── components/
-│   ├── header.html
-│   ├── footer.html
-│   └── card.html
-├── src/
-│   └── main.js
-├── index.html
-└── vite.config.js
-```
-
-Configuration:
-
-```javascript
-import { defineConfig } from "vite";
-import { copyComponentsPlugin } from "ladrillosjs/vite";
-
-export default defineConfig({
-  plugins: [
-    copyComponentsPlugin({
-      src: "components",
-      dest: "components",
-    }),
-  ],
-});
-```
-
-Usage in your app:
-
-```javascript
-// src/main.js
-import { registerComponents } from "ladrillosjs";
-
-await registerComponents([
-  { name: "app-header", path: "./components/header.html" },
-  { name: "app-footer", path: "./components/footer.html" },
-  { name: "app-card", path: "./components/card.html" },
-]);
-```
-
-After running `npm run build`, your components will be copied to `dist/components/` and be ready for production deployment.
-
-### Development Workflow
-
-```bash
-# Start dev server (components served from source)
-npm run dev
-
-# Build for production (components copied to dist)
-npm run build
-
-# Preview production build
-npm run preview
-```
-
-## Quick Start
-
-### 1. Create Your First Component
-
-Create a file called `hello-world.html`:
-
-```html
-<!-- hello-world.html -->
-<div class="greeting">
-  <h1>{title}</h1>
-  <p>Hello, {name}!</p>
-  <button onclick="greet()">Greet ({count})</button>
-</div>
-
-<script>
-  // Component state - automatically reactive
-  let title = "Welcome to LadrillosJS";
-  let name = "World";
-  let count = 0;
-
-  // Event handler
-  const greet = () => {
-    count++; // Automatically triggers re-render
-    name = prompt("What's your name?") || "World";
-  };
-</script>
-
-<style>
-  .greeting {
-    text-align: center;
-    padding: 2rem;
-    background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
-    color: white;
-    border-radius: 8px;
-  }
-
-  button {
-    padding: 0.75rem 1.5rem;
-    font-size: 1rem;
-    background: white;
-    color: #667eea;
-    border: none;
-    border-radius: 4px;
-    cursor: pointer;
-    transition: transform 0.2s;
-  }
-
-  button:hover {
-    transform: scale(1.05);
-  }
-</style>
-```
-
-### 2. Register and Use the Component
-
-```html
-<!DOCTYPE html>
-<html lang="en">
-  <head>
-    <meta charset="UTF-8" />
-    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-    <title>My LadrillosJS App</title>
-  </head>
-  <body>
-    <!-- Use your component -->
-    <hello-world></hello-world>
-
-    <!-- Register the component -->
-    <script type="module">
-      import { registerComponent } from "ladrillosjs";
-      registerComponent("hello-world", "./hello-world.html");
-    </script>
-  </body>
-</html>
-```
-
-### 3. Explore Example Apps
-
-Check out the `samples/apps/` directory for complete examples:
-
-- **[Todo App](samples/apps/todo)** - Classic todo list with component composition
-- **[Notes App](samples/apps/notes)** - Multi-component app with event bus
-- **[Simple Button](samples/apps/simple-button)** - Basic interactive component
-- **[Business Card](samples/apps/biz)** - Form with two-way data binding
-- **[Slideshow](samples/apps/slideshow)** - Multi-slide presentation
-- **[Markdown Editor](samples/apps/markdown)** - Real-time markdown preview
-- **[List Rendering](samples/apps/list-test)** - Dynamic lists with `$for` directive
-
-Run the development server to view examples:
-
-```bash
-npm install
-npm run dev
-```
-
-## Core Concepts
-
-### Component Registration
-
-Register components to make them available as custom HTML elements:
-
-```javascript
-import { registerComponent, registerComponents } from "ladrillosjs";
-
-// Register a single component
-await registerComponent("my-button", "./components/my-button.html");
-
-// Register 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" },
-]);
-
-// Disable Shadow DOM for a component
-await registerComponent("global-styles", "./components/global.html", false);
-
-// Enable lazy loading for a component
-await registerComponent(
-  "footer-section",
-  "./components/footer.html",
-  true,
-  true
-);
-
-// Register multiple components with lazy loading
-await registerComponents([
-  { name: "hero-section", path: "./components/hero.html" },
-  { name: "feature-section", path: "./components/features.html", lazy: true },
-  { name: "footer-section", path: "./components/footer.html", lazy: true },
-]);
-```
-
-### State Management
-
-Components have reactive state that automatically triggers re-renders when changed:
-
-```html
-<div>
-  <h2>Counter: {count}</h2>
-  <p>User: {user.name}</p>
-  <button onclick="increment()">Add</button>
-  <button onclick="updateUser()">Change User</button>
-  <button onclick="reset()">Reset</button>
-</div>
-
-<script>
-  // State variables - automatically reactive
-  let count = 0;
-  let user = { name: "John", age: 25 };
-
-  const increment = () => {
-    count++; // Automatically triggers re-render
-  };
-
-  const updateUser = () => {
-    user.name = "Jane"; // Direct mutation triggers re-render
-  };
-
-  // You can also use $setState for explicit updates
-  const reset = () => {
-    $setState({ count: 0, user: { name: "Anonymous", age: 0 } });
-  };
-</script>
-```
-
-**Available State Utilities:**
-
-- Direct assignment: `count++`, `name = "New"`
-- `$setState(updates)`: Merge updates into state
-- `$getState()`: Access state in external modules
-
-### Event Handling
-
-Attach event handlers directly to elements:
-
-```html
-<!-- Method reference -->
-<button onclick="handleClick(event)">Click me</button>
-
-<!-- Function with arguments -->
-<button onclick="addItem('apple', 5)">Add Item</button>
-
-<!-- Inline arrow function -->
-<button onclick="console.log(event.target)">Log Event</button>
-
-<!-- Multiple events -->
-<label $if="isValid">Valid</label>
-<input
-  type="text"
-  placeholder="Enter text (min 3 characters)"
-  onkeyup="validateInput(event)"
-  onfocus="highlightField(event)"
-  onblur="saveField(event)"
-/>
-
-<script>
-  let items = [];
-  let isValid = false;
-
-  const handleClick = (event) => {
-    console.log("Button clicked!", event);
-  };
-
-  const addItem = (name, quantity) => {
-    items = [...items, { name, quantity }];
-    console.log("Items:", items);
-  };
-
-  const validateInput = (e) => {
-    const value = e.target.value;
-    isValid = value.length >= 3;
-  };
-
-  const highlightField = (e) => {
-    e.target.style.backgroundColor = "lightyellow";
-  };
-
-  const saveField = (e) => {
-    e.target.style.backgroundColor = "";
-    console.log("Field saved:", e.target.value);
-  };
-</script>
-```
-
-### Data Binding
-
-#### One-Way Binding (Display Data)
-
-Use curly braces `{}` to display state in your template:
-
-```html
-<div>
-  <h1>{title}</h1>
-  <p>{user.name} - {user.email}</p>
-  <span>Total: {items.length} items</span>
-  <p>Formatted: {formatPrice(price)}</p>
-</div>
-
-<script>
-  let title = "My App";
-  let user = { name: "John", email: "john@example.com" };
-  let items = ["apple", "banana", "orange"];
-  let price = 29.99;
-
-  const formatPrice = (value) => `$${value.toFixed(2)}`;
-</script>
-```
-
-#### Two-Way Binding (Form Inputs)
-
-Use the `$bind` attribute for automatic synchronization between inputs and state:
-
-```html
-<div>
-  <h2>Hello, {name}!</h2>
-  <input type="text" $bind="name" placeholder="Your name" />
-
-  <p>Email: {email}</p>
-  <input type="email" $bind="email" />
-
-  <p>Bio: {bio}</p>
-  <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>
-
-  <label>
-    <input type="checkbox" $bind="subscribe" />
-    Subscribe to newsletter: {subscribe}
-  </label>
-</div>
-
-<script>
-  // Variables are automatically synced with inputs
-  let name = "World";
-  let email = "";
-  let bio = "";
-  let country = "us";
-  let subscribe = false;
-</script>
-```
-
-### Conditional Rendering
-
-Show or hide elements based on conditions:
-
-```html
-<div>
-  <h1>Shopping Cart</h1>
-
-  <!-- Simple condition -->
-  <p $if="{items.length === 0}">Your cart is empty</p>
-
-  <!-- Multiple conditions -->
-  <div $if="{items.length > 0 && items.length < 5}">
-    <p>You have {items.length} items</p>
-  </div>
-
-  <div $else-if="{items.length >= 5}">
-    <p>Your cart is full! ({items.length} items)</p>
-  </div>
-
-  <!-- Login/Logout example -->
-  <button $if="{!isLoggedIn}" onclick="login()">Login</button>
-  <button $else onclick="logout()">Logout</button>
-
-  <!-- Complex conditions -->
-  <div $if="{user && user.role.toLowerCase() === 'admin'}">
-    <p>{user.role} Panel</p>
-    Hello {user.name}
-    <button onclick="addToCart()">🛒 Add To Cart</button>
-  </div>
-</div>
-
-<script>
-  let items = [];
-  let isLoggedIn = false;
-  let user = null;
-
-  const login = () => {
-    isLoggedIn = true;
-    user = { name: "John", role: "Admin" };
-  };
-
-  const logout = () => {
-    isLoggedIn = false;
-    user = null;
-  };
-
-  const addToCart = () => {
-    if (items.length < 5) {
-      items.push(`Item ${items.length + 1}`);
-    } else {
-      alert("Cart is full!");
-    }
-  };
-</script>
-```
-
-**Conditional Directives:**
-
-- `$if="{expression}"`: Show if expression is truthy
-- `$else-if="{expression}"`: Chain multiple conditions
-- `$else`: Fallback when previous conditions are false
-
-### List Rendering
-
-Render lists of items using the `$for` directive:
-
-```html
-<div>
-  <h2>My Fruits</h2>
-  <ul>
-    <li $for="fruit in fruits">{fruit}</li>
-  </ul>
-  <button onclick="addFruit()">Add Fruit</button>
-</div>
-
-<script>
-  let fruits = ["Apple", "Banana", "Orange"];
-
-  const addFruit = () => {
-    const newFruit = prompt("Enter a fruit name:");
-    if (newFruit) {
-      fruits = [...fruits, newFruit]; // Triggers re-render
-    }
-  };
-</script>
-```
-
-**List Rendering with Objects:**
-
-```html
-<div>
-  <h2>User List</h2>
-  <div class="user-card" $for="user in users">
-    <h3>{user.name}</h3>
-    <p>Email: {user.email}</p>
-  </div>
-</div>
-
-<script>
-  let users = [
-    { name: "John Doe", email: "john@example.com" },
-    { name: "Jane Smith", email: "jane@example.com" },
-  ];
-</script>
-```
-
-**With Index:**
-
-```html
-<ul>
-  <li $for="(item, index) in items">{index + 1}. {item}</li>
-</ul>
-
-<script>
-  let items = ["First", "Second", "Third"];
-</script>
-```
-
-**Performance Optimization with `$key`:**
-
-Use the `$key` attribute to help LadrillosJS track items efficiently:
-
-```html
-<div>
-  <div class="user-card" $for="user in users" $key="user.id">
-    <h3>{user.name}</h3>
-    <p>Email: {user.email}</p>
-    <button onclick="removeUser(user.id)">Remove</button>
-  </div>
-</div>
-
-<script>
-  let users = [
-    { id: 1, name: "John", email: "john@example.com" },
-    { id: 2, name: "Jane", email: "jane@example.com" },
-  ];
-
-  const removeUser = (id) => {
-    users = users.filter((u) => u.id !== id);
-  };
-</script>
-```
-
-### Slots
-
-Project content from parent to child components:
-
-```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>
-  </div>
-</div>
-
-<style>
-  .card {
-    border: 1px solid #ddd;
-    border-radius: 8px;
-    padding: 1rem;
-  }
-  .card-header {
-    font-weight: bold;
-    margin-bottom: 1rem;
-  }
-  .card-footer {
-    margin-top: 1rem;
-    border-top: 1px solid #eee;
-    padding-top: 1rem;
-  }
-</style>
-```
-
-**Usage:**
-
-```html
-<my-card>
-  <h2 slot="header">User Profile</h2>
-  <p>Name: John Doe</p>
-  <p>Email: john@example.com</p>
-  <button slot="footer">Save Changes</button>
-</my-card>
-```
-
-### Component Props
-
-Pass data to components using HTML attributes:
-
-```html
-<!-- greeting.html -->
-<div>
-  <h1>Hello, {name}!</h1>
-  <p>Age: {age}</p>
-</div>
-
-<script>
-  // Access attributes passed to the component
-  let name = this.getAttribute("name") || "Guest";
-  let age = this.getAttribute("age") || "unknown";
-</script>
-```
-
-**Usage:**
-
-```html
-<my-greeting name="John" age="25"></my-greeting>
-<my-greeting name="Jane" age="30"></my-greeting>
-```
-
-### Lifecycle Hooks
-
-LadrillosJS provides Vue.js-style lifecycle hooks so you can run code at specific times in a component's lifecycle. These hooks are tied directly to Web Component lifecycle methods for maximum control.
-
-#### Available Hooks
-
-| Hook         | Called                                           | Purpose                            |
-| ------------ | ------------------------------------------------ | ---------------------------------- |
-| `$onMount`   | After component is mounted and fully initialized | Setup, initialization, API calls   |
-| `$onUpdate`  | After component state changes and re-renders     | React to state changes             |
-| `$onUnmount` | Before component is removed from DOM             | Cleanup, unsubscribe, clear timers |
-
-#### `$onMount(callback)`
-
-Called once when the component is fully mounted and ready. Perfect for initialization, API calls, and setup logic.
-
-```html
-<div>
-  <h2>User Profile</h2>
-  <p $if="{loading}">Loading...</p>
-  <div $else>
-    <h3>{user.name}</h3>
-    <p>{user.email}</p>
-  </div>
-</div>
-
-<script>
-  let user = { name: "", email: "" };
-  let loading = true;
-
-  // Called after component mounts with state ready
-  $onMount(() => {
-    console.log("✅ Component mounted!");
-
-    // Perfect for API calls, initialization, etc
-    fetch("/api/user/123")
-      .then((res) => res.json())
-      .then((data) => {
-        user = data;
-        loading = false;
-      });
-  });
-</script>
-```
-
-**When to use `$onMount`:**
-
-- ✅ Fetch data from APIs
-- ✅ Initialize timers or subscriptions
-- ✅ Set up event listeners
-- ✅ Run component setup logic
-- ✅ Validate initial state
-
-#### `$onUpdate(callback)`
-
-Called after component state changes and the component re-renders. Perfect for reacting to state changes.
-
-```html
-<div>
-  <p>Count: {count}</p>
-  <button onclick="count++">Increment</button>
-</div>
-
-<script>
-  let count = 0;
-
-  $onUpdate(() => {
-    console.log("🔄 Component updated! New count:", count);
-
-    // React to state changes
-    if (count === 10) {
-      console.log("Count reached 10!");
-    }
-  });
-</script>
-```
-
-**When to use `$onUpdate`:**
-
-- ✅ Log state changes for debugging
-- ✅ Trigger side effects when specific properties change
-- ✅ Sync with external systems
-- ✅ Perform validations on updated state
-
-#### `$onUnmount(callback)`
-
-Called before the component is removed from the DOM. Perfect for cleanup operations.
-
-```html
-<div>
-  <p>Timer: {seconds}</p>
-</div>
-
-<script>
-  let seconds = 0;
-  let interval = null;
-
-  $onMount(() => {
-    // Start timer
-    interval = setInterval(() => {
-      seconds++;
-    }, 1000);
-  });
-
-  $onUnmount(() => {
-    console.log("❌ Component unmounting, cleaning up...");
-
-    // Clear timer to prevent memory leaks
-    if (interval) {
-      clearInterval(interval);
-    }
-  });
-</script>
-```
-
-**When to use `$onUnmount`:**
-
-- ✅ Clear timers and intervals
-- ✅ Remove event listeners
-- ✅ Unsubscribe from observables
-- ✅ Cleanup resources
-- ✅ Cancel pending API requests
-
-#### Complete Lifecycle Example
-
-```html
-<div>
-  <h3>Lifecycle Demo</h3>
-  <p>Status: {status}</p>
-  <button onclick="status = 'active'">Activate</button>
-  <button onclick="status = 'inactive'">Deactivate</button>
-</div>
-
-<script>
-  let status = "initializing";
-
-  $onMount(() => {
-    console.log("✅ $onMount - Component ready to go!");
-    status = "ready";
-  });
-
-  $onUpdate(() => {
-    console.log("🔄 $onUpdate - Status changed to:", status);
-  });
-
-  $onUnmount(() => {
-    console.log("❌ $onUnmount - Cleaning up before removal");
-  });
-</script>
-```
-
-#### Lifecycle Timing Diagram
-
-```
-┌─────────────────────────────────────────────────────────┐
-│  Element added to DOM                                   │
-│  ↓                                                      │
-│  connectedCallback() starts                             │
-│  ├─ Parse template                                      │
-│  ├─ Load styles                                         │
-│  ├─ Execute scripts & initialize state                  │
-│  ├─ Render bindings, conditionals, loops                │
-│  │                                                      │
-│  ├─→ $onMount() called ← Component ready!               │
-│  │                                                      │
-│  State changes (click, setState, etc)                   │
-│  ├─ Proxy detects change                                │
-│  ├─ Schedule update (requestAnimationFrame)             │
-│  ├─ Re-render bindings, conditionals, loops             │
-│  │                                                      │
-│  ├─→ $onUpdate() called ← After each update             │
-│  │   ... (can happen many times)                        │
-│  │                                                      │
-│  Element removed from DOM                               │
-│  ├─→ $onUnmount() called ← Before cleanup               │
-│  │                                                      │
-│  disconnectedCallback() cleanup                         │
-│  ├─ Remove event listeners                              │
-│  ├─ Clear subscriptions                                 │
-│  └─ Complete                                            │
-└─────────────────────────────────────────────────────────┘
-```
-
-## Advanced Features
-
-### Lazy Loading
-
-LadrillosJS supports lazy loading components using the Intersection Observer API. Components are loaded only when they enter or are about to enter the viewport, improving initial page load performance.
-
-#### Basic Usage
-
-```javascript
-import { registerComponents } from "ladrillosjs";
-
-await registerComponents([
-  // Eager loading (default) - loads immediately
-  { name: "hero-section", path: "./components/hero.html" },
-  { name: "navbar", path: "./components/navbar.html" },
-
-  // Lazy loading - loads when scrolled into view
-  { name: "feature-section", path: "./components/features.html", lazy: true },
-  { name: "testimonials", path: "./components/testimonials.html", lazy: true },
-  { name: "footer-section", path: "./components/footer.html", lazy: true },
-]);
-```
-
-```html
-<body>
-  <!-- Loads immediately -->
-  <navbar></navbar>
-  <hero-section></hero-section>
-
-  <!-- Loads when user scrolls near these components -->
-  <feature-section></feature-section>
-  <testimonials></testimonials>
-  <footer-section></footer-section>
-</body>
-```
-
-#### Override Lazy Loading with `eager` Attribute
-
-You can force a lazy component to load immediately using the `eager` attribute:
-
-```html
-<!-- This lazy component loads immediately despite lazy registration -->
-<footer-section eager></footer-section>
-```
-
-#### Best Practices for Lazy Loading
-
-**✅ Good candidates for lazy loading:**
-
-- Below-the-fold content (footers, testimonials)
-- Large components with heavy resources
-- Components that may not be viewed by all users
-- Third-party widgets or embeds
-
-**❌ Avoid lazy loading for:**
-
-- Above-the-fold content (heroes, navigation)
-- Critical interactive elements
-- Small, lightweight components
-- Content needed for SEO
+<p align="center">
+  <strong>A lightweight, zero-dependency web component framework.</strong>
+</p>
 
-**Performance Tips:**
+<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>
 
-1. **Reserve space for lazy components** to prevent layout shift:
+<p align="center">
+  Build modular web apps with simple HTML components. No virtual DOM, no complex tooling required.
+</p>
 
-```css
-/* In your global CSS */
-feature-section,
-testimonials,
-footer-section {
-  display: block;
-  min-height: 400px; /* Approximate height */
-}
-```
-
-2. **Load strategy**: Lazy components load **100px before** entering the viewport for smooth user experience and to account for network latency.
-
-3. **Multiple instances**: If you use the same lazy component multiple times on a page, only one network request is made. All instances share the loaded component definition.
-
-4. **Caching**: Once loaded, lazy components are cached and reused across page navigation.
-
-#### How It Works
-
-- **Placeholder**: Lazy components initially render as minimal placeholders
-- **Intersection Observer**: Monitors when placeholders approach the viewport
-- **Automatic Loading**: Component fetches and upgrades when visible
-- **Seamless Swap**: Placeholder is replaced with the real component
-- **Shared Loading**: Multiple instances coordinate to load only once
-
-### Global Event Bus
-
-The global event bus enables communication between components without prop drilling:
-
-```javascript
-// Emit events to other components
-$emit("user-logged-in", { userId: 123, username: "john" });
-
-// Listen for events from any component
-$listen("user-logged-in", (data) => {
-  console.log(`User ${data.username} logged in`);
-  isLoggedIn = true;
-  currentUser = data;
-});
-```
-
-**Example: Cross-Component Communication**
-
-```html
-<!-- header.html -->
-<header>
-  <span $if="{isLoggedIn}">Welcome, {username}!</span>
-  <button $else onclick="requestLogin()">Login</button>
-</header>
-
-<script>
-  let isLoggedIn = false;
-  let username = "";
-
-  $listen("user-logged-in", (user) => {
-    console.log("User logged in:", user);
-    isLoggedIn = true;
-    username = user.username;
-  });
-
-  const requestLogin = () => {
-    $emit("show-login-dialog");
-  };
-</script>
-```
-
-```html
-<!-- login-form.html -->
-<form onsubmit="handleLogin(event)" $if="{showLoginDialog}">
-  <input type="text" $bind="username" placeholder="Username" />
-  <input type="password" $bind="password" placeholder="Password" />
-  <button type="submit">Login</button>
-</form>
-
-<script>
-  let showLoginDialog = false;
-
-  $listen("show-login-dialog", () => {
-    showLoginDialog = true;
-  });
-
-  const handleLogin = (e) => {
-    e.preventDefault();
-    $emit("user-logged-in", { userId: 123, username });
-    username = "";
-    password = "";
-    showLoginDialog = false;
-  };
-</script>
-```
+---
 
-### External Scripts
+## 📑 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)
 
-LadrillosJS supports three ways to include external JavaScript:
+---
 
-#### 1. ES Modules (Recommended for Complex Logic)
+## 🚀 Quick Start
 
-Use `type="module"` for standard ES modules with automatic state synchronization. Variables declared in modules are automatically initialized in component state and mutations are automatically synced:
+### 1. Add the Script
 
 ```html
-<!-- side-nav.html -->
-<nav>
-  <h1>&lt;Note App/&gt;</h1>
-  <button onclick="createNote()">Create Note</button>
-  <ul></ul>
-</nav>
-
-<!-- Load as ES module - variables and exports are auto-synced to state -->
-<script type="module" src="../js/side.js"></script>
-```
-
-**side.js:**
-
-```javascript
-import { registerComponent, $listen, $querySelector } from "ladrillosjs";
-
-// Declare variables that are used in template bindings
-// They are automatically initialized in component state
-const notes = [];
-
-registerComponent("note-item", "./components/note-item.html");
-
-// Export functions so they're available to event handlers
-export const createNote = () => {
-  const title = prompt("Note title:");
-  if (title) {
-    notes.push({ title, content: "" });
-  }
-};
-
-// Listen to global events
-$listen("note_saved", (data) => {
-  notes.push({ ...data });
-  const ul = $querySelector("ul");
-  if (ul) {
-    ul.innerHTML = notes
-      .map((n) => `<note-item data-note='${JSON.stringify(n)}'></note-item>`)
-      .join("");
-  }
-});
-```
-
-**How Module State Sync Works:**
-
-When a module script is loaded, LadrillosJS:
-
-1. **Detects variables used in template bindings** (e.g., variables in `{}` expressions)
-2. **Initializes them in component state** automatically when declared
-3. **Syncs mutations to state** automatically when assigned
-4. **Auto-attaches exports** to the component so event handlers can access them
-
-This means you write natural JavaScript without boilerplate:
-
-```javascript
-// ✨ This is all you need!
-let count = 0; // Auto-initialized in state
-let user = { name: "" }; // Works with objects too
-
-export const increment = () => {
-  count++; // Auto-synced to state!
-};
-
-export const updateUser = (name) => {
-  user.name = name; // Auto-synced to state!
-};
+<script src="https://cdn.jsdelivr.net/npm/ladrillosjs/dist/ladrillosjs.umd.js"></script>
 ```
 
-**ES Module Benefits:**
+### 2. Create a Component
 
-- ✅ Import external libraries and utilities
-- ✅ Organize code across multiple files
-- ✅ Automatic state initialization for binding variables
-- ✅ Automatic state sync on variable mutations
-- ✅ Clean separation of concerns
-- ✅ Standard JavaScript module syntax
-
-**Example: Counter Component**
+Save this as `counter.html`:
 
 ```html
-<!-- counter.html -->
-<div>
-  <h2>Counter: {count}</h2>
-  <button onclick="increment()">+1</button>
-  <button onclick="decrement()">-1</button>
-  <button onclick="reset()">Reset</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 type="module" src="./counter.js"></script>
+<script>
+  let count = 0;
+</script>
 
 <style>
-  div {
+  .counter {
     text-align: center;
     padding: 2rem;
   }
+  .count-display {
+    font-size: 4rem;
+    font-weight: bold;
+  }
   button {
     padding: 0.5rem 1rem;
-    margin: 0.5rem;
+    margin: 0.25rem;
     cursor: pointer;
   }
 </style>
 ```
 
-**counter.js:**
-
-```javascript
-// Variables used in template are auto-initialized
-let count = 0;
-
-// Exports are auto-attached to component for event handlers
-export const increment = () => {
-  count++;
-};
-
-export const decrement = () => {
-  count--;
-};
-
-export const reset = () => {
-  count = 0;
-};
-```
-
-#### 2. Component-Scoped Scripts
-
-Regular script tags execute within the component's context and have access to component state and utilities:
+### 3. Use It
 
 ```html
-<!-- alert-button.html -->
-<button onclick="increaseCount()">{title}: {count}</button>
-
-<!-- This script runs in the component context -->
-<script src="./alert.js"></script>
+<!DOCTYPE html>
+<html>
+  <head>
+    <script src="https://cdn.jsdelivr.net/npm/ladrillosjs/dist/ladrillosjs.umd.js"></script>
+    <script type="module">
+      ladrillosjs.registerComponent("my-counter", "./counter.html");
+    </script>
+  </head>
+  <body>
+    <my-counter></my-counter>
+  </body>
+</html>
 ```
 
-**alert.js:**
-
-```javascript
-// Variables and functions are available to the component
-let count = 0;
-const title = "Button Count";
+That's it! Your reactive component is ready. 🎉
 
-const increaseCount = () => {
-  count++; // Updates component state
-};
-```
+---
 
-#### 3. External Libraries
+## 📦 Installation
 
-Use the `external` attribute for third-party libraries that shouldn't be bound to component context:
+### CDN (No Build Step)
 
 ```html
-<!-- codeblock.html -->
-<link
-  rel="stylesheet"
-  href="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.9.0/styles/atom-one-dark.min.css"
-/>
-<script
-  src="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.9.0/highlight.min.js"
-  external
-></script>
-
-<div class="code-container">
-  <pre><code id="code" class="language-html"></code></pre>
-</div>
+<!-- Global (UMD) -->
+<script src="https://cdn.jsdelivr.net/npm/ladrillosjs/dist/ladrillosjs.umd.js"></script>
+<script type="module">
+  ladrillosjs.registerComponent("my-component", "./component.html");
+</script>
 
-<script>
-  // Access the external library (hljs is global)
-  const codeElement = $querySelector("pre code");
-  codeElement.textContent = "console.log('Hello')";
-  hljs.highlightElement(codeElement); // Use external library
+<!-- ES Module -->
+<script type="module">
+  import { registerComponent } from "https://cdn.jsdelivr.net/npm/ladrillosjs/dist/ladrillosjs.es.js";
+  registerComponent("my-component", "./component.html");
 </script>
 ```
 
-**When to use `external`:**
-
-- Third-party CDN libraries (highlight.js, Chart.js, etc.)
-- Libraries that need to be loaded globally
-- Scripts that don't need component context or utilities
-
-#### Module Script Best Practices
-
-**✅ Use modules for:**
-
-- Component-specific logic and functions
-- Local state management
-- Importing utilities and helpers
-- Organizing complex components
-
-**❌ Don't use modules for:**
-
-- Simple inline event handlers (use inline scripts)
-- Global libraries (use `external` attribute)
-- Scripts that need global scope
+### NPM (With Build Tools)
 
-**Relative Imports:**
-
-Modules automatically resolve relative imports to their proper URLs:
-
-```javascript
-// These work automatically with modules
-import { helper } from "./utils.js";
-import { Component } from "../components/component.js";
-import { api } from "../../api/client.js";
+```bash
+npm install ladrillosjs
 ```
 
-#### Legacy: Using `$reactive` (Optional)
-
-The `$reactive` function is still available for explicit state initialization in edge cases:
-
 ```javascript
-import { $reactive } from "ladrillosjs";
+import { registerComponent, registerComponents } from "ladrillosjs";
 
-let count = 0;
-const setCount = $reactive("count", count); // Manual initialization
+// Single component
+registerComponent("my-counter", "./components/counter.html");
 
-// Later updates
-setCount(newValue);
+// Multiple components
+await registerComponents([
+  { name: "app-header", path: "./components/header.html" },
+  { name: "app-footer", path: "./components/footer.html" },
+]);
 ```
 
-However, this is **no longer necessary for module scripts** since variables are automatically initialized. Use it only if you need:
+---
 
-- Explicit control over initialization timing
-- Manual setter functions
-- Backward compatibility with older code
+## 📖 Core Concepts
 
-#### Advanced Module Patterns
+### Template Bindings
 
-**Pattern 1: Async Data Loading**
+Use `{expression}` to display reactive data. Any JavaScript expression works:
 
 ```html
-<!-- user-profile.html -->
-<div $if="{loading}">Loading user...</div>
-<div $else-if="{error}">{error}</div>
-<div $else>
-  <h1>{user.name}</h1>
-  <p>Email: {user.email}</p>
-  <p>Bio: {user.bio}</p>
-</div>
-
-<script type="module" src="./user-profile.js"></script>
+<h1>{title}</h1>
+<p>Hello, {user.name}!</p>
+<span>Total: {items.length} items</span>
+<p>Is adult: {age >= 18 ? 'Yes' : 'No'}</p>
 ```
 
-**user-profile.js:**
-
-```javascript
-// Variables auto-initialized in component state
-let user = { name: "", email: "", bio: "" };
-let loading = true;
-let error = null;
-
-// Auto-exported so it's available as event handler
-export const loadUser = async (userId) => {
-  loading = true;
-  error = null;
-
-  try {
-    const response = await fetch(`/api/users/${userId}`);
-    user = await response.json();
-  } catch (e) {
-    error = e.message;
-  } finally {
-    loading = false;
-  }
-};
-
-// Load user on component mount
-loadUser(1);
-```
+### Reactive State
 
-**Pattern 2: Composable Logic**
+Just declare variables with `let` — changes automatically update the DOM:
 
-```javascript
-// utils/counter.js
-export const createCounter = (initial = 0) => {
-  let count = initial;
-
-  return {
-    increment: () => count++,
-    decrement: () => count--,
-    reset: () => (count = initial),
-    get value() {
-      return count;
-    },
-  };
-};
-
-// counter.js (module script)
-import { createCounter } from "./utils/counter.js";
-
-const counter = createCounter(0);
-
-export const increment = () => counter.increment();
-export const decrement = () => counter.decrement();
-export const reset = () => counter.reset();
+```html
+<script>
+  let count = 0;
+  let user = { name: "Alice", role: "Developer" };
+  let items = ["Apple", "Banana", "Cherry"];
+</script>
 ```
 
-**Pattern 3: Shared State Between Components**
-
-```javascript
-// store.js - shared module
-export let globalState = {
-  user: null,
-  notifications: [],
-  theme: "light",
-};
-
-export const updateUser = (user) => {
-  globalState.user = user;
-};
+### Event Handlers
 
-export const addNotification = (msg) => {
-  globalState.notifications.push(msg);
-};
+Attach events directly in HTML with inline expressions or function calls:
 
-// In component module script:
-import { globalState, updateUser } from "./store.js";
-
-let user = globalState.user;
-
-export const switchTheme = () => {
-  globalState.theme = globalState.theme === "light" ? "dark" : "light";
-};
+```html
+<button onclick="count++">Increment</button>
+<button onclick="handleClick()">Click me</button>
+<input onkeyup="search(event.target.value)" />
+<form onsubmit="handleSubmit(event)">...</form>
 ```
 
-**Pattern 4: Event-Driven Updates**
-
-```javascript
-import { $listen, $emit } from "ladrillosjs";
-
-let items = [];
-let selectedId = null;
-
-$listen("item:created", (item) => {
-  items = [...items, item];
-});
+### Two-Way Binding
 
-$listen("item:deleted", (itemId) => {
-  items = items.filter((i) => i.id !== itemId);
-});
-
-export const selectItem = (id) => {
-  selectedId = id;
-  $emit("item:selected", { id, item: items.find((i) => i.id === id) });
-};
-
-export const deleteItem = (id) => {
-  $emit("item:delete-request", { id });
-};
-```
+Use `$bind` to sync form inputs with state:
 
-### Shadow DOM
+```html
+<input type="text" $bind="username" placeholder="Enter name" />
+<p>Hello, {username}!</p>
 
-Components use Shadow DOM by default for style encapsulation:
+<textarea $bind="bio"></textarea>
 
-```javascript
-// Shadow DOM enabled (default)
-await registerComponent("isolated-widget", "./widget.html");
-await registerComponent("isolated-widget", "./widget.html", true);
+<select $bind="country">
+  <option value="us">United States</option>
+  <option value="uk">United Kingdom</option>
+</select>
 
-// Shadow DOM disabled
-await registerComponent("global-styles", "./global.html", false);
+<script>
+  let username = "";
+  let bio = "";
+  let country = "us";
+</script>
 ```
 
-**Shadow DOM Benefits:**
-
-- **Style Isolation**: Component styles don't leak to global scope
-- **Encapsulation**: Internal DOM is hidden from parent
-- **Clean Separation**: Each component has its own styling context
-
-**When to Disable:**
-
-- Need to apply global CSS frameworks (Bootstrap, Tailwind)
-- Using third-party libraries that expect normal DOM
-- Easier debugging without shadow boundaries
+---
 
-### Styling Components
+## 🧩 Directives
 
-LadrillosJS supports multiple ways to style your components:
+### Conditional Rendering
 
-#### 1. Inline Styles (Scoped)
+Use `$if`, `$else-if`, and `$else` to conditionally render elements:
 
 ```html
-<div class="button">{label}</div>
-
-<style>
-  .button {
-    padding: 10px 20px;
-    background: #007bff;
-    color: white;
-  }
-</style>
+<div $if="{status === 'loading'}">Loading...</div>
+<div $else-if="{status === 'error'}">Something went wrong!</div>
+<div $else>Content loaded successfully!</div>
 
 <script>
-  let label = "Click me";
+  let status = "loading";
 </script>
 ```
 
-#### 2. External Stylesheets
+### Show/Hide (CSS Toggle)
 
-```html
-<link rel="stylesheet" href="./styles.css" />
-<div class="container">Content</div>
-```
-
-#### 3. Import Fonts and External CSS
+Use `$show` to toggle visibility without removing from DOM (uses `display: none`):
 
 ```html
-<style>
-  @import url("https://fonts.googleapis.com/css2?family=Roboto:wght@400;700&display=swap");
+<div $show="{isVisible}">I can be shown or hidden</div>
 
-  body {
-    font-family: "Roboto", sans-serif;
-  }
-</style>
+<button onclick="isVisible = !isVisible">Toggle</button>
+
+<script>
+  let isVisible = true;
+</script>
 ```
 
-#### 4. Using `:host` Selector (Shadow DOM)
+> **`$show` vs `$if`:** `$show` toggles CSS display (element stays in DOM), `$if` adds/removes from DOM entirely.
+
+### List Rendering
 
-When using Shadow DOM, style the component's container with `:host`:
+Use `$for` to render lists with optional index and key:
 
 ```html
-<style>
-  :host {
-    display: block;
-    padding: 1rem;
-    background: white;
-  }
+<!-- Simple list -->
+<ul>
+  <li $for="fruit in fruits">🍎 {fruit}</li>
+</ul>
 
-  :host(.highlighted) {
-    border: 2px solid gold;
-  }
-</style>
-```
+<!-- With index -->
+<div $for="(item, index) in items">#{index + 1}: {item}</div>
 
-**Usage:**
+<!-- Object array with key -->
+<div $for="user in users" $key="user.id">
+  <span>{user.avatar}</span>
+  <span>{user.name}</span>
+  <span>{user.role}</span>
+</div>
 
-```html
-<my-component class="highlighted"></my-component>
+<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>
 ```
 
-### Performance & Caching
-
-LadrillosJS includes built-in performance optimizations:
+### Directives Cheat Sheet
 
-#### Component Caching
+| Directive        | Purpose               | Example                                          |
+| ---------------- | --------------------- | ------------------------------------------------ |
+| `$if`            | Conditional render    | `<div $if="{isLoggedIn}">Welcome!</div>`         |
+| `$else-if`       | Chained condition     | `<div $else-if="{isGuest}">Hello Guest</div>`    |
+| `$else`          | Fallback              | `<div $else>Please log in</div>`                 |
+| `$show`          | CSS visibility toggle | `<div $show="{isOpen}">Menu</div>`               |
+| `$for`           | Loop rendering        | `<li $for="item in items">{item}</li>`           |
+| `$for` (indexed) | Loop with index       | `<li $for="(item, i) in items">{i}: {item}</li>` |
+| `$bind`          | Two-way binding       | `<input $bind="email" />`                        |
+| `$key`           | List optimization     | `<div $for="user in users" $key="user.id">`      |
+| `$ref`           | Element reference     | `<input $ref="inputEl" />`                       |
 
-- **LRU Cache**: Stores up to 25 most recently used components
-- **Instant Loading**: Cached components load immediately
-- **Reduced Network**: No repeated HTTP requests for components
+---
 
-#### Function Caching
+## 📡 Event Bus
 
-- **Template Compilation**: Caches up to 100 compiled expressions
-- **Memory Efficient**: Reuses Function objects for identical expressions
-- **Faster Renders**: Expressions like `{formatName(user)}` compile once
+Communicate between components using `$emit` and `$listen`:
 
-**Performance Tips:**
+### Sender Component
 
-- Component files are cached after first load
-- State updates trigger minimal DOM changes
-- Event listeners are automatically cleaned up
-- Conditional rendering skips hidden elements
+```html
+<button onclick="sendMessage()">Send Message</button>
 
-## Common Patterns
+<script>
+  let message = "Hello from sender!";
 
-### Keyboard Events
+  function sendMessage() {
+    $emit("my-event", { text: message, time: new Date().toLocaleTimeString() });
+  }
+</script>
+```
 
-Handle keyboard input for interactive features:
+### Receiver Component
 
 ```html
 <div>
-  <p>Press arrow keys to navigate. Current: {direction}</p>
-  <p>Press Enter to submit</p>
+  <p>Received: {receivedMessage}</p>
 </div>
 
 <script>
-  let direction = "none";
-
-  document.addEventListener("keyup", (event) => {
-    if (event.key === "ArrowRight") {
-      direction = "right";
-    } else if (event.key === "ArrowLeft") {
-      direction = "left";
-    } else if (event.key === "ArrowUp") {
-      direction = "up";
-    } else if (event.key === "ArrowDown") {
-      direction = "down";
-    } else if (event.key === "Enter") {
-      direction = "submitted!";
-    }
+  let receivedMessage = "Waiting...";
+
+  $listen("my-event", (data) => {
+    receivedMessage = data.text;
   });
 </script>
 ```
 
-### Form Validation
+---
+
+## 🏷️ Element References
 
-Real-time form validation with reactive state:
+Use `$ref` to get direct DOM access for advanced manipulation:
 
 ```html
-<form onsubmit="handleSubmit(event)">
-  <input type="email" $bind="email" placeholder="Email" onkeyup="validate()" />
-  <p $if="{!isValid}" style="color: red">Please enter a valid email</p>
-  <button type="submit" $if="{isValid}">Submit</button>
-</form>
+<input type="text" $ref="inputEl" placeholder="Click button to focus" />
+<button onclick="focusInput()">Focus Input</button>
 
-<script>
-  let email = "";
-  let isValid = false;
+<canvas $ref="canvas" width="200" height="100"></canvas>
+<button onclick="draw()">Draw on Canvas</button>
 
-  const validate = () => {
-    isValid = email.includes("@") && email.length > 5;
-  };
+<script>
+  function focusInput() {
+    $refs.inputEl.focus();
+    $refs.inputEl.select();
+  }
 
-  const handleSubmit = (e) => {
-    e.preventDefault();
-    if (isValid) {
-      alert(`Submitted: ${email}`);
-    }
-  };
+  function draw() {
+    const ctx = $refs.canvas.getContext("2d");
+    ctx.fillStyle = "blue";
+    ctx.fillRect(10, 10, 100, 50);
+  }
 </script>
 ```
 
-### Loading States
+---
 
-Show loading indicators while fetching data:
+## ⏳ Lazy Loading
 
-```html
-<div>
-  <div $if="{isLoading}">Loading...</div>
-  <div $else-if="{error}">Error: {error}</div>
-  <div $else>
-    <h2>{data.title}</h2>
-    <p>{data.description}</p>
-  </div>
-  <button onclick="fetchData()">Refresh</button>
-</div>
+Load components only when needed to improve initial page load:
 
-<script>
-  let isLoading = false;
-  let error = null;
-  let data = { title: "", description: "" };
-
-  const fetchData = async () => {
-    isLoading = true;
-    error = null;
-
-    try {
-      const response = await fetch("https://api.example.com/data");
-      data = await response.json();
-    } catch (e) {
-      error = e.message;
-    } finally {
-      isLoading = false;
-    }
-  };
-</script>
-```
+### Lazy Loading Strategies
+
+```javascript
+import {
+  registerComponents,
+  lazyOnVisible,
+  lazyOnIdle,
+  lazyOnInteraction,
+  lazyOnMedia,
+  lazyOnDelay,
+} from "ladrillosjs";
 
-## API Reference
-
-### Registration Functions
-
-```typescript
-registerComponent(
-  name: string,
-  path: string,
-  useShadowDOM?: boolean,
-  lazy?: boolean
-): Promise<void>
-
-registerComponents(
-  components: Array<{
-    name: string,
-    path: string,
-    useShadowDOM?: boolean,
-    lazy?: boolean
-  }>
-): Promise<void>
+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
+  },
+]);
 ```
 
-**Parameters:**
+| 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                  |
+
+---
+
+## 📋 API Reference
+
+### registerComponent
 
-- `name`: Component tag name (must include a hyphen)
-- `path`: Path to the component file
-- `useShadowDOM`: Use Shadow DOM for style encapsulation (default: `true`)
-- `lazy`: Enable lazy loading with Intersection Observer (default: `false`)
+```javascript
+registerComponent(name, path, useShadowDOM?, lazy?)
+```
 
-**Examples:**
+| 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      |
 
 ```javascript
-// Basic registration
-await registerComponent("my-button", "./button.html");
+// Basic usage
+registerComponent("my-button", "./button.html");
 
-// Disable Shadow DOM
-await registerComponent("global-nav", "./nav.html", false);
+// Without Shadow DOM (for global CSS)
+registerComponent("my-nav", "./nav.html", false);
 
-// Enable lazy loading
-await registerComponent("footer", "./footer.html", true, true);
+// With lazy loading
+registerComponent("my-footer", "./footer.html", true, lazyOnVisible());
+```
 
-// Batch registration
-await registerComponents([
-  { name: "hero", path: "./hero.html" },
-  { name: "features", path: "./features.html", lazy: true },
-  { name: "footer", path: "./footer.html", useShadowDOM: false, lazy: true },
+### registerComponents
+
+Register multiple components with parallel fetching:
+
+```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 },
 ]);
+
+// Returns: { success: [...], failed: [...], skipped: [...] }
 ```
 
-### Component Utilities
+### Event Bus
 
-Available within component `<script>` tags:
+| Function                   | Description                         |
+| -------------------------- | ----------------------------------- |
+| `$emit(event, data)`       | Broadcast an event to all listeners |
+| `$listen(event, callback)` | Subscribe to an event               |
 
-```typescript
-// State management
-$getState(): object                    // Access component state
-$setState(updates: object): void       // Update state and re-render
+---
 
-// Event bus
-$emit(eventName: string, data?: any): void
-$listen(eventName: string, callback: (data?) => void): () => void
+## 🛠️ Using with Vite
 
-// DOM queries (respects Shadow DOM boundaries)
-$querySelector(selector: string): Element | null
-$querySelectorAll(selector: string): NodeListOf<Element>
+LadrillosJS works seamlessly with Vite for production builds:
 
-// Manual reactive initialization (optional - mainly for backward compatibility)
-// Module scripts automatically initialize and sync variables
-$reactive(name: string, initialValue: any): (value: any) => void
+```bash
+npm install ladrillosjs vite
 ```
 
-### Component Attributes
+```javascript
+// vite.config.js
+import { defineConfig } from "vite";
 
-```html
-<!-- Two-way data binding -->
-<input $bind="variableName" />
-
-<!-- Conditional rendering -->
-<div $if="{condition}">...</div>
-<div $else-if="{anotherCondition}">...</div>
-<div $else>...</div>
-
-<!-- List rendering -->
-<li $for="item in items">{item}</li>
-<li $for="(item, index) in items">{index}: {item}</li>
-<div $for="user in users" $key="user.id">{user.name}</div>
-
-<!-- Lazy loading override -->
-<footer-section eager></footer-section>
-<!-- Force immediate load -->
-
-<!-- Event handlers -->
-<button onclick="methodName()">Click</button>
-<button onclick="method(arg1, arg2)">Call with args</button>
-<button onclick="console.log(event)">Inline function</button>
-
-<!-- Slots -->
-<slot></slot>
-<!-- Default slot -->
-<slot name="header"></slot>
-<!-- Named slot -->
+export default defineConfig({
+  // LadrillosJS components work out of the box!
+});
 ```
 
-### Template Syntax
+```javascript
+// main.js
+import { registerComponent } from "ladrillosjs";
 
-```html
-<!-- Variable interpolation -->
-{variableName} {object.property} {array[0]}
+registerComponent("my-counter", "./components/counter.html", false);
+```
 
-<!-- Function calls -->
-{functionName(arg1, arg2)} {object.method()}
+See the [samples/](samples/) directory for complete examples:
 
-<!-- Expressions -->
-{count + 1} {isActive ? 'Yes' : 'No'} {items.length > 0 ? 'Has items' : 'Empty'}
-```
+- `samples/vite-sample/` — Basic Vite setup
+- `samples/vite-basic-site/` — Multi-component site
+- `samples/ladrillos-demo/` — Full feature showcase
 
-## Development
+---
 
-### Prerequisites
+## 📚 Examples
 
-- **Node.js**: v20.19+ or v22.12+
-- **npm**: v9+ (comes with Node.js)
+### Todo List
 
-### Setup
+A complete CRUD example combining all directives:
 
-```bash
-# Clone the repository
-git clone https://github.com/drubiodev/LadrillosJS.git
-cd LadrillosJS
+```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>
 
-# Install dependencies
-npm install
+  <ul>
+    <li $for="todo in todos" $key="todo.id">
+      <input type="checkbox" onclick="toggleTodo({todo.id})" />
+      <span class="{todo.completed ? 'done' : ''}">{todo.text}</span>
+      <button onclick="removeTodo({todo.id})">🗑️</button>
+    </li>
+  </ul>
 
-# Start development server
-npm run dev
+  <p $if="{todos.length === 0}">No todos yet!</p>
+</div>
 
-# Build the library
-npm run build
+<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 = "";
+    }
+  }
 
-# Run tests
-npm test
+  function toggleTodo(id) {
+    todos = todos.map((t) =>
+      t.id === id ? { ...t, completed: !t.completed } : t
+    );
+  }
 
-# Run tests with coverage
-npm run test:coverage
+  function removeTodo(id) {
+    todos = todos.filter((t) => t.id !== id);
+  }
+</script>
 ```
 
-### Project Structure
+> 💡 Check the [samples/](samples/) folder for more examples including lazy loading, event bus communication, and real-world patterns.
 
-```
-LadrillosJS/
-├── src/
-│   ├── index.ts              # Main entry point
-│   ├── core/
-│   │   ├── main.ts          # Core Ladrillos class
-│   │   ├── webcomponent.ts  # Web component wrapper
-│   │   ├── componentParser.ts  # Parse component files
-│   │   ├── componentSource.ts  # Fetch with caching
-│   │   ├── eventBus.ts      # Global event bus
-│   │   ├── css/
-│   │   │   └── cssParser.ts
-│   │   ├── html/
-│   │   │   ├── htmlparser.ts
-│   │   │   └── htmlRenderer.ts
-│   │   └── js/
-│   │       └── scriptParser.ts
-│   ├── cache/
-│   │   ├── index.ts         # LRU component cache
-│   │   └── functionCache.ts # LRU function cache
-│   ├── types/
-│   │   └── LadrilloTypes.ts
-│   └── utils/
-│       ├── logger.ts
-│       └── regex.ts
-├── samples/                  # Example applications
-│   └── apps/
-│       ├── todo/
-│       ├── notes/
-│       ├── simple-button/
-│       └── ...
-├── test/                     # Test files
-├── dist/                     # Built files
-├── package.json
-├── tsconfig.json
-├── vite.config.js
-└── vitest.config.js
-```
+---
 
-### NPM Scripts
+## 🤝 Contributing
+
+Contributions are welcome! Here's how you can help:
+
+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 Setup
 
 ```bash
-npm run dev              # Start Vite dev server
-npm run build            # Build library (ESM, UMD, CJS)
-npm run build:types      # Generate TypeScript declarations
-npm test                 # Run tests with Vitest
-npm run test:coverage    # Run tests with coverage report
-npm run preview          # Preview production build
+git clone https://github.com/drubiodev/LadrillosJS.git
+cd LadrillosJS
+npm install
+npm run dev        # Watch mode for development
+npm run build      # Build for production
 ```
 
-## Attribution
-
-If you use LadrillosJS in your project, I'd appreciate a mention or link back to this repository, though it's not required. It helps others discover the framework and motivates continued development!
+---
 
-## 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>
 
-🌟 [GitHub](https://github.com/drubiodev/LadrillosJS) • 📦 [NPM](https://www.npmjs.com/package/ladrillosjs) • 📖 [Documentation](https://github.com/drubiodev/LadrillosJS/blob/main/README.md)
+<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>