lego-dom 0.0.8 → 1.0.0

package/docs/router/surgical-swaps.md

@@ -0,0 +1,134 @@
+# 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.
+
+With `b-target` (and optionally `b-link`), we can choose to update only a specific "fragment" of the page.
+
+## The Problem with "Nuclear" Navigation
+
+Imagine a messaging app (like LinkedIn or Slack). You have a sidebar full of conversations. When you click a message, you want the chat window to update, but you **don't** want the sidebar to reload.
+
+If the sidebar reloads:
+
+1.  The scroll position is lost.
+    
+2.  Any search text in the sidebar is cleared.
+    
+3.  The UI "flickers," making the app feel slow.
+
+
+## The Solution: `b-target`
+
+The `b-target` directive allows a link to specify exactly where the new component should be rendered. It implies `b-link` (history update) by default.
+
+
+### Example: messaging-shell.html
+
+In this SFC, we define a layout with a sidebar and a main content area. Clicking a contact updates _only_ the `<main>` area.
+
+```html
+<!-- messaging-shell.html -->
+<template>
+  <div class="messaging-layout">
+    <aside class="sidebar">
+      <h2>Contacts</h2>
+      <nav>
+        <a href="/chat/alice" b-target="#chat-window">Alice</a>
+        <a href="/chat/bob" b-target="#chat-window">Bob</a>
+      </nav>
+    </aside>
+
+    <main id="chat-window">
+      <p>Select a contact to start chatting.</p>
+    </main>
+  </div>
+</template>
+
+<script>
+  export default {
+    mounted() {
+      console.log("Messaging shell ready.");
+    }
+  }
+</script>
+
+<style>
+  .messaging-layout {
+    display: flex;
+    height: 100vh;
+  }
+  .sidebar {
+    width: 300px;
+    border-right: 1px solid #ccc;
+  }
+  #chat-window {
+    flex: 1;
+    padding: 20px;
+  }
+</style>
+
+```
+
+### 1. Targeting by ID
+
+You can tell Lego to find a specific element by its ID and replace its contents.
+
+```html
+<!-- messaging-shell.html -->
+<template>
+  <div class="layout">
+    <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>
+      </div>
+    </aside>
+
+    <main id="chat-window">
+      <!-- Only this area will change when a link is clicked -->
+      <p>Select a conversation to begin.</p>
+    </main>
+  </div>
+</template>
+
+```
+
+### 2. Targeting by Component Tag (The Web Component Way)
+
+Because Lego is built on Custom Elements, you can target a component tag directly. The framework will find that tag and swap its internal content.
+
+```html
+<a href="/profile/settings" b-target="settings-view">Edit Settings</a>
+
+<settings-view>
+  <!-- Content gets swapped here -->
+</settings-view>
+
+```
+
+## How the Target Resolver Works
+
+When you click a link with a `b-target`, the LegoJS **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.
+    
+2.  **Component Match**: If the target doesn't start with `#`, it treats it as a tag name (e.g., `thread-view`).
+    
+3.  **Global Fallback**: If it can't find a local match, it searches the entire document.
+    
+4.  **Router Fallback**: If no target is found, it defaults back to the `<lego-router>`.
+    
+
+## 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.
+
+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.
+
+## Summary
+
+`b-target` turns your web app into a high-performance workspace. By keeping the "Shell" alive and only swapping "Fragments," you maintain state, eliminate flickers, and provide a desktop-like experience.
+
+Next, we will tackle the most common question: **"What happens if I refresh the page while looking at a surgical fragment?"** We'll explore the **Cold Start: Self-Healing Layouts**.

package/examples/vite-app/README.md

@@ -1,6 +1,6 @@
-# LegoJS SFC and Vite Plugin Example
+# Lego SFC and Vite Plugin Example
 
-This example demonstrates how to use LegoJS with Single File Components (.lego files) and the Vite plugin.
+This example demonstrates how to use Lego with Single File Components (.lego files) and the Vite plugin.
 
 ## Setup
 

package/examples/vite-app/index.html

@@ -1,9 +1,10 @@
 <!DOCTYPE html>
 <html lang="en">
