@webjsdev/core 0.7.10 → 0.7.11

package/index-browser.js

@@ -44,10 +44,14 @@ export {
 } from './src/serialize.js';
 export { enableClientRouter, disableClientRouter, navigate, revalidate } from './src/router-client.js';
 export { WebjsFrame } from './src/webjs-frame.js';
+export { WebjsStream, renderStream } from './src/webjs-stream.js';
 
 // Signals (TC39 Stage-1 shape), also available via '@webjsdev/core/signals'
 export { signal, computed, effect, batch, isSignal, Signal } from './src/signal.js';
 
+// Optimistic-mutation helper (thin signal wrapper, rolls back on failure)
+export { optimistic } from './src/optimistic.js';
+
 // Directives, also available via '@webjsdev/core/directives'. The full
 // lit-html-parity set is re-exported here so the dist browser bundle (which
 // the `@webjsdev/core/directives` subpath collapses onto in dist mode) carries

package/index.d.ts

@@ -77,3 +77,12 @@ export function navigate(url: Route, opts?: { replace?: boolean }): Promise<void
 export { unsafeHTML, isUnsafeHTML, live, isLive } from './src/directives.js';
 export { createContext, ContextProvider, ContextConsumer, ContextRequestEvent } from './src/context.js';
 export { Task, TaskStatus } from './src/task.js';
+
+// Optimistic-mutation helper: set a signal to an expected value immediately,
+// run the action, roll back on a thrown error or a `{ success: false }`
+// ActionResult, keep the value on success. Returns the action's result.
+export function optimistic<T, R>(
+  signal: { get(): T; set(v: T): void },
+  value: T,
+  action: () => Promise<R> | R,
+): Promise<R>;

package/index.js

@@ -26,10 +26,14 @@ export {
 } from './src/serialize.js';
 export { enableClientRouter, disableClientRouter, navigate, revalidate } from './src/router-client.js';
 export { WebjsFrame } from './src/webjs-frame.js';
+export { WebjsStream, renderStream } from './src/webjs-stream.js';
 
 // Signals (TC39 Stage-1 shape), also available via '@webjsdev/core/signals'
 export { signal, computed, effect, batch, isSignal, Signal } from './src/signal.js';
 
+// Optimistic-mutation helper (thin signal wrapper, rolls back on failure)
+export { optimistic } from './src/optimistic.js';
+
 // Directives, also available via '@webjsdev/core/directives'. The full
 // lit-html-parity set is re-exported so the bare specifier exposes the same
 // directive surface in Node as the browser bundle does.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webjsdev/core",
-  "version": "0.7.10",
+  "version": "0.7.11",
   "type": "module",
   "description": "webjs core runtime - html/css tags, WebComponent base, isomorphic renderers",
   "types": "./index.d.ts",

package/src/lazy-loader.js

@@ -105,3 +105,59 @@ function onIntersect(entries) {
     observer?.unobserve(entry.target);
   }
 }
+
+/* ====================================================================
+ * Per-element viewport observation (shared with <webjs-frame loading="lazy">)
+ * ==================================================================== */
+
+/**
+ * A separate IntersectionObserver keyed by ELEMENT (not by tag) so a single
+ * element can fire a one-shot callback when it scrolls into view. Reuses the
+ * same `rootMargin: '200px'` warm-up budget as the tag-based lazy-component
+ * observer above, so a `<webjs-frame loading="lazy">` self-loads with the same
+ * timing as a `static lazy = true` component module.
+ *
+ * @type {IntersectionObserver | null}
+ */
+let elementObserver = null;
+
+/** @type {WeakMap<Element, () => void>} element → its one-shot callback */
+const elementCallbacks = new WeakMap();
+
+/** @param {IntersectionObserverEntry[]} entries */
+function onElementIntersect(entries) {
+  for (const entry of entries) {
+    if (!entry.isIntersecting) continue;
+    const cb = elementCallbacks.get(entry.target);
+    elementCallbacks.delete(entry.target);
+    elementObserver?.unobserve(entry.target);
+    if (cb) cb();
+  }
+}
+
+/**
+ * Fire `callback` once when `el` first enters the viewport (within the
+ * shared 200px margin). When IntersectionObserver is unavailable (very old
+ * browser, or a non-DOM test env) the callback fires immediately, so a lazy
+ * frame still self-loads rather than staying blank. Returns a teardown that
+ * stops observing (the frame calls it on disconnect / a `src` change).
+ *
+ * @param {Element} el
+ * @param {() => void} callback
+ * @returns {() => void}  Teardown that unobserves `el`.
+ */
+export function observeViewportOnce(el, callback) {
+  if (typeof IntersectionObserver === 'undefined') {
+    callback();
+    return () => {};
+  }
+  if (!elementObserver) {
+    elementObserver = new IntersectionObserver(onElementIntersect, { rootMargin: '200px' });
+  }
+  elementCallbacks.set(el, callback);
+  elementObserver.observe(el);
+  return () => {
+    elementCallbacks.delete(el);
+    elementObserver?.unobserve(el);
+  };
+}

