npm - lego-dom - Versions diffs - 1.3.4 → 1.5.0 - Mend

lego-dom 1.3.4 → 1.5.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 (93) hide show

package/CHANGELOG.md +72 -1
package/main.js +48 -17
package/main.min.js +2 -2
package/package.json +1 -1
package/parse-lego.js +2 -2
package/vite-plugin.js +0 -14
package/.github/workflows/deploy-docs.yml +0 -56
package/.legodom +0 -87
package/docs/.vitepress/config.js +0 -161
package/docs/api/config.md +0 -95
package/docs/api/define.md +0 -58
package/docs/api/directives.md +0 -50
package/docs/api/globals.md +0 -29
package/docs/api/index.md +0 -30
package/docs/api/lifecycle.md +0 -40
package/docs/api/route.md +0 -37
package/docs/api/vite-plugin.md +0 -58
package/docs/contributing/01-welcome.md +0 -38
package/docs/contributing/02-registry.md +0 -133
package/docs/contributing/03-batcher.md +0 -110
package/docs/contributing/04-reactivity.md +0 -87
package/docs/contributing/05-caching.md +0 -59
package/docs/contributing/06-init.md +0 -136
package/docs/contributing/07-observer.md +0 -72
package/docs/contributing/08-snap.md +0 -140
package/docs/contributing/09-diffing.md +0 -69
package/docs/contributing/10-studs.md +0 -78
package/docs/contributing/11-scanner.md +0 -117
package/docs/contributing/12-render.md +0 -138
package/docs/contributing/13-directives.md +0 -243
package/docs/contributing/14-events.md +0 -57
package/docs/contributing/15-router.md +0 -57
package/docs/contributing/16-state.md +0 -47
package/docs/contributing/17-legodom.md +0 -48
package/docs/contributing/index.md +0 -24
package/docs/examples/form.md +0 -42
package/docs/examples/index.md +0 -104
package/docs/examples/routing.md +0 -409
package/docs/examples/sfc-showcase.md +0 -34
package/docs/examples/todo-app.md +0 -383
package/docs/guide/cdn-usage.md +0 -354
package/docs/guide/components.md +0 -418
package/docs/guide/directives.md +0 -539
package/docs/guide/directory-structure.md +0 -248
package/docs/guide/faq.md +0 -210
package/docs/guide/getting-started.md +0 -262
package/docs/guide/index.md +0 -88
package/docs/guide/lifecycle.md +0 -525
package/docs/guide/quick-start.md +0 -49
package/docs/guide/reactivity.md +0 -415
package/docs/guide/routing.md +0 -334
package/docs/guide/server-side.md +0 -134
package/docs/guide/sfc.md +0 -464
package/docs/guide/templating.md +0 -388
package/docs/index.md +0 -160
package/docs/public/logo.svg +0 -17
package/docs/router/basic-routing.md +0 -103
package/docs/router/cold-entry.md +0 -91
package/docs/router/history.md +0 -69
package/docs/router/index.md +0 -73
package/docs/router/resolver.md +0 -74
package/docs/router/surgical-swaps.md +0 -134
package/docs/tutorial/01-project-setup.md +0 -152
package/docs/tutorial/02-your-first-component.md +0 -226
package/docs/tutorial/03-adding-routes.md +0 -279
package/docs/tutorial/04-multi-page-app.md +0 -329
package/docs/tutorial/05-state-and-globals.md +0 -285
package/docs/tutorial/index.md +0 -40
package/examples/vite-app/README.md +0 -71
package/examples/vite-app/index.html +0 -42
package/examples/vite-app/package.json +0 -18
package/examples/vite-app/src/app.css +0 -3
package/examples/vite-app/src/app.js +0 -29
package/examples/vite-app/src/components/app-navbar.lego +0 -34
package/examples/vite-app/src/components/customers/customer-details.lego +0 -24
package/examples/vite-app/src/components/customers/customer-orders.lego +0 -21
package/examples/vite-app/src/components/customers/order-list.lego +0 -55
package/examples/vite-app/src/components/greeting-card.lego +0 -41
package/examples/vite-app/src/components/sample-component.lego +0 -75
package/examples/vite-app/src/components/shells/customers-shell.lego +0 -21
package/examples/vite-app/src/components/side-menu.lego +0 -46
package/examples/vite-app/src/components/todo-list.lego +0 -239
package/examples/vite-app/src/components/widgets/user-card.lego +0 -27
package/examples/vite-app/vite.config.js +0 -22
package/tests/error.test.js +0 -74
package/tests/main.test.js +0 -103
package/tests/memory.test.js +0 -68
package/tests/monitoring.test.js +0 -74
package/tests/naming.test.js +0 -74
package/tests/parse-lego.test.js +0 -65
package/tests/security.test.js +0 -67
package/tests/server.test.js +0 -114
package/tests/syntax.test.js +0 -67

package/docs/guide/routing.md DELETED Viewed

@@ -1,334 +0,0 @@
-# Surgical Routing
-**Stop rebuilding your entire page just to change one div.**
-LegoDOM's router is different. It doesn't have a single "Root Outlet". Instead, **any element** can be a router target. This allows you to build **Persistent Layouts** (like Sidebars, Music Players, or Chat Windows) that never reload or lose state while the user navigates.
-::: tip 🚀 Just Want to Navigate Between Pages?
-Here's the quick answer:
-**1. Define routes in `app.js`:**
-```javascript
-Lego.route('/', 'home-page');
-Lego.route('/login', 'login-page');
-Lego.route('/dashboard', 'dashboard-page');
-```
-**2. Navigate with links:**
-```html
-<a href="/login" b-link>Go to Login</a>
-```
-**3. Or navigate with JavaScript:**
-```javascript
-this.$go('/login').get();
-```
-That's it! For the full tutorial, see [Adding Routes](/tutorial/03-adding-routes).
-:::
-## Quick Reference
-| I want to... | Code |
-|--------------|------|
-| Define a route | `Lego.route('/path', 'component-name')` |
-| Link to a page | `<a href="/path" b-link>Click</a>` |
-| Navigate via JS | `this.$go('/path').get()` |
-| Get URL params | `this.$route.params.id` |
-| Update only one div | `<a href="/x" b-target="#myDiv">` |
-| Navigate without URL change | `this.$go('/x').get(false)` |
----
-## The Architecture: "The Persistent Shell"
-The best way to use LegoDOM is to define a static "Shell" that holds your persistent tools, and standard outlets for your content.
-```html
-<body>
-  <!-- 1. The Shell (Sidebar): Never reloads. Keeps scroll pos & draft state. -->
-  <aside id="sidebar">
-    <file-tree></file-tree>
-  </aside>
-  <!-- 2. The Stage (Main Content): This changes when URL changes. -->
-  <lego-router id="stage"></lego-router>
-  <!-- 3. The Context (Right Panel): Tools based on selection. -->
-  <aside id="tools"></aside>
-</body>
-```
-Then, you simply tell links *where* to render their content:
-```html
-<!-- Updates component in #stage (Default URL navigation) -->
-<a href="/dashboard" b-target="#stage">Dashboard</a>
-<!-- Updates component in #tools (Keeps URL sync, but only touches right panel) -->
-<a href="/tools/settings" b-target="#tools">Settings</a>
-```
-This feels like a native app. The Sidebar doesn't flicker. The scroll position isn't lost.
----
-## 1. Declarative Routing
-The most common way to route is using standard `<a>` tags enriched with Lego attributes.
-### `b-target`
-Specifies the CSS selector of the element to replace.
-```html
-<!-- 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>
-```
-### `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
-<!-- Updates URL to /settings, swaps #main -->
-<a href="/settings" b-target="#main">Settings</a>
-<!-- Keeps URL same, just swaps the sidebar context -->
-<a href="/sidebar/tools" b-target="#sidebar" b-link="false">Open Tools</a>
-```
-### 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.
-**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
-<body>
-  <nav>...</nav>
-  <!-- Default Outlet: Renders /home, /about, etc. -->
-  <lego-router id="main-app"></lego-router>
-  <!-- Surgical Outlet: Only updated when specifically targeted -->
-  <aside id="sidebar"></aside>
-</body>
-```
-## 2. The `$go` API
-For full programmatic control, use the globally available `$go` helper. It allows for surgical updates from your JavaScript logic.
-### Syntax
-`Lego.globals.$go(path, ...targets)`
-- **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`.
-### Methods
-The `$go` function returns an object with HTTP verb methods, primarily only `.get()` is relevant for routing, but others exist for consistency.
-```javascript
-// 1. Standard Navigation (pushes to history)
-Lego.globals.$go('/profile').get();
-// 2. Surgical Navigation (updates #sidebar, pushes to history)
-Lego.globals.$go('/widgets/clock', '#sidebar').get();
-// 3. Silent Update (updates #modal, NO history change)
-// Pass `false` as the first argument to .get()
-Lego.globals.$go('/modals/login', '#modal').get(false);
-```
-### Interactive Example: "The Shell"
-You can update **multiple** targets at once (future feature) or chain them.
-Commonly, you use `$go` inside your component logic:
-```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>
-```
----
-## 3. Advanced Patterns
-### The "Sidebar" Pattern
-Keep a persistent Main Content while swapping sidebars.
-```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>
-<main id="main">
-  <!-- Dashboard or Files render here -->
-</main>
-<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>
-<!-- Inside Dashboard Component -->
-<button onclick="Lego.globals.$go('/tools/chart-config', '#context-pane').get(false)">
-  Configure Chart
-</button>
-```
-### The "Modal" Pattern
-Render a route into a modal dialog container.
-```html
-<dialog id="modal-container"></dialog>
-<a href="/login" b-target="#modal-container"
-   onclick="document.getElementById('modal-container').showModal()">
-   Login
-</a>
-```
-### 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.
-```html
-<body>
-  <!-- LEFT: Never reloads. Keeps scroll position & expanded folders. -->
-  <aside id="static-left">
-    <file-tree></file-tree>
-  </aside>
-  <!-- CENTER: The main router outlet -->
-  <lego-router id="main-content"></lego-router>
-  <!-- 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">`
----
-## 4. Deep Routing Strategies
-When handling deep routes like `/customers/:id/orders/:orderId`, you have two architectural choices.
-### 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.
-*   **Pros:** Highly surgical. The Shell never re-renders, only its children do.
-*   **Cons:** Requires logic in `mounted()` to "heal" the state on page load.
-```javascript
-// Route Configuration
-Lego.route('/customers/:id', 'customers-shell');
-Lego.route('/customers/:id/orders/:orderId', 'customers-shell');
-// Component Logic (Self-Healing)
-mounted() {
-  if (this.$route.params.orderId) {
-    this.$go(window.location.pathname, '#details-pane').get();
-  }
-}
-```
-### Option B: The Page Strategy (Component Nesting)
-Map deep routes to specific "Page" components. Each page imports and wraps itself in a shared Layout.
-*   **Pros:** Simpler logic. No "healing" code required.
-*   **Cons:** The Layout is technically re-created on every route change (though diffing makes it cheap).
-```javascript
-// Route Configuration
-Lego.route('/customers/:id/orders/:orderId', 'order-details-page');
-```
-```html
-<!-- order-details-page.lego -->
-<template>
-  <customers-layout>
-    <order-info id="[[ $route.params.orderId ]]"></order-info>
-  </customers-layout>
-</template>
-```
----
-## 5. Middleware & Guards
-Middleware runs **before** the surgical swap happens. It### Accessing Parameters
-Route parameters are available directly via `$route.params` in templates.
-> **Note:** `$route` is a global helper available in all templates.
-```javascript
-/*
- * Middleware Signature:
- * (params: Object, globals: Object) => boolean | Promise<boolean>
- * Return `true` to allow navigation, `false` to block.
- */
-// 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;
-};
-Lego.route('/admin', 'admin-panel', requireAuth);
-```
-## 5. Smart History
-Lego's router is "History Aware".
-When you use `b-target`, Lego stores the target selectors in the browser's History State.
-**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!
-## Summary Table
-| 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. |

