lego-dom 1.0.0 → 1.3.4

package/docs/guide/faq.md

@@ -0,0 +1,210 @@
+# Frequently Asked Questions
+
+Quick answers to the most common LegoDOM questions.
+
+## Project Setup
+
+### Where do I define my routes?
+
+**In your entry file (`app.js` or `main.js`), before `Lego.init()`.**
+
+```javascript
+// src/app.js
+import { Lego } from 'lego-dom';
+import registerComponents from 'virtual:lego-components';
+
+registerComponents();
+
+// Define routes HERE ⭐
+Lego.route('/', 'home-page');
+Lego.route('/login', 'login-page');
+Lego.route('/users/:id', 'user-profile');
+
+await Lego.init();  // Must come AFTER routes
+```
+
+### Where does my config go?
+
+Everything related to app configuration belongs in your entry file:
+
+| What | Where |
+|------|-------|
+| Component registration | `registerComponents()` |
+| Route definitions | `Lego.route(...)` |
+| Global state init | `Lego.globals.user = null` |
+| Engine start | `Lego.init()` |
+
+### Should I use `main.js` or `app.js`?
+
+Either works! It's just a naming convention. Use whatever your Vite template created, or rename it. Just make sure your `index.html` points to it:
+
+```html
+<script type="module" src="/src/app.js"></script>
+```
+
+---
+
+## Components
+
+### Why isn't my component showing?
+
+Check these common issues:
+
+1. **No route defined** – Did you add `Lego.route('/', 'my-component')`?
+2. **Missing `<lego-router>`** – Your HTML needs `<lego-router></lego-router>`
+3. **Wrong component name** – Filename `user-card.lego` → component `<user-card>`
+4. **Not registered** – Did you call `registerComponents()` before `init()`?
+
+### Why do component names need hyphens?
+
+It's a Web Components standard! Custom elements must contain a hyphen to avoid conflicts with future HTML elements.
+
+✅ Valid: `user-card`, `app-nav`, `my-button`  
+❌ Invalid: `usercard`, `Card`, `button`
+
+### Can I use PascalCase filenames?
+
+Yes! LegoDOM automatically converts:
+- `UserCard.lego` → `<user-card>`
+- `AppNav.lego` → `<app-nav>`
+- `my_component.lego` → `<my-component>`
+
+---
+
+## Navigation
+
+### How do I navigate between pages?
+
+**Option 1: Declarative (in templates)**
+```html
+<a href="/login" b-link>Go to Login</a>
+```
+
+**Option 2: Programmatic (in JavaScript)**
+```javascript
+this.$go('/login').get();
+```
+
+### What's the difference between `b-link` and `b-target`?
+
+| Attribute | What it does |
+|-----------|--------------|
+| `b-link` | SPA navigation, updates URL, swaps `<lego-router>` |
+| `b-target="#id"` | Swaps content of specific element, updates URL |
+| `b-target="#id" b-link="false"` | Swaps content, does NOT update URL |
+
+### How do I pass data when navigating?
+
+Use global state:
+
+```javascript
+// Before navigating
+Lego.globals.selectedUser = { id: 42, name: 'John' };
+this.$go('/user-details').get();
+
+// In the target component
+mounted() {
+  console.log(Lego.globals.selectedUser.name);  // 'John'
+}
+```
+
+Or use route parameters:
+
+```javascript
+// Route: Lego.route('/users/:id', 'user-profile')
+this.$go('/users/42').get();
+
+// In user-profile component
+mounted() {
+  const userId = this.$route.params.id;  // '42'
+}
+```
+
+---
+
+## State
+
+### How do I share data between components?
+
+Use `Lego.globals`:
+
+```javascript
+// Component A sets it
+Lego.globals.user = { name: 'John' };
+
+// Component B reads it
+console.log(Lego.globals.user.name);  // 'John'
+
+// In templates
+<p>Hello, [[ global.user.name ]]!</p>
+```
+
+### Why isn't my data updating the view?
+
+Make sure you're mutating the reactive object, not replacing references:
+
+```javascript
+// ✅ This works - mutating property
+this.items.push(newItem);
+this.user.name = 'Jane';
+
+// ❌ This might not work - reassigning local variable
+let items = this.items;
+items.push(newItem);  // Won't trigger re-render!
+```
+
+---
+
+## Styling
+
+### What is `self` in styles?
+
+`self` is a special keyword that targets the component's root element (like `:host` in Shadow DOM):
+
+```html
+<style>
+  self {
+    display: block;
+    padding: 1rem;
+  }
+</style>
+```
+
+LegoDOM automatically transforms this to `:host` for Shadow DOM.
+
+### Do styles leak to other components?
+
+No! Styles are scoped via Shadow DOM. Your `.button` class won't affect buttons in other components.
+
+---
+
+## Build & Development
+
+### Can I use LegoDOM without Vite?
+
+Yes! Use the CDN approach:
+
+```html
+<script src="https://unpkg.com/lego-dom/main.js"></script>
+<template b-id="my-component">...</template>
+<my-component></my-component>
+<script>Lego.init();</script>
+```
+
+See [CDN Usage](/guide/cdn-usage) for details.
+
+### Why use Vite?
+
+Benefits of Vite + `.lego` files:
+- **Hot reload** – Changes appear instantly
+- **Auto-discovery** – No manual component registration
+- **Better organization** – One file per component
+- **Syntax highlighting** – Editor support for `.lego` files
+
+---
+
+## Still Stuck?
+
+- 📖 [Complete Tutorial](/tutorial/) – Build an app step-by-step
+- 💬 [GitHub Discussions](https://github.com/rayattack/LegoDOM/discussions)
+- 🐛 [Report Issues](https://github.com/rayattack/LegoDOM/issues)

package/docs/guide/getting-started.md

@@ -2,6 +2,10 @@
 
 Get up and running with Lego in under 5 minutes.
 
+::: tip 🚀 Want a Complete Walkthrough?
+Check out our **[Step-by-Step Tutorial](/tutorial/)** – build a full multi-page app from scratch in 15 minutes!
+:::
+
 ## Installation
 
 ### Option 1: CDN (No Build Tools)
@@ -21,7 +25,7 @@ The fastest way to try Lego is via CDN:
   <template b-id="my-component" b-data="{ count: 0 }">
     <h1>Hello Lego!</h1>
     <button @click="count++">Click me</button>
-    <p>Count: {{ count }}</p>
+    <p>Count: [[ count ]]</p>
   </template>
 </body>
 </html>
@@ -45,7 +49,7 @@ import { Lego } from 'lego-dom';
 Lego.define('my-component', `
   <h1>Hello Lego!</h1>
   <button @click="count++">Click me</button>
-  <p>Count: {{ count }}</p>
+  <p>Count: [[ count ]]</p>
 `, {
   count: 0,
 });
@@ -144,8 +148,8 @@ Lego.define('click-counter', `
     }
   </style>
   
-  <h2>{{ message }}</h2>
-  <p>Count: {{ count }}</p>
+  <h2>[[ message ]]</h2>
+  <p>Count: [[ count ]]</p>
   <button @click="increment()">Click Me!</button>
 `, {
   message: 'Welcome!',
@@ -175,8 +179,8 @@ Create `src/components/click-counter.lego`:
     }
   </style>
   
-  <h2>{{ message }}</h2>
-  <p>Count: {{ count }}</p>
+  <h2>[[ message ]]</h2>
+  <p>Count: [[ count ]]</p>
   <button @click="increment()">Click Me!</button>
 </template>
 
@@ -197,11 +201,11 @@ The Vite plugin automatically discovers and registers it!
 
 ### 1. Templates
 
-Templates define what your component looks like. Use `{{ }}` for dynamic content:
+Templates define what your component looks like. Use `[[ ]]` for dynamic content:
 
 ```html
-<h1>Hello {{ name }}!</h1>
-<p>{{ calculateAge() }} years old</p>
+<h1>Hello [[ name ]]!</h1>
+<p>[[ calculateAge() ]] years old</p>
 ```
 
 ### 2. State (Studs)
@@ -238,7 +242,7 @@ Special attributes for common patterns:
 
 ```html
 <p b-show="isLoggedIn">Welcome back!</p>
-<li b-for="item in items">{{ item.name }}</li>
+<li b-for="item in items">[[ item.name ]]</li>
 <input b-sync="username" />
 ```
 

package/docs/guide/index.md

@@ -77,7 +77,7 @@ Compare that to:
 | Aspect | Lego | Traditional Frameworks |
 |--------|--------|----------------------|
 | **Reactivity** | Direct object mutation | setState / dispatch / ref() |
-| **Templates** | HTML with <code v-pre>{{ }}</code> | 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

@@ -233,6 +233,38 @@ Called when the component is removed from the DOM.
     }
   }
 }
