/*! * Statum - client-side state library. * * An HTMX-inspired state layer. The library manages signed "snapshots" of * application state (one per slot type), keeps them fresh via the server's * `transmit_after` / `invalid_after` timestamps, and binds them to the DOM * through `stm-*` attributes. See model.md for the full specification. * * Distribution: a single IIFE that attaches `window.statum` (no dependencies, * no build step). Targets modern evergreen browsers (uses fetch, * BroadcastChannel, queueMicrotask, URLSearchParams, FormData). */ (function () { 'use strict'; /** Content-Type used by every Statum directive response. */ var STATUM_CONTENT_TYPE = 'application/vnd.statum+json'; /** Request/response header carrying one slot's reference (or base64 frame). */ var SLOT_HEADER = 'X-Statum-Slot'; /** Request header carrying an action's opaque `private` blob. */ var PRIVATE_HEADER = 'X-Statum-Private'; /** Session-cookie marker used to detect a fresh browser session. */ var SESSION_COOKIE = '_statum_sdc'; /** BroadcastChannel name used to sync session/device state across tabs. */ var CHANNEL_NAME = 'statum'; /** localStorage / sessionStorage key prefix for persisted frames. */ var STORAGE_PREFIX = 'statum:'; // --------------------------------------------------------------------------- // Configuration // --------------------------------------------------------------------------- /** * Endpoint URLs. These defaults may be overridden per-page with the * `stm-entrypoint` and `stm-slots` attributes on the `` element. * * @type {{entrypointUrl: string, slotsUrl: string}} */ var config = { entrypointUrl: '/_statum/entrypoint', slotsUrl: '/_statum/slots', channelUrl: '/_statum/channel', workerUrl: '/_statum/worker.js' }; // --------------------------------------------------------------------------- // State store // --------------------------------------------------------------------------- /** * In-memory store, keyed by slot type. Each value is `{frame, snapshot}` * where `snapshot` is the parsed `frame.content`. This map is the single * source of truth for rendering; persistent backends merely hydrate it. * * @type {Map} */ var store = new Map(); /** Listeners, keyed by type name. @type {Map>} */ var listeners = new Map(); /** * Idempotency tracking: slot key -> last-applied frame `signature`. Held in * memory only (per tab), so a frame already persisted by another tab still * re-draws a tab whose tracking lags. Entries are dropped on clear so a * replayed frame re-applies. * @type {Map} */ var signatures = new Map(); /** Optional UI handlers (set via `statum.on*Handler`). */ var handlers = { onConfirm: null, onNotify: null, onError: null }; /** @type {BroadcastChannel|null} */ var channel = null; /** Whether {@link init} has already run. */ var initialized = false; // --------------------------------------------------------------------------- // Small utilities // --------------------------------------------------------------------------- /** * Parse an ISO 8601 timestamp to epoch millis, or `undefined`. * @param {string|undefined} s * @returns {number|undefined} */ function parseTime(s) { if (!s) return undefined; var t = new Date(s).getTime(); return isNaN(t) ? undefined : t; } /** * Base64-encode a UTF-8 string (safe for frames containing non-Latin1 data). * @param {string} str * @returns {string} */ function b64encode(str) { var bytes = new TextEncoder().encode(str); var bin = ''; var chunk = 0x8000; for (var i = 0; i < bytes.length; i += chunk) { bin += String.fromCharCode.apply(null, bytes.subarray(i, i + chunk)); } return btoa(bin); } /** Read a cookie value, or `null` if absent. @param {string} name */ function getCookie(name) { var escaped = name.replace(/([.$?*|{}()[\]\\/+^])/g, '\\$1'); var match = document.cookie.match(new RegExp('(?:^|; )' + escaped + '=([^;]*)')); return match ? decodeURIComponent(match[1]) : null; } /** Set a session cookie (no expiry => cleared when the browser closes). */ function setCookie(name, value) { document.cookie = name + '=' + encodeURIComponent(value) + '; path=/; SameSite=Lax'; } // --------------------------------------------------------------------------- // Expression evaluation // --------------------------------------------------------------------------- /** * Compiled-expression cache. Expressions are evaluated as JavaScript against * a scope object (the page's HTML is trusted, per the model). * @type {Map} */ var exprCache = new Map(); /** * Compile (and cache) an expression string into a function of `scope`. * Uses `with` so that arbitrary type names and loop variables are resolved * as bare identifiers. Returns a function that yields `undefined` on any * runtime or compile error. * @param {string} expr * @returns {Function} */ function compileExpr(expr) { var cached = exprCache.get(expr); if (cached !== undefined) return cached; var fn; try { // Function-constructor bodies are non-strict by default, so `with` is // permitted. The inner try/catch turns reference errors into `undefined` // so a missing path simply yields no value. fn = new Function('scope', 'with(scope){try{return (' + expr + ');}catch(e){return undefined;}}'); } catch (e) { fn = function () { return undefined; }; } exprCache.set(expr, fn); return fn; } /** * Evaluate an expression against a scope. * @param {string} expr * @param {object} [scope] * @returns {*} `undefined` if the expression is empty or fails. */ function evalExpr(expr, scope) { if (expr == null || expr === '') return undefined; try { return compileExpr(expr)(scope || {}); } catch (e) { return undefined; } } /** * Build a child scope that inherits the parent (so type bindings remain * visible) and adds one own loop variable. * @param {object} parent * @param {string} name * @param {*} value * @returns {object} */ function childScope(parent, name, value) { var scope = Object.create(parent || null); scope[name] = value; return scope; } // --------------------------------------------------------------------------- // StatumError // --------------------------------------------------------------------------- /** * Error type thrown for HTTP failures and `error` directives. * @param {string} [message] * @param {string} [code] * @param {object} [data] */ function StatumError(message, code, data) { this.name = 'StatumError'; this.message = message || ''; this.code = code || undefined; this.data = data || undefined; } StatumError.prototype = Object.create(Error.prototype); // --------------------------------------------------------------------------- // UI handlers (confirm / notify / error) // --------------------------------------------------------------------------- /** * Run the `notify` directive's default behaviour or the custom * `statum.onNotifyHandler`. The default surfaces the message via `alert()`. * @param {string} [kind] Application-defined category (freeform). * @param {string} [message] */ function triggerNotify(kind, message) { var fn = handlers.onNotify; try { if (fn) fn(kind, message); else if (message != null) window.alert(message); } catch (e) { console.error('[statum] notify handler error', e); } } /** * Run the `stm-confirm` gate: the custom `statum.onConfirmHandler` if set, * otherwise `window.confirm`. Supports async handlers (custom modals). * @param {string} message * @param {HTMLElement} element * @returns {Promise} truthy if the action should proceed. */ async function triggerConfirm(message, element) { var fn = handlers.onConfirm; try { if (fn) return !!(await fn(message, element)); return !!window.confirm(message); } catch (e) { console.error('[statum] confirm handler error', e); return false; } } /** * Run the custom `statum.onErrorHandler`, if set. Returns whether the default * behaviour (promise rejection + `stm-on-error` classes) should proceed: the * handler suppresses the default by returning (or resolving) `false`. * @param {StatumError} error * @param {HTMLElement|null} element * @returns {Promise} */ async function triggerError(error, element) { var fn = handlers.onError; if (!fn) return true; try { var suppress = await fn(error, element); return suppress !== false; } catch (e) { console.error('[statum] error handler error', e); return true; } } /** * Surface a failure: run `triggerError`, and if the default is not * suppressed, apply `stm-on-error` classes (when an origin element exists) * and re-throw so the originating promise rejects. * @param {StatumError} error * @param {HTMLElement|null} element */ async function reportFailure(error, element) { if (await triggerError(error, element)) { if (element) applyErrorClasses(element, true); throw error; } } // --------------------------------------------------------------------------- // Persistence // --------------------------------------------------------------------------- /** * Pick the storage backend for a scope. * @param {string} scope * @returns {Storage|null} `null` for in-memory scopes. */ function storageFor(scope) { if (scope === 'device' || scope === 'session') return localStorage; if (scope === 'flow') return sessionStorage; return null; // page / transient } /** * Persist a slot's frame to the backend matching its scope, removing any * stale copy from the other backend first (in case the scope changed). * @param {string} type * @param {{frame: object, snapshot: object}} entry */ function persistEntry(type, entry) { var scope = entry.snapshot.slot && entry.snapshot.slot.scope; removePersisted(type); var storage = storageFor(scope); if (!storage) return; try { storage.setItem(STORAGE_PREFIX + type, JSON.stringify(entry.frame)); } catch (e) { /* storage full or unavailable; remain in-memory only */ } } /** Remove a persisted frame from both backends. @param {string} type */ function removePersisted(type) { try { localStorage.removeItem(STORAGE_PREFIX + type); } catch (e) {} try { sessionStorage.removeItem(STORAGE_PREFIX + type); } catch (e) {} } /** Load every persisted frame from a backend into the in-memory store. */ function loadFrom(storage) { for (var i = 0; i < storage.length; i++) { var key = storage.key(i); if (!key || key.indexOf(STORAGE_PREFIX) !== 0) continue; try { var frame = JSON.parse(storage.getItem(key)); var snapshot = JSON.parse(frame.content); var type = snapshot.slot && snapshot.slot.type; if (type && !store.has(type)) store.set(type, { frame: frame, snapshot: snapshot }); } catch (e) { /* corrupt entry: ignore */ } } } /** Hydrate the store from localStorage and sessionStorage. */ function hydrate() { try { loadFrom(localStorage); } catch (e) {} try { loadFrom(sessionStorage); } catch (e) {} } // --------------------------------------------------------------------------- // Session-cookie initialization // --------------------------------------------------------------------------- /** * Detect a fresh browser session using the `_statum_sdc` session cookie. * On a fresh session, clear all `session`-scoped persisted frames, then set * the marker. Session cookies are shared across tabs, so a tab opened * mid-session sees the marker and leaves session data intact. */ function initSession() { if (getCookie(SESSION_COOKIE) !== null) return; clearSessionSlotsFromStorage(); setCookie(SESSION_COOKIE, '1'); } /** Remove all `session`-scoped frames from localStorage. */ function clearSessionSlotsFromStorage() { var toRemove = []; for (var i = 0; i < localStorage.length; i++) { var key = localStorage.key(i); if (!key || key.indexOf(STORAGE_PREFIX) !== 0) continue; try { var frame = JSON.parse(localStorage.getItem(key)); var snapshot = JSON.parse(frame.content); if (snapshot.slot && snapshot.slot.scope === 'session') toRemove.push(key); } catch (e) {} } for (var j = 0; j < toRemove.length; j++) localStorage.removeItem(toRemove[j]); } // --------------------------------------------------------------------------- // Listeners & cross-tab broadcast // --------------------------------------------------------------------------- /** * Fire all listeners for a type. (Renamed from `notify` to avoid confusion * with the `notify` directive.) * @param {string} type * @param {object|null} frame * @param {object|null} snapshot */ function fireListeners(type, frame, snapshot) { var set = listeners.get(type); if (!set) return; var event = { type: type, frame: frame, snapshot: snapshot }; set.forEach(function (cb) { try { cb(event); } catch (e) { console.error('[statum] listener error', e); } }); } /** * Broadcast a state change to other tabs. Only `session`/`device` scopes are * shared (flow/page/transient are per-tab). * @param {object} message * @param {string} [scope] */ function broadcast(message, scope) { if (!channel) return; if (scope !== 'session' && scope !== 'device') return; try { channel.postMessage(message); } catch (e) {} } /** * Broadcast a message to other tabs regardless of slot scope. Used to relay * realtime (live) events so they reach every tab, not just session/device * ones. */ function broadcastAlways(message) { if (!channel) return; try { channel.postMessage(message); } catch (e) {} } /** Open the BroadcastChannel and wire inbound messages. */ function setupChannel() { if (typeof BroadcastChannel === 'undefined') return; try { channel = new BroadcastChannel(CHANNEL_NAME); } catch (e) { channel = null; return; } channel.onmessage = function (ev) { var msg = ev.data; if (!msg) return; if (msg.kind === 'set' && msg.frame) { try { var snapshot = JSON.parse(msg.frame.content); var type = snapshot.slot && snapshot.slot.type; if (type && commitSet(msg.frame, snapshot, type, false)) renderAll(); } catch (e) { /* ignore malformed */ } } else if (msg.kind === 'clear') { var t = msg.type; if (!t && msg.key != null) { store.forEach(function (entry, type) { if (entry.snapshot.slot && entry.snapshot.slot.key === msg.key) t = type; }); } if (t) clearType(t, { broadcast: false }); else if (msg.key != null) signatures.delete(msg.key); renderAll(); } }; } // --------------------------------------------------------------------------- // State mutation // --------------------------------------------------------------------------- /** * Remove a type from the store, un-persist it, drop its idempotency entry, * fire listeners, and (optionally) broadcast the clear to other tabs. * @param {string} type * @param {{broadcast?: boolean}} [opts] */ function clearType(type, opts) { var entry = store.get(type); if (!entry) return; var scope = entry.snapshot.slot && entry.snapshot.slot.scope; var key = entry.snapshot.slot && entry.snapshot.slot.key; store.delete(type); removePersisted(type); if (key) signatures.delete(key); fireListeners(type, null, null); if (opts && opts.broadcast) broadcast({ kind: 'clear', key: key, type: type }, scope); } /** * Resolve a slot key to its type and clear it. Used by the `clear` directive * (keyed) and by live `clear` events. * @param {string} key * @param {boolean} [broadcast] */ function clearByKey(key, broadcast) { var typeToRemove = null; store.forEach(function (entry, type) { if (entry.snapshot.slot && entry.snapshot.slot.key === key) typeToRemove = type; }); if (typeToRemove) clearType(typeToRemove, { broadcast: !!broadcast }); else if (key) signatures.delete(key); } /** * Commit a `set` to the in-memory store, persist it, and fire listeners. * Idempotent: if the frame's `signature` matches the last-applied signature * for this slot (tracked in {@link signatures}), nothing happens and `false` * is returned. When `doBroadcast` is true the set is forwarded to other tabs * via the scope-gated broadcast (session/device only). * @param {object} frame * @param {object} snapshot * @param {string} type * @param {boolean} doBroadcast * @returns {boolean} `true` if state changed. */ function commitSet(frame, snapshot, type, doBroadcast) { var key = snapshot.slot && snapshot.slot.key; var sig = frame.signature; if (key && sig !== undefined && signatures.get(key) === sig) return false; var entry = { frame: frame, snapshot: snapshot }; store.set(type, entry); persistEntry(type, entry); fireListeners(type, frame, snapshot); if (key && sig !== undefined) signatures.set(key, sig); if (doBroadcast) { var scope = snapshot.slot && snapshot.slot.scope; broadcast({ kind: 'set', frame: frame }, scope); } return true; } /** * Apply a `set` directive: store/refresh a slot's snapshot (idempotently), * broadcasting to other tabs. * @param {object} directive `{ snapshot_frame }` */ function applySet(directive) { var frame = directive.snapshot_frame; if (!frame || !frame.content) return; var snapshot; try { snapshot = JSON.parse(frame.content); } catch (e) { return; } var type = snapshot.slot && snapshot.slot.type; if (!type) return; commitSet(frame, snapshot, type, true); } /** * Apply a `clear` directive. The directive carries a slot key, so the type * holding that key is resolved and removed. * @param {object} directive `{ key }` */ function applyClear(directive) { if (directive.key == null) return; clearByKey(directive.key, true); } /** * Apply a live `set` event received over the realtime channel. The frame is * committed (idempotently) and, when new, broadcast to sibling tabs via the * scope-agnostic {@link broadcastAlways} so every tab sees it regardless of * which (or how many) tabs hold a subscription. * @param {object} frame */ function applyRemoteSet(frame) { try { var snapshot = JSON.parse(frame.content); var type = snapshot.slot && snapshot.slot.type; if (!type) return; if (commitSet(frame, snapshot, type, false)) { broadcastAlways({ kind: 'set', frame: frame }); renderAll(); } } catch (e) { /* malformed frame */ } } /** Apply a live `clear` event received over the realtime channel. */ function applyRemoteClear(key) { if (key == null) return; signatures.delete(key); clearByKey(key, false); broadcastAlways({ kind: 'clear', key: key }); renderAll(); } // --------------------------------------------------------------------------- // Snapshot freshness & request headers // --------------------------------------------------------------------------- /** * Categorize a held snapshot relative to the current time. * @returns {'silent'|'always'|'invalid'|'stale'|'fresh'} * - `silent`: unidirectional (`transmit_after` undefined) - never sent. * - `always`: `transmit_after === as_at` - send the base64 frame each time. * - `invalid`: past `invalid_after` - drop and refetch. * - `stale`: past `transmit_after` but not yet invalid - pre-flight first. * - `fresh`: still cached server-side - send the `as_at` reference. */ function entryCategory(entry) { var snap = entry.snapshot; var transmit = snap.transmit_after; if (transmit === undefined || transmit === null) return 'silent'; if (transmit === snap.as_at) return 'always'; var now = Date.now(); var invalidAt = parseTime(snap.invalid_after); var transmitAt = parseTime(transmit); if (invalidAt !== undefined && now >= invalidAt) return 'invalid'; if (transmitAt !== undefined && now >= transmitAt) return 'stale'; return 'fresh'; } /** * Drop locally-invalid snapshots and pre-flight any stale ones. Pre-flighting * posts the stale frames to the slot endpoint and applies the returned `set` * directives, refreshing their `as_at` values before the real request runs. * * Single-flight: concurrent callers share one in-flight preparation. * @returns {Promise} */ var preparePromise = null; function prepareSlots() { if (preparePromise) return preparePromise; preparePromise = doPrepareSlots().then(function () { preparePromise = null; }, function () { preparePromise = null; }); return preparePromise; } async function doPrepareSlots() { var stale = []; store.forEach(function (entry, type) { var cat = entryCategory(entry); if (cat === 'invalid') { clearType(type, { broadcast: false }); } else if (cat === 'stale') { stale.push(entry.frame); } }); if (stale.length) { var directives = await postSlots(stale); var pfResult = applyDirectives(directives, { originElement: null }); executeTerminal(pfResult); } } /** * Build the `X-Statum-Slot` header values for every held slot, using the * freshness rules. Assumes {@link prepareSlots} has just run. * @returns {string[]} */ function buildSlotHeaders() { var headers = []; store.forEach(function (entry) { var snap = entry.snapshot; var cat = entryCategory(entry); if (cat === 'silent' || cat === 'invalid') return; if (cat === 'always') { headers.push(b64encode(JSON.stringify(entry.frame))); } else { headers.push('key=' + snap.slot.key + '; as_at=' + snap.as_at); } }); return headers; } /** * Collect the current frames held for the given slot keys, in the order the * keys are first supplied. Used by the `transmit` directive (which forces a * slot's frame to be posted as if its `transmit_after` had elapsed). Keys the * client does not currently hold are skipped. * @param {string[]} keys * @returns {object[]} */ function collectFramesForKeys(keys) { var keySet = Object.create(null); for (var i = 0; i < keys.length; i++) keySet[keys[i]] = true; var frames = []; store.forEach(function (entry) { var key = entry.snapshot.slot && entry.snapshot.slot.key; if (key && keySet[key]) { frames.push(entry.frame); delete keySet[key]; } }); return frames; } // --------------------------------------------------------------------------- // HTTP helpers // --------------------------------------------------------------------------- /** True if a response is a Statum directive response. */ function isStatum(res) { return (res.headers.get('Content-Type') || '').indexOf(STATUM_CONTENT_TYPE) !== -1; } /** * POST an array of frames to the slot endpoint (the pre-flight target) and * return its directive array. This request intentionally carries no slot * headers (it is itself the refresh). * @param {object[]} frames * @returns {Promise} */ async function postSlots(frames) { var headers = new Headers(); headers.set('Accept', STATUM_CONTENT_TYPE); headers.set('Content-Type', 'application/json'); var res = await fetch(config.slotsUrl, { method: 'POST', headers: headers, body: JSON.stringify(frames), credentials: 'same-origin' }); if (!isStatum(res)) return []; try { return await res.json(); } catch (e) { return []; } } /** * Apply the non-terminal directives from a response (set/clear/subscribe/ * unsubscribe/notify/transmit-collection), then `render`. * * Terminal directives (`navigate`, `post`), error directives, and any * transmit/retry intent are collected on the returned result rather than * executed here: {@link handleResponse} performs the asynchronous * transmission (and optional retry) and then runs terminal navigation, so * that a `transmit` with `retry` can re-issue the request before the page is * navigated away. * @param {object[]} directives * @param {{originElement?: HTMLElement}} [ctx] * @returns {{errors: StatumError[], transmitKeys: string[], retry: boolean, navigate: object|null, post: object|null}} */ function applyDirectives(directives, ctx) { var result = { errors: [], transmitKeys: [], retry: false, navigate: null, post: null }; var list = Array.isArray(directives) ? directives : []; for (var i = 0; i < list.length; i++) { var d = list[i]; if (!d || typeof d !== 'object') continue; switch (d.type) { case 'set': applySet(d); break; case 'clear': applyClear(d); break; case 'subscribe': channelSubscribe(d.key); break; case 'unsubscribe': channelUnsubscribe(d.key); break; case 'notify': triggerNotify(d.kind, d.message); break; case 'transmit': if (d.key != null) { if (result.transmitKeys.indexOf(d.key) === -1) result.transmitKeys.push(d.key); if (d.retry) result.retry = true; } break; case 'error': result.errors.push(new StatumError(d.message, d.code, d.data)); break; case 'navigate': result.navigate = d; break; case 'post': result.post = d; break; } } renderAll(); return result; } /** Execute the terminal navigation directives collected by {@link applyDirectives}. */ function executeTerminal(result) { if (result.navigate) doNavigate(result.navigate); if (result.post) doPost(result.post); } /** Execute a `navigate` directive as a full page load. */ function doNavigate(d) { if (d.uri) window.location.href = d.uri; } /** Execute a `post` directive as a real (navigating) form POST. */ function doPost(d) { if (!d.uri) return; var form = document.createElement('form'); form.method = 'POST'; form.action = d.uri; form.style.display = 'none'; var data = d.data || {}; Object.keys(data).forEach(function (name) { var input = document.createElement('input'); input.type = 'hidden'; input.name = name; input.value = data[name] == null ? '' : String(data[name]); form.appendChild(input); }); document.body.appendChild(form); form.submit(); } /** * Handle a fetch response: if it is a Statum response, apply its directives; * otherwise throw on HTTP errors and no-op on other successful responses. * * Directive ordering: non-terminal directives are applied and the page * rendered; then any `transmit` directives force their slot frames to be * posted (applying the directives the slot endpoint returns); then, if a * transmit requested a retry, the originating request (`ctx.retry`) is * re-issued and this response's terminal directives and errors are skipped. * Otherwise terminal navigation runs, then error directives are surfaced. * @param {Response} res * @param {{originElement?: HTMLElement, retry?: Function}} [ctx] */ async function handleResponse(res, ctx) { var el = ctx && ctx.originElement; if (!isStatum(res)) { if (!res.ok) await reportFailure(new StatumError('HTTP ' + res.status), el); return; } var directives; try { directives = await res.json(); } catch (e) { directives = []; } var result = applyDirectives(directives, ctx); if (result.transmitKeys && result.transmitKeys.length) { var frames = collectFramesForKeys(result.transmitKeys); if (frames.length) { var txDirectives = await postSlots(frames); applyDirectives(txDirectives, { originElement: el }); } } if (result.retry && ctx && typeof ctx.retry === 'function') { await ctx.retry(); return; } executeTerminal(result); var errors = result.errors || []; for (var i = 0; i < errors.length; i++) { await reportFailure(errors[i], el); } } // --------------------------------------------------------------------------- // Entrypoint & action requests // --------------------------------------------------------------------------- /** * Fetch the entrypoint for the current URL, applying its directives. Carries * slot headers (and pre-flights) like any other request. The request is * wrapped in an `attempt` closure passed as the response `retry` callback, so * a `transmit` directive with `retry` can re-issue it after transmission. * @returns {Promise} */ function loadEntrypoint() { var attempt = async function () { await prepareSlots(); var headers = new Headers(); headers.set('Accept', STATUM_CONTENT_TYPE); buildSlotHeaders().forEach(function (v) { headers.append(SLOT_HEADER, v); }); var url = config.entrypointUrl + '?uri=' + encodeURIComponent(window.location.href); var res = await fetch(url, { headers: headers, credentials: 'same-origin' }); await handleResponse(res, { originElement: null, retry: attempt }); }; return attempt(); } /** * Perform an action request. * * The request is wrapped in an `attempt` closure passed as the response * `retry` callback, so a `transmit` directive with `retry` can re-issue the * same action after the transmission (rebuilding headers from current state). * * @param {object} action `{ uri, method, private }` * @param {object} [data] Key/value parameters. Encoded as query string for * GET/HEAD, otherwise as `application/x-www-form-urlencoded`. * @param {HTMLElement} [originElement] Element that triggered the action, so * that `stm-on-error` classes can be applied on an `error` directive. * @returns {Promise} Resolves once the request completes and its * directives have run; rejects on HTTP failure or an `error` directive. */ function performAction(action, data, originElement) { var attempt = async function () { await prepareSlots(); var headers = new Headers(); headers.set('Accept', STATUM_CONTENT_TYPE); buildSlotHeaders().forEach(function (v) { headers.append(SLOT_HEADER, v); }); if (action.private) headers.set(PRIVATE_HEADER, action.private); var method = (action.method || 'GET').toUpperCase(); var params = data || {}; var init = { method: method, headers: headers, credentials: 'same-origin' }; var url = action.uri; if (method === 'GET' || method === 'HEAD') { var qs = new URLSearchParams(params).toString(); if (qs) url += (url.indexOf('?') !== -1 ? '&' : '?') + qs; } else { init.body = new URLSearchParams(params).toString(); headers.set('Content-Type', 'application/x-www-form-urlencoded'); } var res; try { res = await fetch(url, init); } catch (networkErr) { await reportFailure(new StatumError('Network error'), originElement); return; } await handleResponse(res, { originElement: originElement, retry: attempt }); }; return attempt(); } // --------------------------------------------------------------------------- // Realtime channel (subscribe/unsubscribe directives) // --------------------------------------------------------------------------- /** * Per-tab fallback engine, used when `SharedWorker` is unavailable. Owns an * `EventSource`, reads the channel id from the first `event: channel`, * reference-counts slot keys within this tab, PATCHes subscription changes, * applies incoming set/clear events (broadcasting them to siblings), and * closes the stream once it has no subscriptions. */ function createFallbackEngine() { var es = null; var channelId = null; var refs = new Map(); // slotKey -> count var pending = { subscribe: [], unsubscribe: [] }; var patchScheduled = false; function openStream() { if (es) return; try { es = new EventSource(config.channelUrl); } catch (e) { es = null; return; } es.addEventListener('channel', function (ev) { channelId = ev.data; flushPatch(); }); es.addEventListener('set', function (ev) { try { applyRemoteSet(JSON.parse(ev.data)); } catch (e) {} }); es.addEventListener('clear', function (ev) { applyRemoteClear(ev.data); }); es.onerror = function () { /* EventSource auto-reconnects */ }; } function closeStream() { if (es) { try { es.close(); } catch (e) {} es = null; } channelId = null; } function schedulePatch() { if (patchScheduled) return; patchScheduled = true; Promise.resolve().then(function () { patchScheduled = false; flushPatch(); }); } function flushPatch() { if (!channelId) return; var sub = pending.subscribe, uns = pending.unsubscribe; if (!sub.length && !uns.length) return; pending = { subscribe: [], unsubscribe: [] }; var body = {}; if (sub.length) body.subscribe = sub; if (uns.length) body.unsubscribe = uns; try { fetch(config.channelUrl + '/' + encodeURIComponent(channelId), { method: 'PATCH', headers: { 'Content-Type': 'application/json' }, credentials: 'same-origin', body: JSON.stringify(body) }).catch(function () {}); } catch (e) {} } return { subscribe: function (key) { var c = refs.get(key) || 0; refs.set(key, c + 1); if (c === 0) { openStream(); pending.subscribe.push(key); schedulePatch(); } }, unsubscribe: function (key) { var c = refs.get(key) || 0; if (c <= 0) return; if (c - 1 <= 0) { refs.delete(key); pending.unsubscribe.push(key); schedulePatch(); if (refs.size === 0) setTimeout(function () { if (refs.size === 0) closeStream(); }, 0); } else { refs.set(key, c - 1); } } }; } /** * Channel manager. Prefers a `SharedWorker` (which owns the single SSE * connection, reference-counts subscriptions across tabs, and relays events * through the cross-tab `BroadcastChannel`); falls back to a per-tab * `EventSource` engine when `SharedWorker` is unavailable or the worker * script fails to load. Tracks the true per-slot subscription count so it can * replay active subscriptions into the fallback on a mid-session switch. */ function createChannelManager() { var port = null; var workerObj = null; var fallback = null; var mode = null; // 'worker' | 'fallback' | null var counts = new Map(); // slotKey -> count (true subscription state) function switchToFallback() { if (mode === 'fallback') return; mode = 'fallback'; port = null; workerObj = null; fallback = createFallbackEngine(); counts.forEach(function (c, key) { for (var i = 0; i < c; i++) fallback.subscribe(key); }); } function ensure() { if (mode !== null) return; if (typeof SharedWorker !== 'undefined') { try { workerObj = new SharedWorker(config.workerUrl); port = workerObj.port; port.start(); port.postMessage({ op: 'init', url: config.channelUrl }); // The worker delivers events via the BroadcastChannel, so nothing is // required on this port beyond command messages. port.onmessage = function () {}; workerObj.onerror = function () { console.warn('[statum] realtime worker failed; falling back to per-tab channel'); switchToFallback(); }; window.addEventListener('pagehide', function () { if (mode === 'worker' && port) { try { port.postMessage({ op: 'disconnect' }); } catch (e) {} } }); mode = 'worker'; return; } catch (e) { workerObj = null; port = null; } } switchToFallback(); } return { subscribe: function (key) { if (key == null) return; ensure(); counts.set(key, (counts.get(key) || 0) + 1); if (mode === 'worker') { try { port.postMessage({ op: 'subscribe', key: key }); } catch (e) {} } else fallback.subscribe(key); }, unsubscribe: function (key) { if (key == null) return; var c = (counts.get(key) || 0) - 1; if (c <= 0) counts.delete(key); else counts.set(key, c); ensure(); if (mode === 'worker') { try { port.postMessage({ op: 'unsubscribe', key: key }); } catch (e) {} } else fallback.unsubscribe(key); } }; } var channelManager = createChannelManager(); function channelSubscribe(key) { channelManager.subscribe(key); } function channelUnsubscribe(key) { channelManager.unsubscribe(key); } // --------------------------------------------------------------------------- // Rendering: loops, conditionals, bindings // --------------------------------------------------------------------------- /** Templates captured from loop holders. @type {WeakMap} */ var templates = new WeakMap(); /** Instance nodes managed by a loop holder. @type {WeakMap} */ var instancesByHolder = new WeakMap(); /** Loop instance nodes; skipped by the render walk (owned by their holder). */ var instanceNodes = new WeakSet(); /** Elements whose `stm-action` has been wired, to avoid double-binding. */ var wired = new WeakSet(); /** * Find a `stm-for-{name}-in` attribute on an element. * @returns {{varName: string, expr: string}|null} */ function getStmFor(el) { var attrs = el.attributes; for (var i = 0; i < attrs.length; i++) { var match = attrs[i].name.match(/^stm-for-(.+)-in$/); if (match) return { varName: match[1], expr: attrs[i].value }; } return null; } /** Remove any `stm-for-*` and `stm-key` attributes from an element. */ function stripLoopAttrs(el) { var toRemove = []; for (var i = 0; i < el.attributes.length; i++) { var name = el.attributes[i].name; if (/^stm-for-(.+)-in$/.test(name) || name === 'stm-key') toRemove.push(name); } toRemove.forEach(function (n) { el.removeAttribute(n); }); } /** * Evaluate an `stm-if` / `stm-else-if` / `stm-else` chain beginning at `el`, * showing the matching branch and hiding the rest. * * Branches are toggled with the `hidden` attribute rather than detached, so * every branch stays in the DOM and is re-evaluated on each render. (Detaching * the `stm-if` element would remove it from the render walk, leaving an * already-attached `stm-else` branch skipped and never refreshed.) * @returns {Element|null} The active branch element (or `null`). */ function handleIfChain(el, scope) { var branches = [{ el: el, expr: el.getAttribute('stm-if') }]; var cur = el.nextElementSibling; while (cur) { if (cur.hasAttribute('stm-else-if')) { branches.push({ el: cur, expr: cur.getAttribute('stm-else-if') }); cur = cur.nextElementSibling; } else if (cur.hasAttribute('stm-else')) { branches.push({ el: cur, expr: null }); break; } else { break; } } var activeEl = null; for (var i = 0; i < branches.length; i++) { var b = branches[i]; if (b.expr === null || !!evalExpr(b.expr, scope)) { activeEl = b.el; break; } } branches.forEach(function (b) { if (b.el === activeEl) b.el.removeAttribute('hidden'); else b.el.setAttribute('hidden', ''); }); return activeEl; } /** Toggle `stm-class.{name}` classes from their predicate expressions. */ function handleClass(el, scope) { var attrs = el.attributes; for (var i = 0; i < attrs.length; i++) { var attr = attrs[i]; if (attr.name.indexOf('stm-class.') === 0) { var cls = attr.name.slice('stm-class.'.length); if (cls && !!evalExpr(attr.value, scope)) el.classList.add(cls); else el.classList.remove(cls); } } } /** * Bind `stm-attribute.{name}`: a boolean result toggles the attribute, any * other defined value sets it, and `undefined` removes it. * * For booleans, prefer the element's IDL property when one exists (e.g. * `checked`, `disabled`, `hidden`) — setting the content attribute is * unreliable for these once the control is "dirty". */ function handleAttribute(el, scope) { var attrs = el.attributes; for (var i = 0; i < attrs.length; i++) { var attr = attrs[i]; if (attr.name.indexOf('stm-attribute.') === 0) { var name = attr.name.slice('stm-attribute.'.length); if (!name) continue; var value = evalExpr(attr.value, scope); if (value === undefined) { el.removeAttribute(name); } else if (typeof value === 'boolean') { if (name in el && typeof el[name] === 'boolean') el[name] = value; else if (value) el.setAttribute(name, ''); else el.removeAttribute(name); } else { el.setAttribute(name, value === null ? '' : String(value)); } } } } /** * Apply `stm-disabled`: when the predicate is truthy, disable the element and * its descendant form controls; otherwise enable them. */ function handleDisabled(el, scope) { if (!el.hasAttribute('stm-disabled')) return; setDisabledCascade(el, !!evalExpr(el.getAttribute('stm-disabled'), scope)); } /** Set the `disabled` attribute on an element and its descendant controls. */ function setDisabledCascade(el, on) { var nodes = [el].concat(Array.prototype.slice.call( el.querySelectorAll('button,input,select,textarea,fieldset'))); nodes.forEach(function (n) { if (on) n.setAttribute('disabled', ''); else n.removeAttribute('disabled'); }); } /** * Bind `stm-text` / `stm-html`. Per the "leave original DOM content" policy, * an unresolved value (`undefined`) leaves the element untouched; otherwise * the value is stringified (`null` becomes the empty string). */ function handleTextHtml(el, scope) { if (el.hasAttribute('stm-text')) { var text = evalExpr(el.getAttribute('stm-text'), scope); if (text !== undefined) el.textContent = text === null ? '' : String(text); } if (el.hasAttribute('stm-html')) { var html = evalExpr(el.getAttribute('stm-html'), scope); if (html !== undefined) el.innerHTML = html === null ? '' : String(html); } } /** * Expand a loop holder: reconcile its instances against the current array. * Keyed loops (`stm-key`) reuse DOM nodes for unchanged keys to preserve * focus/selection/input state; unkeyed loops rebuild wholesale. */ function handleLoop(el, scope) { var info = getStmFor(el); if (!info) return; var template = templates.get(el); if (!template) { template = el.cloneNode(true); stripLoopAttrs(template); templates.set(el, template); } var raw = evalExpr(info.expr, scope); if (raw === undefined) { // No value for the source path yet: clear instances and restore the // server-rendered holder content (progressive enhancement). var prev = instancesByHolder.get(el) || []; prev.forEach(function (n) { n.remove(); }); instancesByHolder.set(el, []); if (el.getAttribute('data-stm-active') === '1') { el.removeAttribute('data-stm-active'); el.removeAttribute('hidden'); } return; } var arr = Array.isArray(raw) ? raw : []; // Activate: hide the holder so only rendered instances are visible. if (el.getAttribute('data-stm-active') !== '1') { el.setAttribute('data-stm-active', '1'); el.setAttribute('hidden', ''); } var keyExpr = el.getAttribute('stm-key'); var next = []; if (keyExpr) { var oldByKey = new Map(); (instancesByHolder.get(el) || []).forEach(function (n) { if (n.__stmKey !== undefined) oldByKey.set(n.__stmKey, n); }); var used = new Set(); arr.forEach(function (item) { var child = childScope(scope, info.varName, item); var key = evalExpr(keyExpr, child); var node = (key !== undefined && !used.has(key)) ? oldByKey.get(key) : undefined; if (node) { used.add(key); processElement(node, child); } else { node = template.cloneNode(true); node.__stmKey = key; instanceNodes.add(node); processElement(node, child); } next.push(node); }); oldByKey.forEach(function (n, key) { if (!used.has(key)) n.remove(); }); } else { (instancesByHolder.get(el) || []).forEach(function (n) { n.remove(); }); arr.forEach(function (item) { var child = childScope(scope, info.varName, item); var node = template.cloneNode(true); instanceNodes.add(node); processElement(node, child); next.push(node); }); } // Place instances in order, immediately after the holder. var ref = el; next.forEach(function (node) { if (node !== ref.nextSibling) ref.parentNode.insertBefore(node, ref.nextSibling); ref = node; }); instancesByHolder.set(el, next); } /** * Process one element's bindings (and recurse). Loop holders are handled by * {@link handleLoop}; `stm-else-if` / `stm-else` are owned by their `stm-if`. */ function processElement(el, scope) { if (getStmFor(el)) { handleLoop(el, scope); return; } if (el.hasAttribute('stm-else-if') || el.hasAttribute('stm-else')) return; if (el.hasAttribute('stm-if')) { var active = handleIfChain(el, scope); if (active) processInner(active, scope); return; } processInner(el, scope); } /** * Collect `stm-def-{name}-as` attributes on an element into a child scope. * Each expression is evaluated against the incoming scope (so the new * variables cannot reference each other within the same element), and the * results are added to a child scope visible to the element and its * descendants. Multiple defs on one element are supported. If there are no * defs, the original scope is returned unchanged. * @param {Element} el * @param {object} scope * @returns {object} */ function applyDefs(el, scope) { var attrs = el.attributes; var child = null; for (var i = 0; i < attrs.length; i++) { var name = attrs[i].name; if (name.indexOf('stm-def-') === 0 && name.slice(-3) === '-as') { var varName = name.slice(8, -3); if (!varName) continue; if (!child) child = Object.create(scope || null); child[varName] = evalExpr(attrs[i].value, scope); } } return child || scope; } /** Bind the non-control-flow attributes and recurse into children. */ function processInner(el, scope) { var s = applyDefs(el, scope); // local definitions: element + descendants el.__stmScope = s; // latest scope, used when an action fires handleClass(el, s); handleAttribute(el, s); handleDisabled(el, s); handleTextHtml(el, s); wireAction(el); render(el, s); } /** * Walk an element's children, processing each. Loop instance nodes are * skipped here (they are owned and processed by their holder). */ function render(root, scope) { if (!root || !root.children) return; // Snapshot the children: processing mutates the DOM (detaching branches, // inserting loop instances) and a live HTMLCollection would shift indices. var children = Array.prototype.slice.call(root.children); for (var i = 0; i < children.length; i++) { var el = children[i]; if (instanceNodes.has(el)) continue; processElement(el, scope); } } /** Re-render the whole document against the current state. */ function renderAll() { try { render(document.body, stateScope()); } catch (e) { console.error('[statum] render error', e); } } // --------------------------------------------------------------------------- // HTML API: actions // --------------------------------------------------------------------------- /** * Collect data for an action trigger: `stm-data-{key}` attributes plus, for a * form, its named inputs. * @param {HTMLElement} el * @returns {object} */ function collectData(el) { var data = {}; var attrs = el.attributes; for (var i = 0; i < attrs.length; i++) { var name = attrs[i].name; if (name.indexOf('stm-data-') === 0) data[name.slice('stm-data-'.length)] = attrs[i].value; } if (el.tagName === 'FORM') { var fd = new FormData(el); fd.forEach(function (value, key) { data[key] = value instanceof File ? value.name : String(value); }); } return data; } /** * Toggle the busy state of an action element: disables the element and its * descendant form controls and applies `stm-busy-class` classes while busy. * * On un-busy the disabled state is not "restored" to a captured snapshot * (that would clobber a `stm-disabled` value that `renderAll` applied during * the response); instead the nodes are re-enabled and `stm-disabled` is * re-evaluated, which re-disables any that should remain disabled. */ function setBusyState(el, busy) { var nodes = [el].concat(Array.prototype.slice.call( el.querySelectorAll('button,input,select,textarea,fieldset'))); var busyClasses = (el.getAttribute('stm-busy-class') || '').split(/\s+/).filter(Boolean); if (busy) { nodes.forEach(function (n) { n.setAttribute('disabled', ''); }); busyClasses.forEach(function (c) { el.classList.add(c); }); } else { nodes.forEach(function (n) { n.removeAttribute('disabled'); }); busyClasses.forEach(function (c) { el.classList.remove(c); }); reapplyDisabled(el); } } /** Re-apply `stm-disabled` to an element and any descendants that carry it. */ function reapplyDisabled(el) { var scope = el.__stmScope || stateScope(); if (el.hasAttribute('stm-disabled')) handleDisabled(el, scope); var scoped = el.querySelectorAll('[stm-disabled]'); Array.prototype.forEach.call(scoped, function (n) { handleDisabled(n, n.__stmScope || scope); }); } /** Apply or remove `stm-on-error` classes on an action element. */ function applyErrorClasses(el, on) { if (!el || !el.hasAttribute || !el.hasAttribute('stm-on-error')) return; var classes = (el.getAttribute('stm-on-error') || '').split(/\s+/).filter(Boolean); classes.forEach(function (c) { on ? el.classList.add(c) : el.classList.remove(c); }); } /** * Wire an element's primary action once. The listener resolves the action * object against the element's latest render scope, so loop instances bind to * their own item. */ function wireAction(el) { if (!el.hasAttribute('stm-action') || wired.has(el)) return; wired.add(el); var eventName = el.tagName === 'FORM' ? 'submit' : 'click'; el.addEventListener(eventName, function (event) { event.preventDefault(); runElementAction(el); }); } /** * Resolve and perform the action attached to an element, managing busy and * error-state classes around the request. * @param {HTMLElement} el */ async function runElementAction(el) { var scope = el.__stmScope || stateScope(); var action = evalExpr(el.getAttribute('stm-action'), scope); if (!action || typeof action.uri !== 'string') return; // stm-confirm: gate the action behind the confirm handler (async-capable, // so custom modals are supported). if (el.hasAttribute('stm-confirm')) { var confirmed = await triggerConfirm(el.getAttribute('stm-confirm'), el); if (!confirmed) return; } applyErrorClasses(el, false); // clear error state on a new attempt var data = collectData(el); setBusyState(el, true); try { await performAction(action, data, el); } catch (err) { // Already handled: stm-on-error classes and the onErrorHandler run inside // performAction/reportFailure. Swallow so an HTML-triggered action does // not surface as an unhandled rejection. } finally { setBusyState(el, false); } } // --------------------------------------------------------------------------- // Boot visibility (stm-preloader / stm-content) // --------------------------------------------------------------------------- /** * Toggle pre/post-entrypoint visibility with the `hidden` attribute. While * loading, `stm-preloader` elements are shown and `stm-content` elements * hidden; once ready, the reverse. * * To avoid a flash of un-bound template before the script runs, authors may * pre-set `hidden` directly on `stm-content` in the HTML (e.g. * `