@praxisjs/runtime 0.7.1 → 0.8.1

package/src/dom/constants.ts

@@ -29,99 +29,42 @@ export const SVG_TAGS = new Set([
   "foreignObject",
 ]);
 
-export const EVENT_MAP: Record<string, string> = {
+// Event props and the DOM event each one listens to. Every prop is "on" + the event name in camel
+// case and listens to that name in lowercase, so only the camel-case names are spelled out, which
+// keeps the table small in bundles. A Map: looking a prop up is a single probe.
+export const EVENT_MAP: ReadonlyMap<string, string> = /* @__PURE__ */ eventMap(
   // Mouse
-  onClick: "click",
-  onDblClick: "dblclick",
-  onMouseDown: "mousedown",
-  onMouseUp: "mouseup",
-  onMouseEnter: "mouseenter",
-  onMouseLeave: "mouseleave",
-  onMouseMove: "mousemove",
-  onMouseOver: "mouseover",
-  onMouseOut: "mouseout",
-  onContextMenu: "contextmenu",
+  "Click DblClick MouseDown MouseUp MouseEnter MouseLeave MouseMove MouseOver MouseOut ContextMenu " +
   // Keyboard
-  onKeyDown: "keydown",
-  onKeyUp: "keyup",
-  onKeyPress: "keypress",
+  "KeyDown KeyUp KeyPress " +
   // Focus
-  onFocus: "focus",
-  onBlur: "blur",
+  "Focus Blur " +
   // Pointer
-  onPointerDown: "pointerdown",
-  onPointerUp: "pointerup",
-  onPointerMove: "pointermove",
-  onPointerEnter: "pointerenter",
-  onPointerLeave: "pointerleave",
-  onPointerOver: "pointerover",
-  onPointerOut: "pointerout",
-  onPointerCancel: "pointercancel",
-  onGotPointerCapture: "gotpointercapture",
-  onLostPointerCapture: "lostpointercapture",
+  "PointerDown PointerUp PointerMove PointerEnter PointerLeave PointerOver PointerOut PointerCancel " +
+  "GotPointerCapture LostPointerCapture " +
   // Touch
-  onTouchStart: "touchstart",
-  onTouchEnd: "touchend",
-  onTouchMove: "touchmove",
+  "TouchStart TouchEnd TouchMove " +
   // Drag
-  onDrag: "drag",
-  onDragStart: "dragstart",
-  onDragEnd: "dragend",
-  onDragEnter: "dragenter",
-  onDragLeave: "dragleave",
-  onDragOver: "dragover",
-  onDrop: "drop",
+  "Drag DragStart DragEnd DragEnter DragLeave DragOver Drop " +
   // Scroll / Wheel
-  onScroll: "scroll",
-  onScrollEnd: "scrollend",
-  onWheel: "wheel",
+  "Scroll ScrollEnd Wheel " +
   // Form
-  onChange: "change",
-  onInput: "input",
-  onBeforeInput: "beforeinput",
-  onSubmit: "submit",
-  onReset: "reset",
-  onSelect: "select",
-  onInvalid: "invalid",
+  "Change Input BeforeInput Submit Reset Select Invalid " +
   // Clipboard
-  onCopy: "copy",
-  onCut: "cut",
-  onPaste: "paste",
+  "Copy Cut Paste " +
   // Composition (IME)
-  onCompositionStart: "compositionstart",
-  onCompositionUpdate: "compositionupdate",
-  onCompositionEnd: "compositionend",
+  "CompositionStart CompositionUpdate CompositionEnd " +
   // Resource
-  onLoad: "load",
-  onError: "error",
+  "Load Error " +
   // Animation / Transition
-  onAnimationEnd: "animationend",
-  onTransitionEnd: "transitionend",
+  "AnimationEnd TransitionEnd " +
   // Element-specific (details, dialog, popover)
-  onToggle: "toggle",
-  onBeforeToggle: "beforetoggle",
-  onClose: "close",
-  onCancel: "cancel",
+  "Toggle BeforeToggle Close Cancel " +
   // Media
-  onAbort: "abort",
-  onCanPlay: "canplay",
-  onCanPlayThrough: "canplaythrough",
-  onDurationChange: "durationchange",
-  onEmptied: "emptied",
-  onEnded: "ended",
-  onLoadedData: "loadeddata",
-  onLoadedMetadata: "loadedmetadata",
-  onLoadStart: "loadstart",
-  onPause: "pause",
-  onPlay: "play",
-  onPlaying: "playing",
-  onProgress: "progress",
-  onRateChange: "ratechange",
-  onSeeked: "seeked",
-  onSeeking: "seeking",
-  onStalled: "stalled",
-  onSuspend: "suspend",
-  onTimeUpdate: "timeupdate",
-  onVolumeChange: "volumechange",
-  onWaiting: "waiting",
-};
+  "Abort CanPlay CanPlayThrough DurationChange Emptied Ended LoadedData LoadedMetadata LoadStart Pause Play " +
+  "Playing Progress RateChange Seeked Seeking Stalled Suspend TimeUpdate VolumeChange Waiting",
+);
+
+function eventMap(names: string): Map<string, string> {
+  return new Map(names.split(" ").map((name) => [`on${name}`, name.toLowerCase()]));
+}

