lego-dom 0.0.5 → 0.0.8

package/README.md

@@ -1,523 +1,466 @@
-# Lego JS Library
+# LegoJS
 
-Lego JS is a surgical, zero-dependency reactive library for building native Web Components. It skips the virtual DOM overhead, leveraging Proxies and Shadow DOM to provide a lightweight (<5KB) alternative to the heavy-duty framework status quo.
+LegoJS is a tiny, zero-dependency JavaScript library for building reactive Web Components directly in the browser.
 
-## 🏗 Core Concepts
+The goal of LegoJS is **mental model simplicity**:
 
-### 1. Reactive State (`studs`)
+* No virtual DOM
+* No compilation step required
+* No JSX
+* No framework-specific syntax to learn
 
-Lego components use a reactive state object called `studs`. State mutations trigger efficient, batched DOM updates via `requestAnimationFrame`—minimizing reflows without a complex reconciliation engine.
+You write **HTML**, add a few **directives**, and LegoJS takes care of reactivity and updates.
 
-### 2. Shadow DOM Encapsulation
+This README is intentionally designed so that a developer can understand **everything they need** about LegoJS by reading this file alone.
 
-Styles and logic are scoped by default. Use the `self` selector inside a component's `<style>` tag to target the host element without worrying about CSS leakage or global collisions.
+---
 
-### 3. Directives (`b-`)
+## Installation
 
-Native-feeling attributes (`b-if`, `b-for`, `b-sync`) bridge your data to the DOM. No JSX, no compilation required for core features—just standard HTML.
-
-## 🚀 Quickstart
-
-### 📦 Installation
-
-Drop the script and start building. No build step, no `npm install` fatigue.
+The package name on npm is **`lego-dom`** (the name `legojs` was already taken).
 
+```bash
+npm install lego-dom
 ```
-<script src="path/to/main.js"></script>
 
-```
-
-### 🛠 Creating your first Component
-
-Define logic and layout in a standard `<template>`.
+Or include it directly in the browser:
 
+```html
+<script src="node_modules/lego-dom/main.js"></script>
 ```
-<!-- Define -->
-<template b-id="greeting-card">
-  <style>
-    self { display: block; padding: 20px; border-radius: 8px; background: #f0f4f8; }
-  </style>
-
-  <h2>Hello, {{ name }}!</h2>
-  <button @click="showBio = !showBio">Toggle Bio</button>
-  <p b-if="showBio">{{ bio }}</p>
-</template>
 
-<!-- Execute -->
-<greeting-card b-data="{ name: 'Alex', bio: 'Dev', showBio: false }"></greeting-card>
+Once loaded, `Lego` is available globally.
 
-```
-
-## 📖 Directives Deep Dive
+---
 
-Directive
+## The Mental Model
 
-Type
+Think of LegoJS like real Lego blocks:
 
-Description
+* **Templates** define how a block looks
+* **Studs** define the data attached to a block
+* **Directives** snap data to the DOM
+* **Changes to data automatically update the DOM**
 
-Example
+There is no mounting, diffing, or reconciliation engine.
 
-`b-id`
+You change JavaScript objects → LegoJS updates the DOM.
 
-Definition
+---
 
-Registers the custom element tag name.
+## Defining a Component (Block)
 
-`<template b-id="my-tag">`
+A component is defined using a standard HTML `<template>` with a `b-id`.
 
-`b-data`
+```html
+<template b-id="hello-card">
+  <style>
+    self {
+      display: block;
+      padding: 1rem;
+      border: 1px solid #ccc;
+    }
+  </style>
 
-Initialization
+  <h2>Hello {{ name }}</h2>
+  <button @click="count++">Clicked {{ count }} times</button>
+</template>
+```
 
-Sets the initial reactive state.
+Use the component in HTML:
 
-`<my-tag b-data="{ count: 0 }">`
+```html
+<hello-card b-data="{ name: 'Ahmed', count: 0 }"></hello-card>
+```
 
-`b-sync`
+---
 
-Two-way
+## Reactive State (`studs`)
 
-Bi-directional binding for form inputs.
+Each component has a reactive state object internally called **studs**.
 
-`<input b-sync="query">`
+* Defined via `b-data` or component logic
+* Implemented using JavaScript `Proxy`
+* Any mutation automatically schedules a re-render
 
-`b-for`
+```html
+<button @click="count++"></button>
+```
 
-Structural
+No setters. No actions. No reducers.
 
-High-performance array looping.
+Just mutate data.
 
-`<li b-for="u in users">{{ u.name }}</li>`
+---
 
-`b-if`
+## Templating (`{{ }}`)
 
