lego-dom 0.0.8 → 1.0.0

package/docs/guide/components.md

@@ -1,6 +1,6 @@
 # Components
 
-Learn how to create and use components in LegoJS.
+Learn how to create and use components in Lego.
 
 ## What is a Component?
 
@@ -36,10 +36,14 @@ A component is a reusable, self-contained piece of UI with its own template, sty
 Define components directly in your HTML with `<template b-id>`:
 
 ```html
-<template b-id="hello-world">
+<template b-id="hello-world" b-data="{ name: 'Default User' }">
   <h1>Hello {{ name }}!</h1>
 </template>
 
+<!-- Uses the default "Default User" -->
+<hello-world></hello-world>
+
+<!-- Overrides the default with "Alice" -->
 <hello-world b-data="{ name: 'Alice' }"></hello-world>
 ```
 
@@ -113,24 +117,38 @@ Access state in templates using `{{ }}`:
 }"></user-card>
 ```
 
-### Merging with Defaults
+### Data Merging (The Three Tiers)
 
-Component defaults are merged with `b-data`:
+Lego uses a sophisticated three-tier merging strategy to initialize component state. This allows you to define defaults at the library level, customize them for a component type, and then override them for specific instances.
 
-```js
-Lego.define('user-card', `...`, {
-  name: 'Guest',      // Default
-  email: '',          // Default
-  role: 'user'        // Default
-});
-```
+The priority is as follows (**last one wins**):
+
+1.  **Tier 1: Script Logic** - Data defined in `Lego.define()` or exported from a `.lego` SFC.
+2.  **Tier 2: Template Defaults** - Data defined on the `<template b-data="...">` attribute.
+3.  **Tier 3: Instance Overrides** - Data defined on the actual component tag `<my-comp b-data="...">`.
+
+### Example of Merging
 
 ```html
-<!-- Only name is overridden -->
+<!-- 1. Script Logic (Defined in JS) -->
+<script>
+  Lego.define('user-card', `...`, { role: 'guest', theme: 'light' });
+</script>
+
+<!-- 2. Template Defaults (Defined in HTML) -->
+<template b-id="user-card" b-data="{ role: 'member', name: 'Anonymous' }">
+  ...
+</template>
+
+<!-- 3. Instance Overrides -->
 <user-card b-data="{ name: 'Alice' }"></user-card>
-<!-- email and role use defaults -->
 ```
 
+In the example above, the final state for the component will be:
+- `role`: `'member'` (Template override beats Script)
+- `theme`: `'light'` (Only defined in Script)
+- `name`: `'Alice'` (Instance override beats Template)
+
 ## Component Communication
 
 ### Parent → Child (Props)
@@ -326,12 +344,12 @@ Clear timers, remove listeners:
 ### Loading States
 
 ```html
-<div b-if="loading">Loading...</div>
-<div b-if="!loading && data">
+<div b-show="loading">Loading...</div>
+<div b-show="!loading && data">
   <h2>{{ data.title }}</h2>
   <p>{{ data.content }}</p>
 </div>
-<div b-if="!loading && error">
+<div b-show="!loading && error">
   Error: {{ error }}
 </div>
 ```

package/docs/guide/contributing.md

@@ -1,12 +1,12 @@
 # Contributing
 
-Thank you for your interest in contributing to LegoJS!
+Thank you for your interest in contributing to Lego!
 
 ## Development Setup
 
 1. Clone the repository:
    ```bash
-   git clone https://github.com/rayattack/LegoJS.git
+   git clone https://github.com/rayattack/Lego.git
    ```
 
 2. Install dependencies:

package/docs/guide/directives.md

@@ -2,34 +2,34 @@
 
 Directives are special attributes that add reactive behavior to elements.
 
-## b-if
+## b-show
 
 Conditional rendering using `display: none`.
 
 ### Basic Usage
 
 ```html
