lego-dom 1.0.0 → 1.3.4

package/docs/router/resolver.md

@@ -1,7 +1,7 @@
 
 # 06. Target Resolver: Scoping and Logic
 
-In the previous chapters, we used `b-target` to send content to different parts of the page. But how does LegoJS actually find those "holes" in a complex, nested DOM? This is where the **Target Resolver** comes in.
+In the previous chapters, we used `b-target` to send content to different parts of the page. But how does LegoDOM actually find those "holes" in a complex, nested DOM? This is where the **Target Resolver** comes in.
 
 The Target Resolver is a prioritized logic engine that ensures your links always find the correct destination, even in massive applications with thousands of components.
 
@@ -16,11 +16,11 @@ In traditional JavaScript, if you use `document.querySelector('#detail-view')`,
 
 ## The Resolver Hierarchy
 
-When you click a `b-link` with a `b-target`, LegoJS follows a strict search order to resolve the target:
+When you click a `b-link` with a `b-target`, LegoDOM follows a strict search order to resolve the target:
 
 ### 1. Local Component Scope (The Primary Search)
 
-LegoJS first looks for the target **inside the component that contains the link**.
+LegoDOM first looks for the target **inside the component that contains the link**.
 
 If you use `b-target="email-view"`, Lego looks for an `<email-view>` tag _within the current parent shell_. This allows you to have multiple instances of the same layout on one screen without them interfering with each other.
 
