lego-dom 1.3.3 → 1.4.0

package/docs/router/cold-entry.md

@@ -1,91 +0,0 @@
-
-# The Cold Start: Self-Healing Layouts
-
-In the previous section, we learned how to use `b-target` to surgically swap fragments while the app is running. But what happens when a user types `myapp.com/messaging/123` directly into the address bar or hits **Refresh (F5)**?
-
-In a traditional nested router, the framework handles this automatically. In LegoDOM, we use a more powerful, explicit pattern called **Self-Healing Layouts**.
-
-## The Cold Entry/Start Challenge
-
-When a "Cold Start" occurs:
-
-1.  The browser requests the URL from the server.
-    
-2.  The server returns the base `index.html`.
-    
-3.  LegoDOM matches the route `/messaging/:id` to the `messaging-shell` component.
-    
-4.  The `messaging-shell` mounts, but the `#chat-window` target is empty (or showing its default "Select a conversation" text).
-    
-
-The user is at the correct URL, but the **fragment** (the specific email or chat) is missing.
-
-## The Solution: The "Self-Healing" Mounted Hook
-
-To fix this, the Parent Shell must be responsible for "healing" its own internal state if it detects a parameter in the URL on mount.
-
-### Step 1: Define the Shared Route
-
-First, ensure your route configuration points both the list and the detail view to the same Shell component.
-
-```js
-Lego.route('/messaging', 'messaging-shell');
-Lego.route('/messaging/:id', 'messaging-shell');
-
-```
-
-### Step 2: Implement the Healing Logic
-
-Inside your `messaging-shell` component, use the `mounted()` hook to check for the presence of a parameter.
-
-```js
-Lego.define('messaging-shell', `
-  <div class="layout">
-    <aside class="sidebar">
-      <!-- List of threads -->
-    </aside>
-
-    <main id="chat-window">
-       <!-- Default content -->
-       <p>Select a conversation.</p>
-    </main>
-  </div>
-`, {
-  mounted() {
-    // Check if we arrived here via a deep-link (e.g., /messaging/123)
-    if (this.$route.params.id) {
-      // SURGICAL HEALING:
-      // Tell Lego to render the current URL into the local target.
-      // This pulls the 'messaging-details' fragment into the main window.
-      this.$go(window.location.pathname, '#chat-window').get();
-    }
-  }
-});
-
-```
-
-## Why This Pattern is Superior
-
-1.  **Explicit Control**: You decide exactly when and how the child fragment appears.
-    
-2.  **Layout Persistence**: The Sidebar and Header are rendered immediately. The user sees the "Shell" instantly, while the specific data fragment "pops" in a few milliseconds later. This improves the **Perceived Performance**.
-    
-3.  **No Nested Config Hell**: You don't need a complex tree of routes. The DOM structure of your shell defines the nesting naturally.
-    
-
-## Using Slots for Better Defaults
-
-You can use the native `<slot>` tag inside your target area to provide a better "Loading" or "Empty" experience before the healing happens.
-
-```html
-<main id="chat-window">
-  <slot>
-    <div class="skeleton-loader">Loading your message...</div>
-  </slot>
-</main>
-
-```
-
-## Summary
-
-"Self-Healing" is the bridge between a static website and a dynamic application. It ensures that your surgical routing works perfectly even on hard refreshes. By using the `mounted()` hook and the `$go` helper, your components become intelligent enough to manage their own internal layout based on the global URL state.

package/docs/router/history.md