+  }
+}
+```
+
+## Performance Hooks (Metrics)
+
+For advanced monitoring, LegoDOM provides global hooks in `Lego.config.metrics`. These run for **every** component.
+
+### `onRenderStart` & `onRenderEnd`
+
+Useful for tracking how long renders take, which helps identify slow components.
+
+```javascript
+Lego.config.metrics = {
+  onRenderStart(el) {
+    console.time(`render-${el.tagName}`);
+  },
+  onRenderEnd(el) {
+    console.timeEnd(`render-${el.tagName}`);
+  }
+};
+```
+
+### `onAllSettled` (New in v2.0)
+
+Called when the entire component tree (including Shadow DOM children) has finished its initial render pass. This is perfect for removing loading spinners or measuring "Time to Interactive".
+
+```javascript
+/* main.js */
+Lego.init(document.body).then(() => {
+  document.getElementById('global-loader').remove();
+});
 ```
 
 ## Lifecycle Flow

package/docs/guide/quick-start.md

@@ -12,16 +12,16 @@ The fastest way to get started with Lego is using the CDN. No build tools requir
     <title>Lego Quick Start</title>
 </head>
 <body>
-    <!-- 2. Use your component -->
-    <hello-world></hello-world>
+    <!-- Interpolation works here too -->
+    <hello-world name="Lego"></hello-world>
 
     <!-- 3. Define the template -->
     <template b-id="hello-world">
         <style>
             h1 { color: #646cff; }
         </style>
-        <h1>Hello, {{ name }}!</h1>
-        <button @click="toggle()">Toggle Name</button>
+        <h1>Hello [[ name ]]!</h1>
+        <button @click="count++">Count is [[ count ]]</button>
     </template>
 
     <!-- 4. Load Lego -->

package/docs/guide/reactivity.md

@@ -189,7 +189,7 @@ Nested objects are automatically reactive:
 
 ```html
 <!-- All reactive -->