@@ -58,7 +58,7 @@ For highly dynamic UIs, `b-target` can even be a function or a dynamic expressio
 
 ```
 <!-- Logic decides the target based on screen size -->
-<a href="/settings" b-link b-target="{{ isMobile ? '#main' : 'settings-pane' }}">
+<a href="/settings" b-link b-target="[[ isMobile ? '#main' : 'settings-pane' ]]">
   Settings
 </a>
 
@@ -66,7 +66,7 @@ For highly dynamic UIs, `b-target` can even be a function or a dynamic expressio
 
 ## Why This Matters
 
-By prioritizing local tags over global IDs, LegoJS encourages **Encapsulation**. Your components become "Black Boxes" that manage their own internal routing targets. This means you can take a complex "Messaging Shell" and drop it into a "Dashboard Shell" without changing a single line of routing code—the targets will still resolve correctly because they are scoped to their parents.
+By prioritizing local tags over global IDs, LegoDOM encourages **Encapsulation**. Your components become "Black Boxes" that manage their own internal routing targets. This means you can take a complex "Messaging Shell" and drop it into a "Dashboard Shell" without changing a single line of routing code—the targets will still resolve correctly because they are scoped to their parents.
 
 ## Summary
 

package/docs/router/surgical-swaps.md

@@ -1,6 +1,6 @@
 # Surgical Swaps: Mastering b-target
 
-The true power of LegoJS lies in its ability to perform **Surgical Swaps**. In a traditional application, clicking a link often causes the entire page to re-render, destroying the state of your sidebar, header, or scroll position.
+The true power of LegoDOM lies in its ability to perform **Surgical Swaps**. In a traditional application, clicking a link often causes the entire page to re-render, destroying the state of your sidebar, header, or scroll position.
 
 With `b-target` (and optionally `b-link`), we can choose to update only a specific "fragment" of the page.
 
@@ -80,8 +80,8 @@ You can tell Lego to find a specific element by its ID and replace its contents.
     <aside class="sidebar">
       <div b-for="chat in threads">
         <!-- Parent component (this shell) binds data to these links -->
-        <a href="/messaging/{{chat.id}}" b-target="#chat-window">
-          {{chat.userName}}
+        <a href="/messaging/[[chat.id]]" b-target="#chat-window">
+          [[chat.userName]]
         </a>
       </div>
     </aside>
@@ -110,7 +110,7 @@ Because Lego is built on Custom Elements, you can target a component tag directl
 
 ## How the Target Resolver Works
 
-When you click a link with a `b-target`, the LegoJS **Target Resolver** follows a specific hierarchy:
+When you click a link with a `b-target`, the LegoDOM **Target Resolver** follows a specific hierarchy:
 
 1.  **Local Scope**: It looks for the target inside the current component first. This prevents "ID collisions" if you have multiple instances of a layout.
     
@@ -123,7 +123,7 @@ When you click a link with a `b-target`, the LegoJS **Target Resolver** follows
 
 ## Smart History
 
-Even though we are only swapping a small part of the DOM, LegoJS is smart enough to update the browser's address bar.
+Even though we are only swapping a small part of the DOM, LegoDOM is smart enough to update the browser's address bar.
 
 When a surgical swap happens, Lego saves the "target" information into the browser's history state (`history.state.legoTargets`). This means that when a user hits the **Back Button**, Lego knows exactly which fragment needs to be swapped back to its previous state.
 

package/docs/tutorial/01-project-setup.md

@@ -0,0 +1,152 @@
+# Step 1: Project Setup
+
+Let's create a new LegoDOM project from scratch. By the end of this page, you'll have a fully configured development environment ready to build components.
+
+## Create a New Project
+
+Open your terminal and run:
+
+```bash
+# Create a new Vite project
+npm create vite@latest my-lego-app -- --template vanilla
+
+# Enter the project
+cd my-lego-app
+
+# Install LegoDOM
+npm install lego-dom
+
+# Install dependencies
+npm install
+```
+
+## Configure Vite
+
+Create or replace `vite.config.js` in your project root:
+
+```javascript
+import { defineConfig } from 'vite';
+import legoPlugin from 'lego-dom/vite-plugin';
+
+export default defineConfig({
+  plugins: [
+    legoPlugin({
+      componentsDir: './src/components',  // Where your .lego files live
+      include: ['**/*.lego']              // File pattern to match
+    })
+  ]
+});
+```
+
+## Project Structure
+
+Create this folder structure:
+
+```
+my-lego-app/
+├── index.html          ← Your app's entry HTML
+├── src/
+│   ├── app.js          ← Your app's entry JavaScript ⭐
+│   └── components/     ← Your .lego files go here
+│       └── (empty for now)
+├── vite.config.js      ← Vite configuration
+└── package.json
+```
+
+::: warning The Magic File: `app.js`
+This is where **everything comes together**. Your routes, global state, and initialization all happen here. We'll build it in the next section.
+:::
+
+## Set Up Your Entry Point
+
+Replace the contents of `src/app.js` (create it if it doesn't exist):
+
+```javascript
+// 1. Import the Lego core
+import { Lego } from 'lego-dom';
+
+// 2. Import the virtual module that auto-discovers .lego files
+import registerComponents from 'virtual:lego-components';
+
+// 3. Register all discovered components
+registerComponents();
+
+// 4. Define your routes (we'll add these soon!)
+// Lego.route('/', 'home-page');
+// Lego.route('/login', 'login-page');
+
+// 5. Initialize the engine
+await Lego.init();
+```
+
+> **What's happening here?**
+> - Lines 1-3: Import LegoDOM and auto-register every `.lego` file in your `components/` folder
+> - Line 4: Routes map URLs to components (commented out until we create them)
+> - Line 5: `Lego.init()` starts the reactivity engine, routing, and DOM observation
+
+## Set Up Your HTML
+
+Replace `index.html`:
+
+```html
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>My Lego App</title>
+  <style>
+    * { margin: 0; padding: 0; box-sizing: border-box; }
+    body { 
+      font-family: system-ui, -apple-system, sans-serif;
+      background: #f5f5f5;
+      min-height: 100vh;
+    }
+  </style>
+</head>
+<body>
+  <!-- The router renders your page components here -->
+  <lego-router></lego-router>
+  
+  <!-- Load your app -->
+  <script type="module" src="/src/app.js"></script>
+</body>
+</html>
+```
+
+## Run It
+
+```bash
+npm run dev
+```
+
+Open `http://localhost:5173` in your browser. You'll see a blank page—that's expected! We haven't created any components yet.
+
+## What You've Done
+
+✅ Created a Vite project  
+✅ Installed LegoDOM  
+✅ Configured the Vite plugin  
+✅ Set up `app.js` with the Lego initialization pattern  
+✅ Added `<lego-router>` to your HTML  
+
+## The Key Insight
+
+::: tip Where Config Goes: The Golden Rule
+**Everything related to your app's setup goes in `app.js`:**
+- Component registration → `registerComponents()`
+- Route definitions → `Lego.route(...)`
+- Global state → `Lego.globals.user = ...`
+- Initialization → `Lego.init()`
+
+Your `index.html` just needs `<lego-router>` and a script tag. That's it.
+:::
+
+---
+
+<div style="display: flex; justify-content: space-between; margin-top: 3rem;">
+  <span></span>
+  <a href="./02-your-first-component" style="display: inline-block; background: #4CAF50; color: white; padding: 0.75rem 1.5rem; border-radius: 6px; text-decoration: none; font-weight: 600;">
+    Next: Your First Component →
+  </a>
+</div>

package/docs/tutorial/02-your-first-component.md

