npm - litewire - Versions diffs - 1.0.1 → 1.0.3 - Mend

litewire 1.0.1 → 1.0.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (4) hide show

package/LICENSE CHANGED Viewed

@@ -1,6 +1,6 @@
 MIT License
-Copyright (c) 2026 Your Name
+Copyright (c) 2026 Zainurrahman
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal
@@ -18,4 +18,4 @@ 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.
+SOFTWARE.

package/README.MD CHANGED Viewed

@@ -1,305 +1,471 @@
-# Litewire Framework
+# Litewire 1.0.3
-```bash
-npm i litewire
-```
+Litewire is a small browser-side HTML-over-the-wire library. It binds HTTP
+requests, reactive state, and event expressions to HTML attributes, swaps
+server-rendered HTML into the page, and can load ES module components on
+demand.
-## Complete Architecture Manual & Reference Guide
+Version 1.0.3 adds reactive `lw:class` bindings, iterable lists with
+`template[lw:for]`, and event-triggered component mounting. It also improves
+radio model initialization and browser-history markup restoration.
-A comprehensive technical breakdown of the HTML-driven AJAX engine, dynamic component loader, DOM swapping, state management, and lifecycle events.
+## Contents
----
+- [Install and start](#install-and-start)
+- [Configuration](#configuration)
+- [AJAX requests](#ajax-requests)
+- [Reactive state and bindings](#reactive-state-and-bindings)
+- [Lists](#lists)
+- [Dynamic components](#dynamic-components)
+- [HTML swaps and DOM updates](#html-swaps-and-dom-updates)
+- [Browser history](#browser-history)
+- [Lifecycle events](#lifecycle-events)
+- [CSRF](#csrf)
+- [Security considerations](#security-considerations)
+- [API reference](#api-reference)
-## Table of Contents
+## Install and start
-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)
+### Use the browser file
----
+Download `litewire.js` and load it as an ES module:
-## 1. Architecture Overview & Lifecycle
+```html
+<script type="module" src="/js/litewire.js"></script>
+```
-**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.
+Litewire creates `window.litewire` when the document is ready, unless that
+global already exists. It scans the page, binds supported attributes, and
+continues scanning elements added later.
-> **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()`.
+### Use the npm package
-### Lifecycle Flow
+Install version 1.0.3 from your configured npm registry:
-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.
+```sh
+npm install litewire@1.0.3
+```
----
+Import the package from your application's JavaScript entry point:
-## 2. Core Configuration & Initialization
+```js
+import "litewire";
+```
-Litewire auto-instantiates as soon as the DOM is ready, exposing its instance globally on `window.litewire`.
+The package module auto-initializes in a browser environment. Do not create a
+second instance unless you intentionally want an additional set of listeners
+and observers.
-### Base URL Resolution Priority
+### First request
-To support deployment in deeply nested directories or custom app sub-paths, Litewire resolves its root URL using a four-tier fallback mechanism:
+```html
+<button
+  lw-get="/hello"
+  lw-target="#result"
+>
+  Load greeting
+</button>
-```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)
+<div id="result">The response will appear here.</div>
 ```
-### Instantiation Example
+Litewire sends a GET request when the button is clicked and replaces the
+contents of `#result` with the response HTML.
-```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
-});
+## Configuration
+Litewire resolves its base URL in this order:
+1. `baseUrl` constructor option
+2. `<meta name="base-url" content="...">`
+3. `window.AppConfig.baseUrl`
+4. `window.location.origin`
+The default loading class is `litewire-request`. Configure these values before
+Litewire auto-initializes by setting a meta tag or `window.AppConfig` before
+loading the module:
+```html
+<meta name="base-url" content="https://example.com/app">
+<script>
+  window.AppConfig = { baseUrl: "https://example.com/app" };
+</script>
+<script type="module" src="/js/litewire.js"></script>
 ```
----
+The constructor also accepts options when you instantiate the exported class
+yourself:
-## 3. Attribute Reference API
+```js
+window.litewire = {};
+const { default: Litewire } = await import("./litewire.js");
+window.litewire = new Litewire({
+  baseUrl: "https://example.com/app",
+  loadingClass: "is-loading",
+});
+```
-All core functionalities are driven by attaching `lw-*` attributes directly to standard HTML tags.
+The placeholder prevents the module's browser auto-initializer from creating
+another instance before your configured instance is constructed.
-| 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.                   |
+Request and component paths are joined to the resolved base URL. Leading
+slashes are removed from the supplied path before joining.
----
+## AJAX requests
-## 4. Dynamic ES Module Loader (`lw-component`)
+Litewire recognizes `lw-get`, `lw-post`, `lw-put`, and `lw-delete`. It binds
+forms to `submit` by default and other elements to `click`. Set `lw-trigger` to
+choose a different event or to run a request when the element is scanned:
-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.
+```html
+<form lw-post="/messages" lw-target="#messages">
+  <label>
+    Message
+    <input name="message" required>
+  </label>
+  <button type="submit">Send</button>
+</form>
-### Component Mounting Process
+<div id="messages"></div>
+```
-When an element with `lw-component="path/to/module.js"` is injected into the DOM:
+For GET requests, form fields are encoded as URL query parameters. For POST,
+PUT, and DELETE requests, a containing form is sent as `FormData`. If the
+trigger is not in a form, no request body is added.
-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.
+```html
+<input
+  name="q"
+  lw-get="/search"
+  lw-trigger="keyup"
+  lw-target="#results"
+  lw-indicator="#search-status"
+>
+<span id="search-status" class="litewire-indicator">Searching…</span>
+<div id="results"></div>
+```
-### Component Implementation Example
+When a request starts, Litewire adds the configured loading class to the
+trigger and its indicators. Indicators default to `.litewire-indicator`
+descendants of the trigger; `lw-indicator` can instead specify a document-wide
+CSS selector. Litewire removes the class when the request finishes, whether it
+succeeds or fails.
-#### HTML Markup
+Use `lw-trigger="load"` with a request attribute to start a request as soon as
+the element is scanned:
 ```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>
+<section
+  lw-get="/account/summary"
+  lw-trigger="load"
+  lw-target="#account-summary"
+>
+  Loading account summary…
+</section>
+<div id="account-summary"></div>
 ```
-#### JavaScript Module (`assets/js/uploader.js`)
+## Reactive state and bindings
-```javascript
-export default class ImageUploader {
-  constructor(element, params) {
-    this.container = element;
-    this.maxFiles = params.maxFiles || 1;
-    this.allowedTypes = params.allowedTypes || "*";
+Litewire provides a small reactive layer using `lw:state`, `lw:model`,
+`lw:text`, `lw:show`, `lw:class`, `lw:for`, and event-expression attributes.
+The colon in these attribute names is intentional.
-    this.render();
-  }
+### Local state
-  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>
-        `;
-  }
-}
+Put `lw:state` on an element to create state for that element and its
+descendants. Its value must be a JavaScript expression that evaluates to an
+object:
+```html
+<section lw:state="{ count: 0, visible: true }">
+  <button lw:click="count++">Count: <span lw:text="count"></span></button>
+  <p lw:show="visible">This paragraph can be hidden.</p>
+  <button lw:click="visible = !visible">Toggle paragraph</button>
+</section>
 ```
----
+Assignments and deletions of top-level state properties trigger rendering of
+bindings on that element and its descendants that belong to that state root.
+State is shallowly reactive:
+mutating a nested object or array in place does not itself trigger a render.
+Replace the top-level property to trigger one, for example
+`settings = { ...settings, enabled: false }`.
-## 5. DOM Swapping & Navigation Mechanisms
+Nested `lw:state` elements establish their own state scope. A binding uses the
+nearest ancestor state root. Bindings outside a state root use Litewire's
+global models instead.
-Litewire supports multiple strategies for swapping returned server HTML responses into target elements using the `lw-swap` attribute.
+### Text and visibility
-### Swap Modes
+- `lw:text="expression"` evaluates the expression and writes its result as
+  text. `null` and `undefined` render as an empty string.
+- `lw:show="expression"` sets the element's `hidden` property based on the
+  truthiness of the result.
+- `lw:class="{ className: expression }"` adds each class whose expression is
+  truthy and removes classes previously managed by this binding when they
+  become false. Other classes on the element are left alone; a key may contain
+  multiple space-separated class names.
-- **`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.
+Expressions are evaluated when the element is first scanned and again when
+their owning local state renders. Global model updates refresh matching
+`lw:text` bindings and reevaluate global `lw:class` bindings and loops.
-### Automated Mutation Monitoring
+### Lists
-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.
+Use `lw:for` on a `<template>` to repeat its contents for each value in an
+iterable. The repeated expressions can access the item name and `$index`;
+`(item, index)` also declares a named index:
----
+```html
+<ul lw:state="{ items: ['Apples', 'Pears'] }">
+  <template lw:for="(item, index) of items">
+    <li>
+      <span lw:text="index + 1"></span>.
+      <span lw:text="item"></span>
+    </li>
+  </template>
+</ul>
+```
-## 6. History & State Caching
+The expression must evaluate to an iterable, such as an array, string, `Set`,
+or `Map`; `null` and `undefined` render no rows. Assign a new array to the
+top-level state property to refresh the list. Litewire recreates the repeated
+DOM when the owning state renders; it does not key or preserve individual rows
+across updates. `lw:for` also works with global models set through
+`litewire.setModel()`.
-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.
+### Form models
-### How State Caching Works
+```html
+<div lw:state="{ name: '' }">
+  <label>
+    Your name
+    <input lw:model="name">
+  </label>
+  <p>Hello, <span lw:text="name"></span>.</p>
+</div>
+```
-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.
+The default `lw:model` and `lw:model.live` listen for `input`.
+`lw:model.change` listens for `change`, and `lw:model.blur` listens for `blur`.
+For checkboxes, the model value is a boolean; for radio inputs, it is the
+checked value or `null`. Unchecked radio buttons do not initialize or overwrite
+the shared model; other controls use their value.
----
+Without a local `lw:state` root, models are stored globally and can be read or
+written with the instance methods `litewire.getModel(name)` and
+`litewire.setModel(name, value)`. Global model changes dispatch a
+`litewire:model` event on `document`, with `{ name, value }` in `event.detail`.
-## 7. Event System & Lifecycle Hooks
+A model name beginning with `#` or `.` is treated as a CSS selector instead of
+a state key. Litewire copies the control's value to matching elements (to
+`value` for form controls, otherwise to `textContent`) and dispatches
+`litewire:model` on each target with `{ value }` in `event.detail`.
-Litewire dispatches standard, bubbling DOM events during the request lifecycles. Custom JavaScript code can hook into these lifecycle stages using standard `addEventListener` calls.
+### Event expressions
-| 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).                         |
+Supported event attributes are:
-### Lifecycle Hooks Example
+```text
+lw:click   lw:input   lw:change   lw:submit
+lw:keydown lw:keyup   lw:focus    lw:blur
+```
-```javascript
-// Global logging and notification system integration
-document.addEventListener("litewire:beforeRequest", (e) => {
-  console.log("Initiating Litewire request from:", e.target);
-});
+The attribute value is evaluated when its event fires. Within the expression,
+the nearest local state properties (or global models) are in scope. Special
+values are available:
-document.addEventListener("litewire:error", (e) => {
-  alert(`Request failed: ${e.detail.error.message}`);
-});
-```
+- `$event`: the DOM event
+- `$el`: the element carrying the directive
+- `$value`: the current value of that element
+- `$state`: the current state object
+- `$wire`: the Litewire instance
----
+```html
+<div lw:state="{ query: '' }">
+  <input lw:model="query">
+  <button lw:click="console.log(query, $event)">Log query</button>
+</div>
+```
-## 8. CSRF & Security Protocols
+Supported event modifiers:
+| Modifier | Behavior |
+|---|---|
+| `.prevent` | Calls `preventDefault()` |
+| `.stop` | Calls `stopPropagation()` |
+| `.once` | Runs the handler at most once |
+| `.capture` | Registers the listener in capture phase |
+| `.passive` | Registers a passive listener |
+| `.self` | Runs only when the event target is the directive element |
+| `.outside` | Runs only when the event target is outside the directive element |
+| `.window` | Registers the listener on `window` |
+| `.document` | Registers the listener on `document` |
+| `.debounce` | Delays execution until events stop for 250 ms |
+| `.throttle` | Runs at most once per 250 ms |
+Modifiers can be combined, for example `lw:click.prevent.once="save()"`.
+Debounce and throttle delays can be customized in milliseconds, for example
+`lw:input.debounce.400ms="search()"` or
+`lw:click.throttle.1000ms="refresh()"`. `.outside` listens at the document
+level so it can observe events outside the element.
+## Dynamic components
+An element with `lw-component` dynamically imports a JavaScript module. The
+path is joined to Litewire's base URL. Litewire selects the module's default
+export first, then a named `imageUploader` export, then the first export. If
+the selected export is a function, it is called with the host element and its
+`data-*` attributes converted to an object:
-Litewire natively secures outgoing write operations (`POST`, `PUT`, `DELETE`) against Cross-Site Request Forgery (CSRF) attacks.
+```html
+<div
+  lw-component="components/greeting.js"
+  data-user-name="Ada"
+></div>
+```
-### Automatic Token Attachment
+```js
+// /app/components/greeting.js
+export default class Greeting {
+  constructor(element, params) {
+    element.textContent = `Hello, ${params.userName}!`;
+  }
+}
+```
-Before dispatching non-GET requests, Litewire scans the host page head for a CSRF meta tag:
+New components inserted by a swap or added to the document are discovered
+automatically. By default, and with `lw-trigger="load"`, a component mounts
+when discovered. Set `lw-trigger` to another event name to defer mounting
+until that event fires. On a triggered component, `lw-target` optionally
+selects the element passed to the component constructor; the component path
+and `data-*` parameters still come from the element carrying `lw-component`.
+A component is mounted only once after a successful mount. To load one after
+an event and mount it into another element, put `lw-trigger` and `lw-target`
+on the component source:
 ```html
-<meta name="csrf-token" content="abc123securehash456" />
+<button
+  type="button"
+  lw-component="components/widget.js"
+  lw-trigger="click"
+  lw-target="#widget"
+  data-mode="compact"
+>
+  Load widget
+</button>
+<div id="widget"></div>
 ```
-If detected, Litewire automatically includes the retrieved token into the HTTP request headers:
+The module path and `data-*` parameters come from the element carrying
+`lw-component`; `lw-target` is the element passed to the component.
-```text
-X-CSRF-TOKEN: abc123securehash456
-```
+## HTML swaps and DOM updates
+Set `lw-target` to a CSS selector to choose where a response is inserted. If
+omitted, the element that triggered the request is the target. `lw-swap`
+controls how response HTML is applied:
----
+| Value | Behavior |
+|---|---|
+| `innerHTML` (default) | Replaces the target's contents |
+| `outerHTML` | Replaces the target element |
+| `prepend` | Inserts response HTML at the beginning of the target |
+| `append` | Inserts response HTML at the end of the target |
-## 9. Practical Implementation Patterns
+Litewire scans swapped content and mounts its components. It also observes
+added DOM elements so directives in newly inserted content are bound
+automatically.
-### Pattern A: Instant Dynamic Search Table
+## Browser history
+Set `lw-push-url="true"` to push the request URL to browser history, or provide
+a custom URL as the attribute value:
 ```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"
+<a
+  href="/products"
+  lw-get="/products"
+  lw-target="#page"
   lw-push-url="true"
-/>
-<table>
-  <tbody id="user-table-body">
-    <!-- Table rows updated dynamically -->
-  </tbody>
-</table>
+>
+  Products
+</a>
 ```
-```php
-// Route
-Route::get('/users/search', 'UsersController@search')->name('user.search');
-//UserController
-public function search(Request $request)
-    {
-        $query = $request->input('q', '');
-        $search = $this->model('UsersModel')->searchUser($query);
-        $data = [
-            'users' => $search
-        ];
-        $html = $this->render('users/search', $data);
-        return $this->response($html);
-    }
-//Blade
-@if (!empty($users))
-    @foreach ($users as $index => $user)
-        <tr>
-            <td>{{ $index + 1 }}</td>
-            <td>{{ $user['fullname'] }}</td>
-        </tr>
-    @endforeach
-@endif
-```
+Litewire stores the URL, target selector, swap type, and target markup in
+history state. When it creates the initial history entry, it saves the current
+markup so Back can restore the prior view. For `outerHTML`, cached markup
+includes the target element itself. When navigating with Back or Forward,
+Litewire restores cached markup when the target still exists; otherwise it
+attempts to fetch the stored URL. This caches only the selected target's
+markup, not the complete document or JavaScript state.
-### Pattern B: Form Submission with Indicator & Append Swap
+## Lifecycle events
-```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>
+Litewire dispatches bubbling events from the request trigger:
-  <button type="submit">
-    Post Comment
-    <span id="spinner" class="litewire-indicator hidden">Posting...</span>
-  </button>
-</form>
+| Event | `event.detail` | When it fires |
+|---|---|---|
+| `litewire:beforeRequest` | — | Immediately before sending a request |
+| `litewire:afterRequest` | — | After a successful response has been swapped |
+| `litewire:error` | `{ error }` | On a network failure or non-success HTTP response |
-<div id="comments-list">
-  <!-- New comments prepended or appended dynamically -->
-</div>
+Reactive local state also dispatches `litewire:render` from its state root
+after a render, with `{ state }` in `event.detail`.
+```js
+document.addEventListener("litewire:error", (event) => {
+  console.error("Litewire request failed:", event.detail.error);
+});
+document.addEventListener("litewire:render", (event) => {
+  console.log("State rendered:", event.detail.state);
+});
 ```
-### Pattern C: Lazy-Loading Section on Page Load
+## CSRF
-```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>
+When this meta tag is present, Litewire adds its token as the
+`X-CSRF-TOKEN` header to outgoing requests:
-<div id="analytics-container"></div>
+```html
+<meta name="csrf-token" content="your-server-generated-token">
 ```
+The server must still validate the token and enforce its own authorization and
+request protections.
+## Security considerations
+Litewire inserts response bodies as HTML. Only return trusted or appropriately
+sanitized HTML from your server.
+`lw:state` and event-expression attributes are evaluated as JavaScript. Use
+them only in markup you control; do not construct these expressions from
+untrusted user input.
+## API reference
+| Attribute / API | Description |
+|---|---|
+| `lw-get`, `lw-post`, `lw-put`, `lw-delete` | Request path and HTTP method |
+| `lw-trigger` | Request event (defaults to `click` or form `submit`; `load` runs on scan); for components, event to defer mounting |
+| `lw-target` | CSS selector for the response target |
+| `lw-swap` | `innerHTML`, `outerHTML`, `prepend`, or `append` |
+| `lw-indicator` | CSS selector for loading indicators |
+| `lw-push-url` | `true`, `false`, or a custom history URL |
+| `lw-component` | Path to a dynamically imported ES module |
+| `lw:state` | JavaScript object expression that initializes local reactive state |
+| `lw:model`, `.live`, `.change`, `.blur` | Bind a form control to a state or global model |
+| `lw:text` | Render an expression as text |
+| `lw:show` | Toggle the element's `hidden` property from an expression |
+| `lw:class` | Add or remove classes reactively from an object expression |
+| `template[lw:for]` | Repeat template contents for an iterable expression; item and index variables are available to bindings |
+| `lw:click`, `lw:input`, `lw:change`, `lw:submit`, `lw:keydown`, `lw:keyup`, `lw:focus`, `lw:blur` | Evaluate an expression in response to an event; supports the modifiers documented above |
+| `litewire.getModel(name)` | Read a global model |
+| `litewire.setModel(name, value)` | Set a global model and update matching bindings |
+**Buy my kids schoolbooks:** [https://paypal.me/justumg](https://paypal.me/justumg)

package/package.json CHANGED Viewed

@@ -1,24 +1,25 @@
 {
   "name": "litewire",
-  "version": "1.0.1",
-  "description": "A lightweight HTML-driven AJAX engine and dynamic ES module component loader.",
-  "main": "src/litewire.js",
-  "module": "src/litewire.js",
+  "version": "1.0.3",
+  "description": "A lightweight HTML-driven request engine with reactive state and dynamic ES module components.",
+  "main": "./litewire.js",
+  "module": "./litewire.js",
+  "browser": "./litewire.js",
   "type": "module",
   "exports": {
-    ".": "./src/litewire.js"
+    ".": "./litewire.js"
   },
   "files": [
-    "src/",
-    "README.md",
-    "LICENSE"
+    "litewire.js",
+    "README.md"
   ],
   "keywords": [
     "ajax",
-    "htmx",
     "html-over-the-wire",
+    "reactive",
     "components",
-    "dom-observer"
+    "javascript",
+    "frontend"
   ],
   "author": "Zainurrahman <languaojs@gmail.com>",
   "license": "MIT",

package/src/litewire.js DELETED Viewed

@@ -1,261 +0,0 @@
-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(/^\/+/, '');
-        let 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');
-            let params = new URLSearchParams();
-            if (form) {
-                params = new URLSearchParams(new FormData(form));
-            } else if (el.name && el.value !== undefined) {
-                params.append(el.name, el.value);
-            }
-            const queryString = params.toString();
-            if (queryString) {
-                url += (url.includes('?') ? '&' : '?') + queryString;
-            }
-        } else {
-            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();
-    }
-}