npm - lego-dom - Versions diffs - 0.0.3 → 0.0.5 - Mend

lego-dom 0.0.3 → 0.0.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (28) hide show

package/.ignore/auto.html +135 -0
package/.ignore/test.html +73 -0
package/README.md +448 -102
package/index.js +26 -0
package/main.js +459 -0
package/main.test.js +86 -0
package/package.json +14 -8
package/dist/dom/index.js +0 -1
package/dist/index.js +0 -1
package/dist/utils/index.js +0 -1
package/dist/utils/traverser.js +0 -1
package/dist/veyors/basket.js +0 -2
package/dist/veyors/brick.js +0 -1
package/dist/veyors/index.js +0 -1
package/dist/veyors/router.js +0 -1
package/example/blocks/banner.lego +0 -0
package/example/blocks/card.lego +0 -40
package/example/blocks/form.lego +0 -31
package/example/bricks/index.html +0 -50
package/src/dom/index.ts +0 -0
package/src/index.ts +0 -0
package/src/utils/index.ts +0 -0
package/src/utils/traverser.ts +0 -0
package/src/veyors/basket.ts +0 -5
package/src/veyors/brick.ts +0 -0
package/src/veyors/index.ts +0 -0
package/src/veyors/router.ts +0 -0
package/tsconfig.json +0 -69

package/README.md CHANGED Viewed

@@ -1,177 +1,523 @@
-Lego UI Library
-===============
-*Work In Progress and API will change drastically before 1.0.0*
+# Lego JS Library
-&nbsp;
+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.
-Lego is a UI Library that borrows heavily from the children toy company's product of the same name `Lego` &copy; Lego.
+## 🏗 Core Concepts
-It allows for Reusable interlocking User Interfaces (Lego Blocks) to be composed into bricks that are managed in isolation for assembly at runtime.
+### 1. Reactive State (`studs`)
-__Most importantly Lego aims to be the simplest UI Lib a developer can 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.
-```html
+### 2. Shadow DOM Encapsulation
-<html lang="en">
-<head>
-    <meta charset="UTF-8">
-    <meta name="viewport" content="width=device-width, initial-scale=1.0">
-    <title>Lego Example</title>
+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.
-    <style>
-        p {
-            color: red;
-        }
-    </style>
-</head>
-<body>
-    <!-- This is a lego block -->
-    <SomeFormWizard></SomeFormWizard>
+### 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.
-    <AnotherWizard>
-        <!-- whatever is nested inline in a block will be removed and appended as the last child of the loaded block -->
-    </AnotherWizard>
+## 🚀 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>`.
-    <script src="unpkg.com/lego/1.0"></script>
+```
+<!-- Define -->
+<template b-id="greeting-card">
+  <style>
+    self { display: block; padding: 20px; border-radius: 8px; background: #f0f4f8; }
+  </style>
-    <!-- After loading Lego you can either link to where your basket is defined i.e. external js bundle -->
-    <script src="application.bundle.js"></script>
+  <h2>Hello, {{ name }}!</h2>
+  <button @click="showBio = !showBio">Toggle Bio</button>
+  <p b-if="showBio">{{ bio }}</p>
+</template>
-    <!-- Or declare your lego blocks and bricks Inline -->
-    <script>
-        let basket = Lego.use("basket"); //case insensitive so .use("BaSkEt") works also
-        let router = Lego.use("router");
+<!-- Execute -->
+<greeting-card b-data="{ name: 'Alex', bio: 'Dev', showBio: false }"></greeting-card>
-        let AnotherWizard = router.get("./wizard.html");
+```
-        let ProtectedBrick = router.get("./wizard.html", () => {
-            //This can be a global authentication function call to auth0 etc...
-            return router.get("./unathenticated.html");
-        })
+## 📖 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>
-        //Explicit registration
-        Basket.register(AnotherWizard);
-        Basket.register(Router.get("./snippet.html")).as("SomeFormWizard");
-    </script>
-</body>
-</html>
 ```
+## 🏗 Tooling & Ecosystem
+# 📦 Lego Single File Components (.lego)
-There are 5 things to understand all in all to get a complete mastery of Lego JS. These are stylized under the acronym B.R.I.C.K to signify
-how lego acts as a building platform with the meanings provided below.
+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>`.
-- B is for Basket: This is similar to a real basket and is where all blocks `*.lego` pages are kept in memory for reuse.
-```js
-let basket = lego.use("basket");
 ```
