[Live] Updating docs for removal of data-action-name in favor or Stimulus action params

Author: weaverryan

src/LiveComponent/CHANGELOG.md

@@ -1,5 +1,46 @@
 # CHANGELOG
 
+## 2.16.0
+
+-   [BC BREAK] The `data-action-name` attribute behavior was removed in favor of
+    using Stimulus "action parameters" and `data-live-action-param`. This is a
+    breaking change if you were using the `data-action-name` attribute directly
+    in your templates.
+
+    To upgrade your application, follow these changes:
+
+    ```diff
+    <button
+        data-action="live#action"
+    -    data-action-name="debounce(300)|save"
+    +    data-live-action-param="debounce(300)|save"
+    >Save</button>
+    ```
+
+    To pass arguments to an action, also use the Stimulus "action parameters" syntax:
+
+    ```diff
+    <button
+        data-action="live#action"
+    -     data-action-name="addItem(id={{ item.id }}, itemName=CustomItem)"
+    +     data-live-action-param="addItem"
+    +     data-live-id-param="{{ item.id }}"
+    +     data-live-item-name-param="CustomItem"
+    >Add Item</button>
+    ```
+
+   Additionally, the `prevent` modifier (e.g. `prevent|save`) was removed. Replace
+   this with the standard Stimulus `:prevent` action option:
+
+   ```diff
+   <button
+   -    data-action="live#action
+   +    data-action="live#action:prevent"
+   -    data-action-name="prevent|save"
+   +    data-live-action-param="save"
+    >Save</button>
+   ```
+
 ## 2.15.0
 
 -   [BC BREAK] The `data-live-id` attribute was changed to `id` #1484

src/LiveComponent/doc/index.rst

@@ -1036,14 +1036,21 @@ the work::
         // ...
     }
 
-To call this, add ``data-action="live#action"`` and ``data-action-name``
-to an element (e.g. a button or form):
+.. versionadded:: 2.14
+
+    The ``data-live-action-param`` attribute way of specifying the action
+    was added in Live Components 2.14. Previously, this was done with
+    ``data-live-action-name``.
+
+To call this, trigger the ``action`` method on the ``live`` Stimulus
+controller and pass ``resetMax`` as a `Stimulus action parameter`_ called
+``action``:
 
 .. code-block:: html+twig
 
     <button
         data-action="live#action"
-        data-action-name="resetMax"
+        data-live-action-param="resetMax"
     >Reset Min/Max</button>
 
 Done! When the user clicks this button, a POST request will be sent that
@@ -1058,14 +1065,12 @@ You can also add several "modifiers" to the action:
     <form>
         <button
             data-action="live#action"
-            data-action-name="prevent|debounce(300)|save"
+            data-live-action-param="debounce(300)|save"
         >Save</button>
     </form>
 
-The ``prevent`` modifier would prevent the form from submitting
-(``event.preventDefault()``). The ``debounce(300)`` modifier will add
-300ms of "debouncing" before the action is executed. In other words, if
-you click really fast 5 times, only one Ajax request will be made!
+The ``debounce(300)`` adds 300ms of "debouncing" before the action is executed.
+In other words, if you click really fast 5 times, only one Ajax request will be made!
 
 Actions & Services
 ~~~~~~~~~~~~~~~~~~
@@ -1099,22 +1104,28 @@ This means that, for example, you can use action autowiring::
 Actions & Arguments
 ~~~~~~~~~~~~~~~~~~~
 
-.. versionadded:: 2.1
+.. versionadded:: 2.14
 
-    The ability to pass arguments to actions was added in version 2.1.
+    The ``data-live-{NAME}-param`` attribute way of specifying action
+    arguments was added in Live Components 2.14. Previously, this was done
+    inside the ``data-live-action-name`` attribute.
 
-You can also provide custom arguments to your action:
+You can also pass arguments to your action by adding each as a
+`Stimulus action parameter`_:
 
 .. code-block:: html+twig
 
     <form>
         <button
             data-action="live#action"
-            data-action-name="addItem(id={{ item.id }}, itemName=CustomItem)"
+            data-live-action-param="addItem"
+
+            data-live-id-param="{{ item.id }}"
+            data-live-item-name-param="CustomItem"
         >Add Item</button>
     </form>
 
