feat: add documentation for Flow in React (vaadin#3488)

* feat: add documentation for Flow in React

Add documentation on using Flow
components inside a React component.

* Minor changes to wording

* First pass at editing document touched.

* Second pass at editing document touched.

* Update source type

Co-authored-by: Jouni Koivuviita <[email protected]>

* Apply suggestions from code review

Co-authored-by: Jouni Koivuviita <[email protected]>

---------

Co-authored-by: Zhe Sun <[email protected]>
Co-authored-by: Russell J.T. Dyer <[email protected]>
Co-authored-by: Jouni Koivuviita <[email protected]>

Author: 4 people

articles/flow/integrations/react.adoc

@@ -6,7 +6,7 @@ order: 20
 
 = [since:com.vaadin:[email protected]]#Using React Components in Flow#
 
-https://reactjs.org/[React] is a popular JS-based frontend UI library with a wide adoption and many components. This documentation page explains how to integrate existing React components with Flow by using an intermediate adapter Web Component, and then using it in Java applications.
+https://reactjs.org/[React] is a popular JS-based frontend UI library with many components and a wide adoption. This documentation page explains how to integrate existing React components with Flow by using an intermediate adapter Web Component, and then using it in Java applications.
 
 This integration involves two parts: creating a Java class for the server-side adapter component; and a client-side adapter counterpart with TypeScript and React. For examples here, the https://omgovich.github.io/react-colorful/[React Colorful] color picker component is used.
 
@@ -20,12 +20,12 @@ For the server-side part of the integration, create a Java class that extends fr
 ----
 include::../../../src/main/java/com/vaadin/demo/flow/integration/react/RgbaColorPicker.java[tags=annotations]
 ----
-<1> Since this will integrate a third-party React component, the [annotationname]`@NpmPackage` annotation is added to get it installed from npm.
+<1> Since this will integrate a third-party React component, the [annotationname]`@NpmPackage` annotation is added to have it installed from npm.
 <2> The [annotationname]`@Tag` annotation defines the DOM element name of the adapter Web Component (see below).
 <3> The client-side part of the integration (i.e., the adapter Web Component) is yet to be defined and implemented in TypeScript. Therefore, you'll need a separate file for it. Although this file will be created later, the [annotationname]`@JsModule` annotation is added here to import it.
 
 
-=== Java and React States Synchronized
+=== Java & React States Synchronized
 
 The Web Component adapter allows the state to be sent from Java to React and back by using named properties and events in the intermediate Web Component. On the server side, the `ReactAdapterComponent` class provides the following APIs for synchronizing the state with the adapter Web Component:
 
@@ -105,7 +105,7 @@ include::{root}/frontend/demo/flow/integration/react/rgba-color-picker.tsx[tags=
 The `RenderHooks` render callback argument provides the following methods:
 
 - [methodname]`useState<T>(string)` method defines and uses a named state JS property of the adapter Web Component; and
-- [methodname]`useCustomEvent<T | undefined>(string, CustomEventInit<T>)` method returns a simple to use callback that dispatches a Custom Event with the given name on the adapter Web Component:
+- [methodname]`useCustomEvent<T | undefined>(string, CustomEventInit<T>)` method returns a simple-to-use callback that dispatches a Custom Event with the given name on the adapter Web Component:
 
 .Firing a CustomEvent
 [source,jsx]
@@ -146,3 +146,65 @@ public void addPersonDataUpdateListener() {
     }).addEventData("event.detail");
 }
 ----
+
+
+== Adding Flow Components to React Component
+
+It's possible to put Flow [classname]`Component` elements inside a React component implemented with [classname]`ReactAdapterElement`.
+
+You could generate a simple [classname]`RouterLayout` in React that has a navigation menu and the Flow route content on the right side. See <<../routing/layout#, RouterLayout Interface>> for more information.
+
+Create a [classname]`ReactAdapterComponent` that implements the [interfacename]`RouterLayout` interface so that the showRouterLayoutContent is appended into the content element from [methodname]`getContentElement(String)`.
+
+[classname]`RouterLinks` are added to a Div that's bound to the `menu` content element on the client.
+
+.Server Router Layout
+[source,java]
+----
+@JsModule("./ReactRouterLayout.tsx")
+@Tag("react-router-layout")
+public class ReactRouterLayout extends ReactAdapterComponent implements RouterLayout {
+
+    public ReactRouterLayout() {
+        Div links = new Div(
+                new RouterLink("Main view", MainView.class),
+                new Div(),
+                new RouterLink("Information", InfoView.class)
+        );
+        links.getStyle().setMargin("10px");
+        getContentElement("menu").appendChild(links.getElement());
+    }
+
+    @Override
+    public void showRouterLayoutContent(HasElement content) {
+        if (content != null) {
+            // Bind the flow element to the 'flowContent' element on the client
+            getContentElement("flowContent")
+                    .appendChild(Objects.requireNonNull(content.getElement()));
+        }
+    }
+}
+
+----
+
+On the client, there are two places for Flow components to bind: one for `menu` and one for `flowContent`, using the [methodname]`userContent(string)`.
+
+.Client Router Layout
+[source,jsx]
+----
+class ReactRouterLayoutElement extends ReactAdapterElement {
+    protected render(hooks: RenderHooks): React.ReactElement | null {
+        // create content element for name attribute 'menu'
+        const menu = hooks.useContent('menu');
+        // create content element for name attribute 'flowContent'
+        const content = hooks.useContent('flowContent');
+
+        return §div style={{display: 'flex', flex: 1, flexDirection: 'row', height: '100%'}}>
+            <div style={{flex: 1}}>{menu}</div>
+            <div style={{flex: 5}}>{content}</div>
+        </div>;
+    }
+}
+
+customElements.define('react-router-layout', ReactRouterLayoutElement);
+----