Asset mapper: Further docs updates

Author: weaverryan

src/Autocomplete/doc/index.rst

@@ -12,20 +12,19 @@ into an Ajax-powered autocomplete smart UI control (leveraging `Tom Select`_):
 Installation
 ------------
 
-Before you start, make sure you have `Symfony UX configured in your app`_.
+Before you start, make sure you have `StimulusBundle configured in your app`_.
 
 Then install the bundle using Composer and Symfony Flex:
 
 .. code-block:: terminal
 
     $ composer require symfony/ux-autocomplete
 
-If you're using WebpackEncore, install your assets and restart Encore. This is
-not needed if you're using AssetMapper:
+If you're using WebpackEncore, install your assets and restart Encore (not
+needed if you're using AssetMapper):
 
 .. code-block:: terminal
 
-    # Don't forget to install the JavaScript dependencies as well and compile
     $ npm install --force
     $ npm run watch
 
@@ -585,7 +584,7 @@ This bundle aims at following the same Backward Compatibility promise as
 the Symfony framework: https://symfony.com/doc/current/contributing/code/bc.html
 
 .. _`Tom Select`: https://tom-select.js.org/
-.. _`Symfony UX configured in your app`: https://symfony.com/doc/current/frontend/ux.html
+.. _StimulusBundle configured in your app: https://symfony.com/bundles/StimulusBundle/current/index.html
 .. _`Tom Select Options`: https://tom-select.js.org/docs/#general-configuration
 .. _`controller.ts`: https://github.com/symfony/ux/blob/2.x/src/Autocomplete/assets/src/controller.ts
 .. _`Tom Select Render Templates`: https://tom-select.js.org/docs/#render-templates

src/Chartjs/doc/index.rst

@@ -8,20 +8,19 @@ It is part of `the Symfony UX initiative`_.
 Installation
 ------------
 
-Before you start, make sure you have `Symfony UX configured in your app`_.
+Before you start, make sure you have `StimulusBundle configured in your app`_.
 
-Then, install this bundle using Composer and Symfony Flex:
+Then install the bundle using Composer and Symfony Flex:
 
 .. code-block:: terminal
 
     $ composer require symfony/ux-chartjs
 
-If you're using WebpackEncore, install your assets and restart Encore. This is
-not needed if you're using AssetMapper:
+If you're using WebpackEncore, install your assets and restart Encore (not
+needed if you're using AssetMapper):
 
 .. code-block:: terminal
 
-    # Don't forget to install the JavaScript dependencies as well and compile
     $ npm install --force
     $ npm run watch
 
@@ -244,7 +243,7 @@ the Symfony framework: https://symfony.com/doc/current/contributing/code/bc.html
 .. _`Chart.js`: https://www.chartjs.org
 .. _`the Symfony UX initiative`: https://symfony.com/ux
 .. _`Chart.js documentation`: https://www.chartjs.org/docs/latest/
-.. _`Symfony UX configured in your app`: https://symfony.com/doc/current/frontend/ux.html
+.. _StimulusBundle configured in your app: https://symfony.com/bundles/StimulusBundle/current/index.html
 .. _`a lot of plugins`: https://github.com/chartjs/awesome#plugins
 .. _`zoom plugin`: https://www.chartjs.org/chartjs-plugin-zoom/latest/
 .. _`zoom plugin documentation`: https://www.chartjs.org/chartjs-plugin-zoom/latest/guide/integration.html

src/Cropperjs/doc/index.rst

@@ -8,20 +8,19 @@ Symfony UX Cropper.js is a Symfony bundle integrating the
 Installation
 ------------
 
-Before you start, make sure you have `Symfony UX configured in your app`_.
+Before you start, make sure you have `StimulusBundle configured in your app`_.
 
 Then, install this bundle using Composer and Symfony Flex:
 
 .. code-block:: terminal
 
     $ composer require symfony/ux-cropperjs
 
