Change expected return values of item and resource action handle functions

lib/backpex/item_actions/item_action.ex

@@ -75,9 +75,19 @@ defmodule Backpex.ItemAction do
 
   @doc """
   Performs the action. It takes the socket and the casted and validated data (received from [`Ecto.Changeset.apply_action/2`](https://hexdocs.pm/ecto/Ecto.Changeset.html#apply_action/2)).
+
+  You must return either `{:noreply, socket}` or `{:error, changeset}`.
+
+  If `{:noreply, socket}` is returned, the action is considered successful and the action modal is closed.
+
+  If `{:error, changeset}` is returned, the changeset is used to update the form to display the errors. Note that Backpex already validates the form for you.
+  Therefore it is only necessary in rare cases to perform additional validation and return a changeset from `c:handle/3`.
+  For example, if you are building a duplicate action and can only check for a unique constraint when inserting the duplicate element.
+
+  You are only allowed to return `{:error, changeset}` if the action has a form. Otherwise Backpex will throw an ArgumentError.
   """
   @callback handle(socket :: Phoenix.LiveView.Socket.t(), items :: list(map()), params :: map() | struct()) ::
-              {:noreply, Phoenix.LiveView.Socket.t()} | {:reply, map(), Phoenix.LiveView.Socket.t()}
+              {:noreply, Phoenix.LiveView.Socket.t()} | {:error, Ecto.Changeset.t()}
 
   @optional_callbacks confirm: 1, confirm_label: 1, cancel_label: 1, changeset: 3, fields: 0
 

lib/backpex/live_components/form_component.ex

@@ -338,27 +338,23 @@ defmodule Backpex.FormComponent do
         } = assigns
     } = socket
 
+    params = drop_readonly_changes(params, fields, assigns)
+
     result =
       item
       |> Backpex.Resource.change(params, fields, assigns, live_resource)
       |> Ecto.Changeset.apply_action(:insert)
 
-    case result do
-      {:ok, data} ->
-        selected_items =
-          Enum.filter(selected_items, fn item ->
-            live_resource.can?(socket.assigns, action_key, item)
-          end)
-
-        {message, socket} =
-          socket
-          |> assign(:show_form_errors, false)
-          |> assign(selected_items: [])
-          |> assign(select_all: false)
-          |> action_to_confirm.module.handle(selected_items, data)
-
-        {message, push_patch(socket, to: return_to)}
+    with {:ok, data} <- result,
+         selected_items <- Enum.filter(selected_items, &live_resource.can?(socket.assigns, action_key, &1)),
+         {:noreply, socket} <- action_to_confirm.module.handle(socket, selected_items, data) do
+      socket
+      |> assign(:show_form_errors, false)
+      |> assign(:selected_items, [])
+      |> assign(:select_all, false)
 
+      {:noreply, push_patch(socket, to: return_to)}
+    else
       {:error, changeset} ->
         form = Phoenix.Component.to_form(changeset, as: :change)
 

lib/backpex/live_resource.ex

@@ -1199,11 +1199,25 @@ defmodule Backpex.LiveResource do
     %{live_resource: live_resource} = socket.assigns
     items = Enum.filter(items, fn item -> live_resource.can?(socket.assigns, key, item) end)
 
-    socket
-    |> assign(action_to_confirm: nil)
-    |> assign(selected_items: [])
-    |> assign(select_all: false)
-    |> action.module.handle(items, %{})
+    case action.module.handle(socket, items, %{}) do
+      {:noreply, socket} ->
+        socket
+        |> assign(action_to_confirm: nil)
+        |> assign(selected_items: [])
+        |> assign(select_all: false)
+
+        {:noreply, socket}
+
+      unexpected_return ->
+        raise ArgumentError, """
+        Invalid return value from #{inspect(action.module)}.handle/3.
+
+        Expected: {:noreply, socket}
+        Got: #{inspect(unexpected_return)}
+
+        Item Actions with no form fields must return {:noreply, socket}.
+        """
+    end
   end
 
   defp primary_value(socket, item) do