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/guide/routing.md CHANGED Viewed

@@ -1,373 +1,273 @@
-# Routing
+# Surgical Routing
-Lego includes a built-in client-side router for building single-page applications.
+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.
-## Basic Setup
+## The Concept
-### 1. Add Router Outlet
+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.
-```html
-<lego-router></lego-router>
-```
+- **`b-target`**: "Where should this content go?"
+- **`b-link`**: "Should this update the URL history?"
-This is where your routed components will render.
+---
-### 2. Define Routes
+## 1. Declarative Routing
-```js
-Lego.route('/', 'home-page');
-Lego.route('/about', 'about-page');
-Lego.route('/contact', 'contact-page');
-```
+The most common way to route is using standard `<a>` tags enriched with Lego attributes.
-### 3. Create Page Components
+### `b-target`
+Specifies the CSS selector of the element to replace.
 ```html
-<template b-id="home-page">
-  <h1>Home</h1>
-  <p>Welcome to the homepage!</p>
-</template>
-<template b-id="about-page">
-  <h1>About</h1>
-  <p>Learn more about us.</p>
-</template>
+<!-- Swaps content into <div id="main-content"> -->
+<a href="/profile" b-target="#main-content">Go to Profile</a>
+<!-- Example of using route params in a template -->
+<main>
+  <blog-posts b-show="$route.params.section === 'posts'"></blog-posts>
+  <blog-authors b-show="$route.params.section === 'authors'"></blog-authors>
+</main>
 ```
-### 4. Add Navigation
+### `b-link`
+Controls browser history behavior.
+- `b-link` (or just `b-target`): Defaults to `true` (updates URL, pushes history).
+- `b-link="false"`: Does **not** update the URL. Great for tabs, modals, or side-panels.
 ```html
-<nav>
-  <a href="/" b-link>Home</a>
-  <a href="/about" b-link>About</a>
-  <a href="/contact" b-link>Contact</a>
-</nav>
+<!-- Updates URL to /settings, swaps #main -->
+<a href="/settings" b-target="#main">Settings</a>
-<lego-router></lego-router>
+<!-- Keeps URL same, just swaps the sidebar context -->
+<a href="/sidebar/tools" b-target="#sidebar" b-link="false">Open Tools</a>
 ```
-The `b-link` attribute hijacks clicks to prevent page reloads.
+### Deep Linking & Defaults
+If a user refreshes the page, surgical targets (like `#sidebar`) usually won't have content because the `b-target` click never happened.
-## Complete Example
+**The Golden Rule:** Always have a `<lego-router>` as your default "Main" outlet.
+When the page loads, Lego looks for `<lego-router>` to render the URL's matching component.
 ```html
-<!DOCTYPE html>
-<html>
-<head>
-  <title>My SPA</title>
-  <style>
-    nav { padding: 1rem; background: #f0f0f0; }
-    nav a { margin-right: 1rem; text-decoration: none; }
-    nav a.active { font-weight: bold; }
-  </style>
-</head>
 <body>
-  <nav>
-    <a href="/" b-link>Home</a>
-    <a href="/blog" b-link>Blog</a>
-    <a href="/about" b-link>About</a>
-  </nav>
+  <nav>...</nav>
-  <lego-router></lego-router>
-  <template b-id="home-page">
-    <h1>Welcome Home</h1>
-    <p>This is the homepage.</p>
-  </template>
+  <!-- Default Outlet: Renders /home, /about, etc. -->
+  <lego-router id="main-app"></lego-router>
-  <template b-id="blog-page">
-    <h1>Blog</h1>
-    <ul>
-      <li><a href="/blog/1" b-link>First Post</a></li>
-      <li><a href="/blog/2" b-link>Second Post</a></li>
-    </ul>
-  </template>
-  <template b-id="about-page">
-    <h1>About Us</h1>
-    <p>We build awesome things.</p>
-  </template>
-  <script src="https://unpkg.com/lego-dom/main.js"></script>
-  <script>
-    Lego.route('/', 'home-page');
-    Lego.route('/blog', 'blog-page');
-    Lego.route('/about', 'about-page');
-  </script>
+  <!-- Surgical Outlet: Only updated when specifically targeted -->
+  <aside id="sidebar"></aside>
 </body>
-</html>
 ```
