lego-dom 1.0.0 → 1.3.4

package/docs/guide/directives.md

@@ -2,6 +2,32 @@
 
 Directives are special attributes that add reactive behavior to elements.
 
+## b-if
+
+Conditional rendering (adds/removes from DOM).
+
+### Basic Usage
+
+```html
+<p b-if="isLoggedIn">Welcome back!</p>
+<p b-if="!isLoggedIn">Please log in</p>
+```
+
+### With Expressions
+
+```html
+<div b-if="count > 0">Count is [[ count ]]</div>
+<div b-if="items.length === 0">No items</div>
+```
+
+::: tip b-if vs b-show
+`b-if` adds or removes the element from the DOM.
+`b-show` toggles `display: none`.
+
+Use `b-if` if the condition rarely changes.
+Use `b-show` if you toggle often.
+:::
+
 ## b-show
 
 Conditional rendering using `display: none`.
@@ -16,7 +42,7 @@ Conditional rendering using `display: none`.
 ### With Expressions
 
 ```html
-<div b-show="count > 0">Count is {{ count }}</div>
+<div b-show="count > 0">Count is [[ count ]]</div>
 <div b-show="items.length === 0">No items</div>
 <div b-show="user && user.role === 'admin'">Admin panel</div>
 ```
@@ -32,6 +58,73 @@ Conditional rendering using `display: none`.
 `b-show` sets `display: none` when the condition is false. The element stays in the DOM but is hidden.
 :::
 
+## b-html
+
+Renders raw HTML content.
+
+> [!WARNING]
+> Only use on trusted content. This exposes you to XSS vulnerabilities if used with user input.
+
+```html
+<div b-html="rawContent"></div>
+```
+
+```js
+{
+  rawContent: '<b>Bold</b> and <i>Italic</i>'
+}
+```
+
+## b-text
+
+Sets the text content of an element.
+
+> [!WARNING] Limitation
+> **`b-text` is extremely weak.** Unlike `[[ ]]`, it **does not** support JavaScript expressions (math, logic, functions). It ONLY supports simple property paths.
+
+### Functionality
+
+| Syntax | Supported? | Example |
+| :--- | :--- | :--- |
+| **Property Path** | Yes | `b-text="user.name"` |
+| **Math** | No | `b-text="count + 1"` |
+| **Logic** | No | `b-text="isActive ? 'Yes' : 'No'"` |
+| **Methods** | No | `b-text="formatDate(date)"` |
+
+Use `[[ ]]` for anything complex. `b-text` is strictly for direct property binding.
+
+```html
+<!-- Works -->
+<span b-text="user.name"></span>
+
+<!-- Does NOT Work (Use [[ ]] instead) -->
+<span b-text="user.firstName + ' ' + user.lastName"></span>
+<span b-text="count + 1"></span>
+```
+
+## b-var
+
+Creates a reference to a DOM element accessible via `this.$vars`.
+
+Use `b-var` when you need direct DOM access (e.g., `.focus()`, `.click()`, `.play()`).
+
+### Usage
+
+```html
+<input type="file" b-var="fileInput" style="display:none">
+<button @click="$vars.fileInput.click()">Upload</button>
+```
+
+Or in script:
+
+```javascript
+export default {
+  openPicker() {
+    this.$vars.fileInput.click();
+  }
+}
+```
+
 ## b-for
 
 List rendering.
@@ -40,7 +133,7 @@ List rendering.
 
 ```html
 <ul>
-  <li b-for="item in items">{{ item }}</li>
+  <li b-for="item in items">[[ item ]]</li>
 </ul>
 ```
 
@@ -49,7 +142,7 @@ List rendering.
 ```html
 <ul>
   <li b-for="todo in todos">
-    {{ todo.text }} - {{ todo.done ? 'Done' : 'Pending' }}
+    [[ todo.text ]] - [[ todo.done ? 'Done' : 'Pending' ]]
   </li>
 </ul>
 ```
