Event Delegation

Requirements

• Export delegate(container, type, selector, callback) as named and default. Register exactly one bubbling listener on container, without listeners on descendants.
• For each event, walk from its target toward container and invoke callback once for the nearest matching descendant. If the target is a text node, begin at its parent element. Never match container itself or an ancestor outside it.
• Call callback with (event, matchedElement), using matchedElement as this. Preserve the original event. Ignore events with no matching descendant.
• Support dynamically added descendants. Return an idempotent cleanup function that removes this listener without affecting other listeners or delegations.
• Validate the selector when delegate is called and propagate invalid-selector errors before registering. Non-bubbling events, shadow DOM retargeting, and capture mode are outside scope.

Examples

Input: const stop = delegate(container, "click", ".action", function(event, button) {
  console.log(button.textContent);
});
// Later:
stop();
Output: Only the closest matching descendant handles each click.

Input: container.appendChild(Object.assign(document.createElement("button"), { className: "action" }));
Output: New matching buttons are handled without registering new listeners.