-In your component, to allow each argument to be passed, we need to add
+In your component, to allow each argument to be passed, add
 the ``#[LiveArg()]`` attribute::
 
     // src/Components/ItemList.php
@@ -1135,10 +1146,6 @@ the ``#[LiveArg()]`` attribute::
         }
     }
 
-Normally, the argument name in PHP - e.g. ``$id`` - should match the
-argument name used in Twig ``id={{ item.id }}``. But if they don't
-match, you can pass an argument to ``LiveArg``, like we did with ``itemName``.
-
 Actions and CSRF Protection
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -1216,10 +1223,11 @@ to handle the files and tell the component when the file should be sent:
 
 .. code-block:: html+twig
 
-    <p>
-        <input type="file" name="my_file" />
-        <button data-action="live#action" data-action-name="files|my_action" />
-    </p>
+    <input type="file" name="my_file" />
+    <button
+        data-action="live#action"
+        data-live-action-param="files|my_action"
+    />
 
 To send a file (or files) with an action use ``files`` modifier.
 Without an argument it will send all pending files to your action.
@@ -1233,11 +1241,11 @@ You can also specify a modifier parameter to choose which files should be upload
         <input type="file" name="multiple[]" multiple />
 
         {# Send only file from first input #}
-        <button data-action="live#action" data-action-name="files(my_file)|myAction" />
+        <button data-action="live#action" data-live-action-param="files(my_file)|myAction" />
         {# You can chain modifiers to send multiple files #}
-        <button data-action="live#action" data-action-name="files(my_file)|files(multiple[])|myAction" />
+        <button data-action="live#action" data-live-action-param="files(my_file)|files(multiple[])|myAction" />
         {# Or send all pending files #}
-        <button data-action="live#action" data-action-name="files|myAction" />
+        <button data-action="live#action" data-live-action-param="files|myAction" />
     </p>
 
 The files will be available in a regular ``$request->files`` files bag::
@@ -1456,8 +1464,8 @@ Next, tell the ``form`` element to use this action:
 
     {{ form_start(form, {
         attr: {
-            'data-action': 'live#action',
-            'data-action-name': 'prevent|save'
+            'data-action': 'live#action:prevent',
+            'data-live-action-param': 'save'
         }
     }) }}
 
@@ -1757,7 +1765,8 @@ and ``removeComment()`` actions:
             {% for key, commentForm in form.comments %}
                 <button
                     data-action="live#action"
-                    data-action-name="removeComment(index={{ key }})"
+                    data-live-action-param="removeComment"
+                    data-live-index-param="{{ key }}"
                     type="button"
                 >X</button>
 
@@ -1769,7 +1778,7 @@ and ``removeComment()`` actions:
 
             <button
                 data-action="live#action"
-                data-action-name="addComment"
+                data-live-action-param="addComment"
                 type="button"
             >+ Add Comment</button>
 
@@ -2172,8 +2181,8 @@ re-rendered. In your template, render errors using an ``_errors`` variable:
 
     <button
         type="submit"
-        data-action="live#action"
-        data-action-name="prevent|save"
+        data-action="live#action:prevent"
+        data-live-action-param="save"
     >Save</button>
 
 Once a component has been validated, the component will "remember" that
@@ -2766,7 +2775,7 @@ suppose your child component has:
 
 .. code-block:: html
 
-    <button data-action="live#action" data-action-name="save">Save</button>
+    <button data-action="live#action" data-live-action-param="save">Save</button>
 
 When the user clicks that button, it will attempt to call the ``save``
 action in the *child* component only, even if the ``save`` action
@@ -2930,7 +2939,7 @@ In the ``EditPost`` template, you render the
 
             <button
                 data-action="live#action"
-                data-action-name="save"
+                data-live-action-param="save"
             >Save</button>
         </form>
     </div>
@@ -3467,3 +3476,4 @@ bound to Symfony's BC policy for the moment.
 .. _`PostMount hook`: https://symfony.com/bundles/ux-twig-component/current/index.html#postmount-hook
 .. _`validation groups`: https://symfony.com/doc/current/form/validation_groups.html
 .. _morphing library: https://github.com/bigskysoftware/idiomorph
+.. _`Stimulus action parameter`: https://stimulus.hotwired.dev/reference/actions#action-parameters