@@ -61,7 +154,7 @@ Use `$index` (implicit variable):
 ```html
 <ul>
   <li b-for="item in items">
-    #{{ $index + 1 }}: {{ item.name }}
+    #[[ $index + 1 ]]: [[ item.name ]]
   </li>
 </ul>
 ```
@@ -70,10 +163,10 @@ Use `$index` (implicit variable):
 
 ```html
 <div b-for="category in categories">
-  <h3>{{ category.name }}</h3>
+  <h3>[[ category.name ]]</h3>
   <ul>
     <li b-for="product in category.products">
-      {{ product.name }}
+      [[ product.name ]]
     </li>
   </ul>
 </div>
@@ -83,8 +176,8 @@ Use `$index` (implicit variable):
 
 ```html
 <li b-for="user in users">
-  <span b-show="user.active">✅ {{ user.name }}</span>
-  <span b-show="!user.active">❌ {{ user.name }}</span>
+  <span b-show="user.active">✅ [[ user.name ]]</span>
+  <span b-show="!user.active">❌ [[ user.name ]]</span>
 </li>
 ```
 
@@ -96,7 +189,7 @@ Two-way data binding for form inputs.
 
 ```html
 <input b-sync="username" placeholder="Enter username">
-<p>Hello, {{ username }}!</p>
+<p>Hello, [[ username ]]!</p>
 ```
 
 ### Checkbox
@@ -112,7 +205,7 @@ Two-way data binding for form inputs.
 <input type="radio" name="size" value="small" b-sync="selectedSize">
 <input type="radio" name="size" value="medium" b-sync="selectedSize">
 <input type="radio" name="size" value="large" b-sync="selectedSize">
-<p>Selected: {{ selectedSize }}</p>
+<p>Selected: [[ selectedSize ]]</p>
 ```
 
 ### Select Dropdown
@@ -123,14 +216,14 @@ Two-way data binding for form inputs.
   <option value="uk">United Kingdom</option>
   <option value="ca">Canada</option>
 </select>
-<p>Country: {{ country }}</p>
+<p>Country: [[ country ]]</p>
 ```
 
 ### Textarea
 
 ```html
 <textarea b-sync="message" rows="4"></textarea>
-<p>{{ message.length }} characters</p>
+<p>[[ message.length ]] characters</p>
 ```
 
 ### In b-for Loops
@@ -138,7 +231,7 @@ Two-way data binding for form inputs.
 ```html
 <li b-for="todo in todos">
   <input type="checkbox" b-sync="todo.done">
-  <span class="{{ todo.done ? 'done' : '' }}">{{ todo.text }}</span>
+  <span class="[[ todo.done ? 'done' : '' ]]">[[ todo.text ]]</span>
 </li>
 ```
 
@@ -220,8 +313,8 @@ Client-side navigation (prevents page reload).
 ### With Dynamic Routes
 
 ```html
-<a href="/user/{{ userId }}" b-link>View Profile</a>
-<a href="/product/{{ productId }}" b-link>{{ productName }}</a>
+<a href="/user/[[ userId ]]" b-link>View Profile</a>
+<a href="/product/[[ productId ]]" b-link>[[ productName ]]</a>
 ```
 
 ::: tip Router Required
@@ -272,7 +365,7 @@ Lego.define('user-card', `...`, {
 
 ```html
 <li b-for="item in items" b-show="item.visible">
-  {{ item.name }}
+  [[ item.name ]]
 </li>
 ```
 
@@ -281,7 +374,7 @@ Lego.define('user-card', `...`, {
 ```html
 <li b-for="todo in todos">
   <input type="checkbox" b-sync="todo.done">
-  {{ todo.text }}
+  [[ todo.text ]]
 </li>
 ```
 
@@ -303,7 +396,7 @@ Lego.define('user-card', `...`, {
 <div b-show="showPanel">Panel content</div>
 
 <!-- ❌ Verbose -->
-<div style="display: {{ showPanel ? 'block' : 'none' }}">Panel content</div>
+<div style="display: [[ showPanel ? 'block' : 'none' ]]">Panel content</div>
 ```
 
 ### 2. Keep Event Handlers Simple
