lego-dom 1.3.4 → 1.5.0

package/docs/guide/index.md

@@ -1,88 +0,0 @@
-# What is Lego?
-
-LegoDOM is a tiny, zero-dependency JavaScript library for building reactive Web Components directly in the browser.
-
-## The Philosophy
-
-LegoDOM is built on a simple belief: **the DOM is not your enemy**.
-
-Modern frameworks introduced virtual DOMs and compilation steps to solve problems that arose from trying to make the DOM do things it wasn't designed for. Lego takes a different approach—it embraces the DOM and Web Components as they were intended to be used.
-
-## Key Principles
-
-### 1. Mental Model Simplicity
-
-There are no new concepts to learn. If you know:
-- HTML
-- JavaScript objects
-- Basic DOM events
-
-You already know Lego.
-
-### 2. No Build Step Required
-
-Drop a `<script>` tag in your HTML and you're ready to go. Build tools are optional, not mandatory.
-
-### 3. True Reactivity
-
-Change an object → the DOM updates. That's it. No `setState`, no `dispatch`, no `computed properties` to configure.
-
-```js
-// This just works
-component._studs.count++;
-```
-
-### 4. Web Standards First
-
-Lego uses:
-- **Web Components** - Standard custom elements
-- **Shadow DOM** - Native encapsulation
-- **ES6 Proxies** - For reactivity
-- **Template literals** - For templating
-
-No proprietary APIs. Everything is built on web standards.
-
-## When to Use Lego
-
-### ✅ Lego is Great For:
-
-- **Small to medium applications** where framework overhead isn't worth it
-- **Embedded widgets** that need to work anywhere
-- **Progressive enhancement** of existing sites
-- **Learning** how reactive systems work under the hood
-- **Projects** where you want full control and no dependencies
-
-### ⚠️ Consider Alternatives If:
-
-- You need a massive ecosystem of pre-built components
-- Your team is already invested in React/Vue/Angular
-- You need SSR (Server-Side Rendering) out of the box
-- You're building something extremely complex with hundreds of components
-
-## How Small Is It?
-
-The core library (`main.js`) is **under 500 lines** of well-commented JavaScript.
-
-- **No dependencies** - Zero `node_modules` bloat
-- **~22KB** - Unminified, human-readable code
-- **~7KB** - Minified and gzipped
-
-Compare that to:
-- Vue 3: ~33KB (minified + gzipped)
-- React + ReactDOM: ~40KB (minified + gzipped)
-- Angular: ~100KB+ (minified + gzipped)
-
-## What Makes It Different?
-
-| Aspect | Lego | Traditional Frameworks |
-|--------|--------|----------------------|
-| **Reactivity** | Direct object mutation | setState / dispatch / ref() |
-| **Templates** | HTML with <code v-pre>[[ ]]</code> | JSX / template syntax |
-| **Styles** | Shadow DOM (native) | CSS-in-JS / scoped CSS |
-| **Build** | Optional | Required |
-| **Learning Curve** | Hours | Days/Weeks |
-|**Philosophy** | Embrace the platform | Abstract the platform |
-
-## Next Steps
-
-Ready to dive in? Head to the [Getting Started](/guide/getting-started) guide to build your first component in under 5 minutes.

package/docs/guide/lifecycle.md

