WordPress · felixarntz · Dec 18, 2024 · Dec 18, 2024 · Jan 2, 2025 · Jan 2, 2025
@@ -873,6 +873,8 @@ const { state } = store( 'myPlugin', {
 } );
 ```
 
+You may want to add multiple such `yield` points in your action if it is doing a lot of work.
+
 As mentioned above with [`wp-on`](#wp-on), [`wp-on-window`](#wp-on-window), and [`wp-on-document`](#wp-on-document), an async action should be used whenever the `async` versions of the aforementioned directives cannot be used due to the action requiring synchronous access to the `event` object. Synchronous access is required whenever the action needs to call `event.preventDefault()`, `event.stopPropagation()`, or `event.stopImmediatePropagation()`. To ensure that the action code does not contribute to a long task, you may manually yield to the main thread after calling the synchronous event API. For example:
 
 ```js
@@ -885,16 +887,17 @@ function splitTask() {
 
 store( 'myPlugin', {
 	actions: {
-		handleClick: function* ( event ) {
+		handleClick: withSyncEvent( function* ( event ) {
 			event.preventDefault();
 			yield splitTask();
 			doTheWork();
-		},
+		} ),
 	},
 } );
 ```
 
-You may want to add multiple such `yield` points in your action if it is doing a lot of work.
+You may notice the use of the [`withSyncEvent()`](#withsyncevent) utility function in this example. This is necessary due to an ongoing effort to handle store actions asynchronously by default, unless they require synchronous event access. Otherwise a deprecation warning will be triggered, and in a future release the behavior will change accordingly.
+
 
 #### Side Effects
 
@@ -1253,6 +1256,43 @@ store( 'mySliderPlugin', {
 } );
 ```
 
+### withSyncEvent()
+
+Actions that require synchronous access to the `event` object need to use the `withSyncEvent()` function to wrap their handler callback. This is necessary due to an ongoing effort to handle store actions asynchronously by default, unless they require synchronous event access. Therefore, as of Gutenberg `TODO: Add release number here!` / WordPress 6.8 all actions that require synchronous event access need to use the `withSyncEvent()` utility wrapper function. Otherwise a deprecation warning will be triggered, and in a future release the behavior will change accordingly.
+
+Only very specific event methods and properties require synchronous access, so it is advised to only use `withSyncEvent()` when necessary. The following event methods and properties require synchronous access:
+
+* `event.currentTarget`
+* `event.preventDefault()`
+* `event.stopImmediatePropagation()`
+* `event.stopPropagation()`
+
+Here is an example, where one action requires synchronous event access while the other actions do not:
+
+```js
+// store
+import { store, withSyncEvent } from '@wordpress/interactivity';
+
+store( 'myPlugin', {
+	actions: {
+		// `event.preventDefault()` requires synchronous event access.
+		preventNavigation: withSyncEvent( ( event ) => {
+			event.preventDefault();
+		} ),
+
+		// `event.target` does not require synchronous event access.
+		logTarget: ( event ) => {
+			console.log( 'event target => ', event.target );
+		},
+
+		// Not using `event` at all does not require synchronous event access.
+		logSomething: () => {
+			console.log( 'something' );
+		},
+	},
+} );
+```
+
 ## Server functions
 
 The Interactivity API comes with handy functions that allow you to initialize and reference configuration options on the server. This is necessary to feed the initial data that the Server Directive Processing will use to modify the HTML markup before it's send to the browser. It is also a great way to leverage many of WordPress's APIs, like nonces, AJAX, and translations.

@@ -1,7 +1,12 @@
 /**
  * WordPress dependencies
  */
-import { store, getContext, getElement } from '@wordpress/interactivity';
+import {
+	store,
+	getContext,
+	getElement,
+	withSyncEvent,
+} from '@wordpress/interactivity';
 
 /**
  * Tracks whether user is touching screen; used to differentiate behavior for
@@ -128,7 +133,7 @@ const { state, actions, callbacks } = store(
 					}, 450 );
 				}
 			},
-			handleKeydown( event ) {
+			handleKeydown: withSyncEvent( ( event ) => {
 				if ( state.overlayEnabled ) {
 					// Focuses the close button when the user presses the tab key.
 					if ( event.key === 'Tab' ) {
@@ -141,8 +146,8 @@ const { state, actions, callbacks } = store(
 						actions.hideLightbox();
 					}
 				}
-			},
-			handleTouchMove( event ) {
+			} ),
+			handleTouchMove: withSyncEvent( ( event ) => {
 				// On mobile devices, prevents triggering the scroll event because
 				// otherwise the page jumps around when it resets the scroll position.
 				// This also means that closing the lightbox requires that a user
@@ -152,7 +157,7 @@ const { state, actions, callbacks } = store(
 				if ( state.overlayEnabled ) {
 					event.preventDefault();
 				}
-			},
+			} ),
 			handleTouchStart() {
 				isTouching = true;
 			},

@@ -1,7 +1,12 @@
 /**
  * WordPress dependencies
  */
-import { store, getContext, getElement } from '@wordpress/interactivity';
+import {
+	store,
+	getContext,
+	getElement,
+	withSyncEvent,
+} from '@wordpress/interactivity';
 
 const focusableSelectors = [
 	'a[href]',
@@ -106,7 +111,7 @@ const { state, actions } = store(
 					actions.openMenu( 'click' );
 				}
 			},
-			handleMenuKeydown( event ) {
+			handleMenuKeydown: withSyncEvent( ( event ) => {
 				const { type, firstFocusableElement, lastFocusableElement } =
 					getContext();
 				if ( state.menuOpenedBy.click ) {
@@ -137,7 +142,7 @@ const { state, actions } = store(
 						}
 					}
 				}
-			},
+			} ),
 			handleMenuFocusout( event ) {
 				const { modal, type } = getContext();
 				// If focus is outside modal, and in the document, close menu

@@ -1,7 +1,12 @@
 /**
  * WordPress dependencies
  */
-import { store, getContext, getElement } from '@wordpress/interactivity';
+import {
+	store,
+	getContext,
+	getElement,
+	withSyncEvent,
+} from '@wordpress/interactivity';
 
 const isValidLink = ( ref ) =>
 	ref &&
@@ -22,7 +27,7 @@ store(
 	'core/query',
 	{
 		actions: {
-			*navigate( event ) {
+			navigate: withSyncEvent( function* ( event ) {
 				const ctx = getContext();
 				const { ref } = getElement();
 				const queryRef = ref.closest(
@@ -42,7 +47,7 @@ store(
 					const firstAnchor = `.wp-block-post-template a[href]`;
 					queryRef.querySelector( firstAnchor )?.focus();
 				}
-			},
+			} ),
 			*prefetch() {
 				const { ref } = getElement();
 				if ( isValidLink( ref ) ) {

@@ -1,7 +1,12 @@
 /**
  * WordPress dependencies
  */
-import { store, getContext, getElement } from '@wordpress/interactivity';
+import {
+	store,
+	getContext,
+	getElement,
+	withSyncEvent,
+} from '@wordpress/interactivity';
 
 const { actions } = store(
 	'core/search',
@@ -31,15 +36,15 @@ const { actions } = store(
 			},
 		},
 		actions: {
-			openSearchInput( event ) {
+			openSearchInput: withSyncEvent( ( event ) => {
 				const ctx = getContext();
 				const { ref } = getElement();
 				if ( ! ctx.isSearchInputVisible ) {
 					event.preventDefault();
 					ctx.isSearchInputVisible = true;
 					ref.parentElement.querySelector( 'input' ).focus();
 				}
-			},
+			} ),
 			closeSearchInput() {
 				const ctx = getContext();
 				ctx.isSearchInputVisible = false;

@@ -1,17 +1,22 @@
 /**
  * WordPress dependencies
  */
-import { store, getContext, getServerContext } from '@wordpress/interactivity';
+import {
+	store,
+	getContext,
+	getServerContext,
+	withSyncEvent,
+} from '@wordpress/interactivity';
 
 store( 'test/get-server-context', {
 	actions: {
-		*navigate( e ) {
+		navigate: withSyncEvent( function* ( e ) {
 			e.preventDefault();
 			const { actions } = yield import(
 				'@wordpress/interactivity-router'
 			);
 			yield actions.navigate( e.target.href );
-		},
+		} ),
 		attemptModification() {
 			try {
 				getServerContext().prop = 'updated from client';

@@ -1,17 +1,22 @@
 /**
  * WordPress dependencies
  */
-import { store, getServerState, getContext } from '@wordpress/interactivity';
+import {
+	store,
+	getServerState,
+	getContext,
+	withSyncEvent,
+} from '@wordpress/interactivity';
 
 const { state } = store( 'test/get-server-state', {
 	actions: {
-		*navigate( e ) {
+		navigate: withSyncEvent( function* ( e ) {
 			e.preventDefault();
 			const { actions } = yield import(
 				'@wordpress/interactivity-router'
 			);
 			yield actions.navigate( e.target.href );
-		},
+		} ),
 		attemptModification() {
 			try {
 				getServerState().prop = 'updated from client';

@@ -1,7 +1,7 @@
 /**
  * WordPress dependencies
  */
-import { store } from '@wordpress/interactivity';
+import { store, withSyncEvent } from '@wordpress/interactivity';
 
 const { state } = store( 'router', {
 	state: {
@@ -18,7 +18,7 @@ const { state } = store( 'router', {
 		},
 	},
 	actions: {
-		*navigate( e ) {
+		navigate: withSyncEvent( function* ( e ) {
 			e.preventDefault();
 
 			state.navigations.count += 1;
@@ -38,7 +38,7 @@ const { state } = store( 'router', {
 			if ( state.navigations.pending === 0 ) {
 				state.status = 'idle';
 			}
-		},
+		} ),
 		toggleTimeout() {
 			state.timeout = state.timeout === 10000 ? 0 : 10000;
 		},

@@ -1,7 +1,7 @@
 /**
  * WordPress dependencies
  */
-import { store, getContext } from '@wordpress/interactivity';
+import { store, getContext, withSyncEvent } from '@wordpress/interactivity';
 
 const { state } = store( 'router-regions', {
 	state: {
@@ -17,13 +17,13 @@ const { state } = store( 'router-regions', {
 	},
 	actions: {
 		router: {
-			*navigate( e ) {
+			navigate: withSyncEvent( function* ( e ) {
 				e.preventDefault();
 				const { actions } = yield import(
 					'@wordpress/interactivity-router'
 				);
 				yield actions.navigate( e.target.href );
-			},
+			} ),
 			back() {
 				history.back();
 			},

@@ -1,20 +1,20 @@
 /**
  * WordPress dependencies
  */
-import { store } from '@wordpress/interactivity';
+import { store, withSyncEvent } from '@wordpress/interactivity';
 
 const { state } = store( 'test/router-styles', {
 	state: {
 		clientSideNavigation: false,
 	},
 	actions: {
-		*navigate( e ) {
+		navigate: withSyncEvent( function* ( e ) {
 			e.preventDefault();
 			const { actions } = yield import(
 				'@wordpress/interactivity-router'
 			);
 			yield actions.navigate( e.target.href );
 			state.clientSideNavigation = true;
-		},
+		} ),
 	},
 } );
diff --git a/packages/interactivity-router/README.md b/packages/interactivity-router/README.md
@@ -17,12 +17,13 @@ The package is intended to be imported dynamically in the `view.js` files of int
 ```js
 /* view.js */
 
-import { store } from '@wordpress/interactivity';
+import { store, withSyncEvent } from '@wordpress/interactivity';
 
 // This is how you would typically use the navigate() action in your block.
 store( 'my-namespace/myblock', {
 	actions: {
-		*goToPage( e ) {
+		// The withSyncEvent() utility needs to be used because preventDefault() requires synchronous event access.
+		goToPage: withSyncEvent( function* ( e ) {
 			e.preventDefault();
 
 			// We import the package dynamically to reduce the initial JS bundle size.
@@ -31,7 +32,7 @@ store( 'my-namespace/myblock', {
 				'@wordpress/interactivity-router'
 			);
 			yield actions.navigate( e.target.href );
-		},
+		} ),
 	},
 } );
 ```