@@ -350,7 +443,7 @@ Move complex logic to methods.
 
 ```html
 <!-- For frequent toggling -->
-<div class="{{ visible ? '' : 'hidden' }}">Content</div>
+<div class="[[ visible ? '' : 'hidden' ]]">Content</div>
 ```
 
 ```css
@@ -377,7 +470,7 @@ Paginate large lists:
 ```
 
 ```html
-<li b-for="item in visibleItems()">{{ item.name }}</li>
+<li b-for="item in visibleItems()">[[ item.name ]]</li>
 ```
 
 ## Common Patterns
@@ -393,7 +486,7 @@ Paginate large lists:
 
 ```html
 <button @click="count--">-</button>
-<span>{{ count }}</span>
+<span>[[ count ]]</span>
 <button @click="count++">+</button>
 ```
 
@@ -404,7 +497,7 @@ Paginate large lists:
 <ul>
   <li b-for="todo in todos">
     <input type="checkbox" b-sync="todo.done">
-    <span class="{{ todo.done ? 'done' : '' }}">{{ todo.text }}</span>
+    <span class="[[ todo.done ? 'done' : '' ]]">[[ todo.text ]]</span>
   </li>
 </ul>
 ```
@@ -423,6 +516,22 @@ Paginate large lists:
 <div b-show="activeTab === 'settings'">Settings content</div>
 ```
 
+## See Also
+
+Some directives are specific to certain features and are documented in their respective guides:
+
+### Component Directives
+
+- **`b-id`**: Defines a component from a template.
+- **`b-styles`**: Applies shared styles to a component.
+- See [Components Guide](/guide/components)
+
+### Routing Directives
+
+- **`b-target`**: Specifies the target element for surgical routing updates.
+- **`b-link`**: Controls browser history behavior for links.
+- See [Routing Guide](/guide/routing)
+
 ## Next Steps
 
 - See [directive examples](/examples/)

package/docs/guide/directory-structure.md

