@wordpress/compose 7.46.0 → 8.0.0

package/src/utils/subscribe-delegated-listener/index.ts

@@ -0,0 +1,128 @@
+/**
+ * Adds a callback to a shared `addEventListener`. Only one underlying
+ * native listener is attached per (root, event type, phase); subscribers
+ * join an in-JS registry that dispatches events along the DOM ancestry
+ * of `event.target`.
+ *
+ * The model mirrors React's synthetic event system: a single root
+ * listener handles every event of a given type, and callbacks bound to
+ * an `Element` only fire when that element is on the target's path.
+ * Callbacks bound to a `Document` always fire (document is the root of
+ * every event in that document); callbacks bound to a `Window` always
+ * fire as a flat fan-out, since `window` isn't on the DOM tree.
+ *
+ * @param target    `Element`, `Document`, or `Window` to bind the
+ *                  callback to. For `Element`, the callback only fires
+ *                  when the event happens on the element or a
+ *                  descendant.
+ * @param eventType DOM event name.
+ * @param callback  Listener to be invoked with the event.
+ * @param capture   Use the capture phase. Required when ancestor
+ *                  listeners gate on `event.defaultPrevented`, since a
+ *                  bubble-phase root listener fires after them. Defaults
+ *                  to `false`.
+ * @return Unsubscribe function.
+ */
+// root -> eventTypeKey -> subscribedTarget -> Set<callback>
+//
+// Inner registry is a `WeakMap`: element subscribers are held weakly so
+// an iframe removal lets the iframe's Elements (and through them, its
+// `ownerDocument`) be garbage-collected. The native listener is
+// attached to the document itself, so it goes when the document goes.
+const registries = new WeakMap<
+	EventTarget,
+	Map< string, WeakMap< EventTarget, Set< EventListener > > >
+>();
+
+export default function subscribeDelegatedListener(
+	target: EventTarget,
+	eventType: string,
+	callback: EventListener,
+	capture: boolean = false
+): () => void {
+	// Where the native listener is attached:
+	//   Element  → its `ownerDocument`
+	//   Document → itself (own `ownerDocument` is `null`)
+	//   Window   → itself (no `ownerDocument` property)
+	// `undefined` (Window) → use a fan-out branch on dispatch since
+	// events bubble *to* window but never *from* it via `parentNode`.
+	const ownerDoc = ( target as Node ).ownerDocument;
+	const root = ownerDoc ?? target;
+	const isWindow = ownerDoc === undefined;
+
+	let perRoot = registries.get( root );
+	if ( ! perRoot ) {
+		perRoot = new Map();
+		registries.set( root, perRoot );
+	}
+	const key = capture ? `${ eventType }:capture` : eventType;
+	let perEvent = perRoot.get( key );
+	if ( ! perEvent ) {
+		perEvent = new WeakMap< EventTarget, Set< EventListener > >();
+		perRoot.set( key, perEvent );
+		const subscribers = perEvent;
+		root.addEventListener(
+			eventType,
+			( event ) => {
+				if ( isWindow ) {
+					// Window has no DOM ancestry — all subscribers share
+					// the window key; fetch its set and fan out.
+					const set = subscribers.get( root );
+					if ( set ) {
+						for ( const cb of set ) {
+							cb( event );
+						}
+					}
+					return;
+				}
+				// Walk the target → root ancestry, dispatching callbacks
+				// for any node in the path. Bubble order matches the walk
+				// direction, so dispatch inline (no path array). Capture
+				// has to materialise the path to iterate in reverse.
+				if ( capture ) {
+					const path: Array< Node | Document > = [];
+					let current: Node | null = event.target as Node | null;
+					while ( current ) {
+						path.push( current );
+						if ( current === root ) {
+							break;
+						}
+						current = current.parentNode;
+					}
+					for ( let i = path.length - 1; i >= 0; i-- ) {
+						const set = subscribers.get( path[ i ] );
+						if ( set ) {
+							for ( const cb of set ) {
+								cb( event );
+							}
+						}
+					}
+				} else {
+					let current: Node | null = event.target as Node | null;
+					while ( current ) {
+						const set = subscribers.get( current );
+						if ( set ) {
+							for ( const cb of set ) {
+								cb( event );
+							}
+						}
+						if ( current === root ) {
+							break;
+						}
+						current = current.parentNode;
+					}
+				}
+			},
+			capture
+		);
+	}
+	let set = perEvent.get( target );
+	if ( ! set ) {
+		set = new Set();
+		perEvent.set( target, set );
+	}
+	set.add( callback );
+	return () => {
+		set.delete( callback );
+	};
+}

package/src/utils/subscribe-delegated-listener/test/index.js