-<p>{{ user.profile.settings.theme }}</p>
+<p>[[ user.profile.settings.theme ]]</p>
 ```
 
 ```js
@@ -381,7 +381,7 @@ Use methods:
 ```
 
 ```html
-<p>{{ fullName() }}</p>
+<p>[[ fullName() ]]</p>
 ```
 
 ### Debouncing Updates

package/docs/guide/routing.md

@@ -1,14 +1,75 @@
 # Surgical Routing
 
-LegoDOM features a powerful "Surgical Router" that sets it apart from typical SPA routers. Instead of just replacing a single `<router-outlet>`, Lego allows you to swap **any** part of your page from **any** link, giving you the feel of a complex SPA with the simplicity of old-school HTML frames.
+**Stop rebuilding your entire page just to change one div.**
 
-## The Concept
+LegoDOM's router is different. It doesn't have a single "Root Outlet". Instead, **any element** can be a router target. This allows you to build **Persistent Layouts** (like Sidebars, Music Players, or Chat Windows) that never reload or lose state while the user navigates.
 
-In traditional SPAs, you have one `RouterView` that swaps out entire pages.
-In Lego, every link can be a router trigger, and every element can be a target.
+::: tip 🚀 Just Want to Navigate Between Pages?
+Here's the quick answer:
 
-- **`b-target`**: "Where should this content go?"
-- **`b-link`**: "Should this update the URL history?"
+**1. Define routes in `app.js`:**
+```javascript
+Lego.route('/', 'home-page');
+Lego.route('/login', 'login-page');
+Lego.route('/dashboard', 'dashboard-page');
+```
+
+**2. Navigate with links:**
+```html
+<a href="/login" b-link>Go to Login</a>
+```
+
+**3. Or navigate with JavaScript:**
+```javascript
+this.$go('/login').get();
+```
+
+That's it! For the full tutorial, see [Adding Routes](/tutorial/03-adding-routes).
+:::
+
+## Quick Reference
+
+| I want to... | Code |
+|--------------|------|
+| Define a route | `Lego.route('/path', 'component-name')` |
+| Link to a page | `<a href="/path" b-link>Click</a>` |
+| Navigate via JS | `this.$go('/path').get()` |
+| Get URL params | `this.$route.params.id` |
+| Update only one div | `<a href="/x" b-target="#myDiv">` |
+| Navigate without URL change | `this.$go('/x').get(false)` |
+
+---
+
+## The Architecture: "The Persistent Shell"
+
+The best way to use LegoDOM is to define a static "Shell" that holds your persistent tools, and standard outlets for your content.
+
+```html
+<body>
+  <!-- 1. The Shell (Sidebar): Never reloads. Keeps scroll pos & draft state. -->
+  <aside id="sidebar">
+    <file-tree></file-tree>
+  </aside>
+
+  <!-- 2. The Stage (Main Content): This changes when URL changes. -->
+  <lego-router id="stage"></lego-router>
+  
+  <!-- 3. The Context (Right Panel): Tools based on selection. -->
+  <aside id="tools"></aside>
+</body>
+```
+
+Then, you simply tell links *where* to render their content:
+
+```html
+<!-- Updates component in #stage (Default URL navigation) -->
+<a href="/dashboard" b-target="#stage">Dashboard</a>
+
+<!-- Updates component in #tools (Keeps URL sync, but only touches right panel) -->
+<a href="/tools/settings" b-target="#tools">Settings</a>
+```
+
+This feels like a native app. The Sidebar doesn't flicker. The scroll position isn't lost.
 
 ---
 
@@ -130,7 +191,7 @@ Keep a persistent Main Content while swapping sidebars.
   <!-- Context specific tools render here -->
   <template b-id="user-profile">
     <h1>User Profile</h1>
-    <p>User ID: {{ $route.params.id }}</p>
+    <p>User ID: [[ $route.params.id ]]</p>
     <button @click="loadUser()">Load User</button>
   </template>
 </aside>
@@ -213,7 +274,7 @@ Lego.route('/customers/:id/orders/:orderId', 'order-details-page');
 <!-- order-details-page.lego -->
 <template>
   <customers-layout>
-    <order-info id="{{ $route.params.orderId }}"></order-info>
+    <order-info id="[[ $route.params.orderId ]]"></order-info>
   </customers-layout>
 </template>
 ```

