lego-dom 0.0.9 → 1.0.0

package/docs/contributing/06-init.md

@@ -0,0 +1,125 @@
+# In the beginning - `Lego.init()`
+
+The `init()` function is the heart of LegoDOM. It orchestrates the entire initialization process, setting up the observer, connecting the global state, and processing existing components.
+
+## The LegoDOM Entry Point
+
+When your HTML finishes loading
+
+```js
+if (typeof window !== 'undefined') {
+  document.addEventListener('DOMContentLoaded', Lego.init);
+  window.Lego = Lego;
+}
+```
+
+
+LegoDOM executes `Lego.init()`. This is the orchestration phase where the library sets up its "eyes" (the observer) and connects the global state to the page.
+
+```js
+  return {
+    init: () => {
+      document.querySelectorAll('template[b-id]').forEach(t => {
+        registry[t.getAttribute('b-id')] = t;
+      });
+      const observer = new MutationObserver(m => m.forEach(r => {
+        r.addedNodes.forEach(n => n.nodeType === Node.ELEMENT_NODE && snap(n));
+        r.removedNodes.forEach(n => n.nodeType === Node.ELEMENT_NODE && unsnap(n));
+      }));
+      observer.observe(document.body, { childList: true, subtree: true });
+
+      snap(document.body);
+      bind(document.body, { _studs: Lego.globals, _data: { bound: false } });
+
+      if (routes.length > 0) {
+        // Smart History: Restore surgical targets on Back button
+        window.addEventListener('popstate', (event) => {
+          const targets = event.state?.legoTargets || null;
+          _matchRoute(targets);
+        });
+
+        document.addEventListener('click', e => {
+          const link = e.target.closest('a[b-link]');
+          if (link) {
+            e.preventDefault();
+            const href = link.getAttribute('href');
+            const targetAttr = link.getAttribute('b-target');
+            const targets = targetAttr ? targetAttr.split(' ') : [];
+
+            // Execute navigation via $go logic
+            Lego.globals.$go(href, ...targets);
+          }
+        });
+        _matchRoute();
+      }
+    },
+    // ... other functions ...
+  };
+
+```
+
+### 1. Template Registration
+
+The first thing `init()` does is look for blueprints you've already defined in your HTML.
+
+```js
+document.querySelectorAll('template[b-id]').forEach(t => {
+  registry[t.getAttribute('b-id')] = t;
+});
+
+```
+
+It scans the entire document for any `<template>` tag that has a `b-id` attribute. It then adds these to the `registry` object we discussed in [Topic 2](/contributing/02-registry). This allows you to define components directly in your HTML file without writing a single line of JavaScript.
+
+### 2. Setting up the "Eyes" (`MutationObserver`)
+
+This is the most critical part of the initialization. The library creates a `MutationObserver`.
+
+```js
+const observer = new MutationObserver(m => m.forEach(r => {
+  r.addedNodes.forEach(n => n.nodeType === Node.ELEMENT_NODE && snap(n));
+  r.removedNodes.forEach(n => n.nodeType === Node.ELEMENT_NODE && unsnap(n));
+}));
+observer.observe(document.body, { childList: true, subtree: true });
+```
+
+-   **What it does**: It watches the `document.body` for any changes to the HTML structure.
+    
+-   **The Config**: It observes `{ childList: true, subtree: true }`. This means it sees if an element is added to the body, or if an element is added deep inside another element.
+    
+-   **The Reaction**:
+    
+    -   If a new node is **added**, it calls `snap(n)` (which we will cover soon) to turn that raw HTML into a living component.
+        
+    -   If a node is **removed**, it calls `unsnap(n)` to clean up memory and fire lifecycle hooks.
+        
+
+### 3. The "First Snap"
+
+After setting up the observer, it calls `snap(document.body)`.
+
+-   **Why?** The observer only sees _new_ things being added. It doesn't see what was already there when the page loaded.
+    
+-   By calling `snap` on the body, the library manually processes every custom component that was present in the initial HTML.
+    
+
+### 4. Global Data Binding
+
+Finally, it binds the `Lego.globals` state to the `document.body`.
+
+JavaScript
+
+```
+bind(document.body, { _studs: Lego.globals, _data: { bound: false } });
+
+```
+
+This is a clever move: it treats the entire website body as if it were a giant component. This allows you to use reactive data in your "Light DOM" (the regular HTML outside of components) by referencing values stored in `Lego.globals`.
+
+### 5. Routing Initialization
+
+If you have defined any routes using `Lego.route()`, the `init` function sets up global click listeners and history management so that links with the `b-link` attribute don't refresh the page but instead perform a "surgical" swap of content.
+
+----------
+
+**Summary of `init()`:** It finds templates, starts a "watchdog" for new elements, processes existing elements, and enables global data.

