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

lego-dom 0.0.8 → 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 (175) hide show

package/docs/contributing/07-observer.md ADDED Viewed

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

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

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

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

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

package/docs/contributing/12-render.md ADDED Viewed

@@ -0,0 +1,116 @@
+# Paint Me HTML
+In Topic 11, we mapped out where the dynamic "holes" in your HTML are. Now, we look at the engine that actually fills them with data. The `render()` function is the most frequently called piece of code in LegoDOM, it is the bridge between JavaScript state and the pixels on the screen.
+## Rendering `render()` Engine
+The `render(el)` function doesn't refresh the whole component. Instead, it iterates through the "Instruction Objects" (bindings) created during the scanning phase and updates only what is necessary.
+```js
+const render = (el) => {
+  const state = el._studs;
+  if (!state) return;
+  const data = getPrivateData(el);
+  if (data.rendering) return;
+  data.rendering = true;
+  try {
+    const shadow = el.shadowRoot;
+    if (!shadow) return;
+    if (!data.bindings) data.bindings = scanForBindings(shadow);
+    data.bindings.forEach(b => {
+      if (b.type === 'b-show') b.node.style.display = safeEval(b.expr, { state, self: b.node }) ? '' : 'none';
+      if (b.type === 'b-text') b.node.textContent = escapeHTML(resolve(b.path, state));
+      if (b.type === 'b-sync') syncModelValue(b.node, resolve(b.node.getAttribute('b-sync'), state));
+      if (b.type === 'text') {
+        const out = b.template.replace(/{{(.*?)}}/g, (_, k) => escapeHTML(safeEval(k.trim(), { state, self: b.node }) ?? ''));
+        if (b.node.textContent !== out) b.node.textContent = out;
+      }
+      if (b.type === 'attr') {
+        const out = b.template.replace(/{{(.*?)}}/g, (_, k) => escapeHTML(safeEval(k.trim(), { state, self: b.node }) ?? ''));
+        if (b.node.getAttribute(b.attrName) !== out) {
+          b.node.setAttribute(b.attrName, out);
+          if (b.attrName === 'class') b.node.className = out;
+        }
+      }
+      if (b.type === 'b-for') {
+        const list = safeEval(b.listName, { state, global: Lego.globals, self: el }) || [];
+        if (!forPools.has(b.node)) forPools.set(b.node, new Map());
+        const pool = forPools.get(b.node);
+        const currentKeys = new Set();
+        list.forEach((item, i) => {
+          const key = (item && typeof item === 'object') ? (item.__id || (item.__id = Math.random())) : `${i}-${item}`;
+          currentKeys.add(key);
+          let child = pool.get(key);
+          if (!child) {
+            const temp = document.createElement('div');
+            temp.innerHTML = b.template;
+            child = temp.firstElementChild;
+            pool.set(key, child);
+            bind(child, el, { name: b.itemName, listName: b.listName, index: i });
+          }
+          const localScope = Object.assign(Object.create(state), { [b.itemName]: item });
+          updateNodeBindings(child, localScope);
+          child.querySelectorAll('[b-sync]').forEach(input => {
+            const path = input.getAttribute('b-sync');
+            if (path.startsWith(b.itemName + '.')) {
+              const list = safeEval(b.listName, { state, global: Lego.globals, self: el });
+              syncModelValue(input, resolve(path.split('.').slice(1).join('.'), list[i]));
+            }
+          });
+          if (b.node.children[i] !== child) b.node.insertBefore(child, b.node.children[i] || null);
+        });
+        for (const [key, node] of pool.entries()) {
+          if (!currentKeys.has(key)) { node.remove(); pool.delete(key); }
+        }
+      }
+    });
+  } finally {
+    data.rendering = false;
+  }
+};
+```
+### 1. The Guard Rails
+Before doing any work, `render` checks two things:
+-   **The State**: It ensures `el._studs` exists.
+-   **The Recursion Lock**: It sets `data.rendering = true` at the start and `false` at the end. This prevents a "Render Loop" where an update triggers a render, which accidentally triggers another update.
+### 2. Surgical Execution
+The function loops through `data.bindings` and performs specific actions based on the `type`:
+-   **`b-show`**: It evaluates the expression. If false, it sets `display: none`. This is a "CSS-based" conditional; the element stays in the DOM but becomes invisible. **Might change to `remove()` in the future**
+-   **`b-text`**: It uses the `resolve()` helper to find the value in your state and sets the `textContent`.
+-   **`text` (Mustaches)**: It takes the original template (e.g., `Count: {{count}}`), replaces the mustache with the actual value, and updates the text node.
+-   **`attr`**: It updates attributes like `src`, `href`, or `class`. It even has a special check: if the attribute is `class`, it also updates `node.className` to ensure the browser applies the styles correctly.
+### 3. The `safeEval` Bridge
+You’ll notice that for things like `b-show` or <code v-pre>{{mustaches}}</code>, the library calls `safeEval(expr, { state, self: b.node })`.
+-   This allows your HTML to handle more than just simple variables.
+-   You can write logic directly in your template, like <code v-pre>{{ count > 10 ? 'Big' : 'Small' }}</code>.
+-   `render` passes the current state as the "context," so those expressions know exactly what `count` refers to.
+### 4. Directives vs. Mustache Priority
+`render` processes directives (like `b-show` and `b-text`) and mustaches in the same loop. However, because it works with direct DOM references saved in the `bindings` array, it never has to "re-parse" the HTML string. It simply touches the specific property (like `.value` or `.textContent`) of the existing DOM node.
+----------
+**Summary**: `render()` is a "Loop of Truth." It walks through the map created by the scanner, evaluates the current state of your data, and applies those values to the specific DOM nodes that need them.