@jxsuite/runtime 6.0.2 → 6.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jxsuite/runtime",
-  "version": "6.0.2",
+  "version": "6.1.0",
   "description": "JSON-native reactive web component runtime",
   "license": "MIT",
   "repository": {
@@ -33,7 +33,7 @@
     "upgrade": "bun update --latest && bun install"
   },
   "dependencies": {
-    "@jxsuite/schema": "^5.1.0",
+    "@jxsuite/schema": "^5.2.0",
     "@vue/reactivity": "3.5.44"
   },
   "devDependencies": {

package/src/runtime.ts

@@ -1163,6 +1163,69 @@ export function setTemplateErrorHandler(
   _templateErrorHandler = handler;
 }
 
+/** Warn about a throwing template, once per source. */
+function warnTemplateError(source: string, error: Error): void {
+  if (!reportedTemplates.has(source)) {
+    reportedTemplates.add(source);
+    console.warn(`jx: template ${JSON.stringify(source)} threw:`, error);
+  }
+}
+
+/** Lookups in flight whose answers can make a throwing template valid (§6.1). */
+let pendingLookups = 0;
+
+/** Each binding still throwing while a lookup is in flight, by its `run`, with its latest throw. */
+const heldTemplateErrors = new Map<() => void, { error: Error; source: string }>();
+
+/** Who {@link lookupsSettled} has yet to answer. */
+const lookupWaiters: (() => void)[] = [];
+
+/**
+ * Hold template warnings until `lookup` and every other lookup in flight have settled.
+ *
+ * `lookup` must write its answer to state before it settles: the write re-runs the bindings waiting
+ * on it, so whatever is still held when the last one settles is a template the data did not fix,
+ * and only that is reported. A lookup its own answer starts is counted before this one is
+ * released.
+ *
+ * @param {Promise<void>} lookup - Never rejects: it reports its own failure
+ */
+function holdTemplateErrorsFor(lookup: Promise<void>): void {
+  pendingLookups += 1;
+  void lookup.finally(() => {
+    pendingLookups -= 1;
+    if (pendingLookups === 0) {
+      /* The console, even if a handler was installed meanwhile: these throws happened outside that
+         handler's render, and Studio's render critic would refuse its page for them. */
+      for (const { error, source } of heldTemplateErrors.values()) {
+        warnTemplateError(source, error);
+      }
+      heldTemplateErrors.clear();
+      for (const wake of lookupWaiters.splice(0)) {
+        wake();
+      }
+    }
+  });
+}
+
+/**
+ * Answers once no lookup the runtime started is in flight (embedding.md §5.2).
+ *
+ * A host whose question is whether a document renders awaits this between `buildScope` and
+ * `renderNode`, so its templates read the data rather than the `null` before it. A lookup can hang,
+ * and this waits for it, so bounding the wait is the host's job.
+ *
+ * @returns {Promise<void>}
+ */
+export function lookupsSettled(): Promise<void> {
+  if (pendingLookups === 0) {
+    return Promise.resolve();
+  }
+  return new Promise((wake) => {
+    lookupWaiters.push(wake);
+  });
+}
+
 /**
  * Run a template binding as an effect that survives its expression throwing.
  *
@@ -1172,7 +1235,8 @@ export function setTemplateErrorHandler(
  * and the throw unwound the whole `renderNode` above it: one early read blanked the page. Caught
  * INSIDE the effect, every dependency read before the throw stays tracked, so the binding re-runs
  * on the change that makes it valid. Until then it shows `fallback`'s answer (nothing written, by
- * default), and the error is reported once per source.
+ * default), and the error is reported once per source, after any lookup in flight has settled: a
+ * template that only needed that lookup's answer is not reported at all.
  *
  * @param {string} source - The template, for the report
  * @param {() => void} run - Evaluates the template and writes it
@@ -1182,12 +1246,15 @@ function bindTemplate(source: string, run: () => void, fallback?: () => void): v
   effect(() => {
     try {
       run();
+      heldTemplateErrors.delete(run);
     } catch (error) {
+      const thrown = error instanceof Error ? error : new Error(String(error));
       if (_templateErrorHandler) {
-        _templateErrorHandler(error instanceof Error ? error : new Error(String(error)), source);
-      } else if (!reportedTemplates.has(source)) {
-        reportedTemplates.add(source);
-        console.warn(`jx: template ${JSON.stringify(source)} threw:`, error);
+        _templateErrorHandler(thrown, source);
+      } else if (pendingLookups > 0) {
+        heldTemplateErrors.set(run, { error: thrown, source });
+      } else {
+        warnTemplateError(source, thrown);
       }
       fallback?.();
     }
@@ -1857,11 +1924,74 @@ export function renderNode(
         el.append(renderNode(child, localState, childOpts));
       }
     }
+  } else if (isTemplateString(kids)) {
+    renderComputedChildren(el, kids, localState, {
+      ...options,
+      _ns: childNs,
+      _path: [...path, "children"],
+    });
   }
 
   return el;
 }
 
+/**
+ * Draw a whole-`children` template, the way the site build's template pass expands one (spec.md
+ * §8.4). This is what an item's or an entry's parsed body looks like to something that renders the
+ * source document rather than the build's output: Studio's Preview, chiefly.
+ *
+ * A result that is not an array draws nothing, because a plain string is not a `children` value.
+ * The children are rendered in a detached scope of their own, replaced when the template's value
+ * changes (a collection that was still loading), and with tracking paused for the reason
+ * {@link renderSwitch} gives: the bindings inside track for themselves.
+ *
+ * @param {Element} el - The element whose children these are
+ * @param {string} template - The `children` value
+ * @param {JxScope} state
+ * @param {JxRenderOptions} options - `_path` is the `children` position of `el`
+ */
+function renderComputedChildren(
+  el: Element,
+  template: string,
+  state: JxScope,
+  options: JxRenderOptions,
+): void {
+  const path = options._path ?? [];
+  let live: EffectScope | null = null;
+  const retire = (): void => {
+    // Detached before it is stopped, for the reason `teardown` in `renderMappedArray` gives.
+    el.replaceChildren();
+    live?.stop();
+    live = null;
+  };
+  bindTemplate(
+    template,
+    () => {
+      const nodes = evaluateValueTemplate(template, state);
+      retire();
+      if (!Array.isArray(nodes)) {
+        return;
+      }
+      const scope = effectScope(true);
+      live = scope;
+      pauseTracking();
+      try {
+        scope.run(() => {
+          /* SAFETY: a children template that yields an array stands for the child list itself, the
+             same reading the site build's template pass gives it. */
+          for (const [i, child] of (nodes as (JxElement | string)[]).entries()) {
+            el.append(renderNode(child, state, { ...options, _path: [...path, i] }));
+          }
+        });
+      } finally {
+        resetTracking();
+      }
+    },
+    retire,
+  );
+  onScopeDispose(() => live?.stop(), true);
+}
+
 // ─── Template string utilities ────────────────────────────────────────────────
 
 /**
@@ -3297,29 +3427,32 @@ export async function resolvePrototype(
             }
           });
 
-          const doFetch = () =>
-            fetch(url, {
-              method: def.method ?? "GET",
-              signal: controller.signal,
-              ...(def.headers && { headers: def.headers }),
-              ...(def.body && {
-                body: isNonNullObject(def.body) ? JSON.stringify(def.body) : def.body,
-              }),
-            })
-              .then((r): Promise<JsonValue> => (r.ok ? r.json() : Promise.reject(r.statusText)))
-              .then((d) => {
-                s.value = d;
+          const doFetch = () => {
+            holdTemplateErrorsFor(
+              fetch(url, {
+                method: def.method ?? "GET",
+                signal: controller.signal,
+                ...(def.headers && { headers: def.headers }),
+                ...(def.body && {
+                  body: isNonNullObject(def.body) ? JSON.stringify(def.body) : def.body,
+                }),
               })
-              .catch((error) => {
-                if (!(error instanceof Error && error.name === "AbortError")) {
-                  s.value = { error: String(error) };
-                }
-              });
+                .then((r): Promise<JsonValue> => (r.ok ? r.json() : Promise.reject(r.statusText)))
+                .then((d) => {
+                  s.value = d;
+                })
+                .catch((error) => {
+                  if (!(error instanceof Error && error.name === "AbortError")) {
+                    s.value = { error: String(error) };
+                  }
+                }),
+            );
+          };
 
           if (debounceMs > 0) {
             debounceTimer = setTimeout(doFetch, debounceMs);
           } else {
-            void doFetch();
+            doFetch();
           }
         });
       }
@@ -3850,24 +3983,25 @@ async function resolveViaDevProxy(def: JxPrototypeDef, state: JxScope, key: stri
 
   // Always wrap in ref for reactivity
   const s: Ref<JxScopeValue> = ref(null);
+  const resolveInto = (resolvedConfig: JxScope) => {
+    holdTemplateErrorsFor(
+      doResolve(resolvedConfig)
+        .then((value) => {
+          s.value = value;
+        })
+        .catch((error) => console.error("Jx dev proxy:", error)),
+    );
+  };
   if (hasTemplates) {
     effect(() => {
       const resolvedConfig: JxScope = {};
       for (const [k, v] of Object.entries(config)) {
         resolvedConfig[k] = isTemplateString(v) ? evaluateTemplate(v, state) : v;
       }
-      doResolve(resolvedConfig)
-        .then((value) => {
-          s.value = value;
-        })
-        .catch((error) => console.error("Jx dev proxy:", error));
+      resolveInto(resolvedConfig);
     });
   } else {
-    doResolve(config)
-      .then((value) => {
-        s.value = value;
-      })
-      .catch((error) => console.error("Jx dev proxy:", error));
+    resolveInto(config);
   }
   return s;
 }
@@ -3900,19 +4034,21 @@ function latestServerCall(
     const n = seq;
     /* The executor runs before the constructor returns, so the call still starts synchronously,
        and a throw inside it rejects this promise instead of escaping to the caller. */
-    new Promise<JsonValue>((settle) => {
-      settle(invoke(args));
-    })
-      .then((result) => {
-        if (n === seq) {
-          s.value = result;
-        }
+    holdTemplateErrorsFor(
+      new Promise<JsonValue>((settle) => {
+        settle(invoke(args));
       })
-      .catch((error) => {
-        if (n === seq) {
-          console.error(label, error);
-        }
-      });
+        .then((result) => {
+          if (n === seq) {
+            s.value = result;
+          }
+        })
+        .catch((error) => {
+          if (n === seq) {
+            console.error(label, error);
+          }
+        }),
+    );
   };
 }