Add onDocumentPatch callback and allow specifying event dispatch phase (#4043)

Relates to: https://elixirforum.com/t/extending-liveview-with-view-transition-api-support/73136

This commit adds a generic dom hook that runs before the view is patched:

```javascript
let liveSocket = new LiveSocket("/live", Socket, {
  dom: {
    onDocumentPatch(start) {
      // do something
      // then trigger the patch
      start();
    }
  }
})
```

This can be used to call [document.startViewTransition](https://developer.mozilla.org/en-US/docs/Web/API/Document/startViewTransition).

To be able to customize what kind of view transition to perform, this
commit also introduces a new optional fourth parameter on
`Phoenix.LiveView.push_event/3`. By default, events are only dispatched
after the view is patched, but sometimes it is useful to run some code
before patching the DOM:

```elixir
def mount(_params, _session, socket) do
  {:ok,
   socket
   |> assign(...)
   |> push_event("start-view-transition", %{type: "page"}, dispatch: :before)}
end
```

This event will be dispatched before performing the initial mount patch.

Author: SteffenDE

assets/js/phoenix_live_view/index.ts

@@ -146,6 +146,27 @@ export interface LiveSocketOptions {
       query: string,
       defaultQuery: () => Element[],
     ) => Element[];
+    /**
+     * When defined, called with a start callback that needs to be called
+     * to perform the actual patch. Failing to call the start callback causes
+     * the page to become stuck.
+     *
+     * This can be used to delay patches in order to perform view transitions,
+     * for example:
+     *
+     * ```javascript
+     * let liveSocket = new LiveSocket("/live", Socket, {
+     *   dom: {
+     *     onDocumentPatch(start) {
+     *       document.startViewTransition(start);
+     *     }
+     *   }
+     * })
+     * ```
+     *
+     * It is strongly advised to call start as quickly as possible.
+     */
+    onDocumentPatch?: (start: () => void) => void;
     /**
      * Called immediately before a DOM patch is applied.
      */

assets/js/phoenix_live_view/view.js

@@ -316,9 +316,36 @@ export default class View {
   applyDiff(type, rawDiff, callback) {
     this.log(type, () => ["", clone(rawDiff)]);
     const { diff, reply, events, title } = Rendered.extract(rawDiff);
-    callback({ diff, reply, events });
-    if (typeof title === "string" || (type == "mount" && this.isMain())) {
-      window.requestAnimationFrame(() => DOM.putTitle(title));
+
+    // Events are either [event, payload] or [event, payload, true]
+    // where the optional third element (true) indicates that the event should
+    // be dispatched before the DOM patch. This is useful in combination with
+    // the onDocumentPatch dom callback.
+    const ev = events.reduce(
+      (acc, args) => {
+        if (args.length === 3 && args[2] == true) {
+          acc.pre.push(args.slice(0, -1));
+        } else {
+          acc.post.push(args);
+        }
+        return acc;
+      },
+      { pre: [], post: [] },
+    );
+
+    this.liveSocket.dispatchEvents(ev.pre);
+
+    const update = () => {
+      callback({ diff, reply, events: ev.post });
+      if (typeof title === "string" || (type == "mount" && this.isMain())) {
+        window.requestAnimationFrame(() => DOM.putTitle(title));
+      }
+    };
+
+    if ("onDocumentPatch" in this.liveSocket.domCallbacks) {
+      this.liveSocket.triggerDOM("onDocumentPatch", [update]);
+    } else {
+      update();
     }
   }
 

lib/phoenix_live_view.ex

@@ -779,8 +779,17 @@ defmodule Phoenix.LiveView do
   )
   ```
 
+  ## Specifying the dispatch phase
+
+  By default, events pushed with `push_event/3` are only dispatched after
+  the LiveView is patched. In some cases, handling an event before the LiveView
+  is patched can be useful though. To do this, the `dispatch` option can be passed
+  as fourth argument:
+
+      {:noreply, push_event(socket, "scores", %{points: 100, user: "josé"}, dispatch: :before)}
+
   """
-  defdelegate push_event(socket, event, payload), to: Phoenix.LiveView.Utils
+  defdelegate push_event(socket, event, payload, opts \\ []), to: Phoenix.LiveView.Utils
 
   @doc ~S"""
   Allows an upload for the provided name.

lib/phoenix_live_view/utils.ex

@@ -267,12 +267,22 @@ defmodule Phoenix.LiveView.Utils do
   @doc """
   Annotates the changes with the event to be pushed.
 
-  Events are dispatched on the JavaScript side only after
+  By default, events are dispatched on the JavaScript side only after
   the current patch is invoked. Therefore, if the LiveView
-  redirects, the events won't be invoked.
+  redirects, the events won't be invoked. If the `dispatch: :before` option
+  is passed, this event will be dispatched before patching the DOM.
   """
-  def push_event(%Socket{} = socket, event, %{} = payload) do
-    update_in(socket.private.live_temp[:push_events], &[[event, payload] | &1 || []])
+  def push_event(%Socket{} = socket, event, %{} = payload, opts) do
+    opts = Keyword.validate!(opts, [:dispatch])
+    dispatch_phase = Keyword.get(opts, :dispatch, :after)
+
+    case dispatch_phase do
+      :after ->
+        update_in(socket.private.live_temp[:push_events], &[[event, payload] | &1 || []])
+
+      :before ->
+        update_in(socket.private.live_temp[:push_events], &[[event, payload, true] | &1 || []])
+    end
   end
 
   @doc """