@@ -0,0 +1,248 @@
+# Chaos Tends To A Minimum
+
+> [!NOTE] This is a Recommendation, Not a Bible
+> This page is one person's take on how to structure large LegoDOM applications. It is not enforced by the framework. You are encouraged to adapt, improve, or completely ignore it. If you find a better pattern, please share it.
+
+---
+
+In LegoDOM land everything is a `.lego`. A `block` is a lego, a `widget` is a lego, a `component` is a lego, a `page` is a lego.
+
+But what do they *mean*?
+
+
+## The Four Levels
+
+| Level | Role | Knows About | Example |
+| :--- | :--- | :--- | :--- |
+| **Block** | Identity | Its own visuals | `<block-avatar>`, `<block-button>` |
+| **Widget** | Intent | How an interaction works | `<widget-file-trigger>`, `<widget-dropdown>` |
+| **Component** | Computation | Business data & API calls | `<comp-profile-settings>`, `<comp-checkout-form>` |
+| **Page** | Coordination | Layout & Routing | `<page-dashboard>`, `<page-login>` |
+
+
+## The Litmus Test: The Avatar Upload
+
+**The Question:**
+> I have an avatar. When I click it, it opens a file picker. When the file changes, it POSTs to `/v1/avatars`. What is it? A Block? A Widget? A Component?
+
+**The Technical Answer:** `main.js` allows all of this in one file. It will work.
+
+**The Architectural Answer:** You have conflated three distinct responsibilities into one:
+1.  **Identity** Looking like an avatar.
+2.  **Intent** Picking a file.
+3.  **Computation** Saving to *your specific server*.
+
+**The Consequence:**
+If you later want to display that avatar in a read-only user list, you *cannot reuse this component* because clicking it triggers unwanted upload logic. You will be forced to create a new, duplicate `<block-avatar>` just for display.
+
+### The "Lego Way" Solution
+
+Split this into its three atomic truths to maximize reusability.
+
+#### 1. The Block (Identity)
+
+```html
+<!-- block-avatar.lego -->
+<template>
+  <img class="avatar" src="[[ src ]]" alt="[[ alt ]]">
+</template>
+
+<style>
+  .avatar { width: 48px; height: 48px; border-radius: 50%; object-fit: cover; }
+</style>
+
+<script>
+export default {
+  src: '/default-avatar.png',
+  alt: 'User'
+}
+</script>
+```
+-   **Role:** Just the visuals. Circular crop, fallback, size classes.
+-   **Logic:** None. Zero business knowledge.
+-   **Reusability:** Used *everywhere* e.g. Navbar, User List, Profile Page, Comments.
+
+#### 2. The Widget (Intent)
+
+```html
+<!-- widget-file-trigger.lego -->
+<template>
+  <div @click="openPicker()">
+    <slot></slot>
+    <input type="file" style="display:none" b-var="avatarFileElement" @change="onFileChange">
+  </div>
+</template>
+
+<script>
+export default {
+  openPicker() {
+    this.$vars.avatarFileElement.click();
+  },
+  onFileChange(event) {
+    // It doesn't know about /v1/avatars. It just hands you the file.
+    this.$emit('file-selected', { file: event.target.files[0] });
+  }
+}
+</script>
+```
+-   **Role:** The mechanic. Wraps any slotted content and makes it clickable to open a file dialog.
+-   **Logic:** Handles the hidden `<input type="file">`, listens for `change`, and **emits an event**.
+-   **Boundary:** It uses `$emit` (from `main.js`) to broadcast what happened. It never makes API calls.
+
+#### 3. The Component (Computation a.k.a. Context)
+
+```html
+<!-- comp-profile-settings.lego -->
+<template>
+  <h2>Your Profile</h2>
+  <widget-file-trigger @file-selected="uploadAvatar">
+    <block-avatar src="[[ user.avatarUrl ]]"></block-avatar>
+  </widget-file-trigger>
+  <p>Click avatar to change</p>
+</template>
+
+<script>
+export default {
+  user: { avatarUrl: '/me.jpg' },
+
+  async uploadAvatar(event) {
+    const file = event.detail.file;
+    // BUSINESS LOGIC LIVES HERE
+    const formData = new FormData();
+    formData.append('avatar', file);
+    const res = await fetch('/v1/avatars', { method: 'POST', body: formData });
+    const data = await res.json();
+    this.user.avatarUrl = data.url; // Reactivity updates the block-avatar
+  }
+}
+</script>
+```
+-   **Role:** The boss. Assembles the parts and owns the API call.
+-   **Logic:** Knows about `user`, knows about `/v1/avatars`, handles the business outcome.
+-   **Boundary:** This is the *only* place that knows about your specific backend.
+
+
+## The Definitions
+
+### Blocks (Atoms)
+
+> **TL;DR** A Block is an irreducible thing. A UI with identity, but no narrative intent.
+
+A Block cannot be broken down into smaller Blocks. It is self-contained.
+
+-   **State:** Visual only. It can track "Is my mouse over me?" or "Am I spinning?". It never knows about User IDs, Auth tokens, or business data.
+-   **Naming:** `block-avatar`, `block-button`, `block-spinner`, `block-card`.
+-   **Rule:** If you find yourself nesting Blocks inside other Blocks, you have graduated to a Widget.
+
+> [!WARNING] Don't Confuse Styling with Blocks
+> You can use CSS to style many `<h1>` elements. That doesn't mean you need a `<block-title-header>`. Only create a Block when it has distinct *behavior* or *identity* beyond mere styling.
+
+
+### Widgets (Molecules)
+
+> **TL;DR** A Widget is an interaction, not a thing.
+
+A Widget gives Blocks a reason to exist together. It defines *how* an interaction works without embedding *who* it's for or *what* business outcome it serves.
+
+-   **State:** Internal UI state only. "Is the dropdown open?" "Which tab is active?"
+-   **Naming:** `widget-dropdown`, `widget-modal`, `widget-datepicker`, `widget-file-trigger`.
+-   **Rule:** Widgets are portable. You should be able to copy a Widget to a completely different project and it should still work.
+-   **Communication:** Uses `$emit()` to broadcast events. Never makes API calls itself.
+
+
+### Components (Organisms)
+
+> **TL;DR** Components are where your app features come to life.
+
+A Component is a Widget (or set of Widgets) bound to specific data, rules, and responsibility. It's where interaction becomes meaningful to *this* application.
+
+-   **State:** Domain-specific. Owns data fetched from APIs. Knows about the current user.
+-   **Naming:** `comp-profile-settings`, `comp-order-history`, `comp-payroll-table`.
+-   **Rule:** A Component knows *who* it is for, *what* data it owns, and *what* outcome it must produce.
+-   **Communication:** Listens to Widget events (like `@file-selected`) and performs business transactions.
+
+
+### Pages (Coordination)
+
+> **TL;DR** A Page is the top-level host that routing targets.
+
+Pages are the uppermost hosts. They orchestrate the layout of Components within the context of a LegoDOM application.
+
+-   **Role:** Define the grid. Orchestrate Components. Handle route parameters.
+-   **Naming:** `page-dashboard`, `page-login`, `page-user-profile`.
+-   **Rule:** Pages are the *only* UI units directly known to `<lego-router>`. While a Component owns the *logic* of a feature, a Page owns the *real estate*.
+
+
+## Recommended Directory Structure
+
+```text
+src/
+├── blocks/           # Design System primitives
+│   ├── block-avatar.lego
+│   ├── block-button.lego
+│   └── block-input.lego
+├── widgets/          # Generic, portable UI tools
+│   ├── widget-dropdown.lego
+│   ├── widget-modal.lego
+│   └── widget-file-trigger.lego
+├── components/       # Domain-specific features
+│   ├── comp-profile-settings.lego
+│   └── comp-order-history.lego
+├── pages/            # Route targets
+│   ├── page-dashboard.lego
+│   └── page-login.lego
+└── main.js           # App entry, routes, globals
+
+
+## Scaling to Multi-Domain Apps
+
+For large enterprise apps with multiple business domains (HRIS, Finance, Planning, Messages), the flat structure breaks down. Use a **Domain-First** approach.
+
+### Domain-First Structure
+
+```text
+src/
+├── shared/                    # Truly universal (used by 3+ domains)
+│   ├── blocks/
+│   │   ├── block-button.lego
+│   │   └── block-avatar.lego
+│   └── widgets/
+│       ├── widget-datepicker.lego
+│       └── widget-modal.lego
+│
+├── hris/                      # Human Resources domain
+│   ├── blocks/
+│   ├── widgets/
+│   │   └── widget-leave-calendar.lego
+│   ├── components/
+│   │   └── comp-employee-list.lego
+│   └── pages/
+│       └── page-employees.lego
+│
+├── finance/                   # Finance domain
+│   ├── widgets/
+│   ├── components/
+│   └── pages/
+│
+├── planning/                  # Planning domain
+│   ├── widgets/
+│   ├── components/
+│   └── pages/
+│
+└── main.js
+```
+
+### Rules for Multi-Domain
+
+1. **Shared** = Only what is used by 3+ domains. Be ruthless.
+2. **Domain folders** = Each domain owns its own `blocks/`, `widgets/`, `components/`, `pages/`.
+3. **No cross-domain Component imports.** If HRIS needs Finance data, go through a shared service or global state, not by importing `finance/components/...`.
+
+
+## Summary
+
+| If you keep it all in one file... | The "Enterprise" Standard |
+| :--- | :--- |
+| Name it `<comp-avatar-upload>` and accept it is not reusable. | Let the **Widget** handle the interaction. Let the **Component** handle the transaction. |
+
+**This is a recommendation.** If you find a pattern that works better for your team, use it. The goal is clarity, reusability, and reducing arguments - not rigid adherence to a doctrine.