lego-dom 1.3.4 → 1.4.0

package/docs/api/globals.md

@@ -1,29 +0,0 @@
-# Global Helpers
-
-Lego exposes a global `Lego` object when loaded via CDN, or as exports when using modules.
-
-## Lego.page
-
-Access to the router's current state.
-
-```js
-console.log(Lego.page.params); // URL parameters
-console.log(Lego.page.query);  // Query string parameters
-```
-
-## Lego.create()
-
-Manually create a reactive object (stud) detached from a component.
-
-```js
-const store = Lego.create({ count: 0 });
-```
-
-## Event Bus
-
-Simple global event bus.
-
-```js
-Lego.on('user-login', (user) => { ... });
-Lego.emit('user-login', { name: 'Alice' });
-```

package/docs/api/index.md

@@ -1,30 +0,0 @@
-# API Reference
-
-Welcome to the Lego API documentation.
-
-## Core
-
-- [Lego.define()](/api/define) - Defining components
-- [Lego.route()](/api/route) - Client-side routing
-- [Lego.globals](/api/globals) - Global state
-- [Lego.config](/api/config) - Configuration & Error Handling
-- [Lifecycle Hooks](/api/lifecycle) - Component lifecycle methods
-
-## Templates & Binding
-
-- [Directives](/api/directives) - `b-show`, `b-for`, `b-sync`
-
-## Browser Support
-
-Lego requires:
-- Web Components (Custom Elements v1)
-- Shadow DOM v1
-- ES6 Proxy
-- Template Literals
-- MutationObserver
-
-Supported browsers:
-- Chrome 63+
-- Firefox 63+
-- Safari 11.1+
-- Edge 79+

package/docs/api/lifecycle.md

@@ -1,40 +0,0 @@
-# Lifecycle Hooks
-
-Methods that are automatically called during a component's lifecycle.
-
-## init()
-
-Called when the component is initialized and state is reactive, but before rendering.
-
-```js
-{
-  init() {
-    this.fetchData();
-  }
-}
-```
-
-## render()
-
-Called after the DOM has been updated.
-
-```js
-{
-  render() {
-    console.log('Component rendered');
-  }
-}
-```
-
-## destroy()
-
-Called when the component is removed from the DOM.
-
-```js
-{
-  destroy() {
-    // Cleanup timers or listeners
-    clearInterval(this.timer);
-  }
-}
-```

package/docs/api/route.md

@@ -1,37 +0,0 @@
-# Lego.route()
-
-Client-side routing.
-
-## Type Signature
-
-```ts
-Lego.route(path: string, componentOrHtml: string | HTMLElement)
-```
-
-## Arguments
-
-- **path**: The URL path pattern (e.g., `/users/:id`).
-- **componentOrHtml**: The tag name of the component to render, or raw HTML.
-
-## Example
-
-```js
-// Route to a component
-Lego.route('/', 'home-page');
-Lego.route('/about', 'about-page');
-
-// Route with params
-Lego.route('/user/:id', 'user-profile');
-```
-
-## Router Outlet
-
-You must have a `<router-outlet>` in your DOM where the routed content will appear.
-
-```html
-<nav>
-  <a href="/">Home</a>
-  <a href="/about">About</a>
-</nav>
-<router-outlet></router-outlet>
-```

package/docs/api/vite-plugin.md

@@ -1,58 +0,0 @@
-# Vite Plugin API
-
-Lego includes a Vite plugin for processing `.lego` Single File Components.
-
-## Installation
-
-```bash
-npm install vite lego-dom
-```
-
-## Usage
-
-```js
-// vite.config.js
-import { defineConfig } from 'vite';
-import legoPlugin from 'lego-dom/vite-plugin';
-
-export default defineConfig({
-  plugins: [
-    legoPlugin({
-      // Options
-    })
-  ]
-});
-```
-
-## Options
-
-### `componentsDir`
-
-- **Type**: `string`
-- **Default**: `'src/components'`
-
-Directory to search for `.lego` files.
-
-### `include`
-
-- **Type**: `string | string[]`
-- **Default**: `'**/*.lego'`
-
-Glob pattern(s) to match files.
-
-### `exclude`
-
-- **Type**: `string | string[]`
-- **Default**: `null`
-
-Glob pattern(s) to exclude files.
-
-## Virtual Module
-
-The plugin exposes a virtual module to register all components:
-
-```js
-import registerComponents from 'virtual:lego-components';
-
-registerComponents();
-```

package/docs/contributing/01-welcome.md

