@praxisjs/runtime 0.7.0 → 0.8.0

package/src/portal.ts

@@ -3,6 +3,7 @@ import { isServerRenderPass } from "@praxisjs/core/internal";
 
 import { mountChildren } from "./children";
 import { getCurrentScope } from "./context";
+import { addEventRoot } from "./dom/events";
 import { removeNodes } from "./dom/remove";
 
 export interface PortalProps {
@@ -34,6 +35,8 @@ export class Portal extends StatelessComponent<PortalProps> {
     mountChildren(fragment, this.props.children, scope);
     fragment.appendChild(end);
     target.appendChild(fragment);
+    // The portal's content is outside the render container, so its target relays delegated events.
+    scope.add(addEventRoot(target));
 
     scope.add(() => {
       if (!start.parentNode || start.parentNode !== end.parentNode) return;

package/src/reactive.ts

@@ -1,7 +1,13 @@
-import { runInScope } from "./context";
+import type { EffectNode } from "@praxisjs/core/internal";
+
+import { swapLazyScope, swapScope, type LazyScopeHost } from "./context";
 import { removeNodes } from "./dom/remove";
-import { isRecording, registerReactiveNode } from "./hydration-context";
-import { Scope } from "./scope";
+import { onHydrationReplace, recording, registerReactiveNode } from "./hydration-context";
+
+
+import type { Scope } from "./scope";
+
+const NO_NODES: Node[] = [];
 
 function collectNodes(value: unknown, out: Node[]): void {
   if (value === null || value === undefined || value === false) return;
@@ -20,48 +26,149 @@ function nodesToFragment(nodes: Node[]): Node {
   return fragment;
 }
 
-export function mountReactive(
-  parent: Node,
-  fn: () => unknown,
-  parentScope: Scope,
-): void {
-  const end = document.createComment("");
-  parent.appendChild(end);
-
-  let currentNodes: Node[] = [];
-  let childScope = new Scope();
-
-  parentScope.effect(() => {
-    childScope.dispose();
-    childScope = new Scope();
-
-    const result = runInScope(childScope, fn);
-    const newNodes: Node[] = [];
-    collectNodes(result, newNodes);
-
-    // During a hydration build pass, remember that each of these fresh nodes
-    // belongs to *this* array — reconcile() mutates `newNodes` in place (by
-    // reference, same array `currentNodes` ends up pointing at) if it decides
-    // to keep a real element instead of one of them, so future diffs here
-    // stay correct.
-    if (isRecording()) {
-      for (const n of newNodes) registerReactiveNode(n, newNodes);
-    }
+class Region implements LazyScopeHost {
+  declare parent: Node;
+  declare fn: () => unknown;
+  /** Null when the region is all of `parent`'s content and appends to it. */
+  declare end: Node | null;
+  /**
+   * What the region shows. A text node the region built itself is held by `text` alone (`nodes`
+   * empty), so a text-only region never builds an array.
+   */
+  declare nodes: Node[];
+  /** Set while the region shows exactly the text node built from a string/number result, so the
+   * next string/number result rewrites it in place instead of swapping nodes. */
+  declare text: Text | null;
+  declare textValue: string;
+  /**
+   * Set when a text result went in through `parent.textContent` or `end.before()`, which build the
+   * node natively, without a JS wrapper for it: the node is looked up only if a later run has to
+   * change or remove it. Nothing else inserts right before `end` once the region is mounted, so it
+   * is still `end`'s previous sibling (or the only child of `parent`) then.
+   */
+  declare lazyText: boolean;
+  declare parentScope: Scope;
+  /**
+   * Forked the first time a run asks for the current scope, then reused across runs: disposing
+   * empties it, so a re-run allocates no new scope. A region whose runs register nothing has none.
+   */
+  declare scope: Scope | null;
 
-    const anchor = end.parentNode ?? parent;
+  constructor(parent: Node, fn: () => unknown, end: Node | null, placeholder: Text | null, parentScope: Scope) {
+    this.parent = parent;
+    this.fn = fn;
+    this.end = end;
+    this.nodes = NO_NODES;
+    this.text = placeholder;
+    this.textValue = placeholder === null ? "" : placeholder.data;
+    this.lazyText = false;
+    this.parentScope = parentScope;
+    this.scope = null;
+  }
+}
 
-    if (currentNodes.length === 1) {
-      (anchor as Element).removeChild(currentNodes[0]);
-    } else if (currentNodes.length > 1) {
-      removeNodes(currentNodes);
+// Keeps the region shape alive across full GCs; see the keeper in scope.ts. Built without a DOM so
+// the runtime stays importable before one exists.
+Object.defineProperty(Region, "shapeKeeper", {
+  value: new Region(null as unknown as Node, () => undefined, null, null, null as unknown as Scope),
+});
+
+function runRegion(this: EffectNode<Region>): void {
+  const region = this.ctx;
+  const { parent, end } = region;
+  region.scope?.dispose();
+  const prevScope = swapScope(region.scope);
+  const prevHost = swapLazyScope(region);
+  let result: unknown;
+  try {
+    result = region.fn();
+  } finally {
+    swapScope(prevScope);
+    swapLazyScope(prevHost);
+  }
+  const isText = typeof result === "string" || typeof result === "number";
+
+  if (region.lazyText) {
+    region.lazyText = false;
+    region.text = (end === null ? parent.firstChild : end.previousSibling) as Text;
+  }
+  const text = region.text;
+
+  if (isText && text !== null) {
+    const value = String(result);
+    if (value !== region.textValue) {
+      text.data = value;
+      region.textValue = value;
     }
+    return;
+  }
+
+  const anchor = end === null ? parent : (end.parentNode ?? parent);
+  const current = region.nodes;
 
-    if (newNodes.length > 0) {
-      anchor.insertBefore(nodesToFragment(newNodes), end);
+  if (isText && current.length === 0 && !recording) {
+    const value = String(result);
+    region.textValue = value;
+    // A null `end` with nothing shown means `parent` is empty. An empty string builds no node there.
+    if (end === null ? value !== "" : end.parentNode !== null) {
+      if (end === null) parent.textContent = value;
+      else (end as ChildNode).before(value);
+      region.lazyText = true;
+      return;
     }
+    const node = document.createTextNode(value);
+    anchor.insertBefore(node, end);
+    region.text = node;
+    return;
+  }
+
+  const newNodes: Node[] = [];
+  collectNodes(result, newNodes);
+
+  // During a hydration build pass, remember that each of these fresh nodes
+  // belongs to *this* array — reconcile() mutates `newNodes` in place (by
+  // reference, same array `region.nodes` ends up pointing at) if it decides
+  // to keep a real element instead of one of them, so future diffs here
+  // stay correct.
+  if (recording) {
+    for (const n of newNodes) registerReactiveNode(n, newNodes);
+  }
+
+  if (current.length === 1) {
+    anchor.removeChild(current[0]);
+  } else if (current.length > 1) {
+    removeNodes(current);
+  } else if (text !== null) {
+    anchor.removeChild(text);
+  }
 
-    currentNodes = newNodes;
-  });
+  if (newNodes.length > 0) {
+    anchor.insertBefore(nodesToFragment(newNodes), end);
+  }
 
-  parentScope.add(() => { childScope.dispose(); });
+  // Kept even for a lone text node: a hydration pass may swap a real node into this very array.
+  region.nodes = newNodes;
+  if (isText) {
+    region.text = newNodes[0] as Text;
+    region.textValue = region.text.data;
+  } else {
+    region.text = null;
+  }
+}
+
+export function mountReactive(
+  parent: Node,
+  fn: () => unknown,
+  parentScope: Scope,
+  end: Node | null = parent.appendChild(document.createComment("")),
+  placeholder: Text | null = null,
+): void {
+  // `placeholder` is an empty text node already in place (from a compiled template) that a text
+  // result takes over.
+  const region = new Region(parent, fn, end, placeholder, parentScope);
+  // A hydration build pass mounts into a scratch tree. A region with an end node finds the real
+  // parent through it once reconcile() moves it there; one without must be told which real element
+  // reconcile() kept in place of `parent`.
+  if (end === null && recording) onHydrationReplace(parent, (real) => { region.parent = real; });
+  parentScope.contextEffect(runRegion, region);
 }

package/src/scope.ts

@@ -1,35 +1,82 @@
-import { effect as coreEffect } from "@praxisjs/core/internal";
+import { createContextEffect, createEffect, disposeEffect, EffectNode, type EffectCleanup } from "@praxisjs/core/internal";
 import type { Cleanup } from "@praxisjs/shared/internal";
 
+import { removeListener } from "./dom/events";
+
+type Disposable = Cleanup | { dispose(): void } | EffectNode;
+
+// Thousands of scopes are created per list render (one per row and per reactive child), so a scope
+// holds effects and child scopes directly instead of wrapping each in a closure, allocates its
+// arrays only when something is registered, and records event listeners as flat triples.
 export class Scope {
-  #cleanups: Cleanup[] = [];
+  private declare items: Disposable[] | null;
+  private declare listeners: unknown[] | null;
+  /** Bumped by every dispose(): delegated handlers bound in an earlier generation stop firing. */
+  declare gen: number;
+
+  // Assigned here rather than as field initializers, which make scopes noticeably slower to create.
+  constructor() {
+    this.items = null;
+    this.listeners = null;
+    this.gen = 0;
+  }
+
+  effect(fn: () => EffectCleanup): void {
+    (this.items ??= []).push(createEffect(fn));
+  }
 
-  effect(fn: Parameters<typeof coreEffect>[0]): void {
-    this.#cleanups.push(coreEffect(fn));
+  /** Runs an effect whose shared `fn` keeps its state in `ctx` (see createContextEffect). */
+  contextEffect<Ctx>(fn: (this: EffectNode<Ctx>) => EffectCleanup, ctx: Ctx): void {
+    (this.items ??= []).push(createContextEffect(fn, ctx));
   }
 
-  add(cleanup: Cleanup): void {
-    this.#cleanups.push(cleanup);
+  add(cleanup: Cleanup | { dispose(): void }): void {
+    (this.items ??= []).push(cleanup);
   }
 
   fork(): Scope {
     const child = new Scope();
-    this.#cleanups.push(() => { child.dispose(); });
+    (this.items ??= []).push(child);
     return child;
   }
 
+  /** Records a listener that `removeListener` takes off `el` when the scope is disposed. */
+  listen(el: Element, type: string, handler: unknown): void {
+    (this.listeners ??= []).push(el, type, handler);
+  }
+
   dispose(): void {
-    const cleanups = this.#cleanups;
-    this.#cleanups = [];
-    const errors: unknown[] = [];
-    for (const fn of cleanups) {
-      try {
-        fn();
-      } catch (e) {
-        errors.push(e);
+    this.gen++;
+    const items = this.items;
+    const listeners = this.listeners;
+    if (items === null && listeners === null) return;
+    this.items = null;
+    this.listeners = null;
+    let errors: unknown[] | null = null;
+    if (listeners !== null) {
+      for (let i = 0; i < listeners.length; i += 3) {
+        removeListener(listeners[i] as Element, listeners[i + 1] as string, listeners[i + 2]);
       }
     }
+    if (items !== null) {
+      for (const item of items) {
+        try {
+          if (typeof item === "function") item();
+          else if (item instanceof EffectNode) disposeEffect(item);
+          else item.dispose();
+        } catch (e) {
+          (errors ??= []).push(e);
+        }
+      }
+    }
+    if (errors === null) return;
     if (errors.length === 1) throw errors[0];
-    if (errors.length > 1) throw new AggregateError(errors, "[PraxisJS] Multiple errors during dispose()");
+    throw new AggregateError(errors, "[PraxisJS] Multiple errors during dispose()");
   }
 }
+
+// V8 holds map transitions weakly: when every scope dies (a list cleared before a full GC), the
+// hidden class its constructor builds dies too, and the optimized code that embedded it is thrown
+// away. An unused instance keeps the shape alive; Object.defineProperty keeps bundlers from
+// dropping it.
+Object.defineProperty(Scope, "shapeKeeper", { value: new Scope() });

package/src/template.ts

@@ -0,0 +1,271 @@
+import { mountChildren } from "./children";
+import { getCurrentScope } from "./context";
+import { createElement } from "./dom/create";
+import { addDelegatedEvent, delegatedProp, type DelegatedType } from "./dom/events";
+import { applyProp, bindClass, hasWritableProperty, setProp } from "./dom/props";
+import { recording, recordProp } from "./hydration-context";
+import { mountReactive } from "./reactive";
+
+import type { Scope } from "./scope";
+
+// Runtime half of the compiled templates emitted by @praxisjs/vite-plugin. The static part of a JSX
+// tree is built once, then every instance is a single cloneNode(true) plus the bindings for its
+// dynamic parts. template() builds it with the same DOM calls a plain render makes; html() parses
+// markup the compiler emits only where the parser builds that same tree.
+
+type Patch = [path: number[], key: string, value: unknown];
+
+/** A reactive child's position: the comment it inserts its nodes before. */
+export const MARKER = 0;
+
+let pendingPatches: Array<[Element, string, unknown]> | null = null;
+
+// Templates are built in the inert document that <template> contents live in: cloning there and
+// letting the insertion adopt the clone is cheaper than cloning inside the live document. Custom
+// elements are the exception, since only the live document upgrades them, so a template that
+// contains one is built (and cloned) there instead.
+let inertDocument: Document | null = null;
+// null is the live document, looked up when used: the module is imported before any DOM exists
+// when a server renderer installs one afterwards.
+let buildDocument: Document | null = null;
+let sawCustomElement = false;
+// The global document the cached templates were built for, and a counter that tells every template
+// to build again. A server renderer may install a new window (a new global document) for each run:
+// nodes cloned from another window's templates fail every `instanceof Node` check and are dropped.
+let templatesDocument: Document | null = null;
+let generation = 0;
+
+function inert(): Document {
+  templatesDocument ??= document;
+  return (inertDocument ??= document.createElement("template").content.ownerDocument);
+}
+
+/** Called by render(): templates built for another global document are built again on next use. */
+export function syncTemplateDocument(): void {
+  if (templatesDocument === null || templatesDocument === document) return;
+  templatesDocument = null;
+  inertDocument = null;
+  generation++;
+}
+
+// Attribute-level props survive cloneNode, so they are applied to the template itself. A prop that
+// lives only in a property (an expando, a custom element's field) would be lost by cloning, so it is
+// replayed on every clone instead. Which is which is checked on a probe element, not guessed.
+function bakeProp(el: Element, key: string, value: unknown): void {
+  const name = key === "htmlFor" ? "for" : key;
+  if (name === "class" || name === "className" || name === "style" || value === null || value === undefined) {
+    setProp(el, name, value);
+    return;
+  }
+  // Deep, so state held by the children (a <select>'s chosen option) is part of the check.
+  const probe = el.cloneNode(true) as Element & Record<string, unknown>;
+  setProp(probe, name, value);
+  const survives =
+    !hasWritableProperty(probe, name) ||
+    Object.is((probe.cloneNode(true) as Element & Record<string, unknown>)[name], probe[name]);
+  if (survives) setProp(el, name, value);
+  else (pendingPatches as Array<[Element, string, unknown]>).push([el, name, value]);
+}
+
+function appendStatic(parent: Node, child: unknown): void {
+  if (child === MARKER) {
+    parent.appendChild((buildDocument ?? document).createComment(""));
+  } else if (typeof child === "string") {
+    parent.appendChild((buildDocument ?? document).createTextNode(child));
+  } else if (Array.isArray(child)) {
+    for (const c of child) appendStatic(parent, c);
+  } else if (child instanceof Node) {
+    parent.appendChild(child);
+  }
+}
+
+/** Builds one static element of a template. */
+export function element(tag: string, props: Record<string, unknown> | null, children: unknown[] | null): Element {
+  if (tag.includes("-")) sawCustomElement = true;
+  const el = createElement(tag, buildDocument ?? document);
+  // Children first, as mountElement does, so a prop that depends on them (a <select> value) sees them.
+  if (children !== null) for (const child of children) appendStatic(el, child);
+  if (props !== null) for (const key in props) bakeProp(el, key, props[key]);
+  return el;
+}
+
+function pathOf(root: Node, node: Node): number[] {
+  const path: number[] = [];
+  let current = node;
+  while (current !== root) {
+    let index = 0;
+    let sibling = current.previousSibling;
+    while (sibling !== null) {
+      index++;
+      sibling = sibling.previousSibling;
+    }
+    path.unshift(index);
+    current = current.parentNode as Node;
+  }
+  return path;
+}
+
+function nodeAt(root: Node, path: number[]): Element {
+  let node = root;
+  for (const index of path) node = node.childNodes[index];
+  return node as Element;
+}
+
+// Builds the template root in `doc` (null: the live document) and lists the props to replay on
+// every clone.
+function buildIn(doc: Document | null, build: () => Element): [Element, Patch[] | null] {
+  const pending: Array<[Element, string, unknown]> = [];
+  pendingPatches = pending;
+  buildDocument = doc;
+  sawCustomElement = false;
+  const built = build();
+  return [built, pending.length > 0 ? pending.map(([el, key, value]): Patch => [pathOf(built, el), key, value]) : null];
+}
+
+/** Returns a function that clones the template `build` creates (built on first use). */
+export function template(build: () => Element): () => Element {
+  let root: Element | null = null;
+  let patches: Patch[] | null = null;
+  let live = false;
+  let built = -1;
+  return () => {
+    if (built !== generation) {
+      const outerPatches = pendingPatches;
+      const outerDocument = buildDocument;
+      const outerSaw = sawCustomElement;
+      try {
+        let result = buildIn(inert(), build);
+        live = sawCustomElement;
+        if (live) result = buildIn(null, build);
+        [root, patches] = result;
+        built = generation;
+      } finally {
+        pendingPatches = outerPatches;
+        buildDocument = outerDocument;
+        sawCustomElement = outerSaw;
+      }
+    }
+    // A clone of a live-document template taken while another template builds forces that one
+    // into the live document too, or its own clones would hold never-upgraded custom elements.
+    if (live) sawCustomElement = true;
+    const node = (root as Element).cloneNode(true) as Element;
+    if (patches !== null) {
+      for (const [path, key, value] of patches) {
+        const el = nodeAt(node, path);
+        setProp(el, key, value);
+        // Cloned while another template is being built: that template's clones need it too.
+        if (pendingPatches !== null) pendingPatches.push([el, key, value]);
+        if (recording) recordProp(el, key, value, getCurrentScope());
+      }
+    }
+    return node;
+  };
+}
+
+/**
+ * Returns a function that clones the tree `markup` parses to (parsed on first use). The compiler
+ * emits it only for markup the parser reads back as the tree element() would build, with no custom
+ * element in it, so it is parsed and cloned in the inert document like a built template.
+ */
+export function html(markup: string): () => Element {
+  let root: Element | null = null;
+  let built = -1;
+  return () => {
+    if (built !== generation) {
+      const parser = inert().createElement("template");
+      parser.innerHTML = markup;
+      root = parser.content.firstChild as Element;
+      built = generation;
+    }
+    return (root as Element).cloneNode(true) as Element;
+  };
+}
+
+/** Applies a dynamic prop to a cloned element. */
+export function prop(el: Element, key: string, value: unknown, scope: Scope): void {
+  if (recording) recordProp(el, key, value, scope);
+  applyProp(el, key, value, scope);
+}
+
+/** Binds an event prop of a compiled template element through the delegated path (dom/events). */
+export function on(el: Element, key: string, value: unknown, scope: Scope): void {
+  if (recording) recordProp(el, key, value, scope);
+  const entry = delegatedProp(key);
+  if (entry !== null) addDelegatedEvent(el, entry, value, scope);
+  else applyProp(el, key, value, scope);
+}
+
+/**
+ * The binding target of an event prop, resolved once per module by the compiler: the delegated
+ * entry, or the key itself when `key` is not a known event (it is then bound as a plain prop).
+ */
+export function event(key: string): DelegatedType | string {
+  return delegatedProp(key) ?? key;
+}
+
+/** Binds an event prop through the target `event()` resolved, with no lookup per binding. */
+export function onEvent(el: Element, target: DelegatedType | string, value: unknown, scope: Scope): void {
+  if (typeof target === "string") {
+    prop(el, target, value, scope);
+    return;
+  }
+  if (recording) recordProp(el, target.key, value, scope);
+  addDelegatedEvent(el, target, value, scope);
+}
+
+/**
+ * Binds a reactive `class` (or `className`) prop: the compiler emits it for a function literal
+ * value, which applyProp would bind the same way after its key checks.
+ */
+export function className(el: Element, read: () => unknown, scope: Scope): void {
+  if (recording) recordProp(el, "class", read, scope);
+  bindClass(el, read, scope);
+}
+
+/** Mounts a reactive child before its marker comment from the template. */
+export function reactive(marker: Node, fn: () => unknown, scope: Scope): void {
+  mountReactive(marker.parentNode as Node, fn, scope, marker);
+}
+
+/**
+ * Binds a reactive child that is the only content of `parent`, which the template leaves empty: no
+ * anchor comment is needed. Templates compiled by earlier versions hold an empty text node there,
+ * which a text result takes over; a hydration build pass gets one too, as mountReactive registers
+ * fresh nodes of other results only.
+ */
+export function reactiveOnly(parent: Node, fn: () => unknown, scope: Scope): void {
+  let placeholder: Text | null = null;
+  if (parent.hasChildNodes()) placeholder = parent.firstChild as Text;
+  else if (recording) placeholder = parent.appendChild(document.createTextNode(""));
+  mountReactive(parent, fn, scope, null, placeholder);
+}
+
+/** Inserts the only child of `parent`, which the template leaves empty. */
+export function insertOnly(parent: Node, value: unknown, scope: Scope): void {
+  // textContent builds the text node without a JS wrapper for it. An empty string still gets its
+  // (empty) text node, as mountChildren gives it one.
+  if ((typeof value === "string" && value !== "") || typeof value === "number") {
+    parent.textContent = value as string;
+    return;
+  }
+  mountChildren(parent, value, scope);
+}
+
+/** Inserts a dynamic child before `before`, or at the end of `parent` when it is null. */
+export function insert(parent: Node, value: unknown, before: Node | null, scope: Scope): void {
+  if (before === null) {
+    mountChildren(parent, value, scope);
+  } else if (typeof value === "function") {
+    const end = parent.insertBefore(document.createComment(""), before);
+    mountReactive(parent, value as () => unknown, scope, end);
+  } else if (value instanceof Node) {
+    parent.insertBefore(value, before);
+  } else if (typeof value === "string" || typeof value === "number") {
+    (before as ChildNode).before(String(value));
+  } else if (Array.isArray(value)) {
+    // Each item goes straight in front of `before`, in order: no fragment to fill and empty again.
+    for (const item of value) insert(parent, item, before, scope);
+  }
+}
+
+export { getCurrentScope as scope };

package/dist/__tests__/children.test.d.ts

@@ -1,2 +0,0 @@
-export {};
-//# sourceMappingURL=children.test.d.ts.map

package/dist/__tests__/children.test.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"children.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/children.test.ts"],"names":[],"mappings":""}