-## Dynamic Routes
+## 2. The `$go` API
-Use `:param` syntax for URL parameters:
+For full programmatic control, use the globally available `$go` helper. It allows for surgical updates from your JavaScript logic.
-```js
-Lego.route('/user/:id', 'user-profile');
-Lego.route('/blog/:slug', 'blog-post');
-Lego.route('/category/:cat/item/:id', 'product-detail');
-```
+### Syntax
+`Lego.globals.$go(path, ...targets)`
-### Accessing Parameters
+- **path**: The URL to navigate to (e.g., `/user/1`).
+- **targets**: A list of selectors (e.g., `#main`, `#sidebar`). Passing nothing defaults to `lego-router`.
-Route parameters are available in `global.params`:
+### Methods
+The `$go` function returns an object with HTTP verb methods, primarily only `.get()` is relevant for routing, but others exist for consistency.
-```html
-<template b-id="user-profile">
-  <h1>User Profile</h1>
-  <p>User ID: {{ global.params.id }}</p>
-  <button @click="loadUser()">Load User</button>
-</template>
-<script>
-  Lego.define('user-profile',
-    Lego.registry['user-profile'].innerHTML, {
-    async loadUser() {
-      const userId = Lego.globals.params.id;
-      const user = await fetch(`/api/users/${userId}`).then(r => r.json());
-      this.username = user.name;
-    }
-  });
-</script>
-```
+```javascript
+// 1. Standard Navigation (pushes to history)
+Lego.globals.$go('/profile').get();
-## Programmatic Navigation
+// 2. Surgical Navigation (updates #sidebar, pushes to history)
+Lego.globals.$go('/widgets/clock', '#sidebar').get();
-Navigate programmatically using the History API:
+// 3. Silent Update (updates #modal, NO history change)
+// Pass `false` as the first argument to .get()
+Lego.globals.$go('/modals/login', '#modal').get(false);
+```
-```js
-// Navigate to a new route
-history.pushState({}, '', '/about');
-window.dispatchEvent(new PopStateEvent('popstate'));
+### Interactive Example: "The Shell"
+You can update **multiple** targets at once (future feature) or chain them.
+Commonly, you use `$go` inside your component logic:
-// Or in a component method:
-{
-  goToAbout() {
-    history.pushState({}, '', '/about');
-    window.dispatchEvent(new PopStateEvent('popstate'));
+```html
+<script>
+  export default {
+    methods: {
+      async loadUser() {
+        const userId = Lego.globals.$route.params.id; // Access in JS logic
+        const user = await fetch(`/api/users/${userId}`).then(r => r.json());
+        this.username = user.name;
+      },
+      openSettings() {
+        // Open settings in the sidebar without losing the main page context
+        this.global.$go('/settings-panel', '#sidebar').get(false);
+      }
+    }
   }
-}
+</script>
 ```
-## Route Middleware
+---
-Add middleware for authentication, logging, etc:
+## 3. Advanced Patterns
-```js
-// Define middleware function
-const authMiddleware = (params, globals) => {
-  if (!globals.isLoggedIn) {
-    history.pushState({}, '', '/login');
-    window.dispatchEvent(new PopStateEvent('popstate'));
-    return false; // Block navigation
-  }
-  return true; // Allow navigation
-};
-// Apply to routes
-Lego.route('/dashboard', 'dashboard-page', authMiddleware);
-Lego.route('/profile', 'profile-page', authMiddleware);
-```
+### The "Sidebar" Pattern
+Keep a persistent Main Content while swapping sidebars.
-### Middleware Example
+```html
+<nav>
+  <!-- Main Nav: Updates URL and main view -->
+  <a href="/dashboard" b-target="#main">Dashboard</a>
+  <a href="/files" b-target="#main">Files</a>
+</nav>
-```js
-// Logging middleware
-const logger = (params) => {
-  console.log('Navigating to:', params);
-  return true;
-};
+<main id="main">
+  <!-- Dashboard or Files render here -->
+</main>
-// Analytics middleware
-const analytics = (params) => {
-  if (window.gtag) {
-    gtag('event', 'page_view', { page_path: window.location.pathname });
-  }
-  return true;
-};
+<aside id="context-pane">
+  <!-- Context specific tools render here -->
+  <template b-id="user-profile">
+    <h1>User Profile</h1>
+    <p>User ID: {{ $route.params.id }}</p>
+    <button @click="loadUser()">Load User</button>
+  </template>
+</aside>
-// Apply
-Lego.route('/products/:id', 'product-page', (params, globals) => {
-  logger(params);
-  analytics(params);
-  return true;
-});
+<!-- Inside Dashboard Component -->
+<button onclick="Lego.globals.$go('/tools/chart-config', '#context-pane').get(false)">
+  Configure Chart
+</button>
 ```
