[Doc] Update the docs about the mount() method of Twig components

Author: javiereguiluz

src/TwigComponent/doc/index.rst

@@ -447,15 +447,25 @@ need to populate, you can render it with:
 Mounting Data
 -------------
 
-Most of the time, you will create public properties and then pass values
-to those as "props" when rendering. But there are several hooks in case
-you need to do something more complex.
+Most of the time, you will create public properties and pass values to them
+as "props" when rendering the component. However, there are several hooks
+available when you need to perform more complex logic.
 
 The mount() Method
 ~~~~~~~~~~~~~~~~~~
 
-For more control over how your "props" are handled, you can create a method
-called ``mount()``::
+The ``mount()`` method gives you more control over how your "props" are handled.
+It is called only once: immediately after your component is instantiated.
+The ``mount()`` method **cannot access the values of the public properties**
+passed when rendering the component.
+
+For example, if you call your component like this:
+
+.. code-block:: twig
+
+    <twig:Alert type="error" message="..."/>
+
+The following code won't work as expected:
 
     // src/Twig/Components/Alert.php
     // ...
@@ -466,29 +476,46 @@ called ``mount()``::
         public string $message;
         public string $type = 'success';
 
-        public function mount(bool $isSuccess = true): void
+        public function mount(): void
         {
-            $this->type = $isSuccess ? 'success' : 'danger';
+            {# ❌ this won't work: at this point, the $type property still has its
+                   default value. Passed properties are not yet available. #}
+            if ('error' === $this->type) {
+                // ...
+            }
         }
 
         // ...
     }
 
-The ``mount()`` method is called just one time: immediately after your
-component is instantiated. Because the method has an ``$isSuccess``
-argument, if we pass an ``isSuccess`` prop when rendering, it will be
-passed to ``mount()``.
+Instead, define the values you need in the ``mount()`` method as arguments::
 
-.. code-block:: html+twig
+    #[AsTwigComponent]
+    class Alert
+    {
+        public string $message;
+        public string $type = 'success';
 
-    <twig:Alert
-        isSuccess="{{ false }}"
-        message="Danger Will Robinson!"
-    />
+        public function mount(bool $isError = false): void
+        {
+            {# ✅ this works as expected #}
+            if ($isError) {
+                // ...
+            }
+        }
+
+        // ...
+    }
+
+Now, pass the ``mount()`` argument like any other prop:
+
+.. code-block:: twig
+
+    <twig:Alert isError="{{ true }}" message="..."/>
 
-If a prop name (e.g. ``isSuccess``) matches an argument name in ``mount()``,
-the prop will be passed as that argument and the component system will
-**not** try to set it directly on a property or use it for the component
+If a prop name (e.g. ``isError``) matches an argument name in ``mount()``,
+its value will be passed to the method. In that case, the component system
+**will not** set it on a public property or use it in the component's
 ``attributes``.
 
 PreMount Hook