-Structural
+Text interpolation works in:
 
-Toggles presence based on truthiness.
+* Text nodes
+* Attributes
+* Class names
 
-`<div b-if="isAdmin">Admin</div>`
+```html
+<p>Hello {{ user.name }}</p>
+<img src="/avatars/{{ user.id }}.png">
+```
 
-`b-text`
+Expressions are plain JavaScript.
 
-Binding
+---
 
-Escaped text binding (one-way).
+## Event Handling (`@event`)
 
-`<span b-text="title"></span>`
+Use `@` followed by any DOM event.
 
-`@event`
+```html
+<button @click="submit()">Submit</button>
+```
 
-Event
+The expression runs in the component’s state scope.
 
-Standard DOM event listeners.
+You also have access to:
 
-`<button @click="run()">`
+* `event` – the native DOM event
+* `$emit(name, detail)` – dispatch custom events
+* `$element` – the host custom element
 
-## 📝 Advanced Example: Todo List
+---
 
-Demonstrating `b-for`, event handling, and two-way binding in a single block.
+## Conditional Rendering (`b-if`)
 
+```html
+<p b-if="isLoggedIn">Welcome back</p>
 ```
-<template b-id="todo-app">
-  <style>
-    .done { text-decoration: line-through; opacity: 0.6; }
-    ul { list-style: none; padding: 0; }
-  </style>
 
-  <h3>Tasks ({{ tasks.filter(t => !t.done).length }} left)</h3>
-  
-  <input b-sync="newTask" placeholder="Add task...">
-  <button @click="tasks.push({text: newTask, done: false}); newTask=''">Add</button>
-
-  <ul>
-    <li b-for="task in tasks">
-      <input type="checkbox" b-sync="task.done">
-      <span class="{{ task.done ? 'done' : '' }}">{{ task.text }}</span>
-    </li>
-  </ul>
-</template>
+When the expression is falsy, the element is hidden via `display: none`.
 
-<script>
-export default {
-  tasks: [{ text: 'Native Components', done: true }, { text: 'Profit', done: false }],
-  newTask: ''
-}
-</script>
+---
 
-```
+## Lists (`b-for`)
 
-## 🏗 Tooling & Ecosystem
+Render lists using `b-for`:
 
+```html
+<ul>
+  <li b-for="todo in todos">
+    <input type="checkbox" b-sync="todo.done">
+    <span class="{{ todo.done ? 'done' : '' }}">{{ todo.text }}</span>
+  </li>
+</ul>
+```
 
-# 📦 Lego Single File Components (.lego)
+* DOM nodes are reused
+* Items are tracked internally
+* Updates are efficient without a virtual DOM
 
-Single File Components (SFCs) are the professional standard for building with Lego JS. They allow you to co-locate your markup, scoped CSS, and reactive logic in a single `.lego` file, providing a clean separation of concerns without the mental overhead of switching between multiple files.
+---
 
-## 🏗 Anatomy of a .lego File
+## Two-Way Binding (`b-sync`)
 
-A `.lego` file is composed of three top-level blocks: `<template>`, `<style>`, and `<script>`.
+`b-sync` keeps inputs and state in sync.
 
+```html
+<input b-sync="username">
+<input type="checkbox" b-sync="settings.enabled">
 ```
-<!-- user-profile.lego -->
-<template>
-  <div class="profile-card">
-    <img src="{{ avatar }}" alt="{{ name }}">
-    <h2>{{ name }}</h2>
-    <p>{{ bio }}</p>
-    <button @click="poke">Poke {{ name }}</button>
-  </div>
-</template>
 
-<style>
-  self {
-    display: block;
-    border: 1px solid #ddd;
-    border-radius: 8px;
-    padding: 1rem;
-    text-align: center;
-  }
-  img {
-    width: 80px;
-    height: 80px;
-    border-radius: 50%;
-  }
-  h2 { color: #333; }
-</style>
+Works with:
 
-<script>
-  export default {
-    // Initial data state
-    avatar: 'default.png',
-    name: 'Anonymous',
-    bio: 'No bio provided.',
-    
-    // Logic methods
-    poke() {
-      console.log(`${this.name} was poked!`);
-      this.$emit('poked', { name: this.name });
-    },
-
-    // Lifecycle hooks
-    mounted() {
-      console.log('Profile component is now in the DOM');
-    }
-  }
-</script>
-
-```
+* text inputs
+* checkboxes
+* nested objects
+* items inside `b-for`
 
-## 🎨 Scoped Styling
+---
 
-Styles defined inside a `.lego` file are automatically scoped to that component using the **Shadow DOM**.
+## Styling and Shadow DOM
 