-## Active Link Styling
+### The "Modal" Pattern
+Render a route into a modal dialog container.
-Style active navigation links:
+```html
+<dialog id="modal-container"></dialog>
-```js
-// Update active class on navigation
-window.addEventListener('popstate', () => {
-  document.querySelectorAll('[b-link]').forEach(link => {
-    const isActive = link.getAttribute('href') === window.location.pathname;
-    link.classList.toggle('active', isActive);
-  });
-});
+<a href="/login" b-target="#modal-container"
+   onclick="document.getElementById('modal-container').showModal()">
+   Login
+</a>
 ```
-## 404 / Not Found
+### The "Persistent Layout" Pattern (The Holy Grail)
+This is where LegoDOM outshines traditional routers. You can have static sidebars that **never** reload, while the center content changes dynamically.
-Handle unknown routes:
+```html
+<body>
+  <!-- LEFT: Never reloads. Keeps scroll position & expanded folders. -->
+  <aside id="static-left">
+    <file-tree></file-tree>
+  </aside>
-```js
-// Define all your routes
-Lego.route('/', 'home-page');
-Lego.route('/about', 'about-page');
+  <!-- CENTER: The main router outlet -->
+  <lego-router id="main-content"></lego-router>
-// Catch-all for 404
-const matchRoute = () => {
-  const path = window.location.pathname;
-  const routes = ['/', '/about']; // Your known routes
-  if (!routes.includes(path)) {
-    // Show 404
-    document.querySelector('lego-router').innerHTML = '<not-found></not-found>';
-  }
-};
-window.addEventListener('popstate', matchRoute);
-matchRoute(); // Initial check
+  <!-- RIGHT: Context panel for tools/details -->
+  <aside id="static-right"></aside>
+</body>
 ```
