lego-dom 0.0.3 → 0.0.4

package/about.md

@@ -0,0 +1,523 @@
+# 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.

package/index.js

@@ -0,0 +1,26 @@
+#!/usr/bin/env node
+import fs from 'fs-extra';
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+async function init() {
+  const targetDir = process.argv[2] || 'my-lego-app';
+  const templateDir = path.resolve(__dirname, 'template');
+
+  console.log(`Building your Lego app in ${targetDir}...`);
+
+  await fs.copy(templateDir, targetDir);
+  
+  // Customizing package.json name
+  const pkgPath = path.join(targetDir, 'package.json');
+  const pkg = await fs.readJson(pkgPath);
+  pkg.name = targetDir;
+  await fs.writeJson(pkgPath, pkg, { spaces: 2 });
+
+  console.log('\nDone! Now run:\n');
+  console.log(`  cd ${targetDir}\n  npm install\n  npm run dev`);
+}
+
+init();