@@ -1,38 +0,0 @@
-# Topic 1: The Module Pattern & Private Scope
-
-LegoDOM is wrapped in an **IIFE** (Immediately Invoked Function Expression) assigned to `const Lego`. This creates a closure, meaning any variable declared at the top (like `registry` or `proxyCache`) is "private"—it cannot be accessed or tampered with from the browser console unless explicitly exposed.
-
-```js
-const Lego = (() => {
-  // ... all the logic ...
-  return {
-    init: () => { ... },
-    init: () => { ... },
-    define: (tagName, templateHTML, logic = {}) => { ... },
-    defineSFC: (content, filename) => { ... }, // Runtime SFC Parser
-    // ...
-  };
-})();
-
-if (typeof window !== 'undefined') {
-  document.addEventListener('DOMContentLoaded', Lego.init);
-  window.Lego = Lego;
-}
-```
-
-### Why Not Modular ES6?
-
-I started with an **IIFE** and underestimated how big it could grow. It might be a better idea to use ES6 modules, but I'm too lazy to refactor it at the moment.
-
-### The use of `WeakMap`
-
-You’ll notice the use of `WeakMap` for `proxyCache`, `privateData`, and `forPools`.
-
--   **Why not a regular Map?** A `WeakMap` allows the keys (which are DOM elements in this code) to be **garbage collected** if the element is removed from the DOM.
-    
--   **Memory Leak Prevention:** If we used a regular `Map`, the library would hold a reference to every component ever created, even if you deleted them, eventually crashing the browser tab.
-    
-
-### Internal Registry
-
-`const registry = {}` acts as the library's "brain." It stores the `<template>` elements that define what a component looks like. When you write `<my-button>`, Lego looks into this object to find the blueprint.

package/docs/contributing/02-registry.md