package/docs/guide/server-side.md DELETED Viewed

@@ -1,134 +0,0 @@
-# Server-Side Architecture
-LegoDOM is designed to play nicely with backend frameworks like **Heaven**, **Django**, **Rails**, or **Go**.
-Unlike typical SPAs that require a massive build step, LegoDOM can fetch components **on-demand** from your server. This gives you the routing simplicity of a backend with the interactivity of a frontend framework.
-## The Auto-Loader Pattern
-Instead of bundling every component `users-list`, `chat-widget`, `billing-modal` into one big `app.js` file, you can load them lazily.
-Configure the `loader` hook in your main entry file:
-```javascript
-Lego.init(document.body, {
-  loader: (tagName) => `/components/${tagName}.lego`
-});
-```
-Now, your HTML can just use tags that haven't been defined yet:
-```html
-<!-- index.html (Server Rendered) -->
-<h1>Dashboard</h1>
-<!-- LegoDOM sees this, fetches /components/user-feed.lego, and upgrades it -->
-<user-feed></user-feed>
-```
-## Power Mode: Authentication & State
-Often you need to pass **Authentication Tokens** or **Global State** to the server to get a personalized component.
-Return a `Promise` from your loader to take full control of the fetch:
-```javascript
-Lego.init(document.body, {
-  loader: async (tagName) => {
-    const token = localStorage.getItem('jwt');
-    const response = await fetch(`/components/${tagName}`, {
-      headers: {
-        'Authorization': `Bearer ${token}`,
-        'X-Theme': Lego.globals.theme
-      }
-    });
-    if (!response.ok) return null;
-    return await response.text(); // Return the SFC content
-  }
-});
-```
-## Server-Side State Injection
-Since the server generates the `.lego` file, it can inject data before sending it to the browser.
-**Example (Backend Pseudocode):**
-```python
-# GET /components/user-card ("Flask-like" syntax)
-@app.route('/components/user-card')
-def get_user_card():
-    user = db.get_current_user()
-    # We bake the data right into the template!
-    return f"""
-    <template>
-      <div class="card">
-        <h2>[[ name ]]</h2>
-        <p>Balance: $[[ balance ]]</p>
-      </div>
-    </template>
-    <script>
-       export default {
-         name: "{user.name}",
-         balance: {user.balance}
-       }
-    </script>
-    """
-```
-The browser receives a component that **already has the data**. No second API call needed!
-## Runtime Components
-If you fetch component code manually (e.g. via WebSockets or a custom pipeline), you can register it using `Lego.defineSFC`:
-```javascript
-socket.on('component_update', (msg) => {
-  // msg.code contains the <template>... string
-  Lego.defineSFC(msg.code, msg.name + '.lego');
-});
-```
-```
-## Production Considerations
-### 1. Error Handling
-What if the server returns a 404 or 500? Your `loader` should handle this gracefully so the user isn't stuck with a blank screen.
-```javascript
-loader: async (tagName) => {
-  try {
-    const res = await fetch(`/components/${tagName}.lego`);
-    if (!res.ok) {
-      console.error(`Component ${tagName} failed: ${res.status}`);
-      // Fallback to a generic error component
-      return `<template><div class="error">Failed to load ${tagName}</div></template>`;
-    }
-    return await res.text();
-  } catch (err) {
-    return `<template><div class="error">Network Error</div></template>`;
-  }
-}
-```
-### 2. Caching Strategy
-LegoDOM caches the *compiled class* of a component once loaded. It does **not** re-fetch the `.lego` file for every instance.
-However, if you want browser-level caching for the HTTP requests, ensure your server sends correct headers:
-```http
-Cache-Control: public, max-age=3600, immutable
-```
-### 3. Preloading
-If you know a user is about to visit a page (e.g. hovering a link), you can preload the component SFC:
-```javascript
-const preload = (tagName) => {
-  // Just calling the loader puts it in the browser's fetch cache
-  Lego.config.loader(tagName);
-};
-```