lego-dom 0.0.4 → 0.0.7

package/README.md

@@ -0,0 +1,344 @@
+# LegoJS
+
+LegoJS is a tiny, zero-dependency JavaScript library for building reactive Web Components directly in the browser.
+
+The goal of LegoJS is **mental model simplicity**:
+
+* No virtual DOM
+* No compilation step required
+* No JSX
+* No framework-specific syntax to learn
+
+You write **HTML**, add a few **directives**, and LegoJS takes care of reactivity and updates.
+
+This README is intentionally designed so that a developer can understand **everything they need** about LegoJS by reading this file alone.
+
+---
+
+## Installation
+
+The package name on npm is **`lego-dom`** (the name `legojs` was already taken).
+
+```bash
+npm install lego-dom
+```
+
+Or include it directly in the browser:
+
+```html
+<script src="node_modules/lego-dom/main.js"></script>
+```
+
+Once loaded, `Lego` is available globally.
+
+---
+
+## The Mental Model
+
+Think of LegoJS like real Lego blocks:
+
+* **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**
+
+There is no mounting, diffing, or reconciliation engine.
+
+You change JavaScript objects → LegoJS updates the DOM.
+
+---
+
+## Defining a Component (Block)
+
+A component is defined using a standard HTML `<template>` with a `b-id`.
+
+```html
+<template b-id="hello-card">
+  <style>
+    self {
+      display: block;
+      padding: 1rem;
+      border: 1px solid #ccc;
+    }
+  </style>
+
+  <h2>Hello {{ name }}</h2>
+  <button @click="count++">Clicked {{ count }} times</button>
+</template>
+```
+
+Use the component in HTML:
+
+```html
+<hello-card b-data="{ name: 'Ahmed', count: 0 }"></hello-card>
+```
+
+---
+
+## Reactive State (`studs`)
+
+Each component has a reactive state object internally called **studs**.
+
+* Defined via `b-data` or component logic
+* Implemented using JavaScript `Proxy`
+* Any mutation automatically schedules a re-render
+
+```html
+<button @click="count++"></button>
+```
+
+No setters. No actions. No reducers.
+
+Just mutate data.
+
+---
+
+## Templating (`{{ }}`)
+
+Text interpolation works in:
+
+* Text nodes
+* Attributes
+* Class names
+
+```html
+<p>Hello {{ user.name }}</p>
+<img src="/avatars/{{ user.id }}.png">
+```
+
+Expressions are plain JavaScript.
+
+---
+
+## Event Handling (`@event`)
+
+Use `@` followed by any DOM event.
+
+```html
+<button @click="submit()">Submit</button>
+```
+
+The expression runs in the component’s state scope.
+
+You also have access to:
+
+* `event` – the native DOM event
+* `$emit(name, detail)` – dispatch custom events
+* `$element` – the host custom element
+
+---
+
+## Conditional Rendering (`b-if`)
+
+```html
+<p b-if="isLoggedIn">Welcome back</p>
+```
+
+When the expression is falsy, the element is hidden via `display: none`.
+
+---
+
+## Lists (`b-for`)
+
+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>
+```
+
+* DOM nodes are reused
+* Items are tracked internally
+* Updates are efficient without a virtual DOM
+
+---
+
+## Two-Way Binding (`b-sync`)
+
+`b-sync` keeps inputs and state in sync.
+
+```html
+<input b-sync="username">
+<input type="checkbox" b-sync="settings.enabled">
+```
+
+Works with:
+
+* text inputs
+* checkboxes
+* nested objects
+* items inside `b-for`
+
+---
+
+## Styling and Shadow DOM
+
+Every component uses **Shadow DOM** automatically.
+
+Inside `<style>` blocks:
+
+* Use `self` to target the component root
+* `self` is converted to `:host`
+
+```css
+self {
+  display: block;
+}
+```
+
+Styles never leak in or out.
+
+---
+
+## Lifecycle Hooks
+
+Define lifecycle methods directly on the component state:
+
+```js
+{
+  mounted() {
+    console.log('Component attached');
+  },
+  updated() {
+    console.log('State changed');
+  },
+  unmounted() {
+    console.log('Component removed');
+  }
+}
+```
+
+---
+
+## Custom Events (`$emit`)
+
+Child components communicate upward using events.
+
+```html
+<button @click="$emit('save', data)">Save</button>
+```
+
+Events:
+
+* bubble
+* cross Shadow DOM boundaries
+* are standard `CustomEvent`s
+
+---
+
+## Accessing Ancestors (`$ancestors`)
+
+Read state from the nearest ancestor component:
+
+```html
+<p>{{ $ancestors('app-shell').user.name }}</p>
+```
+
+This is intended for **reading**, not mutation.
+
+---
+
+## Shared State (`$registry`)
+
+Components defined via `Lego.define` get a shared singleton state.
+
+```js
+$registry('settings').theme
+```
+
+Useful for global configuration or app-wide state.
+
+---
+
+## Router
+
+LegoJS includes a minimal client-side router.
+
+Add a router outlet:
+
+```html
+<lego-router></lego-router>
+```
+
+Define routes:
+
+```js
+Lego.route('/', 'home-page');
+Lego.route('/user/:id', 'user-page');
+```
+
+Access route params:
+
+```html
+<p>User ID: {{ global.params.id }}</p>
+```
+
+Navigation:
+
+```html
+<a href="/dashboard" b-link>Dashboard</a>
+```
+
+---
+
+## Programmatic Navigation
+
+```js
+history.pushState({}, '', '/success');
+window.dispatchEvent(new PopStateEvent('popstate'));
+```
+
+---
+
+## Defining Components in JavaScript
+
+You can also define components programmatically:
+
+```js
+Lego.define(
+  'counter-box',
+  `
+  <style>self { display:block }</style>
+  <button @click="count++">{{ count }}</button>
+  `,
+  { count: 0 }
+);
+```
+
+---
+
+## Initialization
+
+LegoJS initializes automatically on `DOMContentLoaded`.
+
+You usually do **not** need to call anything manually.
+
+---
+
+## Design Philosophy
+
+LegoJS is intentionally small and opinionated:
+
+* The DOM is the source of truth
+* JavaScript objects are the state
+* HTML stays HTML
+* Complexity is avoided unless absolutely necessary
+
+If you can explain your UI with plain objects and markup, LegoJS will feel natural.
+
+---
+
+## Summary
+
+* 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
+
+That’s it.

package/package.json

@@ -1,17 +1,16 @@
 {
   "name": "lego-dom",
-  "version": "0.0.4",
+  "version": "0.0.7",
   "description": "A feature-rich web components + SFC frontend framework",
   "main": "main.js",
   "type": "module",
   "keywords": ["framework", "sfc", "components", "lego", "legokit"],
-  "author": "Tersoo <ortserga@gmail.com>",
+  "author": "",
   "scripts": {
     "test": "vitest run"
   },
   "devDependencies": {
     "vitest": "^1.0.0",
     "jsdom": "^22.0.0"
-  },
-  "license": "MIT"
+  }
 }

package/about.md

@@ -1,523 +0,0 @@
-# Lego JS Library
-
-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.
-
-## 🏗 Core Concepts
-
-### 1. Reactive State (`studs`)
-
-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.
-
-### 2. Shadow DOM Encapsulation
-
-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-`)
-
-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.
-
-```
-<script src="path/to/main.js"></script>
-
-```
-
-### 🛠 Creating your first Component
-
-Define logic and layout in a standard `<template>`.
-
-```
-<!-- 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>
-
-```
-
-## 📖 Directives Deep Dive
-
-Directive
-
-Type
-
-Description
-
-Example
-
-`b-id`
-
-Definition
-
-Registers the custom element tag name.
-
-`<template b-id="my-tag">`
-
-`b-data`
-
-Initialization
-
-Sets the initial reactive state.
-
-`<my-tag b-data="{ count: 0 }">`
-
-`b-sync`
-
-Two-way
-
-Bi-directional binding for form inputs.
-
-`<input b-sync="query">`
-
-`b-for`
-
-Structural
-
-High-performance array looping.
-
-`<li b-for="u in users">{{ u.name }}</li>`
-
-`b-if`
-
-Structural
-
-Toggles presence based on truthiness.
-
-`<div b-if="isAdmin">Admin</div>`
-
-`b-text`
-
-Binding
-
-Escaped text binding (one-way).
-
-`<span b-text="title"></span>`
-
-`@event`
-
-Event
-
-Standard DOM event listeners.
-
-`<button @click="run()">`
-
-## 📝 Advanced Example: Todo List
-
-Demonstrating `b-for`, event handling, and two-way binding in a single block.
-
-```
-<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>
-
-<script>
-export default {
-  tasks: [{ text: 'Native Components', done: true }, { text: 'Profit', done: false }],
-  newTask: ''
-}
-</script>
-
-```
-
-## 🏗 Tooling & Ecosystem
-
-
-# 📦 Lego Single File Components (.lego)
-
-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
-
-A `.lego` file is composed of three top-level blocks: `<template>`, `<style>`, and `<script>`.
-
-```
-<!-- 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>
-
-<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>
-
-```
-
-## 🎨 Scoped Styling
-
-Styles defined inside a `.lego` file are automatically scoped to that component using the **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.
-    
-
-## ⚙️ Component Logic (`export default`)
-
-The `<script>` block must `export default` a plain JavaScript object. This object defines the component's state and behavior.
-
-### 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:
-
-Hook
-
-Description
-
-`mounted()`
-
-Called after the component is attached to the DOM and its shadow root is initialized.
-
-`updated()`
-
-Called after the state changes and the DOM has been patched via the batcher.
-
-`unmounted()`
-
-Called just before the component is removed from the DOM. Use for cleanup (e.g., clearing timers).
-
-## ✨ Magic Helpers ($)
-
-Lego JS provides several "magic" variables available directly in your templates and event handlers to speed up development.
-
-### `$element`
-
-Refers to the host custom element itself (the root of the component).
-
-### `$refs`
-
-Provides quick access to DOM elements within the component's Shadow DOM that have a `ref` attribute.
-
-### `$emit(eventName, detail)`
-
-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.
-
-### `$ancestors(id)`
-
-Searches up the DOM tree for the nearest component matching the provided tag name or `b-id`.
-
-### `$event` and `$self`
-
--   `$event`: The native DOM event object.
-    
--   `$self`: The specific element that triggered the event (alias for `event.target`).
-    
-
-## 📡 The "One Way" Pattern (Data Flow)
-
-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)
-
-Avoid having children directly change an ancestor's data. It makes debugging impossible.
-
-```
-<!-- child.lego: DON'T DO THIS -->
-<button @click="$ancestors('app-shell').user.age++">Update Age</button>
-
-```
-
-### ✅ 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`:
-
-```
-import { defineConfig } from 'vite';
-import { Lego } from './path/to/lego.js';
-
-export default defineConfig({
-  plugins: [Lego.vitePlugin()]
-});
-
-```
-
-## 💡 Best Practices
-
-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.
-
-
-
-# 🛣 Lego JS Routing Guide
-
-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
-
-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.
-
-```
-<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>
-
-```
-
-## 📍 Basic Route Definition
-
-Routes are defined using `Lego.route(path, componentName)`.
-
-```
-// Map the root path to 'home-page' block
-Lego.route('/', 'home-page');
-
-// Map /about to 'about-page' block
-Lego.route('/about', 'about-page');
-
-```
-
-## 动态 Dynamic Route Parameters
-
-You can define dynamic segments in your paths using the `:` prefix. These parameters are automatically parsed and injected into `Lego.globals.params`.
-
-### Definition
-
-```
-Lego.route('/user/:id', 'user-profile');
-Lego.route('/post/:category/:slug', 'blog-post');
-
-```
-
-### Usage inside a Component
-
-Any component can access these parameters via the `global` object.
-
-```
-<template b-id="user-profile">
-  <div>
-    <h2>User Profile</h2>
-    <p>Viewing ID: {{ global.params.id }}</p>
-  </div>
-</template>
-
-```
-
-## 🛡 Navigation Middleware (Authentication)
-
-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
-
-```
-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
-});
-
-```
-
-## 🔗 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.
-
-```
-<!-- This will trigger the router logic -->
-<a href="/dashboard" b-link>Go to Dashboard</a>
-
-<!-- This will trigger a standard browser reload -->
-<a href="/external-site.com">External Link</a>
-
-```
-
-## 🏗 Programmatic Navigation
-
-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:
-
-```
-// In your component logic
-submitForm() {
-  // Save data...
-  history.pushState({}, '', '/success');
-  // Dispatch popstate so the router hears it
-  window.dispatchEvent(new PopStateEvent('popstate'));
-}
-
-```
-
-## 📂 Large Scale Structure
-
-For larger projects, define your routes in a dedicated initialization file and ensure your page components are registered before the router starts.
-
-```
-// 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
-  });
-};
-
-```
-
-## 📝 Router State Summary
-
-Feature
-
-Syntax
-
-Description
-
-**Viewport**
-
-`<lego-router>`
-
-Where the content renders.
-
-**Directive**
-
-`b-link`
-
-Intercepts link clicks.
-
-**Globals**
-
-`global.params`
-
-Object containing URL variables.
-
-**Middleware**
-
-`(params, globals) => boolean`
-
-Logic to permit/block access.