lego-dom 1.3.3 → 1.4.0

package/docs/guide/directory-structure.md

@@ -1,248 +0,0 @@
-# Chaos Tends To A Minimum
-
-> [!NOTE] This is a Recommendation, Not a Bible
-> This page is one person's take on how to structure large LegoDOM applications. It is not enforced by the framework. You are encouraged to adapt, improve, or completely ignore it. If you find a better pattern, please share it.
-
----
-
-In LegoDOM land everything is a `.lego`. A `block` is a lego, a `widget` is a lego, a `component` is a lego, a `page` is a lego.
-
-But what do they *mean*?
-
-
-## The Four Levels
-
-| Level | Role | Knows About | Example |
-| :--- | :--- | :--- | :--- |
-| **Block** | Identity | Its own visuals | `<block-avatar>`, `<block-button>` |
-| **Widget** | Intent | How an interaction works | `<widget-file-trigger>`, `<widget-dropdown>` |
-| **Component** | Computation | Business data & API calls | `<comp-profile-settings>`, `<comp-checkout-form>` |
-| **Page** | Coordination | Layout & Routing | `<page-dashboard>`, `<page-login>` |
-
-
-## The Litmus Test: The Avatar Upload
-
-**The Question:**
-> I have an avatar. When I click it, it opens a file picker. When the file changes, it POSTs to `/v1/avatars`. What is it? A Block? A Widget? A Component?
-
-**The Technical Answer:** `main.js` allows all of this in one file. It will work.
-
-**The Architectural Answer:** You have conflated three distinct responsibilities into one:
-1.  **Identity** Looking like an avatar.
-2.  **Intent** Picking a file.
-3.  **Computation** Saving to *your specific server*.
-
-**The Consequence:**
-If you later want to display that avatar in a read-only user list, you *cannot reuse this component* because clicking it triggers unwanted upload logic. You will be forced to create a new, duplicate `<block-avatar>` just for display.
-
-### The "Lego Way" Solution
-
-Split this into its three atomic truths to maximize reusability.
-
-#### 1. The Block (Identity)
-
-```html
-<!-- block-avatar.lego -->
-<template>
-  <img class="avatar" src="[[ src ]]" alt="[[ alt ]]">
-</template>
-
-<style>
-  .avatar { width: 48px; height: 48px; border-radius: 50%; object-fit: cover; }
-</style>
-
-<script>
-export default {
-  src: '/default-avatar.png',
-  alt: 'User'
-}
-</script>
-```
--   **Role:** Just the visuals. Circular crop, fallback, size classes.
--   **Logic:** None. Zero business knowledge.
--   **Reusability:** Used *everywhere* e.g. Navbar, User List, Profile Page, Comments.
-
-#### 2. The Widget (Intent)
-
-```html
-<!-- widget-file-trigger.lego -->
-<template>
-  <div @click="openPicker()">
-    <slot></slot>
-    <input type="file" style="display:none" b-var="avatarFileElement" @change="onFileChange">
-  </div>
-</template>
-
-<script>
-export default {
-  openPicker() {
-    this.$vars.avatarFileElement.click();
-  },
-  onFileChange(event) {
-    // It doesn't know about /v1/avatars. It just hands you the file.
-    this.$emit('file-selected', { file: event.target.files[0] });
-  }
-}
-</script>
-```
--   **Role:** The mechanic. Wraps any slotted content and makes it clickable to open a file dialog.
--   **Logic:** Handles the hidden `<input type="file">`, listens for `change`, and **emits an event**.
--   **Boundary:** It uses `$emit` (from `main.js`) to broadcast what happened. It never makes API calls.
-
-#### 3. The Component (Computation a.k.a. Context)
-
-```html
-<!-- comp-profile-settings.lego -->
-<template>
-  <h2>Your Profile</h2>
-  <widget-file-trigger @file-selected="uploadAvatar">
-    <block-avatar src="[[ user.avatarUrl ]]"></block-avatar>
-  </widget-file-trigger>
-  <p>Click avatar to change</p>
-</template>
-
-<script>
-export default {
-  user: { avatarUrl: '/me.jpg' },
-
-  async uploadAvatar(event) {
-    const file = event.detail.file;
-    // BUSINESS LOGIC LIVES HERE
-    const formData = new FormData();
-    formData.append('avatar', file);
-    const res = await fetch('/v1/avatars', { method: 'POST', body: formData });
-    const data = await res.json();
-    this.user.avatarUrl = data.url; // Reactivity updates the block-avatar
-  }
-}
-</script>
-```
--   **Role:** The boss. Assembles the parts and owns the API call.
--   **Logic:** Knows about `user`, knows about `/v1/avatars`, handles the business outcome.
--   **Boundary:** This is the *only* place that knows about your specific backend.
-
-
-## The Definitions
-
-### Blocks (Atoms)
-
-> **TL;DR** A Block is an irreducible thing. A UI with identity, but no narrative intent.
-
-A Block cannot be broken down into smaller Blocks. It is self-contained.
-
--   **State:** Visual only. It can track "Is my mouse over me?" or "Am I spinning?". It never knows about User IDs, Auth tokens, or business data.
--   **Naming:** `block-avatar`, `block-button`, `block-spinner`, `block-card`.
--   **Rule:** If you find yourself nesting Blocks inside other Blocks, you have graduated to a Widget.
-
-> [!WARNING] Don't Confuse Styling with Blocks
-> You can use CSS to style many `<h1>` elements. That doesn't mean you need a `<block-title-header>`. Only create a Block when it has distinct *behavior* or *identity* beyond mere styling.
-
-
-### Widgets (Molecules)
-
-> **TL;DR** A Widget is an interaction, not a thing.
-
-A Widget gives Blocks a reason to exist together. It defines *how* an interaction works without embedding *who* it's for or *what* business outcome it serves.
-
--   **State:** Internal UI state only. "Is the dropdown open?" "Which tab is active?"
--   **Naming:** `widget-dropdown`, `widget-modal`, `widget-datepicker`, `widget-file-trigger`.
--   **Rule:** Widgets are portable. You should be able to copy a Widget to a completely different project and it should still work.
--   **Communication:** Uses `$emit()` to broadcast events. Never makes API calls itself.
-
-
-### Components (Organisms)
-
-> **TL;DR** Components are where your app features come to life.
-
-A Component is a Widget (or set of Widgets) bound to specific data, rules, and responsibility. It's where interaction becomes meaningful to *this* application.
-
--   **State:** Domain-specific. Owns data fetched from APIs. Knows about the current user.
--   **Naming:** `comp-profile-settings`, `comp-order-history`, `comp-payroll-table`.
--   **Rule:** A Component knows *who* it is for, *what* data it owns, and *what* outcome it must produce.
--   **Communication:** Listens to Widget events (like `@file-selected`) and performs business transactions.
-
-
-### Pages (Coordination)
-
-> **TL;DR** A Page is the top-level host that routing targets.
-
-Pages are the uppermost hosts. They orchestrate the layout of Components within the context of a LegoDOM application.
-
--   **Role:** Define the grid. Orchestrate Components. Handle route parameters.
--   **Naming:** `page-dashboard`, `page-login`, `page-user-profile`.
--   **Rule:** Pages are the *only* UI units directly known to `<lego-router>`. While a Component owns the *logic* of a feature, a Page owns the *real estate*.
-
-
-## Recommended Directory Structure
-
-```text
-src/
-├── blocks/           # Design System primitives
-│   ├── block-avatar.lego
-│   ├── block-button.lego
-│   └── block-input.lego
-├── widgets/          # Generic, portable UI tools
-│   ├── widget-dropdown.lego
-│   ├── widget-modal.lego
-│   └── widget-file-trigger.lego
-├── components/       # Domain-specific features
-│   ├── comp-profile-settings.lego
-│   └── comp-order-history.lego
-├── pages/            # Route targets
-│   ├── page-dashboard.lego
-│   └── page-login.lego
-└── main.js           # App entry, routes, globals
-
-
-## Scaling to Multi-Domain Apps
-
-For large enterprise apps with multiple business domains (HRIS, Finance, Planning, Messages), the flat structure breaks down. Use a **Domain-First** approach.
-
-### Domain-First Structure
-
-```text
-src/
-├── shared/                    # Truly universal (used by 3+ domains)
-│   ├── blocks/
-│   │   ├── block-button.lego
-│   │   └── block-avatar.lego
-│   └── widgets/
-│       ├── widget-datepicker.lego
-│       └── widget-modal.lego
-│
-├── hris/                      # Human Resources domain
-│   ├── blocks/
-│   ├── widgets/
-│   │   └── widget-leave-calendar.lego
-│   ├── components/
-│   │   └── comp-employee-list.lego
-│   └── pages/
-│       └── page-employees.lego
-│
-├── finance/                   # Finance domain
-│   ├── widgets/
-│   ├── components/
-│   └── pages/
-│
-├── planning/                  # Planning domain
-│   ├── widgets/
-│   ├── components/
-│   └── pages/
-│
-└── main.js
-```
-
-### Rules for Multi-Domain
-
-1. **Shared** = Only what is used by 3+ domains. Be ruthless.
-2. **Domain folders** = Each domain owns its own `blocks/`, `widgets/`, `components/`, `pages/`.
-3. **No cross-domain Component imports.** If HRIS needs Finance data, go through a shared service or global state, not by importing `finance/components/...`.
-
-
-## Summary
-
-| If you keep it all in one file... | The "Enterprise" Standard |
-| :--- | :--- |
-| Name it `<comp-avatar-upload>` and accept it is not reusable. | Let the **Widget** handle the interaction. Let the **Component** handle the transaction. |
-
-**This is a recommendation.** If you find a pattern that works better for your team, use it. The goal is clarity, reusability, and reducing arguments - not rigid adherence to a doctrine.

package/docs/guide/faq.md

@@ -1,210 +0,0 @@
-# Frequently Asked Questions
-
-Quick answers to the most common LegoDOM questions.
-
-## Project Setup
-
-### Where do I define my routes?
-
-**In your entry file (`app.js` or `main.js`), before `Lego.init()`.**
-
-```javascript
-// src/app.js
-import { Lego } from 'lego-dom';
-import registerComponents from 'virtual:lego-components';
-
-registerComponents();
-
-// Define routes HERE ⭐
-Lego.route('/', 'home-page');
-Lego.route('/login', 'login-page');
-Lego.route('/users/:id', 'user-profile');
-
-await Lego.init();  // Must come AFTER routes
-```
-
-### Where does my config go?
-
-Everything related to app configuration belongs in your entry file:
-
-| What | Where |
-|------|-------|
-| Component registration | `registerComponents()` |
-| Route definitions | `Lego.route(...)` |
-| Global state init | `Lego.globals.user = null` |
-| Engine start | `Lego.init()` |
-
-### Should I use `main.js` or `app.js`?
-
-Either works! It's just a naming convention. Use whatever your Vite template created, or rename it. Just make sure your `index.html` points to it:
-
-```html
-<script type="module" src="/src/app.js"></script>
-```
-
----
-
-## Components
-
-### Why isn't my component showing?
-
-Check these common issues:
-
-1. **No route defined** – Did you add `Lego.route('/', 'my-component')`?
-2. **Missing `<lego-router>`** – Your HTML needs `<lego-router></lego-router>`
-3. **Wrong component name** – Filename `user-card.lego` → component `<user-card>`
-4. **Not registered** – Did you call `registerComponents()` before `init()`?
-
-### Why do component names need hyphens?
-
-It's a Web Components standard! Custom elements must contain a hyphen to avoid conflicts with future HTML elements.
-
-✅ Valid: `user-card`, `app-nav`, `my-button`  
-❌ Invalid: `usercard`, `Card`, `button`
-
-### Can I use PascalCase filenames?
-
-Yes! LegoDOM automatically converts:
-- `UserCard.lego` → `<user-card>`
-- `AppNav.lego` → `<app-nav>`
-- `my_component.lego` → `<my-component>`
-
----
-
-## Navigation
-
-### How do I navigate between pages?
-
-**Option 1: Declarative (in templates)**
-```html
-<a href="/login" b-link>Go to Login</a>
-```
-
-**Option 2: Programmatic (in JavaScript)**
-```javascript
-this.$go('/login').get();
-```
-
-### What's the difference between `b-link` and `b-target`?
-
-| Attribute | What it does |
-|-----------|--------------|
-| `b-link` | SPA navigation, updates URL, swaps `<lego-router>` |
-| `b-target="#id"` | Swaps content of specific element, updates URL |
-| `b-target="#id" b-link="false"` | Swaps content, does NOT update URL |
-
-### How do I pass data when navigating?
-
-Use global state:
-
-```javascript
-// Before navigating
-Lego.globals.selectedUser = { id: 42, name: 'John' };
-this.$go('/user-details').get();
-
-// In the target component
-mounted() {
-  console.log(Lego.globals.selectedUser.name);  // 'John'
-}
-```
-
-Or use route parameters:
-
-```javascript
-// Route: Lego.route('/users/:id', 'user-profile')
-this.$go('/users/42').get();
-
-// In user-profile component
-mounted() {
-  const userId = this.$route.params.id;  // '42'
-}
-```
-
----
-
-## State
-
-### How do I share data between components?
-
-Use `Lego.globals`:
-
-```javascript
-// Component A sets it
-Lego.globals.user = { name: 'John' };
-
-// Component B reads it
-console.log(Lego.globals.user.name);  // 'John'
-
-// In templates
-<p>Hello, [[ global.user.name ]]!</p>
-```
-
-### Why isn't my data updating the view?
-
-Make sure you're mutating the reactive object, not replacing references:
-
-```javascript
-// ✅ This works - mutating property
-this.items.push(newItem);
-this.user.name = 'Jane';
-
-// ❌ This might not work - reassigning local variable
-let items = this.items;
-items.push(newItem);  // Won't trigger re-render!
-```
-
----
-
-## Styling
-
-### What is `self` in styles?
-
-`self` is a special keyword that targets the component's root element (like `:host` in Shadow DOM):
-
-```html
-<style>
-  self {
-    display: block;
-    padding: 1rem;
-  }
-</style>
-```
-
-LegoDOM automatically transforms this to `:host` for Shadow DOM.
-
-### Do styles leak to other components?
-
-No! Styles are scoped via Shadow DOM. Your `.button` class won't affect buttons in other components.
-
----
-
-## Build & Development
-
-### Can I use LegoDOM without Vite?
-
-Yes! Use the CDN approach:
-
-```html
-<script src="https://unpkg.com/lego-dom/main.js"></script>
-<template b-id="my-component">...</template>
-<my-component></my-component>
-<script>Lego.init();</script>
-```
-
-See [CDN Usage](/guide/cdn-usage) for details.
-
-### Why use Vite?
-
-Benefits of Vite + `.lego` files:
-- **Hot reload** – Changes appear instantly
-- **Auto-discovery** – No manual component registration
-- **Better organization** – One file per component
-- **Syntax highlighting** – Editor support for `.lego` files
-
----
-
-## Still Stuck?
-
-- 📖 [Complete Tutorial](/tutorial/) – Build an app step-by-step
-- 💬 [GitHub Discussions](https://github.com/rayattack/LegoDOM/discussions)
-- 🐛 [Report Issues](https://github.com/rayattack/LegoDOM/issues)

package/docs/guide/getting-started.md

@@ -1,262 +0,0 @@
-# Getting Started
-
-Get up and running with Lego in under 5 minutes.
-
-::: tip 🚀 Want a Complete Walkthrough?
-Check out our **[Step-by-Step Tutorial](/tutorial/)** – build a full multi-page app from scratch in 15 minutes!
-:::
-
-## Installation
-
-### Option 1: CDN (No Build Tools)
-
-The fastest way to try Lego is via CDN:
-
-```html
-<!DOCTYPE html>
-<html>
-<head>
-  <title>My Lego App</title>
-</head>
-<body>
-  <my-component></my-component>
-  
-  <script src="https://unpkg.com/lego-dom/main.js"></script>
-  <template b-id="my-component" b-data="{ count: 0 }">
-    <h1>Hello Lego!</h1>
-    <button @click="count++">Click me</button>
-    <p>Count: [[ count ]]</p>
-  </template>
-</body>
-</html>
-```
-
-That's it! Open this HTML file in any browser and it works.
-
-### Option 2: npm
-
-For projects using npm:
-
-```bash
-npm install lego-dom
-```
-
-Then import it:
-
-```js
-import { Lego } from 'lego-dom';
-
-Lego.define('my-component', `
-  <h1>Hello Lego!</h1>
-  <button @click="count++">Click me</button>
-  <p>Count: [[ count ]]</p>
-`, {
-  count: 0,
-});
-```
-
-### Option 3: With Vite (Recommended for Larger Projects)
-
-For the best development experience with `.lego` Single File Components:
-
-```bash
-npm create vite@latest my-lego-app
-cd my-lego-app
-npm install lego-dom
-```
-
-Configure `vite.config.js`:
-
-```js
-import { defineConfig } from 'vite';
-import legoPlugin from 'lego-dom/vite-plugin';
-
-export default defineConfig({
-  plugins: [legoPlugin()]
-});
-```
-
-### The Runtime Engine
-
-Crucially, you must initialize the Lego background engine in your entry file (`src/main.js`):
-
-```js
-import { Lego } from 'lego-dom';
-import registerComponents from 'virtual:lego-components';
-
-// 1. Register SFCs
-registerComponents();
-
-// 2. Start the Engine (Async)
-await Lego.init();
-```
-
-## Your First Component
-
-Let's create a simple counter component.
-
-### Using HTML Templates
-
-```html
-<template b-id="click-counter" b-data="{ message: 'Welcome!', count: 0 }">
-  <style>
-    self {
-      display: block;
-      padding: 2rem;
-      text-align: center;
-      background: #f0f0f0;
-      border-radius: 8px;
-    }
-    button {
-      font-size: 1.2rem;
-      padding: 0.5rem 1.5rem;
-      background: #4CAF50;
-      color: white;
-      border: none;
-      border-radius: 4px;
-      cursor: pointer;
-    }
-    button:hover {
-      background: #45a049;
-    }
-  </style>
-  
-  <template b-id="click-counter" b-data="{ message: 'Welcome!', count: 0 }">
-    ... markup ...
-  </template>
-  
-  <!-- Uses defaults: message="Welcome!", count=0 -->
-  <click-counter></click-counter>
-
-  <!-- Overrides message, keeps count=0 -->
-  <click-counter b-data="{ message: 'Bienvenido!' }"></click-counter>
-
-<script src="https://unpkg.com/lego-dom/main.js"></script>
-```
-
-### Using JavaScript
-
-```js
-import { Lego } from 'lego-dom';
-
-Lego.define('click-counter', `
-  <style>
-    self {
-      display: block;
-      padding: 2rem;
-      text-align: center;
-    }
-  </style>
-  
-  <h2>[[ message ]]</h2>
-  <p>Count: [[ count ]]</p>
-  <button @click="increment()">Click Me!</button>
-`, {
-  message: 'Welcome!',
-  count: 0,
-  increment() {
-    this.count++;
-  }
-});
-```
-
-Then use it in your HTML:
-
-```html
-<click-counter></click-counter>
-```
-
-### Using .lego Files (with Vite)
-
-Create `src/components/click-counter.lego`:
-
-```html
-<template>
-  <style>
-    self {
-      display: block;
-      padding: 2rem;
-    }
-  </style>
-  
-  <h2>[[ message ]]</h2>
-  <p>Count: [[ count ]]</p>
-  <button @click="increment()">Click Me!</button>
-</template>
-
-<script>
-export default {
-  message: 'Welcome!',
-  count: 0,
-  increment() {
-    this.count++;
-  }
-}
-</script>
-```
-
-The Vite plugin automatically discovers and registers it!
-
-## Understanding the Basics
-
-### 1. Templates
-
-Templates define what your component looks like. Use `[[ ]]` for dynamic content:
-
-```html
-<h1>Hello [[ name ]]!</h1>
-<p>[[ calculateAge() ]] years old</p>
-```
-
-### 2. State (Studs)
-
-Each component has reactive state called "studs":
-
-```js
-{ 
-  name: 'Alice',
-  age: 25,
-  calculateAge() {
-    return new Date().getFullYear() - 1999;
-  }
-}
-```
-
-### 3. Events
-
-Use `@eventname` to handle events:
-
-```html
-<button @click="handleClick()">Click</button>
-<input @input="handleInput()" />
-<form @submit="handleSubmit(event)">
-```
-
-### 4. Directives
-
-Special attributes for common patterns:
-
-- `b-show` - Conditional rendering
-- `b-for` - List rendering
-- `b-sync` - Two-way binding
-
-```html
-<p b-show="isLoggedIn">Welcome back!</p>
-<li b-for="item in items">[[ item.name ]]</li>
-<input b-sync="username" />
-```
-
-## What You've Learned
-
-- ✅ Three different ways to install Lego
-- ✅ How to create your first component
-- ✅ The basics of templates, state, and events
-- ✅ Available directives
-- ✅ The importance of the `Lego.init()` engine
-
-## Next Steps
-
-- Learn about [Components](/guide/components) in depth
-- Explore [Reactivity](/guide/reactivity) and how it works
-- Check out [Templating](/guide/templating) features
-- See [Examples](/examples/) of real applications