@wordpress/compose 7.46.0 → 8.0.0

package/src/hooks/use-dialog/index.ts

@@ -1,13 +1,17 @@
 /**
  * External dependencies
  */
-import type { RefCallback, SyntheticEvent } from 'react';
+import type {
+	KeyboardEvent,
+	KeyboardEventHandler,
+	RefCallback,
+	SyntheticEvent,
+} from 'react';
 
 /**
  * WordPress dependencies
  */
 import { useRef, useEffect, useCallback } from '@wordpress/element';
-import { ESCAPE } from '@wordpress/keycodes';
 
 /**
  * Internal dependencies
@@ -43,6 +47,10 @@ type DialogOptions = {
 	 */
 	constrainTabbing?: boolean;
 	onClose?: () => void;
+	/**
+	 * Optional `onKeyDown` handler, merged with the built-in one.
+	 */
+	onKeyDown?: KeyboardEventHandler< HTMLElement >;
 	/**
 	 * Use the `onClose` prop instead.
 	 *
@@ -56,7 +64,9 @@ type DialogOptions = {
 
 type useDialogReturn = [
 	RefCallback< HTMLElement >,
-	ReturnType< typeof useFocusOutside > & Pick< HTMLElement, 'tabIndex' >,
+	ReturnType< typeof useFocusOutside > & {
+		onKeyDown: ( event: KeyboardEvent< HTMLElement > ) => void;
+	} & Pick< HTMLElement, 'tabIndex' >,
 ];
 
 /**
@@ -86,23 +96,23 @@ function useDialog( options: DialogOptions ): useDialogReturn {
 			currentOptions.current.onClose();
 		}
 	} );
-	const closeOnEscapeRef = useCallback( ( node: HTMLElement ) => {
-		if ( ! node ) {
-			return;
+	// Close on Escape via a React `onKeyDown` (rather than a native listener)
+	// so portaled descendants that handle Escape and call
+	// `event.stopPropagation()` correctly prevent the dialog from closing.
+	// See https://github.com/WordPress/gutenberg/issues/78432.
+	const onKeyDown = useCallback( ( event: KeyboardEvent< HTMLElement > ) => {
+		// Let the consumer-provided handler (if any) run first so it can
+		// call `preventDefault()` to opt out of close-on-Escape.
+		currentOptions.current?.onKeyDown?.( event );
+		if (
+			event.key === 'Escape' &&
+			! event.defaultPrevented &&
+			currentOptions.current?.onClose
+		) {
+			event.preventDefault();
+			event.stopPropagation();
+			currentOptions.current.onClose();
 		}
-
-		node.addEventListener( 'keydown', ( event: KeyboardEvent ) => {
-			// Close on escape.
-			if (
-				event.keyCode === ESCAPE &&
-				! event.defaultPrevented &&
-				currentOptions.current?.onClose
-			) {
-				event.preventDefault();
-				event.stopPropagation();
-				currentOptions.current.onClose();
-			}
-		} );
 	}, [] );
 
 	return [
@@ -110,10 +120,10 @@ function useDialog( options: DialogOptions ): useDialogReturn {
 			constrainTabbing ? constrainedTabbingRef : null,
 			options.focusOnMount !== false ? focusReturnRef : null,
 			options.focusOnMount !== false ? focusOnMountRef : null,
-			closeOnEscapeRef,
 		] ),
 		{
 			...focusOutsideProps,
+			onKeyDown,
 			tabIndex: -1,
 		},
 	];

package/src/hooks/use-dialog/test/index.tsx

@@ -1,7 +1,9 @@
 /**
  * External dependencies
  */