@@ -0,0 +1,170 @@
+/**
+ * Internal dependencies
+ */
+import subscribeDelegatedListener from '..';
+
+describe( 'subscribeDelegatedListener', () => {
+	let root;
+	let target;
+
+	beforeEach( () => {
+		// Build a nested DOM:
+		//   document.body > #outer > #inner > #leaf
+		root = document.createElement( 'div' );
+		root.id = 'outer';
+		const inner = document.createElement( 'div' );
+		inner.id = 'inner';
+		target = document.createElement( 'span' );
+		target.id = 'leaf';
+		inner.appendChild( target );
+		root.appendChild( inner );
+		document.body.appendChild( root );
+	} );
+
+	afterEach( () => {
+		document.body.removeChild( root );
+	} );
+
+	function fire( element, type = 'click', init = { bubbles: true } ) {
+		element.dispatchEvent( new Event( type, init ) );
+	}
+
+	test( 'invokes element subscriber when event fires on that element', () => {
+		const cb = jest.fn();
+		subscribeDelegatedListener( target, 'click', cb );
+		fire( target );
+		expect( cb ).toHaveBeenCalledTimes( 1 );
+	} );
+
+	test( 'invokes element subscriber when event fires on a descendant', () => {
+		const cb = jest.fn();
+		const child = document.createElement( 'b' );
+		target.appendChild( child );
+		subscribeDelegatedListener( target, 'click', cb );
+		fire( child );
+		expect( cb ).toHaveBeenCalledTimes( 1 );
+	} );
+
+	test( 'does not invoke element subscriber when event fires outside its subtree', () => {
+		const cb = jest.fn();
+		const sibling = document.createElement( 'div' );
+		document.body.appendChild( sibling );
+		subscribeDelegatedListener( target, 'click', cb );
+		fire( sibling );
+		expect( cb ).not.toHaveBeenCalled();
+		document.body.removeChild( sibling );
+	} );
+
+	test( 'bubble phase: nested subscribers fire inner-to-outer', () => {
+		const order = [];
+		subscribeDelegatedListener( root, 'click', () =>
+			order.push( 'outer' )
+		);
+		subscribeDelegatedListener( target, 'click', () =>
+			order.push( 'leaf' )
+		);
+		fire( target );
+		expect( order ).toEqual( [ 'leaf', 'outer' ] );
+	} );
+
+	test( 'capture phase: nested subscribers fire outer-to-inner', () => {
+		const order = [];
+		subscribeDelegatedListener(
+			root,
+			'click',
+			() => order.push( 'outer' ),
+			true
+		);
+		subscribeDelegatedListener(
+			target,
+			'click',
+			() => order.push( 'leaf' ),
+			true
+		);
+		fire( target );
+		expect( order ).toEqual( [ 'outer', 'leaf' ] );
+	} );
+
+	test( 'capture and bubble registries are independent', () => {
+		const captureCb = jest.fn();
+		const bubbleCb = jest.fn();
+		subscribeDelegatedListener( target, 'click', captureCb, true );
+		subscribeDelegatedListener( target, 'click', bubbleCb, false );
+		fire( target );
+		expect( captureCb ).toHaveBeenCalledTimes( 1 );
+		expect( bubbleCb ).toHaveBeenCalledTimes( 1 );
+	} );
+
+	test( 'document subscriber always fires for events in the document', () => {
+		const cb = jest.fn();
+		subscribeDelegatedListener( document, 'click', cb );
+		fire( target );
+		expect( cb ).toHaveBeenCalledTimes( 1 );
+	} );
+
+	test( 'window subscriber fans out independently of element subscribers', () => {
+		const winCb = jest.fn();
+		const elCb = jest.fn();
+		subscribeDelegatedListener( window, 'resize', winCb );
+		subscribeDelegatedListener( target, 'resize', elCb );
+		window.dispatchEvent( new Event( 'resize' ) );
+		expect( winCb ).toHaveBeenCalledTimes( 1 );
+		// Element subscriber doesn't see a resize on window.
+		expect( elCb ).not.toHaveBeenCalled();
+	} );
+
+	test( 'multiple callbacks for the same element all fire', () => {
+		const a = jest.fn();
+		const b = jest.fn();
+		subscribeDelegatedListener( target, 'click', a );
+		subscribeDelegatedListener( target, 'click', b );
+		fire( target );
+		expect( a ).toHaveBeenCalledTimes( 1 );
+		expect( b ).toHaveBeenCalledTimes( 1 );
+	} );
+
+	test( 'unsubscribe stops further dispatch', () => {
+		const cb = jest.fn();
+		const unsub = subscribeDelegatedListener( target, 'click', cb );
+		fire( target );
+		expect( cb ).toHaveBeenCalledTimes( 1 );
+		unsub();
+		fire( target );
+		expect( cb ).toHaveBeenCalledTimes( 1 );
+	} );
+
+	test( 'attaches one native listener per (root, eventType, phase) regardless of subscriber count', () => {
+		const spy = jest.spyOn( document, 'addEventListener' );
+		// First subscribe attaches the native listener; subsequent ones
+		// for the same key share it.
+		subscribeDelegatedListener( target, 'mousemove', jest.fn() );
+		subscribeDelegatedListener( root, 'mousemove', jest.fn() );
+		subscribeDelegatedListener( document, 'mousemove', jest.fn() );
+		const nativeMousemoves = spy.mock.calls.filter(
+			( [ type, , opts ] ) => type === 'mousemove' && ! opts // bubble-phase only
+		).length;
+		expect( nativeMousemoves ).toBe( 1 );
+		spy.mockRestore();
+	} );
+
+	test( 'cross-realm Document/Window: accepts targets from a different realm', () => {
+		// Simulate an iframe document — a Document from a different realm
+		// would not be `instanceof Document` of the parent realm. Replicate
+		// that by passing a duck-typed Document-like object.
+		const iframe = document.createElement( 'iframe' );
+		document.body.appendChild( iframe );
+		const iframeDoc = iframe.contentDocument;
+		const iframeTarget = iframeDoc.createElement( 'span' );
+		iframeDoc.body.appendChild( iframeTarget );
+
+		const cb = jest.fn();
+		expect( () =>
+			subscribeDelegatedListener( iframeTarget, 'click', cb )
+		).not.toThrow();
+		iframeTarget.dispatchEvent(
+			new iframe.contentWindow.Event( 'click', { bubbles: true } )
+		);
+		expect( cb ).toHaveBeenCalledTimes( 1 );
+		document.body.removeChild( iframe );
+	} );
+} );