LiveView implementation of modal component.

This component is a general purpose modal implementation for LiveView with emphasis on keeping nested components largely agnostic of the fact that they are placed in a modal and maintaining good user experience on connections with high latency.

Usage

An example use case for a modal is embedding a form inside existing live view which allows adding new entries of some kind:

<.live_component module={Modal} id="some-form-modal" :let={modal_unique_id}>
  <.live_component
    module={SomeForm}
    id={"some-form-#{modal_unique_id}"}
    on_save_form={
      fn entry, socket ->
        send(self(), {:entry_added, entry})
        Modal.close(socket, "some-form-modal")
      end
    }
  />
</.live_component>

Then somewhere in the same live view the modal is rendered in:

<.button x-data x-on:click={Modal.JS.open("goals-form-modal")}>
  + Add Entry
</.button>

Explanation

The component embedded inside the modal is always rendered when the live view is mounted but is kept hidden until Modal.JS.open is called on it. On subsequent openings within the same session the contents of the modal are completely remounted. This assures that any stateful components inside the modal are reset to their initial state. The modal component provides modal_unique_id as an argument to its inner block. Appending this ID to every live components' ID nested inside the modal is important for consistent state reset on every reopening. This also applies to live components nested inside live components embedded directly in the modal's inner block - then the unique ID should be also passed down as an attribute and appended accordingly. Appending can be skipped if embedded component handles state reset explicitly (via, for instance, phx-click-away callback).

Modal exposes a number of functions for managing window state:

• Modal.JS.preopen/1 - to preopen the modal on the frontend. Useful when the actual opening is done server-side with Modal.open/2 - helps avoid lack of feedback to the end user when server-side state change before opening the modal is still in progress.

• Modal.JS.open/1 - to open the modal from the frontend. It's important to make sure the element triggering that call is wrapped in an Alpine UI component - or is an Alpine component itself - adding x-data attribute without any value is enough to ensure that.

• Modal.open/2 - to open the modal from the backend; usually called from handle_event/2 of component wrapping the modal and providing the state. Should be used together with Modal.JS.preopen/1 for optimal user experience.

• Modal.close/2 - to close the modal from the backend; usually done inside wrapped component's handle_event/2. The example quoted above shows one way to implement this, under that assumption that the component exposes a callback, like this:

  defmodule SomeForm do
    use Phoenix.LiveComponent
  
    def update(assigns, socket) do
      # ...
  
      {:ok, assign(socket, :on_save_form, assigns.on_save_form)}
    end
  
    #...
  
    def handle_event("save-form", %{"form" => form}, socket) do
      case save_entry(form) do
        {:ok, entry} ->
          {:noreply, socket.assigns.on_save_form(entry, socket)}
  
        # error case handling ...
      end
    end
  end

  Using callback approach has an added benefit of making the component more flexible.