@@ -1,133 +0,0 @@
-# The Good Ole Registry (Lego Basket)
-
-Let's not keep our toys everywhere, let's be good citizens and put them in a basket.
-
-PSS!!! Come here lemme tell you a secret - are you a frontend developer? "The DOM is not your enemy"
-we talk about Light DOM and Shadow DOM in a minute ;-).
-
-
-## Topic 2: The Registry & Internal Storage
-
-LegoDOM uses three specialized collections to store the "DNA" of your application. This separation allows the framework to distinguish between what a component **looks like** versus how it **behaves**.
-
-```js
-const registry = {};
-const sfcLogic = new Map();
-const sharedStates = new Map();
-```
-
-### 1. The HTML Blueprint Collection (`registry`)
-
-`const registry = {}` is a plain object that stores references to `<template>` elements.
-
--   When the library initializes, it scans the DOM for any `<template b-id="my-component">` and saves it here.
-    
--   The `b-id` becomes the key, and the DOM node itself is the value.
-    
--   **Purpose:** This is the "Light DOM" source used to populate the "Shadow DOM" later during the "snapping" process.
-    
-
-### 2. The SFC Logic Collection (`sfcLogic`)
-
-`const sfcLogic = new Map();` stores the JavaScript objects passed into `Lego.define()`.
-
--   While `registry` holds the HTML/CSS, `sfcLogic` holds the functions like `mounted()`, `updated()`, or custom methods.
-    
--   **Why a Map?** Unlike a plain object, a `Map` is more performant for frequent lookups by string keys (tag names) - I think!!! or maybe I read wrong (call me out).
-    
-
-### 3. The Singleton States Collection (`sharedStates`)
-
-`const sharedStates = new Map();` is one of the most powerful "hidden" features of LegoDOM.
-
--   Every time you define a component, Lego creates a **reactive version** of its logic and stores it here.
-    
--   This allows other components to access a specific component's state globally via the `$registry('tag-name')` helper. **NOTE** the component's (template/blueprint) state, not the instance state.
-    
--   **Example:** If you have 3 `user-profile` components, any other component on the page can peek at their (shared) state data by asking the `sharedStates` map.
-
-
-#### Dissecting Registration
-
-The `registry` doesn't just wait for you to type; it's fed by three distinct streams across 2 paradigms.
-
-**Paradigm 1: Explicitly**
-
-```js
-const sfcLogic = new Map(); // Specifically for SFC script logic
-// ...
-define: (tagName, templateHTML, logic = {}) => {
-  const t = document.createElement('template');
-  // ... stores template in registry
-  sfcLogic.set(tagName, logic); // Stores the JS part separately
-}
-```
-
-**Paradigm 2: Implicitly**
-
-```js
-// vite-plugin.js
-async buildStart() {
-  const root = config?.root || process.cwd();
-  legoFiles = await fg(include, { cwd: searchPath, absolute: true }); // Scans for .lego files
-}
-// ...
-async load(id) {
-  if (id.endsWith('.lego')) {
-    const defineCall = generateDefineCall(parsed); // Converts .lego file to Lego.define()
-    return `import { Lego } from 'lego-dom/main.js';\n${defineCall}`;
-  }
-}
-
-```
-
-**The Three Ways to Register:**
-1.  **The HTML Manual Method:** You put `<template b-id="my-comp">` directly in your `*.html` files. During `Lego.init()`, the library scrapes these and populates the registry. This is great for "no-build" prototypes.
-    
-2.  **The `Lego.define()` JS Method:** You call `Lego.define('my-comp', '<h1>Hi</h1>', { ... logic })` in a standard JavaScript file.
-    
-3.  **The SFC Automatic Method (The "Vite Way"):** * The **Vite Plugin** (as seen in `vite-plugin.js`) acts as a build-time robot.
-    
-    -   It uses `fast-glob` (`fg`) to scan your entire `src/components` directory for any file ending in `.lego`.
-        
-    -   It parses the `<template>` and `<script>` inside that `.lego` file.
-        
-    -   It **injects** a `Lego.define()` call into your JavaScript bundle automatically.
-        
-    -   **Result:** You just create a file named `user-card.lego`, and suddenly `<user-card>` is a valid HTML tag in your app.
-
-**Paradigm 3: Runtime Component Definition (New in v2.0)**
-
-```js
-defineSFC: (content, filename) => {
-  // Regex parsing of <template>, <script>, <style>
-  const templateMatch = content.match(/<template([\s\S]*?)>([\s\S]*?)<\/template>/);
-  // ...
-  const logicObj = new Function(`return ${script}`)();
-  // ...
-  sfcLogic.set(name, logicObj);
-}
-```
-
-This is the power behind the **Server Loader**. We can fetch a string from the server and "compile" it in the browser using `new Function()`. It populates `registry` and `sfcLogic` just like the build-time tools, but on the fly.
-
-### 4. Component Naming Conventions ("Explicit or Go Home")
-
-When you define a component via a file (e.g. `.lego`), the library automatically derives the tag name. To keep the web platform happy, we enforce **Custom Element Best Practices**:
-
-1.  **Automatic Conversion**: All filenames are converted to `kebab-case`.
-    -   `UserProfile.lego` -> `<user-profile>`
-    -   `navBar.lego` -> `<nav-bar>`
-    -   `data_table.lego` -> `<data-table>`
-    
-2.  **The Hyphen Rule**: A custom element **MUST** contain a hyphen.
-    -   `Button.lego` -> Error
-    -   `Adidas.lego` -> Error
-
-> [!TIP]
-> **Single Word Component? Namespace It!** 
-> Custom Element specs require a hyphen to distinguish from native tags. To ensure forward compatibility, **LegoDOM will throw an error** if you try to define a single-word component.
-> Simply add your app or product prefix to the filename:
-> -   `fb-button.lego` -> `<fb-button>`
-> -   `shop-card.lego` -> `<shop-card>`
-> -   `mobile-button.lego` -> `<mobile-button>`

package/docs/contributing/03-batcher.md