package/docs/guide/server-side.md

@@ -0,0 +1,134 @@
+# Server-Side Architecture
+
+LegoDOM is designed to play nicely with backend frameworks like **Heaven**, **Django**, **Rails**, or **Go**.
+
+Unlike typical SPAs that require a massive build step, LegoDOM can fetch components **on-demand** from your server. This gives you the routing simplicity of a backend with the interactivity of a frontend framework.
+
+## The Auto-Loader Pattern
+
+Instead of bundling every component `users-list`, `chat-widget`, `billing-modal` into one big `app.js` file, you can load them lazily.
+
+Configure the `loader` hook in your main entry file:
+
+```javascript
+Lego.init(document.body, {
+  loader: (tagName) => `/components/${tagName}.lego`
+});
+```
+
+Now, your HTML can just use tags that haven't been defined yet:
+
+```html
+<!-- index.html (Server Rendered) -->
+<h1>Dashboard</h1>
+
+<!-- LegoDOM sees this, fetches /components/user-feed.lego, and upgrades it -->
+<user-feed></user-feed>
+```
+
+## Power Mode: Authentication & State
+
+Often you need to pass **Authentication Tokens** or **Global State** to the server to get a personalized component.
+
+Return a `Promise` from your loader to take full control of the fetch:
+
+```javascript
+Lego.init(document.body, {
+  loader: async (tagName) => {
+    const token = localStorage.getItem('jwt');
+    
+    const response = await fetch(`/components/${tagName}`, {
+      headers: {
+        'Authorization': `Bearer ${token}`,
+        'X-Theme': Lego.globals.theme
+      }
+    });
+
+    if (!response.ok) return null;
+    return await response.text(); // Return the SFC content
+  }
+});
+```
+
+## Server-Side State Injection
+
+Since the server generates the `.lego` file, it can inject data before sending it to the browser.
+
+**Example (Backend Pseudocode):**
+
+```python
+# GET /components/user-card ("Flask-like" syntax)
+@app.route('/components/user-card')
+def get_user_card():
+    user = db.get_current_user()
+    
+    # We bake the data right into the template!
+    return f"""
+    <template>
+      <div class="card">
+        <h2>[[ name ]]</h2>
+        <p>Balance: $[[ balance ]]</p>
+      </div>
+    </template>
+    
+    <script>
+       export default {
+         name: "{user.name}", 
+         balance: {user.balance}
+       }
+    </script>
+    """
+```
+
+The browser receives a component that **already has the data**. No second API call needed!
+
+## Runtime Components
+
+If you fetch component code manually (e.g. via WebSockets or a custom pipeline), you can register it using `Lego.defineSFC`:
+
+```javascript
+socket.on('component_update', (msg) => {
+  // msg.code contains the <template>... string
+  Lego.defineSFC(msg.code, msg.name + '.lego');
+});
+```
+```
+
+## Production Considerations
+
+### 1. Error Handling
+What if the server returns a 404 or 500? Your `loader` should handle this gracefully so the user isn't stuck with a blank screen.
+
+```javascript
+loader: async (tagName) => {
+  try {
+    const res = await fetch(`/components/${tagName}.lego`);
+    if (!res.ok) {
+      console.error(`Component ${tagName} failed: ${res.status}`);
+      // Fallback to a generic error component
+      return `<template><div class="error">Failed to load ${tagName}</div></template>`;
+    }
+    return await res.text();
+  } catch (err) {
+    return `<template><div class="error">Network Error</div></template>`;
+  }
+}
+```
+
+### 2. Caching Strategy
+LegoDOM caches the *compiled class* of a component once loaded. It does **not** re-fetch the `.lego` file for every instance.
+However, if you want browser-level caching for the HTTP requests, ensure your server sends correct headers:
+
+```http
+Cache-Control: public, max-age=3600, immutable
+```
+
+### 3. Preloading
+If you know a user is about to visit a page (e.g. hovering a link), you can preload the component SFC:
+
+```javascript
+const preload = (tagName) => {
+  // Just calling the loader puts it in the browser's fetch cache
+  Lego.config.loader(tagName); 
+};
+```