package/docs/contributing/07-observer.md

@@ -0,0 +1,69 @@
+# Big Brother is Watching
+
+In Topic 6, we saw that Lego.init() sets up a "watchdog." Now, let's look at exactly how that watchdog functions. This is what makes the library feel "automatic"—you can inject HTML into the page using vanilla JavaScript, and Lego will instantly recognize it and bring it to life.
+
+## Mutation Observer
+
+The `MutationObserver` is a built-in browser API that provides the ability to watch for changes being made to the DOM tree. In this library, it acts as the "Event Loop" for component lifecycles.
+
+### 1. The Configuration
+
+The library observes the `document.body` with specific settings:
+
+```js
+observer.observe(document.body, { childList: true, subtree: true });
+
+```
+
+-   **`childList: true`**: Tells the observer to watch for elements being added or removed.
+
+-   **`subtree: true`**: This is vital. Without this, the library would only see things added directly to the `<body>`. With it, the library sees changes happening deep inside nested divs or other components.
+
+
+### 2. Processing `addedNodes`
+
+Whenever a new piece of HTML is injected (via `innerHTML`, `appendChild`, etc.), the observer receives a list of `addedNodes`.
+
+-   **Filter**: The library checks `n.nodeType === Node.ELEMENT_NODE` to ensure it is an **Element** (like a `<div>` or `<my-comp>`) and not just a fragment of text.
+
+-   **The Action**: It calls `snap(n)`. This triggers the entire initialization process: attaching the Shadow DOM, creating reactive state, and rendering the template.
+
+
+### 3. Processing `removedNodes`
+
+When an element is deleted from the page, the observer catches it in `removedNodes`.
+
+-   **Cleanup**: It calls `unsnap(n)`.
+
+-   **Lifecycle Hook**: `unsnap` checks the component's state for an `unmounted` function. This allows you to perform cleanup, like stopping timers or closing WebSocket connections, preventing memory leaks.
+
+
+### Why this is superior to manual initialization
+In most frameworks, you have to tell the library when you’ve changed the page (e.g., calling `root.render()`). This library turns that upside down by using the browser's native **MutationObserver** to watch the DOM and react automatically.
+Unlike some libraries where adding a button via `innerHTML` requires a manual "re-scan" or "re-bind" call, this setup makes LegoDOM **reactive to the DOM itself**: the moment a tag like `<user-card>` appears in the document, it is automatically detected and upgraded into a functional, living component.
+
+### 1. The Strategy: "Observe Once, Act Everywhere"
+
+The library sets up a single observer on `document.body`.
+
+-   **`childList: true`**: This tells the observer to watch for the addition or removal of direct children.
+
+-   **`subtree: true`**: This is the "secret sauce." It extends the observation to the entire DOM tree. If you have a deeply nested `div` and you inject a Lego component into it, the observer will see it.
+
+
+### 2. The Logic Loop: Added Nodes
+
+When the observer detects changes, it provides a list of `MutationRecord` objects. The library loops through these records specifically looking for `addedNodes`.
+
+-   **Type Filtering**: It checks `n.nodeType === Node.ELEMENT_NODE`. This ensures the library ignores text changes or comments and only focuses on **Elements** (tags).
+
+-   **The Upgrade (Snapping)**: For every new element found, it calls `snap(n)`. This is why you can do `document.body.innerHTML += '<my-counter></my-counter>'` in the console, and the counter will immediately start working.
+
+
+### 3. The Logic Loop: Removed Nodes
+
+This is equally important for "garbage collection." When an element is deleted, it appears in `removedNodes`.
+
+-   **The `unsnap` Trigger**: The library calls `unsnap(n)`.
+
+-   **Lifecycle Cleanup**: Inside `unsnap`, the library looks for a developer-defined `unmounted` function. This is where you'd kill `setInterval` timers or close database connections. Without this, your app would suffer from "Memory Leaks"—processes that keep running even though the component is gone.

