solarite 0.8.0 → 0.9.0

package/src/PathToComponent.js

@@ -78,106 +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) {
-
-
-			// 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);
-					});
+		// 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;
 				}
-				Globals.currentSlotChildren = null;
-				return;
-			}
-
-			Globals.currentSlotChildren = [...el.childNodes]; // TODO: Does this need to be a stack?
-			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, '');
+				// 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);
 				}
 
-				// If type is a non-boolean primitive, set the attribute value.
-				else if (valType==='string' || valType === 'number' || valType==='bigint')
-					newEl.setAttribute(name, val);
-			}
 
+				// 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);
 
-			// 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);
+				// 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]);
+				}
 
-			// 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]);
+				// 2e. Swap it to the DOM.
+				el.replaceWith(newEl);
 			}
 
-			// 2e. Swap it to the DOM.
-			el.replaceWith(newEl);
-		}
-
-		// 2f. Render
-		else if (typeof el.render === 'function')
-			el.render(attribs, changed);
+			// 2f. Render
+			else if (typeof el.render === 'function')
+				el.render(attribs, changed);
 
-		Globals.currentSlotChildren = null;
+		}
+		finally {
+			Globals.currentSlotChildren = prevSlotChildren;
+		}
 	}
 
 	/**

package/src/PathToEvent.js

@@ -1,5 +1,6 @@
 import assert from "./assert.js";
 import PathToAttribValue, {delegatedKeyFor} from "./PathToAttribValue.js";
+import {nativeEventPrefix} from "./Util.js";
 
 // TODO: Merge this into PathToAttribValue?
 export default class PathToEvent extends PathToAttribValue {
@@ -11,11 +12,24 @@ export default class PathToEvent extends PathToAttribValue {
 	 * 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;
-		this.eventName = attribName ? attribName.slice(2) : null;
-		this.delegatedKey = this.eventName !== null ? delegatedKeyFor(this.eventName) : undefined;
+		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;
 	}
 
 	/**

package/src/RootNodeGroup.js

@@ -30,13 +30,30 @@ export default class RootNodeGroup extends NodeGroup {
 			if (el) {
 				this.rootEl = el;
 
-				// Save slot
-				// 1. Globals.currentSlotChildren is set if this is called via PathToComponent.applyComponent() calls render()
-				// 2. el.childNodes is set if render() is called manually for the first time.
+				// Save the children that belong in this component's <slot>, from one of two places:
+				// 1. A hand-off parked by PathToComponent.applyAll() just before it constructed
+				//    us, when this component was declared inside another template.  It carries
+				//    the Constructor it was meant for, so an unrelated component built in the
+				//    meantime -- a field initializer creating a menu, say -- leaves it alone.
+				// 2. el.childNodes, when render() is called manually for the first time.
+				// An addressed hand-off wins even when its node list is empty:  a component
+				// declared as <my-tag></my-tag> is asking for an empty slot, not for whatever
+				// its own constructor happened to put in the element.
+				//
+				// The hand-off is deliberately NOT cleared on read.  A component that builds
+				// another instance of its OWN class while constructing cannot be told apart
+				// from itself by any address, so both match; the inner one takes the nodes and
+				// this outer one takes them straight back, which is the only thing that makes
+				// that case work.
+				let handOff = Globals.currentSlotChildren;
+				let mySlotNodes = handOff?.Constructor === el.constructor
+					? handOff.nodes
+					: (el.childNodes.length ? [...el.childNodes] : null);
+
 				let slotChildren;
-				if (Globals.currentSlotChildren || el.childNodes.length) {
+				if (mySlotNodes) {
 					slotChildren = Globals.doc.createDocumentFragment();
-					slotChildren.append(...(Globals.currentSlotChildren || el.childNodes));
+					slotChildren.append(...mySlotNodes);
 				}
 
 				// If el should replace the root node of the fragment.

package/src/Shell.js

@@ -168,6 +168,9 @@ export default class Shell {
 		// Smaller fragments make cloning, path resolution, and insertion faster.
 		stripTableWhitespace(this.docFrag);
 
+		// 1c. Neutralize `is` so the browser can't upgrade a placeholder out from under us.
+		renameIsAttribs(this.docFrag);
+
 		// 2. Find placeholders
 		let node;
 		let toRemove = [];
@@ -181,7 +184,7 @@ export default class Shell {
 			
 			// Replace attributes
 			if (node.nodeType === 1) {
-				const hasIs = node.hasAttribute('is');
+				const hasIs = node.hasAttribute('_is'); // Renamed from `is` in step 1c.
 				const isComponent = (hasIs || node.tagName.includes('-'));
 				const componentAttribPaths = [];
 
@@ -285,10 +288,6 @@ export default class Shell {
 					path.attribPaths = componentAttribPaths;
 					this.paths.splice(this.paths.length - componentAttribPaths.length, 0, path); // Insert before its componentAttribPaths
 
-					if (hasIs) {
-						node.setAttribute('_is', node.getAttribute('is'));
-						node.removeAttribute('is');
-					}
 				}
 			}
 
@@ -305,7 +304,7 @@ export default class Shell {
 				// Components and slots are excluded because they move their children
 				// during instantiation, which would orphan the expression's region.
 				if (parent.nodeType === 1 && !node.previousSibling && !node.nextSibling
-					&& !parent.tagName.includes('-') && parent.tagName !== 'SLOT' && !parent.hasAttribute('is')) {
+					&& !parent.tagName.includes('-') && parent.tagName !== 'SLOT' && !parent.hasAttribute('_is')) {
 					let path = new PathToNodes(null, parent);
 					path.wholeParent = true;
 					this.paths.push(path);
@@ -719,6 +718,38 @@ function stripTableWhitespace(el) {
 	}
 }
 
+/**
+ * Rename every `is` attribute to `_is`, rebuilding the element to do it.
+ *
+ * A component written as a dashed tag is neutralized in the shell by renaming the TAG
+ * (`<my-tag>` becomes `<my-tag-SOLARITE-PLACEHOLDER>`), so the browser never recognizes the
+ * placeholder and never upgrades it.  A customized built-in cannot be neutralized that way,
+ * because its tag has to stay real:  a `<tr is="my-row">` that is not a `<tr>` is thrown out
+ * by the parser's table rules.  So its ATTRIBUTE is renamed instead.
+ *
+ * Renaming the attribute in place is not enough.  `is` is also recorded in an internal slot on
+ * the element, which removeAttribute() cannot clear and cloneNode() copies, so a placeholder
+ * that was parsed with `is` stays a customized built-in as far as the browser is concerned.
+ * Every clone of it is upgraded the moment it enters a document with a browsing context —
+ * running the component's constructor on the placeholder, before PathToComponent has
+ * instantiated the real element or evaluated the attribute expressions meant for it.  A
+ * constructor that renders then renders the placeholder, whose children are the ones the user
+ * declared, and those get handed to the real instance as if they were slot content.
+ *
+ * Building a fresh element and moving everything across is the only way to drop that slot.
+ * It happens once per unique template, because Shells are cached, and never per render.
+ *
+ * @param docFrag {DocumentFragment} */
+function renameIsAttribs(docFrag) {
+	for (let el of docFrag.querySelectorAll('[is]')) {
+		let clean = el.ownerDocument.createElement(el.tagName);
+		for (let attrib of el.attributes)
+			clean.setAttribute(attrib.name === 'is' ? '_is' : attrib.name, attrib.value);
+		clean.append(...el.childNodes);
+		el.replaceWith(clean);
+	}
+}
+
 // One-entry memo for Shell.get().
 let lastHtmlStrings = null, lastSvgMode = false, lastShell = null;
 

