lego-dom 0.0.8 → 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,44 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [1.0.0] - 2026-01-10
+
+**The Launch Release!** 🚀
+LegoDOM moves out of beta with a finalized API, robust routing, and a hybrid rendering engine.
+
+### 🌟 Major features
+
+- **Surgical Routing:** Introduced a groundbreaking `b-target` attribute that allows any link to update any part of the page without a full reload.
+    - **Smart History:** The router now tracks surgical updates in `history.state`, correctly restoring "fragment" states when using the Back/Forward buttons.
+    - **Persistent Layouts:** Support for "Holy Grail" layouts where sidebars never reload or lose state (scroll position, inputs) while main content changes.
+- **Hybrid Rendering Engine:**
+    - **Light DOM Support:** The engine now hydrates `{{mustaches}}` in `index.html` and Light DOM slots, not just inside Shadow Roots.
+    - **Global Reactivity:** Components now automatically broadcast global state changes (like URL params) to all active subscribers.
+    - **Optimized Updates:** A dependency tracking system ensures only components that *use* global state are re-rendered.
+- **Developer Experience (DX):**
+    - **Automatic Injection:** `$route` and `$go` are now injected into every component's script scope (`this.$route`, `this.$go`), removing the need for `Lego.globals.xxx`.
+    - **Cleaner Templates:** Template expressions now support `$route` directly (`{{ $route.params.id }}`) without `global.` prefix.
+    - **HMR 2.0:** The Vite plugin now correctly handles adding/deleting `.lego` files and performs smarter hot updates.
+
+### ⚡ Improvements
+
+- **Router:**
+    - Exposed `$go(path, ...targets).get()` for programmatic surgical navigation.
+    - Fixed `TypeError` where `$go` was not found in component scopes.
+    - Support for multiple URL parameters (e.g., `/customers/:id/orders/:orderId`).
+    - Defaults `b-link` to `true` (always push history) unless explicitly set to `false`.
+- **Core:**
+    - `Lego.init()` is now required to start the engine, allowing for explicit control over startup timing.
+    - `e.composedPath()` is used for event delegation, allowing links inside Shadow DOM to trigger the global router.
+    - Fixed `b-sync` losing reactivity inside `b-for` loops.
+    - Fixed hydration of attributes like `href="/user/{{id}}"`.
+- **Docs:**
+    - Complete overhaul of Routing guide with "Surgical Swaps", "Deep Linking", and "Self-Healing" patterns.
+    - Clarified component naming conventions (Filename for Vite vs. `b-id` for CDN).
+
+### 🐛 Bug Fixes
+
+- Fixed "Literal Mustaches" appearing in `href` and text content on initial load.
+- Fixed Deep Linking where hitting Refresh on a sub-route would render an empty shell (addressed via Self-Healing pattern).
+- Fixed an issue where `Lego.globals` changes triggered a full re-render of unrelated components.

package/README.md

@@ -1,466 +1,83 @@
-# LegoJS
+# Lego 🧱
 
-LegoJS is a tiny, zero-dependency JavaScript library for building reactive Web Components directly in the browser.
+**The tiny, zero-dependency library for building reactive Web Components.**
 
-The goal of LegoJS is **mental model simplicity**:
+Lego embraces the web platform. It turns standard HTML `<template>` tags into reactive, encapsulated custom elements with zero build steps required.
 