+<!-- 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>
-- R is for Router: This is the global router responsible for loading and displaying blocks.
-```js
-let router = lego.use("router");
 ```
+## 🎨 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.
-- I is for Interface: This is a proxy to the UI/DOM that helps tie your JS code to what appears on screen.
-```js
-let interface = lego.use("interface");
 ```
+<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>
-- C is for Connection: The connection holds utilities for fetching data and sending data to an API.
-```js
-let connection = lego.use("connection");
 ```
+## 📍 Basic Route Definition
-- K is for Keep: The Keep is the global store for your application to register and reuse state and services.
-```js
-const db = lego.use("keep");
+Routes are defined using `Lego.route(path, componentName)`.
+```
+// Map the root path to 'home-page' block
+Lego.route('/', 'home-page');
-class User = { /** Methods, Fields, Constructor, Localized state etc. */ }
+// Map /about to 'about-page' block
+Lego.route('/about', 'about-page');
-db.register("User", User);
-db.register("User.Enterprise", User); //scoped
 ```
-```html
+## 动态 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
-<script src="unpkg.com/lego-dom@1.0.0"></script>
-<script></script>
 ```
+Lego.route('/user/:id', 'user-profile');
+Lego.route('/post/:category/:slug', 'blog-post');
+```
-&nbsp;
+### Usage inside a Component
-&nbsp;
+Any component can access these parameters via the `global` object.
-<hr>
+```
+<template b-id="user-profile">
+  <div>
+    <h2>User Profile</h2>
+    <p>Viewing ID: {{ global.params.id }}</p>
+  </div>
+</template>
-## Loading Files
+```
-<hr>
-There are two ways to load a file in Lego
+## 🛡 Navigation Middleware (Authentication)
-- Server Loaded
+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
-- Client Loaded
+```
+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
+});
+```
-### Server Loaded
-<hr>
+## 🔗 Internal Navigation (`b-link`)
-Java/PHP/Python or XYZ code on the server is responsible for checking if the request is a Lego request (X-Lego) header present or if it is a plain old HTTP Request.
+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.
-- The server can send back a `Lego Brick` or `full HTML` Page depending on if the request is a Lego Request or plain old HTTP request.
+```
+<!-- This will trigger the router logic -->
+<a href="/dashboard" b-link>Go to Dashboard</a>
-&nbsp;
+<!-- This will trigger a standard browser reload -->
+<a href="/external-site.com">External Link</a>
+```
+## 🏗 Programmatic Navigation
-### Basket Loaded
-<hr>
+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:
-This strategy depends on you calling into the `Lego Basket` to get the page where the Naive Brick returned from the server should sit.
+```
+// In your component logic
+submitForm() {
+  // Save data...
+  history.pushState({}, '', '/success');
+  // Dispatch popstate so the router hears it
+  window.dispatchEvent(new PopStateEvent('popstate'));
+}
-```html
+```
-<Card></Card>
+## 📂 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.
-<script src="/path.to.bundle.js"></script>
-<script>
-    let blocks = Basket.get("/approute/:ids/supported");
-    blocks.insert("#insertionPoint")
-</script>
 ```
+// 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
-# KEEP
-The keep is where state and objects are stored for reuse i.e. a User class or object that should be shared across multiple bricks and blocks. Like all other parts of Lego the API is pretty straightforward.
+Feature
-```html
+Syntax
-<html>
-<body>
-</body>
+Description
-<script src="unpkg.com/lego/1.0"></script>
-<script>
-    let keep = lego.use("keep");
+**Viewport**
-    class User = { /* custom methods and properties etc */ }
+`<lego-router>`
-    keep.set("User", User);
-</script>
+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 ADDED Viewed

@@ -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();