solarite 0.7.1 → 0.9.0

package/src/PathToComponent.js

@@ -4,6 +4,7 @@ import delve, {isDelvePath} from "./delve.js";
 import assert from "./assert.js";
 import PathToAttribValue from "./PathToAttribValue.js";
 import PathToKey from "./PathToKey.js";
+import PathToEvent from "./PathToEvent.js";
 import Globals from "./Globals.js";
 import {getObjectHash} from "./Template.js";
 
@@ -23,15 +24,15 @@ export default class PathToComponent extends Path {
 	 * Call render() on the component pointed to by this Path.
 	 * And instantiate it (from a -solarite-placeholder element) if it hasn't been done yet.
 	 * @param exprs {Expr[][]} Expressions to evaluate for each attribute to pass to the constructor.
-	 * This is different than other Path.apply() functions which only receive Expr[] and not Expr[][].
+	 * This is different than other Path.applyAll() functions which only receive Expr[] and not Expr[][].
 	 * Because here we're receiving an array of arrays of expressions, one for each dynamic attribute. */
-	apply(exprs) {
-		//#IFDEV
+	applyAll(exprs) {
+		//#IFDEBUG
 		assert(Array.isArray(exprs));
 		assert(!exprs.length || Array.isArray(exprs[0]));
 		//#ENDIF
 
-		//#IFDEV
+		//#IFDEBUG
 		assert(exprs.length === this.attribPaths.length);
 		//#ENDIF
 
@@ -47,8 +48,15 @@ export default class PathToComponent extends Path {
 		for (let i=0, attribPath; attribPath = this.attribPaths[i]; i++) {
 			if (attribPath instanceof PathToKey) // The list key is never a component arg.
 				continue;
+			// Event attributes like onchange=${...} are bound with addEventListener when the
+			// PathToEvent itself is applied.  They must not also become constructor fields:
+			// a component that assigns its fields onto itself would set the native on*
+			// property, making the handler fire a second time with only the (event) argument
+			// instead of Solarite's documented (event, element) signature.
+			if (attribPath instanceof PathToEvent)
+				continue;
 			if (attribPath instanceof PathToAttribValue) {
-				let name = Util.dashesToCamel(attribPath.attrName);
+				let name = Util.dashesToCamel(attribPath.attribName);
 				
 				// Resolve two way bindimg path before we pass it to the component.
 				let value = attribPath.getValue(exprs[i]);
@@ -70,85 +78,120 @@ export default class PathToComponent extends Path {
 			}
 		}
 
-		// 2. Instantiate component on first time.
-		let isAttrib = el.getAttribute('_is');
-		if (el.tagName.endsWith('-SOLARITE-PLACEHOLDER') || isAttrib) {
+		// Constructing a component runs arbitrary user code -- field initializers, the
+		// constructor body, render() -- and that code can build more components, re-entering
+		// this method and overwriting the hand-off parked below.  Saving the caller's value
+		// here and restoring it in the finally makes the JS call stack the stack this hand-off
+		// needs, and unlike an explicit stack it cannot leak if construction throws.
+		let prevSlotChildren = Globals.currentSlotChildren;
+		try {
+			// 2. Instantiate component on first time.
+			let isAttrib = el.getAttribute('_is');
+			if (el.tagName.endsWith('-SOLARITE-PLACEHOLDER') || isAttrib) {
+
+
+				// 2a. Instantiate component
+				let tagName = (isAttrib || el.tagName.slice(0, -21)).toLowerCase(); // Remove -SOLARITE-PLACEHOLDER
+				let Constructor = customElements.get(tagName);
+
+				// Not defined yet (e.g. the module is being lazily imported): keep the placeholder
+				// and instantiate when the definition lands, like a native custom-element upgrade.
+				// deferredExprs always holds the LATEST exprs so re-renders while undefined win.
+				if (!Constructor) {
+					this.deferredExprs = exprs;
+					if (!this.whenDefinedPending) {
+						this.whenDefinedPending = true;
+						console.warn(`Solarite: <${tagName}> is not defined yet; waiting for customElements.define().`);
+						customElements.whenDefined(tagName).then(() => {
+							this.whenDefinedPending = false;
+							let deferred = this.deferredExprs;
+							this.deferredExprs = null;
+							// Skip if a newer render already instantiated or replaced the placeholder.
+							if (deferred && this.nodeMarker === el && el.tagName.endsWith('-SOLARITE-PLACEHOLDER'))
+								this.applyAll(deferred);
+						});
+					}
+					return;
+				}
 
+				// Hand the children declared inside the component's tag to the RootNodeGroup that
+				// its render() is about to create.  There is no other channel: the children have
+				// to be parked before new Constructor(), because a Solarite constructor may call
+				// this.render() itself, and the element that would otherwise carry them does not
+				// exist yet.
+				Globals.currentSlotChildren = {Constructor, nodes: [...el.childNodes]};
+				let newEl = new Constructor(attribs);
+
+				// 2b. Copy attributes over.
+				if (isAttrib) {
+					newEl.setAttribute('is', isAttrib);
+				//	el.removeAttribute('_is');
+				}
+				for (let attrib of el.attributes)
+					if (attrib.name !== '_is')
+						newEl.setAttribute(attrib.name, attrib.value);
+
+				// Set dynamic attributes if they are primitive types.
+				for (let name in attribs) {
+					let val = attribs[name];
+					let valType = typeof val;
+					// Only true and false can reach here, so the undefined/null halves of the
+					// falsy test this used to spell out could never have decided anything.
+					if (valType === 'boolean') {
+						if (val)
+							newEl.setAttribute(name, '');
+					}
+
+					// If type is a non-boolean primitive, set the attribute value.
+					else if (valType==='string' || valType === 'number' || valType==='bigint')
+						newEl.setAttribute(name, val);
+				}
 
-			// 2a. Instantiate component
-			let tagName = (isAttrib || el.tagName.slice(0, -21)).toLowerCase(); // Remove -SOLARITE-PLACEHOLDER
-			let Constructor = customElements.get(tagName);
-			if (!Constructor)
-				throw new Error(`Must call customElements.define('${tagName}', Class) before using it.`);
 
-			Globals.currentSlotChildren = [...el.childNodes]; // TODO: Does this need to be a stack?
-			let newEl = new Constructor(attribs);
+				// 2c. If an id pointed at the placeholder, update it to point to the new element.
+				let id = newEl.getAttribute('data-id') || newEl.getAttribute('id');
+				if (id)
+					delve(this.parentNg.getRootEl(), id.split(/\./g), newEl);
 
-			// 2b. Copy attributes over.
-			if (isAttrib) {
-				newEl.setAttribute('is', isAttrib);
-			//	el.removeAttribute('_is');
-			}
-			for (let attrib of el.attributes)
-				if (attrib.name !== '_is')
-					newEl.setAttribute(attrib.name, attrib.value);
-
-			// Set dynamic attributes if they are primitive types.
-			for (let name in attribs) {
-				let val = attribs[name];
-				let valType = typeof val;
-				if (valType === 'boolean') {
-					if (val !== false && val !== undefined && val !== null) // Util.isFalsy() inlined
-						newEl.setAttribute(name, '');
+				// 2d. Update paths to use replaced element.
+				let ng = this.parentNg;
+				this.nodeMarker = newEl;
+				for (let path of ng.paths) {
+					if (path.nodeMarker === el)
+						path.nodeMarker = newEl;
+					if (path.nodeBefore === el)
+						path.nodeBefore = newEl;
+				}
+				if (ng.startNode === el)
+					ng.startNode = newEl;
+				if (ng.endNode === el)
+					ng.endNode = newEl;
+
+				// 2f. Call render() if it wasn't called by the constructor.
+				// This must happen before we add it to the DOM which can trigger connectedCallback() -> renderFirstTime()
+				// Because that path renders it without the attribute expressions.
+				if (typeof newEl.render === 'function' && !Globals.rendered.has(newEl))
+					newEl.render(attribs, true);
+
+				// 2g. Update attribute paths to use the new element and re-apply them.
+				for (let i=0, attribPath; attribPath = this.attribPaths[i]; i++) {
+					attribPath.parentNg = this.parentNg;
+					attribPath.nodeMarker = newEl;
+					attribPath.applyAll(exprs[i]);
 				}
 
-				// If type is a non-boolean primitive, set the attribute value.
-				else if (valType==='string' || valType === 'number' || valType==='bigint')
-					newEl.setAttribute(name, val);
+				// 2e. Swap it to the DOM.
+				el.replaceWith(newEl);
 			}
 
+			// 2f. Render
+			else if (typeof el.render === 'function')
+				el.render(attribs, changed);
 
-			// 2c. If an id pointed at the placeholder, update it to point to the new element.
-			let id = newEl.getAttribute('data-id') || newEl.getAttribute('id');
-			if (id)
-				delve(this.parentNg.getRootNode(), id.split(/\./g), newEl);
-
-			// 2d. Update paths to use replaced element.
-			let ng = this.parentNg;
-			this.nodeMarker = newEl;
-			for (let path of ng.paths) {
-				if (path.nodeMarker === el)
-					path.nodeMarker = newEl;
-				if (path.nodeBefore === el)
-					path.nodeBefore = newEl;
-			}
-			if (ng.startNode === el)
-				ng.startNode = newEl;
-			if (ng.endNode === el)
-				ng.endNode = newEl;
-
-			// 2f. Call render() if it wasn't called by the constructor.
-			// This must happen before we add it to the DOM which can trigger connectedCallback() -> renderFirstTime()
-			// Because that path renders it without the attribute expressions.
-			if (typeof newEl.render === 'function' && !Globals.rendered.has(newEl))
-				newEl.render(attribs, true);
-
-			// 2g. Update attribute paths to use the new element and re-apply them.
-			for (let i=0, attribPath; attribPath = this.attribPaths[i]; i++) {
-				attribPath.parentNg = this.parentNg;
-				attribPath.nodeMarker = newEl;
-				attribPath.apply(exprs[i]);
-			}
-
-			// 2e. Swap it to the DOM.
-			el.replaceWith(newEl);
 		}
-
-		// 2f. Render
-		else if (typeof el.render === 'function')
-			el.render(attribs, changed);
-
-		Globals.currentSlotChildren = null;
+		finally {
+			Globals.currentSlotChildren = prevSlotChildren;
+		}
 	}
 
 	/**
@@ -156,21 +199,16 @@ export default class PathToComponent extends Path {
 	 * @param pathOffset {int}
 	 * @return {Path} */
 	clone(newRoot, pathOffset=0) {
-		/*#IFDEV*/this.verify();/*#ENDIF*/
-		let nodeMarker = this.getNewNodeMarker(newRoot, pathOffset);
-		let result = new PathToComponent(null, nodeMarker);
+		// A component path's nodeBefore is always null (the constructor discards it), so the
+		// base clone() resolves only the nodeMarker and hands back a new PathToComponent.
+		let result = super.clone(newRoot, pathOffset);
 		result.attribPaths = this.attribPaths.map(path => path.clone(newRoot, pathOffset));
-
-		//#IFDEV
-		result.verify();
-		//#ENDIF
-
 		return result;
 	}
 
 	getExpressionCount() { return 0 }
 
-	//#IFDEV
+	//#IFDEBUG
 	verify() {
 		super.verify();
 		assert(this.nodeMarker.nodeType === Node.ELEMENT_NODE);

package/src/PathToEvent.js

@@ -1,15 +1,35 @@
 import assert from "./assert.js";
-import PathToAttribValue from "./PathToAttribValue.js";
+import PathToAttribValue, {delegatedKeyFor} from "./PathToAttribValue.js";
+import {nativeEventPrefix} from "./Util.js";
 
 // TODO: Merge this into PathToAttribValue?
 export default class PathToEvent extends PathToAttribValue {
 
-	/** @type {string} The attrName without the "on" prefix. */
+	/** @type {string} The attribName without the "on" prefix. */
 	eventName;
 
-	constructor(nodeBefore, nodeMarker, attrName=null, attrValue=null) {
-		super(null, nodeMarker, attrName, attrValue);
-		this.eventName = attrName ? attrName.slice(2) : null;
+	/** @type {symbol|undefined} Expando key nodes store this event's delegated handler under.
+	 * Undefined for non-delegatable (non-bubbling) events; bindEvent() then binds directly. */
+	delegatedKey;
+
+	/** @type {boolean} True for `native:onclick`: the handler is registered with addEventListener
+	 * when the template renders, so it runs at its element's own turn in the browser's dispatch
+	 * order instead of being delegated to the component root. */
+	native;
+
+	constructor(nodeBefore, nodeMarker, attribName=null, attrValue=null) {
+		super(null, nodeMarker, attribName, attrValue);
+		this.skipIfSame = true;
+		let name = attribName;
+		this.native = name !== null && name.startsWith(nativeEventPrefix);
+		if (this.native)
+			name = name.slice(nativeEventPrefix.length);
+		this.eventName = name ? name.slice(2) : null;
+
+		// A native binding leaves delegatedKey undefined.  That is the single switch both
+		// bindEvent() and the compiled stamp program test to choose the direct
+		// addEventListener path, so nothing else has to know about the prefix.
+		this.delegatedKey = (this.eventName !== null && !this.native) ? delegatedKeyFor(this.eventName) : undefined;
 	}
 
 	/**
@@ -19,8 +39,8 @@ export default class PathToEvent extends PathToAttribValue {
 	 * onclick=${[this, 'doSomething', 'meow']}
 	 *
 	 * @param exprs {Expr[]} Only the first is used.*/
-	apply(exprs) {
-		//#IFDEV
+	applyAll(exprs) {
+		//#IFDEBUG
 		assert(Array.isArray(exprs));
 		//#ENDIF
 
@@ -28,7 +48,7 @@ export default class PathToEvent extends PathToAttribValue {
 		// We have expressions within a string attribute value that's not a Solarite event.  E.g.
 		// <div onclick="alert(${1});"
 		if (this.attrValue?.length > 1) {
-			super.apply(exprs);
+			super.applyAll(exprs);
 			return;
 		}
 
@@ -40,16 +60,16 @@ export default class PathToEvent extends PathToAttribValue {
 	applySingle(expr) {
 		// Expressions within a string attribute value that's not a Solarite event.
 		if (this.attrValue?.length > 1)
-			return super.apply([expr]);
+			return super.applyAll([expr]);
 
 		// Don't bind events to component placeholders.
 		// PathToComponent will do the binding later when it instantiates the component.
 		if (this.isComponentAttrib && this.nodeMarker.tagName.endsWith('-SOLARITE-PLACEHOLDER'))
 			return;
 
-		let root = this.parentNg.rootNg.root
+		let root = this.parentNg.rootNg.rootEl
 
-		/*#IFDEV*/
+		/*#IFDEBUG*/
 		assert(root?.nodeType === 1);
 		/*#ENDIF*/
 
@@ -67,7 +87,7 @@ export default class PathToEvent extends PathToAttribValue {
 			expr = null;
 		}
 		else
-			throw new Error(`Invalid event binding: <${node.tagName.toLowerCase()} ${this.attrName}=\${${JSON.stringify(expr)}}>`);
+			throw new Error(`Solarite: ${this.attribName}=\${...} is not a function.`);
 
 		this.bindEvent(node, root, eventName, eventName, func, expr);
 	}

package/src/PathToKey.js

@@ -7,12 +7,6 @@ import Path from "./Path.js";
  * matches NodeGroups to new templates by this key. */
 export default class PathToKey extends Path {
 
-	/**
-	 * @param exprs {Expr[]} Only the first is used. */
-	apply(exprs) {
-		this.parentNg.key = exprs[0];
-	}
-
 	applySingle(expr) {
 		this.parentNg.key = expr;
 	}