--   **The `self` selector**: Use `self` to target the host element of the component itself (the custom tag). In the final build, this is converted to the `:host` CSS selector.
-    
--   **No Leakage**: Styles defined here will not leak out to the parent page, and global styles (except CSS variables) will not leak into the component.
-    
+Every component uses **Shadow DOM** automatically.
 
-## ⚙️ Component Logic (`export default`)
+Inside `<style>` blocks:
 
-The `<script>` block must `export default` a plain JavaScript object. This object defines the component's state and behavior.
+* Use `self` to target the component root
+* `self` is converted to `:host`
 
-### 1. Reactive Data
-
-Any property defined in the exported object becomes part of the reactive `data` proxy. When you change `this.username = 'NewName'`, the template updates automatically.
-
-### 2. Lifecycle Hooks
-
-Lego JS provides specific hooks to manage the component's existence:
+```css
+self {
+  display: block;
+}
+```
 
-Hook
+Styles never leak in or out.
 
-Description
+---
 
-`mounted()`
+## Lifecycle Hooks
 
-Called after the component is attached to the DOM and its shadow root is initialized.
+Define lifecycle methods directly on the component state:
 
-`updated()`
+```js
+{
+  mounted() {
+    console.log('Component attached');
+  },
+  updated() {
+    console.log('State changed');
+  },
+  unmounted() {
+    console.log('Component removed');
+  }
+}
+```
 
-Called after the state changes and the DOM has been patched via the batcher.
+---
 
-`unmounted()`
+## Custom Events (`$emit`)
 
-Called just before the component is removed from the DOM. Use for cleanup (e.g., clearing timers).
+Child components communicate upward using events.
 
-## ✨ Magic Helpers ($)
+```html
+<button @click="$emit('save', data)">Save</button>
+```
 
-Lego JS provides several "magic" variables available directly in your templates and event handlers to speed up development.
+Events:
 
-### `$element`
+* bubble
+* cross Shadow DOM boundaries
+* are standard `CustomEvent`s
 
-Refers to the host custom element itself (the root of the component).
+---
 
-### `$refs`
+## Accessing Ancestors (`$ancestors`)
 
-Provides quick access to DOM elements within the component's Shadow DOM that have a `ref` attribute.
+Read state from the nearest ancestor component:
 
-### `$emit(eventName, detail)`
+```html
+<p>{{ $ancestors('app-shell').user.name }}</p>
+```
 
-A shorthand for dispatching custom events. By default, these events have `bubbles: true` and `composed: true`, allowing them to pass through multiple levels of Shadow DOM.
+This is intended for **reading**, not mutation.
 
-### `$ancestors(id)`
+---
 
-Searches up the DOM tree for the nearest component matching the provided tag name or `b-id`.
+## Shared State (`$registry`)
 
-### `$event` and `$self`
+Components defined via `Lego.define` get a shared singleton state.
 
--   `$event`: The native DOM event object.
-    
--   `$self`: The specific element that triggered the event (alias for `event.target`).
-    
+```js
+$registry('settings').theme
+```
 
-## 📡 The "One Way" Pattern (Data Flow)
+Useful for global configuration or app-wide state.
 
-While Lego JS allows deep tree access, the **only** recommended way to handle state updates in large apps is **Data Down, Events Up**. This prevents "mutant state" where you don't know which child changed a value.
+---
 
-### ❌ The "Bad" Way (Direct Mutation)
+## Router
 
-Avoid having children directly change an ancestor's data. It makes debugging impossible.
+LegoJS includes a minimal client-side router.
 