package/docs/contributing/08-snap.md

@@ -0,0 +1,126 @@
+# Let there be, and it was!
+
+If LegoDOM were a robot it would probably say - snap() is the most complex function I have because it acts as the "Middleman" between the static DOM, the reactive state, and the Shadow DOM. It is the "constructor" that the ~~stingy~~ browser never gave anyone - LegoDOM.
+
+
+## Snap, snap, snap!
+
+The `snap(el)` function is responsible for "upgrading" a standard HTML element. It is recursive, meaning if you snap a `<div>`, it will automatically look inside that `<div>` and snap every child as well.
+
+```js
+const snap = (el) => {
+  if (!el || el.nodeType !== Node.ELEMENT_NODE) return;
+  const data = getPrivateData(el);
+  const name = el.tagName.toLowerCase();
+  const templateNode = registry[name];
+
+  if (templateNode && !data.snapped) {
+    data.snapped = true;
+    const tpl = templateNode.content.cloneNode(true);
+    const shadow = el.attachShadow({ mode: 'open' });
+
+    // TIER 1: Logic from Lego.define (SFC)
+    const scriptLogic = sfcLogic.get(name) || {};
+
+    // TIER 2: Logic from the <template b-data="..."> attribute
+    const templateLogic = parseJSObject(templateNode.getAttribute('b-data') || '{}');
+
+    // TIER 3: Logic from the <my-comp b-data="..."> tag
+    const instanceLogic = parseJSObject(el.getAttribute('b-data') || '{}');
+
+    // Priority: Script < Template < Instance
+    el._studs = reactive({
+      ...scriptLogic,
+      ...templateLogic,
+      ...instanceLogic
+    }, el);
+
+    shadow.appendChild(tpl);
+
+    const style = shadow.querySelector('style');
+    if (style) {
+      style.textContent = style.textContent.replace(/\bself\b/g, ':host');
+    }
+
+    bind(shadow, el);
+    render(el);
+
+    if (typeof el._studs.mounted === 'function') {
+      try { el._studs.mounted.call(el._studs); } catch (e) { console.error(`[Lego] Error in mounted <${name}>:`, e); }
+    }
+  }
+
+  let provider = el.parentElement;
+  while (provider && !provider._studs) provider = provider.parentElement;
+  if (provider && provider._studs) bind(el, provider);
+
+  [...el.children].forEach(snap);
+};
+```
+
+### 1. The Blueprint Lookup
+
+When `snap(el)` runs, the first thing it does is determine if the element is a Lego component.
+
+-   It converts the tag name to lowercase (e.g., `<MY-COMP>` becomes `my-comp`).
+    
+-   It checks the **`registry`** (which we filled in [Topic 2](./02-registry.md)) to see if a `<template>` exists for that name.
+    
+-   It uses `getPrivateData(el).snapped` to ensure it never "snaps" the same element twice, preventing infinite loops.
+    
+
+### 2. Attaching the Shadow DOM
+
+If a template is found, Lego creates a **Shadow DOM** for the element:
+
+JavaScript
+
+```
+const shadow = el.attachShadow({ mode: 'open' });
+
+```
+
+-   **Encapsulation**: By using `attachShadow`, the component’s internal styles and HTML are shielded from the rest of the page.
+    
+-   **Template Injection**: It clones the content of the template and appends it to this new Shadow Root.
+    
+
+### 3. CSS "self" Transformation
+
+Lego includes a small but clever utility for styling:
+
+JavaScript
+
+```
+style.textContent = style.textContent.replace(/\bself\b/g, ':host');
+
+```
+
+-   This allows you to write `self { color: red; }` in your template CSS.
+    
+-   During the snap process, Lego converts the word `self` to the official Web Component selector `:host`, which targets the component itself.
+    
+
+### 4. Data Merging & Reactivity
+
+This is where the component's state is born. The library merges data from three different sources (we will dive deeper into this "Tier System" in Topic 9) and wraps the result in the **`reactive()`** proxy.
+
+-   The resulting proxy is stored in `el._studs`. This is the "brain" of your component.
+    
+
+### 5. The First Render and Lifecycle
+
+Once the data is ready and the Shadow DOM is attached:
+
+1.  **`bind(shadow, el)`**: Connects event listeners (like `@click`) inside the Shadow DOM.
+    
+2.  **`render(el)`**: Performs the initial pass to fill in <code v-pre>{{ variables }}</code> and handle `b-show/b-for` logic.
+    
+3.  **`mounted()`**: If you defined a `mounted` function in your logic, Lego calls it now. This is your signal that the component is officially "alive" and visible on the page.
+
+---------
+
+**Crucial Logic Note:** At the very end of the function, `snap` calls itself on every child of the element: `[...el.children].forEach(snap)`. This ensures that if you have components nested inside components, they all "wake up" in a top-down order.
+    
+
+**Summary**: `snap()` takes a raw tag, gives it a Shadow DOM "soul," injects its HTML blueprint, sets up its reactive "brain" (`_studs`), and triggers its first breath (`mounted`).