-import { render, screen, fireEvent } from '@testing-library/react';
+import { render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { createPortal } from 'react-dom';
 
 /**
  * Internal dependencies
@@ -22,44 +24,58 @@ function Dialog( { onClose }: { onClose?: () => void } ) {
 	);
 }
 
-// `useDialog` currently detects the Escape key via the deprecated `keyCode`
-// property (`event.keyCode === 27`). In jsdom, `userEvent.keyboard('[Escape]')`
-// does not set `keyCode` to 27, so we use `fireEvent` to control the event
-// shape. Once the hook is updated to use `event.key === 'Escape'`, these tests
-// should be rewritten to use `userEvent` for more realistic event simulation.
-function pressEscapeOn( element: HTMLElement ) {
-	fireEvent.keyDown( element, { keyCode: 27, key: 'Escape' } );
-}
-
 describe( 'useDialog', () => {
-	it( 'should call onClose when Escape is pressed', () => {
+	it( 'should call onClose when Escape is pressed', async () => {
+		const user = userEvent.setup();
 		const onClose = jest.fn();
 
 		render( <Dialog onClose={ onClose } /> );
 
-		pressEscapeOn( screen.getByRole( 'dialog' ) );
+		screen.getByRole( 'dialog' ).focus();
+		await user.keyboard( '[Escape]' );
 
 		expect( onClose ).toHaveBeenCalledTimes( 1 );
 	} );
 
-	it( 'should not call onClose when Escape is pressed if defaultPrevented', () => {
+	it( 'should not call onClose when Escape is pressed if defaultPrevented', async () => {
+		const user = userEvent.setup();
 		const onClose = jest.fn();
 
-		render( <Dialog onClose={ onClose } /> );
+		function DialogWithChild() {
+			const [ ref, props ] = useDialog( {
+				onClose,
+				focusOnMount: false,
+			} );
+			return (
+				<div
+					ref={ ref }
+					{ ...props }
+					role="dialog"
+					aria-label="Test dialog"
+				>
+					<button
+						onKeyDown={ ( event ) => {
+							if ( event.key === 'Escape' ) {
+								event.preventDefault();
+							}
+						} }
+					>
+						Inside
+					</button>
+				</div>
+			);
+		}
+
+		render( <DialogWithChild /> );
 
-		const dialog = screen.getByRole( 'dialog' );
-		const event = new KeyboardEvent( 'keydown', {
-			keyCode: 27,
-			bubbles: true,
-			cancelable: true,
-		} );
-		event.preventDefault();
-		dialog.dispatchEvent( event );
+		screen.getByRole( 'button', { name: 'Inside' } ).focus();
+		await user.keyboard( '[Escape]' );
 
 		expect( onClose ).not.toHaveBeenCalled();
 	} );
 
-	it( 'should stop Escape event from propagating to parent elements', () => {
+	it( 'should stop Escape event from propagating to parent elements', async () => {
+		const user = userEvent.setup();
 		const onClose = jest.fn();
 		const parentKeyDownHandler = jest.fn();
 
@@ -70,13 +86,15 @@ describe( 'useDialog', () => {
 			</div>
 		);
 
-		pressEscapeOn( screen.getByRole( 'button', { name: 'Inside' } ) );
+		screen.getByRole( 'button', { name: 'Inside' } ).focus();
+		await user.keyboard( '[Escape]' );
 
 		expect( onClose ).toHaveBeenCalledTimes( 1 );
 		expect( parentKeyDownHandler ).not.toHaveBeenCalled();
 	} );
 
-	it( 'should let Escape propagate when there is no onClose handler', () => {
+	it( 'should let Escape propagate when there is no onClose handler', async () => {
+		const user = userEvent.setup();
 		const parentKeyDownHandler = jest.fn();
 
 		render(
@@ -86,12 +104,62 @@ describe( 'useDialog', () => {
 			</div>
 		);
 
-		pressEscapeOn( screen.getByRole( 'button', { name: 'Inside' } ) );
+		screen.getByRole( 'button', { name: 'Inside' } ).focus();
+		await user.keyboard( '[Escape]' );
 
 		expect( parentKeyDownHandler ).toHaveBeenCalledTimes( 1 );
 	} );
 
-	it( 'should close only the innermost dialog when nested', () => {
+	it( 'should not close when a portaled descendant handles Escape and stops propagation', async () => {
+		const user = userEvent.setup();
+		const onClose = jest.fn();
+		const descendantHandled = jest.fn();
+
+		const portalTarget = document.createElement( 'div' );
+		document.body.appendChild( portalTarget );
+
+		function DialogWithPortaledChild() {
+			const [ ref, props ] = useDialog( {
+				onClose,
+				focusOnMount: false,
+			} );
+			return (
+				<div
+					ref={ ref }
+					{ ...props }
+					role="dialog"
+					aria-label="Test dialog"
+				>
+					{ createPortal(
+						<button
+							onKeyDown={ ( event ) => {
+								if ( event.key === 'Escape' ) {
+									descendantHandled();
+									event.stopPropagation();
+								}
+							} }
+						>
+							Portaled
+						</button>,
+						portalTarget
+					) }
+				</div>
+			);
+		}
+
+		render( <DialogWithPortaledChild /> );
+
+		screen.getByText( 'Portaled' ).focus();
+		await user.keyboard( '[Escape]' );
+
+		expect( descendantHandled ).toHaveBeenCalledTimes( 1 );
+		expect( onClose ).not.toHaveBeenCalled();
+
+		document.body.removeChild( portalTarget );
+	} );
+
+	it( 'should close only the innermost dialog when nested', async () => {
+		const user = userEvent.setup();
 		const outerOnClose = jest.fn();
 		const innerOnClose = jest.fn();
 
@@ -126,22 +194,82 @@ describe( 'useDialog', () => {
 
 		render( <NestedDialogs /> );
 
-		pressEscapeOn( screen.getByRole( 'button', { name: 'Focusable' } ) );
+		screen.getByRole( 'button', { name: 'Focusable' } ).focus();
+		await user.keyboard( '[Escape]' );
 
 		expect( innerOnClose ).toHaveBeenCalledTimes( 1 );
 		expect( outerOnClose ).not.toHaveBeenCalled();
 	} );
 
-	it( 'should not call onClose for non-Escape keys', () => {
+	it( 'should call the consumer-provided onKeyDown alongside close-on-Escape', async () => {
+		const user = userEvent.setup();
 		const onClose = jest.fn();
+		const consumerOnKeyDown = jest.fn();
 
-		render( <Dialog onClose={ onClose } /> );
+		function DialogWithConsumerOnKeyDown() {
+			const [ ref, props ] = useDialog( {
+				onClose,
+				onKeyDown: consumerOnKeyDown,
+				focusOnMount: false,
+			} );
+			return (
+				<div
+					ref={ ref }
+					{ ...props }
+					role="dialog"
+					aria-label="Test dialog"
+				/>
+			);
+		}
+
+		render( <DialogWithConsumerOnKeyDown /> );
+
+		screen.getByRole( 'dialog' ).focus();
+		await user.keyboard( '[Escape]' );
+
+		expect( consumerOnKeyDown ).toHaveBeenCalledTimes( 1 );
+		expect( consumerOnKeyDown.mock.calls[ 0 ][ 0 ].key ).toBe( 'Escape' );
+		expect( onClose ).toHaveBeenCalledTimes( 1 );
+	} );
+
+	it( 'should let the consumer-provided onKeyDown opt out of close-on-Escape via preventDefault', async () => {
+		const user = userEvent.setup();
+		const onClose = jest.fn();
 
-		const dialog = screen.getByRole( 'dialog' );
+		function DialogOptingOut() {
+			const [ ref, props ] = useDialog( {
+				onClose,
+				onKeyDown: ( event ) => event.preventDefault(),
+				focusOnMount: false,
+			} );
+			return (
+				<div
+					ref={ ref }
+					{ ...props }
+					role="dialog"
+					aria-label="Test dialog"
+				/>
+			);
+		}
+
+		render( <DialogOptingOut /> );
+
+		screen.getByRole( 'dialog' ).focus();
+		await user.keyboard( '[Escape]' );
+
+		expect( onClose ).not.toHaveBeenCalled();
+	} );
+
+	it( 'should not call onClose for non-Escape keys', async () => {
+		const user = userEvent.setup();
+		const onClose = jest.fn();
+
+		render( <Dialog onClose={ onClose } /> );
 
-		fireEvent.keyDown( dialog, { keyCode: 13, key: 'Enter' } );
-		fireEvent.keyDown( dialog, { keyCode: 65, key: 'a' } );
-		fireEvent.keyDown( dialog, { keyCode: 9, key: 'Tab' } );
+		screen.getByRole( 'dialog' ).focus();
+		await user.keyboard( '[Enter]' );
+		await user.keyboard( 'a' );
+		await user.keyboard( '[Tab]' );
 
 		expect( onClose ).not.toHaveBeenCalled();
 	} );

package/src/hooks/use-disabled/index.ts

@@ -45,14 +45,14 @@ export default function useDisabled( {
 			}
 
 			/** A variable keeping track of the previous updates in order to restore them. */
-			const updates: Function[] = [];
+			const updates: ( () => void )[] = [];
 			const disable = () => {
 				node.childNodes.forEach( ( child ) => {
 					if ( ! ( child instanceof defaultView.HTMLElement ) ) {
 						return;
 					}
-					if ( ! child.getAttribute( 'inert' ) ) {
-						child.setAttribute( 'inert', 'true' );
+					if ( ! child.hasAttribute( 'inert' ) ) {
+						child.setAttribute( 'inert', '' );
 						updates.push( () => {
 							child.removeAttribute( 'inert' );
 						} );

package/src/hooks/use-disabled/test/index.js

@@ -37,9 +37,9 @@ describe( 'useDisabled', () => {
 		const link = screen.getByRole( 'link' );
 		const p = screen.getByRole( 'document' );
 
-		expect( input ).toHaveAttribute( 'inert', 'true' );
-		expect( link ).toHaveAttribute( 'inert', 'true' );
-		expect( p ).toHaveAttribute( 'inert', 'true' );
+		expect( input ).toHaveAttribute( 'inert' );
+		expect( link ).toHaveAttribute( 'inert' );
+		expect( p ).toHaveAttribute( 'inert' );
 	} );
 
 	it( 'will disable an element rendered in an update to the component', async () => {
@@ -52,7 +52,7 @@ describe( 'useDisabled', () => {
 
 		const button = screen.getByText( 'Button' );
 		await waitFor( () => {
-			expect( button ).toHaveAttribute( 'inert', 'true' );
+			expect( button ).toHaveAttribute( 'inert' );
 		} );
 	} );
 } );

package/src/hooks/use-focus-outside/index.native.js

@@ -55,7 +55,7 @@ function isFocusNormalizedButton( eventTarget ) {
  */
 
 /**
- * @typedef {React.MutableRefObject<FocusOutsideReactElement | undefined>} FocusOutsideRef
+ * @typedef {React.RefObject<FocusOutsideReactElement | undefined>} FocusOutsideRef
  */
 
 /**
@@ -88,7 +88,7 @@ export default function useFocusOutside( onFocusOutside ) {
 	const preventBlurCheck = useRef( false );
 
 	/**
-	 * @type {React.MutableRefObject<number | undefined>}
+	 * @type {React.RefObject<number | undefined>}
 	 */
 	const blurCheckTimeoutId = useRef();
 

package/src/hooks/use-focus-return/index.js

@@ -29,9 +29,9 @@ let origin = null;
  * ```
  */
 function useFocusReturn( onFocusReturn ) {
-	/** @type {React.MutableRefObject<null | HTMLElement>} */
+	/** @type {React.RefObject<HTMLElement| null>} */
 	const ref = useRef( null );
-	/** @type {React.MutableRefObject<null | Element>} */
+	/** @type {React.RefObject<Element | null>} */
 	const focusedBeforeMount = useRef( null );
 	const onFocusReturnRef = useRef( onFocusReturn );
 	useEffect( () => {

package/src/hooks/use-media-query/index.ts

@@ -1,45 +1,69 @@
 /**
  * WordPress dependencies
  */
-import { useMemo, useSyncExternalStore } from '@wordpress/element';
+import { useSyncExternalStore } from '@wordpress/element';
 
-type MQLCache = Map< string, MediaQueryList >;
+type MQLSubscriber = {
+	subscribe: ( onStoreChange: () => void ) => () => void;
+	getValue: () => boolean;
+};
 
-const perWindowCache = new WeakMap< Window, MQLCache >();
+// One subscriber per (window, query). The underlying MediaQueryList lives
+// inside the subscriber's closure; a single `change` listener fans out to
+// every React consumer via an in-JS `Set` to avoid the per-consumer
+// `addEventListener` cost (~85 ms during a large-post editor mount).
+const perWindowCache = new WeakMap< Window, Map< string, MQLSubscriber > >();
 
-/**
- * A new MediaQueryList object for the media query
- *
- * @param view    Window.
- * @param [query] Media Query.
- */
-function getMediaQueryList(
-	view: Window,
-	query?: string
-): MediaQueryList | null {
-	if ( ! query ) {
-		return null;
-	}
-
-	const matchMediaCache: MQLCache = perWindowCache.get( view ) ?? new Map();
+const EMPTY_SUBSCRIBER: MQLSubscriber = {
+	subscribe: () => () => {},
+	getValue: () => false,
+};
 
-	if ( ! perWindowCache.has( view ) ) {
-		perWindowCache.set( view, matchMediaCache );
+function getMQLSubscriber( view: Window, query?: string ): MQLSubscriber {
+	if ( ! query || typeof view?.matchMedia !== 'function' ) {
+		return EMPTY_SUBSCRIBER;
 	}
 
-	let match = matchMediaCache.get( query );
-
-	if ( match ) {
-		return match;
+	let queryCache = perWindowCache.get( view );
+	if ( ! queryCache ) {
+		queryCache = new Map();
+		perWindowCache.set( view, queryCache );
 	}
 
-	if ( typeof view?.matchMedia === 'function' ) {
-		match = view.matchMedia( query );
-		matchMediaCache.set( query, match );
-		return match;
+	const cached = queryCache.get( query );
+	if ( cached ) {
+		return cached;
 	}
 
-	return null;
+	const mediaQueryList = view.matchMedia( query );
+	const listeners = new Set< () => void >();
+	const notify = () => {
+		for ( const listener of listeners ) {
+			listener();
+		}
+	};
+
+	const subscriber: MQLSubscriber = {
+		subscribe( onStoreChange ) {
+			if ( listeners.size === 0 ) {
+				// Avoid a fatal error when browsers don't support `addEventListener` on MediaQueryList.
+				mediaQueryList.addEventListener?.( 'change', notify );
+			}
+			listeners.add( onStoreChange );
+			return () => {
+				listeners.delete( onStoreChange );
+				if ( listeners.size === 0 ) {
+					mediaQueryList.removeEventListener?.( 'change', notify );
+				}
+			};
+		},
+		getValue() {
+			return mediaQueryList.matches;
+		},
+	};
+
+	queryCache.set( query, subscriber );
+	return subscriber;
 }
 
 /**
@@ -53,29 +77,7 @@ export default function useMediaQuery(
 	query?: string,
 	view: Window = window
 ): boolean {
-	const source = useMemo( () => {
-		const mediaQueryList = getMediaQueryList( view, query );
-
-		return {
-			subscribe( onStoreChange: any ) {
-				if ( ! mediaQueryList ) {
-					return () => {};
-				}
-
-				// Avoid a fatal error when browsers don't support `addEventListener` on MediaQueryList.
-				mediaQueryList.addEventListener?.( 'change', onStoreChange );
-				return () => {
-					mediaQueryList.removeEventListener?.(
-						'change',
-						onStoreChange
-					);
-				};
-			},
-			getValue() {
-				return mediaQueryList?.matches ?? false;
-			},
-		};
-	}, [ view, query ] );
+	const source = getMQLSubscriber( view, query );
 
 	return useSyncExternalStore(
 		source.subscribe,

package/src/hooks/use-merge-refs/index.ts

@@ -2,13 +2,13 @@
  * WordPress dependencies
  */
 import { useRef, useCallback, useLayoutEffect } from '@wordpress/element';
-import type { MutableRefObject, Ref, RefCallback } from 'react';
+import type { Ref, RefCallback } from 'react';
 
 function assignRef< T >( ref: Ref< T >, value: T ) {
 	if ( typeof ref === 'function' ) {
 		ref( value );
 	} else if ( ref && ref.hasOwnProperty( 'current' ) ) {
-		( ref as MutableRefObject< T > ).current = value;
+		ref.current = value;
 	}
 }
 

package/src/hooks/use-resize-observer/use-resize-observer.ts

@@ -18,7 +18,7 @@ export function useResizeObserver< T extends HTMLElement >(
 ): ( element?: T | null ) => void {
 	const callbackEvent = useEvent( callback );
 
-	const observedElementRef = useRef< T | null >( null );
+	const observedElementRef = useRef< T >( null );
 	const resizeObserverRef = useRef< ResizeObserver >( undefined );
 	return useEvent( ( element?: T | null ) => {
 		if ( element === observedElementRef.current ) {

package/src/index.js

@@ -7,6 +7,9 @@ export * from './utils/throttle';
 // The `ObservableMap` data structure
 export * from './utils/observable-map';
 
+// Private APIs.
+export { privateApis } from './private-apis';
+
 // The `compose` and `pipe` helpers (inspired by `flowRight` and `flow` from Lodash).
 export { default as compose } from './higher-order/compose';
 export { default as pipe } from './higher-order/pipe';

package/src/lock-unlock.ts

@@ -0,0 +1,10 @@
+/**
+ * WordPress dependencies
+ */
+import { __dangerousOptInToUnstableAPIsOnlyForCoreModules } from '@wordpress/private-apis';
+
+export const { lock, unlock } =
+	__dangerousOptInToUnstableAPIsOnlyForCoreModules(
+		'I acknowledge private features are not for use in themes or plugins and doing so will break in the next version of WordPress.',
+		'@wordpress/compose'
+	);

package/src/private-apis.ts

@@ -0,0 +1,13 @@
+/**
+ * Internal dependencies
+ */
+import { lock } from './lock-unlock';
+import subscribeDelegatedListener from './utils/subscribe-delegated-listener';
+
+/**
+ * Private @wordpress/compose APIs.
+ */
+export const privateApis = {};
+lock( privateApis, {
+	subscribeDelegatedListener,
+} );