+*   **Main Links:** `<a href="/page" b-target="#main-content">`
+*   **Tool Links:** `<a href="/tool" b-target="#static-right">`
-## Nested Routes
+---
-While Lego doesn't have built-in nested routing, you can implement it:
+## 4. Deep Routing Strategies
-```html
-<template b-id="blog-layout">
-  <aside>
-    <a href="/blog/posts" b-link>Posts</a>
-    <a href="/blog/authors" b-link>Authors</a>
-  </aside>
-  <main>
-    <blog-posts b-if="global.params.section === 'posts'"></blog-posts>
-    <blog-authors b-if="global.params.section === 'authors'"></blog-authors>
-  </main>
-</template>
-```
+When handling deep routes like `/customers/:id/orders/:orderId`, you have two architectural choices.
-```js
-Lego.route('/blog/:section', 'blog-layout');
-```
+### Option A: The Shell Strategy (Self-Healing)
+Map everything to a single "Shell" component. The Shell determines what to show in its sub-outlets based on the URL params.
-## Query Strings
+*   **Pros:** Highly surgical. The Shell never re-renders, only its children do.
+*   **Cons:** Requires logic in `mounted()` to "heal" the state on page load.
-Access query parameters using URLSearchParams:
+```javascript
+// Route Configuration
+Lego.route('/customers/:id', 'customers-shell');
+Lego.route('/customers/:id/orders/:orderId', 'customers-shell');
-```js
-{
-  mounted() {
-    const params = new URLSearchParams(window.location.search);
-    this.searchQuery = params.get('q') || '';
-    this.page = parseInt(params.get('page')) || 1;
+// Component Logic (Self-Healing)
+mounted() {
+  if (this.$route.params.orderId) {
+    this.$go(window.location.pathname, '#details-pane').get();
   }
 }
 ```
-Example: `/search?q=legojs&page=2`
-## Hash vs History Mode
+### Option B: The Page Strategy (Component Nesting)
+Map deep routes to specific "Page" components. Each page imports and wraps itself in a shared Layout.
-Lego uses History API (pushState) by default, giving you clean URLs:
+*   **Pros:** Simpler logic. No "healing" code required.
+*   **Cons:** The Layout is technically re-created on every route change (though diffing makes it cheap).
-✅ `/about`
-✅ `/user/123`
-✅ `/blog/my-post`
-Not hash-based:
-❌ `#/about`
-❌ `#/user/123`
-### Server Configuration
-For clean URLs to work, configure your server to serve `index.html` for all routes:
-**nginx:**
-```nginx
-location / {
-  try_files $uri $uri/ /index.html;
-}
+```javascript
+// Route Configuration
+Lego.route('/customers/:id/orders/:orderId', 'order-details-page');
 ```
-**Apache (.htaccess):**
-```apache
-RewriteEngine On
-RewriteCond %{REQUEST_FILENAME} !-f
-RewriteCond %{REQUEST_FILENAME} !-d
-RewriteRule ^ index.html [L]
+```html
+<!-- order-details-page.lego -->
+<template>
+  <customers-layout>
+    <order-info id="{{ $route.params.orderId }}"></order-info>
+  </customers-layout>
+</template>
 ```
-**Node.js/Express:**
-```js
-app.get('*', (req, res) => {
-  res.sendFile(path.join(__dirname, 'index.html'));
-});
-```
+---
-## Best Practices
+## 5. Middleware & Guards
-### 1. Centralize Route Definitions
+Middleware runs **before** the surgical swap happens. It### Accessing Parameters
+Route parameters are available directly via `$route.params` in templates.
-```js
-// routes.js
-const routes = {
-  '/': 'home-page',
-  '/blog': 'blog-page',
-  '/blog/:slug': 'blog-post',
-  '/user/:id': 'user-profile',
-  '/about': 'about-page'
-};
+> **Note:** `$route` is a global helper available in all templates.
-Object.entries(routes).forEach(([path, component]) => {
-  Lego.route(path, component);
-});
-```
+```javascript
+/*
+ * Middleware Signature:
+ * (params: Object, globals: Object) => boolean | Promise<boolean>
+ * Return `true` to allow navigation, `false` to block.
+ */
-### 2. Loading States
+// Example: Auth Guard
+const requireAuth = (params, globals) => {
+  if (!globals.user) {
+    // Redirect to login using surgical routing!
+    globals.$go('/login', '#main').get();
+    return false; // Stop original navigation
+  }
+  return true;
+};
-```html
-<template b-id="user-profile">
-  <div b-if="loading">Loading...</div>
-  <div b-if="!loading">
-    <h1>{{ user.name }}</h1>
-    <p>{{ user.bio }}</p>
-  </div>
-</template>
+Lego.route('/admin', 'admin-panel', requireAuth);
 ```
-### 3. Error Handling
-```js
-{
-  async loadData() {
-    this.loading = true;
-    this.error = null;
-    try {
-      const data = await fetch('/api/data').then(r => r.json());
-      this.data = data;
-    } catch (err) {
-      this.error = 'Failed to load data';
-    } finally {
-      this.loading = false;
-    }
-  }
-}
-```
+## 5. Smart History
-## Limitations
+Lego's router is "History Aware".
+When you use `b-target`, Lego stores the target selectors in the browser's History State.
-- No nested router outlets (single level only)
-- No route guards (use middleware instead)
-- No automatic scroll restoration
-- Routes must be defined upfront (not lazy-loaded)
+**What this means:**
+1. You click "Open Sidebar" (Surgical update to `#sidebar`).
+2. You click "Home" (Main update to `#main`).
+3. You click **Back**.
+4. Lego automatically knows to reverse the "Home" navigation.
+5. You click **Back** again.
+6. Lego knows the previous state was a surgical update to `#sidebar` and restores it correctly!
-For complex routing needs, consider integrating a dedicated router library.
+## Summary Table
-## Next Steps
+| Feature | Code | Description |
+| :--- | :--- | :--- |
+| **Standard Link** | `<a href="/x">` | Standard browser navigation (full reload). |
+| **SPA Link** | `<a href="/x" b-target>` | Default SPA nav. Swaps `<lego-router>`. |
+| **Surgical Link** | `<a href="/x" b-target="#id">` | Swaps content of `#id`. Updates URL. |
+| **Silent Link** | `... b-link="false">` | Swaps content. **No** URL update. |
+| **JS Nav** | `$go('/x').get()` | Programmatic navigation. |
+| **Silent JS** | `$go('/x').get(false)` | Programmatic silent swap. |
-- See [routing examples](/examples/routing)
-- Learn about [lifecycle hooks](/guide/lifecycle)
-- Explore [state management patterns](/guide/reactivity)

package/docs/guide/sfc.md CHANGED Viewed

@@ -215,7 +215,7 @@ Contains your component's HTML markup with Lego directives:
 ```html
 <template>
   <h1>{{ title }}</h1>
-  <p b-if="showContent">{{ content }}</p>
+  <p b-show="showContent">{{ content }}</p>
   <ul>
     <li b-for="item in items">{{ item }}</li>
   </ul>

package/docs/guide/templating.md CHANGED Viewed

@@ -343,8 +343,8 @@ If a calculation is expensive, cache it:
 ### Show/Hide Based on Condition
 ```html
-<p b-if="user">Welcome, {{ user.name }}!</p>
-<p b-if="!user">Please log in</p>
+<p b-show="user">Welcome, {{ user.name }}!</p>
+<p b-show="!user">Please log in</p>
 ```
 ### List with Index

package/docs/index.md CHANGED Viewed

@@ -57,11 +57,35 @@ features:
     details: Battle-tested patterns from Vue and React, adapted for pure Web Components. No framework lock-in.
 ---
-## Quick Example
+## Components & Naming
+How you name your components depends on how you use Lego:
+### 1. Vite / Build Tools (Recommended)
+**Convention over Configuration.** The filename *is* the tag name.
+- `user-card.lego` → `<user-card></user-card>`
+- `app-nav.lego` → `<app-nav></app-nav>`
+You do not need `b-id` inside `.lego` files; the build system handles registration automatically.
+### 2. CDN / Script Tags
+Since there are no files, you must explicitly name your components using the `b-id` attribute on the `<template>` tag.
+```html
+<!-- Only needed for CDN usage -->
+<template b-id="user-profile">
+  <h1>User Profile</h1>
+</template>
+```
+## Quick Start (CDN)
 ```html
 <!-- Define a component -->
-<template b-id="counter-button">
+<template b-id="counter-button" b-data="{
+  title: 'My counter',
+  count: 0
+}">
   <style>
     self {
       display: block;
@@ -80,13 +104,25 @@ features:
 </template>
 <!-- Use it -->
-<counter-button b-data="{ title: 'My Counter', count: 0 }"></counter-button>
+<counter-button b-data="{ title: 'Override b-data title' }"></counter-button>
 <script src="https://unpkg.com/lego-dom/main.js"></script>
+<script>
+  // Complete the initialization
+  Lego.init();
+</script>
 ```
 That's it. No build step, no npm, no configuration.
+> [!IMPORTANT]
+> **Why call `Lego.init()`?**
+> While `Lego.define()` will "snap" your components into the page immediately, you must call `Lego.init()` to start the background engine. Without it:
+> - **Reactivity** to data changes won't work.
+> - **Mustaches** (<code v-pre>{{...}}</code>) outside of components won't hydrate.
+> - **Single Page Routing** won't be activated.
+> - **New components** added to the DOM dynamically won't be auto-initialized.
 ## Why Lego?
 **For small projects**, you get reactive components without the overhead of a full framework.
@@ -119,8 +155,6 @@ Lego works in all modern browsers that support:
 This includes Chrome 63+, Firefox 63+, Safari 11.1+, and Edge 79+.
 ## Community
-- 📖 [Documentation](https://rayattack.github.io/Lego/)
-- 💬 [Discussions](https://github.com/rayattack/Lego/discussions)
-- 🐛 [Issue Tracker](https://github.com/rayattack/Lego/issues)
+- 💬 [Discussions](https://github.com/rayattack/LegoDOM/discussions)
+- 🐛 [Issue Tracker](https://github.com/rayattack/LegoDOM/issues)
 - 📦 [npm Package](https://www.npmjs.com/package/lego-dom)