@jxsuite/runtime 0.28.4 → 0.29.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jxsuite/runtime",
-  "version": "0.28.4",
+  "version": "0.29.0",
   "description": "JSON-native reactive web component runtime",
   "license": "MIT",
   "repository": {
@@ -23,12 +23,13 @@
   },
   "scripts": {
     "build": "bun build ./src/runtime.ts --outdir dist --target browser --sourcemap=linked",
+    "build:metafile": "bun build ./src/runtime.ts --outdir dist --target browser --sourcemap=linked --metafile=metafile.json",
     "test": "bun test --isolate",
     "test:coverage": "bun test --isolate --coverage",
     "upgrade": "bunx npm-check-updates -u && bun install"
   },
   "dependencies": {
-    "@jxsuite/schema": "^0.28.4",
+    "@jxsuite/schema": "^0.29.0",
     "@vue/reactivity": "^3.5.38"
   },
   "devDependencies": {

package/src/expression.ts

@@ -139,7 +139,7 @@ function resolveExprRef(ref: string, state: JxScope, event: Event | null, iterCt
     } else if (key === "index") {
       base = iterCtx?.index ?? map?.index ?? state["$map/index"];
     } else {
-      base = map?.[key] ?? state[`$map/${key}`];
+      base = map?.[key!] ?? state[`$map/${key}`];
     }
     return parts.length > 2 ? getPath(base, parts.slice(2).join("/")) : base;
   }
