ladrillosjs 2.0.0-beta.3.6 → 2.0.0-beta.4

package/README.md

@@ -23,6 +23,7 @@ A lightweight, zero-dependency web component framework for building modular web
   - [List Rendering](#list-rendering)
   - [Slots](#slots)
   - [Component Props](#component-props)
+  - [Lifecycle Hooks](#lifecycle-hooks)
 - [Advanced Features](#advanced-features)
   - [Lazy Loading](#lazy-loading)
   - [Global Event Bus](#global-event-bus)
@@ -30,6 +31,7 @@ A lightweight, zero-dependency web component framework for building modular web
   - [Shadow DOM](#shadow-dom)
   - [Styling Components](#styling-components)
   - [Performance & Caching](#performance--caching)
+- [Creating Component Libraries](#creating-component-libraries)
 - [Common Patterns](#common-patterns)
   - [Keyboard Events](#keyboard-events)
   - [Form Validation](#form-validation)
@@ -783,6 +785,189 @@ Pass data to components using HTML attributes:
 <my-greeting name="Jane" age="30"></my-greeting>
 ```
 
+### Lifecycle Hooks
+
+LadrillosJS provides Vue.js-style lifecycle hooks so you can run code at specific times in a component's lifecycle. These hooks are tied directly to Web Component lifecycle methods for maximum control.
+
+#### Available Hooks
+
+| Hook         | Called                                           | Purpose                            |
+| ------------ | ------------------------------------------------ | ---------------------------------- |
+| `$onMount`   | After component is mounted and fully initialized | Setup, initialization, API calls   |
+| `$onUpdate`  | After component state changes and re-renders     | React to state changes             |
+| `$onUnmount` | Before component is removed from DOM             | Cleanup, unsubscribe, clear timers |
+
+#### `$onMount(callback)`
+
+Called once when the component is fully mounted and ready. Perfect for initialization, API calls, and setup logic.
+
+```html
+<div>
+  <h2>User Profile</h2>
+  <p $if="{loading}">Loading...</p>
+  <div $else>
+    <h3>{user.name}</h3>
+    <p>{user.email}</p>
+  </div>
+</div>
+
+<script>
+  let user = { name: "", email: "" };
+  let loading = true;
+
+  // Called after component mounts with state ready
+  $onMount(() => {
+    console.log("✅ Component mounted!");
+
+    // Perfect for API calls, initialization, etc
+    fetch("/api/user/123")
+      .then((res) => res.json())
+      .then((data) => {
+        user = data;
+        loading = false;
+      });
+  });
+</script>
+```
+
+**When to use `$onMount`:**
+
+- ✅ Fetch data from APIs
+- ✅ Initialize timers or subscriptions
+- ✅ Set up event listeners
+- ✅ Run component setup logic
+- ✅ Validate initial state
+
+#### `$onUpdate(callback)`
+
+Called after component state changes and the component re-renders. Perfect for reacting to state changes.
+
+```html
+<div>
+  <p>Count: {count}</p>
+  <button onclick="count++">Increment</button>
+</div>
+
+<script>
+  let count = 0;
+
+  $onUpdate(() => {
+    console.log("🔄 Component updated! New count:", count);
+
+    // React to state changes
+    if (count === 10) {
+      console.log("Count reached 10!");
+    }
+  });
+</script>
+```
+
+**When to use `$onUpdate`:**
+
+- ✅ Log state changes for debugging
+- ✅ Trigger side effects when specific properties change
+- ✅ Sync with external systems
+- ✅ Perform validations on updated state
+
+#### `$onUnmount(callback)`
+
+Called before the component is removed from the DOM. Perfect for cleanup operations.
+
+```html
+<div>
+  <p>Timer: {seconds}</p>
+</div>
+
+<script>
+  let seconds = 0;
+  let interval = null;
+
+  $onMount(() => {
+    // Start timer
+    interval = setInterval(() => {
+      seconds++;
+    }, 1000);
+  });
+
+  $onUnmount(() => {
+    console.log("❌ Component unmounting, cleaning up...");
+
+    // Clear timer to prevent memory leaks
+    if (interval) {
+      clearInterval(interval);
+    }
+  });
+</script>
+```
+
+**When to use `$onUnmount`:**
+
+- ✅ Clear timers and intervals
+- ✅ Remove event listeners
+- ✅ Unsubscribe from observables
+- ✅ Cleanup resources
+- ✅ Cancel pending API requests
+
+#### Complete Lifecycle Example
+
+```html
+<div>
+  <h3>Lifecycle Demo</h3>
+  <p>Status: {status}</p>
+  <button onclick="status = 'active'">Activate</button>
+  <button onclick="status = 'inactive'">Deactivate</button>
+</div>
+
+<script>
+  let status = "initializing";
+
+  $onMount(() => {
+    console.log("✅ $onMount - Component ready to go!");
+    status = "ready";
+  });
+
+  $onUpdate(() => {
+    console.log("🔄 $onUpdate - Status changed to:", status);
+  });
+
+  $onUnmount(() => {
+    console.log("❌ $onUnmount - Cleaning up before removal");
+  });
+</script>
+```
+
+#### Lifecycle Timing Diagram
+
+```
+┌─────────────────────────────────────────────────────────┐
+│  Element added to DOM                                   │
+│  ↓                                                      │
+│  connectedCallback() starts                             │
+│  ├─ Parse template                                      │
+│  ├─ Load styles                                         │
+│  ├─ Execute scripts & initialize state                  │
+│  ├─ Render bindings, conditionals, loops                │
+│  │                                                      │
+│  ├─→ $onMount() called ← Component ready!               │
+│  │                                                      │
+│  State changes (click, setState, etc)                   │
+│  ├─ Proxy detects change                                │
+│  ├─ Schedule update (requestAnimationFrame)             │
+│  ├─ Re-render bindings, conditionals, loops             │
+│  │                                                      │
+│  ├─→ $onUpdate() called ← After each update             │
+│  │   ... (can happen many times)                        │
+│  │                                                      │
+│  Element removed from DOM                               │
+│  ├─→ $onUnmount() called ← Before cleanup               │
+│  │                                                      │
+│  disconnectedCallback() cleanup                         │
+│  ├─ Remove event listeners                              │
+│  ├─ Clear subscriptions                                 │
+│  └─ Complete                                            │
+└─────────────────────────────────────────────────────────┘
+```
+
 ## Advanced Features
 
 ### Lazy Loading
@@ -1410,6 +1595,117 @@ LadrillosJS includes built-in performance optimizations:
 - Event listeners are automatically cleaned up
 - Conditional rendering skips hidden elements
 
+## Creating Component Libraries
+
+LadrillosJS makes it easy to create and publish reusable component libraries. Developers can use your components in their projects with full TypeScript support.
+
+### Quick Example
+
+**Create a library:**
+
+```typescript
+// src/types/index.ts - Define interfaces
+export interface ButtonProps {
+  variant?: 'primary' | 'secondary';
+  size?: 'sm' | 'md' | 'lg';
+}
+
+export interface AwesomeButton extends HTMLElement {
+  variant?: ButtonProps['variant'];
+  size?: ButtonProps['size'];
+  setLoading(state: boolean): void;
+}
+
+// src/components/Button/button.html
+<button class="btn-{variant}" onclick="handleClick()">
+  <slot>{label}</slot>
+</button>
+
+<script>
+  let variant = this.getAttribute('variant') || 'primary';
+  let label = this.getAttribute('label') || 'Click';
+
+  export const handleClick = () => {
+    $emit('button:click', { timestamp: Date.now() });
+  };
+</script>
+
+// src/index.ts - Export registry
+export * from './types';
+export * from './components/Button';
+
+export const AWESOME_COMPONENTS = [
+  { name: 'awesome-button', path: './components/Button/button.html' }
+];
+
+export const registerAwesomeComponents = async () => {
+  const { registerComponents } = await import('ladrillosjs');
+  return registerComponents(AWESOME_COMPONENTS);
+};
+```
+
+**Consumers use it:**
+
+```typescript
+import {
+  registerAwesomeComponents,
+  createButton,
+  type AwesomeButton,
+} from "@awesome/ui";
+
+// Register all components
+await registerAwesomeComponents();
+
+// Use in HTML
+<awesome-button variant="primary" label="Click Me"></awesome-button>;
+
+// Or programmatically with types
+const btn = createButton() as AwesomeButton;
+btn.setAttribute("variant", "secondary");
+btn.setLoading(true);
+
+// Type-safe events
+btn.addEventListener("button:click", (e) => {
+  console.log("Clicked:", e.detail.timestamp);
+});
+```
+
+### Key Features for Libraries
+
+✅ **TypeScript Interfaces** - Full type definitions for all props, events, and methods  
+✅ **Component Registry** - Easy batch registration  
+✅ **Helper Functions** - `createButton()`, `configureCard()`, etc.  
+✅ **Metadata Export** - Component documentation and metadata  
+✅ **Multiple Formats** - ESM, CJS, UMD outputs  
+✅ **Tree-Shakeable** - Only import what you use
+
+### Creating Your Library
+
+1. **Define TypeScript interfaces** for props, events, and typed element references
+2. **Create single-file `.html` components** with template, styles, and scripts
+3. **Export helper functions** for programmatic component creation
+4. **Create component registry** for batch registration
+5. **Configure package.json** with exports field for subpath imports
+6. **Build and publish** to NPM
+
+### Example Projects
+
+- **[Full Example Library](samples/component-library/)** - Complete Button, Card, Modal components with TypeScript
+- **[Library Demo App](samples/apps/component-library-demo/)** - Shows all usage patterns and integrations
+
+### Complete Guide
+
+For detailed instructions on creating, building, and publishing component libraries, see the **[Library Authoring Guide](docs/LIBRARY_AUTHORING.md)**.
+
+Topics covered:
+
+- Project structure and best practices
+- Component creation with HTML + TypeScript
+- Building with Vite
+- Publishing to NPM
+- Consumer usage examples
+- React/Vue integration patterns
+
 ## Common Patterns
 
 ### Keyboard Events