Docs: describing why this is useful with React 17

stevematney · stevematney · commit c12ca21c9d0c · 2021-02-03T22:39:22.000-07:00
diff --git a/README.md b/README.md
@@ -3,13 +3,14 @@
 [![Build Status](https://travis-ci.com/WTW-IM/react-html-element.svg?branch=master)](https://travis-ci.com/github/WTW-IM/react-html-element)
 [![npm version](https://badge.fury.io/js/react-html-element.svg)](https://badge.fury.io/js/react-html-element)
 
-## The Problem
+## NOTE:
 
-The [React documentation around using React in Web Components](https://reactjs.org/docs/web-components.html#using-react-in-your-web-components) presents a case where you can create Web Components using React, but when explored, utilizing React in Web Components presents some significant functionality issues, as detailed in [this issue](https://github.com/facebook/react/issues/9242). Namely, complex React apps rendered in Web Components lose their functionality.
+This package works with React at version 17. For version 16, [see the react-16
+branch of this repo](tree/react-16).
 
-## The Solution
+## What is it?
 
-`react-html-element` seamlessly creates the glue needed to utilize React in your Web Components without losing functionality.
+`react-html-element` gives a few quality of life improvements over simply
 
 ## Installation
 
@@ -50,28 +51,22 @@ import ReactHTMLElement from 'react-html-element';
 
 class IncrementerComponent extends ReactHTMLElement {
   connectedCallback(): void {
-    ReactDOM.render(<Incrementer />, this.mountPoint);
+    this.render(<Incrementer />);
   }
 }
 
 customElements.define('incrementer', ReactTestComponent);
 ```
 
-The key pieces of code are `... extends ReactHTMLElement` and `this.mountPoint`.
+The key pieces of code are `... extends ReactHTMLElement` and `this.render`,
+which mounts our app to its designated `mountPoint`, [as described below](#thismountpoint-and-using-custom-templates).
 
 > ### Polyfills
 >
-> One thing to remember is that you will need to load [the webcomponentsjs polyfills](https://www.webcomponents.org/polyfills) for `ReactHTMLElement` to work in all browsers. Be sure to include [the ES5 adapter](https://github.com/webcomponents/polyfills/tree/master/packages/webcomponentsjs#custom-elements-es5-adapterjs), as we currently transpile `ReactHTMLElement` down to ES5. The polyfills should be in the `<head>`, and should look something like this:
+> One thing to remember is that you will need to load [the webcomponentsjs polyfills](https://www.webcomponents.org/polyfills) for `ReactHTMLElement` to work in all browsers.
 >
 > ```html
 > <script src="https://cdnjs.cloudflare.com/ajax/libs/webcomponentsjs/2.4.3/webcomponents-bundle.js"></script>
-> <script>
->   if (!window.customElements) {
->     document.write('<!--');
->   }
-> </script>
-> <script src="https://cdnjs.cloudflare.com/ajax/libs/webcomponentsjs/2.4.3/custom-elements-es5-adapter.js"></script>
-> <!--- We use the closing bracket of this comment to close off the above opening comment, if it gets written -->
 > ```
 >
 > There are many ways to implement these polyfills, and you can explore them in the [webpcomponentsjs README](https://github.com/webcomponents/polyfills/tree/master/packages/webcomponentsjs#how-to-use).
@@ -113,7 +108,7 @@ import ReactHTMLElement from 'react-html-element';
 
 class IncrementerComponent extends ReactHTMLElement {
   connectedCallback(): void {
-    ReactDOM.render(<Incrementer />, this.mountPoint);
+    this.render(<Incrementer />);
   }
 
   constructor(): void {
@@ -136,11 +131,10 @@ Using styled-components with ReactHTMLElement seems tricky, but there's actually
 ```jsx
 class ReactWebComponent extends ReactHTMLElement {
   connectedCallback() {
-    ReactDOM.render(
+    this.render(
       <StyleSheetManager target={this.shadow}>
         <App />
-      </StyleSheetManager>,
-      this.mountPoint
+      </StyleSheetManager>
     );
   }
 }
@@ -149,7 +143,8 @@ class ReactWebComponent extends ReactHTMLElement {
 `this.shadow` is a getter that will initialize your Web Component, attaching a Shadow
 Root with `{mode: 'open'}`, and setting the Shadow Root's innerHTML to your
 template or `<div></div>`. If this initialization has already occurred, it will
-simply return the previously created Shadow Root.
+simply return the previously created Shadow Root. `this.mountPoint` utilizes
+`this.shadow` as part of its work to generate the Shadow Root.
 
 We use `this.shadow` for the styles instead of simply using `this.mountPoint` because of unmounting. If stylesheets are a child of `this.mountPoint`, ReactDOM will throw an error when you try to unmount. (`unmountComponentAtNode(): The node you're attempting to unmount was rendered by another copy of React.`) This error is a little cryptic, but the bottom line is that ReactDOM expects that everything inside the mounted node was generated by React itself. When we use the same node to place our styles, it breaks that expectation. Using the `this.shadow` will cause the styles to be placed as a first-child of the Shadow DOM, but not inside the same component where our app is mounted.
 
