lego-dom 1.3.4 → 1.4.0

package/CHANGELOG.md

@@ -2,6 +2,61 @@
 
 All notable changes to this project will be documented in this file.
 
+## [1.4.0] - 2026-01-16
+
+### Breaking Changes
+
+- **`$ancestors()` now returns element instead of state:** For consistency with `$element`, `$ancestors()` now returns the ancestor element. Access state via `.state` property.
+  ```javascript
+  // Before (v1.3.x)
+  const userId = this.$ancestors('user-profile').userId;
+  
+  // After (v1.4.0)
+  const userId = this.$ancestors('user-profile').state.userId;
+  ```
+  **Migration:** Add `.state` after all `$ancestors()` calls that access component state.
+
+## [1.3.5] - 2026-01-16
+
+### Features
+
+- **Lego Studio:** Added zero-config component development environment. Enable with `Lego.init(document.body, { studio: true })` and navigate to `/_/studio` to browse, preview, and inspect components in real-time.
+  - Component browser with search/filter
+  - Live component preview in isolation
+  - Real-time state inspector with JSON editor
+  - URL deep linking for sharing components
+  - Published as separate package: `@legodom/studio@0.0.2`
+
+- **Advanced API:** Exposed `Lego.snap()` and `Lego.unsnap()` for manual component initialization and cleanup. Useful for building dev tools, testing, and dynamic component creation in Shadow DOMs.
+  ```javascript
+  const el = document.createElement('my-component');
+  mount.appendChild(el);
+  Lego.snap(el);  // Manually initialize
+  
+  // Later...
+  Lego.unsnap(el);  // Clean up
+  ```
+
+- **Component State Property:** Added `element.state` getter/setter to all component instances for cleaner state access.
+  ```javascript
+  // Before (internal API)
+  const state = element._studs;
+  
+  // After (public API)
+  const state = element.state;
+  element.state = { count: 5 };  // Merges into existing state
+  ```
+
+### Documentation
+
+- **Advanced API Guide:** Added comprehensive documentation for `Lego.snap()` and `Lego.unsnap()` at `/docs/api/advanced.md`
+- **Lego Studio Guide:** Added full Studio documentation at `/docs/guide/studio.md` with quick start, examples, and troubleshooting
+
+### Improvements
+
+- **Studio CDN Loading:** Studio is loaded on-demand from unpkg CDN when `studio: true` is set, keeping core LegoDOM lightweight
+- **State Reactivity:** The `element.state` setter uses `Object.assign()` to merge new values while preserving the reactive Proxy
+
 ## [1.3.4] - 2026-01-16
 
 ### Improvements

package/main.js

