lego-dom 1.0.0 → 1.3.4

package/docs/tutorial/05-state-and-globals.md

@@ -0,0 +1,285 @@
+# Step 5: State & Globals
+
+You've built a complete app! Now let's understand how state management works in LegoDOM and explore advanced patterns.
+
+## Two Levels of State
+
+### 1. Component State (Local)
+
+Each component has its own reactive state defined in the `<script>` section:
+
+```javascript
+export default {
+  // This is local to THIS component instance
+  count: 0,
+  items: [],
+  
+  increment() {
+    this.count++;  // Triggers re-render of THIS component only
+  }
+}
+```
+
+### 2. Global State (`Lego.globals`)
+
+Shared across ALL components. Perfect for user sessions, themes, shopping carts, etc.
+
+```javascript
+// In app.js or any component
+Lego.globals.user = { name: 'John' };
+Lego.globals.theme = 'dark';
+Lego.globals.cart = [];
+
+// In any component
+console.log(Lego.globals.user.name);  // 'John'
+```
+
+## Accessing Globals in Components
+
+### In JavaScript (Methods)
+
+```javascript
+export default {
+  mounted() {
+    // Direct access
+    console.log(Lego.globals.user);
+  },
+  
+  toggleTheme() {
+    Lego.globals.theme = Lego.globals.theme === 'dark' ? 'light' : 'dark';
+  }
+}
+```
+
+### In Templates
+
+Use the `global` keyword:
+
+```html
+<template>
+  <p>Hello, [[ global.user.name ]]!</p>
+  <div class="[[ global.theme ]]">
+    Content styled by theme
+  </div>
+  <button b-show="global.user">Logout</button>
+</template>
+```
+
+## Route State (`$route`)
+
+Access current route information:
+
+```javascript
+// Available in any component
+this.$route.url       // '/users/42?tab=posts'
+this.$route.route     // '/users/:id'
+this.$route.params    // { id: '42' }
+this.$route.query     // { tab: 'posts' }
+```
+
+```html
+<template>
+  <h1>User [[ $route.params.id ]]</h1>
+  <p>Current tab: [[ $route.query.tab ]]</p>
+</template>
+```
+
+## State Patterns
+
+### Pattern 1: User Authentication
+
+```javascript
+// app.js
+Lego.globals.user = null;  // Initialize
+
+// login-page.lego
+handleLogin() {
+  Lego.globals.user = { name: 'John', token: 'abc123' };
+  this.$go('/dashboard').get();
+}
+
+// Any protected component
+mounted() {
+  if (!Lego.globals.user) {
+    this.$go('/login').get();
+  }
+}
+```
+
+### Pattern 2: Theme Switching
+
+```javascript
+// app.js
+Lego.globals.theme = localStorage.getItem('theme') || 'light';
+
+// theme-toggle.lego
+<template>
+  <button @click="toggle()">
+    [[ global.theme === 'dark' ? '☀️' : '🌙' ]]
+  </button>
+</template>
+
+<script>
+export default {
+  toggle() {
+    const newTheme = Lego.globals.theme === 'dark' ? 'light' : 'dark';
+    Lego.globals.theme = newTheme;
+    localStorage.setItem('theme', newTheme);
+    document.body.className = newTheme;
+  }
+}
+</script>
+```
+
+### Pattern 3: Shopping Cart
+
+```javascript
+// app.js
+Lego.globals.cart = [];
+
+// product-card.lego
+addToCart() {
+  Lego.globals.cart.push({
+    id: this.product.id,
+    name: this.product.name,
+    price: this.product.price
+  });
+}
+
+// cart-icon.lego
+<template>
+  <span class="cart">
+    🛒 [[ global.cart.length ]]
+  </span>
+</template>
+```
+
+### Pattern 4: Fetching Data
+
+```javascript
+export default {
+  users: [],
+  loading: true,
+  error: null,
+  
+  async mounted() {
+    try {
+      const response = await fetch('/api/users');
+      this.users = await response.json();
+    } catch (e) {
+      this.error = e.message;
+    } finally {
+      this.loading = false;
+    }
+  }
+}
+```
+
+```html
+<template>
+  <div b-show="loading">Loading...</div>
+  <div b-show="error" class="error">[[ error ]]</div>
+  <ul b-show="!loading && !error">
+    <li b-for="user in users">[[ user.name ]]</li>
+  </ul>
+</template>
+```
+
+## Cross-Component Communication
+
+### Using `$emit` (Child to Parent)
+
+```html
+<!-- child-component.lego -->
+<template>
+  <button @click="notifyParent()">Click Me</button>
+</template>
+
+<script>
+export default {
+  notifyParent() {
+    this.$emit('custom-event', { message: 'Hello from child!' });
+  }
+}
+</script>
+```
+
+```html
+<!-- parent-component.lego -->
+<template>
+  <child-component @custom-event="handleEvent(event)"></child-component>
+</template>
+
+<script>
+export default {
+  handleEvent(event) {
+    console.log(event.detail.message);  // 'Hello from child!'
+  }
+}
+</script>
+```
+
+### Using `$ancestors` (Access Parent State)
+
+```javascript
+// In a deeply nested component
+mounted() {
+  // Get state from a specific ancestor by tag name
+  const parentState = this.$ancestors('user-profile');
+  console.log(parentState.userId);
+}
+```
+
+## Best Practices
+
+| Do | Don't |
+|----|-------|
+| ✅ Use `Lego.globals` for truly global state (user, theme) | ❌ Put everything in globals |
+| ✅ Keep component state local when possible | ❌ Over-engineer state management |
+| ✅ Initialize globals in `app.js` | ❌ Initialize globals in random components |
+| ✅ Use `$emit` for child→parent communication | ❌ Reach into child component internals |
+
+## Complete State Cheatsheet
+
+| I want to... | Use this |
+|--------------|----------|
+| Store component-local data | `export default { myData: ... }` |
+| Share data app-wide | `Lego.globals.myData = ...` |
+| Read global in template | `[[ global.myData ]]` |
+| Read global in JS | `Lego.globals.myData` |
+| Get route params | `this.$route.params.id` |
+| Get query string | `this.$route.query.tab` |
+| Notify parent component | `this.$emit('event-name', data)` |
+| Navigate with state | Set globals before `$go()` |
+
+## What's Next?
+
+🎉 **Congratulations!** You've completed the LegoDOM tutorial!
+
+You now know how to:
+- Set up a project from scratch
+- Create beautiful components
+- Navigate between pages
+- Share state across your app
+
+### Continue Learning
+
+- [Components Deep Dive](/guide/components) – Advanced component patterns
+- [Directives Reference](/guide/directives) – All `b-*` directives explained
+- [Routing Guide](/guide/routing) – Surgical swaps and advanced routing
+- [API Reference](/api/) – Complete API documentation
+
+### Get Help
+
+- 💬 [GitHub Discussions](https://github.com/rayattack/LegoDOM/discussions)
+- 🐛 [Report Issues](https://github.com/rayattack/LegoDOM/issues)
+
+---
+
+<div style="text-align: center; margin-top: 3rem; padding: 2rem; background: linear-gradient(135deg, #667eea 0%, #764ba2 100%); border-radius: 16px; color: white;">
+  <h2 style="margin-bottom: 1rem;">You Did It! 🚀</h2>
+  <p style="opacity: 0.9; margin-bottom: 1.5rem;">You've built a complete multi-page app with LegoDOM.</p>
+  <a href="/guide/" style="display: inline-block; background: white; color: #667eea; padding: 0.75rem 1.5rem; border-radius: 8px; text-decoration: none; font-weight: 600;">
+    Explore More Guides →
+  </a>
+</div>

package/docs/tutorial/index.md

@@ -0,0 +1,40 @@
+# Your First LegoDOM App
+
+Welcome! In the next 15 minutes, you'll build a complete multi-page application with beautiful components, smooth navigation, and a login flow. No prior framework experience needed.
+
+## What You'll Build
+
+A polished app with:
+- 🏠 **Landing Page** – Your app's front door
+- 🔐 **Login Page** – A form that validates and navigates
+- 🎉 **Welcome Page** – Personalized dashboard after login
+
+All using Single File Components (`.lego` files) and client-side routing.
+
+## Prerequisites
+
+- Node.js 18+ installed
+- A code editor (VS Code recommended)
+- Basic HTML/CSS/JavaScript knowledge
+
+## Tutorial Path
+
+| Step | You'll Learn |
+|------|--------------|
+| [1. Project Setup](./01-project-setup) | Create a new project with Vite |
+| [2. Your First Component](./02-your-first-component) | Build a `.lego` file |
+| [3. Adding Routes](./03-adding-routes) | Navigate between pages |
+| [4. Multi-Page App](./04-multi-page-app) | Complete login flow |
+| [5. State & Globals](./05-state-and-globals) | Share data across pages |
+
+## Ready?
+
+<div style="text-align: center; margin: 2rem 0;">
+  <a href="./01-project-setup" style="display: inline-block; background: linear-gradient(135deg, #667eea 0%, #764ba2 100%); color: white; padding: 1rem 2rem; border-radius: 8px; text-decoration: none; font-weight: 600; font-size: 1.2rem;">
+    Start Building →
+  </a>
+</div>
+
+::: tip No Build Tools? No Problem!
+If you want to skip the Vite setup and use LegoDOM via CDN, check out the [CDN Quick Start](/guide/cdn-usage). You can always come back to this tutorial later.
+:::

package/examples/vite-app/index.html

@@ -32,6 +32,7 @@
 
 <body>
   <app-navbar></app-navbar>
+  <side-menu></side-menu>
   <lego-router id="app-outlet"></lego-router>
   <aside id="outside-router"></aside>
 

package/examples/vite-app/src/app.js

@@ -1,8 +1,8 @@
 // Import Tailwind CSS
 import './app.css';
 
-// Import Lego core
-import { Lego } from 'lego-dom/main.js';
+// Import Lego core (local for testing)
+import { Lego } from '../../../lego.js';
 
 // Import virtual module that auto-discovers and registers all .lego components
 import registerComponents from 'virtual:lego-components';

package/examples/vite-app/src/components/side-menu.lego

@@ -0,0 +1,46 @@
+<style>
+  /* @import 'https://fonts.googleapis.com/css2?family=Material+Symbols+Rounded:wght@400;700&display=swap'; */
+  self {
+    display: flex;
+    flex-direction: column;
+    align-items: center;
+    justify-content: center;
+  }
+  .tooltipped:hover .tooltip {
+    visibility: visible;
+  }
+  .tooltip {
+    visibility: hidden;
+    width: 120px;
+    background-color: black;
+    color: #fff;
+    text-align: center;
+    border-radius: 5px;
+    padding: 5px 0;
+    position: absolute;
+    z-index: 1;
+    bottom: 125%;
+    left: 50%;
+    margin-left: -60px;
+  }
+</style>
+
+<template>
+  <div>
+    <span b-for="menu in [
+      { icon: 'home', name: 'Home' },
+      { icon: 'mail', name: 'Mail' },
+      { icon: 'calendar', name: 'Calendar' },
+      { icon: 'person', name: 'Profile' },
+    ]">
+      <p>[[ menu.name ]]</p>
+    </span>
+  </div>
+  <p>[[ name ]]</p>
+</template>
+
+<script>
+export default {
+  name: 'side-menu'
+}
+</script>

package/examples/vite-app/vite.config.js

@@ -9,7 +9,8 @@ export default defineConfig({
   plugins: [
     legoPlugin({
       componentsDir: './src/components',
-      include: ['**/*.lego']
+      include: ['**/*.lego'],
+      importPath: 'lego-dom/main.js' // Use the alias defined below
     }),
     tailwindcss()
   ],