package/src/optimistic.js

@@ -0,0 +1,64 @@
+/**
+ * `optimistic(signal, value, action)`, a thin optimistic-mutation helper.
+ *
+ * The optimistic-UI pattern: show the expected result of a mutation
+ * IMMEDIATELY (so the interface feels instant), run the real server action,
+ * and roll the optimistic value back if the action fails. This wrapper does
+ * exactly that and nothing more, no state machine, no extra reactivity, just
+ * the existing signal primitive plus a try / envelope check.
+ *
+ *   import { signal, optimistic } from '@webjsdev/core';
+ *   import { likePost } from '../actions/like-post.server.js';
+ *
+ *   const liked = signal(false);
+ *   // In an @click handler:
+ *   await optimistic(liked, true, () => likePost(postId));
+ *   // `liked` flips to true instantly; if likePost throws or returns
+ *   // { success: false }, it rolls back to its prior value.
+ *
+ * Behaviour:
+ *   1. Capture `prev = signal.get()`.
+ *   2. `signal.set(value)` so the UI updates before the round-trip.
+ *   3. `await action()`.
+ *   4a. The action THROWS  -> `signal.set(prev)` (rollback) + re-throw.
+ *   4b. The action returns an ActionResult FAILURE envelope
+ *       (`result && result.success === false`) -> `signal.set(prev)`
+ *       (rollback) + return the result (the caller reads its
+ *       `error` / `fieldErrors`).
+ *   4c. SUCCESS (anything else) -> keep the optimistic value + return the
+ *       result. The caller can reconcile to the authoritative value from the
+ *       returned result if it wants to (e.g. `signal.set(result.data.count)`).
+ *
+ * It rolls back on a thrown error OR a `{ success: false }` ActionResult, and
+ * never rolls back on success. Client-only: it mutates a signal (client work),
+ * so a component importing it is never elided as display-only.
+ *
+ * @template T
+ * @param {{ get: () => T, set: (v: T) => void }} signal  A webjs signal.
+ * @param {T} value  The optimistic value to show immediately.
+ * @param {() => Promise<any> | any} action  The server-action call (or any
+ *   thunk returning a Promise / value).
+ * @returns {Promise<any>}  The action's result. On a `{ success: false }`
+ *   envelope the rolled-back result is returned (not thrown); a thrown action
+ *   re-throws after rollback.
+ */
+export async function optimistic(signal, value, action) {
+  const prev = signal.get();
+  signal.set(value);
+  let result;
+  try {
+    result = await action();
+  } catch (err) {
+    // The action rejected: roll the optimistic value back and let the caller
+    // handle the error (re-throw, do not swallow).
+    signal.set(prev);
+    throw err;
+  }
+  // ActionResult FAILURE envelope: a `{ success: false }` is a handled
+  // failure, not a throw. Roll back and hand the result back so the caller
+  // can read its `error` / `fieldErrors`.
+  if (result && result.success === false) {
+    signal.set(prev);
+  }
+  return result;
+}

package/src/render-client.js