-* No virtual DOM
-* No compilation step required
-* No JSX
-* No framework-specific syntax to learn
-
-You write **HTML**, add a few **directives**, and LegoJS takes care of reactivity and updates.
-
-This README is intentionally designed so that a developer can understand **everything they need** about LegoJS by reading this file alone.
-
----
-
-## Installation
-
-The package name on npm is **`lego-dom`** (the name `legojs` was already taken).
-
-```bash
-npm install lego-dom
-```
-
-Or include it directly in the browser:
-
-```html
-<script src="node_modules/lego-dom/main.js"></script>
-```
-
-Once loaded, `Lego` is available globally.
-
----
-
-## The Mental Model
-
-Think of LegoJS like real Lego blocks:
-
-* **Templates** define how a block looks
-* **Studs** define the data attached to a block
-* **Directives** snap data to the DOM
-* **Changes to data automatically update the DOM**
-
-There is no mounting, diffing, or reconciliation engine.
-
-You change JavaScript objects → LegoJS updates the DOM.
-
----
-
-## Defining a Component (Block)
-
-A component is defined using a standard HTML `<template>` with a `b-id`.
-
-```html
-<template b-id="hello-card">
-  <style>
-    self {
-      display: block;
-      padding: 1rem;
-      border: 1px solid #ccc;
-    }
-  </style>
-
-  <h2>Hello {{ name }}</h2>
-  <button @click="count++">Clicked {{ count }} times</button>
-</template>
-```
-
-Use the component in HTML:
-
-```html
-<hello-card b-data="{ name: 'Ahmed', count: 0 }"></hello-card>
-```
-
----
-
-## Reactive State (`studs`)
-
-Each component has a reactive state object internally called **studs**.
-
-* Defined via `b-data` or component logic
-* Implemented using JavaScript `Proxy`
-* Any mutation automatically schedules a re-render
-
-```html
-<button @click="count++"></button>
-```
-
-No setters. No actions. No reducers.
-
-Just mutate data.
-
----
-
-## Templating (`{{ }}`)
-
-Text interpolation works in:
-
-* Text nodes
-* Attributes
-* Class names
-
-```html
-<p>Hello {{ user.name }}</p>
-<img src="/avatars/{{ user.id }}.png">
-```
-
-Expressions are plain JavaScript.
-
----
-
-## Event Handling (`@event`)
-
-Use `@` followed by any DOM event.
-
-```html
-<button @click="submit()">Submit</button>
-```
-
-The expression runs in the component’s state scope.
-
-You also have access to:
-
-* `event` – the native DOM event
-* `$emit(name, detail)` – dispatch custom events
-* `$element` – the host custom element
-
----
-
-## Conditional Rendering (`b-if`)
-
-```html
-<p b-if="isLoggedIn">Welcome back</p>
-```
-
-When the expression is falsy, the element is hidden via `display: none`.
-
----
-
-## Lists (`b-for`)
-
-Render lists using `b-for`:
-
-```html
-<ul>
-  <li b-for="todo in todos">
-    <input type="checkbox" b-sync="todo.done">
-    <span class="{{ todo.done ? 'done' : '' }}">{{ todo.text }}</span>
-  </li>
-</ul>
-```
-
-* DOM nodes are reused
-* Items are tracked internally
-* Updates are efficient without a virtual DOM
-
----
-
-## Two-Way Binding (`b-sync`)
-
-`b-sync` keeps inputs and state in sync.
-
-```html
-<input b-sync="username">
-<input type="checkbox" b-sync="settings.enabled">
-```
-
-Works with:
-
-* text inputs
-* checkboxes
-* nested objects
-* items inside `b-for`
-
----
-
-## Styling and Shadow DOM
-
-Every component uses **Shadow DOM** automatically.
-
-Inside `<style>` blocks:
-
-* Use `self` to target the component root
-* `self` is converted to `:host`
-
-```css
-self {
-  display: block;
-}
-```
-
-Styles never leak in or out.
-
----
-
-## Lifecycle Hooks
-
-Define lifecycle methods directly on the component state:
-
-```js
-{
-  mounted() {
-    console.log('Component attached');
-  },
-  updated() {
-    console.log('State changed');
-  },
-  unmounted() {
-    console.log('Component removed');
-  }
-}
-```
+[**Explore the Docs**](https://rayattack.github.io/legodom/) | [**Examples**](https://rayattack.github.io/legodom/examples/) | [**GitHub**](https://github.com/rayattack/legodom)
 
 ---
 
-## Custom Events (`$emit`)
-
-Child components communicate upward using events.
+## Why Lego?
 
-```html
-<button @click="$emit('save', data)">Save</button>
-```
-
-Events:
-
-* bubble
-* cross Shadow DOM boundaries
-* are standard `CustomEvent`s
+- ⚡ **Extremely Fast** – No virtual DOM. No reconciliation. Direct DOM updates.
+- 📦 **Zero Dependencies** – Weighs less than 4kb gzipped.
+- 🛠️ **No Build Step** – Works directly in the browser with standard `<script>` tags.
+- 🧩 **Native Web Components** – Real Custom Elements, real Shadow DOM.
+- 🌐 **Built-in Routing** – Lego Router included for client-side routing.
+- 📝 **Familiar Mentals** – Plain JavaScript objects for state, plain HTML for templates.
 
 ---
 
-## Accessing Ancestors (`$ancestors`)
-
-Read state from the nearest ancestor component:
-
-```html
-<p>{{ $ancestors('app-shell').user.name }}</p>
-```
-
-This is intended for **reading**, not mutation.
-
----
-
-## Shared State (`$registry`)
-
-Components defined via `Lego.define` get a shared singleton state.
-
-```js
-$registry('settings').theme
-```
-
-Useful for global configuration or app-wide state.
-
----
-
-## Router
-
-LegoJS includes a minimal client-side router.
-
-Add a router outlet:
-
-```html
-<lego-router></lego-router>
-```
-
-Define routes:
-
-```js
-Lego.route('/', 'home-page');
-Lego.route('/user/:id', 'user-page');
-```
-
-Access route params:
+## Quick Start (No Build Required)
 
 ```html
-<p>User ID: {{ global.params.id }}</p>
-```
+<!DOCTYPE html>
+<html>
+<body>
+  <hello-world></hello-world>
 
-Navigation:
+  <template b-id="hello-world">
+    <style>
+      h1 { color: #ffca28; font-family: sans-serif; }
+    </style>
+    <h1>Hello, {{ name }}!</h1>
+    <button @click="toggle()">Toggle Name</button>
+  </template>
 
-```html
-<a href="/dashboard" b-link>Dashboard</a>
+  <script src="https://unpkg.com/lego-dom/main.js"></script>
+  <script>
+    document.querySelector('hello-world').state = {
+      name: 'World',
+      toggle() {
+        this.name = this.name === 'World' ? 'Lego' : 'World';
+      }
+    };
+  </script>
+</body>
+</html>
 ```
 
 ---
 
-## Programmatic Navigation
-
-```js
-history.pushState({}, '', '/success');
-window.dispatchEvent(new PopStateEvent('popstate'));
-```
-
----
-
-## Defining Components in JavaScript
-
-You can also define components programmatically:
-
-```js
-Lego.define(
-  'counter-box',
-  `
-  <style>self { display:block }</style>
-  <button @click="count++">{{ count }}</button>
-  `,
-  { count: 0 }
-);
-```
-
----
-
-## Initialization
-
-LegoJS initializes automatically on `DOMContentLoaded`.
-
-You usually do **not** need to call anything manually.
-
----
-
-## Design Philosophy
-
-LegoJS is intentionally small and opinionated:
-
-* The DOM is the source of truth
-* JavaScript objects are the state
-* HTML stays HTML
-* Complexity is avoided unless absolutely necessary
-
-If you can explain your UI with plain objects and markup, LegoJS will feel natural.
-
----
-
-## Single File Components (SFC)
+## Also Supports Modern Toolchains
 
-LegoJS supports **Single File Components** using `.lego` files when using a build tool like Vite.
-
-### .lego File Format
-
-A `.lego` file contains three optional sections:
+Lego includes a **Vite plugin** for developers who prefer **Single File Components (.lego)**:
 
 ```html
+<!-- user-card.lego -->
 <template>
-  <!-- Your HTML markup with directives -->
-  <h1>{{ title }}</h1>
-  <button @click="count++">{{ count }}</button>
+  <h1>{{ name }}</h1>
 </template>
 
-<script>
-export default {
-  // Your component logic/state
-  title: 'Hello',
-  count: 0
-}
-</script>
-
 <style>
-  /* Scoped CSS using self keyword */
-  self {
-    display: block;
-    padding: 1rem;
-  }
+  self { display: block; padding: 20px; }
 </style>
-```
-
-The component name is automatically derived from the filename (e.g., `sample-component.lego` → `<sample-component>`).
-
----
-
-## Vite Plugin Setup
-
-### Installation
-
-```bash
-npm install lego-dom vite
-```
-
-### Configuration
-
-Create `vite.config.js`:
-
-```js
-import { defineConfig } from 'vite';
-import legoPlugin from 'lego-dom/vite-plugin';
-
-export default defineConfig({
-  plugins: [
-    legoPlugin({
-      componentsDir: './src/components',  // Where to look for .lego files
-      include: ['**/*.lego']              // Glob patterns to match
-    })
-  ]
-});
-```
-
-### Usage
-
-Create your components in `.lego` files:
-
-```
-src/
-  components/
-    my-button.lego
-    user-card.lego
-  main.js
-index.html
-```
-
-In your `main.js`:
-
-```js
-import { Lego } from 'lego-dom/main.js';
-import registerComponents from 'virtual:lego-components';
-
-registerComponents();
-```
-
-In your HTML:
 
-```html
-<my-button></my-button>
-<user-card></user-card>
+<script>
+  export default { name: 'John Doe' }
+</script>
 ```
 
-**Auto-discovery**: The Vite plugin automatically finds all `.lego` files and registers them with LegoJS!
-
 ---
 
-## Two Usage Modes
-
-LegoJS works in **two modes**:
-
-### 1. Without Build Tooling
-
-Include `main.js` directly and use `<template b-id>` or `Lego.define()`:
-
-```html
-<script src="node_modules/lego-dom/main.js"></script>
-<template b-id="my-component">
-  <h1>Hello</h1>
-</template>
-```
-
-### 2. With Vite (SFC)
-
-Use `.lego` files that are auto-discovered and compiled:
-
-```bash
-npm run dev
-```
-
-Both modes use the same LegoJS runtime and support all the same features!
-
----
+## 🔗 Links
 
-## Summary
+- 📖 [Full Documentation](https://rayattack.github.io/legodom/)
+- 🚀 [Quick Start Guide](https://rayattack.github.io/legodom/guide/quick-start)
+- 🔌 [Vite Plugin Setup](https://rayattack.github.io/legodom/api/vite-plugin)
+- 🧪 [Example Showcase](https://rayattack.github.io/legodom/examples/)
 
-* Install with `npm install lego-dom`
-* Define components with `<template b-id>`
-* Use `b-data` for state
-* Use `{{ }}` for binding
-* Use `@event` for logic
-* Use `b-if`, `b-for`, and `b-sync` for structure
+## License
 
-That’s it.
+MIT © [Tersoo Ortserga](https://github.com/rayattack)

package/cdn.html

@@ -0,0 +1,124 @@
+<html lang="en">
+
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>Lego Test</title>
+  <script src="./main.js"></script>
+</head>
+
+<body @todo-added="() => {console.log('Todo added!')}">
+  <template b-id="todo-list" b-data="{
+      title: 'My Todo List',
+      items: [],
+      newItem: '',
+      mounted() {
+        console.log('Todo list mounted!');
+      }
+    }">
+    <style>
+      :host {
+        display: block;
+        font-family: system-ui, sans-serif;
+        padding: 20px;
+      }
+
+      .done {
+        text-decoration: line-through;
+        color: #888;
+      }
+
+      .input {
+        padding: .4em;
+        border: 1px solid #ccc;
+        border-radius: 0.1em;
+      }
+
+      .item-row {
+        margin-bottom: 8px;
+        display: flex;
+        align-items: center;
+        gap: 10px;
+      }
+
+      button {
+        cursor: pointer;
+        border: none;
+        padding: 5px 10px;
+        border-radius: 0px;
+        background-color: #404;
+        color: #fff;
+      }
+
+      h3 {
+        color: #318d8d;
+        margin-top: 0;
+      }
+    </style>
+
+    <h3>{{title}}</h3>
+    <p>{{ items.filter(t => !t.done).length }} of {{ items.length }} items remaining</p>
+    <div style="margin-bottom: 20px;">
+      <input b-sync="newItem" placeholder="Add task..." class="input">
+      <button @click="() => {
+            if(!newItem.trim()) return;
+            items.push({text: `${newItem} - ${items.length + 1}`, done: false});
+            newItem = '';
+            $emit('todo-added', { item: newItem });
+          }">Add</button>
+    </div>
+
+    <div b-for="todo in items">
+      <div class="item-row {{todo.done ? 'done' : ''}}">
+        <input type="checkbox" b-sync="todo.done">
+        <span>{{todo.text}}</span>
+      </div>
+    </div>
+  </template>
+
+  <template b-id="user-card" b-data="{
+      name: 'Anonymous',
+      bio: 'No bio provided'
+    }">
+    <style>
+      :host {
+        display: block;
+        font-family: system-ui, sans-serif;
+        padding: 20px;
+        border: 1px solid #ccc;
+        border-radius: 8px;
+        margin-bottom: 20px;
+      }
+
+      h3 {
+        color: #62318d;
+        margin-top: 0;
+      }
+    </style>
+
+    <h3>{{name}}</h3>
+    <p>{{bio}}</p>
+    <slot></slot>
+  </template>
+
+  <!-- Using defaults -->
+  <user-card>
+    <p>This user uses default data from the template.</p>
+  </user-card>
+
+  <!-- Overriding defaults -->
+  <user-card b-data="{
+        name: 'John Doe',
+        bio: 'Software Engineer'
+      }">
+    <p>This user overrides the defaults.</p>
+
+    <todo-list b-data="{
+          title: 'Work Tasks',
+          items: [{text: 'Implement template defaults', done: true}]
+        }">
+    </todo-list>
+  </user-card>
+</body>
+
+</html>