package/src/dom/create.ts

@@ -1,7 +1,7 @@
 import { SVG_NAMESPACE, SVG_TAGS } from "./constants";
 
-export function createElement(tag: string): HTMLElement | SVGElement {
+export function createElement(tag: string, doc: Document = document): HTMLElement | SVGElement {
   return SVG_TAGS.has(tag)
-    ? (document.createElementNS(SVG_NAMESPACE, tag))
-    : document.createElement(tag);
+    ? (doc.createElementNS(SVG_NAMESPACE, tag))
+    : doc.createElement(tag);
 }

package/src/dom/events.ts

@@ -1,21 +1,34 @@
-import { batch } from "@praxisjs/core/internal";
+import { endBatch, startBatch } from "@praxisjs/core/internal";
+
+import { EVENT_MAP } from "./constants";
 
 import type { Scope } from "../scope";
 
-// One wrapper per handler keeps addEventListener's dedupe of an identical listener intact.
-const batchedHandlers = new WeakMap<EventListener, EventListener>();
+type Handler = (this: Element, event: Event) => unknown;
+type HandlerSlot = Handler | Handler[];
+
+const HANDLERS = Symbol("praxis.handlers");
+
+interface HandlerHost {
+  [HANDLERS]?: Record<string, HandlerSlot | undefined>;
+}
 
-// Handlers run inside batch() so several signal writes in one event flush their effects once,
-// instead of re-running the same reactive subtree after every write.
-function batched(handler: EventListener): EventListener {
-  let wrapper = batchedHandlers.get(handler);
-  if (!wrapper) {
-    wrapper = function (this: Element, event) {
-      batch(() => { handler.call(this, event); });
-    };
-    batchedHandlers.set(handler, wrapper);
+// One shared listener per element and event type dispatches to the handlers stored on the
+// element, so binding a handler allocates no wrapper. Handlers run inside a batch so several
+// signal writes in one event flush their effects once.
+function dispatch(this: Element, event: Event): void {
+  const slot = (this as HandlerHost)[HANDLERS]?.[event.type];
+  if (slot === undefined) return;
+  startBatch();
+  try {
+    if (typeof slot === "function") {
+      slot.call(this, event);
+    } else {
+      for (const handler of slot.slice()) handler.call(this, event);
+    }
+  } finally {
+    endBatch();
   }
-  return wrapper;
 }
 
 export function addEvent(
@@ -27,7 +40,162 @@ export function addEvent(
   // Components forward optional handlers (`onSubmit={this.onSubmit}`) as-is, and addEventListener
   // has always treated a missing listener as a no-op.
   if (handler == null) return;
-  const listener = typeof handler === "function" ? batched(handler) : handler;
-  el.addEventListener(eventName, listener);
-  scope.add(() => { el.removeEventListener(eventName, listener); });
+  if (typeof handler !== "function") {
+    el.addEventListener(eventName, handler);
+    scope.add(() => { el.removeEventListener(eventName, handler); });
+    return;
+  }
+  const host = el as HandlerHost;
+  const handlers = (host[HANDLERS] ??= {});
+  const slot = handlers[eventName];
+  if (slot === undefined) {
+    // `in` tells a slot emptied by a disposed scope (listener still attached) from a new event type.
+    if (!(eventName in handlers)) el.addEventListener(eventName, dispatch);
+    handlers[eventName] = handler as Handler;
+  } else if (typeof slot === "function") {
+    // Same as addEventListener: registering an identical listener twice is a no-op.
+    if (slot === handler) return;
+    handlers[eventName] = [slot, handler as Handler];
+  } else {
+    if (slot.includes(handler as Handler)) return;
+    slot.push(handler as Handler);
+  }
+  scope.listen(el, eventName, handler);
+}
+
+// ── Delegated binding (compiled templates) ──────────────────────────────────
+
+// A delegated handler is stored on its element under a per-type key, together with the scope that
+// bound it and that scope's generation: disposing the scope bumps the generation, which turns the
+// handler off without any per-handler cleanup. No listener is attached when it is bound. One capture
+// listener per event type, on the document and on every render container, attaches the element's own
+// listener the first time an event of that type is on its way to it. Listeners are read when the
+// event reaches each node, so the new one runs for that very event, at its own element and phase:
+// order, `this`, `currentTarget` and `stopPropagation()` behave exactly as with a listener attached
+// at render time. Render containers cover trees that are not in the document.
+
+type DelegatedHost = Record<symbol, unknown>;
+
+const OWNER = Symbol("praxis.owner");
+const GENERATION = Symbol("praxis.generation");
+export interface DelegatedType {
+  /** The event prop (`onClick`), under which a hydration build pass records the handler. */
+  key: string;
+  type: string;
+  /** Holds an element's handler for this type. */
+  slot: symbol;
+  /** Set once the element's own listener for this type is attached. */
+  attached: symbol;
+  /** The capture listeners for this type are registered. */
+  watched: boolean;
+}
+
+// Every event prop maps to its own event type (EVENT_MAP has no two props for one type), so an
+// entry is created once per prop and found by type when an event comes in.
+const byType = new Map<string, DelegatedType>();
+// Keyed by event prop name (`onClick`), so binding a handler costs one lookup. `null` marks a prop
+// that is not an event.
+const byProp = new Map<string, DelegatedType | null>();
+const watched: DelegatedType[] = [];
+const roots = new Set<EventTarget>();
+
+/** The delegated event type an event prop binds, or null when `key` is not an event prop. */
+export function delegatedProp(key: string): DelegatedType | null {
+  let entry = byProp.get(key);
+  if (entry === undefined) {
+    const type = EVENT_MAP.get(key);
+    entry = null;
+    if (type !== undefined) {
+      entry = { key, type, slot: Symbol(`praxis.on.${type}`), attached: Symbol(`praxis.attached.${type}`), watched: false };
+      byType.set(type, entry);
+    }
+    byProp.set(key, entry);
+  }
+  return entry;
+}
+
+function dispatchDelegated(this: Element, event: Event): void {
+  const host = this as unknown as DelegatedHost;
+  const handler = host[(byType.get(event.type) as DelegatedType).slot] as Handler | undefined;
+  if (handler === undefined || (host[OWNER] as { gen: number }).gen !== host[GENERATION]) return;
+  startBatch();
+  try {
+    handler.call(this, event);
+  } finally {
+    endBatch();
+  }
+}
+
+function attachOnDemand(this: EventTarget, event: Event): void {
+  const { type, slot, attached } = byType.get(event.type) as DelegatedType;
+  for (const node of event.composedPath()) {
+    if (node === this) return;
+    const host = node as unknown as DelegatedHost;
+    if (host[slot] !== undefined && host[attached] === undefined) {
+      host[attached] = true;
+      node.addEventListener(type, dispatchDelegated);
+    }
+  }
+}
+
+function watchType(entry: DelegatedType): void {
+  entry.watched = true;
+  watched.push(entry);
+  document.addEventListener(entry.type, attachOnDemand, true);
+  for (const root of roots) root.addEventListener(entry.type, attachOnDemand, true);
+}
+
+/**
+ * Registers a render container (or portal target) whose subtree gets delegated handlers even while
+ * it is not in the document. Returns the function that unregisters it.
+ */
+export function addEventRoot(root: EventTarget): () => void {
+  roots.add(root);
+  for (const entry of watched) root.addEventListener(entry.type, attachOnDemand, true);
+  return () => {
+    roots.delete(root);
+    for (const entry of watched) root.removeEventListener(entry.type, attachOnDemand, true);
+  };
+}
+
+/**
+ * Binds `handler` for the event of `entry` (see delegatedProp) on `el` without attaching a
+ * listener now (see above). Falls back to addEvent when no render container is registered (an
+ * element mounted outside render()), when the element already has a delegated handler for this
+ * type, or when it was bound by another scope.
+ */
+export function addDelegatedEvent(el: Element, entry: DelegatedType, handler: unknown, scope: Scope & { gen: number }): void {
+  if (handler == null) return;
+  const host = el as unknown as DelegatedHost;
+  const key = entry.slot;
+  if (
+    roots.size === 0 ||
+    typeof handler !== "function" ||
+    host[key] !== undefined ||
+    (host[OWNER] !== undefined && host[OWNER] !== scope)
+  ) {
+    addEvent(el, entry.type, handler as EventListener, scope);
+    return;
+  }
+  if (!entry.watched) watchType(entry);
+  host[key] = handler;
+  host[OWNER] = scope;
+  host[GENERATION] = scope.gen;
+}
+
+export function removeListener(el: Element, eventName: string, handler: unknown): void {
+  const handlers = (el as HandlerHost)[HANDLERS];
+  const slot = handlers?.[eventName];
+  if (handlers === undefined || slot === undefined) return;
+  if (typeof slot === "function") {
+    if (slot !== handler) return;
+    // The shared listener stays registered: with an empty slot it does nothing, and leaving it
+    // saves a native call per handler when thousands of rows are disposed at once.
+    handlers[eventName] = undefined;
+    return;
+  }
+  const index = slot.indexOf(handler as Handler);
+  if (index === -1) return;
+  slot.splice(index, 1);
+  if (slot.length === 1) handlers[eventName] = slot[0];
 }

package/src/dom/props.ts

@@ -1,4 +1,4 @@
-import { untrack } from "@praxisjs/core/internal";
+import { untrack, type EffectNode } from "@praxisjs/core/internal";
 
 import { EVENT_MAP } from "./constants";
 import { addEvent } from "./events";
@@ -8,7 +8,15 @@ import type { Scope } from "../scope";
 function applyClass(el: Element, value: unknown): void {
   if (value === null || value === undefined) {
     el.removeAttribute("class");
+  } else if (el instanceof HTMLElement) {
+    // eslint-disable-next-line @typescript-eslint/no-base-to-string
+    const next = String(value);
+    // Reading is cheap; writing invalidates the element's style even when nothing changes, which
+    // is what a first binding run does on every element whose class starts empty.
+    if (el.className !== next) el.className = next;
   } else {
+    // SVG elements expose className as an SVGAnimatedString, so the attribute is the way in (as
+    // for any element of another kind, or of another window).
     // eslint-disable-next-line @typescript-eslint/no-base-to-string
     el.setAttribute("class", String(value));
   }
@@ -34,7 +42,11 @@ function applyStyle(el: Element, value: unknown): void {
 }
 
 function applyAttr(el: Element, key: string, value: unknown): void {
-  if (value === false || value === null || value === undefined) {
+  if (typeof value === "boolean" && key.startsWith("aria-")) {
+    // ARIA states are the strings "true" and "false", not HTML boolean attributes: an empty or
+    // missing aria-selected/aria-expanded reads as unset to assistive technology.
+    el.setAttribute(key, value ? "true" : "false");
+  } else if (value === false || value === null || value === undefined) {
     el.removeAttribute(key);
   } else if (value === true) {
     el.setAttribute(key, "");
@@ -62,7 +74,7 @@ function lookupWritable(proto: object, key: string): boolean {
 // must be excluded here or assignment below throws. The prototype walk is cached per
 // prototype because every element of a given tag repeats the same lookups; a property defined on
 // a prototype after its first lookup (e.g. a late polyfill) is therefore not picked up.
-function hasWritableProperty(el: Element, key: string): boolean {
+export function hasWritableProperty(el: Element, key: string): boolean {
   const own = Object.getOwnPropertyDescriptor(el, key);
   if (own) return own.set !== undefined || own.writable === true;
 
@@ -80,7 +92,7 @@ function hasWritableProperty(el: Element, key: string): boolean {
   return writable;
 }
 
-function setProp(el: Element, key: string, value: unknown): void {
+export function setProp(el: Element, key: string, value: unknown): void {
   if (key === "class" || key === "className") {
     applyClass(el, value);
   } else if (key === "style") {
@@ -110,17 +122,66 @@ export function applyProp(
     return;
   }
 
-  if (normalizedKey in EVENT_MAP) {
-    addEvent(el, EVENT_MAP[normalizedKey], value as EventListener, scope);
+  // Every event prop starts with "on": checking that first keeps other props off the map lookup.
+  const type = normalizedKey.startsWith("on") ? EVENT_MAP.get(normalizedKey) : undefined;
+  if (type !== undefined) {
+    addEvent(el, type, value as EventListener, scope);
     return;
   }
 
   if (typeof value === "function") {
-    scope.effect(() => {
-      setProp(el, normalizedKey, (value as () => unknown)());
-    });
+    bindProp(el, normalizedKey, value as () => unknown, scope);
     return;
   }
 
   setProp(el, normalizedKey, value);
 }
+
+// State the user can change behind a binding's back (typing, toggling a <details>, the media
+// controls, scrolling): always written, so a re-run puts the bound value back exactly as before.
+const LIVE_PROPS = new Set([
+  "value", "checked", "selected", "indeterminate", "selectedIndex", "open",
+  "muted", "volume", "currentTime", "playbackRate", "scrollTop", "scrollLeft",
+]);
+const UNSET = Symbol("unset");
+
+interface PropBinding {
+  el: Element;
+  key: string;
+  read: () => unknown;
+  last: unknown;
+}
+
+// One function for every binding, reading its state from the effect: no closure per binding.
+function runBinding(this: EffectNode<PropBinding>): void {
+  const binding = this.ctx;
+  const value = binding.read();
+  // A binding re-runs when anything it read changes; most re-runs produce the same primitive,
+  // and skipping that write saves a DOM call and the style or attribute work behind it.
+  if (value === binding.last && (typeof value !== "object" || value === null)) return;
+  binding.last = value;
+  setProp(binding.el, binding.key, value);
+}
+
+function runLiveBinding(this: EffectNode<PropBinding>): void {
+  const binding = this.ctx;
+  setProp(binding.el, binding.key, binding.read());
+}
+
+function bindProp(el: Element, key: string, read: () => unknown, scope: Scope): void {
+  scope.contextEffect(LIVE_PROPS.has(key) ? runLiveBinding : runBinding, { el, key, read, last: UNSET });
+}
+
+function runClassBinding(this: EffectNode<PropBinding>): void {
+  const binding = this.ctx;
+  const value = binding.read();
+  if (value === binding.last && (typeof value !== "object" || value === null)) return;
+  binding.last = value;
+  applyClass(binding.el, value);
+}
+
+/** A reactive `class` prop, bound like any other reactive prop but with no key dispatch per run. */
+export function bindClass(el: Element, read: () => unknown, scope: Scope): void {
+  // Same record shape as bindProp's, so the effects of both kinds stay one shape.
+  scope.contextEffect(runClassBinding, { el, key: "class", read, last: UNSET });
+}

package/src/dom/range.ts

@@ -0,0 +1,45 @@
+type MovableParent = Node & {
+  moveBefore?: (node: Node, child: Node | null) => void;
+};
+
+// moveBefore() keeps focus, iframes, playing media and running CSS animations/transitions of the
+// moved subtree, which a remove + insert resets. It only applies inside a connected tree (both nodes
+// already share the parent here), so a detached parent such as a DocumentFragment uses insertBefore.
+export function moveNode(parent: Node, node: Node, ref: Node | null): void {
+  const target = parent as MovableParent;
+  if (target.moveBefore !== undefined && target.isConnected) {
+    target.moveBefore(node, ref);
+  } else {
+    parent.insertBefore(node, ref);
+  }
+}
+
+// Every node from `first` to `last` (inclusive) moves, not only the tracked ones, so anything a
+// nested reactive child inserted between them after mount travels with them.
+export function moveRange(parent: Node, first: Node, last: Node, ref: Node | null): void {
+  if (first === last) {
+    moveNode(parent, first, ref);
+    return;
+  }
+  let node: Node = first;
+  for (;;) {
+    const next = node.nextSibling as Node;
+    moveNode(parent, node, ref);
+    if (node === last) return;
+    node = next;
+  }
+}
+
+export function removeRange(parent: Node, first: Node, last: Node): void {
+  if (first === last) {
+    parent.removeChild(first);
+    return;
+  }
+  let node: Node = first;
+  for (;;) {
+    const next = node.nextSibling as Node;
+    parent.removeChild(node);
+    if (node === last) return;
+    node = next;
+  }
+}

package/src/dom/remove.ts

@@ -1,3 +1,5 @@
+import { removeRange } from "./range";
+
 // Replaces Range.deleteContents(): creating a Range per removal is several times slower than
 // walking the siblings, and unreachable Ranges stay registered with the document until collected.
 // Walking first → last (rather than only the tracked nodes) also removes anything a nested reactive
@@ -12,11 +14,5 @@ export function removeNodes(nodes: Node[]): void {
     return;
   }
 
-  let node: Node | null = first;
-  while (node) {
-    const next: Node | null = node.nextSibling;
-    parent.removeChild(node);
-    if (node === last) return;
-    node = next;
-  }
+  removeRange(parent, first, last);
 }

package/src/element.ts

@@ -1,7 +1,7 @@
 import { mountChildren } from "./children";
 import { createElement } from "./dom/create";
 import { applyProp } from "./dom/props";
-import { isRecording, recordProps } from "./hydration-context";
+import { recording, recordProps } from "./hydration-context";
 
 import type { Scope } from "./scope";
 
@@ -14,16 +14,18 @@ export function mountElement(
 
   // During a hydration build pass, retain (props, scope) so reconcile() can
   // replay them onto whichever real element it ends up keeping instead.
-  if (isRecording()) recordProps(el, props, scope);
+  if (recording) recordProps(el, props, scope);
+
+  // Children before props: a prop that depends on them (a <select>'s value picking one of its
+  // options, a ref reading the subtree) would otherwise run against an empty element.
+  if (props.children !== undefined) {
+    mountChildren(el, props.children, scope);
+  }
 
   for (const key in props) {
     if (key === "children") continue;
     applyProp(el, key, props[key], scope);
   }
 
-  if (props.children !== undefined) {
-    mountChildren(el, props.children, scope);
-  }
-
   return el;
 }