@praxisjs/runtime 0.7.1 → 0.8.0

package/src/hydration-context.ts

@@ -1,6 +1,11 @@
 import type { Scope } from "./scope";
 
-let _recording = false;
+/**
+ * True during a hydration build pass (see runInRecording). Exported as a live binding so the hot
+ * render paths read a variable instead of calling isRecording() for every binding.
+ */
+ 
+export let recording = false;
 
 /**
  * Marks the synchronous "build" pass of a hydration attempt: `factory()` runs
@@ -11,17 +16,17 @@ let _recording = false;
  * element instead of the fresh one. No-op / zero cost outside a build pass.
  */
 export function runInRecording<T>(fn: () => T): T {
-  const prev = _recording;
-  _recording = true;
+  const prev = recording;
+  recording = true;
   try {
     return fn();
   } finally {
-    _recording = prev;
+    recording = prev;
   }
 }
 
 export function isRecording(): boolean {
-  return _recording;
+  return recording;
 }
 
 interface PropRecord {
@@ -35,19 +40,35 @@ export function recordProps(el: Element, props: Record<string, unknown>, scope:
   _propRecords.set(el, { props, scope });
 }
 
+/** Adds one prop to an element's record, for elements whose props are applied one at a time. */
+export function recordProp(el: Element, key: string, value: unknown, scope: Scope): void {
+  const record = _propRecords.get(el);
+  if (record === undefined) _propRecords.set(el, { props: { [key]: value }, scope });
+  else record.props[key] = value;
+}
+
 export function getRecordedProps(el: Element): PropRecord | undefined {
   return _propRecords.get(el);
 }
 
-// mountReactive() keeps a `currentNodes` array (by reference) for diffing its
-// *next* update. If reconcile() replaces one of those fresh nodes with a real
-// one, it needs to overwrite that array in place so the closure sees the swap.
-const _reactiveOwners = new WeakMap<Node, Node[]>();
+// Code that keeps references to fresh nodes for its *next* update (mountReactive's
+// `currentNodes`, a list row's boundaries) registers how to repoint them, so reconcile()
+// can tell it when it keeps a real element in place of a fresh one. One node can have several
+// owners (a list row's element is also part of the nodes an enclosing reactive child returned).
+const _replacers = new WeakMap<Node, (real: Node) => void>();
 
-export function registerReactiveNode(node: Node, owner: Node[]): void {
-  _reactiveOwners.set(node, owner);
+export function onHydrationReplace(node: Node, replace: (real: Node) => void): void {
+  const prev = _replacers.get(node);
+  _replacers.set(node, prev === undefined ? replace : (real) => { prev(real); replace(real); });
+}
+
+export function getHydrationReplacer(node: Node): ((real: Node) => void) | undefined {
+  return _replacers.get(node);
 }
 
-export function getReactiveOwner(node: Node): Node[] | undefined {
-  return _reactiveOwners.get(node);
+export function registerReactiveNode(node: Node, owner: Node[]): void {
+  onHydrationReplace(node, (real) => {
+    const idx = owner.indexOf(node);
+    if (idx !== -1) owner[idx] = real;
+  });
 }

package/src/hydration.ts

@@ -1,5 +1,5 @@
 import { applyProp } from "./dom/props";
-import { getReactiveOwner, getRecordedProps } from "./hydration-context";
+import { getHydrationReplacer, getRecordedProps } from "./hydration-context";
 
 function replayProps(real: Element, fresh: Element): void {
   const record = getRecordedProps(fresh);
@@ -10,15 +10,10 @@ function replayProps(real: Element, fresh: Element): void {
   }
 }
 
-// mountReactive()'s `currentNodes` array holds fresh node references for its
-// *next* diff. If we're keeping `real` instead of `fresh` here, that array
-// needs to see the swap too — it's registered by reference, so this mutation
-// is visible to whichever effect closure owns it.
+// mountReactive()'s `currentNodes` and list rows keep fresh node references for their
+// *next* update. If we're keeping `real` instead of `fresh` here, they need to see the swap.
 function notifyReplacement(fresh: Node, real: Node): void {
-  const owner = getReactiveOwner(fresh);
-  if (!owner) return;
-  const idx = owner.indexOf(fresh);
-  if (idx !== -1) owner[idx] = real;
+  getHydrationReplacer(fresh)?.(real);
 }
 
 /**

package/src/index.ts

@@ -1,8 +1,10 @@
 import { mountChildren } from "./children";
 import { runInScope } from "./context";
+import { addEventRoot } from "./dom/events";
 import { reconcile } from "./hydration";
 import { runInRecording } from "./hydration-context";
 import { Scope } from "./scope";
+import { syncTemplateDocument } from "./template";
 
 /** Written by `@praxisjs/ssg` onto the mount container in its prerendered HTML. */
 const SSG_MARKER = "data-praxis-ssg";
@@ -11,8 +13,10 @@ function mountCreate(
   factory: () => Node | Node[] | null,
   container: HTMLElement,
 ): () => void {
+  syncTemplateDocument();
   const rootScope = new Scope();
   container.innerHTML = "";
+  const removeEventRoot = addEventRoot(container);
 
   runInScope(rootScope, () => {
     const result = factory();
@@ -21,6 +25,7 @@ function mountCreate(
 
   return () => {
     rootScope.dispose();
+    removeEventRoot();
     container.innerHTML = "";
   };
 }
@@ -29,6 +34,7 @@ function hydrate(
   factory: () => Node | Node[] | null,
   container: HTMLElement,
 ): () => void {
+  syncTemplateDocument();
   const rootScope = new Scope();
   const scratch = document.createDocumentFragment();
 
@@ -44,24 +50,40 @@ function hydrate(
   });
 
   reconcile(container, Array.from(scratch.childNodes));
+  const removeEventRoot = addEventRoot(container);
 
   return () => {
     rootScope.dispose();
+    removeEventRoot();
     container.innerHTML = "";
   };
 }
 
+// Reached only through enableHydration(), so an app that never calls it leaves the reconciliation
+// and every recording branch of the render paths out of its bundle.
+let hydrateRoot: typeof hydrate | null = null;
+
+/**
+ * Lets render() hydrate the HTML `@praxisjs/ssg` prerendered. `ssgPlugin()` calls it at the start of
+ * the client bundle, so apps it builds need nothing more; a page prerendered another way calls it
+ * once before render(). Without it, a container carrying the hydration marker is cleared and
+ * mounted fresh.
+ */
+export function enableHydration(): void {
+  hydrateRoot = hydrate;
+}
+
 /**
  * Renders a component tree into a container element.
  *
  * The factory function is called once inside the root scope,
  * so `jsx()` can access the current scope via `getCurrentScope()`.
  *
- * If `container` carries the marker `@praxisjs/ssg` stamps onto prerendered
- * HTML, the tree is built normally into a detached scratch node and then
- * reconciled against the existing DOM (real elements are kept and have their
- * props/listeners replayed onto them; text/comments and any mismatched nodes
- * are recreated) instead of clearing the container and mounting fresh.
+ * Once hydration is enabled (see `enableHydration()`), a `container` carrying the marker
+ * `@praxisjs/ssg` stamps onto prerendered HTML has its tree built normally into a detached
+ * scratch node and then reconciled against the existing DOM (real elements are kept and have their
+ * props/listeners replayed onto them; text/comments and any mismatched nodes are recreated)
+ * instead of being cleared and mounted fresh.
  *
  * @example
  * render(() => <App />, document.getElementById('app'));
@@ -70,8 +92,8 @@ export function render(
   factory: () => Node | Node[] | null,
   container: HTMLElement,
 ): () => void {
-  if (container.hasAttribute(SSG_MARKER)) {
-    return hydrate(factory, container);
+  if (hydrateRoot !== null && container.hasAttribute(SSG_MARKER)) {
+    return hydrateRoot(factory, container);
   }
   return mountCreate(factory, container);
 }
@@ -79,5 +101,30 @@ export function render(
 export { Scope } from "./scope";
 export { runInScope, getCurrentScope } from "./context";
 export { mountElement } from "./element";
+export { mountChildren } from "./children";
+export {
+  template as _$template,
+  html as _$html,
+  element as _$element,
+  prop as _$prop,
+  reactive as _$reactive,
+  insert as _$insert,
+  reactiveOnly as _$reactiveOnly,
+  insertOnly as _$insertOnly,
+  on as _$on,
+  event as _$event,
+  onEvent as _$onEvent,
+  className as _$className,
+  scope as _$scope,
+} from "./template";
 export { mountComponent } from "./component";
+export { registerHot as _$hmrRegister, acceptsHotUpdate as _$hmrAccepts } from "./hmr";
 export { Portal, type PortalProps } from "./portal";
+export {
+  For,
+  Index,
+  type ForProps,
+  type IndexProps,
+  type ListSource,
+  type ListTransition,
+} from "./list";