Add doc examples using attach_hook for code organization instead of LiveComponents

guides/introduction/welcome.md

@@ -229,6 +229,8 @@ For authentication, with built-in LiveView support, run `mix phx.gen.auth Accoun
 LiveView supports two extension mechanisms: function components, provided by
 `HEEx` templates, and stateful components, known as LiveComponents.
 
+### Function Components to organize markup
+
 Similar to `render(assigns)` in our LiveView, a function component is any
 function that receives an assigns map and returns a `~H` template. For example:
 
@@ -245,9 +247,82 @@ You can learn more about function components in the `Phoenix.Component`
 module. At the end of the day, they are a useful mechanism for code organization
 and to reuse markup in your LiveViews.
 
+### attach_hook/4 to organize event handling
+
 However, sometimes you need to share more than just markup across LiveViews,
-and you also need to move events to a separate module. For these cases, LiveView
-provide `Phoenix.LiveComponent`, which are rendered using
+and you also need to move events to a separate module. For these cases you
+can use `Phoenix.LiveView.attach_hook/4`
+
+    defmodule DemoLive do
+      use Phoenix.LiveView
+
+      def render(assigns) do
+        ~H"""
+        <div>
+          <div>
+            Counter: {@counter}
+            <button phx-click="inc">+</button>
+          </div>
+
+          <MySortComponent.display lists={[first_list: @first_list, second_list: @second_list]} />
+        </div>
+        """
+      end
+
+      def mount(_params, _session, socket) do
+        first_list = for(i <- 1..9, do: "First List #{i}") |> Enum.shuffle()
+        second_list = for(i <- 1..9, do: "Second List #{i}") |> Enum.shuffle()
+
+        socket =
+          socket
+          |> assign(:counter, 0)
+          |> assign(first_list: first_list)
+          |> assign(second_list: second_list)
+          |> attach_hook(:sort, :handle_event, &MySortComponent.hooked_event/3)  # 2) Delegated events
+        {:ok, socket}
+      end
+
+      # 1) Normal event
+      def handle_event("inc", _params, socket) do
+        {:noreply, update(socket, :counter, &(&1 + 1))}
+      end
+    end
+
+    defmodule MySortComponent do
+      use Phoenix.Component
+
+      def display(assigns) do
+        ~H"""
+        <div :for={{key, list} <- @lists}>
+          <ul><li :for={item <- list}>{item}</li></ul>
+          <button phx-click="shuffle" phx-value-list={key}>Shuffle</button>
+          <button phx-click="sort" phx-value-list={key}>Sort</button>
+        </div>
+        """
+      end
+
+      def hooked_event("shuffle", %{"list" => key}, socket) do
+        key = String.to_existing_atom(key)
+        shuffled = Enum.shuffle(socket.assigns[key])
+
+        {:halt, assign(socket, key, shuffled)}
+      end
+
+      def hooked_event("sort", %{"list" => key}, socket) do
+        key = String.to_existing_atom(key)
+        sorted = Enum.sort(socket.assigns[key])
+
+        {:halt, assign(socket, key, sorted)}
+      end
+
+      def hooked_event(_event, _params, socket), do: {:cont, socket}
+    end
+
+### Live Components to encapsulate additional state
+
+A component will occasionally need control over not only it's own events,
+but also it's own seperate state. For these cases, LiveView
+provides `Phoenix.LiveComponent`, which are rendered using
 [`live_component/1`](`Phoenix.Component.live_component/1`):
 
 ```heex
@@ -261,6 +336,11 @@ are more complex than function components themselves. Given they all run in the
 same process, errors in components cause the whole view to fail to render.
 For a complete rundown, see `Phoenix.LiveComponent`.
 
+When in doubt over [Functional components or live components?](`Phoenix.LiveComponent#functional-components-or-live-components`), default to the former.
+Rely on the latter only when you need the additional state.
+
+### live_render/3 to encapsulate state (with error isolation)
+
 Finally, if you want complete isolation between parts of a LiveView, you can
 always render a LiveView inside another LiveView by calling
 [`live_render/3`](`Phoenix.Component.live_render/3`). This child LiveView
@@ -277,11 +357,23 @@ Given that it runs in its own process, a nested LiveView is an excellent tool
 for creating completely isolated UI elements, but it is a slightly expensive
 abstraction if all you want is to compartmentalize markup or events (or both).
 
-To sum it up:
+### Summary
+
+In LiveViews we may want to organize code by extracting related sections to another module
+
+There are four common situations
+  1. Extract html
+  2. Extract html and related handle_events
+  3. Extract html, handle_events, and create additional separate state
+  4. Same as 3, but with error isolation
+
+  For 1, we have [FunctionComponents](`Phoenix.Component`)
+
+  For 2, we can combine FunctionComponents & [attach_hook/4](`Phoenix.LiveView.attach_hook/4`)
+
+  Situation 3 is covered by [LiveComponents](`Phoenix.LiveComponent`)
 
-  * use `Phoenix.Component` for code organization and reusing markup
-  * use `Phoenix.LiveComponent` for sharing state, markup, and events between LiveViews
-  * use nested `Phoenix.LiveView` to compartmentalize state, markup, and events (with error isolation)
+  Finally, for 4 we use nested `Phoenix.LiveView` via live_render/3
 
 ## Guides
 

lib/phoenix_live_view.ex

@@ -1508,6 +1508,12 @@ defmodule Phoenix.LiveView do
   interoperability](js-interop.html#client-hooks-via-phx-hook) because a client hook
   can push an event and receive a reply.
 
+  ## Organizing code
+
+  Lifecycle hooks are an excellent way to extract related events out of the parent LiveView and
+  into seperate modules without resorting unnecessarily to LiveComponents for organization.
+  An example can be found in ["Compartmentalize state, markup, and events in LiveView"](welcome.md#attach_hook-4-to-organize-event-handling)
+
   ## Examples
 
   Attaching and detaching a hook: