lego-dom 0.0.7 → 0.0.9

package/.github/workflows/deploy-docs.yml

@@ -0,0 +1,56 @@
+name: Deploy Documentation
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: npm
+
+      - name: Setup Pages
+        uses: actions/configure-pages@v4
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Build with VitePress
+        run: npm run docs:build
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: docs/.vitepress/dist
+
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    needs: build
+    runs-on: ubuntu-latest
+    name: Deploy
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tersoo Ortserga
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,344 +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.
+[**Explore the Docs**](https://rayattack.github.io/legodom/) | [**Examples**](https://rayattack.github.io/legodom/examples/) | [**GitHub**](https://github.com/rayattack/legodom)
 
 ---
 
-## 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:
+## Why Lego?
 
-```html
-<script src="node_modules/lego-dom/main.js"></script>
-```
-
-Once loaded, `Lego` is available globally.
+- ⚡ **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.
 
 ---
 
-## 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`.
+## Quick Start (No Build Required)
 
 ```html
-<template b-id="hello-card">
-  <style>
-    self {
-      display: block;
-      padding: 1rem;
-      border: 1px solid #ccc;
-    }
-  </style>
+<!DOCTYPE html>
+<html>
+<body>
+  <hello-world></hello-world>
 
-  <h2>Hello {{ name }}</h2>
-  <button @click="count++">Clicked {{ count }} times</button>
-</template>
-```
+  <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>
 
-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>
+  <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>
 ```
 
-No setters. No actions. No reducers.
-
-Just mutate data.
-
 ---
 
-## Templating (`{{ }}`)
+## Also Supports Modern Toolchains
 
-Text interpolation works in:
-
-* Text nodes
-* Attributes
-* Class names
+Lego includes a **Vite plugin** for developers who prefer **Single File Components (.lego)**:
 
 ```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
+<!-- user-card.lego -->
+<template>
+  <h1>{{ name }}</h1>
+</template>
 
-You can also define components programmatically:
+<style>
+  self { display: block; padding: 20px; }
+</style>
 
-```js
-Lego.define(
-  'counter-box',
-  `
-  <style>self { display:block }</style>
-  <button @click="count++">{{ count }}</button>
-  `,
-  { count: 0 }
-);
+<script>
+  export default { name: 'John Doe' }
+</script>
 ```
 
 ---
 
-## 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.
-
----
+## 🔗 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

@@ -0,0 +1,107 @@
+import { defineConfig } from 'vitepress';
+
+export default defineConfig({
+  title: 'Lego',
+  description: 'A feature-rich web components + SFC frontend framework',
+  base: '/legodom/',
+
+  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'
+    }
+  },
+
+  markdown: {
+    theme: {
+      light: 'github-light',
+      dark: 'github-dark'
+    }
+  }
+});

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

@@ -0,0 +1,22 @@
+<!DOCTYPE html>
+<html lang="en-US" dir="ltr">
+  <head>
+    <meta charset="utf-8">
+    <meta name="viewport" content="width=device-width,initial-scale=1">
+    <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.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\":\"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>