feature #2283 [React] Add permanent option to react_component function (smnandre)

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

Discussion
----------

[React] Add `permanent` option to `react_component` function

| Q             | A
| ------------- | ---
| Bug fix?      | yes
| New feature?  | yes
| Issues        | Fix #...
| License       | MIT

(Issue reported on a work project)

Using Turbo `data-turbo-permanent` creates race conditions that lead to the controller code failing to keep or reload the component.

In the current implementation, the Stimulus controller _unmounts_ the component then tried to _create_ it again.. which cannot be done:

> Once you call root.unmount you cannot call root.render again on the same root. Attempting to call root.render on an unmounted root will throw a “Cannot update an unmounted root” error. However, you can create a new root for the same DOM node after the previous root for that node has been unmounted.

https://react.dev/reference/react-dom/client/createRoot#root-unmount

---

~The proposed implementation uses a short delay before calling unmount. It is "morphing-library-agnostic", and will work with any Turbo-like framework, with no impact on the existing projects using UX React (except a bug fixed 😅 ).~

New implementation:

A new option `permanent` prevent the "unmount" of the component when set to true

```twig
{# This component will not be unmounted on "disconnect" #}

{{ react_component('MyComponent', props, {permanent: true}) }}

```

This allows to avoid the bug when a component is disconnected and immediately reconnected (ex with Turbo)

Commits
-------

4d60724 [React] Add `permanent` option to `react_component` function

Author: kbond

src/React/CHANGELOG.md

@@ -1,5 +1,10 @@
 # CHANGELOG
 
+## 2.21.0
+
+-   Add `permanent` option to the `react_component` Twig function, to prevent the 
+    _unmounting_ when the component is deconnected and immediately re-connected. 
+
 ## 2.13.2
 
 -   Revert "Change JavaScript package to `type: module`"

src/React/assets/dist/render_controller.d.ts