-If you're using WebpackEncore, install your assets and restart Encore. This is
-not needed if you're using AssetMapper:
+If you're using WebpackEncore, install your assets and restart Encore (not
+needed if you're using AssetMapper):
 
 .. code-block:: terminal
 
-    # Don't forget to install the JavaScript dependencies as well and compile
     $ npm install --force
     $ npm run watch
 
@@ -151,4 +150,4 @@ https://symfony.com/doc/current/contributing/code/bc.html
 .. _`Cropper.js`: https://fengyuanchen.github.io/cropperjs/
 .. _`the Symfony UX initiative`: https://symfony.com/ux
 .. _`the Cropper.js options`: https://github.com/fengyuanchen/cropperjs/blob/main/README.md#options
-.. _`Symfony UX configured in your app`: https://symfony.com/doc/current/frontend/ux.html
+.. _StimulusBundle configured in your app: https://symfony.com/bundles/StimulusBundle/current/index.html

src/Dropzone/doc/index.rst

@@ -10,20 +10,19 @@ having to browse their computer for a file.
 Installation
 ------------
 
-Before you start, make sure you have `Symfony UX configured in your app`_.
+Before you start, make sure you have `StimulusBundle configured in your app`_.
 
 Then, install this bundle using Composer and Symfony Flex:
 
 .. code-block:: terminal
 
     $ composer require symfony/ux-dropzone
 
-If you're using WebpackEncore, install your assets and restart Encore. This is
-not needed if you're using AssetMapper:
+If you're using WebpackEncore, install your assets and restart Encore (not
+needed if you're using AssetMapper):
 
 .. code-block:: terminal
 
-    # Don't forget to install the JavaScript dependencies as well and compile
     $ npm install --force
     $ npm run watch
 
@@ -157,4 +156,4 @@ the Symfony framework:
 https://symfony.com/doc/current/contributing/code/bc.html
 
 .. _`the Symfony UX initiative`: https://symfony.com/ux
-.. _`Symfony UX configured in your app`: https://symfony.com/doc/current/frontend/ux.html
+.. _StimulusBundle configured in your app: https://symfony.com/bundles/StimulusBundle/current/index.html

src/LazyImage/doc/index.rst

@@ -12,20 +12,19 @@ It provides two key features:
 Installation
 ------------
 
-Before you start, make sure you have `Symfony UX configured in your app`_.
+Before you start, make sure you have `StimulusBundle configured in your app`_.
 
 Then install this bundle using Composer and Symfony Flex:
 
 .. code-block:: terminal
 
     $ composer require symfony/ux-lazy-image
 
-If you're using WebpackEncore, install your assets and restart Encore. This is
-not needed if you're using AssetMapper:
+If you're using WebpackEncore, install your assets and restart Encore (not
+needed if you're using AssetMapper):
 
 .. code-block:: terminal
 
-    # Don't forget to install the JavaScript dependencies as well and compile
     $ npm install --force
     $ npm run watch
 
@@ -174,4 +173,4 @@ https://symfony.com/doc/current/contributing/code/bc.html
 .. _`the Symfony UX initiative`: https://symfony.com/ux
 .. _`BlurHash implementation`: https://blurha.sh
 .. _`StimulusBundle`: https://symfony.com/bundles/StimulusBundle/current/index.html
-.. _`Symfony UX configured in your app`: https://symfony.com/doc/current/frontend/ux.html
+.. _StimulusBundle configured in your app: https://symfony.com/bundles/StimulusBundle/current/index.html

src/LiveComponent/doc/index.rst

@@ -4,11 +4,14 @@ Live Components
 **EXPERIMENTAL** This component is currently experimental and is likely
 to change, or even change drastically.
 
-Live components work with the `TwigComponent`_ library
+Live components builds on top of the `TwigComponent`_ library
 to give you the power to automatically update your Twig components on
 the frontend as the user interacts with them. Inspired by
 `Livewire`_ and `Phoenix LiveView`_.
 
+If you're not familiar with Twig components yet, it's worth taking a few minutes
+to familiarize yourself in the `TwigComponent documentation`_.
+
 A real-time product search component might look like this::
 
     // src/Components/ProductSearch.php