-```
-<!-- child.lego: DON'T DO THIS -->
-<button @click="$ancestors('app-shell').user.age++">Update Age</button>
+Add a router outlet:
 
+```html
+<lego-router></lego-router>
 ```
 
-### ✅ The "Lego" Way (Generic Update Pattern)
-
-If you have many fields, you don't need unique event handlers for each. Use a single generic update event.
-
-1.  **Child** sends the field name and the new value:
-    
-    ```
-    <!-- settings-child.lego -->
-    <input type="text" 
-           value="{{ $ancestors('app-shell').user.name }}" 
-           @input="$emit('update-field', { key: 'name', value: $self.value })">
-    
-    <input type="number" 
-           value="{{ $ancestors('app-shell').user.age }}" 
-           @input="$emit('update-field', { key: 'age', value: $self.value })">
-    
-    ```
-    
-2.  **Ancestor** handles all updates in one function:
-    
-    ```
-    <!-- grand-parent.lego -->
-    <template>
-      <div @update-field="handleFieldUpdate">
-        <settings-child></settings-child>
-      </div>
-    </template>
-    
-    <script>
-      export default {
-        user: { name: 'John', age: 30 },
-        handleFieldUpdate(event) {
-          const { key, value } = event.detail;
-          // One place to validate everything
-          if (this.user.hasOwnProperty(key)) {
-            this.user[key] = value;
-          }
-        }
-      }
-    </script>
-    
-    ```
-    
-
-## 🚀 The Build Process (Vite)
-
-To use `.lego` files, you must use the `Lego.vitePlugin()`. This plugin transforms your HTML-like file into a standard JavaScript module that registers the component with the `Lego.define` API.
-
-### Configuration
-
-In your `vite.config.js`:
+Define routes:
 
+```js
+Lego.route('/', 'home-page');
+Lego.route('/user/:id', 'user-page');
 ```
-import { defineConfig } from 'vite';
-import { Lego } from './path/to/lego.js';
 
-export default defineConfig({
-  plugins: [Lego.vitePlugin()]
-});
+Access route params:
 
+```html
+<p>User ID: {{ global.params.id }}</p>
 ```
 
-## 💡 Best Practices
+Navigation:
 
-1.  **Naming**: Use multi-word names for components to avoid collisions.
-    
-2.  **Read-Only Ancestors**: Use `$ancestors()` primarily for **reading** values.
-    
-3.  **Intent-based Events**: For complex logic (e.g., `submit-order`), use a specific event. For simple data syncing, use a generic `update-field` event.
+```html
+<a href="/dashboard" b-link>Dashboard</a>
+```
 
+---
 
+## Programmatic Navigation
 
-# 🛣 Lego JS Routing Guide
+```js
+history.pushState({}, '', '/success');
+window.dispatchEvent(new PopStateEvent('popstate'));
+```
 
-The Lego JS router is a lightweight client-side routing solution that leverages the browser's History API. It allows you to build Single Page Applications (SPAs) by mapping URL paths to specific Web Components (Blocks).
+---
 
-## 🧩 The Router Viewport
+## Defining Components in JavaScript
 
-To use routing, you must place the `<lego-router>` element in your HTML. This acts as the container where the matched component will be rendered.
+You can also define components programmatically:
 
+```js
+Lego.define(
+  'counter-box',
+  `
+  <style>self { display:block }</style>
+  <button @click="count++">{{ count }}</button>
+  `,
+  { count: 0 }
+);
 ```
-<body>
-  <nav>
-    <a href="/" b-link>Home</a>
-    <a href="/profile/123" b-link>Profile</a>
-  </nav>
 
-  <!-- Routed components appear here -->
-  <lego-router></lego-router>
-</body>
+---
 
-```
+## Initialization
 
-## 📍 Basic Route Definition
+LegoJS initializes automatically on `DOMContentLoaded`.
 
-Routes are defined using `Lego.route(path, componentName)`.
+You usually do **not** need to call anything manually.
 
-```
-// Map the root path to 'home-page' block
-Lego.route('/', 'home-page');
+---
 
-// Map /about to 'about-page' block
-Lego.route('/about', 'about-page');
+## Design Philosophy
 
-```
+LegoJS is intentionally small and opinionated:
 
-## 动态 Dynamic Route Parameters
+* The DOM is the source of truth
+* JavaScript objects are the state
+* HTML stays HTML
+* Complexity is avoided unless absolutely necessary
 
-You can define dynamic segments in your paths using the `:` prefix. These parameters are automatically parsed and injected into `Lego.globals.params`.
+If you can explain your UI with plain objects and markup, LegoJS will feel natural.
 
-### Definition
+---
 
-```
-Lego.route('/user/:id', 'user-profile');
-Lego.route('/post/:category/:slug', 'blog-post');
+## Single File Components (SFC)
 
-```
+LegoJS supports **Single File Components** using `.lego` files when using a build tool like Vite.
 
-### Usage inside a Component
+### .lego File Format
 
-Any component can access these parameters via the `global` object.
+A `.lego` file contains three optional sections:
 
-```
-<template b-id="user-profile">
-  <div>
-    <h2>User Profile</h2>
-    <p>Viewing ID: {{ global.params.id }}</p>
-  </div>
+```html
+<template>
+  <!-- Your HTML markup with directives -->
+  <h1>{{ title }}</h1>
+  <button @click="count++">{{ count }}</button>
 </template>
 
