litewire 1.0.2 → 1.0.4

package/README.MD

@@ -1,20 +1,28 @@
-# Litewire 1.0.2
+# Litewire 1.0.3
 
-Litewire is a browser-side HTML-over-the-wire library. It binds requests and
-reactive behaviors to HTML attributes, swaps server-rendered HTML into the
-page, and can load ES module components on demand.
+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.
+
+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.
 
 ## Contents
 
 - [Install and start](#install-and-start)
+- [End-to-end example](#end-to-end-example)
 - [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)
+- [Troubleshooting](#troubleshooting)
 - [Security considerations](#security-considerations)
 - [API reference](#api-reference)
 
@@ -34,10 +42,10 @@ continues scanning elements added later.
 
 ### Use the npm package
 
-If version 1.0.2 is available from your configured npm registry:
+Install version 1.0.3 from your configured npm registry:
 
 ```sh
-npm install litewire@1.0.2
+npm install litewire@1.0.3
 ```
 
 Import the package from your application's JavaScript entry point:
@@ -66,6 +74,45 @@ and observers.
 Litewire sends a GET request when the button is clicked and replaces the
 contents of `#result` with the response HTML.
 
+## End-to-end example
+
+This example uses an HTML form to submit a search query and swaps the
+server-rendered result into a separate element:
+
+```html
+<form
+  lw-get="/search"
+  lw-target="#search-results"
+  lw-indicator="#search-status"
+>
+  <label>
+    Search
+    <input name="q" type="search" required>
+  </label>
+  <button type="submit">Search</button>
+  <span id="search-status" aria-live="polite">Ready</span>
+</form>
+
+<section id="search-results" aria-live="polite">
+  Enter a query to see results.
+</section>
+```
+
+The browser sends a request like `GET /search?q=...`. The endpoint should
+return an HTML fragment, for example:
+
+```html
+<h2>Results for “tea”</h2>
+<ul>
+  <li>Green tea</li>
+  <li>Black tea</li>
+</ul>
+```
+
+Litewire replaces the contents of `#search-results` with that fragment. The
+new content is scanned for Litewire attributes and any `lw-component` modules
+are loaded. No JSON decoding or client-side template rendering is performed.
+
 ## Configuration
 
 Litewire resolves its base URL in this order:
@@ -160,11 +207,38 @@ the element is scanned:
 <div id="account-summary"></div>
 ```
 
+### Request and form behavior
+
+- A form listens for `submit` by default. Other elements listen for `click`.
+  Set `lw-trigger` to a DOM event name to use another event; `load` runs the
+  request immediately when the element is discovered.
+- A GET request serializes all successful controls in the nearest containing
+  form as URL query parameters. If there is no containing form, a control with
+  a `name` and `value` contributes that one parameter.
+- POST, PUT, and DELETE requests send the nearest containing form as
+  `FormData`. If there is no form, Litewire sends no request body.
+- Litewire checks `response.ok`; a non-success status is treated as a request
+  failure. Successful response bodies are read as text and inserted as HTML.
+  Set the response `Content-Type` appropriately on the server, even though
+  Litewire does not parse it.
+- `lw-target` is resolved with `document.querySelector`. If omitted, the
+  triggering element is the target. Ensure the selector matches the intended
+  element when the response is applied.
+- A trigger and each loading indicator receive the configured loading class
+  while the request is in flight. By default, indicators are descendants with
+  the `litewire-indicator` class; `lw-indicator` can select indicators
+  elsewhere in the document.
+- Request failures are logged to the console and emit `litewire:error` from
+  the trigger. The loading class is removed on both success and failure.
+
+`lw-trigger="load"` is useful for initial content, but avoid putting it on
+large numbers of elements if they would all issue requests at once.
+
 ## Reactive state and bindings
 
-Litewire 1.0.2 adds a small reactive layer using `lw:state`, `lw:model`,
-`lw:text`, `lw:show`, and event-expression attributes. The colon in these
-attribute names is intentional.
+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.
 
 ### Local state
 
@@ -181,9 +255,10 @@ object:
 ```
 
 Assignments and deletions of top-level state properties trigger rendering of
-descendant `lw:text` and `lw:show` bindings owned by 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
+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 }`.
 
 Nested `lw:state` elements establish their own state scope. A binding uses the
@@ -196,10 +271,38 @@ global models instead.
   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.
 
 Expressions are evaluated when the element is first scanned and again when
-their owning local state renders. Global model updates also update matching
-`lw:text` bindings.
+their owning local state renders. Global model updates refresh matching
+`lw:text` bindings and reevaluate global `lw:class` bindings and loops.
+
+### Lists
+
+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>
+```
+
+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()`.
 
 ### Form models
 
@@ -216,18 +319,44 @@ their owning local state renders. Global model updates also update matching
 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`; other controls use their value.
+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`.
 
+For example, a control outside a local state root can populate a global model,
+and a matching text binding can display it:
+
+```html
+<input name="status" lw:model="status" aria-label="Status">
+<p>Current status: <span lw:text="status"></span></p>
+
+<script type="module">
+  import "litewire";
+
+  window.addEventListener("DOMContentLoaded", () => {
+    window.litewire.setModel("status", "Ready");
+  });
+</script>
+```
+
+When setting global models from application code, set them on the initialized
+`window.litewire` instance. `setModel()` updates a `lw:text` binding whose
+expression is exactly that model name, reevaluates global `lw:class` and
+`lw:for` bindings, and dispatches `litewire:model`.
+
 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`.
 
+For example, `lw:model="#live-preview"` copies an input value to the
+`textContent` of the element with that ID. Selector-based models update the
+matching targets; they are not reactive state properties.
+
 ### Event expressions
 
 Supported event attributes are:
@@ -271,14 +400,18 @@ Supported event modifiers:
 | `.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:
+export first, then its first export. If the selected export is a function, it
+is called with the host element and its `data-*` attributes converted to an
+object:
 
 ```html
 <div
@@ -297,7 +430,30 @@ export default class Greeting {
 ```
 
 New components inserted by a swap or added to the document are discovered
-automatically. A given element is mounted only once.
+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
+<button
+  type="button"
+  lw-component="components/widget.js"
+  lw-trigger="click"
+  lw-target="#widget"
+  data-mode="compact"
+>
+  Load widget
+</button>
+<div id="widget"></div>
+```
+
+The module path and `data-*` parameters come from the element carrying
+`lw-component`; `lw-target` is the element passed to the component.
 
 ## HTML swaps and DOM updates
 
@@ -332,11 +488,13 @@ a custom URL as the attribute value:
 </a>
 ```
 
-Litewire stores the URL, target selector, and target HTML in history state.
-When navigating with Back or Forward, it restores cached HTML when the state
-contains a selector and markup and the target still exists. Otherwise it
-attempts to fetch the stored URL. This caches only the selected target's HTML,
-not the complete document or JavaScript state.
+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.
 
 ## Lifecycle events
 
@@ -373,6 +531,19 @@ When this meta tag is present, Litewire adds its token as the
 The server must still validate the token and enforce its own authorization and
 request protections.
 
+## Troubleshooting
+
+| Symptom | Things to check |
+|---|---|
+| The global `window.litewire` is missing | Load Litewire in a browser as a module and check the console for module loading errors. Auto-initialization occurs after the document is ready. |
+| A request does not run | Confirm the element has one of `lw-get`, `lw-post`, `lw-put`, or `lw-delete`. Check its default or configured `lw-trigger` event and whether another handler prevents the event from reaching it. |
+| The server receives no form values | Make sure the trigger is inside the form, or is the form itself. Non-GET requests without a containing form have no body. For GET, a standalone control needs both `name` and `value`. |
+| The request succeeds but the page does not change | Return an HTML fragment, verify `lw-target` matches an element, and check that the selected `lw-swap` behavior is suitable. |
+| A request reports an error | Inspect the browser console and the `litewire:error` event. Litewire treats HTTP statuses outside the 2xx range as failures. |
+| A state binding stays unchanged | Confirm the binding is under the intended `lw:state` root. Replace a top-level state property; nested mutations are not observed. |
+| A component does not mount | Check the module URL, its default or first export, and that the export is a function. For deferred components, verify the triggering event and optional `lw-target` selector. |
+| A directive in newly inserted HTML does not run | Ensure the HTML is inserted through a Litewire swap or added to the observed document body. The observer watches additions under `document.body`. |
+
 ## Security considerations
 
 Litewire inserts response bodies as HTML. Only return trusted or appropriately
@@ -387,18 +558,26 @@ untrusted user input.
 | Attribute / API | Description |
 |---|---|
 | `lw-get`, `lw-post`, `lw-put`, `lw-delete` | Request path and HTTP method |
-| `lw-trigger` | Event name; defaults to `click` or form `submit`; `load` runs immediately |
-| `lw-target` | CSS selector for the response target |
+| `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; for a triggered component, selects the element passed to the component |
 | `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-component` | Path to a dynamically imported ES module; its default export or first export is mounted |
 | `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 |
+| `new Litewire({ baseUrl, loadingClass })` | Construct and initialize an instance with optional configuration |
+
+The browser module exports the `Litewire` class as its default export and
+auto-creates `window.litewire` if that global is not already set. When creating
+a custom instance, set `window.litewire` to a placeholder before importing the
+module if needed to prevent auto-initialization, then assign the instance.
 
 **Buy my kids schoolbooks:** [https://paypal.me/justumg](https://paypal.me/justumg)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "litewire",
-  "version": "1.0.2",
+  "version": "1.0.4",
   "description": "A lightweight HTML-driven request engine with reactive state and dynamic ES module components.",
   "main": "./litewire.js",
   "module": "./litewire.js",