package/docs/contributing/09-diffing.md

@@ -0,0 +1,69 @@
+# He said, She said, They Said, Who Said?
+
+This topic is about the "Power Struggle" inside the code. When a component is born, it needs to know what its data is. The library looks at three different places to find that data, and it has a strict hierarchy of who wins in a conflict.
+
+
+## Diffing, Merging, and Priorities (The Tier System)
+
+Inside the `snap(el)` function, you will see a variable called `logic`. This isn't just a simple object; it is the result of a three-way merge. The code uses the spread operator `{ ... }` to layer these "Tiers."
+
+### The Three Tiers of Authority
+
+1.  **Tier 1: The Global Definition (Lowest Priority)**
+    
+    ```js
+    const baseLogic = sfcLogic.get(name) || {};
+    
+    ```
+    
+    This is the JavaScript object you provided when you called `Lego.define()`. It contains your default values and methods. It’s the "fallback" data. SFCs and .lego files fall under this tier.
+    
+2.  **Tier 2: The Template Attributes (Middle Priority)**
+
+    
+    ```js
+    const templateLogic = parseJSObject(t.getAttribute('b-data')) || {};
+    
+    ```
+    
+    Lego looks at the `<template>` tag itself in your HTML. If you added a `b-data` attribute there, it overrides the global definition. This is useful for creating "variants" of a component template without writing new JavaScript.
+    
+3.  **Tier 3: The Instance Attributes (Highest Priority)**
+    
+    ```js
+    const instanceLogic = parseJSObject(el.getAttribute('b-data')) || {};
+    
+    ```
+    
+    This is the data attached to the specific tag on your page (e.g., `<user-profile b-data="{id: 42}">`). This is the "Final Word." If the instance says the ID is 42, it doesn't matter what the template or the global definition said.
+    
+
+### The Merge Order
+
+The code combines them like this:
+
+JavaScript
+
+```
+const mergedLogic = { ...baseLogic, ...templateLogic, ...instanceLogic };
+
+```
+
+In JavaScript, when you spread objects, the properties on the right overwrite properties on the left. So, Instance > Template > Definition.
+
+### The `parseJSObject` Utility
+
+To make this work, the library includes a helper called `parseJSObject`.
+
+-   **Why not `JSON.parse`?** JSON is strict (requires double quotes, no functions).
+    
+-   **The Library's Way**: It uses `new Function('return ' + str)()`. This is a powerful (and dangerous) trick that allows you to write actual JavaScript inside your HTML attributes, including functions or arrays, which Lego then evaluates into a real object.
+    
+
+### The Edge Case: `b-data` as a "Ref"
+
+If the `b-data` attribute starts with a `$`, like `b-data="$someGlobal"`, the library treats it as a pointer to a global variable instead of a raw object string. This allows for deep data sharing between the component and the outside world.
+
+----------
+
+**Summary**: A component's data is a "Cake" with three layers. The Global Logic is the bottom, the Template Logic is the middle, and the Instance Logic is the frosting. The "Frosting" (Instance) is what the user ultimately sees.