+
 <head>
   <meta charset="UTF-8">
   <meta name="viewport" content="width=device-width, initial-scale=1.0">
-  <title>LegoJS Vite Example</title>
+  <title>Lego Vite Example</title>
   <style>
     body {
       font-family: system-ui, -apple-system, sans-serif;
@@ -28,18 +29,13 @@
     }
   </style>
 </head>
-<body>
-  <h1>LegoJS + Vite Example</h1>
-  
-  <div class="info">
-    <p><strong>✨ These components are auto-discovered from .lego files!</strong></p>
-    <p>The Vite plugin automatically finds all .lego files in <code>src/components/</code> and registers them.</p>
-  </div>
 
-  <!-- These components are automatically discovered and hydrated -->
-  <sample-component></sample-component>
-  <greeting-card></greeting-card>
+<body>
+  <app-navbar></app-navbar>
+  <lego-router id="app-outlet"></lego-router>
+  <aside id="outside-router"></aside>
 
-  <script type="module" src="/src/main.js"></script>
+  <script type="module" src="/src/app.js"></script>
 </body>
-</html>
+
+</html>

package/examples/vite-app/package.json

@@ -8,9 +8,11 @@
     "preview": "vite preview"
   },
   "dependencies": {
-    "lego-dom": "file:../.."
+    "@tailwindcss/vite": "^4.1.18",
+    "lego-dom": "file:../..",
+    "tailwindcss": "^4.1.18"
   },
   "devDependencies": {
     "vite": "^5.0.0"
   }
-}
+}

package/examples/vite-app/src/app.css

@@ -0,0 +1,3 @@
+h1 {
+  color: red !important;
+}

package/examples/vite-app/src/app.js

@@ -0,0 +1,29 @@
+// Import Tailwind CSS
+import './app.css';
+
+// Import Lego core
+import { Lego } from 'lego-dom/main.js';
+
+// Import virtual module that auto-discovers and registers all .lego components
+import registerComponents from 'virtual:lego-components';
+
+// Register all auto-discovered components
+registerComponents();
+
+// 10. Define SPA Routes
+Lego.route('/', 'sample-component');
+Lego.route('/todo', 'todo-list');
+Lego.route('/card', 'user-card');
+Lego.route('/customers/:id/orders', 'customer-orders');
+Lego.route('/customers/:id/details', 'customer-details');
+
+// 11. Optional: Add a middleware example
+Lego.route('/admin', 'admin-panel', async (params, globals) => {
+  console.log('Checking permissions for', params);
+  return globals.isLoggedIn;
+});
+
+// Initialize Lego
+await Lego.init(document.body, {
+  tailwind: ['/src/app.css']
+})

package/examples/vite-app/src/components/app-navbar.lego

@@ -0,0 +1,34 @@
+<style>
+  self {
+    display: block;
+    padding: 1rem;
+    background: #f9fafb;
+    border-bottom: 1px solid #e0e0e0;
+  }
+
+  nav {
+    display: flex;
+    justify-content: space-between;
+    align-items: center;
+  }
+</style>
+
+<template>
+  <nav>
+    <ul>
+      <li><a href="/" b-target="#outside-router" b-link="true">Home</a></li>
+      <li><a href="/todo" b-target>Todo</a></li>
+      <li><a href="/card" b-target>Card</a></li>
+      <li><a href="/customers/1/orders">Customers</a></li>
+    </ul>
+  </nav>
+</template>
+
+<script>
+  export default {
+    name: 'AppNavbar',
+    mounted() {
+      console.log('This is mounted');
+    }
+  }
+</script>

package/examples/vite-app/src/components/customers/customer-details.lego