@@ -55,16 +58,6 @@ A real-time product search component might look like this::
         </ul>
     </div>
 
-.. versionadded:: 2.1
-
-    The ability to reference local variables in the template (e.g. ``query``) was added in TwigComponents 2.1.
-    Previously, all data needed to be referenced through ``this`` (e.g. ``this.query``).
-
-.. versionadded:: 2.1
-
-    The ability to initialize live component with the ``attributes`` twig variable was added in LiveComponents
-    2.1. Previously, the ``init_live_component()`` function was required (this function was removed in 2.1).
-
 Done! Now render it wherever you want:
 
 .. code-block:: twig
@@ -79,20 +72,19 @@ Want some demos? Check out https://ux.symfony.com/live-component#demo
 Installation
 ------------
 
-Before you start, make sure you have `Symfony UX configured in your app`_.
+Before you start, make sure you have `StimulusBundle configured in your app`_.
 
 Now install the library with:
 
 .. code-block:: terminal
 
     $ composer require symfony/ux-live-component
 
-If you're using WebpackEncore, install your assets and restart Encore. This is
-not needed if you're using AssetMapper:
+If you're using WebpackEncore, install your assets and restart Encore (not
+needed if you're using AssetMapper):
 
 .. code-block:: terminal
 
-    # Don't forget to install the JavaScript dependencies as well and compile
     $ npm install --force
     $ npm run watch
 
@@ -411,7 +403,8 @@ In this case, the model (e.g. ``publishAt``) will probably *not*
 update correctly because JavaScript doesn't trigger the normal
 ``change`` event. To fix this, you'll need to "hook" into the
 JavaScript library and set the model directly (or trigger a
-``change`` event on the ``data-model`` field). See :ref:`working-in-javascript`.
+``change`` event on the ``data-model`` field). See
+:ref:`manually trigger an element change <javascript-manual-element-change>`.
 
 .. _hydration:
 
@@ -789,6 +782,8 @@ initialized:
     const component = document.getElementById('id-of-your-element').__component;
     component.mode = 'editing';
 
+.. _javascript-manual-element-change:
+
 Finally, you can also set the value of a model field directly. However,
 be sure to *also* trigger a ``change`` event so that live components is notified
 of the change:
@@ -2949,14 +2944,15 @@ However it is currently considered `experimental`_, meaning it is not
 bound to Symfony's BC policy for the moment.
 
 .. _`TwigComponent`: https://symfony.com/bundles/ux-twig-component/current/index.html
+.. _TwigComponent documentation: https://symfony.com/bundles/ux-twig-component/current/index.html
 .. _`Livewire`: https://laravel-livewire.com
 .. _`Phoenix LiveView`: https://hexdocs.pm/phoenix_live_view/Phoenix.LiveView.html
 .. _`Twig Component`: https://symfony.com/bundles/ux-twig-component/current/index.html
 .. _`Twig Component mount documentation`: https://symfony.com/bundles/ux-twig-component/current/index.html#the-mount-method
 .. _`Symfony form`: https://symfony.com/doc/current/forms.html
 .. _`experimental`: https://symfony.com/doc/current/contributing/code/experimental.html
 .. _`dependent form fields`: https://ux.symfony.com/live-component/demos/dependent-form-fields
-.. _`Symfony UX configured in your app`: https://symfony.com/doc/current/frontend/ux.html
+.. _StimulusBundle configured in your app: https://symfony.com/bundles/StimulusBundle/current/index.html
 .. _`localizes its URLs`: https://symfony.com/doc/current/translation/locale.html#translation-locale-url
 .. _`attributes variable`: https://symfony.com/bundles/ux-twig-component/current/index.html#component-attributes
 .. _`CollectionType`: https://symfony.com/doc/current/form/form_collections.html

src/Notify/doc/index.rst