@@ -0,0 +1,226 @@
+# Step 2: Your First Component
+
+Now let's create a component! By the end of this page, you'll understand the `.lego` file format and have a working home page.
+
+## Create Your First `.lego` File
+
+Create `src/components/home-page.lego`:
+
+```html
+<template>
+  <div class="hero">
+    <h1>[[ title ]]</h1>
+    <p>[[ subtitle ]]</p>
+    <button @click="handleClick()">[[ buttonText ]]</button>
+  </div>
+  
+  <div class="features">
+    <div class="feature" b-for="feature in features">
+      <span class="icon">[[ feature.icon ]]</span>
+      <h3>[[ feature.title ]]</h3>
+      <p>[[ feature.description ]]</p>
+    </div>
+  </div>
+</template>
+
+<style>
+  self {
+    display: block;
+    min-height: 100vh;
+    background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
+    color: white;
+    padding: 4rem 2rem;
+  }
+  
+  .hero {
+    text-align: center;
+    max-width: 600px;
+    margin: 0 auto 4rem;
+  }
+  
+  .hero h1 {
+    font-size: 3rem;
+    margin-bottom: 1rem;
+  }
+  
+  .hero p {
+    font-size: 1.25rem;
+    opacity: 0.9;
+    margin-bottom: 2rem;
+  }
+  
+  .hero button {
+    background: white;
+    color: #667eea;
+    border: none;
+    padding: 1rem 2.5rem;
+    font-size: 1.1rem;
+    font-weight: 600;
+    border-radius: 50px;
+    cursor: pointer;
+    transition: transform 0.2s, box-shadow 0.2s;
+  }
+  
+  .hero button:hover {
+    transform: translateY(-2px);
+    box-shadow: 0 10px 20px rgba(0,0,0,0.2);
+  }
+  
+  .features {
+    display: grid;
+    grid-template-columns: repeat(auto-fit, minmax(250px, 1fr));
+    gap: 2rem;
+    max-width: 900px;
+    margin: 0 auto;
+  }
+  
+  .feature {
+    background: rgba(255,255,255,0.1);
+    padding: 2rem;
+    border-radius: 16px;
+    text-align: center;
+    backdrop-filter: blur(10px);
+  }
+  
+  .feature .icon {
+    font-size: 3rem;
+    display: block;
+    margin-bottom: 1rem;
+  }
+  
+  .feature h3 {
+    margin-bottom: 0.5rem;
+  }
+  
+  .feature p {
+    opacity: 0.8;
+    font-size: 0.9rem;
+  }
+</style>
+
+<script>
+export default {
+  title: 'Welcome to My App',
+  subtitle: 'Built with LegoDOM – the tiny framework that loves developers',
+  buttonText: 'Get Started',
+  
+  features: [
+    { icon: '⚡', title: 'Lightning Fast', description: 'No virtual DOM overhead' },
+    { icon: '🧩', title: 'Component-Based', description: 'Reusable building blocks' },
+    { icon: '🎨', title: 'Scoped Styles', description: 'CSS that never leaks' }
+  ],
+  
+  handleClick() {
+    // We'll wire this up to navigation soon!
+    alert('Clicked! Next: we\'ll navigate to /login');
+  },
+  
+  mounted() {
+    console.log('Home page mounted!');
+  }
+}
+</script>
+```
+
+## Understanding the Structure
+
+Every `.lego` file has three sections:
+
+### 1. `<template>` – Your HTML
+
+```html
+<template>
+  <h1>[[ title ]]</h1>           <!-- Reactive text -->
+  <button @click="doSomething()"> <!-- Event binding -->
+  <div b-for="item in items">     <!-- Loop directive -->
+</template>
+```
+
+### 2. `<style>` – Scoped CSS
+
+```html
+<style>
+  self {
+    /* 'self' targets the component root (like :host) */
+    display: block;
+  }
+  
+  button {
+    /* These styles ONLY affect this component */
+  }
+</style>
+```
+
+### 3. `<script>` – Logic & State
+
+```html
+<script>
+export default {
+  // Reactive properties
+  title: 'Hello',
+  count: 0,
+  items: [],
+  
+  // Methods
+  doSomething() {
+    this.count++;  // Mutation triggers re-render!
+  },
+  
+  // Lifecycle
+  mounted() {
+    console.log('Component is ready');
+  }
+}
+</script>
+```
+
+## Register the Route
+
+Now update `src/app.js` to show your component:
+
+```javascript{7-8}
+import { Lego } from 'lego-dom';
+import registerComponents from 'virtual:lego-components';
+
+registerComponents();
+
+// Add this line:
+Lego.route('/', 'home-page');
+
+await Lego.init();
+```
+
+## See It Live
+
+```bash
+npm run dev
+```
+
+Open `http://localhost:5173` and you'll see your beautiful home page!
+
+## What You've Learned
+
+✅ The three-section `.lego` file structure  
+✅ Template syntax: `[[ ]]` for data, `@click` for events, `b-for` for loops  
+✅ The `self` keyword for component root styling  
+✅ How to export state and methods from `<script>`  
+✅ Connecting a component to a route  
+
+## Key Pattern: Component → Route → Display
+
+```
+home-page.lego  →  Lego.route('/', 'home-page')  →  <lego-router> shows it
+```
+
+The filename (minus `.lego`) becomes the component name. Routes map URLs to component names. The router displays the matched component.
+
+---
+
+<div style="display: flex; justify-content: space-between; margin-top: 3rem;">
+  <a href="./01-project-setup" style="display: inline-block; background: #eee; color: #333; padding: 0.75rem 1.5rem; border-radius: 6px; text-decoration: none; font-weight: 600;">
+    ← Previous: Project Setup
+  </a>
+  <a href="./03-adding-routes" style="display: inline-block; background: #4CAF50; color: white; padding: 0.75rem 1.5rem; border-radius: 6px; text-decoration: none; font-weight: 600;">
+    Next: Adding Routes →
+  </a>
+</div>