clarify navigation in chained JS commands

Closes #4411.

Author: SteffenDE

lib/phoenix_live_view/js.ex

@@ -206,6 +206,17 @@ defmodule Phoenix.LiveView.JS do
   it is guaranteed that the event will be pushed first and the patch will only be handled after
   the first event was handled by the LiveView.
 
+  > #### A note on navigation {: .warning}
+  >
+  > When `JS.push` is followed by navigation that replaces the current LiveView,
+  > such as `JS.navigate`, the navigation may terminate the LiveView while it is
+  > still handling the pushed event. The commands are executed in order, but the
+  > event handler is not guaranteed to complete. If the event must finish before
+  > navigation, initiate the navigation from `handle_event/3` instead, for example
+  > with `push_navigate/2`.
+  >
+  > This does not apply to `JS.patch`, which keeps the current LiveView process running.
+
   '''
   alias Phoenix.LiveView.JS