solarite 0.7.0 → 0.8.0

package/src/Path.js

@@ -39,6 +39,23 @@ export default class Path {
 	 * @type {Node[]} Cached result of getNodes() */
 	nodesCache;
 
+	/** @type {boolean|undefined} True when this path provides an attribute of a web component
+	 * (a -solarite-placeholder element).  Only attribute paths ever set it true, but it's
+	 * declared here on every Path because clone() and cloneWithNodes() copy it to every clone;
+	 * declaring it keeps those stores from transitioning the clone's hidden class. */
+	isComponentAttrib;
+
+	/** @type {boolean} True when re-applying an expression identical to the one already
+	 * applied is provably a no-op, so a re-render can skip this path entirely.  Only event
+	 * bindings qualify: binding the same handler to the same node again changes nothing,
+	 * while an attribute or a child expression may have been altered outside the template. */
+	skipIfSame = false;
+
+	/** @type {boolean|undefined} True when the attribute is a live HTML property
+	 * (checked/value/selected — Util.isHtmlProp), which users can flip underneath the
+	 * template.  Declared here for the same hidden-class reason as isComponentAttrib. */
+	isHtmlProperty;
+
 	// Set only on Shell paths, never on cloned instances, so they're not declared as
 	// class fields; that would cost a store per field on every clone:
 	// nodeBeforeIndex {int} Index of nodeBefore among its parentNode's children.
@@ -52,7 +69,7 @@ export default class Path {
 	constructor(nodeBefore, nodeMarker) {
 		this.nodeBefore = nodeBefore;
 		this.nodeMarker = nodeMarker;
-		/*#IFDEV*/this.verify();/*#ENDIF*/
+		/*#IFDEBUG*/this.verify();/*#ENDIF*/
 	}
 
 	/**
@@ -74,7 +91,12 @@ export default class Path {
 	 * [[expr5], [expr6, expr7]] // arguments to second my-component constructor.
 	 * [expr5]                   // user attribute value.
 	 * [expr6, expr7]            // role attribute value. */
-	apply(exprs) {}
+	applyAll(exprs) {
+		//#IFDEBUG
+		assert(Array.isArray(exprs));
+		//#ENDIF
+		this.applySingle(exprs[0]);
+	}
 
 	/**
 	 * Fast path used by NodeGroup.applyExprs() when every path consumes exactly one expression.
@@ -84,26 +106,12 @@ export default class Path {
 
 	getExpressionCount() { return 1 }
 
-
 	/**
-	 * Resolve nodeMarkerPath to new root.
-	 * TODO: Make clone() use this.*/
-	getNewNodeMarker(newRoot, pathOffset) {
-		let root = newRoot;
-		let path = this.nodeMarkerPath;
-		let pathLength = path.length - pathOffset;
-		for (let i=pathLength-1; i>0; i--) { // Resolve the path.
-			//#IFDEV
-			assert(root.childNodes[path[i]]);
-			//#ENDIF
-			root = root.childNodes[path[i]];
-		}
-		let childNodes = root.childNodes;
-
-		return pathLength
-			? childNodes[path[0]]
-			: newRoot;
-	}
+	 * The value a path hands to a component constructor, for the single-expression paths.
+	 * PathToAttribValue overrides this to join its surrounding static strings.
+	 * @param exprs {Expr[]}
+	 * @return {Expr} */
+	getValue(exprs) { return exprs[0] }
 
 
 	/**
@@ -113,7 +121,7 @@ export default class Path {
 	 * @param nodeMarker {Node}
 	 * @return {Path} */
 	cloneWithNodes(nodeBefore, nodeMarker) {
-		let result = new this.constructor(nodeBefore, nodeMarker, this.attrName, this.attrValue);
+		let result = new this.constructor(nodeBefore, nodeMarker, this.attribName, this.attrValue);
 		result.isComponentAttrib = this.isComponentAttrib;
 		result.wholeParent = this.wholeParent;
 		result.isHtmlProperty = this.isHtmlProperty;
@@ -125,41 +133,25 @@ export default class Path {
 	 * @param pathOffset {int}
 	 * @return {Path} */
 	clone(newRoot, pathOffset=0) {
-		/*#IFDEV*/this.verify();/*#ENDIF*/
-
-		// Resolve node paths.
-		let nodeMarker, nodeBefore;
-		let root = newRoot;
-		let path = this.nodeMarkerPath;
-		let pathLength = path.length - pathOffset;
-		for (let i=pathLength-1; i>0; i--) { // Resolve the path.
-			//#IFDEV
-			assert(root.childNodes[path[i]]);
-			//#ENDIF
-			root = root.childNodes[path[i]];
-		}
-		let childNodes = root.childNodes;
-
-		nodeMarker = pathLength
-			? childNodes[path[0]]
-			: newRoot;
+		/*#IFDEBUG*/this.verify();/*#ENDIF*/
+
+		// Resolve node paths.  nodeBefore is always a sibling of nodeMarker (Shell builds it from
+		// nodeMarker.previousSibling, or inserts a comment immediately before it), so the list
+		// nodeBeforeIndex counts within is the marker's own parent's childNodes.  An empty path
+		// leaves the marker as newRoot itself, and then that list is newRoot's children.
+		let nodeBefore;
+		let nodeMarker = Path.resolve(newRoot, this.nodeMarkerPath, pathOffset);
 		if (this.nodeBefore) {
-			//#IFDEV
+			let childNodes = (nodeMarker === newRoot ? newRoot : nodeMarker.parentNode).childNodes;
+			//#IFDEBUG
 			assert(childNodes[this.nodeBeforeIndex]);
 			//#ENDIF
 			nodeBefore = childNodes[this.nodeBeforeIndex];
-
 		}
 
-		let result = new this.constructor(nodeBefore, nodeMarker, this.attrName, this.attrValue);
-
-		result.isComponentAttrib = this.isComponentAttrib;
-		result.wholeParent = this.wholeParent;
-
-		// TODO: Put this in PathToAttribValue.clone().
-		result.isHtmlProperty = this.isHtmlProperty;
+		let result = this.cloneWithNodes(nodeBefore, nodeMarker);
 
-		//#IFDEV
+		//#IFDEBUG
 		result.verify();
 		//#ENDIF
 
@@ -183,14 +175,21 @@ export default class Path {
 	 * Note that the path is backward, with the outermost element at the end.
 	 * @param root {HTMLElement|Document|DocumentFragment|ParentNode}
 	 * @param path {int[]}
+	 * @param skip {int} How many of the outermost steps to leave off, for when root is
+	 *   already that many levels down from where the path was recorded.  An empty walk
+	 *   (skip === path.length) returns root itself.
 	 * @returns {Node|HTMLElement|HTMLStyleElement} */
-	static resolve(root, path) {
-		for (let i=path.length-1; i>=0; i--)
+	static resolve(root, path, skip=0) {
+		for (let i=path.length-1-skip; i>=0; i--) {
+			//#IFDEBUG
+			assert(root.childNodes[path[i]]);
+			//#ENDIF
 			root = root.childNodes[path[i]];
+		}
 		return root;
 	}
 
-	//#IFDEV
+	//#IFDEBUG
 
 	/** @return {HTMLElement|ParentNode} */
 	getParentNode() {

package/src/PathToAttribValue.js

@@ -2,32 +2,30 @@ import Path from "./Path.js";
 import Util from "./Util.js";
 import delve, {isDelvePath} from "./delve.js";
 import assert from "./assert.js";
+import {SelectorRef} from "./Selector.js";
 
 export default class PathToAttribValue extends Path {
 
 	/** @type {?string} Used only if type=AttribType.Value. */
-	attrName;
+	attribName;
 
 	/**
 	 * @type {?string[]} Used only if type=AttribType.Value. If null, use one expr to set the whole attribute value. */
 	attrValue;
 
-	/** @type {boolean} Provides value for attribute on a component. */
-	isComponent;
+	// isComponentAttrib and isHtmlProperty are declared on the Path base class.
 
-	isHtmlProperty;
-
-	constructor(nodeBefore, nodeMarker, attrName=null, attrValue=null) {
+	constructor(nodeBefore, nodeMarker, attribName=null, attrValue=null) {
 		super(null, nodeMarker);
-		this.attrName = attrName;
+		this.attribName = attribName;
 		this.attrValue = attrValue;
 	}
 
 	/**
 	 * Set the value of an attribute.  This can be for any attribute, not just attributes named "value".
 	 * @param exprs {Expr[]} */
-	apply(exprs) {
-		//#IFDEV
+	applyAll(exprs) {
+		//#IFDEBUG
 		assert(Array.isArray(exprs));
 		//#ENDIF
 
@@ -40,14 +38,14 @@ export default class PathToAttribValue extends Path {
 			// Only update attributes if the value has changed.
 			// This is needed for setting input.value, .checked, option.selected, etc.
 			let oldVal = isProp
-				? node[this.attrName]
-				: node.getAttribute(this.attrName);
+				? node[this.attribName]
+				: node.getAttribute(this.attribName);
 			if (oldVal !== joinedValue) {
 				if (isProp)
-					node[this.attrName] = joinedValue;
-				else if (this.attrName === 'value' && node.hasAttribute('contenteditable'))
+					node[this.attribName] = joinedValue;
+				else if (this.attribName === 'value' && node.hasAttribute('contenteditable'))
 					node.innerHTML = joinedValue;
-				node.setAttribute(this.attrName, joinedValue);
+				node.setAttribute(this.attribName, joinedValue);
 			}
 		}
 		else
@@ -60,7 +58,7 @@ export default class PathToAttribValue extends Path {
 	applySingle(expr) {
 		// One expression surrounded by strings, e.g. class="a ${b} c".  Join through apply().
 		if (this.attrValue)
-			return this.apply([expr]);
+			return this.applyAll([expr]);
 
 		let node = this.nodeMarker;
 
@@ -81,12 +79,12 @@ export default class PathToAttribValue extends Path {
 			let [obj, path] = [expr[0], expr.slice(1)];
 
 			if (!obj)
-				throw new Error(`Solarite cannot bind to <${node.tagName.toLowerCase()} ${this.attrName}=\${[${expr.map(item => item ? `'${item}'` : item+'').join(', ')}]}>.`);
+				throw new Error(`Solarite cannot bind ${this.attribName} to ${obj}.`);
 
 			let value = delve(obj, path);
 
 			// Special case to allow setting select-multiple value from an array
-			if (this.attrName === 'value' && node.type === 'select-multiple' && Array.isArray(value)) {
+			if (this.attribName === 'value' && node.type === 'select-multiple' && Array.isArray(value)) {
 				// Set the .selected property on the options having a value within value.
 				let strValues = value.map(v => v + '');
 				for (let option of node.options)
@@ -102,7 +100,7 @@ export default class PathToAttribValue extends Path {
 				const strValue = Util.isFalsy(value) ? '' : value;
 
 				// Special case for contenteditable
-				if (this.attrName === 'value' && node.hasAttribute('contenteditable')) {
+				if (this.attribName === 'value' && node.hasAttribute('contenteditable')) {
 					const existingValue = node.innerHTML;
 					if (strValue !== existingValue)
 						node.innerHTML = strValue;
@@ -111,28 +109,39 @@ export default class PathToAttribValue extends Path {
 
 					// If we don't have this condition, when we call render(), the browser will scroll to the currently
 					// selected item in a <select> and mess up manually scrolling to a different value.
-					if (strValue !== node[this.attrName])
-						node[this.attrName] = strValue;
+					if (strValue !== node[this.attribName])
+						node[this.attribName] = strValue;
 				}
 			}
 
 			// TODO: We need to remove any old listeners, like in bindEventAttribute.
 			// Does bindEvent() now handle that?
 			let func = () => {
-				let value = (this.attrName === 'value' || node.type === 'radio')
+				let value = (this.attribName === 'value' || node.type === 'radio')
 					? Util.getInputValue(node)
-					: node[this.attrName];
+					: node[this.attribName];
 				delve(obj, path, value);
 			}
 
 			// We use capture so we update the values before other events added by the user.
 			// TODO: Bind to scroll events also?
 			// What about resize events and width/height?
-			this.bindEvent(node, this.parentNg.getRootNode(), this.attrName, 'input', func, null, true);
+			this.bindEvent(node, this.parentNg.getRootEl(), this.attribName, 'input', func, null, true);
 		}
 
 		// Regular attribute
 		else {
+			// A selection binding (h.selector().when()) writes its own value and tells the
+			// selector which list this row belongs to, so a later change of selection reaches
+			// the attribute directly instead of going back through render().  The typeof test
+			// keeps ordinary string attributes — nearly all of them — from paying for the
+			// prototype check.
+			if (typeof expr === 'object' && expr instanceof SelectorRef) {
+				if (!this.isComponentAttrib)
+					expr.bind(node, this.attribName, this.parentNg);
+				return;
+			}
+
 			// Cache this on Path.isHtmlProperty when Shell creates the props.
 			// Have Path.clone() copy .isHtmlProperty?
 			let isProp = this.isHtmlProperty;
@@ -145,43 +154,53 @@ export default class PathToAttribValue extends Path {
 			else
 				expr = Util.makePrimitive(expr);
 
-			// Values to toggle an attribute
-			if (expr === undefined || expr === false || expr === null) { // Util.isFalsy() inlined.
-				if (isProp)
-					node[this.attrName] = false;
-				node.removeAttribute(this.attrName);
+			// Values that remove an attribute.  The empty string is included so that an attribute
+			// disappears whenever its expression is empty, instead of only when it happened to be
+			// absent already.  makePrimitive() above turns null into '', so plain null lands here
+			// too; the explicit null test still matters for a function expression returning null,
+			// which skips makePrimitive.
+			// An html property is exempt: on those, '' is a real value meaning "empty", as when
+			// clearing an <input>, so it belongs on the assignment path below.
+			if (expr === undefined || expr === false || expr === null || (expr === '' && !isProp)) {
+				if (isProp) {
+					// Clear the property with a value of its own type.  Assigning false to a string
+					// property such as input.value would put the text "false" in the field.
+					let old = node[this.attribName];
+					node[this.attribName] = typeof old === 'boolean' ? false : '';
+				}
+				node.removeAttribute(this.attribName);
 			}
 			else if (expr === true) {
 				if (isProp)
-					node[this.attrName] = true;
-				node.setAttribute(this.attrName, '');
+					node[this.attribName] = true;
+				node.setAttribute(this.attribName, '');
 			}
 
 			// A non-toggled attribute
 			else {
 				// Only update attributes if the value has changed.
 				// This is needed for setting input.value, .checked, option.selected, etc.
-				// A missing attribute counts as '', so empty values don't write empty attributes.
+				// Non-property attributes never reach here with '', since that removes above.
 				let oldVal = isProp
-					? node[this.attrName]
-					: node.getAttribute(this.attrName) ?? '';
+					? node[this.attribName]
+					: node.getAttribute(this.attribName) ?? '';
 				if (oldVal !== expr) {
 
 					// <textarea value=${expr}></textarea>
 					// Without this branch we have no way to set the value of a textarea,
 					// since we also prohibit expressions that are a child of textarea.
 					if (isProp)
-						node[this.attrName] = expr;
+						node[this.attribName] = expr;
 
 						// Allow one-way binding to contenteditable value attribute.
 						// Contenteditables normally don't have a value attribute and have their content set via innerHTML.
 					// Solarite doesn't allow contenteditables to have expressions as their children.
-					else if (this.attrName === 'value' && node.hasAttribute('contenteditable')) {
+					else if (this.attribName === 'value' && node.hasAttribute('contenteditable')) {
 						node.innerHTML = expr;
 					}
 
 					// TODO: Putting an 'else' here would be more performant
-					node.setAttribute(this.attrName, expr);
+					node.setAttribute(this.attribName, expr);
 				}
 			}
 		}
@@ -195,14 +214,14 @@ export default class PathToAttribValue extends Path {
 	 * @return {string} The joined values of the expressions, or the first expression if there are no strings. */
 	getValue(exprs) {
 
-		//#IFDEV
+		//#IFDEBUG
 		assert(Array.isArray(exprs));
 		//#ENDIF
 		//if (!Array.isArray(exprs))
 		//	return exprs;
 
 		if (!this.attrValue) {// If it's not multiple paths inside a single attribute, return first (and only) expression.
-			//#IFDEV
+			//#IFDEBUG
 			assert(exprs.length === 1);
 			//#ENDIF
 			return exprs[0];
@@ -213,6 +232,18 @@ export default class PathToAttribValue extends Path {
 		for (let i = 0; i < values.length; i++) {
 			result.push(values[i]);
 			if (i < values.length - 1) {
+				// A selection binding has to own the whole attribute, because its whole point is
+				// writing that attribute without re-rendering, which it can't do if the rest of
+				// the value comes from expressions it doesn't know about.  Whether a selector sits
+				// inside a multi-part attribute is fixed by the shape of the template and never by
+				// the data, so this can only be an authoring mistake, and it always surfaces on the
+				// template's very first render -- exactly like the placement check in
+				// SelectorRef.bind().  That makes it safe to strip from the built file, where the
+				// throw is the only thing lost: makePrimitive() then turns the ref into '' and the
+				// attribute is written from its constant parts alone.  Stripping it also keeps a
+				// per-expression instanceof out of the multi-part attribute loop.
+				if (typeof exprs[i] === 'object' && exprs[i] instanceof SelectorRef)
+					throw new Error(`Solarite: a selector must own the whole ${this.attribName} attribute.`);
 				let val = Util.makePrimitive(exprs[i]);
 				if (!Util.isFalsy(val))
 					result.push(val);
@@ -233,17 +264,41 @@ export default class PathToAttribValue extends Path {
 	/**
 	 * @param funcAndArgs {?Array} The [func, ...args] array from the template, or null if func stands alone. */
 	bindEvent(node, root, key, eventName, func, funcAndArgs, capture=false) {
+		//#IFDEBUG
+		// Both callers already guarantee a function, so this only catches a future third caller.
+		// PathToEvent.applySingle() rejects every shape a template can produce and names the
+		// offending value, and the two-way binding path above passes a closure it just made
+		// here, so nothing a page author writes can reach this line.  That makes it dev-only:
+		// stripping it from the built file costs no diagnostic that the surviving throw in
+		// PathToEvent doesn't already give, with a better message.
 		if (typeof func !== 'function')
-			throw new Error(`Solarite cannot bind to <${node.tagName.toLowerCase()} ${this.attrName}=\${${func}}> because it's not a function.`);
+			throw new Error(`Solarite cannot bind to <${node.tagName.toLowerCase()} ${this.attribName}=\${${func}}> because it's not a function.`);
+		//#ENDIF
 
-		// Whether to delegate is decided in registerBinding(), which only runs for a NEW binding.
-		// Re-renders rebind existing rows (just updating binding.args below), so they skip the
-		// options lookup + delegatableEvents check entirely.
-		let options = this.parentNg.rootNg.options;
+		// Delegated path: a bubbling event (when the root's options allow it, the default)
+		// stores its handler directly on the node as a per-event-type Symbol expando, with no
+		// EventBinding object and no addEventListener call.  The root-level dispatcher reads
+		// these expandos while walking up from the event target.  Re-renders just overwrite
+		// the property.  this.delegatedKey is set by the PathToEvent constructor only for
+		// delegatable event names, so this test also excludes non-bubbling events.
+		if (capture === false && this.delegatedKey !== undefined) {
+			let opt = this.parentNg.rootNg.renderOptions?.eventDelegation ?? true;
+			let toDocument = opt === 'document';
+			if (opt !== false && (opt === true || toDocument || opt.includes(eventName))) {
+				let dk = this.delegatedKey;
+				if (node[dk] === undefined) // First binding of this type on this node.
+					ensureDelegatedDispatcher(root, eventName, toDocument);
+				// Array-form bindings (onclick=${[fn, arg]}, the hot per-row case) store the
+				// template's own [func, ...args] array; a plain function is stored bare.
+				// Either way, nothing is allocated.
+				node[dk] = funcAndArgs || func;
+				node[delegatedRootKey] = root;
+				return;
+			}
+		}
 
-		// Store the callable as a single [func, ...args] array.  Array-form bindings
-		// (onclick=${[fn, arg]}, the hot per-row case) pass it through with no allocation;
-		// a plain function allocates a one-element array, which is rare (buttons, two-way).
+		// Direct path: capture bindings, non-bubbling events, and eventDelegation:false.
+		// Store the callable as a single [func, ...args] array.
 		let args = funcAndArgs || [func];
 
 		// One stable EventBinding object per node+key is registered with addEventListener
@@ -253,7 +308,7 @@ export default class PathToAttribValue extends Path {
 		let nodeEvents = node[eventBindingsKey];
 		if (nodeEvents === undefined) {
 			let b = node[eventBindingsKey] = new EventBinding(root, node, key, args);
-			registerBinding(b, node, eventName, capture, options, root);
+			node.addEventListener(eventName, b, capture);
 			return;
 		}
 
@@ -271,7 +326,7 @@ export default class PathToAttribValue extends Path {
 				let map = node[eventBindingsKey] = {};
 				map[nodeEvents.key] = nodeEvents;
 				binding = map[key] = new EventBinding(root, node, key, args);
-				registerBinding(binding, node, eventName, capture, options, root);
+				node.addEventListener(eventName, binding, capture);
 				return;
 			}
 		}
@@ -279,11 +334,11 @@ export default class PathToAttribValue extends Path {
 			binding = nodeEvents[key];
 			if (!binding) {
 				binding = nodeEvents[key] = new EventBinding(root, node, key, args);
-				registerBinding(binding, node, eventName, capture, options, root);
+				node.addEventListener(eventName, binding, capture);
 				return;
 			}
 		}
-		binding.root = root;
+		binding.rootEl = root;
 		binding.args = args;
 	}
 }
@@ -304,73 +359,99 @@ export function getEventBinding(node, key) {
 	return b instanceof EventBinding ? (b.key === key ? b : undefined) : b[key];
 }
 
-/**
- * Attach a new EventBinding either directly or through the root component's delegated
- * dispatcher.  The dispatcher lives on the root element (not the document) so a component
- * still receives delegated events while detached from the document, and events stay scoped
- * to the component that rendered them. */
-function registerBinding(binding, node, eventName, capture, options, root) {
-	// Bubbling events are delegated by default: they skip addEventListener entirely, and one
-	// root-level dispatcher per event type finds bindings by walking up from the event target.
-	// eventDelegation:false opts out; an array delegates only the named events.  Capture
-	// bindings and non-bubbling events always stay direct.
-	let delegate = false;
-	if (capture === false) {
-		let opt = options?.eventDelegation ?? true;
-		if (opt !== false && delegatableEvents.has(eventName))
-			delegate = opt === true || opt.includes(eventName);
-	}
-
-	if (delegate) {
-		binding.delegated = true;
-		let types = root[delegatedTypesKey];
-		if (types === undefined)
-			types = root[delegatedTypesKey] = new Set();
-		if (!types.has(eventName)) {
-			types.add(eventName);
-			root.addEventListener(eventName, delegatedDispatcher);
-		}
-	}
-	else
-		node.addEventListener(eventName, binding, capture);
-}
-
 // Bubbling events that one root-level listener can dispatch.  Same set Solid.js delegates.
 const delegatableEvents = new Set(['beforeinput', 'click', 'contextmenu', 'dblclick', 'focusin', 'focusout',
 	'input', 'keydown', 'keyup', 'mousedown', 'mousemove', 'mouseout', 'mouseover', 'mouseup',
 	'pointerdown', 'pointermove', 'pointerout', 'pointerover', 'pointerup', 'touchend', 'touchmove', 'touchstart']);
 
+// One Symbol per delegated event type; nodes store their delegated handler under it.
+// Symbols (vs string expandos like Solid's $$click) can't collide with user properties.
+const delegatedKeys = {};
+
+/**
+ * Get the per-event-type Symbol key, or undefined for non-delegatable events.
+ * Called once per PathToEvent construction, never per bind.
+ * @param eventName {string}
+ * @return {symbol|undefined} */
+export function delegatedKeyFor(eventName) {
+	if (!delegatableEvents.has(eventName))
+		return undefined;
+	return delegatedKeys[eventName] ??= Symbol('sol$' + eventName);
+}
+
+// The component root a node's delegated handlers run with as `this`.
+// Exported so NodeGroup.applyStamp()'s compiled stamp program can write it directly.
+export const delegatedRootKey = Symbol('solariteDelegatedRoot');
+
 // Per-root-element Set of event types that already have a delegated dispatcher registered.
 const delegatedTypesKey = Symbol('solariteDelegatedTypes');
 
+/**
+ * Register the delegated dispatcher for eventName on root if it isn't already.
+ * Shared by bindEvent()'s delegated branch and NodeGroup.applyStamp()'s stamp program.
+ *
+ * With andDocument (the eventDelegation:'document' render option), the dispatcher is also
+ * registered on the document, once per event type: a bound node that gets re-parented
+ * OUTSIDE its root (e.g. a toolbar a dock parks in its own chrome) bubbles past the root's
+ * listener, and only a document-level listener can still reach its handler.  The
+ * delegatedDoneKey marker keeps the two dispatchers from double-running the same event.
+ * @param root {HTMLElement}
+ * @param eventName {string}
+ * @param andDocument {boolean} */
+export function ensureDelegatedDispatcher(root, eventName, andDocument=false) {
+	let types = root[delegatedTypesKey];
+	if (types === undefined)
+		types = root[delegatedTypesKey] = new Set();
+	if (!types.has(eventName)) {
+		types.add(eventName);
+		root.addEventListener(eventName, delegatedDispatcher);
+	}
+	if (andDocument) {
+		let doc = root.ownerDocument ?? document;
+		let docTypes = doc[delegatedTypesKey];
+		if (docTypes === undefined)
+			docTypes = doc[delegatedTypesKey] = new Set();
+		if (!docTypes.has(eventName)) {
+			docTypes.add(eventName);
+			doc.addEventListener(eventName, delegatedDispatcher);
+		}
+	}
+}
+
 // Marks an event the innermost root dispatcher has already walked, so an outer root's
 // listener (when components are nested) skips it instead of dispatching the bindings again.
 const delegatedDoneKey = Symbol('solariteDelegated');
 
 /**
  * The per-root listener for each delegated event type.  The first (innermost) root the
- * bubbling event reaches walks from the event target upward, invoking delegated
- * EventBindings stored on the nodes along the way; outer roots then see the done-marker and
- * skip.  Each binding carries its own root, so handlers in an outer component still run with
- * the correct `this`.  event.currentTarget is patched to the node whose binding is running,
- * and restored after.  stopPropagation() inside a handler ends the walk, mirroring native
- * bubbling. */
+ * bubbling event reaches walks from the event target upward, invoking delegated handlers
+ * stored on the nodes along the way; outer roots then see the done-marker and skip.
+ * Each node carries the root its handlers run with as `this` (see delegatedRootKey), so
+ * handlers in an outer component still run with the correct component.  event.currentTarget
+ * is patched to the node whose handler is running, and restored after.  stopPropagation()
+ * inside a handler ends the walk, mirroring native bubbling. */
 function delegatedDispatcher(ev) {
 	if (ev[delegatedDoneKey])
 		return;
 	ev[delegatedDoneKey] = true;
-	let type = ev.type;
+	let dk = delegatedKeys[ev.type];
 	let current = ev.target;
 	Object.defineProperty(ev, 'currentTarget', {configurable: true, get() { return current }});
 	while (current) {
-		let b = current[eventBindingsKey];
-		if (b !== undefined) {
-			let binding = b instanceof EventBinding ? b : b[type];
-			if (binding !== undefined && binding.delegated === true && binding.key === type) {
-				binding.handleEvent(ev);
-				if (ev.cancelBubble)
-					break;
-			}
+		let a = current[dk];
+		if (a !== undefined) {
+			let root = current[delegatedRootKey];
+			if (typeof a === 'function')
+				a.call(root, ev, current);
+			else
+				switch (a.length) {
+					case 1: a[0].call(root, ev, current); break;
+					case 2: a[0].call(root, a[1], ev, current); break;
+					case 3: a[0].call(root, a[1], a[2], ev, current); break;
+					default: a[0].call(root, ...a.slice(1), ev, current);
+				}
+			if (ev.cancelBubble)
+				break;
 		}
 		current = current.parentNode;
 	}
@@ -379,7 +460,7 @@ function delegatedDispatcher(ev) {
 
 class EventBinding {
 	constructor(root, node, key, args) {
-		this.root = root;
+		this.rootEl = root;
 		this.node = node;
 		this.key = key;
 
@@ -393,10 +474,10 @@ class EventBinding {
 	'handleEvent'(event) {
 		let a = this.args;
 		switch (a.length) {
-			case 1: return a[0].call(this.root, event, this.node);
-			case 2: return a[0].call(this.root, a[1], event, this.node);
-			case 3: return a[0].call(this.root, a[1], a[2], event, this.node);
+			case 1: return a[0].call(this.rootEl, event, this.node);
+			case 2: return a[0].call(this.rootEl, a[1], event, this.node);
+			case 3: return a[0].call(this.rootEl, a[1], a[2], event, this.node);
 		}
-		return a[0].call(this.root, ...a.slice(1), event, this.node);
+		return a[0].call(this.rootEl, ...a.slice(1), event, this.node);
 	}
 }