@@ -1,525 +0,0 @@
-# Lifecycle Hooks
-
-Learn about component lifecycle hooks in Lego.
-
-## Overview
-
-Components have three lifecycle hooks:
-
-- `mounted()` - Called after component is added to DOM
-- `updated()` - Called after state changes and re-render
-- `unmounted()` - Called when component is removed from DOM
-
-## mounted()
-
-Called once when the component is first attached to the DOM.
-
-### Usage
-
-```js
-{
-  data: null,
-  
-  mounted() {
-    console.log('Component is now in the DOM');
-    this.fetchData();
-  },
-  
-  async fetchData() {
-    this.data = await fetch('/api/data').then(r => r.json());
-  }
-}
-```
-
-### Common Use Cases
-
-**Fetch Data:**
-```js
-{
-  mounted() {
-    this.loadUserData();
-  }
-}
-```
-
-**Start Timers:**
-```js
-{
-  timer: null,
-  
-  mounted() {
-    this.timer = setInterval(() => {
-      this.tick();
-    }, 1000);
-  }
-}
-```
-
-**Add Event Listeners:**
-```js
-{
-  mounted() {
-    window.addEventListener('resize', this.handleResize.bind(this));
-  }
-}
-```
-
-**Initialize Third-Party Libraries:**
-```js
-{
-  mounted() {
-    this.chart = new Chart(this.$element.shadowRoot.querySelector('canvas'), {
-      type: 'bar',
-      data: this.chartData
-    });
-  }
-}
-```
-
-## updated()
-
-Called after every state change and re-render.
-
-### Usage
-
-```js
-{
-  count: 0,
-  
-  updated() {
-    console.log('Component re-rendered, count is:', this.count);
-  }
-}
-```
-
-### Common Use Cases
-
-**Track Changes:**
-```js
-{
-  previousValue: null,
-  value: 0,
-  
-  updated() {
-    if (this.value !== this.previousValue) {
-      console.log('Value changed from', this.previousValue, 'to', this.value);
-      this.previousValue = this.value;
-    }
-  }
-}
-```
-
-**Update Third-Party Libraries:**
-```js
-{
-  chartData: [],
-  
-  updated() {
-    if (this.chart) {
-      this.chart.data = this.chartData;
-      this.chart.update();
-    }
-  }
-}
-```
-
-**Analytics:**
-```js
-{
-  updated() {
-    if (window.gtag) {
-      gtag('event', 'state_change', {
-        component: 'my-component',
-        count: this.count
-      });
-    }
-  }
-}
-```
-
-::: warning Performance
-`updated()` runs on every state change. Keep it lightweight!
-:::
-
-## unmounted()
-
-Called when the component is removed from the DOM.
-
-### Usage
-
-```js
-{
-  unmounted() {
-    console.log('Component is being removed');
-    this.cleanup();
-  }
-}
-```
-
-### Common Use Cases
-
-**Clear Timers:**
-```js
-{
-  timer: null,
-  
-  mounted() {
-    this.timer = setInterval(() => this.tick(), 1000);
-  },
-  
-  unmounted() {
-    clearInterval(this.timer);
-  }
-}
-```
-
-**Remove Event Listeners:**
-```js
-{
-  handleResize: null,
-  
-  mounted() {
-    this.handleResize = () => {
-      this.width = window.innerWidth;
-    };
-    window.addEventListener('resize', this.handleResize);
-  },
-  
-  unmounted() {
-    window.removeEventListener('resize', this.handleResize);
-  }
-}
-```
-
-**Destroy Third-Party Instances:**
-```js
-{
-  chart: null,
-  
-  mounted() {
-    this.chart = new Chart(...);
-  },
-  
-  unmounted() {
-    if (this.chart) {
-      this.chart.destroy();
-    }
-  }
-}
-```
-
-**Cancel Pending Requests:**
-```js
-{
-  controller: null,
-  
-  async fetchData() {
-    this.controller = new AbortController();
-    try {
-      const data = await fetch('/api/data', {
-        signal: this.controller.signal
-      }).then(r => r.json());
-      this.data = data;
-    } catch (err) {
-      if (err.name === 'AbortError') {
-        console.log('Fetch aborted');
-      }
-    }
-  },
-  
-  unmounted() {
-    if (this.controller) {
-      this.controller.abort();
-    }
-  }
-}
-  }
-}
-```
-
-## Performance Hooks (Metrics)
-
-For advanced monitoring, LegoDOM provides global hooks in `Lego.config.metrics`. These run for **every** component.
-
-### `onRenderStart` & `onRenderEnd`
-
-Useful for tracking how long renders take, which helps identify slow components.
-
-```javascript
-Lego.config.metrics = {
-  onRenderStart(el) {
-    console.time(`render-${el.tagName}`);
-  },
-  onRenderEnd(el) {
-    console.timeEnd(`render-${el.tagName}`);
-  }
-};
-```
-
-### `onAllSettled` (New in v2.0)
-
-Called when the entire component tree (including Shadow DOM children) has finished its initial render pass. This is perfect for removing loading spinners or measuring "Time to Interactive".
-
-```javascript
-/* main.js */
-Lego.init(document.body).then(() => {
-  document.getElementById('global-loader').remove();
-});
-```
-
-## Lifecycle Flow
-
-```
-1. Component created (HTML element instantiated)
-2. Shadow DOM attached
-3. Template rendered
-4. mounted() hook called → Component is interactive
-5. User interaction / state change
-6. Component re-rendered
-7. updated() hook called
-8. (repeat steps 5-7 as needed)
-9. Component removed from DOM
-10. unmounted() hook called → Cleanup
-```
-
-## Complete Example
-
-```js
-{
-  // State
-  count: 0,
-  timer: null,
-  data: null,
-  
-  // Lifecycle: Component mounted
-  mounted() {
-    console.log('[mounted] Component added to DOM');
-    
-    // Fetch initial data
-    this.fetchData();
-    
-    // Start interval
-    this.timer = setInterval(() => {
-      this.count++;
-    }, 1000);
-    
-    // Add event listener
-    this.handleKeyPress = (e) => {
-      if (e.key === 'Escape') {
-        this.reset();
-      }
-    };
-    document.addEventListener('keydown', this.handleKeyPress);
-  },
-  
-  // Lifecycle: Component updated
-  updated() {
-    console.log('[updated] Component re-rendered, count:', this.count);
-    
-    // Log when count reaches milestone
-    if (this.count % 10 === 0) {
-      console.log('Milestone:', this.count);
-    }
-  },
-  
-  // Lifecycle: Component unmounted
-  unmounted() {
-    console.log('[unmounted] Component removed from DOM');
-    
-    // Clear interval
-    if (this.timer) {
-      clearInterval(this.timer);
-    }
-    
-    // Remove event listener
-    document.removeEventListener('keydown', this.handleKeyPress);
-  },
-  
-  // Methods
-  async fetchData() {
-    this.data = await fetch('/api/data').then(r => r.json());
-  },
-  
-  reset() {
-    this.count = 0;
-  }
-}
-```
-
-## Best Practices
-
-### 1. Initialize in mounted()
-
-Don't fetch data or start timers in the state object:
-
-```js
-// ❌ Bad
-{
-  data: fetch('/api/data').then(r => r.json()),  // Executes immediately
-  timer: setInterval(() => {}, 1000)  // Starts before component exists
-}
-
-// ✅ Good
-{
-  data: null,
-  timer: null,
-  mounted() {
-    this.fetchData();
-    this.timer = setInterval(() => {}, 1000);
-  }
-}
-```
-
-### 2. Always Clean Up
-
-If you start something in `mounted()`, stop it in `unmounted()`:
-
-```js
-{
-  mounted() {
-    this.timer = setInterval(...);
-    window.addEventListener('resize', this.handleResize);
-  },
-  
-  unmounted() {
-    clearInterval(this.timer);  // ✅
-    window.removeEventListener('resize', this.handleResize);  // ✅
-  }
-}
-```
-
-### 3. Keep updated() Light
-
-`updated()` runs frequently—avoid heavy operations:
-
-```js
-// ❌ Bad
-{
-  updated() {
-    this.expensiveCalculation();  // Runs on every change!
-  }
-}
-
-// ✅ Good
-{
-  updated() {
-    // Only log or track
-    console.log('State changed');
-  }
-}
-```
-
-### 4. Guard Against Errors
-
-```js
-{
-  unmounted() {
-    // Check before clearing
-    if (this.timer) {
-      clearInterval(this.timer);
-    }
-    
-    // Check before destroying
-    if (this.chart) {
-      this.chart.destroy();
-    }
-  }
-}
-```
-
-## Common Patterns
-
-### Loading State
-
-```js
-{
-  loading: true,
-  data: null,
-  
-  async mounted() {
-    try {
-      this.data = await fetch('/api/data').then(r => r.json());
-    } finally {
-      this.loading = false;
-    }
-  }
-}
-```
-
-### Polling
-
-```js
-{
-  pollInterval: null,
-  
-  mounted() {
-    this.poll();
-    this.pollInterval = setInterval(() => this.poll(), 5000);
-  },
-  
-  async poll() {
-    this.data = await fetch('/api/status').then(r => r.json());
-  },
-  
-  unmounted() {
-    clearInterval(this.pollInterval);
-  }
-}
-```
-
-### Scroll Position
-
-```js
-{
-  scrollY: 0,
-  handleScroll: null,
-  
-  mounted() {
-    this.handleScroll = () => {
-      this.scrollY = window.scrollY;
-    };
-    window.addEventListener('scroll', this.handleScroll);
-  },
-  
-  unmounted() {
-    window.removeEventListener('scroll', this.handleScroll);
-  }
-}
-```
-
-### Animation
-
-```js
-{
-  mounted() {
-    const el = this.$element.shadowRoot.querySelector('.animated');
-    el.classList.add('fade-in');
-  }
-}
-```
-
-## Debugging Lifecycle
-
-Log lifecycle events to understand component behavior:
-
-```js
-{
-  mounted() {
-    console.log('[LIFECYCLE] mounted');
-  },
-  
-  updated() {
-    console.log('[LIFECYCLE] updated');
-  },
-  
-  unmounted() {
-    console.log('[LIFECYCLE] unmounted');
-  }
-}
-```
-
-## Next Steps
-
-- See [lifecycle examples](/examples/)
-- Learn about [component patterns](/guide/components)
-- Explore [state management](/guide/reactivity)

