minor #930 Asset mapper: Further docs updates (weaverryan)

This PR was squashed before being merged into the 2.x branch.

Discussion
----------

Asset mapper: Further docs updates

| Q             | A
| ------------- | ---
| Bug fix?      | no
| New feature?  | no
| Tickets       | None
| License       | MIT

Further updates for smooth documentation now that the AssetMapper component exists. The biggest change is that the docs for installing UX (which really just means installing StimulusBundle at this point) have moved into that bundle.

Cheers!

Commits
-------

62b8c76 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