-<p b-if="isLoggedIn">Welcome back!</p>
-<p b-if="!isLoggedIn">Please log in</p>
+<p b-show="isLoggedIn">Welcome back!</p>
+<p b-show="!isLoggedIn">Please log in</p>
 ```
 
 ### With Expressions
 
 ```html
-<div b-if="count > 0">Count is {{ count }}</div>
-<div b-if="items.length === 0">No items</div>
-<div b-if="user && user.role === 'admin'">Admin panel</div>
+<div b-show="count > 0">Count is {{ count }}</div>
+<div b-show="items.length === 0">No items</div>
+<div b-show="user && user.role === 'admin'">Admin panel</div>
 ```
 
 ### Multiple Conditions
 
 ```html
-<p b-if="isLoggedIn && isPremium">Premium content</p>
-<p b-if="age >= 18 || hasParentConsent">Access granted</p>
+<p b-show="isLoggedIn && isPremium">Premium content</p>
+<p b-show="age >= 18 || hasParentConsent">Access granted</p>
 ```
 
 ::: tip How it Works
-`b-if` sets `display: none` when the condition is false. The element stays in the DOM but is hidden.
+`b-show` sets `display: none` when the condition is false. The element stays in the DOM but is hidden.
 :::
 
 ## b-for
@@ -83,8 +83,8 @@ Use `$index` (implicit variable):
 
 ```html
 <li b-for="user in users">
-  <span b-if="user.active">✅ {{ user.name }}</span>
-  <span b-if="!user.active">❌ {{ user.name }}</span>
+  <span b-show="user.active">✅ {{ user.name }}</span>
+  <span b-show="!user.active">❌ {{ user.name }}</span>
 </li>
 ```
 
@@ -103,7 +103,7 @@ Two-way data binding for form inputs.
 
 ```html
 <input type="checkbox" b-sync="agreed">
-<p b-if="agreed">You agreed to the terms</p>
+<p b-show="agreed">You agreed to the terms</p>
 ```
 
 ### Radio Buttons
@@ -243,7 +243,7 @@ Initialize component state.
 ```html
 <todo-list b-data="{
   todos: [
-    { text: 'Learn LegoJS', done: true },
+    { text: 'Learn Lego', done: true },
     { text: 'Build app', done: false }
   ],
   filter: 'all'