package/docs/guide/quick-start.md

@@ -1,49 +0,0 @@
-# Quick Start
-
-The fastest way to get started with Lego is using the CDN. No build tools required!
-
-## 1. Create an HTML file
-
-```html
-<!DOCTYPE html>
-<html lang="en">
-<head>
-    <meta charset="UTF-8">
-    <title>Lego Quick Start</title>
-</head>
-<body>
-    <!-- Interpolation works here too -->
-    <hello-world name="Lego"></hello-world>
-
-    <!-- 3. Define the template -->
-    <template b-id="hello-world">
-        <style>
-            h1 { color: #646cff; }
-        </style>
-        <h1>Hello [[ name ]]!</h1>
-        <button @click="count++">Count is [[ count ]]</button>
-    </template>
-
-    <!-- 4. Load Lego -->
-    <script src="https://unpkg.com/lego-dom/main.js"></script>
-    
-    <!-- 5. Define logic & Init -->
-    <script>
-        document.querySelector('hello-world').state = {
-            name: 'World',
-            toggle() {
-                this.name = this.name === 'World' ? 'Lego' : 'World';
-            }
-        };
-
-        // Start the engine
-        Lego.init();
-    </script>
-</body>
-</html>
-```
-
-## Next Steps
-
-- Explore [Core Concepts](/guide/components)
-- Check out the [API Reference](/api/)