@@ -7,20 +7,19 @@ in Symfony applications using `Mercure`_. It is part of `the Symfony UX initiati
 Installation
 ------------
 
-Before you start, make sure you have `Symfony UX configured in your app`_.
+Before you start, make sure you have `StimulusBundle configured in your app`_.
 
 Then, install this bundle using Composer and Symfony Flex:
 
 .. code-block:: terminal
 
     $ composer require symfony/ux-notify
 
-If you're using WebpackEncore, install your assets and restart Encore. This is
-not needed if you're using AssetMapper:
+If you're using WebpackEncore, install your assets and restart Encore (not
+needed if you're using AssetMapper):
 
 .. code-block:: terminal
 
-    # Don't forget to install the JavaScript dependencies as well and compile
     $ npm install --force
     $ npm run watch
 
@@ -153,7 +152,7 @@ the Symfony framework:
 https://symfony.com/doc/current/contributing/code/bc.html
 
 .. _`the Symfony UX initiative`: https://symfony.com/ux
-.. _`Symfony UX configured in your app`: https://symfony.com/doc/current/frontend/ux.html
+.. _StimulusBundle configured in your app: https://symfony.com/bundles/StimulusBundle/current/index.html
 .. _`Mercure`: https://mercure.rocks
 .. _`running Mercure server`: https://symfony.com/doc/current/mercure.html#running-a-mercure-hub
 .. _`native notifications`: https://developer.mozilla.org/en-US/docs/Web/API/Notifications_API/Using_the_Notifications_API

src/React/doc/index.rst

@@ -13,7 +13,12 @@ Symfony UX React supports React 18+.
 Installation
 ------------
 
-Before you start, make sure you have `Symfony UX configured in your app`_.
+.. note::
+
+    This package works best with WebpackEncore. To use it with AssetMapper, see
+    :ref:`Using with AssetMapper <using-with-asset-mapper>`.
+
+Before you start, make sure you have `StimulusBundle configured in your app`_.
 Then install the bundle using Composer and Symfony Flex:
 
 .. code-block:: terminal
@@ -40,7 +45,6 @@ Install a package to help React:
     $ npm run watch
 
     # or use yarn
-    
     $ yarn add @babel/preset-react --dev --force
     $ yarn watch
 
@@ -98,11 +102,40 @@ For example:
         <div {{ react_component('MyComponent', { 'fullName': number }) }}>
             Loading... <i class="fas fa-cog fa-spin fa-3x"></i>
         </div>
-        
+
         {# Component living in a subdirectory: "assets/react/controllers/Admin/OtherComponent" #}
         <div {{ react_component('Admin/OtherComponent') }}></div>
     {% endblock %}
 
+.. _using-with-asset-mapper:
+
+Using with AssetMapper
+----------------------
+
+Because the JSX format isn't pure JavaScript, using this library with AssetMapper
+requires some extra steps.
+
+#. Compile your ``.jsx`` files to pure JavaScript files. This can be done by
+   installing Babel and the ``@babel/preset-react`` preset. Example:
+   https://github.com/symfony/ux/blob/2.x/ux.symfony.com/package.json
+
+#. Point this library at the "built" controllers directory that contains the final
+   JavaScript files:
+
+.. code-block:: yaml
+
+    # config/packages/react.yaml
+    react:
+        controllers_path: '%kernel.project_dir%/assets/build/react/controllers'
+
+Also, inside of your ``.jsx`` files, when importing another component, use the
+``.js`` extension:
+
+.. code-block:: javascript
+
+    // use PackageList.js even though the file is named PackageList.jsx
+    import PackageList from '../components/PackageList.js';
+
 Backward Compatibility promise
 ------------------------------
 
@@ -112,4 +145,4 @@ https://symfony.com/doc/current/contributing/code/bc.html
 
 .. _`React`: https://reactjs.org/
 .. _`the Symfony UX initiative`: https://symfony.com/ux
-.. _`Symfony UX configured in your app`: https://symfony.com/doc/current/frontend/ux.html
+.. _StimulusBundle configured in your app: https://symfony.com/bundles/StimulusBundle/current/index.html