@@ -1,69 +0,0 @@
-
-# Smart History & The Back Button
-
-One of the biggest frustrations in modern web development is "breaking the back button." When you use JavaScript to update only part of a page, the browser often doesn't realize a navigation event occurred. If the user hits "Back," they might be booted out of your app entirely.
-
-LegoDOM solves this using a system called **Smart History**. It ensures that even surgical, fragment-level updates are recorded and reversible.
-
-## How Traditional Routers Fail
-
-In a standard SPA, the router usually manages a single "current view." When you navigate:
-
-1.  The URL changes.
-    
-2.  The old component is destroyed.
-    
-3.  The new component is mounted.
-    
-
-Because the whole page (or the main outlet) is replaced, the browser's history stack is simple: Page A -> Page B. But in a complex layout like LinkedIn, you might have changed the chat window 5 times while the sidebar stayed exactly the same. Users expect the "Back" button to cycle through those chats, not take them back to the login screen.
-
-## The LegoDOM Approach: Target Tracking
-
-When you use `b-link` with a `b-target`, LegoDOM does two things simultaneously:
-
-1.  It updates the browser URL using the History API.
-    
-2.  It stores a "snapshot" of the target information in the history state.
-    
-
-### Inside the History State
-
-Every time a surgical swap happens, LegoDOM saves the target selector in the `history.state`. It looks something like this:
-
-```js
-// Internal representation
-history.pushState({ 
-  legoTargets: '#chat-window' 
-}, '', '/messaging/124');
-
-```
-
-## The "Popstate" Magic
-
-When a user hits the **Back** or **Forward** button, the browser triggers a `popstate` event. LegoDOM intercepts this event and checks if the incoming state contains `legoTargets`.
-
--   **If `legoTargets` exists:** LegoDOM performs a surgical swap. It takes the URL the browser is moving to and renders it _only_ into the specified target (e.g., `#chat-window`).
-    
--   **If no target exists:** It performs a global swap in the `<lego-router>`.
-    
-
-## Why This Matters for User Experience
-
-### 1. Persistence of Sibling State
-
-Because only the target is swapped during history navigation, your sidebar remains untouched. If the user had scrolled halfway down a list of 500 emails, they stay exactly at that scroll position as they hit "Back" and "Forward" to view different email details.
-
-### 2. Zero-Config History
-
-You don't have to write a single line of code to make the back button work. As long as you are using `b-link` and `b-target`, the framework handles the history reconciliation automatically.
-
-### 3. Deep Link Consistency
-
-Because the history state uses the same URLs as your standard links, a "Back" navigation and a "Hard Refresh" result in the same UI state (thanks to the Self-Healing logic we covered in the previous section).
-
-## Summary
-
-Smart History is the "glue" that makes a multi-fragment interface feel like a single, cohesive application. It respects the user's intent by making the browser's navigation tools work for specific parts of the page, not just the whole page.
-
-Next, we'll dive into the mechanics of how LegoDOM finds these targets in complex, nested DOM trees in **Target Resolver: Scoping and Logic**.

package/docs/router/index.md

@@ -1,73 +0,0 @@
-
-# LegoDOM vs Traditional SPA Router
-
-Traditional Single Page Application (SPA) routers (like React Router, Vue Router, or Angular's Router) rely on a **Centralized Configuration Tree**. As your project grows, this JSON or JavaScript object becomes a "source of truth" that is fragile, hard to maintain, and forces a rigid hierarchy on your UI.
-
-**LegoDOM breaks this pattern.**
-
-In Lego, we don't nest routes in a config file. Instead, we use the **URL as the Data Source** and the **DOM as the Layout Engine**.
-
-## The Shift in Thinking
-
-|Concept | Traditional SPAs | LegoDOM |
-|-----------|---------------|--------|
-| **Route Map** | Nested JSON Objects | Flat Component List |
-| **Nesting** | Defined in JS | Defined by your HTML structure |
-| **UI Updates** | "Nuclear" (Re-renders parent + children) | "Surgical" (Swaps exactly one fragment"|
-| **State** | Lost unless lifted to Global Store | Persists naturally in unaffected siblings |
-
-
-## The "Flat Route" Philosophy
-
-In a large project, your route definitions should remain a flat list of "Shells" (Layouts).
-
-```js
-// A flat list of structural shells
-Lego.route('/', 'home-shell');
-Lego.route('/messaging', 'messaging-shell');
-Lego.route('/messaging/:id', 'messaging-shell');
-Lego.route('/settings', 'settings-shell');
-
-```
-
-By pointing `/messaging` and `/messaging/:id` to the same **Shell**, you are telling Lego: _"I want the same layout for both URLs, but I'll decide how to fill the holes inside the component based on the URL parameters."_
-
-## Why This Scales
-
-In a LinkedIn-sized project, a traditional router would need to know that the `ChatWindow` is a child of the `MessagingLayout`. If you wanted to move that `ChatWindow` to the `HomeLayout`, you’d have to refactor your entire route tree.
-
-In Lego, you just change the **Target**. Because the components are agnostic, they don't care who their parent is. They just care about where the `b-target` tells them to go.
-
-### Defining with SFCs
-
-LegoDOM supports the use of Single File Components and this works seamlessly with the Router. You can define your Shell components via the `<template>` tag. This keeps our architectural "Shells" clean and readable.
-
-```html
-<style></style>
-<template b-id="home-shell">
-  <div class="layout">
-    <nav-bar></nav-bar>
-    <lego-router></lego-router> <!-- The global outlet -->
-  </div>
-</template>
-<script>
-  export default {
-    name: 'HomeShell'
-  }
-</script>
-```
-
-### Key Vocabulary for the Tutorial
-
-Throughout this guide, we will refer to three primary concepts:
-
-1.  **The Shell**: The high-level SFC that provides the grid, navigation, and sidebar.
-    
-2.  **The Fragment**: A self-contained SFC (like a chat thread or a profile header) that is surgically injected into a shell.
-    
-3.  **The Target**: A CSS selector, Tag Name, or ID that acts as the "destination hole" for a fragment.
-    
-
-## What's Next?
-
-We will move away from the theory and look at **Basic Routing**. We'll see how the `<lego-router>` element acts as the default gateway for your application and how Lego identifies which component to mount when the page first loads.

package/docs/router/resolver.md

@@ -1,74 +0,0 @@
-
-# 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 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.
-
-## The Problem with Global Selectors
-
-In traditional JavaScript, if you use `document.querySelector('#detail-view')`, the browser searches the entire page. This is fine for small sites, but in a "Web Component First" architecture, it causes two major issues:
-
-1.  **ID Collisions**: If you accidentally use the same ID in two different components, your link might update the wrong part of the page.
-    
-2.  **Tight Coupling**: Your sidebar link has to know the exact global ID of the main content area, making it harder to move components around.
-    
-
-## The Resolver Hierarchy
-
-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)
-
-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.
-
-### 2. Tag Name Resolution (The Web Component Way)
-
-If your target doesn't start with a `#`, Lego treats it as a **Component Tag Name**.
-
-```
-<!-- Lego looks for a <thread-view> tag nearby -->
-<a href="/chat/1" b-link b-target="thread-view">Open Chat</a>
-
-<thread-view></thread-view>
-
-```
-
-This is the most "Enterprise" way to build. It makes your HTML self-documenting. You aren't targeting a generic `div`; you are targeting a specific functional slot.
-
-### 3. Global ID Fallback
-
-If no local tag or element matches, the resolver expands its search to the entire `document` using ID selectors.
-
-```
-<!-- Lego looks for any element with id="global-sidebar" -->
-<a href="/menu" b-link b-target="#global-sidebar">Menu</a>
-
-```
-
-### 4. The Router Default
-
-If the resolver exhausts all options and still can't find the target, it defaults to the `<lego-router>`. This ensures that even if you make a typo in your target name, the user still sees the content (it just might take over the whole page instead of a small fragment).
-
-## Advanced: The Functional Target
-
-For highly dynamic UIs, `b-target` can even be a function or a dynamic expression.
-
-```
-<!-- Logic decides the target based on screen size -->
-<a href="/settings" b-link b-target="[[ isMobile ? '#main' : 'settings-pane' ]]">
-  Settings
-</a>
-
-```
-
-## Why This Matters
-
-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
-
-The Target Resolver turns string attributes into intelligent DOM navigation. It respects the boundaries of your Web Components while providing a robust fallback system.
-

package/docs/router/surgical-swaps.md

@@ -1,134 +0,0 @@
-# Surgical Swaps: Mastering b-target
-
-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.
-
-## 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 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.
-    
-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, 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.
-
-## 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/docs/tutorial/01-project-setup.md

@@ -1,152 +0,0 @@
-# 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>