lego-dom 0.0.8 → 0.0.9

package/README.md

@@ -1,466 +1,82 @@
-# LegoJS
+# Lego 🧱
 
-LegoJS is a tiny, zero-dependency JavaScript library for building reactive Web Components directly in the browser.
+**The tiny, zero-dependency library for building reactive Web Components.**
 
-The goal of LegoJS is **mental model simplicity**:
+Lego embraces the web platform. It turns standard HTML `<template>` tags into reactive, encapsulated custom elements with zero build steps required.
 
-* 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');
-  }
-}
-```
+[**Explore the Docs**](https://rayattack.github.io/legodom/) | [**Examples**](https://rayattack.github.io/legodom/examples/) | [**GitHub**](https://github.com/rayattack/legodom)
 
 ---
 
-## Custom Events (`$emit`)
-
-Child components communicate upward using events.
+## Why Lego?
 
-```html
-<button @click="$emit('save', data)">Save</button>
-```
-
-Events:
-
-* bubble
-* cross Shadow DOM boundaries
-* are standard `CustomEvent`s
+- ⚡ **Extremely Fast** – No virtual DOM. No reconciliation. Direct DOM updates.
+- 📦 **Zero Dependencies** – Weighs less than 4kb gzipped.
+- 🛠️ **No Build Step** – Works directly in the browser with standard `<script>` tags.
+- 🧩 **Native Web Components** – Real Custom Elements, real Shadow DOM.
+- 📝 **Familiar Mentals** – Plain JavaScript objects for state, plain HTML for templates.
 
 ---
 
-## 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:
+## Quick Start (No Build Required)
 
 ```html
-<p>User ID: {{ global.params.id }}</p>
-```
+<!DOCTYPE html>
+<html>
+<body>
+  <hello-world></hello-world>
 
-Navigation:
+  <template b-id="hello-world">
+    <style>
+      h1 { color: #ffca28; font-family: sans-serif; }
+    </style>
+    <h1>Hello, {{ name }}!</h1>
+    <button @click="toggle()">Toggle Name</button>
+  </template>
 
-```html
-<a href="/dashboard" b-link>Dashboard</a>
+  <script src="https://unpkg.com/lego-dom/main.js"></script>
+  <script>
+    document.querySelector('hello-world').state = {
+      name: 'World',
+      toggle() {
+        this.name = this.name === 'World' ? 'Lego' : 'World';
+      }
+    };
+  </script>
+</body>
+</html>
 ```
 
 ---
 
-## 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.
-
----
-
-## Single File Components (SFC)
+## Also Supports Modern Toolchains
 
-LegoJS supports **Single File Components** using `.lego` files when using a build tool like Vite.
-
-### .lego File Format
-
-A `.lego` file contains three optional sections:
+Lego includes a **Vite plugin** for developers who prefer **Single File Components (.lego)**:
 
 ```html
+<!-- user-card.lego -->
 <template>
-  <!-- Your HTML markup with directives -->
-  <h1>{{ title }}</h1>
-  <button @click="count++">{{ count }}</button>
+  <h1>{{ name }}</h1>
 </template>
 
-<script>
-export default {
-  // Your component logic/state
-  title: 'Hello',
-  count: 0
-}
-</script>
-
 <style>
-  /* Scoped CSS using self keyword */
-  self {
-    display: block;
-    padding: 1rem;
-  }
+  self { display: block; padding: 20px; }
 </style>
-```
-
-The component name is automatically derived from the filename (e.g., `sample-component.lego` → `<sample-component>`).
-
----
-
-## Vite Plugin Setup
-
-### Installation
-
-```bash
-npm install lego-dom vite
-```
-
-### Configuration
-
-Create `vite.config.js`:
-
-```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
-    })
-  ]
-});
-```
-
-### Usage
-
-Create your components in `.lego` files:
-
-```
-src/
-  components/
-    my-button.lego
-    user-card.lego
-  main.js
-index.html
-```
-
-In your `main.js`:
-
-```js
-import { Lego } from 'lego-dom/main.js';
-import registerComponents from 'virtual:lego-components';
-
-registerComponents();
-```
-
-In your HTML:
 
-```html
-<my-button></my-button>
-<user-card></user-card>
+<script>
+  export default { name: 'John Doe' }
+</script>
 ```
 
-**Auto-discovery**: The Vite plugin automatically finds all `.lego` files and registers them with LegoJS!
-
 ---
 
-## Two Usage Modes
-
-LegoJS works in **two modes**:
-
-### 1. Without Build Tooling
-
-Include `main.js` directly and use `<template b-id>` or `Lego.define()`:
-
-```html
-<script src="node_modules/lego-dom/main.js"></script>
-<template b-id="my-component">
-  <h1>Hello</h1>
-</template>
-```
-
-### 2. With Vite (SFC)
-
-Use `.lego` files that are auto-discovered and compiled:
-
-```bash
-npm run dev
-```
-
-Both modes use the same LegoJS runtime and support all the same features!
-
----
+## 🔗 Links
 
-## Summary
+- 📖 [Full Documentation](https://rayattack.github.io/legodom/)
+- 🚀 [Quick Start Guide](https://rayattack.github.io/legodom/guide/quick-start)
+- 🔌 [Vite Plugin Setup](https://rayattack.github.io/legodom/api/vite-plugin)
+- 🧪 [Example Showcase](https://rayattack.github.io/legodom/examples/)
 
-* 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
+## License
 
-That’s it.
+MIT © [Tersoo Ortserga](https://github.com/rayattack)

package/docs/.vitepress/config.js

@@ -1,9 +1,9 @@
 import { defineConfig } from 'vitepress';
 
 export default defineConfig({
-  title: 'LegoJS',
-  description: 'A tiny, zero-dependency JavaScript library for building reactive Web Components',
-  base: '/LegoJS/',
+  title: 'Lego',
+  description: 'A feature-rich web components + SFC frontend framework',
+  base: '/legodom/',
 
   themeConfig: {
     logo: '/logo.svg',
@@ -26,7 +26,7 @@ export default defineConfig({
         {
           text: 'Introduction',
           items: [
-            { text: 'What is LegoJS?', link: '/guide/' },
+            { text: 'What is Lego?', link: '/guide/' },
             { text: 'Getting Started', link: '/guide/getting-started' },
             { text: 'Quick Start', link: '/guide/quick-start' },
             { text: 'Contributing', link: '/guide/contributing' }

package/docs/.vitepress/dist/404.html

@@ -3,20 +3,20 @@
   <head>
     <meta charset="utf-8">
     <meta name="viewport" content="width=device-width,initial-scale=1">
-    <title>404 | LegoJS</title>
+    <title>404 | Lego</title>
     <meta name="description" content="Not Found">
     <meta name="generator" content="VitePress v1.6.4">
     <link rel="preload stylesheet" href="/LegoJS/assets/style.eycE2Jhw.css" as="style">
     <link rel="preload stylesheet" href="/LegoJS/vp-icons.css" as="style">
     
-    <script type="module" src="/LegoJS/assets/app.BG5s3B0P.js"></script>
+    <script type="module" src="/LegoJS/assets/app.BfblNDJy.js"></script>
     <link rel="preload" href="/LegoJS/assets/inter-roman-latin.Di8DUHzh.woff2" as="font" type="font/woff2" crossorigin="">
     <script id="check-dark-mode">(()=>{const e=localStorage.getItem("vitepress-theme-appearance")||"auto",a=window.matchMedia("(prefers-color-scheme: dark)").matches;(!e||e==="auto"?a:e==="dark")&&document.documentElement.classList.add("dark")})();</script>
     <script id="check-mac-os">document.documentElement.classList.toggle("mac",/Mac|iPhone|iPod|iPad/i.test(navigator.platform));</script>
   </head>
   <body>
     <div id="app"></div>
-    <script>window.__VP_HASH_MAP__=JSON.parse("{\"api_define.md\":\"UA-ygUnQ\",\"api_directives.md\":\"BV-D251p\",\"api_globals.md\":\"DOjt7AV0\",\"api_index.md\":\"OS6h01ct\",\"api_lifecycle.md\":\"Ccm5xw6-\",\"api_route.md\":\"CAHf_KNp\",\"api_vite-plugin.md\":\"DNn9VhL5\",\"examples_form.md\":\"B3stGKbu\",\"examples_index.md\":\"BDEG_D4J\",\"examples_routing.md\":\"bqZ9DjDK\",\"examples_sfc-showcase.md\":\"DLXaUiop\",\"examples_todo-app.md\":\"D5RhZoo5\",\"guide_cdn-usage.md\":\"CAjf03Lr\",\"guide_components.md\":\"BIFWF1Hc\",\"guide_contributing.md\":\"BgbUN-Mr\",\"guide_directives.md\":\"Bi3ynu1d\",\"guide_getting-started.md\":\"2Nr1lp2z\",\"guide_index.md\":\"GvZq_Yf2\",\"guide_lifecycle.md\":\"B28j1OzS\",\"guide_quick-start.md\":\"CNk3VGTF\",\"guide_reactivity.md\":\"CVsaMaPv\",\"guide_routing.md\":\"DSpDP25o\",\"guide_sfc.md\":\"CVUP66tS\",\"guide_templating.md\":\"BgCGe4aa\",\"index.md\":\"xV1taCED\"}");window.__VP_SITE_DATA__=JSON.parse("{\"lang\":\"en-US\",\"dir\":\"ltr\",\"title\":\"LegoJS\",\"description\":\"A tiny, zero-dependency JavaScript library for building reactive Web Components\",\"base\":\"/LegoJS/\",\"head\":[],\"router\":{\"prefetchLinks\":true},\"appearance\":true,\"themeConfig\":{\"logo\":\"/logo.svg\",\"nav\":[{\"text\":\"Guide\",\"link\":\"/guide/\"},{\"text\":\"API\",\"link\":\"/api/\"},{\"text\":\"Examples\",\"link\":\"/examples/\"},{\"text\":\"v0.0.7\",\"items\":[{\"text\":\"Changelog\",\"link\":\"https://github.com/rayattack/LegoJS/releases\"}]}],\"sidebar\":{\"/guide/\":[{\"text\":\"Introduction\",\"items\":[{\"text\":\"What is LegoJS?\",\"link\":\"/guide/\"},{\"text\":\"Getting Started\",\"link\":\"/guide/getting-started\"},{\"text\":\"Quick Start\",\"link\":\"/guide/quick-start\"},{\"text\":\"Contributing\",\"link\":\"/guide/contributing\"}]},{\"text\":\"Core Concepts\",\"items\":[{\"text\":\"Components\",\"link\":\"/guide/components\"},{\"text\":\"Templating\",\"link\":\"/guide/templating\"},{\"text\":\"Reactivity\",\"link\":\"/guide/reactivity\"},{\"text\":\"Directives\",\"link\":\"/guide/directives\"}]},{\"text\":\"Advanced\",\"items\":[{\"text\":\"Single File Components\",\"link\":\"/guide/sfc\"},{\"text\":\"Routing\",\"link\":\"/guide/routing\"},{\"text\":\"CDN Usage\",\"link\":\"/guide/cdn-usage\"},{\"text\":\"Lifecycle Hooks\",\"link\":\"/guide/lifecycle\"}]}],\"/api/\":[{\"text\":\"API Reference\",\"items\":[{\"text\":\"Overview\",\"link\":\"/api/\"},{\"text\":\"Lego.define()\",\"link\":\"/api/define\"},{\"text\":\"Lego.route()\",\"link\":\"/api/route\"},{\"text\":\"Lego.globals\",\"link\":\"/api/globals\"},{\"text\":\"Directives\",\"link\":\"/api/directives\"},{\"text\":\"Directives\",\"link\":\"/api/directives\"},{\"text\":\"Lifecycle Hooks\",\"link\":\"/api/lifecycle\"},{\"text\":\"Vite Plugin\",\"link\":\"/api/vite-plugin\"}]}],\"/examples/\":[{\"text\":\"Examples\",\"items\":[{\"text\":\"Overview\",\"link\":\"/examples/\"},{\"text\":\"Todo App\",\"link\":\"/examples/todo-app\"},{\"text\":\"Routing Demo\",\"link\":\"/examples/routing\"},{\"text\":\"SFC Showcase\",\"link\":\"/examples/sfc-showcase\"},{\"text\":\"Form Validation\",\"link\":\"/examples/form\"}]}]},\"socialLinks\":[{\"icon\":\"github\",\"link\":\"https://github.com/rayattack/LegoJS\"}],\"footer\":{\"message\":\"Released under the MIT License.\",\"copyright\":\"Copyright © 2024-present\"},\"search\":{\"provider\":\"local\"},\"editLink\":{\"pattern\":\"https://github.com/rayattack/LegoJS/edit/main/docs/:path\",\"text\":\"Edit this page on GitHub\"}},\"locales\":{},\"scrollOffset\":134,\"cleanUrls\":false}");</script>
+    <script>window.__VP_HASH_MAP__=JSON.parse("{\"api_define.md\":\"UA-ygUnQ\",\"api_directives.md\":\"BV-D251p\",\"api_globals.md\":\"CEznyRAY\",\"api_index.md\":\"IEYUxUIr\",\"api_lifecycle.md\":\"Ccm5xw6-\",\"api_route.md\":\"CAHf_KNp\",\"api_vite-plugin.md\":\"DC8Li09k\",\"examples_form.md\":\"DQoAgbLR\",\"examples_index.md\":\"CVJJjXXE\",\"examples_routing.md\":\"sRnA5RXw\",\"examples_sfc-showcase.md\":\"DPf9Wm99\",\"examples_todo-app.md\":\"CqF4JaWn\",\"guide_cdn-usage.md\":\"CjIjusre\",\"guide_components.md\":\"CMU3iM6R\",\"guide_contributing.md\":\"Crrv3T_0\",\"guide_directives.md\":\"DFwqvqOv\",\"guide_getting-started.md\":\"DtaJPe0i\",\"guide_index.md\":\"DtJVpLI9\",\"guide_lifecycle.md\":\"CfY3jlU1\",\"guide_quick-start.md\":\"CwdNNA21\",\"guide_reactivity.md\":\"DgTH0MTn\",\"guide_routing.md\":\"nMB0QOBR\",\"guide_sfc.md\":\"BUkWma1z\",\"guide_templating.md\":\"XI3uUlYI\",\"index.md\":\"M4_o26kF\"}");window.__VP_SITE_DATA__=JSON.parse("{\"lang\":\"en-US\",\"dir\":\"ltr\",\"title\":\"Lego\",\"description\":\"A feature-rich web components + SFC frontend framework\",\"base\":\"/LegoJS/\",\"head\":[],\"router\":{\"prefetchLinks\":true},\"appearance\":true,\"themeConfig\":{\"logo\":\"/logo.svg\",\"nav\":[{\"text\":\"Guide\",\"link\":\"/guide/\"},{\"text\":\"API\",\"link\":\"/api/\"},{\"text\":\"Examples\",\"link\":\"/examples/\"},{\"text\":\"v0.0.7\",\"items\":[{\"text\":\"Changelog\",\"link\":\"https://github.com/rayattack/LegoJS/releases\"}]}],\"sidebar\":{\"/guide/\":[{\"text\":\"Introduction\",\"items\":[{\"text\":\"What is Lego?\",\"link\":\"/guide/\"},{\"text\":\"Getting Started\",\"link\":\"/guide/getting-started\"},{\"text\":\"Quick Start\",\"link\":\"/guide/quick-start\"},{\"text\":\"Contributing\",\"link\":\"/guide/contributing\"}]},{\"text\":\"Core Concepts\",\"items\":[{\"text\":\"Components\",\"link\":\"/guide/components\"},{\"text\":\"Templating\",\"link\":\"/guide/templating\"},{\"text\":\"Reactivity\",\"link\":\"/guide/reactivity\"},{\"text\":\"Directives\",\"link\":\"/guide/directives\"}]},{\"text\":\"Advanced\",\"items\":[{\"text\":\"Single File Components\",\"link\":\"/guide/sfc\"},{\"text\":\"Routing\",\"link\":\"/guide/routing\"},{\"text\":\"CDN Usage\",\"link\":\"/guide/cdn-usage\"},{\"text\":\"Lifecycle Hooks\",\"link\":\"/guide/lifecycle\"}]}],\"/api/\":[{\"text\":\"API Reference\",\"items\":[{\"text\":\"Overview\",\"link\":\"/api/\"},{\"text\":\"Lego.define()\",\"link\":\"/api/define\"},{\"text\":\"Lego.route()\",\"link\":\"/api/route\"},{\"text\":\"Lego.globals\",\"link\":\"/api/globals\"},{\"text\":\"Directives\",\"link\":\"/api/directives\"},{\"text\":\"Lifecycle Hooks\",\"link\":\"/api/lifecycle\"},{\"text\":\"Vite Plugin\",\"link\":\"/api/vite-plugin\"}]}],\"/examples/\":[{\"text\":\"Examples\",\"items\":[{\"text\":\"Overview\",\"link\":\"/examples/\"},{\"text\":\"Todo App\",\"link\":\"/examples/todo-app\"},{\"text\":\"Routing Demo\",\"link\":\"/examples/routing\"},{\"text\":\"SFC Showcase\",\"link\":\"/examples/sfc-showcase\"},{\"text\":\"Form Validation\",\"link\":\"/examples/form\"}]}]},\"socialLinks\":[{\"icon\":\"github\",\"link\":\"https://github.com/rayattack/LegoJS\"}],\"footer\":{\"message\":\"Released under the MIT License.\",\"copyright\":\"Copyright © 2024-present\"},\"search\":{\"provider\":\"local\"},\"editLink\":{\"pattern\":\"https://github.com/rayattack/LegoJS/edit/main/docs/:path\",\"text\":\"Edit this page on GitHub\"}},\"locales\":{},\"scrollOffset\":134,\"cleanUrls\":false}");</script>
     
   </body>
 </html>