lego-dom 0.0.9 → 1.0.0

package/docs/guide/components.md

@@ -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/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
@@ -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

@@ -18,8 +18,10 @@ The fastest way to try Lego is via CDN:
   <my-component></my-component>
   
   <script src="https://unpkg.com/lego-dom/main.js"></script>
-  <template b-id="my-component">
+  <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>
@@ -42,7 +44,11 @@ import { Lego } from 'lego-dom';
 
 Lego.define('my-component', `
   <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,12 +232,12 @@ 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" />
 ```
@@ -224,6 +248,7 @@ Special attributes for common patterns:
 - ✅ 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

@@ -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)
@@ -77,7 +77,7 @@ Compare that to:
 | 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/quick-start.md

@@ -27,7 +27,7 @@ The fastest way to get started with Lego is using the CDN. No build tools requir
     <!-- 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',
@@ -35,6 +35,9 @@ The fastest way to get started with Lego is using the CDN. No build tools requir
                 this.name = this.name === 'World' ? 'Lego' : 'World';
             }
         };
+
+        // Start the engine
+        Lego.init();
     </script>
 </body>
 </html>

package/docs/guide/reactivity.md

@@ -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: