npm - lego-dom - Versions diffs - 0.0.9 → 1.0.0 - Mend

lego-dom 0.0.9 → 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (166) hide show

package/docs/router/basic-routing.md ADDED Viewed

@@ -0,0 +1,103 @@
+# Basic Routing: The Global Outlet
+Before we dive into surgical swaps, we must understand how LegoJS handles the initial entry into your application. Every application needs a primary gateway—a place where the main content lives. In Lego, this is the `<lego-router>`.
+## The Entry Point
+In your `index.html`, you define a single custom element that acts as the "Master Outlet":
+```html
+<body>
+  <my-application-nav></my-application-nav>
+  <lego-router></lego-router>
+</body>
+```
+When the page loads, the LegoJS router looks at the current browser URL and searches its internal "Route Map" for a match.
+## Defining Your First Routes
+Routes are defined using the `Lego.route(path, componentName)` method. This creates a contract between a URL pattern and a Web Component.
+```js
+// Static Route
+Lego.route('/', 'home-page');
+// Dynamic Route (with parameters)
+Lego.route('/user/:id', 'profile-page');
+```
+### How the Matching Works
+1.  **The Match**: Lego uses Regex to compare the window location with your defined paths.
+2.  **The Injection**: If a match is found, Lego creates an instance of the associated component (e.g., `<home-page>`) and injects it into the `<lego-router>` tag.
+3.  **The Hydration**: The framework then "snaps" the component to life, initializing its state and running its `mounted()` lifecycle hook.
+## The Global Fallback
+If no route matches the current URL, LegoJS looks for a special fallback route. This is essential for handling **404 Not Found** states gracefully.
+```js
+Lego.route('*', 'not-found-page');
+```
+## Handling Parameters (`$params`)
+When you use a dynamic path like `/user/:id`, Lego automatically parses the URL and makes the data available to the component via the global `$route` object.
+In your component template:
+```html
+<template b-id="profile-page">
+  <h1>User Profile</h1>
+  <p>Viewing ID: {{ $route.params.id }}</p>
+</template>
+```
+In your component logic:
+```js
+mounted() {
+  const userId = this.$route.params.id;
+  this.fetchUserData(userId);
+}
+```
+**or**
+```html
+<!-- profile-page.lego -->
+<style>
+  /* nothing here for now */
+</style>
+<template>
+  <h1>User Profile</h1>
+  <p>Viewing ID: {{ $params.id }}</p>
+</template>
+<script>
+export default {
+  mounted() {
+    const userId = this.$route.params.id;
+    this.fetchUserData(userId);
+  }
+}
+</script>
+```
+## Summary
+The `<lego-router>` is the foundation. It handles the "Big Swaps" of your application. However, in a modern "Enterprise" application, we rarely want to swap the _entire_ page content every time the URL changes.
+In the next section, we will learn about **Surgical Swaps**, where we move beyond the global router and start updating specific pieces of the DOM using `b-target`.

package/docs/router/cold-entry.md ADDED Viewed

@@ -0,0 +1,91 @@
+# 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 LegoJS, 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.  LegoJS 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 ADDED Viewed

@@ -0,0 +1,69 @@
+# 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.
+LegoJS 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 LegoJS Approach: Target Tracking
+When you use `b-link` with a `b-target`, LegoJS 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, LegoJS 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. LegoJS intercepts this event and checks if the incoming state contains `legoTargets`.
+-   **If `legoTargets` exists:** LegoJS 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 LegoJS finds these targets in complex, nested DOM trees in **Target Resolver: Scoping and Logic**.

package/docs/router/index.md ADDED Viewed

@@ -0,0 +1,73 @@
+# 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.
+**LegoJS 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 ADDED Viewed

@@ -0,0 +1,74 @@
+# 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.
+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`, LegoJS 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**.
+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, 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.
+## 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 ADDED Viewed

@@ -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/index.html CHANGED Viewed

@@ -31,19 +31,11 @@
 </head>
 <body>
-  <h1>Lego + Vite Example</h1>
+  <app-navbar></app-navbar>
+  <lego-router id="app-outlet"></lego-router>
+  <aside id="outside-router"></aside>
-  <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>
-  <todo-list></todo-list>
-  <script type="module" src="/src/main.js"></script>
+  <script type="module" src="/src/app.js"></script>
 </body>
 </html>

package/examples/vite-app/package.json CHANGED Viewed

@@ -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 ADDED Viewed

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

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

@@ -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 ADDED Viewed

@@ -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 ADDED Viewed

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