package/docs/contributing/10-studs.md

@@ -0,0 +1,76 @@
+# State Management
+
+Let's see how the "Cake" of data we merged in Topic 9 is actually brought to life. This is the moment a static object becomes a **Reactive State**, which the library stores in a property called `_studs`.
+
+
+## The `reactive` State (`_studs`)
+
+Once `snap()` has merged the data from the SFC (Tier 1), the Template (Tier 2), and the Instance (Tier 3), it doesn't just save that object to the element. It transforms it.
+
+```js
+//...rest of code
+  const tpl = templateNode.content.cloneNode(true);
+  const shadow = el.attachShadow({ mode: 'open' });
+
+  // TIER 1: Logic from Lego.define (SFC)
+  const scriptLogic = sfcLogic.get(name) || {};
+
+  // TIER 2: Logic from the <template b-data="..."> attribute
+  const templateLogic = parseJSObject(templateNode.getAttribute('b-data') || '{}');
+
+  // TIER 3: Logic from the <my-comp b-data="..."> tag
+  const instanceLogic = parseJSObject(el.getAttribute('b-data') || '{}');
+
+  // Priority: Script < Template < Instance
+  el._studs = reactive({
+    ...scriptLogic,
+    ...templateLogic,
+    ...instanceLogic
+  }, el);
+  //... rest of code
+```
+
+### 1. Why the name `_studs`?
+
+In the physical world, "studs" are the bumps on top of a Lego brick that allow it to connect to others. In this library:
+
+-   **`el._studs`** represents the connection point between your JavaScript logic and the DOM.
+    
+-   It is the "source of truth" for the component. Every `{{variable}}` you write in your HTML is looking for a matching key inside `_studs`.
+    
+
+### 2. The Transformation
+
+The library executes this line during the snap process:
+
+```js
+el._studs = reactive({ ...mergedLogic }, el);
+
+```
+
+-   **The `reactive` call**: This wraps the merged object in the **Proxy** we discussed in Topic 4.
+    
+-   **The `el` argument**: Crucially, the proxy is given a reference to the DOM element (`el`). This allows the Proxy's `set` trap to know exactly which component needs to be added to the `globalBatcher` when a property changes.
+    
+
+### 3. Contextual Binding (The `this` Keyword)
+
+After the `_studs` proxy is created, the library ensures that your methods work correctly. When you define a method in your SFC, you expect `this` to point to your data.
+
+-   Inside `snap()`, lifecycle hooks are called like this: `el._studs.mounted.call(el._studs)`.
+    
+-   By using `.call(el._studs)`, the library forces the execution context of your functions to be the reactive proxy.
+    
+-   **Result**: When you write `this.count++` in your code, you are actually interacting with the **Proxy**, which triggers the `set` trap, which notifies the **Batcher**, which triggers the **Render**.
+    
+
+### 4. Visibility vs. Privacy
+
+-   **`_studs`**: This is attached directly to the DOM element. You can actually type `document.querySelector('my-component')._studs` in your browser console to see and even modify the live state of any component.
+    
+-   **`privateData`**: Unlike `_studs`, the internal "housekeeping" (like whether the component has already snapped) is kept in a `WeakMap` called `privateData`, making it inaccessible to the outside world.
+    
+
+----------
+
+**Summary**: `_studs` is the reactive engine of your component. It is created by merging all data tiers into a Proxy that is uniquely linked to that specific DOM element.

package/docs/contributing/11-scanner.md