@@ -167,7 +167,7 @@ function resolveExprRef(ref: string, state: JxScope, event: Event | null, iterCt
 function resolveWritableRef(
   ref: string,
   state: JxScope,
-  event: Event | null,
+  _event: Event | null,
   iterCtx?: IterCtx,
 ): { obj: JxScope; key: string } {
   if (ref.startsWith("$map/")) {
@@ -180,7 +180,7 @@ function resolveWritableRef(
     } else if (key === "index") {
       base = iterCtx?.index ?? map?.index ?? state["$map/index"];
     } else {
-      base = map?.[key] ?? state[`$map/${key}`];
+      base = map?.[key!] ?? state[`$map/${key}`];
     }
     if (parts.length > 2) {
       const pathParts = parts.slice(2);

package/src/runtime.ts

@@ -13,7 +13,15 @@
  * @module jx
  */
 
-import { computed, effect, isRef, onEffectCleanup, reactive, ref } from "@vue/reactivity";
+import {
+  computed,
+  effect,
+  effectScope,
+  isRef,
+  onEffectCleanup,
+  reactive,
+  ref,
+} from "@vue/reactivity";
 import { evaluateExpression, isMutating } from "./expression.ts";
 import type { DynamicClass, JxEventHandler, JxPath, JxRenderOptions, JxScope } from "./types.ts";
 import {
@@ -81,7 +89,7 @@ export async function Jx(
   const state = await buildScope(doc, {}, base);
   target.append(renderNode(doc, state, options));
   if (typeof state.onMount === "function") {
-    state.onMount(state);
+    (state.onMount as (s: JxScope) => unknown)(state);
   }
   return state;
 }
@@ -300,16 +308,31 @@ export { hasSchemaKeywords };
  * @param {JxScope} state
  * @returns {string}
  */
-function evaluateTemplate(str: string, state: JxScope) {
+function evaluateTemplate(str: string, state: JxScope): string {
   const $map = state?.$map as { item?: unknown; index?: number } | undefined;
-  const fn = new Function("state", "$map", "item", "index", `return \`${str}\``);
+  const fn = new Function("state", "$map", "item", "index", `return \`${str}\``) as (
+    state: JxScope,
+    $map: unknown,
+    item: unknown,
+    index: number | undefined,
+  ) => string;
   return fn(state, $map, $map?.item, $map?.index);
 }
 
 // ─── Step 2b: Function resolution (Shape 4) ─────────────────────────────────
 
+/** Shape of a dynamically imported module: named exports plus an optional default. */
+type ImportedModule = Record<string, unknown> & { default?: Record<string, unknown> };
+
+/** Minimal contract an externally-imported resolver class may implement. */
+interface ExternalClassInstance {
+  value?: unknown;
+  resolve?: () => unknown;
+  subscribe?: (cb: (newVal: unknown) => void) => void;
+}
+
 /** Module cache for $src imports (shared with external class resolution). */
-const _moduleCache = new Map();
+const _moduleCache = new Map<string, ImportedModule>();
 
 /**
  * Resolve a $prototype: "Function" entry into a function or computed.
@@ -337,11 +360,11 @@ async function resolveFunction(def: JxFunctionDef, state: JxScope, key: string,
     return noop;
   }
 
-  let fn;
+  let fn: ((...args: unknown[]) => unknown) | undefined;
 
   if (def.body) {
     const params = resolveParamNames(def);
-    fn = new Function(...params, def.body);
+    fn = new Function(...params, def.body) as (...args: unknown[]) => unknown;
     Object.defineProperty(fn, "name", {
       configurable: true,
       value: def.name ?? key,
@@ -353,26 +376,27 @@ async function resolveFunction(def: JxFunctionDef, state: JxScope, key: string,
       throw new Error(`Jx: '${key}' has neither body nor $src`);
     }
     const exportName = def.$export ?? key;
-    let mod;
+    let mod: ImportedModule;
     if (_moduleCache.has(src)) {
-      mod = _moduleCache.get(src);
+      mod = _moduleCache.get(src)!;
     } else {
       if (base) {
         const resolvedSrc = new URL(src, base).href;
         try {
-          mod = await import(resolvedSrc);
+          mod = (await import(resolvedSrc)) as ImportedModule;
         } catch {
-          mod = await import(src);
+          mod = (await import(src)) as ImportedModule;
         }
       } else {
-        mod = await import(src);
+        mod = (await import(src)) as ImportedModule;
       }
       _moduleCache.set(src, mod);
     }
-    fn = mod[exportName] ?? mod.default?.[exportName];
-    if (typeof fn !== "function") {
+    const candidate = mod[exportName] ?? mod.default?.[exportName];
+    if (typeof candidate !== "function") {
       throw new TypeError(`Jx: export "${exportName}" not found or not a function in "${src}"`);
     }
+    fn = candidate as (...args: unknown[]) => unknown;
   }
 
   // Detect computed: body contains a return statement, or $src function introspection.
@@ -475,11 +499,11 @@ export function renderNode(
   }
 
   // Extend scope with any $-prefixed local bindings declared on this node
-  let localState = state;
+  let localState: JxScope = state;
   for (const [key, val] of Object.entries(def)) {
     if (key.startsWith("$") && !RESERVED_KEYS.has(key)) {
       if (localState === state) {
-        localState = Object.create(state);
+        localState = Object.create(state) as JxScope;
       }
       localState[key] = isRefObj(val) ? resolveRef(val.$ref, state) : val;
     }
@@ -500,14 +524,11 @@ export function renderNode(
   if (def.$switch) {
     return renderSwitch(def, localState, options);
   }
-  if (isMappedArray(def.children)) {
-    return renderMappedArray(def, def.children, localState, options);
-  }
 
   const el = document.createElement(tagName);
 
   if (options?.onNodeCreated) {
-    options.onNodeCreated(el, path, def);
+    options.onNodeCreated(el, path, def, localState);
   }
 
   applyProperties(el, def, localState);
@@ -519,10 +540,23 @@ export function renderNode(
   );
   applyAttributes(el, def.attributes ?? {}, localState);
 
-  const children = Array.isArray(def.children) ? def.children : [];
-  for (let i = 0; i < children.length; i++) {
-    const childOpts = options ? { ...options, _path: [...path, "children", i] } : undefined;
-    el.append(renderNode(children[i], localState, childOpts));
+  const kids = def.children;
+  if (isMappedArray(kids)) {
+    // Legacy whole-children repeater: the items render directly into `el` (which keeps its own
+    // TagName, e.g. <ul>), with no extra wrapper element.
+    const arrOpts = options ? { ...options, _path: [...path, "children"] } : undefined;
+    renderMappedArrayInto(el, kids, localState, arrOpts);
+  } else if (Array.isArray(kids)) {
+    for (let i = 0; i < kids.length; i++) {
+      const child = kids[i]!;
+      const childOpts = options ? { ...options, _path: [...path, "children", i] } : undefined;
+      if (isMappedArray(child)) {
+        // Array pseudo-element among siblings: expand inline, no wrapper.
+        renderMappedArrayInto(el, child, localState, childOpts);
+      } else {
+        el.append(renderNode(child, localState, childOpts));
+      }
+    }
   }
 
   return el;
@@ -562,14 +596,15 @@ function applyProperties(el: HTMLElement, def: JxElement, state: JxScope) {
         const handler = resolveRef(val.$ref, state);
         if (typeof handler === "function") {
           const scope = state;
-          el.addEventListener(key.slice(2), (e) => handler(scope, e));
+          const handlerFn = handler as (s: JxScope, e: Event) => unknown;
+          el.addEventListener(key.slice(2), (e) => handlerFn(scope, e));
         }
         continue;
       }
       // Event handler: inline $prototype: "Function"
       if (isFunctionDef(val) && val.body) {
         const params = resolveParamNames(val);
-        const fn = new Function(...params, val.body);
+        const fn = new Function(...params, val.body) as (s: JxScope, e: Event) => unknown;
         const scope = state;
         el.addEventListener(key.slice(2), (e) => fn(scope, e));
         continue;
@@ -781,7 +816,40 @@ export function applyStyle(
 
   const tag = document.createElement("style");
   tag.textContent = css;
+  tag.dataset.jxOwner = uid;
   document.head.append(tag);
+  elementStyleTags.set(el, tag);
+}
+
+/**
+ * Scoped <style> tags emitted per element by applyStyle (latest wins). Lets callers replace an
+ * element's emitted styles instead of accumulating orphaned tags.
+ */
+export const elementStyleTags = new WeakMap<HTMLElement, HTMLStyleElement>();
+
+/**
+ * Re-apply an element's style definition in place: removes the previously emitted scoped <style>
+ * tag (if any), clears inline styles, and applies the new definition.
+ *
+ * @param {HTMLElement} el
+ * @param {JxStyle | undefined} styleDef
+ * @param {Record<string, string>} [mediaQueries]
+ * @param {JxScope} [state]
+ */
+export function reapplyStyle(
+  el: HTMLElement,
+  styleDef: JxStyle | undefined,
+  mediaQueries: Record<string, string> = {},
+  state: JxScope = {},
+) {
+  const prev = elementStyleTags.get(el);
+  if (prev) {
+    prev.remove();
+    elementStyleTags.delete(el);
+  }
+  el.style.cssText = "";
+  delete el.dataset.jx;
+  applyStyle(el, styleDef ?? {}, mediaQueries, state);
 }
 
 /**
@@ -804,65 +872,72 @@ function applyAttributes(el: HTMLElement, attrs: Record<string, JxAttributeValue
 // ─── Array mapping ────────────────────────────────────────────────────────────
 
 /**
- * @param {JxElement} def
+ * Render a mapped array (repeater) wrapper-less: its item instances are inserted directly into
+ * `parentEl`, in place, ahead of an anchor comment that marks the array's position among the
+ * parent's other children. Re-renders reactively when `items` (or the filter/sort sources) change;
+ * each generation's item renders live in their own detached effect scope so nested arrays and
+ * template bindings are disposed — not leaked or double-fired — on the next change.
+ *
+ * `options._path` is the array node's own document path (`[…, "children", i]`, or `[…, "children"]`
+ * for a legacy whole-children repeater); item instances render at `[…that…, "map", index]`.
+ *
+ * @param {HTMLElement} parentEl
  * @param {import("@jxsuite/schema/types").JxMappedArray} arrayDef
  * @param {JxScope} state
  * @param {JxRenderOptions} [options]
- * @returns {HTMLElement}
  */
-function renderMappedArray(
-  def: JxElement,
+function renderMappedArrayInto(
+  parentEl: HTMLElement,
   arrayDef: JxMappedArray,
   state: JxScope,
   options?: JxRenderOptions,
 ) {
   const path = options?._path ?? [];
-  const container = document.createElement(def.tagName ?? "div");
-
-  if (options?.onNodeCreated) {
-    options.onNodeCreated(container, path, def);
-  }
-
-  applyProperties(container, def, state);
-  applyStyle(container, def.style ?? {}, (state["$media"] as Record<string, string>) ?? {}, state);
-  applyAttributes(container, def.attributes ?? {}, state);
+  const anchor = document.createComment("jx-array");
+  parentEl.append(anchor);
   const { items: itemsSrc, map: mapDef, filter: filterRef, sort: sortRef } = arrayDef;
 
   effect(() => {
-    container.innerHTML = "";
-    let items: unknown;
-    items = isRefObj(itemsSrc) ? resolveRef(itemsSrc.$ref, state) : itemsSrc;
-    if (!Array.isArray(items)) {
-      return;
-    }
-    if (isRefObj(filterRef)) {
+    let items: unknown = isRefObj(itemsSrc) ? resolveRef(itemsSrc.$ref, state) : itemsSrc;
+    if (Array.isArray(items) && isRefObj(filterRef)) {
       const fn = resolveRef(filterRef.$ref, state);
       if (typeof fn === "function") {
         items = items.filter(fn as (v: unknown) => boolean);
       }
     }
-    if (isRefObj(sortRef)) {
+    if (Array.isArray(items) && isRefObj(sortRef)) {
       const fn = resolveRef(sortRef.$ref, state);
       if (typeof fn === "function") {
         items = [...(items as unknown[])].toSorted(fn as (a: unknown, b: unknown) => number);
       }
     }
+    if (!Array.isArray(items) || !mapDef) {
+      return;
+    }
 
-    for (const [index, item] of (items as unknown[]).entries()) {
-      const child = Object.create(state);
-      child.$map = { index, item };
-      child["$map/item"] = item;
-      child["$map/index"] = index;
-      const childOpts = options
-        ? { ...options, _path: [...path, "children", "map", index] }
-        : undefined;
-      if (mapDef) {
-        container.append(renderNode(mapDef, child, childOpts));
+    // Render this generation's items inside a detached scope; the cleanup (run before the next
+    // Re-render and when the enclosing render scope stops) tears it down and removes its nodes.
+    const scope = effectScope(true);
+    const nodes: ChildNode[] = [];
+    scope.run(() => {
+      for (const [index, item] of (items as unknown[]).entries()) {
+        const child = Object.create(state) as JxScope;
+        child.$map = { index, item };
+        child["$map/item"] = item;
+        child["$map/index"] = index;
+        const childOpts = options ? { ...options, _path: [...path, "map", index] } : undefined;
+        const node = renderNode(mapDef, child, childOpts);
+        anchor.before(node);
+        nodes.push(node);
       }
-    }
+    });
+    onEffectCleanup(() => {
+      scope.stop();
+      for (const n of nodes) {
+        n.remove();
+      }
+    });
   });
-
-  return container;
 }
 
 // ─── $switch ──────────────────────────────────────────────────────────────────
@@ -878,7 +953,7 @@ function renderSwitch(def: JxElement, state: JxScope, options?: JxRenderOptions)
   const container = document.createElement(def.tagName ?? "div");
 
   if (options?.onNodeCreated) {
-    options.onNodeCreated(container, path, def);
+    options.onNodeCreated(container, path, def, state);
   }
 
   applyProperties(container, def, state);
@@ -960,7 +1035,7 @@ export async function resolvePrototype(
 
       if (!def.manual) {
         effect(() => {
-          let url;
+          let url: string | undefined;
           if (isTemplateString(def.url)) {
             url = evaluateTemplate(def.url, state);
           } else {
@@ -1000,7 +1075,7 @@ export async function resolvePrototype(
           if (debounceMs > 0) {
             debounceTimer = setTimeout(doFetch, debounceMs);
           } else {
-            doFetch();
+            void doFetch();
           }
         });
       }
@@ -1013,11 +1088,13 @@ export async function resolvePrototype(
         const p: Record<string, string> = {};
         for (const [k, v] of Object.entries(def)) {
           if (k !== "$prototype") {
-            p[k] = isRefObj(v)
-              ? resolveRef(v.$ref, state)
-              : isTemplateString(v)
-                ? evaluateTemplate(v, state)
-                : v;
+            p[k] = (
+              isRefObj(v)
+                ? resolveRef(v.$ref, state)
+                : isTemplateString(v)
+                  ? evaluateTemplate(v, state)
+                  : v
+            ) as string;
           }
         }
         return new URLSearchParams(p).toString();
@@ -1028,10 +1105,10 @@ export async function resolvePrototype(
     case "SessionStorage": {
       const store = def.$prototype === "LocalStorage" ? localStorage : sessionStorage;
       const k = def.key ?? key;
-      let init;
+      let init: unknown;
       try {
         const s = store.getItem(k);
-        init = s !== null ? JSON.parse(s) : (def.default ?? null);
+        init = s !== null ? (JSON.parse(s) as unknown) : (def.default ?? null);
       } catch {
         init = def.default ?? null;
       }
@@ -1060,7 +1137,7 @@ export async function resolvePrototype(
           return null;
         }
         try {
-          return JSON.parse(decodeURIComponent(m[1]));
+          return JSON.parse(decodeURIComponent(m[1]!));
         } catch {
           return m[1];
         }
@@ -1221,16 +1298,16 @@ async function resolveExternalPrototype(
  * @returns {Promise<unknown>}
  */
 async function importAndInstantiate(def: JxScope, src: string, exportName: string, base?: string) {
-  let mod;
+  let mod: ImportedModule;
   if (_moduleCache.has(src)) {
-    mod = _moduleCache.get(src);
+    mod = _moduleCache.get(src)!;
   } else {
     try {
-      mod = await import(src);
+      mod = (await import(src)) as ImportedModule;
     } catch {
       if (base) {
         const resolvedSrc = new URL(src, base).href;
-        mod = await import(resolvedSrc);
+        mod = (await import(resolvedSrc)) as ImportedModule;
       } else {
         throw new Error(`Failed to import "${src}"`);
       }
@@ -1253,9 +1330,10 @@ async function importAndInstantiate(def: JxScope, src: string, exportName: strin
     }
   }
 
-  const instance = new ExportedClass(config);
+  const Ctor = ExportedClass as new (config: JxScope) => ExternalClassInstance;
+  const instance = new Ctor(config);
 
-  let value;
+  let value: unknown;
   if (typeof instance.resolve === "function") {
     value = await instance.resolve();
   } else if ("value" in instance) {
@@ -1342,9 +1420,9 @@ async function resolveClassJson(def: JxPrototypeDef, state: JxScope, key: string
       config[k] = v;
     }
   }
-  const instance = new DynClass(config);
+  const instance = new DynClass(config) as ExternalClassInstance;
 
-  let value;
+  let value: unknown;
   if (typeof instance.resolve === "function") {
     value = await instance.resolve();
   } else if ("value" in instance) {
@@ -1395,7 +1473,12 @@ function classFromSchema(classDef: JxClassDef) {
       }
       if (ctor?.body) {
         const bodyStr = Array.isArray(ctor.body) ? ctor.body.join("\n") : ctor.body;
-        new Function("config", bodyStr).call(this, config);
+        (
+          new Function("config", bodyStr) as (
+            this: unknown,
+            config: Record<string, unknown>,
+          ) => void
+        ).call(this, config);
       }
     }
   }
@@ -1528,17 +1611,17 @@ async function resolveServerFunction(
   const src = def.$src;
   const exportName = def.$export;
 
-  let mod;
+  let mod: ImportedModule;
   if (_moduleCache.has(src)) {
-    mod = _moduleCache.get(src);
+    mod = _moduleCache.get(src)!;
   } else {
     try {
-      mod = await import(src);
+      mod = (await import(src)) as ImportedModule;
     } catch {
       if (base) {
         try {
           const resolvedSrc = new URL(src, base).href;
-          mod = await import(resolvedSrc);
+          mod = (await import(resolvedSrc)) as ImportedModule;
         } catch {
           // Module cannot run in the browser — fall back to dev server proxy
           return resolveServerFunctionViaProxy(def, state, key, base);
@@ -1550,13 +1633,14 @@ async function resolveServerFunction(
     _moduleCache.set(src, mod);
   }
 
-  const fn = mod[exportName] ?? mod.default?.[exportName];
-  if (!fn) {
+  const candidate = mod[exportName] ?? mod.default?.[exportName];
+  if (!candidate) {
     throw new Error(`Jx: export "${exportName}" not found in "${src}" for "${key}"`);
   }
-  if (typeof fn !== "function") {
+  if (typeof candidate !== "function") {
     throw new TypeError(`Jx: "${exportName}" from "${src}" is not a function`);
   }
+  const fn = candidate as (args: JxScope) => Promise<unknown>;
 
   const rawArgs = def.arguments ?? {};
   const hasReactiveArg = Object.values(rawArgs).some((v: unknown) => isRefObj(v));
@@ -1672,7 +1756,7 @@ export function resolveRef(refPath: string, state: JxScope) {
     const parts = refPath.split("/");
     const [, key] = parts; // "item" or "index"
     const map = state.$map as Record<string, unknown> | undefined;
-    const base = map?.[key] ?? state[`$map/${key}`];
+    const base = map?.[key!] ?? state[`$map/${key}`];
     return parts.length > 2 ? getPath(base, parts.slice(2).join("/")) : base;
   }
   if (refPath.startsWith("#/state/")) {
@@ -1742,7 +1826,7 @@ function getPath(obj: unknown, path: string) {
  * @returns {JxScope}
  */
 function mergeProps(def: JxElement, parentState: JxScope): JxScope {
-  const child = Object.create(parentState);
+  const child = Object.create(parentState) as JxScope;
   for (const [k, v] of Object.entries(def.$props ?? {})) {
     child[k] = isRefObj(v) ? resolveRef(v.$ref, parentState) : v;
   }
@@ -1927,7 +2011,7 @@ export async function defineElement(source: string | JxDocument, baseUrl?: strin
       const propsAttr = this.dataset.jxProps;
       if (propsAttr) {
         try {
-          const props = JSON.parse(propsAttr);
+          const props = JSON.parse(propsAttr) as Record<string, unknown>;
           for (const [key, val] of Object.entries(props)) {
             if (key in (def.state ?? {})) {
               state[key] = val;
@@ -1984,19 +2068,19 @@ export async function defineElement(source: string | JxDocument, baseUrl?: strin
       // Lifecycle: onMount
       const { onMount } = state;
       if (typeof onMount === "function") {
-        queueMicrotask(() => onMount(state));
+        queueMicrotask(() => (onMount as (s: JxScope) => unknown)(state));
       }
     }
 
     disconnectedCallback() {
       if (typeof this._state?.onUnmount === "function") {
-        this._state.onUnmount(this._state);
+        (this._state.onUnmount as (s: JxScope) => unknown)(this._state);
       }
     }
 
     adoptedCallback() {
       if (typeof this._state?.onAdopted === "function") {
-        this._state.onAdopted(this._state);
+        (this._state.onAdopted as (s: JxScope) => unknown)(this._state);
       }
     }
 
@@ -2037,7 +2121,7 @@ function renderCustomElementWithProps(
   const el = document.createElement(def.tagName ?? "div");
 
   if (options?.onNodeCreated) {
-    options.onNodeCreated(el, path ?? [], def);
+    options.onNodeCreated(el, path ?? [], def, state);
   }
 
   // Set JS properties from $props (before connection)
@@ -2067,7 +2151,7 @@ function renderCustomElementWithProps(
   const children = Array.isArray(def.children) ? def.children : [];
   for (let i = 0; i < children.length; i++) {
     const childOpts = options && path ? { ...options, _path: [...path, "children", i] } : undefined;
-    el.append(renderNode(children[i], state, childOpts));
+    el.append(renderNode(children[i]!, state, childOpts));
   }
 
   return el;

package/src/types.ts

@@ -1,7 +1,7 @@
 /// <reference lib="dom" />
 import type { JxElement, JxPath } from "@jxsuite/schema/types";
 
-export type { JxPath };
+export type { JxPath } from "@jxsuite/schema/types";
 
 /**
  * The live reactive scope: a prototype-chained object whose keys are user-defined state names.
@@ -15,7 +15,16 @@ export type JxEventHandler = (scope: JxScope, event: Event) => unknown;
 
 export interface JxRenderOptions {
   _path?: JxPath;
-  onNodeCreated?: (el: HTMLElement | Text, path: JxPath, def: JxElement | string) => void;
+  /**
+   * Called for each created node. `state` is the local scope the node's children render with —
+   * callers can capture it to re-render a subtree in isolation later.
+   */
+  onNodeCreated?: (
+    el: HTMLElement | Text,
+    path: JxPath,
+    def: JxElement | string,
+    state?: JxScope,
+  ) => void;
 }
 
 export interface DynamicClass {