@@ -0,0 +1,24 @@
+<template>
+  <customers-shell>
+    <div style="padding: 1rem; border: 1px dashed #4f46e5;">
+      <h3>👤 Customer Profile</h3>
+      <p>Details for Customer ID: <strong>{{ global.$route.params.id }}</strong></p>
+
+      <div style="display: grid; gap: 0.5rem; margin-top: 1rem;">
+        <div><strong>Status:</strong> Premium Member</div>
+        <div><strong>Joined:</strong> January 2024</div>
+        <div><strong>Region:</strong> Europe</div>
+      </div>
+
+      <div style="margin-top: 1rem;">
+        <a href="/customers/{{ global.$route.params.id }}/orders" b-target="#todo-container">View Orders</a>
+      </div>
+    </div>
+  </customers-shell>
+</template>
+
+<script>
+  export default {
+    name: 'CustomerDetails'
+  }
+</script>

package/examples/vite-app/src/components/customers/customer-orders.lego

@@ -0,0 +1,21 @@
+<template>
+  <customers-shell>
+    <div style="padding: 1rem; border: 1px dashed #ccc;">
+      <h3>📦 Order History</h3>
+      <p>Viewing orders for Customer ID: <strong>{{ global.$route.params.id }}</strong></p>
+
+      <!-- Composition: Using another component inside -->
+      <order-list></order-list>
+
+      <div style="margin-top: 1rem;">
+        <a href="/customers/{{ global.$route.params.id }}/details" b-target="#todo-container">View Profile Info</a>
+      </div>
+    </div>
+  </customers-shell>
+</template>
+
+<script>
+  export default {
+    name: 'CustomerOrders'
+  }
+</script>

package/examples/vite-app/src/components/customers/order-list.lego

@@ -0,0 +1,55 @@
+<style>
+  ul {
+    list-style: none;
+    padding: 0;
+  }
+
+  li {
+    padding: 0.5rem;
+    border: 1px solid #eee;
+    margin-bottom: 0.5rem;
+    border-radius: 4px;
+    display: flex;
+    justify-content: space-between;
+  }
+
+  .status {
+    font-weight: bold;
+    color: #059669;
+  }
+</style>
+
+<template>
+  <div>
+    <h4>Recent Orders</h4>
+    <p b-show="loading">Loading orders for customer...</p>
+    <ul b-show="!loading">
+      <li b-for="order in orders">
+        <span>Order #{{ order.id }}</span>
+        <span class="status">{{ order.status }}</span>
+      </li>
+    </ul>
+  </div>
+</template>
+
+<script>
+  export default {
+    name: 'OrderList',
+    state: {
+      orders: [],
+      loading: true
+    },
+    async mounted() {
+      // Simulate API fetch using the customer ID from parent or global params
+      const customerId = Lego.globals.$route.params.id;
+      setTimeout(() => {
+        this.orders = [
+          { id: '101', status: 'Delivered' },
+          { id: '105', status: 'Shipped' },
+          { id: '110', status: 'Processing' }
+        ];
+        this.loading = false;
+      }, 800);
+    }
+  }
+</script>

package/examples/vite-app/src/components/greeting-card.lego

@@ -1,34 +1,34 @@
-<template>
-  <style>
-    self {
-      display: block;
-      padding: 1rem;
-      background: #f3f4f6;
-      border-radius: 0.5rem;
-      margin: 0.5rem 0;
-    }
+<style>
+  self {
+    display: block;
+    padding: 1rem;
+    background: #f3f4f6;
+    border-radius: 0.5rem;
+    margin: 0.5rem 0;
+  }
 
-    input {
-      padding: 0.5rem;
-      border: 1px solid #d1d5db;
-      border-radius: 0.25rem;
-      margin-right: 0.5rem;
-      font-size: 1rem;
-    }
+  input {
+    padding: 0.5rem;
+    border: 1px solid #d1d5db;
+    border-radius: 0.25rem;
+    margin-right: 0.5rem;
+    font-size: 1rem;
+  }
 
-    .greeting {
-      margin-top: 1rem;
-      padding: 1rem;
-      background: white;
-      border-radius: 0.25rem;
-      font-size: 1.25rem;
-      color: #1f2937;
-    }
-  </style>
+  .greeting {
+    margin-top: 1rem;
+    padding: 1rem;
+    background: white;
+    border-radius: 0.25rem;
+    font-size: 1.25rem;
+    color: #1f2937;
+  }
+</style>
 
+<template>
   <div>
     <input b-sync="name" type="text" placeholder="Enter your name">
