Add blocking: true to JS.dispatch (#3615)

* Add blocking: true to JS.dispatch

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:

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

```javascript
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.

* add test for blocking: true

* fail when done key is already used

Author: SteffenDE

assets/js/phoenix_live_view/js.js

@@ -71,10 +71,16 @@ const JS = {
     view,
     sourceEl,
     el,
-    { event, detail, bubbles },
+    { event, detail, bubbles, blocking },
   ) {
     detail = detail || {};
     detail.dispatcher = sourceEl;
+    if (blocking) {
+      const promise = new Promise((resolve, _reject) => {
+        detail.done = resolve;
+      });
+      view.liveSocket.asyncTransition(promise);
+    }
     DOM.dispatchEvent(el, event, { detail, bubbles });
   },
 

assets/js/phoenix_live_view/live_socket.js

@@ -265,6 +265,10 @@ export default class LiveSocket {
     this.transitions.after(callback);
   }
 
+  asyncTransition(promise) {
+    this.transitions.addAsyncTransition(promise);
+  }
+
   transition(time, onStart, onDone = function () {}) {
     this.transitions.addTransition(time, onStart, onDone);
   }
@@ -1206,6 +1210,7 @@ export default class LiveSocket {
 class TransitionSet {
   constructor() {
     this.transitions = new Set();
+    this.promises = new Set();
     this.pendingOps = [];
   }
 
@@ -1214,6 +1219,7 @@ class TransitionSet {
       clearTimeout(timer);
       this.transitions.delete(timer);
     });
+    this.promises.clear();
     this.flushPendingOps();
   }
 
@@ -1235,12 +1241,20 @@ class TransitionSet {
     this.transitions.add(timer);
   }
 
+  addAsyncTransition(promise) {
+    this.promises.add(promise);
+    promise.then(() => {
+      this.promises.delete(promise);
+      this.flushPendingOps();
+    });
+  }
+
   pushPendingOp(op) {
     this.pendingOps.push(op);
   }
 
   size() {
-    return this.transitions.size;
+    return this.transitions.size + this.promises.size;
   }
 
   flushPendingOps() {

assets/test/js_test.ts

@@ -447,6 +447,7 @@ describe("JS", () => {
       modal.addEventListener("click", () => done());
       JS.exec(event, "click", click.getAttribute("phx-click"), view, click);
     });
+
     test("with details", (done) => {
       const view = setupView(`
       <div id="modal">modal</div>
@@ -492,6 +493,32 @@ describe("JS", () => {
 
       JS.exec(event, "close", close.getAttribute("phx-click"), view, close);
     });
+
+    test("blocking blocks DOM updates until done", (done) => {
+      let view = setupView(`
+      <div id="modal">modal</div>
+      <div id="click" phx-click='[["dispatch", {"to": "#modal", "event": "custom", "blocking": true}]]'></div>
+      `);
+      let modal = simulateVisibility(document.querySelector("#modal"));
+      let click = document.querySelector("#click");
+      let doneCalled = false;
+
+      modal.addEventListener("custom", (e) => {
+        expect(e.detail).toEqual({
+          done: expect.any(Function),
+          dispatcher: click,
+        });
+        expect(view.liveSocket.transitions.size()).toBe(1);
+        view.liveSocket.requestDOMUpdate(() => {
+          expect(doneCalled).toBe(true);
+          done();
+        });
+        // now we unblock the transition
+        e.detail.done();
+        doneCalled = true;
+      });
+      JS.exec(event, "click", click.getAttribute("phx-click"), view, click);
+    });
   });
 
   describe("exec_add_class and exec_remove_class", () => {

lib/phoenix_live_view/js.ex

@@ -266,6 +266,9 @@ defmodule Phoenix.LiveView.JS do
       with the client event. The details will be available in the
       `event.detail` attribute for event listeners.
     * `:bubbles` – A boolean flag to bubble the event or not. Defaults to `true`.
+    * `:blocking` - A boolean flag to block the UI until the event handler calls `event.detail.done()`.
+      The done function is injected by LiveView and *must* be called eventually to unblock the UI.
+      This is useful to integrate with third party JavaScript based animation libraries.
 
   ## Examples
 
@@ -283,7 +286,7 @@ defmodule Phoenix.LiveView.JS do
 
   @doc "See `dispatch/2`."
   def dispatch(%JS{} = js, event, opts) do
-    opts = validate_keys(opts, :dispatch, [:to, :detail, :bubbles])
+    opts = validate_keys(opts, :dispatch, [:to, :detail, :bubbles, :blocking])
     args = [event: event, to: opts[:to]]
 
     args =
@@ -298,6 +301,21 @@ defmodule Phoenix.LiveView.JS do
           args
       end
 
+    if opts[:blocking] do
+      case opts[:detail] do
+        map when is_map(map) and (is_map_key(map, "done") or is_map_key(map, :done)) ->
+          raise ArgumentError, """
+          the detail map passed to JS.dispatch must not contain a `done` key
+          when `blocking: true` is used!
+
+          Got: #{inspect(map)}
+          """
+
+        _ ->
+          :ok
+      end
+    end
+
     args =
       case {event, Keyword.fetch(opts, :detail)} do
         {"click", {:ok, _detail}} ->
@@ -322,6 +340,15 @@ defmodule Phoenix.LiveView.JS do
           args
       end
 
+    args =
+      case Keyword.get(opts, :blocking) do
+        true ->
+          Keyword.put(args, :blocking, opts[:blocking])
+
+        _ ->
+          args
+      end
+
     put_op(js, "dispatch", args)
   end
 

test/phoenix_live_view/js_test.exs

@@ -477,6 +477,12 @@ defmodule Phoenix.LiveView.JSTest do
       assert js_to_string(JS.dispatch("click", to: ".foo")) ==
                "[["dispatch",{"event":"click","to":".foo"}]]"
     end
+
+    test "raises when done is a details key and blocking is true" do
+      assert_raise ArgumentError, ~r/must not contain a `done` key/, fn ->
+        JS.dispatch("foo", detail: %{done: true}, blocking: true)
+      end
+    end
   end
 
   describe "toggle" do