@@ -268,10 +268,10 @@ Lego.define('user-card', `...`, {
 
 ## Combining Directives
 
-### b-if + b-for
+### b-show + b-for
 
 ```html
-<li b-for="item in items" b-if="item.visible">
+<li b-for="item in items" b-show="item.visible">
   {{ item.name }}
 </li>
 ```
@@ -296,11 +296,11 @@ Lego.define('user-card', `...`, {
 
 ## Best Practices
 
-### 1. Use b-if for Show/Hide
+### 1. Use b-show for Show/Hide
 
 ```html
 <!-- ✅ Clean -->
-<div b-if="showPanel">Panel content</div>
+<div b-show="showPanel">Panel content</div>
 
 <!-- ❌ Verbose -->
 <div style="display: {{ showPanel ? 'block' : 'none' }}">Panel content</div>
@@ -344,9 +344,9 @@ Move complex logic to methods.
 
 ## Performance Tips
 
-### b-if vs CSS
+### b-show vs CSS
 
-`b-if` is fine for most cases, but for frequently toggled elements, use CSS:
+`b-show` is fine for most cases, but for frequently toggled elements, use CSS:
 
 ```html
 <!-- For frequent toggling -->
@@ -386,7 +386,7 @@ Paginate large lists:
 
 ```html
 <button @click="visible = !visible">Toggle</button>
-<div b-if="visible">Content</div>
+<div b-show="visible">Content</div>
 ```
 
 ### Counter
@@ -418,9 +418,9 @@ Paginate large lists:
   <button @click="activeTab = 'settings'">Settings</button>
 </nav>
 
-<div b-if="activeTab === 'home'">Home content</div>
-<div b-if="activeTab === 'profile'">Profile content</div>
-<div b-if="activeTab === 'settings'">Settings content</div>
+<div b-show="activeTab === 'home'">Home content</div>
+<div b-show="activeTab === 'profile'">Profile content</div>
+<div b-show="activeTab === 'settings'">Settings content</div>
 ```
 
 ## Next Steps

package/docs/guide/getting-started.md

@@ -1,25 +1,27 @@
 # Getting Started
 
-Get up and running with LegoJS in under 5 minutes.
+Get up and running with Lego in under 5 minutes.
 
 ## Installation
 
 ### Option 1: CDN (No Build Tools)
 
-The fastest way to try LegoJS is via CDN:
+The fastest way to try Lego is via CDN:
 
 ```html
 <!DOCTYPE html>
 <html>
 <head>
-  <title>My LegoJS App</title>
+  <title>My Lego App</title>
 </head>
 <body>
   <my-component></my-component>
   
   <script src="https://unpkg.com/lego-dom/main.js"></script>
-  <template b-id="my-component">
-    <h1>Hello LegoJS!</h1>
+  <template b-id="my-component" b-data="{ count: 0 }">
+    <h1>Hello Lego!</h1>
+    <button @click="count++">Click me</button>
+    <p>Count: {{ count }}</p>
   </template>
 </body>
 </html>
@@ -41,8 +43,12 @@ Then import it:
 import { Lego } from 'lego-dom';
 
 Lego.define('my-component', `
-  <h1>Hello LegoJS!</h1>
-`);
+  <h1>Hello Lego!</h1>
+  <button @click="count++">Click me</button>
+  <p>Count: {{ count }}</p>
+`, {
+  count: 0,
+});
 ```
 
 ### Option 3: With Vite (Recommended for Larger Projects)
@@ -66,6 +72,21 @@ export default defineConfig({
 });
 ```
 
+### The Runtime Engine
+
+Crucially, you must initialize the Lego background engine in your entry file (`src/main.js`):
+
+```js
+import { Lego } from 'lego-dom';
+import registerComponents from 'virtual:lego-components';
+
+// 1. Register SFCs
+registerComponents();
+
+// 2. Start the Engine (Async)
+await Lego.init();
+```
+
 ## Your First Component
 
 Let's create a simple counter component.
@@ -73,7 +94,7 @@ Let's create a simple counter component.
 ### Using HTML Templates
 
 ```html
-<template b-id="click-counter">
+<template b-id="click-counter" b-data="{ message: 'Welcome!', count: 0 }">
   <style>
     self {
       display: block;
@@ -96,12 +117,15 @@ Let's create a simple counter component.
     }
   </style>
   
-  <h2>{{ message }}</h2>
-  <p>Count: <strong>{{ count }}</strong></p>
-  <button @click="count++">Click Me!</button>
-</template>
+  <template b-id="click-counter" b-data="{ message: 'Welcome!', count: 0 }">
+    ... markup ...
+  </template>
+  
+  <!-- Uses defaults: message="Welcome!", count=0 -->
+  <click-counter></click-counter>
 
-<click-counter b-data="{ message: 'Welcome!', count: 0 }"></click-counter>
+  <!-- Overrides message, keeps count=0 -->
+  <click-counter b-data="{ message: 'Bienvenido!' }"></click-counter>
 
 <script src="https://unpkg.com/lego-dom/main.js"></script>
 ```
@@ -208,22 +232,23 @@ Use `@eventname` to handle events:
 
 Special attributes for common patterns:
 
-- `b-if` - Conditional rendering
+- `b-show` - Conditional rendering
 - `b-for` - List rendering
 - `b-sync` - Two-way binding
 
 ```html
-<p b-if="isLoggedIn">Welcome back!</p>
+<p b-show="isLoggedIn">Welcome back!</p>
 <li b-for="item in items">{{ item.name }}</li>
 <input b-sync="username" />
 ```
 
 ## What You've Learned
 
-- ✅ Three different ways to install LegoJS
+- ✅ Three different ways to install Lego
 - ✅ How to create your first component
 - ✅ The basics of templates, state, and events
 - ✅ Available directives
+- ✅ The importance of the `Lego.init()` engine
 
 ## Next Steps
 

package/docs/guide/index.md

@@ -1,12 +1,12 @@
-# What is LegoJS?
+# What is Lego?
 
-LegoJS is a tiny, zero-dependency JavaScript library for building reactive Web Components directly in the browser.
+LegoDOM is a tiny, zero-dependency JavaScript library for building reactive Web Components directly in the browser.
 
 ## The Philosophy
 
-LegoJS is built on a simple belief: **the DOM is not your enemy**.
+LegoDOM is built on a simple belief: **the DOM is not your enemy**.
 
-Modern frameworks introduced virtual DOMs and compilation steps to solve problems that arose from trying to make the DOM do things it wasn't designed for. LegoJS takes a different approach—it embraces the DOM and Web Components as they were intended to be used.
+Modern frameworks introduced virtual DOMs and compilation steps to solve problems that arose from trying to make the DOM do things it wasn't designed for. Lego takes a different approach—it embraces the DOM and Web Components as they were intended to be used.
 
 ## Key Principles
 
@@ -17,7 +17,7 @@ There are no new concepts to learn. If you know:
 - JavaScript objects
 - Basic DOM events
 
-You already know LegoJS.
+You already know Lego.
 
 ### 2. No Build Step Required
 
@@ -34,7 +34,7 @@ component._studs.count++;
 
 ### 4. Web Standards First
 
-LegoJS uses:
+Lego uses:
 - **Web Components** - Standard custom elements
 - **Shadow DOM** - Native encapsulation
 - **ES6 Proxies** - For reactivity
@@ -42,9 +42,9 @@ LegoJS uses:
 
 No proprietary APIs. Everything is built on web standards.
 
-## When to Use LegoJS
+## When to Use Lego
 
-### ✅ LegoJS is Great For:
+### ✅ Lego is Great For:
 
 - **Small to medium applications** where framework overhead isn't worth it
 - **Embedded widgets** that need to work anywhere
@@ -64,8 +64,8 @@ No proprietary APIs. Everything is built on web standards.
 The core library (`main.js`) is **under 500 lines** of well-commented JavaScript.
 
 - **No dependencies** - Zero `node_modules` bloat
-- **~17KB** - Unminified, human-readable code
-- **~6KB** - Minified and gzipped
+- **~22KB** - Unminified, human-readable code
+- **~7KB** - Minified and gzipped
 
 Compare that to:
 - Vue 3: ~33KB (minified + gzipped)
@@ -74,10 +74,10 @@ Compare that to:
 
 ## What Makes It Different?
 
-| Aspect | LegoJS | Traditional Frameworks |
+| Aspect | Lego | Traditional Frameworks |
 |--------|--------|----------------------|
 | **Reactivity** | Direct object mutation | setState / dispatch / ref() |
-| **Templates** | HTML with `{{ }}` | JSX / template syntax |
+| **Templates** | HTML with <code v-pre>{{ }}</code> | JSX / template syntax |
 | **Styles** | Shadow DOM (native) | CSS-in-JS / scoped CSS |
 | **Build** | Optional | Required |
 | **Learning Curve** | Hours | Days/Weeks |

package/docs/guide/lifecycle.md

@@ -1,6 +1,6 @@
 # Lifecycle Hooks
 
-Learn about component lifecycle hooks in LegoJS.
+Learn about component lifecycle hooks in Lego.
 
 ## Overview
 

package/docs/guide/quick-start.md

@@ -1,6 +1,6 @@
 # Quick Start
 
-The fastest way to get started with LegoJS is using the CDN. No build tools required!
+The fastest way to get started with Lego is using the CDN. No build tools required!
 
 ## 1. Create an HTML file
 
@@ -9,7 +9,7 @@ The fastest way to get started with LegoJS is using the CDN. No build tools requ
 <html lang="en">
 <head>
     <meta charset="UTF-8">
-    <title>LegoJS Quick Start</title>
+    <title>Lego Quick Start</title>
 </head>
 <body>
     <!-- 2. Use your component -->
@@ -24,17 +24,20 @@ The fastest way to get started with LegoJS is using the CDN. No build tools requ
         <button @click="toggle()">Toggle Name</button>
     </template>
 
-    <!-- 4. Load LegoJS -->
+    <!-- 4. Load Lego -->
     <script src="https://unpkg.com/lego-dom/main.js"></script>
     
-    <!-- 5. Define logic (Optional) -->
+    <!-- 5. Define logic & Init -->
     <script>
         document.querySelector('hello-world').state = {
             name: 'World',
             toggle() {
-                this.name = this.name === 'World' ? 'LegoJS' : 'World';
+                this.name = this.name === 'World' ? 'Lego' : 'World';
             }
         };
+
+        // Start the engine
+        Lego.init();
     </script>
 </body>
 </html>

package/docs/guide/reactivity.md

@@ -1,6 +1,6 @@
 # Reactivity
 
-Understand how LegoJS makes your UI automatically update when data changes.
+Understand how Lego makes your UI automatically update when data changes.
 
 ## The Core Concept
 
@@ -15,7 +15,7 @@ No `setState()`, no `dispatch()`, no special syntax. Just mutate the data.
 
 ## How It Works
 
-LegoJS uses **ES6 Proxies** to track changes:
+Lego uses **ES6 Proxies** to track changes:
 
 ```js
 const reactive = (obj, el) => {
@@ -62,7 +62,7 @@ this.items.sort();            // ✅ Reactive
 this.user.profile.age = 30;   // ✅ Reactive
 ```
 
-LegoJS recursively wraps nested objects in proxies.
+Lego recursively wraps nested objects in proxies.
 
 ### ✅ Object Deletion
 
@@ -112,7 +112,7 @@ Initialize all properties upfront:
 
 ## Batching Updates
 
-LegoJS batches updates using `requestAnimationFrame`:
+Lego batches updates using `requestAnimationFrame`:
 
 ```js
 this.count = 1;
@@ -145,11 +145,32 @@ This prevents unnecessary DOM updates and improves performance.
   
   updated() {
     console.log('DOM updated with:', this.count);
-    // DOM is updated now!
   }
 }
 ```
 
+## Global Reactivity
+
+Lego also supports **Global State** available to all components and the main document.
+
+```js
+// src/main.js
+Lego.globals.isLoggedIn = true;
+```
+
+For global state to automatically update mustaches in your `index.html`, you must initialize the engine:
+
+```js
+// Enables global reactivity and the MutationObserver
+Lego.init();
+```
+
+Inside any component, you can access global state via `global`:
+
+```html
+<p b-show="global.isLoggedIn">Welcome!</p>
+```
+
 ## Deep Reactivity
 
 Nested objects are automatically reactive:
@@ -296,7 +317,7 @@ console.log(component._studs.count);  // Actual value
 const count = ref(0);
 count.value++;
 
-// LegoJS
+// Lego
 this.count++;
 ```
 
@@ -307,7 +328,7 @@ this.count++;
 const [count, setCount] = useState(0);
 setCount(count + 1);
 
-// LegoJS
+// Lego
 this.count++;
 ```
 
@@ -318,11 +339,11 @@ this.count++;
 let count = 0;
 count++;
 
-// LegoJS
+// Lego
 this.count++;
 ```
 
-LegoJS is closest to Svelte's model but uses Proxies instead of compilation.
+Lego is closest to Svelte's model but uses Proxies instead of compilation.
 
 ## Advanced Patterns