lego-dom 1.3.4 → 1.5.0

package/docs/api/config.md

@@ -1,95 +0,0 @@
-# Global Configuration
-
-`Lego.config` allows you to customize framework behavior, including error handling and metrics.
-
-## Properties
-
-### `syntax`
-
-*   **Type**: `'mustache' | 'brackets'`
-*   **Default**: `'brackets'`
-
-Configures the template delimiter style.
-
-*   `'brackets'`: Uses <code v-pre>[[ variable ]]</code> (Default)
-*   `'mustache'`: Uses <code v-pre>{{ variable }}</code> (Legacy/Vue-style)
-
-```javascript
-// Switch back to mustache syntax if preferred
-Lego.config.syntax = 'mustache';
-```
-
-### `loader`
-
-*   **Type**: `(tagName: string) => string | Promise<string> | null`
-*   **Default**: `undefined`
-
-Use this hook to implement **Server-Side Component Delivery**.
-
-**Option 1: Simple Mode (Return URL)**
-We fetch it for you.
-```javascript
-loader: (tag) => `/components/${tag}.lego`
-```
-
-**Option 2: Power Mode (Return Promise)**
-You control the fetch. Useful for **Authentication** (Cookies, JWT) or Custom Headers.
-
-```javascript
-Lego.init(document.body, {
-  loader: async (tagName) => {
-    // Custom Authenticated Fetch
-    const res = await fetch(`/components/${tagName}.lego`, {
-      credentials: 'include', // Send Cookies
-      headers: { 'Authorization': getToken() }
-    });
-    return await res.text(); // Return SFC content directly
-  }
-});
-```
-**Mechanism:**
-1. Browser sees unknown `<admin-widget>`.
-2. `Lego` calls `config.loader('admin-widget')`.
-3. If URL returned, it fetches the file.
-4. The server returns raw SFC content (`<template>...`).
-5. `Lego.defineSFC()` parses and upgrades the element instantly.
-
-### `onError`
-
-*   **Type**: `(error: Error, type: string, context: HTMLElement) => void`
-*   **Default**: `undefined`
-
-Global error handler hook. Called when an error occurs during:
-*   `render`: Template rendering (expression evaluation)
-*   `event-handler`: `@event` callbacks
-*   `define`: Component definition
-*   `sync-update`: `b-sync` updates
-
-```javascript
-Lego.config.onError = (err, type, context) => {
-  console.error(`Error in ${type}:`, err);
-  // Send to Sentry/Datadog
-  captureException(err, { tags: { type } });
-};
-```
-
-### `metrics`
-
-*   **Type**: `Object`
-
-Performance monitoring hooks, primarily used by plugins.
-
-*   `onRenderStart(el)`: Called before a component renders.
-*   `onRenderEnd(el)`: Called after a component finishes rendering.
-
-```javascript
-// Example monitoring implementation
-Lego.config.metrics = {
-  onRenderStart(el) {
-    console.time(el.tagName);
-  },
-  onRenderEnd(el) {
-    console.timeEnd(el.tagName);
-  }
-};
-```

package/docs/api/define.md

@@ -1,58 +0,0 @@
-# Lego.define()
-
-Defining components in JavaScript.
-
-## Type Signature
-
-```ts
-Lego.define(tagName: string, template: string, state?: object)
-```
-
-## Arguments
-
-- **tagName**: The name of the custom element (must contain a hyphen).
-- **template**: The HTML string for the component. Can include `<style>`, markup, and bindings.
-- **state**: Initial state object and methods.
-
-## Example
-
-```js
-import { Lego } from 'lego-dom';
-
-Lego.define('user-card', `
-  <div class="card">
-    <h3>[[ name ]]</h3>
-    <p>[[ role ]]</p>
-  </div>
-`, {
-  name: 'John Doe',
-  role: 'Admin'
-});
-```
-
-## Lego.defineSFC()
-
-Runtime parser for Single File Components (SFC). Useful for **Server-Side Rendering** or dynamic loading architectures.
-
-```ts
-Lego.defineSFC(content: string, filename?: string)
-```
-
-### Example
-
-```javascript
-const sfc = `
-<template>
-  <h1>[[ title ]]</h1>
-</template>
-<script>
-  export default { title: 'Hello World' }
-</script>
-<style>
-  h1 { color: red; }
-</style>
-`;
-
-// Registers <my-component> instantly
-Lego.defineSFC(sfc, 'my-component.lego');
-```

package/docs/api/directives.md

@@ -1,50 +0,0 @@
-# Directives
-
-Special attributes that control DOM behavior.
-
-## b-show
-
-Conditionally render an element.
-
-```html
-<div b-show="loading">Loading...</div>
-<div b-show="!loading">Content loaded!</div>
-```
-
-## b-html
-
-Renders raw HTML. **Security Risk**: Use with caution.
-
-```html
-<div b-html="htmlContent"></div>
-```
-
-## b-for
-
-Render a list of items.
-
-```html
-<ul>
-  <li b-for="user in users">
-    [[ user.name ]]
-  </li>
-</ul>
-```
-
-## b-sync
-
-Two-way data binding for form inputs.
-
-```html
-<input b-sync="username" placeholder="Enter username">
-<p>You typed: [[ username ]]</p>
-```
-
-## @event
-
-Event listeners.
-
-```html
-<button @click="save()">Save</button>
-<input @input="validate($event)">
-```

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.