@@ -1,110 +0,0 @@
-# Batching, Scheduling, and doing things the right way
-
-Say you are building the next big thing, if you update checkboxes, input fields a 100 times,
-you don't want the DOM to re-render 100 times. That would be a performance nightmare.
-LegoDOM uses Batching & Scheduling to do things the right way.
-
-
-## Topic 3: The Global Batcher & Scheduler
-
-When you change data in a reactive application, you often change multiple things at once (e.g., updating a user's name, age, and profile picture). Without a **Batcher**, the browser would try to re-render the HTML every single time one of those properties changed. This would cause "jank" (stuttering) and poor performance.
-
-### The `createBatcher` Factory
-
-The library defines `createBatcher` as a closure that manages the update cycle. It provides three critical layers of protection:
-
-```js
-  const createBatcher = () => {
-    let queued = false;
-    const componentsToUpdate = new Set();
-    let isProcessing = false;
-
-    return {
-      add: (el) => {
-        if (!el || isProcessing) return;
-        componentsToUpdate.add(el);
-        if (queued) return;
-        queued = true;
-
-        requestAnimationFrame(() => {
-          isProcessing = true;
-          const batch = Array.from(componentsToUpdate);
-          componentsToUpdate.clear();
-          queued = false;
-
-          batch.forEach(el => render(el));
-
-          setTimeout(() => {
-            batch.forEach(el => {
-              const state = el._studs;
-              if (state && typeof state.updated === 'function') {
-                try {
-                  state.updated.call(state);
-                } catch (e) {
-                  console.error(`[Lego] Error in updated hook:`, e);
-                }
-              }
-            });
-            isProcessing = false;
-          }, 0);
-        });
-      }
-    };
-  };
-
-  const globalBatcher = createBatcher();
-```
-
-1.  **Deduplication with `Set`**:
-    
-    -   The batcher maintains a `componentsToUpdate = new Set()`.
-        
-    -   Because a `Set` only stores unique values, if you trigger an update on the same component 50 times in a single loop, it is only added to the "todo" list **once**.
-        
-2.  **The `queued` Gatekeeper**:
-    
-    -   A boolean flag `queued` prevents multiple update cycles from being scheduled simultaneously.
-        
-    -   Once the first change hits the batcher, it "locks the gate," schedules the work, and ignores further requests to start a new cycle until the current one begins.
-        
-3.  **The `isProcessing` Lock**:
-    
-    -   This flag ensures that if a component’s state changes _while_ the render is actually happening, it doesn't cause a collision or infinite loop.
-        
-
-### Timing: `requestAnimationFrame` (rAF)
-
-Instead of updating immediately, the library uses `requestAnimationFrame`.
-
--   **What it does**: It tells the browser, "Wait until you are just about to draw the next frame on the screen, then run this code".
-
--   **Efficiency**: It bundles every single change from every component into a single "tick."
-    
--   **The Benefit**: This syncs your JavaScript logic with the monitor's refresh rate (usually 60 times per second), making animations and updates look buttery smooth.
-    
-
-### The Execution Phase
-
-When the "frame" triggers, the batcher:
-
-1.  Takes a snapshot of the `Set`.
-    
-2.  Clears the `Set` for the next round.
-    
-3.  Runs `render(el)` for every component in that batch.
-    
-
-### The `updated` Lifecycle Hook
-
-After the render is complete, the batcher uses a `setTimeout(() => ..., 0)`.
-
--   **The Trick**: Even with a delay of `0`, this "macro-task" ensures the code inside runs **after** the browser has finished its rendering work.
-    
--   **The Hook**: It looks for `our` lifecycle hook function a.k.a or notoriously known as `updated`
-in each component's state (`_studs`) and executes it. This is the perfect place for us to run code that needs to measure the new size of an element or scroll a list to the bottom.
-
-**Example**
-If you have a `chat-box` component and you update the messages, you might use the `updated()` hook to scroll to the bottom. Because of this batcher, you are guaranteed that the DOM has finished changing before your scroll logic runs.
-
-
-> **Visualizing the flow:** State Change -> `batcher.add(el)` -> `Set` collects `el` -> `rAF` triggers -> `render(el)` runs -> `updated()` hook fires.

package/docs/contributing/04-reactivity.md

@@ -1,87 +0,0 @@
-# Reacting to stimuli is how we react to stimuli
-
-If living things react to stimuli, then so should our components.
-
-
-## Topic 4: Reactivity (The Proxy)
-
-LegoDOM uses the JavaScript **`Proxy`** object to create its reactivity. Think of a Proxy as a "security guard" that sits in front of your data object. Every time you try to read or change a property, the guard intercepts the request.
-
-### The `reactive(obj, el, batcher)` Function
-
-When a component is "snapped" (created), its data is passed through this function.
-
-```js
-  //... rest of the code
-  const reactive = (obj, el, batcher = globalBatcher) => {
-    if (obj === null || typeof obj !== 'object' || obj instanceof Node) return obj;
-    if (proxyCache.has(obj)) return proxyCache.get(obj);
-
-    const handler = {
-      get: (t, k) => {
-        const val = Reflect.get(t, k);
-        if (val !== null && typeof val === 'object' && !(val instanceof Node)) {
-          return reactive(val, el, batcher);
-        }
-        return val;
-      },
-      set: (t, k, v) => {
-        const old = t[k];
-        const r = Reflect.set(t, k, v);
-        if (old !== v) batcher.add(el);
-        return r;
-      },
-      deleteProperty: (t, k) => {
-        const r = Reflect.deleteProperty(t, k);
-        batcher.add(el);
-        return r;
-      }
-    };
-
-    const p = new Proxy(obj, handler);
-    proxyCache.set(obj, p);
-    return p;
-  };
-
-  //... rest of the code
-```
-
-1.  **The Traps (`get` and `set`)**:
-    
-    -   **The `get` trap**: When you access a property (e.g., `state.count`), the Proxy checks if that property is _also_ an object. If it is, it recursively wraps that object in a Proxy too. This ensures that "deep" data like `user.profile.name` is also reactive.
-        
-    -   **The `set` trap**: This is the trigger. When you do `state.count = 5`, the Proxy compares the `old` value with the `new` value. If they are different, it immediately calls `batcher.add(el)`.
-        
-    -   **The `deleteProperty` trap**: Even if you delete a key (e.g., `delete state.tempData`), the Proxy intercepts this and tells the batcher to re-render the UI.
-        
-2.  **Handling Objects vs. Nodes**:
-    
-    -   The code explicitly checks if a value is an `instanceof Node`. If you try to store a raw HTML element in your state, the library **will not** wrap it in a Proxy. This prevents the library from accidentally trying to "observe" the entire DOM tree, which would crash the browser.
-        
-
-### Concrete Example
-
-Imagine you have a component defined like this:
-
-```js
-Lego.define('counter-app', '<h1>{{count}}</h1>', {
-  count: 0,
-  increment() { this.count++; }
-});
-
-```
-
--   **Step A**: Lego takes that object `{ count: 0, ... }` and wraps it in a Proxy.
-    
--   **Step B**: You call `increment()`.
-    
--   **Step C**: The line `this.count++` triggers the Proxy's `set` trap.
-    
--   **Step D**: The `set` trap notices `0` is now `1` and calls `globalBatcher.add(thisElement)`.
-    
--   **Step E**: The Batcher (from Topic 3) schedules a render for the next animation frame.
-    
-
-### Why this is "Surgical"
-
-Because the `reactive` function is passed the specific element (`el`) it belongs to, it knows exactly which component in the DOM needs to re-render. It doesn't have to guess or refresh the whole page; it targets the specific "Lego block" that owns that data.

package/docs/contributing/05-caching.md

@@ -1,59 +0,0 @@
-# There are 2 hard things in computer science
-
-- cache invalidation
-- naming things
-- off-by-one errors
-
-
-## Proxy Caching (`proxyCache`)
-
-In [Topic 4](/contributing/04-reactivity), we saw how `reactive()` wraps objects in a Proxy.
-However, a common issue in reactive programming is trying to wrap the same object multiple
-times, or dealing with circular references
-(e.g. Object A points to Object B, and Object B points back to Object A).
-
-### The Problem: Infinite Recursion
-
-Without a cache, every time you access a nested object, the `get` trap would create a **new** Proxy wrapper.
-
-```js
-// Without a cache:
-const p1 = state.user; 
-const p2 = state.user;
-console.log(p1 === p2); // false! They are different "guards" for the same data.
-
-```
-
-This wastes memory and breaks object identity. Even worse, if an object points to itself, the code would keep creating Proxies until the browser crashed with a "Maximum call stack size exceeded" error.
-
-### The Solution: `proxyCache`
-
-The library uses `const proxyCache = new WeakMap()` to keep track of every object it has already turned into a Proxy.
-
-1.  **Checking the Map**: At the very start of the `reactive()` function, the code checks: `if (proxyCache.has(obj)) return proxyCache.get(obj);`.
-    
-2.  **Storing the Result**: If it's a new object, the code creates the Proxy and then immediately saves it: `proxyCache.set(obj, p);`.
-    
-3.  **The Result**: If you access `state.user` 100 times, you get the exact same Proxy instance every time. It ensures that `p1 === p2` is always `true`.
-    
-
-### Why a `WeakMap`?
-
-This is a critical "expert-level" choice.
-
--   A regular `Map` holds a "strong reference" to its keys. If you deleted a piece of data from your state, but that data was still a key in a regular `Map`, the browser could never delete it from memory.
-    
--   Because `proxyCache` is a `WeakMap`, as soon as your component is destroyed and the original object is no longer needed, the browser’s Garbage Collector can automatically wipe it from the cache.
-    
-
-### Summary of Logic:
-
--   **Step 1:** Request to make `obj` reactive.
-    
--   **Step 2:** Check `proxyCache`. Found it? Return the existing Proxy.
-    
--   **Step 3:** Not found? Create a new Proxy.
-    
--   **Step 4:** Store `obj -> Proxy` in `proxyCache`.
-    
--   **Step 5:** Return the new Proxy.