litewire 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Your Name
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.MD

@@ -0,0 +1,263 @@
+# Litewire Framework
+
+## Complete Architecture Manual & Reference Guide
+
+A comprehensive technical breakdown of the HTML-driven AJAX engine, dynamic component loader, DOM swapping, state management, and lifecycle events.
+
+---
+
+## Table of Contents
+
+1. [Architecture Overview & Lifecycle](#1-architecture-overview--lifecycle)
+2. [Core Configuration & Initialization](#2-core-configuration--initialization)
+3. [Attribute Reference API](#3-attribute-reference-api)
+4. [Dynamic ES Module Loader (`lw-component`)](#4-dynamic-es-module-loader-lw-component)
+5. [DOM Swapping & Navigation Mechanisms](#5-dom-swapping--navigation-mechanisms)
+6. [History & State Caching](#6-history--state-caching)
+7. [Event System & Lifecycle Hooks](#7-event-system--lifecycle-hooks)
+8. [CSRF & Security Protocols](#8-csrf--security-protocols)
+9. [Practical Implementation Patterns](#9-practical-implementation-patterns)
+
+---
+
+## 1. Architecture Overview & Lifecycle
+
+**Litewire** is an HTML-first AJAX engine and dynamic component loader designed to build modern, interactive single-page-like applications with minimal client-side JavaScript configuration. By extending standard HTML elements with custom `lw-*` attributes, Litewire automatically intercepts user interactions, initiates asynchronous HTTP requests, updates specific DOM regions, and manages dynamic ES Module lifecycles.
+
+> **Core Principles**  
+> Litewire eliminates the need for full-page reloads and complex SPA frameworks by leveraging declarative markup, dynamic MutationObservers, and native browser features like `fetch()` and `history.pushState()`.
+
+### Lifecycle Flow
+
+1. **Initialization:** The class resolves the application's base URL and attaches DOM observers.
+2. **Document Scanning:** Existing DOM nodes are scanned for request triggers and dynamic components.
+3. **Event Binding:** Intercepts clicks, form submissions, and page load triggers automatically.
+4. **Execution:** Sends non-blocking background HTTP requests with built-in CSRF security headers.
+5. **Swap & Mount:** Replaces target DOM regions with backend HTML and automatically boots dynamic JS components on newly introduced elements.
+
+---
+
+## 2. Core Configuration & Initialization
+
+Litewire auto-instantiates as soon as the DOM is ready, exposing its instance globally on `window.litewire`.
+
+### Base URL Resolution Priority
+
+To support deployment in deeply nested directories or custom app sub-paths, Litewire resolves its root URL using a four-tier fallback mechanism:
+
+```text
+1. Constructor Option:  new Litewire({ baseUrl: '[https://example.com/api](https://example.com/api)' })
+2. Meta Tag Element:    <meta name="base-url" content="[https://example.com](https://example.com)">
+3. Global App Config:  window.AppConfig.baseUrl
+4. Window Location:     window.location.origin (Default)
+```
+
+### Instantiation Example
+
+```javascript
+// Custom manual instantiation with options
+const customLitewire = new Litewire({
+    baseUrl: '[https://api.myproject.com](https://api.myproject.com)',
+    loadingClass: 'is-loading' // Class applied to active triggers and indicators
+});
+```
+
+---
+
+## 3. Attribute Reference API
+
+All core functionalities are driven by attaching `lw-*` attributes directly to standard HTML tags.
+
+| Attribute | Accepted Values | Default | Functional Description |
+|---|---|---|---|
+| `lw-get` | Relative / Absolute Path | None | Executes an HTTP GET request to the specified endpoint. |
+| `lw-post` | Relative / Absolute Path | None | Executes an HTTP POST request. Submits form payload if bound to or inside a `<form>`. |
+| `lw-put` | Relative / Absolute Path | None | Executes an HTTP PUT request with FormData payload attachment. |
+| `lw-delete` | Relative / Absolute Path | None | Executes an HTTP DELETE request. |
+| `lw-trigger` | `click`, `submit`, `load`, custom | Contextual | Overrides trigger event. Defaults to `submit` for forms, `click` for interactive tags. `load` fires instantly. |
+| `lw-target` | CSS Selector | Self Element | Specifies the container element where the returned HTML response will be rendered. |
+| `lw-swap` | `innerHTML`, `outerHTML`, `prepend`, `append` | `innerHTML` | Controls how the received HTML response replaces or integrates into the target element. |
+| `lw-indicator` | CSS Selector | `.litewire-indicator` | Specifies target loading elements. Automatically toggles the active `loadingClass` during request execution. |
+| `lw-push-url` | `true`, `false`, Custom Path | `false` | Pushes a new state to the browser history, caching DOM contents for native back/forward navigation. |
+| `lw-component` | JS File Path | None | Asynchronously imports a JavaScript module and mounts it directly onto the host DOM element. |
+
+---
+
+## 4. Dynamic ES Module Loader (`lw-component`)
+
+Litewire features a client-side component loader capable of fetching and initializing JavaScript ES modules on demand without requiring heavy bundle configurations or static page imports.
+
+### Component Mounting Process
+
+When an element with `lw-component="path/to/module.js"` is injected into the DOM:
+
+1. Litewire resolves the full script path against `this.baseUrl`.
+2. Executes a native dynamic `import(fullPath)` statement.
+3. Extracts component constructors or functions via fallback export resolution:
+   `module.default` → `module.imageUploader` → `Object.values(module)[0]`
+4. Instantiates the module using `new componentFn(el, params)` or direct function execution.
+5. Passes all `data-*` HTML attributes as an object to the component's `params` argument.
+
+### Component Implementation Example
+
+#### HTML Markup
+
+```html
+<!-- Target element containing component directives and dataset parameters -->
+<div 
+  lw-component="assets/js/uploader.js" 
+  data-max-files="5" 
+  data-allowed-types="image/png,image/jpeg">
+</div>
+```
+
+#### JavaScript Module (`assets/js/uploader.js`)
+
+```javascript
+export default class ImageUploader {
+    constructor(element, params) {
+        this.container = element;
+        this.maxFiles = params.maxFiles || 1;
+        this.allowedTypes = params.allowedTypes || '*';
+        
+        this.render();
+    }
+
+    render() {
+        this.container.innerHTML = `
+            <div class="upload-box">
+                <p>Upload up to ${this.maxFiles} files (${this.allowedTypes})</p>
+                <input type="file" multiple accept="${this.allowedTypes}">
+            </div>
+        `;
+    }
+}
+```
+
+---
+
+## 5. DOM Swapping & Navigation Mechanisms
+
+Litewire supports multiple strategies for swapping returned server HTML responses into target elements using the `lw-swap` attribute.
+
+### Swap Modes
+
+- **`innerHTML` (Default):** Replaces the complete inner HTML content of the target container.
+- **`outerHTML`:** Completely replaces the target element itself with the server response.
+- **`prepend`:** Inserts the new server HTML snippet right before the first child inside the target element.
+- **`append`:** Appends the new server HTML snippet right after the last child inside the target element.
+
+### Automated Mutation Monitoring
+
+Litewire uses an internal `MutationObserver` attached to `document.body`. Whenever new DOM elements are appended via AJAX swaps, standard page renders, or dynamic JS scripts, Litewire automatically scans and binds all newly discovered `lw-*` elements and mounts dynamic `lw-component` directives seamlessly.
+
+---
+
+## 6. History & State Caching
+
+Enabling history tracking via `lw-push-url="true"` allows AJAX-driven applications to retain full browser history support, enabling smooth back-and-forward navigation without page refreshes.
+
+### How State Caching Works
+
+1. When a request completes successfully, Litewire captures the target container's current `innerHTML`.
+2. Saves an object containing `{ litewireUrl, targetSelector, html }` into `window.history.state`.
+3. When users press the browser's **Back** or **Forward** buttons, a `popstate` event fires.
+4. Litewire retrieves the cached HTML snippet directly from history state and restores the DOM instantly without initiating network requests.
+5. If no cached HTML state exists, Litewire seamlessly falls back to re-fetching the current location URL.
+
+---
+
+## 7. Event System & Lifecycle Hooks
+
+Litewire dispatches standard, bubbling DOM events during the request lifecycles. Custom JavaScript code can hook into these lifecycle stages using standard `addEventListener` calls.
+
+| Event Name | `event.detail` | Description / Usage |
+|---|---|---|
+| `litewire:beforeRequest` | `null` | Fires immediately before the HTTP request is initiated. Ideal for disabling inputs or custom client validation. |
+| `litewire:afterRequest` | `null` | Fires after the request succeeds and the HTML content swap is complete. Ideal for triggering animations. |
+| `litewire:error` | `{ error: Error }` | Fires if a network error occurs or the HTTP response returns an error status (non-2xx). |
+
+### Lifecycle Hooks Example
+
+```javascript
+// Global logging and notification system integration
+document.addEventListener('litewire:beforeRequest', (e) => {
+    console.log('Initiating Litewire request from:', e.target);
+});
+
+document.addEventListener('litewire:error', (e) => {
+    alert(`Request failed: ${e.detail.error.message}`);
+});
+```
+
+---
+
+## 8. CSRF & Security Protocols
+
+Litewire natively secures outgoing write operations (`POST`, `PUT`, `DELETE`) against Cross-Site Request Forgery (CSRF) attacks.
+
+### Automatic Token Attachment
+
+Before dispatching non-GET requests, Litewire scans the host page head for a CSRF meta tag:
+
+```html
+<meta name="csrf-token" content="abc123securehash456">
+```
+
+If detected, Litewire automatically includes the retrieved token into the HTTP request headers:
+
+```text
+X-CSRF-TOKEN: abc123securehash456
+```
+
+---
+
+## 9. Practical Implementation Patterns
+
+### Pattern A: Instant Dynamic Search Table
+
+```html
+<!-- Live search input updating target table and browser address bar -->
+<input 
+  type="text" 
+  name="q" 
+  placeholder="Search users..." 
+  lw-get="/users/search" 
+  lw-trigger="keyup" 
+  lw-target="#user-table-body" 
+  lw-push-url="true">
+
+<table>
+  <tbody id="user-table-body">
+    <!-- Table rows updated dynamically -->
+  </tbody>
+</table>
+```
+
+### Pattern B: Form Submission with Indicator & Append Swap
+
+```html
+<form lw-post="/comments/add" lw-target="#comments-list" lw-swap="append" lw-indicator="#spinner">
+  <textarea name="comment" required placeholder="Write a comment..."></textarea>
+  
+  <button type="submit">
+    Post Comment 
+    <span id="spinner" class="litewire-indicator hidden">Posting...</span>
+  </button>
+</form>
+
+<div id="comments-list">
+  <!-- New comments prepended or appended dynamically -->
+</div>
+```
+
+### Pattern C: Lazy-Loading Section on Page Load
+
+```html
+<!-- Automatically fetches and replaces content once page loads -->
+<div lw-get="/analytics/widget" lw-trigger="load" lw-target="#analytics-container">
+    <p>Loading real-time analytics data...</p>
+</div>
+
+<div id="analytics-container"></div>
+```

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "litewire",
+  "version": "1.0.0",
+  "description": "A lightweight HTML-driven AJAX engine and dynamic ES module component loader.",
+  "main": "src/litewire.js",
+  "module": "src/litewire.js",
+  "type": "module",
+  "exports": {
+    ".": "./src/litewire.js"
+  },
+  "files": [
+    "src/",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "ajax",
+    "htmx",
+    "html-over-the-wire",
+    "components",
+    "dom-observer"
+  ],
+  "author": "Zainurrahman <languaojs@gmail.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/languaojs/litewire.git"
+  },
+  "bugs": {
+    "url": "https://github.com/languaojs/litewire/issues"
+  },
+  "homepage": "https://github.com/languaojs/litewire#readme"
+}

package/src/litewire.js

@@ -0,0 +1,247 @@
+class Litewire {
+    constructor(options = {}) {
+        const metaBaseUrl = document.querySelector('meta[name="base-url"]')?.getAttribute('content');
+        const rawBaseUrl = options.baseUrl
+            || metaBaseUrl
+            || window.AppConfig?.baseUrl
+            || window.location.origin;
+        this.baseUrl = rawBaseUrl.replace(/\/+$/, '');
+        this.loadingClass = options.loadingClass || 'litewire-request';
+        this.init();
+    }
+
+    init() {
+        this.scan(document);
+        this.loadComponents(document);
+        this.observe();
+        this.listenToHistory();
+    }
+
+    async loadComponents(root) {
+        const selector = '[lw-component]';
+        const elements = root.querySelectorAll ? root.querySelectorAll(selector) : [];
+
+        if (root.nodeType === Node.ELEMENT_NODE && root.matches(selector)) {
+            this.mountComponent(root);
+        }
+        elements.forEach(el => this.mountComponent(el));
+    }
+
+    async mountComponent(el) {
+        if (el._litewireComponentMounted) return;
+        el._litewireComponentMounted = true;
+
+        const rawPath = el.getAttribute('lw-component');
+        if (!rawPath) return;
+
+        const cleanPath = rawPath.replace(/^\/+/, '');
+        const fullPath = `${this.baseUrl}/${cleanPath}`;
+
+        try {
+            const module = await import(fullPath);
+            const params = { ...el.dataset };
+
+            const componentFn = module.default || module.imageUploader || Object.values(module)[0];
+
+            if (typeof componentFn === 'function') {
+                try {
+                    new componentFn(el, params);
+                } catch {
+                    componentFn(el, params);
+                }
+            } else {
+                console.error(`[Litewire Error] No valid export found in module: ${fullPath}`);
+            }
+        } catch (err) {
+            console.error(`[Litewire Error] Failed to import component from ${fullPath}:`, err);
+        }
+    }
+
+    scan(root) {
+        const selector = '[lw-get], [lw-post], [lw-put], [lw-delete], [lw-trigger="load"]';
+        const elements = root.querySelectorAll ? root.querySelectorAll(selector) : [];
+
+        if (root.nodeType === Node.ELEMENT_NODE && root.matches(selector)) {
+            this.bindElement(root);
+        }
+        elements.forEach(el => this.bindElement(el));
+    }
+
+    bindElement(el) {
+        if (el._litewireBound) return;
+        el._litewireBound = true;
+
+        const trigger = el.getAttribute('lw-trigger') || (el.tagName === 'FORM' ? 'submit' : 'click');
+
+        if (trigger === 'load') {
+            this.executeRequest(el);
+        } else {
+            el.addEventListener(trigger, (e) => {
+                if (el.tagName === 'FORM' || trigger === 'click') e.preventDefault();
+                this.executeRequest(el);
+            });
+        }
+    }
+
+    getIndicators(el) {
+        const indicatorAttr = el.getAttribute('lw-indicator');
+        if (!indicatorAttr) {
+            return Array.from(el.querySelectorAll('.litewire-indicator'));
+        }
+        return Array.from(document.querySelectorAll(indicatorAttr));
+    }
+
+    async executeRequest(el, isPopState = false) {
+        const method = ['post', 'put', 'delete', 'get'].find(m => el.hasAttribute(`lw-${m}`)) || 'get';
+        const path = el.getAttribute(`lw-${method}`);
+        if (!path) return;
+
+        const cleanPath = path.replace(/^\/+/, '');
+        const url = `${this.baseUrl}/${cleanPath}`;
+
+        const options = { method: method.toUpperCase(), headers: {} };
+
+        const csrfToken = document.querySelector('meta[name="csrf-token"]')?.getAttribute('content');
+        if (csrfToken) {
+            options.headers['X-CSRF-TOKEN'] = csrfToken;
+        }
+
+        if (method !== 'get') {
+            const form = el.tagName === 'FORM' ? el : el.closest('form');
+            if (form) {
+                options.body = new FormData(form);
+            }
+        }
+
+        const indicators = this.getIndicators(el);
+
+        try {
+            el.classList.add(this.loadingClass);
+            indicators.forEach(ind => ind.classList.add(this.loadingClass));
+
+            el.dispatchEvent(new CustomEvent('litewire:beforeRequest', { bubbles: true }));
+
+            const response = await fetch(url, options);
+            if (!response.ok) throw new Error(`HTTP ${response.status}`);
+            const html = await response.text();
+
+            const target = this.swapHTML(el, html);
+
+            if (!isPopState) {
+                this.handleHistoryPush(el, url, target);
+            }
+
+            el.dispatchEvent(new CustomEvent('litewire:afterRequest', { bubbles: true }));
+        } catch (err) {
+            console.error(`[Litewire Error] ${method.toUpperCase()} ${url} failed:`, err);
+            el.dispatchEvent(new CustomEvent('litewire:error', { bubbles: true, detail: { error: err } }));
+        } finally {
+            el.classList.remove(this.loadingClass);
+            indicators.forEach(ind => ind.classList.remove(this.loadingClass));
+        }
+    }
+
+    swapHTML(el, html) {
+        const targetSelector = el.getAttribute('lw-target');
+        const target = targetSelector ? document.querySelector(targetSelector) : el;
+        const swapType = el.getAttribute('lw-swap') || 'innerHTML';
+
+        if (!target) return target;
+
+        if (swapType === 'outerHTML') {
+            const parent = target.parentElement;
+            target.outerHTML = html;
+            if (parent) {
+                this.scan(parent);
+                this.loadComponents(parent);
+            }
+        } else if (swapType === 'prepend') {
+            target.insertAdjacentHTML('afterbegin', html);
+            this.scan(target);
+            this.loadComponents(target);
+        } else if (swapType === 'append') {
+            target.insertAdjacentHTML('beforeend', html);
+            this.scan(target);
+            this.loadComponents(target);
+        } else {
+            target.innerHTML = html;
+            this.scan(target);
+            this.loadComponents(target);
+        }
+
+        return target;
+    }
+
+    handleHistoryPush(el, requestUrl, target) {
+        const pushAttr = el.getAttribute('lw-push-url');
+        if (!pushAttr || pushAttr === 'false') return;
+
+        const newUrl = pushAttr === 'true' ? requestUrl : pushAttr;
+        const targetSelector = el.getAttribute('lw-target') || '';
+
+        if (!history.state) {
+            history.replaceState({
+                litewireUrl: window.location.href,
+                targetSelector: targetSelector,
+                html: target ? target.innerHTML : ''
+            }, '', window.location.href);
+        }
+
+        history.pushState({
+            litewireUrl: newUrl,
+            targetSelector: targetSelector,
+            html: target ? target.innerHTML : ''
+        }, '', newUrl);
+    }
+
+    listenToHistory() {
+        window.addEventListener('popstate', (e) => {
+            if (!e.state) return;
+
+            const { targetSelector, html, litewireUrl } = e.state;
+
+            if (targetSelector && html !== undefined) {
+                const target = document.querySelector(targetSelector);
+                if (target) {
+                    target.innerHTML = html;
+                    this.scan(target);
+                    this.loadComponents(target);
+                    return;
+                }
+            }
+
+            const fallbackEl = document.createElement('div');
+            fallbackEl.setAttribute('lw-get', litewireUrl || window.location.href);
+            if (targetSelector) fallbackEl.setAttribute('lw-target', targetSelector);
+
+            this.executeRequest(fallbackEl, true);
+        });
+    }
+
+    observe() {
+        const observer = new MutationObserver((mutations) => {
+            for (const m of mutations) {
+                m.addedNodes.forEach(node => {
+                    if (node.nodeType === Node.ELEMENT_NODE) {
+                        this.scan(node);
+                        this.loadComponents(node);
+                    }
+                });
+            }
+        });
+        observer.observe(document.body, { childList: true, subtree: true });
+    }
+}
+
+export default Litewire;
+
+// Auto-instantiate in browser environments if not loaded as a module
+if (typeof window !== 'undefined' && typeof document !== 'undefined') {
+    if (document.readyState === 'loading') {
+        document.addEventListener('DOMContentLoaded', () => {
+            if (!window.litewire) window.litewire = new Litewire();
+        });
+    } else {
+        if (!window.litewire) window.litewire = new Litewire();
+    }
+}