@@ -0,0 +1,104 @@
+# Scanner
+
+Now let's get into the "eyes" of the rendering engine. For LegoDOM to be able to update the DOM efficiently, it needs to know which specific parts of your HTML are static (never change) and which parts are dynamic (contain {{mustaches}} or b- directives).
+
+
+## Scanning for Bindings (The `TreeWalker`)
+
+In `main.js`, the `scanForBindings` function is called the very first time a component renders. Instead of re-scanning the DOM every time a variable changes, Lego scans **once**, creates a "map" of all the dynamic spots, and saves that map in the element's `privateData`.
+
+```js
+const scanForBindings = (container) => {
+  const bindings = [];
+  const walker = document.createTreeWalker(container, NodeFilter.SHOW_ELEMENT | NodeFilter.SHOW_TEXT);
+  let node;
+  while (node = walker.nextNode()) {
+    const isInsideBFor = (n) => {
+      let curr = n.parentNode;
+      while (curr && curr !== container) {
+        if (curr.hasAttribute && curr.hasAttribute('b-for')) return true;
+        if (curr.tagName && curr.tagName.includes('-') && registry[curr.tagName.toLowerCase()]) return true;
+        curr = curr.parentNode;
+      }
+      return false;
+    };
+    if (isInsideBFor(node)) continue;
+
+    if (node.nodeType === Node.ELEMENT_NODE) {
+      if (node.hasAttribute('b-show')) bindings.push({ type: 'b-show', node, expr: node.getAttribute('b-show') });
+      if (node.hasAttribute('b-for')) {
+        const match = node.getAttribute('b-for').match(/^\s*(\w+)\s+in\s+(.+)\s*$/);
+        if (match) {
+          bindings.push({
+            type: 'b-for',
+            node,
+            itemName: match[1],
+            listName: match[2].trim(),
+            template: node.innerHTML
+          });
+          node.innerHTML = '';
+        }
+      }
+      if (node.hasAttribute('b-text')) bindings.push({ type: 'b-text', node, path: node.getAttribute('b-text') });
+      if (node.hasAttribute('b-sync')) bindings.push({ type: 'b-sync', node });
+      [...node.attributes].forEach(attr => {
+        if (attr.value.includes('{{')) bindings.push({ type: 'attr', node, attrName: attr.name, template: attr.value });
+      });
+    } else if (node.nodeType === Node.TEXT_NODE && node.textContent.includes('{{')) {
+      bindings.push({ type: 'text', node, template: node.textContent });
+    }
+  }
+  return bindings;
+};
+```
+
+### 1. The `TreeWalker` Efficiency
+
+LegoDOM uses a native browser tool called a `TreeWalker`.
+
+```js
+const walker = document.createTreeWalker(container, NodeFilter.SHOW_ELEMENT | NodeFilter.SHOW_TEXT);
+
+```
+
+-   **Why not `querySelectorAll('*')`?** A `TreeWalker` is much faster and more memory-efficient. It allows the library to step through every single node (including text nodes) one by one.
+    
+
+### 2. The "Nested Component" Shield
+
+One of the smartest parts of this function is the `isInsideBFor` check.
+
+-   If the scanner finds an element that is inside a `b-for` loop or belongs to a **different** custom component (i.e. user-profile, product-card etc.), it stops.
+    
+-   **Reasoning**: You don't want the parent component to try and manage the internal text of a child component. This maintains **Encapsulation**.
+    
+
+### 3. What it looks for
+
+As it walks the tree, it populates a `bindings` array with "Instruction Objects":
+
+-   **Directives**: It looks for `b-show`, `b-text`, `b-sync`, and `b-for` attributes.
+    
+-   **Mustaches in Text**: It looks for text nodes containing <code v-pre>{{ }}</code>. It saves the original template (e.g., `"Hello {{name}}"`) so it can swap the name later without losing the "Hello".
+    
+-   **Mustaches in Attributes**: It scans every attribute (like <code v-pre>class="btn {{color}}"</code>) to see if it needs to be dynamic.
+    
+
+### 4. The "Instruction Object" Structure
+
+When it finds something, it pushes an object like this into the list:
+
+```js
+{ 
+  type: 'text', 
+  node: [The actual TextNode], 
+  template: 'Hello {{user.name}}' 
+}
+
+```
+
+By storing the **actual Node reference**, the library can update the screen later with surgical precision. It doesn't have to search the DOM again; it just goes straight to that specific memory address and updates the value.
+
+----------
+
+**Summary**: `scanForBindings` is a one-time "reconnaissance mission." it maps out every dynamic part of your component so that future updates are lightning-fast.