@@ -3,9 +3,14 @@ import { Controller } from '@hotwired/stimulus';
 export default class extends Controller {
     readonly componentValue?: string;
     readonly propsValue?: object;
+    readonly permanentValue: boolean;
     static values: {
         component: StringConstructor;
         props: ObjectConstructor;
+        permanent: {
+            type: BooleanConstructor;
+            default: boolean;
+        };
     };
     connect(): void;
     disconnect(): void;

src/React/assets/dist/render_controller.js

@@ -54,6 +54,9 @@ class default_1 extends Controller {
         });
     }
     disconnect() {
+        if (this.permanentValue) {
+            return;
+        }
         this.element.root.unmount();
         this.dispatchEvent('unmount', {
             component: this.componentValue,
@@ -74,6 +77,7 @@ class default_1 extends Controller {
 default_1.values = {
     component: String,
     props: Object,
+    permanent: { type: Boolean, default: false },
 };
 
 export { default_1 as default };

src/React/assets/src/render_controller.ts

@@ -14,17 +14,17 @@ import { Controller } from '@hotwired/stimulus';
 export default class extends Controller {
     declare readonly componentValue?: string;
     declare readonly propsValue?: object;
+    declare readonly permanentValue: boolean;
 
     static values = {
         component: String,
         props: Object,
+        permanent: { type: Boolean, default: false },
     };
 
     connect() {
         const props = this.propsValue ? this.propsValue : null;
-
         this.dispatchEvent('connect', { component: this.componentValue, props: props });
-
         if (!this.componentValue) {
             throw new Error('No component specified.');
         }
@@ -40,6 +40,12 @@ export default class extends Controller {
     }
 
     disconnect() {
+        if (this.permanentValue) {
+            // Prevent unmounting the component if the controller is permanent
+            // (no render is allowed after unmounting)
+            return;
+        }
+
         (this.element as any).root.unmount();
         this.dispatchEvent('unmount', {
             component: this.componentValue,

src/React/doc/index.rst

@@ -2,12 +2,14 @@ Symfony UX React
 ================
 
 Symfony UX React is a Symfony bundle integrating `React`_ in
-Symfony applications. It is part of `the Symfony UX initiative`_.
+Symfony applications. It is part of the `Symfony UX initiative`_.
 
 React is a JavaScript library for building user interfaces.
 Symfony UX React provides tools to render React components from Twig,
 handling rendering and data transfers.
 
+You can see a live example of this integration on the `Symfony UX React demo`_.
+
 Symfony UX React supports React 18+.
 
 Installation
@@ -41,6 +43,9 @@ React components.
 Usage
 -----
 
+Register components
+~~~~~~~~~~~~~~~~~~~
+
 The Flex recipe will have already added the ``registerReactControllerComponents()``
 code to your ``assets/app.js`` file:
 
@@ -55,7 +60,11 @@ This will load all React components located in the ``assets/react/controllers``
 directory. These are known as **React controller components**: top-level
 components that are meant to be rendered from Twig.
 
-You can render any React controller component in Twig using the ``react_component()``.
+Render in Twig
+~~~~~~~~~~~~~~
+
+You can render any React controller component in your Twig templates, using the
+``react_component()`` function.
 
 For example:
 
@@ -82,6 +91,31 @@ For example:
         <div {{ react_component('Admin/OtherComponent') }}></div>
     {% endblock %}
 
+Permanent components
+~~~~~~~~~~~~~~~~~~~~
+
+.. versionadded:: 2.21
+
+    The ability to mark a component ``permanent`` was added in UX React 2.21.
+
+The controller responsible to render the React components can be configured
+to keep the React component mounted when the root element is removed from 
+the DOM, using the ``permanent`` option.
+
+This is particularly useful when the root element of a component is moved around
+in the DOM  or is removed and immediately re-added to the DOM (e.g. when using 
+`Turbo`_ and its `data-turbo-permanent` attribute).
+
+.. code-block:: html+twig
+
+    {# templates/home.html.twig #}
+    {% extends 'base.html.twig' %}
+    
+    {# The React component will stay mounted if the div is moved in the DOM #}
+    <div {{ react_component('Hello', {fullName: 'Fabien'}, {permanent: true}) }}>
+         Loading...  
+    </div>
+
 .. _using-with-asset-mapper:
 
 Using with AssetMapper
@@ -119,4 +153,6 @@ the Symfony framework:
 https://symfony.com/doc/current/contributing/code/bc.html
 
 .. _`React`: https://reactjs.org/
-.. _`the Symfony UX initiative`: https://ux.symfony.com/
+.. _`Symfony UX initiative`: https://ux.symfony.com/
+.. _`Symfony UX React demo`: https://ux.symfony.com/react
+:: _`Turbo`: https://turbo.hotwire.dev/

src/React/src/Twig/ReactComponentExtension.php

@@ -45,15 +45,24 @@ public function getFunctions(): array
         ];
     }
 
-    public function renderReactComponent(string $componentName, array $props = []): string
+    /**
+     * @param array<string, mixed>    $props
+     * @param array{permanent?: bool} $options
+     */
+    public function renderReactComponent(string $componentName, array $props = [], array $options = []): string
     {
-        $params = ['component' => $componentName];
+        $values = ['component' => $componentName];
         if ($props) {
-            $params['props'] = $props;
+            $values['props'] = $props;
+        }
+        if ($options) {
+            if (\is_bool($permanent = $options['permanent'] ?? null)) {
+                $values['permanent'] = $permanent;
+            }
         }
 
         $stimulusAttributes = $this->stimulusHelper->createStimulusAttributes();
-        $stimulusAttributes->addController('@symfony/ux-react/react', $params);
+        $stimulusAttributes->addController('@symfony/ux-react/react', $values);
 
         return (string) $stimulusAttributes;
     }

src/React/tests/Twig/ReactComponentExtensionTest.php

@@ -9,7 +9,7 @@
  * file that was distributed with this source code.
  */
 
-namespace Symfony\UX\React\Tests;
+namespace Symfony\UX\React\Tests\Twig;
 
 use PHPUnit\Framework\TestCase;
 use Symfony\UX\React\Tests\Kernel\TwigAppKernel;
@@ -41,6 +41,39 @@ public function testRenderComponent()
         );
     }
 
+    /**
+     * @dataProvider provideOptions
+     */
+    public function testRenderComponentWithOptions(array $options, string|false $expected)
+    {
+        $kernel = new TwigAppKernel('test', true);
+        $kernel->boot();
+
+        /** @var ReactComponentExtension $extension */
+        $extension = $kernel->getContainer()->get('test.twig.extension.react');
+
+        $rendered = $extension->renderReactComponent(
+            'SubDir/MyComponent',
+            ['fullName' => 'Titouan Galopin'],
+            $options,
+        );
+
+        $this->assertStringContainsString('data-controller="symfony--ux-react--react" data-symfony--ux-react--react-component-value="SubDir/MyComponent" data-symfony--ux-react--react-props-value="{"fullName":"Titouan Galopin"}"', $rendered);
+        if (false === $expected) {
+            $this->assertStringNotContainsString('data-symfony--ux-react--react-permanent-value', $rendered);
+        } else {
+            $this->assertStringContainsString($expected, $rendered);
+        }
+    }
+
+    public static function provideOptions(): iterable
+    {
+        yield 'permanent' => [['permanent' => true], 'data-symfony--ux-react--react-permanent-value="true"'];
+        yield 'not permanent' => [['permanent' => false], 'data-symfony--ux-react--react-permanent-value="false"'];
+        yield 'permanent not bool' => [['permanent' => 12345], false];
+        yield 'no permanent' => [[], false];
+    }
+
     public function testRenderComponentWithoutProps()
     {
         $kernel = new TwigAppKernel('test', true);