-    <div class="greeting" b-if="name">
+    <div class="greeting" b-show="name">
       Hello, {{ name }}! 👋
     </div>
   </div>

package/examples/vite-app/src/components/sample-component.lego

@@ -1,75 +1,75 @@
-<template>
-  <style>
-    self {
-      display: block;
-      padding: 1.5rem;
-      margin: 1rem 0;
-      border: 2px solid #4f46e5;
-      border-radius: 0.5rem;
-      background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
-      color: white;
-      font-family: system-ui, -apple-system, sans-serif;
-      box-shadow: 0 4px 6px rgba(0, 0, 0, 0.1);
-    }
+<style>
+  self {
+    display: block;
+    padding: 1.5rem;
+    margin: 1rem 0;
+    border: 2px solid #4f46e5;
+    border-radius: 0.5rem;
+    background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
+    color: white;
+    font-family: system-ui, -apple-system, sans-serif;
+    box-shadow: 0 4px 6px rgba(0, 0, 0, 0.1);
+  }
 
-    .header {
-      font-size: 1.5rem;
-      font-weight: bold;
-      margin-bottom: 0.5rem;
-    }
+  .header {
+    font-size: 1.5rem;
+    font-weight: bold;
+    margin-bottom: 0.5rem;
+  }
 
-    .content {
-      margin: 1rem 0;
-      line-height: 1.6;
-    }
+  .content {
+    margin: 1rem 0;
+    line-height: 1.6;
+  }
 
-    button {
-      background: white;
-      color: #4f46e5;
-      border: none;
-      padding: 0.5rem 1rem;
-      border-radius: 0.25rem;
-      font-weight: 600;
-      cursor: pointer;
-      transition: transform 0.2s;
-    }
+  button {
+    background: white;
+    color: #4f46e5;
+    border: none;
+    padding: 0.5rem 1rem;
+    border-radius: 0.25rem;
+    font-weight: 600;
+    cursor: pointer;
+    transition: transform 0.2s;
+  }
 
-    button:hover {
-      transform: scale(1.05);
-    }
+  button:hover {
+    transform: scale(1.05);
+  }
 
-    .count {
-      display: inline-block;
-      background: rgba(255, 255, 255, 0.2);
-      padding: 0.25rem 0.75rem;
-      border-radius: 0.25rem;
-      margin-left: 0.5rem;
-    }
-  </style>
+  .count {
+    display: inline-block;
+    background: rgba(255, 255, 255, 0.2);
+    padding: 0.25rem 0.75rem;
+    border-radius: 0.25rem;
+    margin-left: 0.5rem;
+  }
+</style>
 
+<template>
   <div class="header">{{ title }}</div>
   <div class="content">
-    <p>This is a sample LegoJS component loaded from a .lego file!</p>
+    <p class="gobe">This is a sample Lego component loaded from a .lego file!</p>
     <p>Message: {{ message }}</p>
   </div>
   <button @click="incrementCount()">
-    Click me! 
+    Click me!
     <span class="count">{{ count }}</span>
   </button>
 </template>
 
 <script>
-export default {
-  title: 'Sample Component',
-  message: 'Hello from .lego file!',
-  count: 0,
-  
-  incrementCount() {
-    this.count++;
-  },
-  
-  mounted() {
-    console.log('Sample component mounted!');
+  export default {
+    title: 'Sample Component',
+    message: 'Hello from .lego file!',
+    count: 0,
+
+    incrementCount() {
+      this.count++;
+    },
+
+    mounted() {
+      console.log('Sample component mounted!');
+    }
   }
-}
-</script>
+</script>

package/examples/vite-app/src/components/shells/customers-shell.lego

@@ -0,0 +1,21 @@
+<style>
+  self {
+    display: block;
+    padding: 1rem;
+    background: #f9fafb;
+    border-bottom: 1px solid #e0e0e0;
+  }
+</style>
+
+<template>
+  <div>
+    <h2>Customers Shell</h2>
+    <slot></slot>
+  </div>
+</template>
+
+<script>
+  export default {
+    name: 'CustomersShell'
+  }
+</script>