@praxisjs/runtime 0.7.0 → 0.8.0

package/src/hmr.ts

@@ -0,0 +1,110 @@
+import { isComponent, type ComponentConstructor } from "@praxisjs/shared/internal";
+
+import type { Scope } from "./scope";
+
+// Hot module replacement of components, driven by the code @praxisjs/vite-plugin appends to each
+// module in development: every top-level component class is registered under a stable id (the
+// file and the class name). When an edited module runs again, its new classes replace the old ones
+// under the same ids, and every mounted instance of an old class is rendered again with the new
+// one, in place. Nothing of this runs until a class is registered, so production builds only pay
+// the `hotEnabled` checks.
+
+/** A mounted instance of a registered component: what it needs to be mounted again in place. */
+export interface HotInstance {
+  ctor: ComponentConstructor;
+  props: Record<string, unknown>;
+  parentScope: Scope;
+  scope: Scope;
+  start: Comment;
+  end: Comment;
+}
+
+interface HotRecord {
+  current: ComponentConstructor;
+  instances: Set<HotInstance>;
+}
+
+/** True once a component class was registered: mountComponent then tracks hot instances. */
+export let hotEnabled = false;
+
+// A WeakMap, not a static property: a subclass would inherit a property and resolve to its base.
+const ids = new WeakMap<ComponentConstructor, string>();
+const records = new Map<string, HotRecord>();
+const stale = new Set<HotRecord>();
+
+let remount: ((hot: HotInstance, ctor: ComponentConstructor) => void) | null = null;
+
+/** Set by the component module, which owns mounting (kept out of here to avoid an import cycle). */
+export function setHotRemount(fn: (hot: HotInstance, ctor: ComponentConstructor) => void): void {
+  remount = fn;
+}
+
+/** The newest class registered under the id of `ctor`, or `ctor` itself. */
+export function latestClass(ctor: ComponentConstructor): ComponentConstructor {
+  const id = ids.get(ctor);
+  return id === undefined ? ctor : (records.get(id) as HotRecord).current;
+}
+
+export function isHotClass(ctor: ComponentConstructor): boolean {
+  return ids.has(ctor);
+}
+
+/** Records a mounted instance of a registered class until its scope is disposed. */
+export function trackHotInstance(hot: HotInstance): void {
+  const record = records.get(ids.get(hot.ctor) as string) as HotRecord;
+  record.instances.add(hot);
+  hot.scope.add(() => { record.instances.delete(hot); });
+}
+
+function flush(): void {
+  const records = [...stale];
+  stale.clear();
+  let error: unknown;
+  let failed = false;
+  for (const record of records) {
+    for (const hot of [...record.instances]) {
+      // Gone with a parent remounted before it, or already mounted with the new class.
+      if (!record.instances.has(hot) || hot.ctor === record.current) continue;
+      try {
+        (remount as (hot: HotInstance, ctor: ComponentConstructor) => void)(hot, record.current);
+      } catch (e) {
+        if (!failed) error = e;
+        failed = true;
+      }
+    }
+  }
+  if (failed) throw error;
+}
+
+/**
+ * Registers `ctor` under `id`. Called by the code the Vite plugin appends to each module in
+ * development, every time the module runs. Mounted instances of a class registered before under
+ * the same id are mounted again with `ctor`, in one microtask for every class of the update, so a
+ * parent and its children edited together render once. Returns false for a class that is not a
+ * component, which is not registered.
+ */
+export function registerHot(ctor: unknown, id: string): boolean {
+  if (!isComponent(ctor)) return false;
+  hotEnabled = true;
+  ids.set(ctor, id);
+  const record = records.get(id);
+  if (record === undefined) {
+    records.set(id, { current: ctor, instances: new Set() });
+  } else if (record.current !== ctor) {
+    record.current = ctor;
+    if (stale.size === 0) queueMicrotask(flush);
+    stale.add(record);
+  }
+  return true;
+}
+
+/**
+ * Whether an updated module can replace its previous version in place: every export is a
+ * registered component class. Anything else (a helper, a constant, a store) may be held by the
+ * modules that import it, so the update has to reach them (Vite then re-runs or reloads them).
+ */
+export function acceptsHotUpdate(module: Record<string, unknown> | undefined): boolean {
+  if (module === undefined) return false;
+  const values = Object.values(module);
+  return values.length > 0 && values.every((value) => typeof value === "function" && ids.has(value as ComponentConstructor));
+}

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";