lego-dom 0.0.5 → 0.0.8

package/docs/guide/templating.md

@@ -0,0 +1,383 @@
+# Templating
+
+Learn about LegoJS templating features and syntax.
+
+## Interpolation
+
+Use `{{ }}` to insert dynamic content:
+
+### Simple Values
+
+```html
+<p>{{ message }}</p>
+<h1>{{ title }}</h1>
+<span>{{ count }}</span>
+```
+
+### Expressions
+
+```html
+<p>{{ count * 2 }}</p>
+<span>{{ price.toFixed(2) }}</span>
+<div>{{ firstName + ' ' + lastName }}</div>
+```
+
+### Method Calls
+
+```html
+<p>{{ formatDate(timestamp) }}</p>
+<span>{{ calculateTotal() }}</span>
+<div>{{ getUsername() }}</div>
+```
+
+### Conditional (Ternary)
+
+```html
+<p>{{ age >= 18 ? 'Adult' : 'Minor' }}</p>
+<span>{{ isOnline ? '🟢 Online' : '🔴 Offline' }}</span>
+<div>{{ items.length > 0 ? items.length + ' items' : 'Empty' }}</div>
+```
+
+## Attribute Binding
+
+Interpolate in any attribute:
+
+### Simple Attributes
+
+```html
+<img src="/avatars/{{ userId }}.png" alt="{{ username }}">
+<a href="/user/{{ userId }}">{{ username }}</a>
+<input placeholder="{{ defaultText }}">
+```
+
+### Class Names
+
+```html
+<div class="card {{ isActive ? 'active' : '' }}">...</div>
+<button class="{{ isDisabled ? 'disabled' : 'enabled' }}">...</button>
+<li class="item status-{{ status }}">...</li>
+```
+
+### Data Attributes
+
+```html
+<div data-id="{{ itemId }}" data-type="{{ itemType }}">...</div>
+```
+
+### Style (Inline)
+
+```html
+<div style="color: {{ textColor }}; background: {{ bgColor }}">...</div>
+```
+
+## Escaping
+
+LegoJS automatically escapes HTML to prevent XSS:
+
+```js
+{
+  userInput: '<script>alert("XSS")</script>'
+}
+```
+
+```html
+<p>{{ userInput }}</p>
+<!-- Renders as: &lt;script&gt;alert("XSS")&lt;/script&gt; -->
+```
+
+**There is no way to render raw HTML.** This is by design—for security.
+
+## Whitespace
+
+Templates preserve whitespace:
+
+```html
+<p>
+  {{ message }}
+</p>
+<!-- Renders with newlines and indentation -->
+```
+
+Trim manually if needed:
+
+```html
+<p>{{ message.trim() }}</p>
+```
+
+## Context
+
+Inside `{{ }}`, you have access to:
+
+### Component State (`this`)
+
+```html
+<p>{{ count }}</p>  <!-- this.count -->
+<span>{{ user.name }}</span>  <!-- this.user.name -->
+```
+
+### Methods
+
+```html
+<p>{{ formatDate(timestamp) }}</p>
+<div>{{ calculateTotal() }}</div>
+```
+
+### Special Keywords
+
+- `global` - Access `Lego.globals`
+- `event` - In event handlers
+- `self` - Reference to component element (rare)
+
+```html
+<p>{{ global.user.name }}</p>
+<button @click="console.log(event)">Click</button>
+```
+
+## Complex Examples
+
+### Formatting Currency
+
+```js
+{
+  price: 29.99,
+  formatCurrency(value) {
+    return '$' + value.toFixed(2);
+  }
+}
+```
+
+```html
+<p>Price: {{ formatCurrency(price) }}</p>
+```
+
+### Date Formatting
+
+```js
+{
+  timestamp: Date.now(),
+  formatDate(ts) {
+    return new Date(ts).toLocaleDateString();
+  }
+}
+```
+
+```html
+<time>{{ formatDate(timestamp) }}</time>
+```
+
+### Pluralization
+
+```js
+{
+  items: ['apple', 'banana'],
+  plural(count, singular, plural) {
+    return count === 1 ? singular : plural;
+  }
+}
+```
+
+```html
+<p>{{ items.length }} {{ plural(items.length, 'item', 'items') }}</p>
+```
+
+### Truncation
+
+```js
+{
+  description: 'Very long text...',
+  truncate(text, length) {
+    return text.length > length 
+      ? text.slice(0, length) + '...' 
+      : text;
+  }
+}
+```
+
+```html
+<p>{{ truncate(description, 100) }}</p>
+```
+
+## Limitations
+
+### No Statements
+
+Can't use statements—only expressions:
+
+```html
+<!-- ❌ Doesn't work -->
+<p>{{ if (condition) { return 'yes'; } }}</p>
+<p>{{ for (let i = 0; i < 10; i++) { } }}</p>
+
+<!-- ✅ Use ternary or methods -->
+<p>{{ condition ? 'yes' : 'no' }}</p>
+<p>{{ renderList() }}</p>
+```
+
+### No Declarations
+
+Can't declare variables:
+
+```html
+<!-- ❌ Doesn't work -->
+<p>{{ const total = price * qty; total }}</p>
+
+<!-- ✅ Use methods -->
+<p>{{ getTotal() }}</p>
+```
+
+```js
+{
+  getTotal() {
+    const total = this.price * this.qty;
+    return total;
+  }
+}
+```
+
+## Best Practices
+
+### 1. Keep Templates Simple
+
+If logic is complex, use methods:
+
+```html
+<!-- ❌ Too complex -->
+<p>{{ items.filter(x => x.active).map(x => x.name).join(', ') }}</p>
+
+<!-- ✅ Better -->
+<p>{{ getActiveNames() }}</p>
+```
+
+```js
+{
+  getActiveNames() {
+    return this.items
+      .filter(x => x.active)
+      .map(x => x.name)
+      .join(', ');
+  }
+}
+```
+
+### 2. Format in Methods
+
+Don't put formatting logic in templates:
+
+```html
+<!-- ❌ Messy -->
+<p>${{ (price * 1.2).toFixed(2) }}</p>
+
+<!-- ✅ Clean -->
+<p>{{ formatPrice(price) }}</p>
+```
+
+### 3. Avoid Side Effects
+
+Don't mutate state in templates:
+
+```html
+<!-- ❌ Bad -->
+<p>{{ count++ }}</p>
+
+<!-- ✅ Good -->
+<p>{{ count }}</p>
+<button @click="count++">Increment</button>
+```
+
+### 4. Use Descriptive Method Names
+
+```js
+{
+  // ✅ Clear purpose
+  formatCurrency(value) { ... },
+  calculateTax(amount) { ... },
+  isValidEmail(email) { ... }
+}
+```
+
+## Performance Tips
+
+### Cache Computed Values
+
+If a calculation is expensive, cache it:
+
+```js
+{
+  items: [],
+  _cachedTotal: null,
+  
+  total() {
+    if (this._cachedTotal === null) {
+      this._cachedTotal = this.items.reduce((sum, x) => sum + x.price, 0);
+    }
+    return this._cachedTotal;
+  },
+  
+  updated() {
+    this._cachedTotal = null;  // Invalidate cache
+  }
+}
+```
+
+### Avoid Heavy Calculations
+
+```html
+<!-- ❌ Runs on every render -->
+<p>{{ expensiveCalculation() }}</p>
+
+<!-- ✅ Calculate once, store result -->
+<p>{{ cachedResult }}</p>
+```
+
+```js
+{
+  cachedResult: null,
+  mounted() {
+    this.cachedResult = this.expensiveCalculation();
+  }
+}
+```
+
+## Common Patterns
+
+### Show/Hide Based on Condition
+
+```html
+<p b-if="user">Welcome, {{ user.name }}!</p>
+<p b-if="!user">Please log in</p>
+```
+
+### List with Index
+
+```html
+<ul>
+  <li b-for="item in items">
+    #{{ $index + 1 }}: {{ item.name }}
+  </li>
+</ul>
+```
+
+### Conditional Classes
+
+```html
+<div class="item {{ item.active ? 'active' : '' }} {{ item.featured ? 'featured' : '' }}">
+  {{ item.name }}
+</div>
+```
+
+### Dynamic Attributes
+
+```html
+<a 
+  href="/product/{{ product.id }}" 
+  class="product-link {{ product.inStock ? '' : 'out-of-stock' }}"
+  title="{{ product.name }} - ${{ product.price }}">
+  {{ product.name }}
+</a>
+```
+
+## Next Steps
+
+- Learn about [Directives](/guide/directives)
+- See [templating examples](/examples/)
+- Explore [component patterns](/guide/components)