package/src/Solarite.d.ts

@@ -10,17 +10,19 @@ export interface RenderOptions {
     ids?: boolean;
     render?: boolean;
 
-    /** Defaults to true: bubbling events (click, input, etc.) dispatch from one listener on
-     * the component's root element instead of addEventListener per element - much faster
-     * creation and teardown of large lists.  Pass false to bind every event directly, or an
-     * array to delegate only the listed event names.  Pass 'document' to also register the
-     * dispatcher on the document, so handlers keep firing on nodes that get re-parented
-     * outside the component (e.g. a toolbar a dock parks in its own chrome).  Non-bubbling
-     * events always bind directly.  Note: delegated handlers run when the event bubbles to
-     * the root (or document), so stopPropagation() in a manually added listener on an element
-     * in between suppresses them, and such manual listeners fire first.  A programmatically
-     * dispatched non-bubbling event won't reach delegated handlers. */
-    eventDelegation?: boolean | string[] | 'document';
+    /**
+     * Delegate bubbling events (default true).  A handler is stored on its element instead of
+     * registered with addEventListener, and when an event of that type starts, a capture-phase
+     * listener on the component root and the document attaches a real listener to each element
+     * on the event's path that has one; the browser then dispatches normally.  Much faster
+     * creation and teardown of large lists, with native ordering, stopPropagation(),
+     * currentTarget, non-bubbling events and moved elements all behaving as with
+     * addEventListener.  The one difference: a delegated handler is attached when the event
+     * starts, so it runs after listeners other code added to the same element.  Prefix an
+     * attribute with native: (native:onclick) to bind just that handler at render time.
+     * Pass false to bind every event directly, or an array to delegate only the listed event
+     * names.  Non-bubbling events always bind directly. */
+    eventDelegation?: boolean | string[];
 }
 
 /**
@@ -183,7 +185,7 @@ export function delve(obj: object, path: string[], createVal?: any): any;
  * Internal utilities and state. */
 export const Globals: {
     connected: WeakSet<HTMLElement>;
-    currentSlotChildren: any[] | null;
+    currentSlotChildren: {Constructor: Function, nodes: Node[]} | null;
     div: HTMLDivElement;
     doc: Document;
     elementClasses: {[key: string]: typeof Node};

package/src/Util.js

@@ -1,6 +1,12 @@
 import Globals from "./Globals.js";
 import delve from "./delve.js";
 
+/**
+ * Prefix that asks for a handler to bypass event delegation: `<button native:onclick=\${...}>`
+ * is bound with addEventListener at render time, taking its normal place in the browser's own
+ * dispatch order.  Shared by Util.isEvent() and PathToEvent, which strips it. */
+export const nativeEventPrefix = 'native:';
+
 let Util = {
 
 	/**
@@ -200,7 +206,14 @@ let Util = {
 		return node.value; // String
 	},
 
+	/**
+	 * True for an attribute name that binds an event: `onclick`, or `native:onclick` for a
+	 * handler that is registered with addEventListener when the template renders instead of
+	 * being delegated.  Only names an element really exposes as on* handlers count, so an
+	 * attribute like `online` is never mistaken for one. */
 	isEvent(attribName) {
+		if (attribName.startsWith(nativeEventPrefix))
+			attribName = attribName.slice(nativeEventPrefix.length);
 		return attribName.startsWith('on') && attribName in Globals.div;
 	},