Add onDocumentPatch callback and allow specifying event dispatch phase

[SteffenDE]

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

https://gist.github.com/SteffenDE/cf7cdb91ba037b08cdc583763e4ffc69

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

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

This can be used to call 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:

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.

Thanks to @spicychickensauce!

[josevalim]

I am wondering if it should be called beforePatch, given it receives a function, which I assume does the whole patching, and therefore you can execute something afterwards? There is also onPatchStart and onPatchEnd, which could add to the confusion.

I'd suggest something like onDocumentPatchStart or onDocumentPatch, to make it clear this is invoked before patching the whole document. Or onTreePatchStart etc. Thoughts?

[SteffenDE]

I like onDocumentPatch!