@wordpress/compose 7.46.0 → 8.1.0

package/build-types/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.js"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.js"],"names":[],"mappings":"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"}

package/build-types/lock-unlock.d.ts

@@ -0,0 +1,2 @@
+export declare const lock: (object: unknown, privateData: unknown) => void, unlock: <T = any>(object: unknown) => T;
+//# sourceMappingURL=lock-unlock.d.ts.map

package/build-types/lock-unlock.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lock-unlock.d.ts","sourceRoot":"","sources":["../src/lock-unlock.ts"],"names":[],"mappings":"AAKA,eAAO,MAAQ,IAAI,mDAAE,MAAM,iCAIzB,CAAC"}

package/build-types/private-apis.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Private @wordpress/compose APIs.
+ */
+export declare const privateApis: {};
+//# sourceMappingURL=private-apis.d.ts.map

package/build-types/private-apis.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"private-apis.d.ts","sourceRoot":"","sources":["../src/private-apis.ts"],"names":[],"mappings":"AAMA;;GAEG;AACH,eAAO,MAAM,WAAW,IAAK,CAAC"}

package/build-types/utils/subscribe-delegated-listener/index.d.ts

@@ -0,0 +1,27 @@
+/**
+ * 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.
+ */
+export default function subscribeDelegatedListener(target: EventTarget, eventType: string, callback: EventListener, capture?: boolean): () => void;
+//# sourceMappingURL=index.d.ts.map

package/build-types/utils/subscribe-delegated-listener/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/utils/subscribe-delegated-listener/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAYH,MAAM,CAAC,OAAO,UAAU,0BAA0B,CACjD,MAAM,EAAE,WAAW,EACnB,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,aAAa,EACvB,OAAO,GAAE,OAAe,GACtB,MAAM,IAAI,CAsFZ"}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@wordpress/compose",
-	"version": "7.46.0",
+	"version": "8.1.0",
 	"description": "WordPress higher-order components (HOCs).",
 	"author": "The WordPress Contributors",
 	"license": "GPL-2.0-or-later",
@@ -47,13 +47,14 @@
 	"sideEffects": false,
 	"dependencies": {
 		"@types/mousetrap": "^1.6.8",
-		"@wordpress/deprecated": "^4.46.0",
-		"@wordpress/dom": "^4.46.0",
-		"@wordpress/element": "^6.46.0",
-		"@wordpress/is-shallow-equal": "^5.46.0",
-		"@wordpress/keycodes": "^4.46.0",
-		"@wordpress/priority-queue": "^3.46.0",
-		"@wordpress/undo-manager": "^1.46.0",
+		"@wordpress/deprecated": "^4.48.0",
+		"@wordpress/dom": "^4.48.0",
+		"@wordpress/element": "^8.0.0",
+		"@wordpress/is-shallow-equal": "^5.48.0",
+		"@wordpress/keycodes": "^4.48.0",
+		"@wordpress/priority-queue": "^3.48.0",
+		"@wordpress/private-apis": "^1.48.0",
+		"@wordpress/undo-manager": "^1.48.0",
 		"change-case": "^4.1.2",
 		"mousetrap": "^1.6.5",
 		"use-memo-one": "^1.1.1"
@@ -67,5 +68,5 @@
 	"publishConfig": {
 		"access": "public"
 	},
-	"gitHead": "51264e33b95fadff9a06b68141e674ce9cde9675"
+	"gitHead": "e7856693aeb4e2522d13608cd32c994e4a97cb9c"
 }

package/src/hooks/use-copy-on-click/index.ts

@@ -8,7 +8,7 @@ import type { RefObject } from 'react';
 /**
  * Internal dependencies
  */
-import { clearSelection, copyToClipboard } from '../use-copy-to-clipboard';
+import { restoreFocus, copyToClipboard } from '../use-copy-to-clipboard';
 
 /**
  * Copies the text to the clipboard when the element is clicked.
@@ -73,7 +73,7 @@ export default function useCopyOnClick(
 				return;
 			}
 			if ( success ) {
-				clearSelection( trigger );
+				restoreFocus( trigger );
 				if ( timeout ) {
 					setHasCopied( true );
 					clearTimeout( timeoutId );

package/src/hooks/use-copy-to-clipboard/index.ts

@@ -52,15 +52,14 @@ export async function copyToClipboard(
 }
 
 /**
- * Clears the current selection and restores focus to the trigger element.
+ * Restores focus to the trigger element.
  *
  * @param trigger The element that triggered the copy.
  */
