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 and event handling
+
 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,16 @@ 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.
 
-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
+Sometimes you need to share more than just markup across LiveViews. When you also
+want to move events to a seperate module, or use the same event handler in multiple
+places, function components can be paired with
+[`Phoenix.LiveView.attach_hook/4`](`Phoenix.LiveView.attach_hook/4#sharing-event-handling-logic`)
+
+### Live components to encapsulate additional state
+
+A component will occasionally need control over not only its own events,
+but also its 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 +270,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,9 +291,9 @@ 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
   * use `Phoenix.Component` for code organization and reusing markup
+  * pair `Phoenix.Component` with [`attach_hook/4`](`Phoenix.LiveView.attach_hook/4#sharing-event-handling-logic`) to organize and reuse event handling
   * use `Phoenix.LiveComponent` for sharing state, markup, and events between LiveViews
   * use nested `Phoenix.LiveView` to compartmentalize state, markup, and events (with error isolation)
 

lib/phoenix_live_view.ex

@@ -1508,7 +1508,77 @@ 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.
 
-  ## Examples
+  ## Sharing event handling logic
+
+  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.
+
+      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
+
+  ## Other examples
 
   Attaching and detaching a hook: