Merge pull request #14 from WTW-IM/react-17

React 17 Implementation

Author: stevematney

CHANGELOG.md

@@ -1,3 +1,46 @@
+# [3.0.0-react-17.3](https://github.com/WTW-IM/react-html-element/compare/v3.0.0-react-17.2...v3.0.0-react-17.3) (2021-02-05)
+
+
+### Docs
+
+* completing React 17 docs ([1d48bc0](https://github.com/WTW-IM/react-html-element/commit/1d48bc0e31df2fa50de84fd930779c6c69cb8006))
+* fixing react-16 link ([43435a4](https://github.com/WTW-IM/react-html-element/commit/43435a4ccc425433afabaefd577aff633e0accff))
+
+# [3.0.0-react-17.2](https://github.com/WTW-IM/react-html-element/compare/v3.0.0-react-17.1...v3.0.0-react-17.2) (2021-02-04)
+
+
+### Docs
+
+* describing why this is useful with React 17 ([c12ca21](https://github.com/WTW-IM/react-html-element/commit/c12ca21c9d0cff0c8636593d15889c641034205a))
+
+### Fix
+
+* ensuring we only load the HTML 5 Adapter when we need it ([871755f](https://github.com/WTW-IM/react-html-element/commit/871755fc4b78fc557e77bf3b7bd6048480b3a34d))
+
+# [3.0.0-react-17.1](https://github.com/WTW-IM/react-html-element/compare/v2.2.0...v3.0.0-react-17.1) (2021-02-04)
+
+
+### Breaking
+
+* removing event retargeting ([60abc05](https://github.com/WTW-IM/react-html-element/commit/60abc05ffed68591840c7651d0c3a49668c4d040))
+
+### Build
+
+* ensuring we push package.json with semantic-release commit ([f0531bc](https://github.com/WTW-IM/react-html-element/commit/f0531bca4998708fe7e37117e28a4e5ab213cf8c))
+* reconfiguring .travis.yml to use on conditions ([f587a7c](https://github.com/WTW-IM/react-html-element/commit/f587a7cc127ed61413c74cbcfc9f26bc7b015755))
+* running release build on react-16 and react-17 branches ([4abdde9](https://github.com/WTW-IM/react-html-element/commit/4abdde98d68464bd32b0f52acebee9701dde6815))
+* setting up release for react-17 ([9d9d4ad](https://github.com/WTW-IM/react-html-element/commit/9d9d4add5f77e7b6089195a357893abc1764a6fe))
+
+### Update
+
+* adding a base-level render function ([9cb8a6b](https://github.com/WTW-IM/react-html-element/commit/9cb8a6b5a5a66eafa827dfebe2e83577f7a70b68))
+* adding this.shadow for easy style placement ([1a5c275](https://github.com/WTW-IM/react-html-element/commit/1a5c2758acaf3850d67852efe61fa95899f00259))
+* ensuring we can accommodate lower versions of React 17 ([2cac97b](https://github.com/WTW-IM/react-html-element/commit/2cac97b4eea0305b018f87f65eca049d79520878))
+
+### Upgrade
+
+* updating all dependencies ([5737167](https://github.com/WTW-IM/react-html-element/commit/5737167f47ffb4b3e99fc7f15e4bd1f987663eb7))
+
 # [2.2.0](https://github.com/WTW-IM/react-html-element/compare/v2.1.0...v2.2.0) (2021-01-12)
 
 

README.md

@@ -3,13 +3,16 @@
 [![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](https://github.com/WTW-IM/react-html-element/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 using React
+in Web Components [as described in the React documentation](https://reactjs.org/docs/web-components.html).
+Read on to find out what you can get by using it!
 
 ## Installation
 
@@ -31,7 +34,7 @@ function Incrementer(): React.ReactElement {
       <button
         id="iterate-button"
         type="button"
-        onClick={(): void => setIncrement(prevIncrement => prevIncrement + 1)}
+        onClick={(): void => setIncrement((prevIncrement) => prevIncrement + 1)}
       >
         Increment
       </button>
@@ -50,27 +53,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).
@@ -94,9 +92,7 @@ This will allow us to utilize our Web Component as an element in any HTML:
     <script src="./path/to/incrementer.js"></script>
   </head>
   <body>
-    <h1>
-      Behold: An Incrementer
-    </h1>
+    <h1>Behold: An Incrementer</h1>
     <!-- put your web component in your html -->
     <incrementer></incrementer>
   </body>
@@ -114,7 +110,7 @@ import ReactHTMLElement from 'react-html-element';
 
 class IncrementerComponent extends ReactHTMLElement {
   connectedCallback(): void {
-    ReactDOM.render(<Incrementer />, this.mountPoint);
+    this.render(<Incrementer />);
   }
 
   constructor(): void {
@@ -134,21 +130,27 @@ customElements.define('incrementer', ReactTestComponent);
 
 Using styled-components with ReactHTMLElement seems tricky, but there's actually a very simple way to implement it: the [`StyleSheetManager`](https://styled-components.com/docs/api#stylesheetmanager). An app rendered with `StyleSheetManager` might look like this:
 
-```react
+```jsx
 class ReactWebComponent extends ReactHTMLElement {
   connectedCallback() {
-    ReactDOM.render((
-      <StyleSheetManager target={this.mountPoint.parentNode}>
+    this.render(
+      <StyleSheetManager target={this.shadow}>
         <App />
       </StyleSheetManager>
-    ), this.mountPoint);
+    );
   }
 }
 ```
 
-We use `this.mountPoint.parentNode` for the styles instead of simply using `this.mountPoint` for the case 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 `parentNode` will cause the styles to be placed within the Shadow DOM, but not inside the same component where our app is mounted.
+`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. `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.
 
-If you're using a [custom template](#thismountpoint-and-using-custom-templates), you can find a node for your `StyleSheetManager` target by searching through the `shadowRoot` in the same way you might search through `document.body`. Often, simply using `this.mountPoint.parentNode` will still work as expected, even with custom templates.
+If you're using a [custom template](#thismountpoint-and-using-custom-templates), you may need to set the target for your `StyleSheetManager` differently. Often, simply using `this.mountPoint.parentNode` will work as expected, even with custom templates, but this will depend on your template. (You may run into competing styles or have a very unusual use-case where placing a `style` tag as a sibling of your application causes some other issue.)
 
 # Contributing