Attaching multiple handlers to an event and allowing asynchronous event handlers

[westonruter]

In thinking about use cases for the Interactivity API, a common use case for scripting in general on the web is for analytics (for better or worse) to track interactions. Given the following interactive block from the examples, how would a 3rd party plugin attach a click event handler to send off the number of times that the button was clicked to some analytics backend?

<div data-wp-context='{ "isOpen": true }'>
  <button data-wp-on--click="actions.someAction">Click</button>
</div>

Unlike with the wp-init directive, it does not appear that multiple wp-on directives can be added with a unique ID to differentiate them (as the event name plays this role). Is there a way for another plugin, such as with the Tag Processor, to inject additional event handlers to run? (Other than to attach the event handler manually in wp-init?)

In particular the Performance team here is concerned about enforcing best practices for... performance. A common problem on the web is that analytics trackers will attach their event handlers that run synchronously at the same time as critical 1st party code. This very frequently results in a long task that hurts INP. If multiple events handlers are supported for a wp-on directive (as it seems they should be) then there should be a way to ensure that they run asynchronously unless they absolutely need synchronous access to the event object (such as to call preventDefault()). This will allow the Interactivity API to yield to the main thread before invoking each event handler, if declared as asynchronous. (Relatedly, the Interactivity API should allow for event handlers to be passive: #58705).

[DAreRodz]

Hi @westonruter 👋 . The possibility of using multiple event listeners for the same event sounds essential. The current problem is that we cannot have two identical properties in the same HTML element, as you mentioned.

<div data-wp-context='{ "isOpen": true }'>
  <button
    data-wp-on--click="actions.someAction"
    data-wp-on--click="analytics::actions.track" <!-- duplicated attribute: won't work -->
  >Click</button>
</div>

A possibility would be to extend the current data-wp-on API to allow passing a JSON with some sort of configuration, leaving the directive suffix to uniquely identify the attribute.

<div data-wp-context='{ "isOpen": true }'>
  <button
    data-wp-on--click="actions.someAction"
    data-wp-on--analytics='{ "event": "click", "callback": "analytics::actions.track", "async": true, "passive": true }'
  >Click</button>
</div>

That would be a substantial change to the API, with the suffix being either an event type or a unique ID, and could cause some confusion. I'm open to exploring that, though. 😄 Maybe we could create another directive for more complex event listener definitions like you proposed. 🤔

---

PS: Another possibility: append the ID after the suffix with the event type.

<div data-wp-context='{ "isOpen": true }'>
  <button
    data-wp-on--click="actions.someAction"
    data-wp-on--click--analytics='{ "callback": "analytics::actions.track", "async": true, "passive": true }'
  >Click</button>
</div>

[sirreal]

Would an array form of the on directive be a solution?

<!-- simple -->
<button data-wp-on--click="actions.clickHandler">X</button>

<!-- multiple -->
<button data-wp-on--click='["actions.clickHandler", "analytics::actions.trackClick"]'>X</button>

[felixarntz]

@sirreal

Would an array form of the on directive be a solution?

I don't think an array would be a suitable solution, since different plugins need to be able to add e.g. "click" listeners to the same element. So it wouldn't be a good DX to have to modify an existing attribute, change it from string to array, etc.

@DAreRodz

PS: Another possibility: append the ID after the suffix with the event type.

That would be a great solution IMO. It ties in nicely with the existing approach on data-wp-init--{uniqueId} and data-wp-watch--{uniqueId}. So basically we would have data-wp-on--{event}--{uniqueId}. It keeps attributes separate, so separate plugins could easily add them.

[felixarntz]

This is a great example on how the current limitation actually limits even important features like the client-side navigation. It wouldn't work for any a tags that already use the Interactivity API in certain ways, which would be a major drawback.

[gziolo]

I’m inclined to consider it a bug in the implementation given that multiple handlers are possible for other directives. I also learned today that Woo had it implemented in their custom version of Interactivity API which they might be even using in production for quite some time. I still need to research it and report back with more insights.

[DAreRodz]

I've created a PR to solve this. It's based on the Woo implementation.

• Interactivity API: Allow multiple event handlers for the same type with data-wp-on. #60661

[westonruter]

Let's say this is settled then. Let's continue discussing the second part of this topic: #60574 (comment)

[gziolo]

The second part is indeed important but also more difficult to address.

[westonruter]

Let's say it's settled that multiple actions can be attached to an event, whether it is via a unique ID suffix or some array syntax. The question then remains how we can safeguard performance. And that's the second part of the discussion topic. There should be a way to register an action for an event which can be run entirely asynchronously. Related to this is the docs on async actions and the use of generators as actions. The async actions there are those which run synchronously and then allow for an asynchronous break in execution (e.g. to perform a fetch() after first having called event.preventDefault()). However, in the case for analytics trackers, there is no need for synchronous access to the event object. They should be added as passive event listeners and/or the action should be wrapped in some logic that immediately yields to the main thread (cf. #58225/#58227). This would help guard against the click event from causing a long task that hurts INP.

One way to do this would be to introduce some mainThread() function in the @wordpress/interactivity package which an action could proactively use for performance. For example, an analytics provider could do:

import { store, mainThread } from '@wordpress/interactivity';

store( "myPlugin", {
  actions: {
    *trackClick() {
      yield mainThread();
      // Now do tracking logic...
    },
  },
} );

This would be a useful tool in the toolbox for tuning the performance of actions regardless (e.g. to break up a computationally-expensive action), but it's yet another thing that a developer has to know. Ideally such actions could be asynchronous by default so that a manual yield mainThread() wouldn't be necessary. How could an action indicate it can be called entirely async? Even more could actions default to being asynchronous with others explicitly declaring that they need synchronous access to event?

[westonruter]

I think that makes sense. Also, in addition to the event handler being made passive (which isn't actually supported in Preact right now), the behavior here could be simply to yield to main immediately before invoking the action. When an event directive is marked as passive, this would always be safe to do.

Also, maybe data-wp-on-async--click would be better, to mention async rather than passive? This would have less of a negative connotation and it would perhaps be more accurate technically (as again Preact doesn't support passive events).

As for it having been ideal to be the other way around from the start, perhaps we can mitigate this with tooling to identify any wp-on directives which should rather be wp-on-async? If the action lacks any reference to preventDefault then this could be done. Also, documentation should highlight that wp-on-async should be used by default for best performance, unless synchronous access to the event object is required.

[luisherranz]

the behavior here could be simply to yield to main immediately before invoking the action

I like that.

maybe data-wp-on-async--click would be better

That would be better, yes.

documentation should highlight that wp-on-async should be used by default for best performance

Yes, we can make that very clear in the docs and replace all the examples that currently use data-wp-on, including the create-block template.

we can mitigate this with tooling to identify any wp-on directives which should rather be wp-on-async?

The problem is that the directive is in PHP, and the action is in JS. So we can't do it without a tool that understands both and their connection, which seems challenging, at least for now.

[westonruter]

Yes, I think the tool would have to be running as part of the JS runtime.

[westonruter]

I've filed this as a new issue: #61634

[westonruter]

Initial PR: #61885

[sirreal]

With #60661 and #61885 both landed, is this work complete?

[westonruter]

I think so. We'll need to monitor adoption and the performance impact. We also should consider ways to inform developers when they're using wp-on when they should rather be using wp-on-async. Relatedly, I've opened #62665 to export yieldToMain as part of @wordpress/interactivity so that when a developer must resort to wp-on they can still add yield points after they have called event.preventDefault() for example.

PR with documentation updates: #62663

[luisherranz]

Closing this as completed 🙂