From c8113e04a853d293365ae9307f1c69ba5e63c0af Mon Sep 17 00:00:00 2001
From: srich387 <64944171+srich387@users.noreply.github.com>
Date: Mon, 1 Jan 2024 14:27:41 +1100
Subject: [PATCH] [live-component docs] Rearrange information about using
 custom Stimulus controllers

In the section 'Working with the Component in JavaScript', the preamble mentions that you can create a custom Stimulus controller and attach it to or put it around the root component element in order to control its behaviour.

How to attach a custom controller is only explained further down in the subsection 'Adding a Stimulus Controller to your Component Root Element'. This subsection is currently buried beneath an intervening subsection on a different topic, 'JavaScript Component Hooks', making it easy for a reader to overlook.

As such, to improve the logical flow of the documentation, I have swapped these two subsections around.

It is especially important that this information is presented clearly because it has caused confusion in the past; see e.g. #687.
---
 src/LiveComponent/doc/index.rst | 30 +++++++++++++++---------------
 1 file changed, 15 insertions(+), 15 deletions(-)

diff --git a/src/LiveComponent/doc/index.rst b/src/LiveComponent/doc/index.rst
index 3ea663a633f..6c491397565 100644
--- a/src/LiveComponent/doc/index.rst
+++ b/src/LiveComponent/doc/index.rst
@@ -842,6 +842,21 @@ of the change:
 
     input.dispatchEvent(new Event('change', { bubbles: true }));
 
+Adding a Stimulus Controller to your Component Root Element
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. versionadded:: 2.9
+
+    The ability to use the ``defaults()`` method with ``stimulus_controller()``
+    was added in TwigComponents 2.9 and requires ``symfony/stimulus-bundle``.
+    Previously, ``stimulus_controller()`` was passed to ``attributes.add()``.
+
+To add a custom Stimulus controller to your root component element:
+
+.. code-block:: html+twig
+
+    <div {{ attributes.defaults(stimulus_controller('my-controller', { someValue: 'foo' })) }}>
+
 JavaScript Component Hooks
 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -876,21 +891,6 @@ The following hooks are available (along with the arguments that are passed):
 * ``loading.state:finished`` args ``(element: HTMLElement)``
 * ``model:set`` args ``(model: string, value: any, component: Component)``
 
-Adding a Stimulus Controller to your Component Root Element
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-.. versionadded:: 2.9
-
-    The ability to use the ``defaults()`` method with ``stimulus_controller()``
-    was added in TwigComponents 2.9 and requires ``symfony/stimulus-bundle``.
-    Previously, ``stimulus_controller()`` was passed to ``attributes.add()``.
-
-To add a custom Stimulus controller to your root component element:
-
-.. code-block:: html+twig
-
-    <div {{ attributes.defaults(stimulus_controller('my-controller', { someValue: 'foo' })) }}>
-
 Loading States
 --------------