Add blocking: true to JS.dispatch

[SteffenDE]

Relates to: #3516

When integrating external animation libraries like motion.dev, the existing JS functions are not sufficient. Instead, the third party library needs to be triggered via JS. This has the downside of not being able to block the DOM until the animation is complete, which prevents this from working when elements are removed using phx-remove.

This commit introduces a new blocking: true option to JS.dispatch/3, which injects a done function into the event's detail object.

Using this with motion could look like this:

def render(assigns) do
  ~H"""
  <div :if={@show} phx-remove={JS.dispatch("motion:rotate", blocking: true)}>
    ...
  </div>
  """
end

const { animate } = Motion

window.addEventListener("motion:rotate", (e) => {
  animate(e.target, { rotate: [0, 360] }, { duration: 1 }).then(() => {
    if (e.detail.done) {
      e.detail.done()
    }
  })
})

It is still necessary to block the DOM while the remove animation is running, as the remove can happen because of a navigation, where the animation would otherwise not run as the whole LiveView is just replaced.

[josevalim]

Given we already support :blocking in other commands, this is a no-brainer for me. 👍 (although I can't speak for the JS code).

In the long term we want to look at this holistically. Overall we have three distinct capabilities:

1. Lock the whole UI
2. Lock certain elements
3. Annotate an element while there is an event in flux (such as classes we attach to the form)

We already have :blocking to mean 1 and :loading to mean 2 and 3, but we definitely want to expose more granular controls around them. If folks have use cases for them, please let us know, as it will help us refine the APIs (as mentioned in #3516). But once again, I don't think this applies here, :blocking is already available elsewhere, so this makes it consistent.

It is also worth saying that, if you can block the whole UI with the :blocking option, that's the best option, because it guarantees no inconsistencies. That's good as long as what you are doing is perceived by the user as fast. If you lock granular elements, then there is always a chance concurrent updates will interact in weird ways, for example, the element will be removed by a server update in the middle of an animation.

[SteffenDE]

Still todo: tests

[Gazler]

Should we error if detail.done already exists? Seems like something that could already be in use. That being said, since the user has to opt-in to blocking, it's not going to break for anyone upgrading LV.