lego-dom 1.3.3 → 1.4.0

package/docs/tutorial/04-multi-page-app.md

@@ -1,329 +0,0 @@
-# Step 4: Building a Multi-Page App
-
-Let's bring it all together! In this step, we'll complete the **index → login → welcome** flow that every real app needs. You'll see exactly how data flows between pages.
-
-## The Complete App Structure
-
-By the end of this page, you'll have:
-
-```
-src/components/
-├── home-page.lego      ← Landing page (/)
-├── login-page.lego     ← Login form (/login)
-└── welcome-page.lego   ← Dashboard (/welcome)
-```
-
-## Step 1: Create the Welcome Page
-
-Create `src/components/welcome-page.lego`:
-
-```html
-<template>
-  <div class="dashboard">
-    <header>
-      <h1>Welcome, [[ username ]]! 🎉</h1>
-      <button @click="handleLogout()">Logout</button>
-    </header>
-    
-    <main>
-      <div class="card">
-        <h2>You're In!</h2>
-        <p>You've successfully navigated through a complete authentication flow built with LegoDOM.</p>
-        <p>This page received your username from the login form using global state.</p>
-      </div>
-      
-      <div class="stats">
-        <div class="stat">
-          <span class="value">[[ visitCount ]]</span>
-          <span class="label">Page Views</span>
-        </div>
-        <div class="stat">
-          <span class="value">[[ formatTime() ]]</span>
-          <span class="label">Current Time</span>
-        </div>
-        <div class="stat">
-          <span class="value">✓</span>
-          <span class="label">Logged In</span>
-        </div>
-      </div>
-      
-      <div class="actions">
-        <a href="/" b-link class="btn">← Back to Home</a>
-      </div>
-    </main>
-  </div>
-</template>
-
-<style>
-  self {
-    display: block;
-    min-height: 100vh;
-    background: linear-gradient(180deg, #1a1a2e 0%, #16213e 100%);
-    color: white;
-    padding: 2rem;
-  }
-  
-  header {
-    display: flex;
-    justify-content: space-between;
-    align-items: center;
-    max-width: 800px;
-    margin: 0 auto 3rem;
-  }
-  
-  header h1 {
-    font-size: 1.75rem;
-  }
-  
-  header button {
-    background: rgba(255,255,255,0.1);
-    color: white;
-    border: 1px solid rgba(255,255,255,0.2);
-    padding: 0.5rem 1rem;
-    border-radius: 6px;
-    cursor: pointer;
-    transition: background 0.2s;
-  }
-  
-  header button:hover {
-    background: rgba(255,255,255,0.2);
-  }
-  
-  main {
-    max-width: 800px;
-    margin: 0 auto;
-  }
-  
-  .card {
-    background: rgba(255,255,255,0.05);
-    padding: 2rem;
-    border-radius: 16px;
-    margin-bottom: 2rem;
-    border: 1px solid rgba(255,255,255,0.1);
-  }
-  
-  .card h2 {
-    color: #4ecca3;
-    margin-bottom: 1rem;
-  }
-  
-  .card p {
-    opacity: 0.8;
-    line-height: 1.6;
-    margin-bottom: 0.5rem;
-  }
-  
-  .stats {
-    display: grid;
-    grid-template-columns: repeat(3, 1fr);
-    gap: 1rem;
-    margin-bottom: 2rem;
-  }
-  
-  .stat {
-    background: rgba(255,255,255,0.05);
-    padding: 1.5rem;
-    border-radius: 12px;
-    text-align: center;
-    border: 1px solid rgba(255,255,255,0.1);
-  }
-  
-  .stat .value {
-    display: block;
-    font-size: 2rem;
-    font-weight: bold;
-    color: #4ecca3;
-    margin-bottom: 0.5rem;
-  }
-  
-  .stat .label {
-    font-size: 0.85rem;
-    opacity: 0.7;
-  }
-  
-  .actions {
-    text-align: center;
-  }
-  
-  .btn {
-    display: inline-block;
-    padding: 0.75rem 1.5rem;
-    background: #4ecca3;
-    color: #1a1a2e;
-    text-decoration: none;
-    border-radius: 8px;
-    font-weight: 600;
-  }
-</style>
-
-<script>
-export default {
-  visitCount: 0,
-  
-  get username() {
-    // Get username from global state (set by login page)
-    return Lego.globals.user?.name || 'Guest';
-  },
-  
-  mounted() {
-    this.visitCount++;
-    
-    // Redirect to login if not authenticated
-    if (!Lego.globals.user) {
-      console.log('Not logged in, redirecting...');
-      this.$go('/login').get();
-    }
-  },
-  
-  formatTime() {
-    return new Date().toLocaleTimeString();
-  },
-  
-  handleLogout() {
-    // Clear global user state
-    Lego.globals.user = null;
-    this.$go('/').get();
-  }
-}
-</script>
-```
-
-## Step 2: Update Login to Set Global State
-
-The login page needs to store the user in global state. Update `src/components/login-page.lego`'s script section:
-
-```javascript
-<script>
-export default {
-  email: '',
-  password: '',
-  
-  handleSubmit(event) {
-    event.preventDefault();
-    
-    // Store user in GLOBAL state (accessible from any component!)
-    Lego.globals.user = {
-      name: this.email.split('@')[0],  // Use email prefix as name
-      email: this.email,
-      loggedInAt: new Date()
-    };
-    
-    console.log('User logged in:', Lego.globals.user);
-    
-    // Navigate to welcome page
-    this.$go('/welcome').get();
-  }
-}
-</script>
-```
-
-## Step 3: Update Home Page Navigation
-
-Update `src/components/home-page.lego`'s `handleClick` method:
-
-```javascript
-handleClick() {
-  this.$go('/login').get();
-}
-```
-
-## Step 4: Complete `app.js`
-
-Here's the final `src/app.js`:
-
-```javascript
-import { Lego } from 'lego-dom';
-import registerComponents from 'virtual:lego-components';
-
-// Register all .lego components
-registerComponents();
-
-// Define routes
-Lego.route('/', 'home-page');
-Lego.route('/login', 'login-page');
-Lego.route('/welcome', 'welcome-page');
-
-// Initialize with default user state
-Lego.globals.user = null;
-
-// Start the engine
-await Lego.init();
-```
-
-## Test the Complete Flow
-
-```bash
-npm run dev
-```
-
-1. **Home Page** (`/`) – Click "Get Started"
-2. **Login Page** (`/login`) – Enter an email, click "Sign In"
-3. **Welcome Page** (`/welcome`) – See your username displayed!
-4. Click "Logout" – Clears state, returns to home
-5. Try navigating directly to `/welcome` – Redirects to login!
-
-## The Data Flow
-
-```
-┌─────────────────────────────────────────────────────────────┐
-│                        Lego.globals                          │
-│  ┌─────────────────────────────────────────────────────┐    │
-│  │  user: { name: 'john', email: 'john@test.com' }    │    │
-│  └─────────────────────────────────────────────────────┘    │
-└─────────────────────────────────────────────────────────────┘
-         ▲                                    │
-         │ writes                             │ reads
-         │                                    ▼
-   ┌──────────┐                        ┌──────────────┐
-   │  login   │                        │   welcome    │
-   │  page    │                        │    page      │
-   └──────────┘                        └──────────────┘
-```
-
-## Auth Guard Pattern
-
-Want to protect routes? Add middleware:
-
-```javascript
-// In app.js
-
-const requireAuth = (params, globals) => {
-  if (!globals.user) {
-    globals.$go('/login').get();
-    return false;  // Block navigation
-  }
-  return true;  // Allow navigation
-};
-
-Lego.route('/welcome', 'welcome-page', requireAuth);
-Lego.route('/dashboard', 'dashboard-page', requireAuth);
-Lego.route('/settings', 'settings-page', requireAuth);
-```
-
-## What You've Built
-
-✅ A complete login flow: home → login → welcome  
-✅ Global state shared across components  
-✅ Logout functionality that clears state  
-✅ Automatic redirect when not authenticated  
-✅ Route protection with middleware  
-
-## The Full Picture
-
-| File | Purpose |
-|------|---------|
-| `index.html` | Entry HTML with `<lego-router>` |
-| `src/app.js` | Routes, globals, initialization |
-| `src/components/*.lego` | Your page components |
-| `vite.config.js` | Vite + LegoDOM plugin setup |
-
----
-
-<div style="display: flex; justify-content: space-between; margin-top: 3rem;">
-  <a href="./03-adding-routes" style="display: inline-block; background: #eee; color: #333; padding: 0.75rem 1.5rem; border-radius: 6px; text-decoration: none; font-weight: 600;">
-    ← Previous: Adding Routes
-  </a>
-  <a href="./05-state-and-globals" style="display: inline-block; background: #4CAF50; color: white; padding: 0.75rem 1.5rem; border-radius: 6px; text-decoration: none; font-weight: 600;">
-    Next: State & Globals →
-  </a>
-</div>

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

@@ -1,285 +0,0 @@
-# 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

@@ -1,40 +0,0 @@
-# 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.
-:::