Rewords

Author: squrious

src/LiveComponent/doc/index.rst

@@ -2081,6 +2081,8 @@ then render it manually after:
 
     {{ form_widget(form.todoItems.vars.button_add, { label: '+ Add Item', attr: { class: 'btn btn-outline-primary' } }) }}
 
+.. _validation:
+
 Validation (without a Form)
 ---------------------------
 
@@ -2302,14 +2304,14 @@ You can also trigger a specific "action" instead of a normal re-render:
         #}
     >
 
-Binding LiveProp to URL query parameters
+Changing the URL when a LiveProp changes
 ----------------------------------------
 
-.. versionadded:: 2.13
+.. versionadded:: 2.14
 
-    The ``url`` option was introduced in Live Components 2.13.
+    The ``url`` option was introduced in Live Components 2.14.
 
-You can bind your component LiveProp's values to URL query parameters thanks to the ``url`` option::
+If you want the URL to update when a ``LiveProp`` changes, you can do that with the ``url`` option::
 
     // src/Components/SearchModule.php
     namespace App\Components;
@@ -2327,43 +2329,41 @@ You can bind your component LiveProp's values to URL query parameters thanks to
         public string $query = '';
     }
 
-Now if you change the value of the ``query`` prop, the url will be updated to reflect the new state of your
-component, for example: ``https://my.domain/search?query=my+search+string``.
+Now, when the user changes the value of the ``query`` prop, a query parameter in the URL will be updated to reflect the
+new state of your component, for example: ``https://my.domain/search?query=my+search+string``.
 
-Then, if you load this URL in your browser, your component will be initialized with the values provided in the query
-string.
+If you load this URL in your browser, the ``LiveProp`` value will be initialized using the query string
+(e.g. ``my search string``).
 
 .. note::
 
-    URL is updated in place, no new entry is added to the browser's history.
+    The URL is changed via ``history.replaceState()``. So no new entry is added.
 
 .. warning::
 
     You can use multiple components with URL bindings in the same page, as long as bound field names don't collide.
     Otherwise, you will observe unexpected behaviors.
 
-Supported data types
+Supported Data Types
 ~~~~~~~~~~~~~~~~~~~~
 
 You can use scalars, arrays and objects in your URL bindings:
 
 ============================================  =================================================
-``prop`` value                                URL representation
+JavaScript ``prop`` value                     URL representation
 ============================================  =================================================
 ``'some search string'``                      ``prop=some+search+string``
 ``42``                                        ``prop=42``
 ``['foo', 'bar']``                            ``prop[0]=foo&prop[1]=bar``
 ``{ foo: 'bar', baz: 42 }``                   ``prop[foo]=bar&prop[baz]=42``
 
 
-.. note::
-
-    Type consistency is enforced by the LiveComponent internal hydrator when the component is initialized with query
-    parameters. If a value could not be hydrated properly, it will be ignored to avoid unfriendly errors for the end
-    user.
+When a page is loaded with a query parameter that's bound to a ``LiveProp`` (e.g. ``/search?query=my+search+string``),
+the value - ``my search string`` - goes through the hydration system before it's set onto the property. If a value can't
+be hydrated, it will be ignored.
 
-Multiple bindings
-~~~~~~~~~~~~~~~~~
+Multiple Query Parameter Bindings
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 You can use as many URL bindings as you want in your component. To ensure the state is fully represented in the URL,
 all bound props will be set as query parameters, even if their values didn't change.
@@ -2384,17 +2384,15 @@ For example, if you declare the following bindings::
     }
 
 
-And you only set the ``query`` value, then your URL will be updated to ``https://my.domain/search?query=my+query+string&mode=fulltext``.
+And you only set the ``query`` value, then your URL will be updated to
+``https://my.domain/search?query=my+query+string&mode=fulltext``.
 
-Validation
-~~~~~~~~~~
-
-.. caution::
-
-    It is recommended to validate data provided through query string parameters, so you can prevent malicious inputs
-    from being processed and rendered.
+Validating the Query Parameter Values
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-To validate your component state when it is rendered for the first time, you have to setup a `PostMount hook`_::
+Like any writable ``LiveProp``, because the user can modify this value, you should consider adding
+:ref:`validation <validation>`. When you bind a ``LiveProp`` to the URL, the initial value is not automatically
+validated. To validate it, you have to set up a `PostMount hook`_::
 
     // ...
     use Symfony\Component\Validator\Constraints as Assert;
@@ -2416,8 +2414,11 @@ To validate your component state when it is rendered for the first time, you hav
         #[PostMount]
         public function postMount(): void
         {
-            // Validate 'mode' field without throwing an exception
-            $this->validateField('mode', false);
+            // Validate 'mode' field without throwing an exception, so the component can be mounted anyway and a
+            // validation error can be shown to the user
+            if (!$this->validateField('mode', false)) {
+                // Do something when validation fails
+            }
         }
 
         // ...