@@ -193,11 +193,11 @@ const Lego = (() => {
     return current ?? '';
   };
 
-  const findAncestorState = (el, tagName) => {
+  const findAncestor = (el, tagName) => {
     let parent = el.parentElement || el.getRootNode().host;
     while (parent) {
       if (parent.tagName && parent.tagName.toLowerCase() === tagName.toLowerCase()) {
-        return parent._studs;
+        return parent;
       }
       parent = parent.parentElement || (parent.getRootNode && parent.getRootNode().host);
     }
@@ -231,7 +231,7 @@ const Lego = (() => {
       }
 
       const helpers = {
-        $ancestors: (tag) => findAncestorState(context.self, tag),
+        $ancestors: (tag) => findAncestor(context.self, tag),
         $registry: (tag) => sharedStates.get(tag.toLowerCase()),
         $element: context.self,
         $route: Lego.globals.$route,
@@ -568,6 +568,13 @@ const Lego = (() => {
         get $go() { return Lego.globals.$go }
       }, el);
 
+      Object.defineProperty(el, 'state', {
+        get() { return this._studs },
+        set(v) { Object.assign(this._studs, v) },
+        configurable: true,
+        enumerable: false
+      });
+
       shadow.appendChild(tpl);
 
       const style = shadow.querySelector('style');
@@ -649,6 +656,8 @@ const Lego = (() => {
   };
 
   const publicAPI = {
+    snap,
+    unsnap,
     init: async (root = document.body, options = {}) => {
       if (!root || typeof root.nodeType !== 'number') root = document.body;
       styleConfig = options.styles || {};
@@ -706,6 +715,17 @@ const Lego = (() => {
       bind(root, root);
       render(root);
 
+      if (options.studio) {
+        if (!registry['lego-studio']) {
+          const script = document.createElement('script');
+          script.src = 'https://unpkg.com/@legodom/studio@0.0.2/dist/lego-studio.js';
+          script.onerror = () => console.warn('[Lego] Failed to load Studio from CDN');
+          document.head.appendChild(script);
+        }
+        Lego.route('/_/studio', 'lego-studio');
+        Lego.route('/_/studio/:component', 'lego-studio');
+      }
+
       if (routes.length > 0) {
         // Smart History: Restore surgical targets on Back button
         window.addEventListener('popstate', (event) => {
@@ -826,6 +846,7 @@ const Lego = (() => {
     },
     // For specific test validation
     getActiveComponentsCount: () => activeComponents.size,
+    getLegos: () => Object.keys(registry),
     config, // Expose config for customization
     route: (path, tagName, middleware = null) => {
       const paramNames = [];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lego-dom",
-  "version": "1.3.4",
+  "version": "1.4.0",
   "license": "MIT",
   "description": "A feature-rich web components + SFC frontend framework",
   "main": "main.js",

package/vite-plugin.js

@@ -153,20 +153,6 @@ export default '${parsed.componentName}';
       }
     },
 
-    transform(code, id) {
-      if (id.endsWith('.lego') && !id.includes('?')) {
-        const parsed = parseLego(code, path.basename(id));
-        const validation = validateLego(parsed);
-
-        if (!validation.valid) {
-          throw new Error(`Invalid .lego file:\n${validation.errors.join('\n')}`);
-        }
 
-        return {
-          code: generateDefineCall(parsed),
-          map: null
-        };
-      }
-    }
   };
 }

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

@@ -1,56 +0,0 @@
-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/.legodom

@@ -1,87 +0,0 @@
-# LegoDOM Framework Definition (.legodom)
-
-This file defines the valid syntax, API, and behavior of the LegoDOM framework. Use this context to write valid `.lego` components and understand the runtime behavior.
-
-## 1. Component Structure (.lego)
-A `.lego` file is a Single File Component (SFC) composed of three sections:
-
-```html
-<template b-styles="optional-style-id">
-  <!-- HTML template with directives -->
-</template>
-
-<script>
-  export default {
-    // Reactive State
-    count: 0,
-    
-    // Lifecycle Hooks
-    mounted() { console.log('Mounted'); },
-    updated() { console.log('State updated'); },
-    unmounted() { console.log('Destroyed'); },
-
-    // Methods
-    increment() { this.count++ }
-  }
-</script>
-
-<style>
-  /* Scoped CSS. 'self' is replaced with ':host' automatically */
-  self { display: block; }
-  h1 { color: blue; }
-</style>
-```
-
-## 2. Template Directives
-
-| Directive | Syntax | Description |
-|-----------|--------|-------------|
-| **b-if** | `b-if="expr"` | Conditionally renders element if `expr` is truthy. Replaced by comment anchor if false. |
-| **b-show**| `b-show="expr"` | Toggles `display: none` based on `expr`. |
-| **b-for** | `b-for="item in list"` | Renders element for each item in `list`. `item` is available in scope. |
-| **b-text**| `b-text="path"` | Sets `textContent` to value at `path` (e.g. `user.name`). |
-| **b-html**| `b-html="expr"` | Sets `innerHTML` to result of `expr`. **Unsafe**. |
-| **b-sync**| `b-sync="path"` | Two-way binding for inputs. Updates `state.path` on input/change. |
-| **Event** | `@event="expr"` | Native event listener. `event` is available in scope. E.g. `@click="save()"`. |
-| **Interpolation** | `[[ expr ]]` | Text interpolation. Delimiters are `[[` and `]]` by default. |
-
-Note: `b-data` can be used on `<template>` or the custom element tag to inject initial state from JSON string.
-
-## 3. Script Context & Helpers
-The `script` exports a default object which becomes the reactive state (`this`).
-Inside methods and template expressions, the following helpers are available:
-
-### Scope
-- **this**: The reactive state of the component.
-- **event**: The native DOM event (only in `@event` handlers).
-
-### Helpers
-- **$element**: The component's host DOM element.
-- **$emit(name, detail)**: Dispatches a CustomEvent `name` with `detail` (bubbles: true, composed: true).
-- **$go(path, ...targets)**: Router navigation helper. Returns object with method calls.
-  - `this.$go('/url', '#target').get()`
-  - `this.$go('/api', '#response').post({data})`
-- **$ancestors(tagName)**: Finds the state of the nearest ancestor component with `tagName`.
-- **$registry(tagName)**: Access shared state of logical-only components defined via `Lego.define`.
-- **$route**: Global route state object.
-
-## 4. Router & Targets
-LegoDOM uses a "Target-Oriented" router. Navigation updates specific DOM elements (targets) rather than full page reloads.
-
-- **Definition**: `Lego.route('/path/:id', 'tag-name', middleware)`
-- **Targets**:
-  - `string`: CSS selector (e.g., `#main`, `user-card`).
-  - `function`: `(allComponents) => elements`
-- **Usage**:
-  - HTML: `<a href="/path" b-target="#main">Link</a>` creates a surgical navigation link.
-  - JS: `this.$go('/path', '#main').get()`
-
-## 5. Lifecycle Hooks
-- **mounted()**: Called when the component is attached to DOM, shadow root created, and initial render complete.
-- **updated()**: Called after reactive state changes have been batched and applied to the DOM.
-- **unmounted()**: Called when component is removed from the DOM.
-
-## 6. Global Configuration
-- `Lego.init(root, { styles: { ... }, loader: callback })`: Initializes the app.
-- `Lego.globals`: Global reactive state shared across all components.
-```

package/docs/.vitepress/config.js

@@ -1,161 +0,0 @@
-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: 'Tutorial', link: '/tutorial/' },
-      { text: 'Contributing', link: '/contributing/' },
-      { text: 'API', link: '/api/' },
-      { text: 'Examples', link: '/examples/' },
-      { text: 'Router', link: '/router/' },
-      {
-        text: 'v1.3.4',
-        items: [
-          { text: 'Changelog', link: 'https://github.com/rayattack/LegoDOM/releases' }
-
-        ]
-      }
-    ],
-
-    sidebar: {
-      '/contributing/': [
-        {
-          text: 'Contributing',
-          items: [
-            { text: 'Topic 1 - Welcome', link: '/contributing/01-welcome' },
-            { text: 'Topic 2 - The Registry', link: '/contributing/02-registry' },
-            { text: 'Topic 3 - Batching', link: '/contributing/03-batcher' },
-            { text: 'Topic 4 - Reactivity', link: '/contributing/04-reactivity' },
-            { text: 'Topic 5 - Caching', link: '/contributing/05-caching' },
-            { text: 'Topic 6 - LegoDOM Init', link: '/contributing/06-init' },
-            { text: 'Topic 7 - Observer', link: '/contributing/07-observer' },
-            { text: 'Topic 8 - Snap', link: '/contributing/08-snap' },
-            { text: 'Topic 9 - Diffing', link: '/contributing/09-diffing' },
-            { text: 'Topic 10 - State', 'link': '/contributing/10-studs' },
-            { text: 'Topic 11 - Scanner', 'link': '/contributing/11-scanner' },
-            { text: 'Topic 12 - Render', 'link': '/contributing/12-render' },
-            { text: 'Topic 13 - Directives', 'link': '/contributing/13-directives' },
-            { text: 'Topic 14 - Events', 'link': '/contributing/14-events' },
-            { text: 'Topic 15 - Router', 'link': '/contributing/15-router' },
-            { text: 'Topic 16 - State', 'link': '/contributing/16-state' },
-            { text: 'Topic 17 - LegoDOM', 'link': '/contributing/17-legodom' },
-          ]
-        }
-      ],
-      '/tutorial/': [
-        {
-          text: 'Tutorial: Your First App',
-          items: [
-            { text: 'Overview', link: '/tutorial/' },
-            { text: '1. Project Setup', link: '/tutorial/01-project-setup' },
-            { text: '2. Your First Component', link: '/tutorial/02-your-first-component' },
-            { text: '3. Adding Routes', link: '/tutorial/03-adding-routes' },
-            { text: '4. Multi-Page App', link: '/tutorial/04-multi-page-app' },
-            { text: '5. State & Globals', link: '/tutorial/05-state-and-globals' }
-          ]
-        }
-      ],
-      '/guide/': [
-        {
-          text: 'Introduction',
-          items: [
-            { text: 'What is LegoDOM?', link: '/guide/' },
-            { text: 'Getting Started', link: '/guide/getting-started' },
-            { text: 'Quick Start', link: '/guide/quick-start' },
-          ]
-        },
-        {
-          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' },
-            { text: 'Large Apps', link: '/guide/directory-structure' },
-            { text: 'FAQ', link: '/guide/faq' }
-          ]
-        }
-      ],
-      '/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: 'Lego.config', link: '/api/config' },
-            { text: 'Directives', link: '/api/directives' },
-            { text: 'Lifecycle Hooks', link: '/api/lifecycle' },
-            { text: 'Vite Plugin', link: '/api/vite-plugin' }
-          ]
-        }
-      ],
-      '/router/': [
-        {
-          text: 'LegoDOM Router',
-          items: [
-            { text: 'About', link: '/router/' },
-            { text: 'Basic Routing', link: '/router/basic-routing' },
-            { text: 'Surgical Swaps', link: '/router/surgical-swaps' },
-            { text: 'Cold Entry', link: '/router/cold-entry' },
-            { text: 'History', link: '/router/history' }
-          ]
-        }
-      ],
-      '/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/LegoDOM' }
-    ],
-
-    footer: {
-      message: 'Released under the MIT License.',
-      copyright: 'Copyright © 2024-present'
-    },
-
-    search: {
-      provider: 'local'
-    },
-
-    editLink: {
-      pattern: 'https://github.com/rayattack/LegoDOM/edit/main/docs/:path',
-      text: 'Edit this page on GitHub'
-    }
-  },
-
-  markdown: {
-    theme: {
-      light: 'github-light',
-      dark: 'github-dark'
-    }
-  }
-});

package/docs/api/config.md

@@ -1,95 +0,0 @@
-# Global Configuration
-
-`Lego.config` allows you to customize framework behavior, including error handling and metrics.
-
-## Properties
-
-### `syntax`
-
-*   **Type**: `'mustache' | 'brackets'`
-*   **Default**: `'brackets'`
-
-Configures the template delimiter style.
-
-*   `'brackets'`: Uses <code v-pre>[[ variable ]]</code> (Default)
-*   `'mustache'`: Uses <code v-pre>{{ variable }}</code> (Legacy/Vue-style)
-
-```javascript
-// Switch back to mustache syntax if preferred
-Lego.config.syntax = 'mustache';
-```
-
-### `loader`
-
-*   **Type**: `(tagName: string) => string | Promise<string> | null`
-*   **Default**: `undefined`
-
-Use this hook to implement **Server-Side Component Delivery**.
-
-**Option 1: Simple Mode (Return URL)**
-We fetch it for you.
-```javascript
-loader: (tag) => `/components/${tag}.lego`
-```
-
-**Option 2: Power Mode (Return Promise)**
-You control the fetch. Useful for **Authentication** (Cookies, JWT) or Custom Headers.
-
-```javascript
-Lego.init(document.body, {
-  loader: async (tagName) => {
-    // Custom Authenticated Fetch
-    const res = await fetch(`/components/${tagName}.lego`, {
-      credentials: 'include', // Send Cookies
-      headers: { 'Authorization': getToken() }
-    });
-    return await res.text(); // Return SFC content directly
-  }
-});
-```
-**Mechanism:**
-1. Browser sees unknown `<admin-widget>`.
-2. `Lego` calls `config.loader('admin-widget')`.
-3. If URL returned, it fetches the file.
-4. The server returns raw SFC content (`<template>...`).
-5. `Lego.defineSFC()` parses and upgrades the element instantly.
-
-### `onError`
-
-*   **Type**: `(error: Error, type: string, context: HTMLElement) => void`
-*   **Default**: `undefined`
-
-Global error handler hook. Called when an error occurs during:
-*   `render`: Template rendering (expression evaluation)
-*   `event-handler`: `@event` callbacks
-*   `define`: Component definition
-*   `sync-update`: `b-sync` updates
-
-```javascript
-Lego.config.onError = (err, type, context) => {
-  console.error(`Error in ${type}:`, err);
-  // Send to Sentry/Datadog
-  captureException(err, { tags: { type } });
-};
-```
-
-### `metrics`
-
-*   **Type**: `Object`
-
-Performance monitoring hooks, primarily used by plugins.
-
-*   `onRenderStart(el)`: Called before a component renders.
-*   `onRenderEnd(el)`: Called after a component finishes rendering.
-
-```javascript
-// Example monitoring implementation
-Lego.config.metrics = {
-  onRenderStart(el) {
-    console.time(el.tagName);
-  },
-  onRenderEnd(el) {
-    console.timeEnd(el.tagName);
-  }
-};
-```

package/docs/api/define.md

@@ -1,58 +0,0 @@
-# Lego.define()
-
-Defining components in JavaScript.
-
-## Type Signature
-
-```ts
-Lego.define(tagName: string, template: string, state?: object)
-```
-
-## Arguments
-
-- **tagName**: The name of the custom element (must contain a hyphen).
-- **template**: The HTML string for the component. Can include `<style>`, markup, and bindings.
-- **state**: Initial state object and methods.
-
-## Example
-
-```js
-import { Lego } from 'lego-dom';
-
-Lego.define('user-card', `
-  <div class="card">
-    <h3>[[ name ]]</h3>
-    <p>[[ role ]]</p>
-  </div>
-`, {
-  name: 'John Doe',
-  role: 'Admin'
-});
-```
-
-## Lego.defineSFC()
-
-Runtime parser for Single File Components (SFC). Useful for **Server-Side Rendering** or dynamic loading architectures.
-
-```ts
-Lego.defineSFC(content: string, filename?: string)
-```
-
-### Example
-
-```javascript
-const sfc = `
-<template>
-  <h1>[[ title ]]</h1>
-</template>
-<script>
-  export default { title: 'Hello World' }
-</script>
-<style>
-  h1 { color: red; }
-</style>
-`;
-
-// Registers <my-component> instantly
-Lego.defineSFC(sfc, 'my-component.lego');
-```

package/docs/api/directives.md

@@ -1,50 +0,0 @@
-# Directives
-
-Special attributes that control DOM behavior.
-
-## b-show
-
-Conditionally render an element.
-
-```html
-<div b-show="loading">Loading...</div>
-<div b-show="!loading">Content loaded!</div>
-```
-
-## b-html
-
-Renders raw HTML. **Security Risk**: Use with caution.
-
-```html
-<div b-html="htmlContent"></div>
-```
-
-## b-for
-
-Render a list of items.
-
-```html
-<ul>
-  <li b-for="user in users">
-    [[ user.name ]]
-  </li>
-</ul>
-```
-
-## b-sync
-
-Two-way data binding for form inputs.
-
-```html
-<input b-sync="username" placeholder="Enter username">
-<p>You typed: [[ username ]]</p>
-```
-
-## @event
-
-Event listeners.
-
-```html
-<button @click="save()">Save</button>
-<input @input="validate($event)">
-```