Add doc for URL binding feature

Author: squrious

src/LiveComponent/doc/index.rst

@@ -2302,6 +2302,114 @@ You can also trigger a specific "action" instead of a normal re-render:
         #}
     >
 
+Binding LiveProp to URL query parameters
+----------------------------------------
+
+.. versionadded:: 2.13
+
+    The ``url`` option was introduced in Live Components 2.13.
+
+You can bind your component LiveProp's values to URL query parameters thanks to the ``url`` option::
+
+    // src/Components/SearchModule.php
+    namespace App\Components;
+
+    use Symfony\UX\LiveComponent\Attribute\AsLiveComponent;
+    use Symfony\UX\LiveComponent\Attribute\LiveProp;
+    use Symfony\UX\LiveComponent\DefaultActionTrait;
+
+    #[AsLiveComponent]
+    class SearchModule
+    {
+        use DefaultActionTrait;
+
+        #[LiveProp(writable: true, url: true)]
+        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``.
+
+Then, if you load this URL in your browser, your component will be initialized with the values provided in the query
+string.
+
+Supported data types
+~~~~~~~~~~~~~~~~~~~~
+
+You can use scalars, arrays and objects in your URL bindings:
+
+============================================  =================================================
+``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.
+
+Multiple 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 added to query parameters, even if their values didn't change.
+
+For example, if you declare the following bindings::
+
+    // ...
+    #[AsLiveComponent]
+    class SearchModule
+    {
+        #[LiveProp(writable: true, url: true)]
+        public string $query = '';
+
+        #[LiveProp(writable: true, url: true)]
+        public 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
+~~~~~~~~~~
+
+To validate your component state when it is rendered for the first time, you have to setup a `PostMount hook`_::
+
+    // ...
+    use Symfony\Component\Validator\Constraints as Assert;
+    use Symfony\UX\LiveComponent\ValidatableComponentTrait;
+    use Symfony\UX\TwigComponent\Attribute\PostMount;
+
+    #[AsLiveComponent]
+    class SearchModule
+    {
+        use ValidatableComponentTrait;
+
+        #[LiveProp(writable: true, url: true)]
+        public string $query = '';
+
+        #[LiveProp(writable: true, url: true)]
+        #[Assert\NotBlank]
+        public string $mode = 'fulltext';
+
+        #[PostMount]
+        public function postMount(): void
+        {
+            // Validate 'mode' field without throwing an exception
+            $this->validateField('mode', false);
+        }
+
+        // ..
+    }
+
+
 .. _emit:
 
 Communication Between Components: Emitting Events
@@ -3315,3 +3423,4 @@ bound to Symfony's BC policy for the moment.
 .. _`Symfony's built-in form theming techniques`: https://symfony.com/doc/current/form/form_themes.html
 .. _`pass content to Twig Components`: https://symfony.com/bundles/ux-twig-component/current/index.html#passing-blocks
 .. _`Twig Component debug command`: https://symfony.com/bundles/ux-twig-component/current/index.html#debugging-components
+.. _`PostMount hook`: https://symfony.com/bundles/ux-twig-component/current/index.html#postmount-hook