package/docs/index.md

@@ -0,0 +1,126 @@
+---
+layout: home
+
+hero:
+  name: LegoJS
+  text: Build Reactive Web Components
+  tagline: A tiny, zero-dependency JavaScript library for creating reactive Web Components directly in the browser
+  image:
+    src: /logo.svg
+    alt: LegoJS
+  actions:
+    - theme: brand
+      text: Get Started
+      link: /guide/getting-started
+    - theme: alt
+      text: View on GitHub
+      link: https://github.com/rayattack/LegoJS
+    - theme: alt
+      text: Try Examples
+      link: /examples/
+
+features:
+  - icon: 🎯
+    title: Mental Model Simplicity
+    details: No virtual DOM, no compilation step, no JSX. Just HTML with a few directives and reactive objects.
+  
+  - icon: ⚡
+    title: Zero Dependencies
+    details: Under 500 lines of code with no external dependencies. The entire library is smaller than most framework router plugins.
+  
+  - icon: 🔄
+    title: True Reactivity
+    details: Direct object mutation triggers updates. No setters, no actions, no reducers. Just change the data and the DOM updates.
+  
+  - icon: 🧩
+    title: Web Components Native
+    details: Built on standard Web Components with Shadow DOM. Works anywhere, plays well with existing code.
+  
+  - icon: 📦
+    title: Single File Components
+    details: Use .lego files with Vite for a modern development experience, or load directly in the browser.
+  
+  - icon: 🎨
+    title: Scoped Styles
+    details: Shadow DOM encapsulation means your styles never leak. Use the 'self' keyword to target component root.
+  
+  - icon: 🛣️
+    title: Built-in Router
+    details: Client-side routing included. Define routes, handle parameters, and add middleware without extra packages.
+  
+  - icon: 💪
+    title: TypeScript Ready
+    details: Full JSDoc annotations for excellent IDE support and optional TypeScript integration.
+  
+  - icon: 🚀
+    title: Production Ready
+    details: Battle-tested patterns from Vue and React, adapted for pure Web Components. No framework lock-in.
+---
+
+## Quick Example
+
+```html
+<!-- Define a component -->
+<template b-id="counter-button">
+  <style>
+    self {
+      display: block;
+      padding: 1rem;
+    }
+    button {
+      font-size: 1.2rem;
+      padding: 0.5rem 1rem;
+    }
+  </style>
+  
+  <h2>{{ title }}</h2>
+  <button @click="count++">
+    Clicked {{ count }} times
+  </button>
+</template>
+
+<!-- Use it -->
+<counter-button b-data="{ title: 'My Counter', count: 0 }"></counter-button>
+
+<script src="https://unpkg.com/lego-dom/main.js"></script>
+```
+
+That's it. No build step, no npm, no configuration.
+
+## Why LegoJS?
+
+**For small projects**, you get reactive components without the overhead of a full framework.
+
+**For large projects**, you get a clear mental model and Web Standards compliance.
+
+**For learning**, you can read the entire source code in an afternoon and understand exactly how it works.
+
+## Comparison
+
+| Feature | LegoJS | Vue | React |
+|---------|--------|-----|-------|
+| Size | < 17KB | ~33KB | ~40KB |
+| Dependencies | 0 | Many | Many |
+| Build Required | No* | Yes | Yes |
+| Virtual DOM | No | Yes | Yes |
+| Learning Curve | Minimal | Moderate | Moderate |
+| Web Components | Native | Optional | No |
+
+\* *Optional with Vite for .lego files*
+
+## Browser Support
+
+LegoJS works in all modern browsers that support:
+- Web Components
+- Shadow DOM
+- ES6 Proxy
+- Template literals
+
+This includes Chrome 63+, Firefox 63+, Safari 11.1+, and Edge 79+.
+
+## Community
+
+- 📖 [Documentation](https://rayattack.github.io/LegoJS/)
+- 💬 [Discussions](https://github.com/rayattack/LegoJS/discussions)
+- 🐛 [Issue Tracker](https://github.com/rayattack/LegoJS/issues)
+- 📦 [npm Package](https://www.npmjs.com/package/lego-dom)

package/docs/public/logo.svg

@@ -0,0 +1,38 @@
+<svg width="200" height="200" viewBox="0 0 200 200" fill="none" xmlns="http://www.w3.org/2000/svg">
+  <defs>
+    <linearGradient id="blockGrad" x1="0%" y1="0%" x2="100%" y2="100%">
+      <stop offset="0%" style="stop-color:#FF4B2B" />
+      <stop offset="100%" style="stop-color:#FF416C" />
+    </linearGradient>
+    <filter id="shadow" x="-20%" y="-20%" width="140%" height="140%">
+      <feGaussianBlur in="SourceAlpha" stdDeviation="3" />
+      <feOffset dx="2" dy="4" result="offsetblur" />
+      <feComponentTransfer>
+        <feFuncA type="linear" slope="0.2" />
+      </feComponentTransfer>
+      <feMerge>
+        <feMergeNode />
+        <feMergeNode in="SourceGraphic" />
+      </feMerge>
+    </filter>
+  </defs>
+
+  <g filter="url(#shadow)" transform="translate(40, 40)">
+    <path d="M60 80 L90 65 L90 95 L60 110 Z" fill="#D32F2F" />
+    <path d="M90 65 L120 80 L120 110 L90 95 Z" fill="#B71C1C" />
+    <path d="M60 80 L90 65 L120 80 L90 95 Z" fill="url(#blockGrad)" />
+    <circle cx="90" cy="80" r="4" fill="white" fill-opacity="0.3" />
+
+    <path d="M30 65 L60 50 L60 80 L30 95 Z" fill="#D32F2F" />
+    <path d="M60 50 L90 65 L90 95 L60 80 Z" fill="#B71C1C" />
+    <path d="M30 65 L60 50 L90 65 L60 80 Z" fill="url(#blockGrad)" />
+    <circle cx="60" cy="65" r="4" fill="white" fill-opacity="0.3" />
+
+    <path d="M30 35 L60 20 L60 50 L30 65 Z" fill="#D32F2F" />
+    <path d="M60 20 L90 35 L90 65 L60 50 Z" fill="#B71C1C" />
+    <path d="M30 35 L60 20 L90 35 L60 50 Z" fill="url(#blockGrad)" />
+    <circle cx="60" cy="35" r="4" fill="white" fill-opacity="0.3" />
+  </g>
+  
+  <text x="100" y="180" font-family="Arial, sans-serif" font-weight="900" font-size="24" fill="#333" text-anchor="middle" letter-spacing="1">LEGO.JS</text>
+</svg>

package/examples/vite-app/README.md

@@ -0,0 +1,71 @@
+# LegoJS SFC and Vite Plugin Example
+
+This example demonstrates how to use LegoJS with Single File Components (.lego files) and the Vite plugin.
+
+## Setup
+
+1. Install dependencies:
+```bash
+npm install
+```
+
+2. Run the dev server:
+```bash
+npm run dev
+```
+
+3. Open your browser to the URL shown (usually `http://localhost:5173`)
+
+## Structure
+
+```
+examples/vite-app/
+├── src/
+│   ├── components/          # .lego files auto-discovered here
+│   │   ├── sample-component.lego
+│   │   └── greeting-card.lego
+│   └── main.js              # Entry point
+├── index.html               # HTML shell
+├── vite.config.js           # Vite configuration with lego plugin
+└── package.json
+```
+
+## How It Works
+
+1. The Vite plugin scans `src/components/` for `.lego` files
+2. Each `.lego` file is parsed and transformed into a `Lego.define()` call
+3. The virtual module `virtual:lego-components` imports all discovered components
+4. Components are automatically registered and available in your HTML
+
+## Creating Components
+
+Create a new `.lego` file in `src/components/`:
+
+```html
+<template>
+  <h1>{{ message }}</h1>
+  <button @click="count++">{{ count }}</button>
+</template>
+
+<script>
+export default {
+  message: 'Hello!',
+  count: 0
+}
+</script>
+
+<style>
+  self {
+    display: block;
+    padding: 1rem;
+  }
+</style>
+```
+
+Then use it in your HTML:
+
+```html
+<your-component-name></your-component-name>
+```
+
+The component name is automatically derived from the filename (kebab-case required).

package/examples/vite-app/index.html

@@ -0,0 +1,45 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>LegoJS Vite Example</title>
+  <style>
+    body {
+      font-family: system-ui, -apple-system, sans-serif;
+      max-width: 800px;
+      margin: 2rem auto;
+      padding: 0 1rem;
+      background: #f9fafb;
+    }
+
+    h1 {
+      color: #1f2937;
+      border-bottom: 3px solid #4f46e5;
+      padding-bottom: 0.5rem;
+    }
+
+    .info {
+      background: white;
+      padding: 1rem;
+      border-radius: 0.5rem;
+      margin: 1rem 0;
+      border-left: 4px solid #10b981;
+    }
+  </style>
+</head>
+<body>
+  <h1>LegoJS + Vite Example</h1>
+  
+  <div class="info">
+    <p><strong>✨ These components are auto-discovered from .lego files!</strong></p>
+    <p>The Vite plugin automatically finds all .lego files in <code>src/components/</code> and registers them.</p>
+  </div>
+
+  <!-- These components are automatically discovered and hydrated -->
+  <sample-component></sample-component>
+  <greeting-card></greeting-card>
+
+  <script type="module" src="/src/main.js"></script>
+</body>
+</html>

package/examples/vite-app/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "lego-vite-example",
+  "version": "1.0.0",
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build",
+    "preview": "vite preview"
+  },
+  "dependencies": {
+    "lego-dom": "file:../.."
+  },
+  "devDependencies": {
+    "vite": "^5.0.0"
+  }
+}