@@ -37,8 +37,12 @@ import {
  *   - Event listeners are attached once and retargeted when the handler
  *     reference changes (swap-in-place via a dispatch closure, so `addEventListener`
  *     isn't churned every render).
- *   - This is a conservative implementation; no keyed list diffing yet: array
- *     changes rebuild the whole text part.
+ *   - A plain `.map()` array reconciles POSITIONALLY (non-keyed), matching
+ *     lit-html: each index updates its item instance in place when the
+ *     template shape is unchanged, so DOM node identity (and the focus,
+ *     selection, scroll, and in-progress native drag it carries) survives an
+ *     item-level update. See `reconcileArray`. Keyed reordering still needs
+ *     the `repeat()` directive.
  */
 
 /** @type {WeakMap<TemplateStringsArray | string[], { templateEl: HTMLTemplateElement, parts: PartDescriptor[] }>} */
@@ -911,12 +915,35 @@ function applyChildInner(part, value) {
     return;
   }
 
+  // Plain array (a `.map()` / list interpolation): positional, non-keyed
+  // reconciliation. Update each position's instance IN PLACE when its
+  // template shape is unchanged, so DOM node identity survives an item
+  // update (focus, selection, scroll, and an in-progress native drag all
+  // survive). Mirrors lit-html's non-keyed array child part. Without this,
+  // flipping one item's binding rebuilt the WHOLE list and detached every
+  // node, which cancels a native drag mid-gesture. Use `repeat()` for keyed
+  // reordering.
+  if (Array.isArray(value)) {
+    if (part.child && /** @type any */ (part.child).kind === 'array') {
+      reconcileArray(part, value);
+      return;
+    }
+    teardownChild(part);
+    const arrState = { kind: 'array', items: [] };
+    part.child = arrState;
+    applyArrayFresh(marker, /** @type any */ (arrState), value);
+    return;
+  }
+
   // Remove previously rendered nodes between marker and its next sibling we own.
   if (part.child) {
     const c = /** @type any */ (part.child);
     if (c.kind === 'repeat') {
       teardownRepeat(c);
       part.child = undefined;
+    } else if (c.kind === 'array') {
+      teardownArray(/** @type any */ (c));
+      part.child = undefined;
     } else if (c.kind === 'async-stream') {
       teardownAsyncStream(c);
       part.child = undefined;
@@ -966,29 +993,6 @@ function applyChildInner(part, value) {
     return;
   }
 
-  if (Array.isArray(value)) {
-    const list = [];
-    for (const v of value) {
-      if (isTemplate(v)) {
-        // Create an inline instance. No keyed reconciliation yet.
-        const tr = /** @type any */ (v);
-        const { templateEl, parts } = compile(tr);
-        const frag = /** @type DocumentFragment */ (templateEl.content.cloneNode(true));
-        const bound = parts.map((p) => bindPart(p, frag));
-        for (let i = 0; i < tr.values.length; i++) {
-          applyPart(bound[i], tr.values[i], undefined, tr.values);
-        }
-        list.push(...frag.childNodes);
-      } else if (v != null && v !== false && v !== true) {
-        list.push(document.createTextNode(String(v)));
-      }
-    }
-    const frag = nodesToFrag(list);
-    marker.parentNode?.insertBefore(frag, marker);
-    part.child = list;
-    return;
-  }
-
   const node = document.createTextNode(String(value));
   marker.parentNode?.insertBefore(node, marker);
   part.child = [node];
@@ -1150,6 +1154,151 @@ function teardownRepeat(state) {
   state.map.clear();
 }
 
+/* ================================================================
+ * Plain array (.map) support: positional, non-keyed reconciliation
+ * ================================================================ */
+
+/**
+ * One rendered slot of a plain array. A `tpl` carries a detached template
+ * instance (bookended by its own markers), a `text` carries a single text
+ * node, and an `empty` slot (a nullish / boolean element) renders nothing
+ * but still holds the position so index-based reconciliation stays aligned.
+ * @typedef {{ type: 'tpl', inst: TemplateInstance } | { type: 'text', node: Text } | { type: 'empty' }} ArrayItem
+ */
+
+/** @param {ArrayItem} item @returns {ChildNode | null} */
+function arrayItemFirstNode(item) {
+  if (item.type === 'tpl') return item.inst.startNode;
+  if (item.type === 'text') return item.node;
+  return null;
+}
+
+/** @param {ArrayItem} item */
+function removeArrayItem(item) {
+  if (item.type === 'tpl') {
+    disposeInstance(item.inst);
+    removeBetween(item.inst.startNode, item.inst.endNode);
+  } else if (item.type === 'text') {
+    item.node.parentNode?.removeChild(item.node);
+  }
+}
+
+/**
+ * Build the slot for one array element, plus the fragment to insert (null
+ * for an empty slot). A TemplateResult becomes a detached instance, a
+ * primitive becomes a text node, and nullish / boolean renders nothing.
+ * @param {unknown} v
+ * @returns {{ item: ArrayItem, frag: Node | null }}
+ */
+function buildArrayItem(v) {
+  if (isTemplate(v)) {
+    const { inst, frag } = buildDetached(/** @type any */ (v));
+    return { item: { type: 'tpl', inst }, frag };
+  }
+  if (v != null && v !== false && v !== true) {
+    const node = document.createTextNode(String(v));
+    return { item: { type: 'text', node }, frag: node };
+  }
+  return { item: { type: 'empty' }, frag: null };
+}
+
+/**
+ * Initial render of a plain array: insert every slot's nodes before the marker.
+ * @param {Comment} marker
+ * @param {{ kind: 'array', items: ArrayItem[] }} state
+ * @param {unknown[]} value
+ */
+function applyArrayFresh(marker, state, value) {
+  const parent = marker.parentNode;
+  if (!parent) return;
+  const bulk = document.createDocumentFragment();
+  /** @type {ArrayItem[]} */
+  const items = [];
+  for (const v of value) {
+    const { item, frag } = buildArrayItem(v);
+    if (frag) bulk.appendChild(frag);
+    items.push(item);
+  }
+  parent.insertBefore(bulk, marker);
+  state.items = items;
+}
+
+/**
+ * Positional (non-keyed) reconciliation. For each index, update the slot
+ * in place when its shape is unchanged (preserving DOM node identity),
+ * otherwise replace it; grow or shrink at the tail. There is no key
+ * matching, so a reorder reduces to a series of in-place value updates;
+ * reach for `repeat()` when element identity must follow a moved key.
+ * @param {Extract<BoundPart, {kind:'child'}>} part
+ * @param {unknown[]} value
+ */
+function reconcileArray(part, value) {
+  const marker = part.marker;
+  const parent = marker.parentNode;
+  if (!parent) return;
+  const state = /** @type {{ kind: 'array', items: ArrayItem[] }} */ (part.child);
+  const old = state.items;
+  /** @type {ArrayItem[]} */
+  const next = [];
+
+  for (let i = 0; i < value.length; i++) {
+    const v = value[i];
+    const o = old[i];
+    if (isTemplate(v)) {
+      const tr = /** @type any */ (v);
+      if (o && o.type === 'tpl' && o.inst.strings === tr.strings) {
+        updateInstance(o.inst, tr.values);
+        next.push(o);
+        continue;
+      }
+    } else if (v != null && v !== false && v !== true) {
+      if (o && o.type === 'text') {
+        const str = String(v);
+        if (o.node.data !== str) o.node.data = str;
+        next.push(o);
+        continue;
+      }
+    } else {
+      // Empty slot: drop any prior nodes that occupied this position.
+      if (o) removeArrayItem(o);
+      next.push({ type: 'empty' });
+      continue;
+    }
+    // Shape changed, or the array grew past the old length. Build fresh,
+    // insert at this position (before the current / next still-attached
+    // old node, else the marker), then drop the old slot it replaced.
+    const { item, frag } = buildArrayItem(v);
+    if (frag) parent.insertBefore(frag, nextArrayAnchor(old, i, marker));
+    if (o) removeArrayItem(o);
+    next.push(item);
+  }
+
+  // Shrink: remove slots beyond the new length.
+  for (let i = value.length; i < old.length; i++) removeArrayItem(old[i]);
+  state.items = next;
+}
+
+/**
+ * The node a freshly-built slot at index `i` inserts before: the first
+ * node of the current or next still-attached old slot, else the part
+ * marker (a tail append).
+ * @param {ArrayItem[]} old @param {number} i @param {Comment} marker
+ * @returns {ChildNode}
+ */
+function nextArrayAnchor(old, i, marker) {
+  for (let j = i; j < old.length; j++) {
+    const f = arrayItemFirstNode(old[j]);
+    if (f && f.parentNode) return f;
+  }
+  return marker;
+}
+
+/** @param {{ kind: 'array', items: ArrayItem[] }} state */
+function teardownArray(state) {
+  for (const it of state.items) removeArrayItem(it);
+  state.items = [];
+}
+
 /**
  * Collect [start .. end] (inclusive) and insert immediately before `anchor`.
  * Browsers treat insertBefore of an already-connected node as a move and
@@ -1208,6 +1357,8 @@ function teardownChild(part) {
   const c = /** @type any */ (part.child);
   if (c.kind === 'repeat') {
     teardownRepeat(c);
+  } else if (c.kind === 'array') {
+    teardownArray(c);
   } else if (c.kind === 'async-stream') {
     teardownAsyncStream(c);
   } else if ('strings' in c) {