Introduce withSyncEvent action wrapper utility and proxy event object whenever it is not used

[felixarntz]

This implements the 1st step from #64944. Please see the issue for additional context on the rationale and overarching approach for this.

Relevant technical choices

• In order for directive implementations to access resolved data from the entries, a few new functions are needed. This is because the evaluate function resolves the entry into the relevant data, but then also immediately evaluates it.
  • For the case of an event listener callback, this means the evaluate function will not only "look up" the callback, but also call it.
  • Since we need to conditionally alter the event object based on whether the callback is wrapped in withSyncEvent prior to calling the callback, the evaluate function is not sufficient.
  • In a future PR, we would then also need to call splitTask() before running the callback function (see 2nd step from Introduce withSyncEvent and require Interactivity API actions that use the event object to use it #64944).
• As a solution, this PR introduces two new functions resolveEntry and evaluateResolved. If they are called right after each other, it's effectively the same as evaluate. In fact, this PR updates evaluate to rely on these two lower-level functions, to avoid duplicate code.
• Most directives can still use evaluate as is, which is more ergonomic. However the on (but not on-async) directives require the more granular access of the callback first, to only execute it later.

Work in progress, but early reviews are appreciated.

So far, I have not implemented the actual proxying yet. I would like to get a sense of whether this minor expansion of the Interactivity API infrastructure makes sense before continuing.

[github-actions]

Flaky tests detected in dad7083.
Some tests passed with failed attempts. The failures may not be related to this commit but are still reported for visibility. See the documentation for more information.

🔍 Workflow run URL: https://github.com/WordPress/gutenberg/actions/runs/12589925664
📝 Reported issues:

• [Flaky Test] Navigates the items list via UP/DOWN arrow keys #64334 in /test/e2e/specs/site-editor/dataviews-list-layout-keyboard.spec.js

[gziolo]

So far, I have not implemented the actual proxying yet. I would like to get a sense of whether this minor expansion of the Interactivity API infrastructure makes sense before continuing.

I don't know the codebase, but you are on track as much as I understand the changes and their implications. Thank you for continuing to work on it. I also wanted to share that it might not be easy to get more feedback in the next 2-3 weeks as many folks, myself included, take longer holiday breaks 🎉

[michalczaplinski]

I gave it an initial review and so far it's looking good. The approach of splitting evaluate into 2 functions seems sound to me. I see that you haven't implemented the proxying yet, so I'm happy to take another look once that's closer to being ready.

PS. The Interactivity API is almost entirely tested using the e2e suite in test/e2e/specs/interactivity/. For this PR, you'll probably need to modify some of the existing "test" blocks like packages/e2e-tests/plugins/interactive-blocks/directive-on/view.js or create a new "test" block in that folder.

[github-actions]

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the props-bot label.

If you're merging code through a pull request on GitHub, copy and paste the following into the bottom of the merge commit message.

Co-authored-by: felixarntz <[email protected]>
Co-authored-by: michalczaplinski <[email protected]>
Co-authored-by: gziolo <[email protected]>

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.

[felixarntz]

I have implemented the event proxying logic. For now, I'm warning about accessing the following without withSyncEvent():

• event.currentTarget
• event.preventDefault()
• event.stopImmediatePropagation()
• event.stopPropagation()

As discussed on the issue, there may be more properties and methods to warn about, but we could always expand later. I think these 4 are a good starting point and should cover what's most common.

Keep in mind that for now there is only a warning, but no functional behavior change. We can only yield before all callbacks that aren't using withSyncEvent() after at least one release cycle (which is why the warning message mentions WordPress 6.9, as this enhancement ideally launches as part of WordPress 6.8).

Review much appreciated!