-export function clearSelection( trigger: Element ): void {
+export function restoreFocus( trigger: Element ): void {
 	if ( 'focus' in trigger && typeof trigger.focus === 'function' ) {
 		trigger.focus();
 	}
-	trigger.ownerDocument?.defaultView?.getSelection()?.removeAllRanges();
 }
 
 /**
@@ -93,7 +92,7 @@ export default function useCopyToClipboard< T extends HTMLElement >(
 	const textRef = useUpdatedRef( text );
 	const onSuccessRef = useUpdatedRef( onSuccess );
 	return useRefEffect( ( node ) => {
-		// Flag to prevent callbacks after unmount when the Promise resolves.
+		// Tracks whether the node is still mounted when the Promise resolves.
 		let isActive = true;
 		const handleClick = async () => {
 			const textToCopy =
@@ -101,11 +100,12 @@ export default function useCopyToClipboard< T extends HTMLElement >(
 					? textRef.current()
 					: textRef.current || '';
 			const success = await copyToClipboard( textToCopy, node );
-			if ( ! isActive ) {
-				return;
-			}
 			if ( success ) {
-				clearSelection( node );
+				// Restoring focus only matters while the node is mounted.
+				if ( isActive ) {
+					restoreFocus( node );
+				}
+				// Always run, even after unmount, to allow updating other UI.
 				if ( onSuccessRef.current ) {
 					onSuccessRef.current();
 				}

package/src/hooks/use-copy-to-clipboard/test/index.tsx

@@ -7,7 +7,7 @@ import userEvent from '@testing-library/user-event';
 /**
  * Internal dependencies
  */
-import useCopyToClipboard, { copyToClipboard, clearSelection } from '../';
+import useCopyToClipboard, { copyToClipboard, restoreFocus } from '../';
 
 interface TestComponentProps {
 	text: string | ( () => string );
@@ -68,7 +68,7 @@ describe( 'useCopyToClipboard', () => {
 		expect( onSuccess ).not.toHaveBeenCalled();
 	} );
 
-	it( 'should not call onSuccess after unmount', async () => {
+	it( 'should call onSuccess after the node unmounts', async () => {
 		let resolvePromise: () => void;
 		const delayedPromise = new Promise< void >( ( resolve ) => {
 			resolvePromise = resolve;
@@ -91,7 +91,35 @@ describe( 'useCopyToClipboard', () => {
 			await new Promise( ( resolve ) => setTimeout( resolve, 0 ) );
 		} );
 
-		expect( onSuccess ).not.toHaveBeenCalled();
+		expect( onSuccess ).toHaveBeenCalledTimes( 1 );
+	} );
+
+	it( 'should not restore focus after the node unmounts', async () => {
+		let resolvePromise: () => void;
+		const delayedPromise = new Promise< void >( ( resolve ) => {
+			resolvePromise = resolve;
+		} );
+		jest.spyOn( navigator.clipboard, 'writeText' ).mockReturnValue(
+			delayedPromise
+		);
+
+		const user = userEvent.setup();
+		const { unmount } = render( <TestComponent text="test" /> );
+
+		const button = screen.getByRole( 'button' );
+		const focusSpy = jest.spyOn( button, 'focus' );
+
+		await user.click( button );
+		unmount();
+		// Discard focus calls from the initial click; we only care about post-unmount calls.
+		focusSpy.mockClear();
+
+		await act( async () => {
+			resolvePromise();
+			await new Promise( ( resolve ) => setTimeout( resolve, 0 ) );
+		} );
+
+		expect( focusSpy ).not.toHaveBeenCalled();
 	} );
 } );
 
@@ -129,13 +157,13 @@ describe( 'copyToClipboard', () => {
 	} );
 } );
 
-describe( 'clearSelection', () => {
+describe( 'restoreFocus', () => {
 	it( 'should focus the trigger element', () => {
 		const trigger = document.createElement( 'button' );
 		document.body.appendChild( trigger );
 		const focusMock = jest.spyOn( trigger, 'focus' );
 
-		clearSelection( trigger );
+		restoreFocus( trigger );
 
 		expect( focusMock ).toHaveBeenCalledTimes( 1 );
 

package/src/hooks/use-dialog/README.md

@@ -6,22 +6,7 @@ React hook to be used on a dialog wrapper to enable the following behaviors:
 -   focus on mount.
 -   return focus on unmount.
 -   focus outside.
-
-## Returned value
-
-The hooks returns an array composed of the two following values:
-
-### `ref`
-
--   Type: `Object|Function`
-
-A React ref that must be passed to the DOM element where the behavior should be attached.
-
-### `props`
-
--   Type: `Object`
-
-Extra props to apply to the wrapper.
+-   close on Escape.
 
 ## Usage
 
@@ -29,15 +14,64 @@ Extra props to apply to the wrapper.
 import { __experimentalUseDialog as useDialog } from '@wordpress/compose';
 
 const MyDialog = () => {
-	const [ ref, extraProps ] = useDialog( {
+	const [ ref, dialogProps ] = useDialog( {
 		onClose: () => console.log( 'do something to close the dialog' ),
 	} );
 
 	return (
-		<div ref={ ref } { ...extraProps }>
+		<div ref={ ref } { ...dialogProps }>
 			<Button />
 			<Button />
 		</div>
 	);
 };
 ```
+
+## Options
+
+### `focusOnMount`
+
+-   Type: `'firstElement' | 'firstInputElement' | boolean`
+-   Default: `'firstElement'`
+
+Determines focus behavior when the dialog mounts:
+
+-   `'firstElement'` focuses the first tabbable element within the dialog.
+-   `'firstInputElement'` focuses the first value control within the dialog.
+-   `true` focuses the dialog wrapper itself.
+-   `false` does nothing, and _should not be used unless an accessible substitute behavior is implemented_.
+
+### `constrainTabbing`
+
+-   Type: `boolean`
+-   Default: `focusOnMount !== false`
+
+Whether tabbing is constrained within the dialog (preventing keyboard focus from leaving without explicit focus elsewhere), or whether the dialog remains part of the wider tab order.
+
+### `onClose`
+
+-   Type: `() => void`
+
+Called when the dialog should close, e.g. when the user presses Escape or focus moves outside.
+
+### `onKeyDown`
+
+-   Type: `KeyboardEventHandler<HTMLElement>`
+
+Optional `onKeyDown` handler, merged with the built-in close-on-Escape handler. Provided to keep things working when the dialog wrapper already has its own `onKeyDown`. The provided handler runs first and can call `event.preventDefault()` to opt out of close-on-Escape.
+
+## Returned value
+
+A tuple of:
+
+### `ref`
+
+-   Type: `RefCallback<HTMLElement>`
+
+A React ref to attach to the dialog wrapper DOM element.
+
+### `dialogProps`
+
+-   Type: `object`
+
+Extra props (`onFocus`, `onBlur`, `onKeyDown`, `tabIndex`, …) to spread onto the same wrapper element.

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();
 	} );