+<script>
+export default {
+  // Your component logic/state
+  title: 'Hello',
+  count: 0
+}
+</script>
+
+<style>
+  /* Scoped CSS using self keyword */
+  self {
+    display: block;
+    padding: 1rem;
+  }
+</style>
 ```
 
-## 🛡 Navigation Middleware (Authentication)
+The component name is automatically derived from the filename (e.g., `sample-component.lego` → `<sample-component>`).
 
-Middleware allows you to guard routes. The middleware function is executed before the component is rendered. If it returns `false`, the navigation is cancelled.
+---
 
-### Example: Auth Guard
+## Vite Plugin Setup
 
-```
-Lego.route('/admin', 'admin-dashboard', async (params, globals) => {
-  const isAuthorized = globals.user && globals.user.role === 'admin';
-  
-  if (!isAuthorized) {
-    // Redirect to login or home
-    history.pushState({}, '', '/login');
-    // We must manually trigger the router check after pushState
-    Lego.init(); 
-    return false; // Prevent 'admin-dashboard' from loading
-  }
-  
-  return true; // Proceed to load the component
-});
+### Installation
 
+```bash
+npm install lego-dom vite
 ```
 
-## 🔗 Internal Navigation (`b-link`)
-
-To navigate without a full page refresh, use the `b-link` directive on anchor tags. This intercepts the click, updates the URL via `pushState`, and tells the Lego router to swap the view.
+### Configuration
 
-```
-<!-- This will trigger the router logic -->
-<a href="/dashboard" b-link>Go to Dashboard</a>
+Create `vite.config.js`:
 
-<!-- This will trigger a standard browser reload -->
-<a href="/external-site.com">External Link</a>
+```js
+import { defineConfig } from 'vite';
+import legoPlugin from 'lego-dom/vite-plugin';
 
+export default defineConfig({
+  plugins: [
+    legoPlugin({
+      componentsDir: './src/components',  // Where to look for .lego files
+      include: ['**/*.lego']              // Glob patterns to match
+    })
+  ]
+});
 ```
 
-## 🏗 Programmatic Navigation
+### Usage
 
-Sometimes you need to navigate via JavaScript (e.g., after a successful form submission). Use the standard `history.pushState` but remember that the library listens for the `popstate` event. To trigger a render manually, you can call the internal route matcher or simply use a helper:
+Create your components in `.lego` files:
 
 ```
-// In your component logic
-submitForm() {
-  // Save data...
-  history.pushState({}, '', '/success');
-  // Dispatch popstate so the router hears it
-  window.dispatchEvent(new PopStateEvent('popstate'));
-}
-
+src/
+  components/
+    my-button.lego
+    user-card.lego
+  main.js
+index.html
 ```
 
-## 📂 Large Scale Structure
+In your `main.js`:
 
-For larger projects, define your routes in a dedicated initialization file and ensure your page components are registered before the router starts.
+```js
+import { Lego } from 'lego-dom/main.js';
+import registerComponents from 'virtual:lego-components';
 
+registerComponents();
 ```
-// router-config.js
-import './views/home.lego';
-import './views/login.lego';
-import './views/profile.lego';
-
-export const setupRouter = () => {
-  Lego.route('/', 'home-view');
-  Lego.route('/login', 'login-view');
-  
-  // Nested logic for clean organization
-  Lego.route('/profile/:username', 'profile-view', (params) => {
-    return !!params.username; // Basic validation
-  });
-};
 
-```
+In your HTML:
 
-## 📝 Router State Summary
+```html
+<my-button></my-button>
+<user-card></user-card>
+```
 
-Feature
+**Auto-discovery**: The Vite plugin automatically finds all `.lego` files and registers them with LegoJS!
 
-Syntax
+---
 
-Description
+## Two Usage Modes
 
-**Viewport**
+LegoJS works in **two modes**:
 
-`<lego-router>`
+### 1. Without Build Tooling
 
-Where the content renders.
+Include `main.js` directly and use `<template b-id>` or `Lego.define()`:
 
-**Directive**
+```html
+<script src="node_modules/lego-dom/main.js"></script>
+<template b-id="my-component">
+  <h1>Hello</h1>
+</template>
+```
 
-`b-link`
+### 2. With Vite (SFC)
 
-Intercepts link clicks.
+Use `.lego` files that are auto-discovered and compiled:
 
-**Globals**
+```bash
+npm run dev
+```
 
-`global.params`
+Both modes use the same LegoJS runtime and support all the same features!
 
-Object containing URL variables.
+---
 
-**Middleware**
+## Summary
 
-`(params, globals) => boolean`
+* Install with `npm install lego-dom`
+* Define components with `<template b-id>`
+* Use `b-data` for state
+* Use `{{ }}` for binding
+* Use `@event` for logic
+* Use `b-if`, `b-for`, and `b-sync` for structure
 
-Logic to permit/block access.
+That’s it.