Render ng-templates using a ReactTemplate (React) component

Tracks changes via an `NgZone`

Author: Ben Grynhaus

libs/core/src/lib/components/wrapper-component.ts

@@ -192,8 +192,12 @@ export abstract class ReactWrapperComponent<TProps extends {}> implements AfterV
       return undefined;
     }
 
+    if (!this._ngZone) {
+      throw new Error('To create an input JSX renderer you must pass an NgZone to the constructor.');
+    }
+
     if (input instanceof TemplateRef) {
-      const templateRenderer = createTemplateRenderer(input, additionalProps);
+      const templateRenderer = createTemplateRenderer(input, this._ngZone, additionalProps);
       return (context: TContext) => templateRenderer.render(context);
     }
 

libs/core/src/lib/renderer/react-content.ts

@@ -23,8 +23,7 @@ export interface ReactContentProps {
 /**
  * Creates a new `ReactContent` element.
  * @param children The children to append to the `ReactContent` element.
- * @param additionalProps _Optional_. @see `ReactContentProps`
- * @returns
+ * @param additionalProps _Optional_. @see `ReactContentProps`.
  */
 export function createReactContentElement(children: ReadonlyArray<HTMLElement>, additionalProps?: ReactContentProps) {
   return React.createElement(ReactContent, {
@@ -36,12 +35,12 @@ export function createReactContentElement(children: ReadonlyArray<HTMLElement>,
 /**
  * @internal
  */
-export interface InternalReactContentProps extends ReactContentProps {
+interface InternalReactContentProps extends ReactContentProps {
   readonly [CHILDREN_TO_APPEND_PROP]: ReadonlyArray<HTMLElement>;
 }
 
 /**
- * Render any `HTMLElement`s (including Angular components) as a child of React components.
+ * Render any `HTMLElement`s as a child of React components.
  * Supports two rendering modes:
  *  1. `legacy` - append `<react-content>` as the root, and nest the `children-to-append` underneath it.
  *  2. `new` (**default**) - append the `children-to-append` to the parent of this component, and hide the `<react-content>` element.

libs/core/src/lib/renderer/react-template.ts

@@ -0,0 +1,100 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+import { EmbeddedViewRef, NgZone, TemplateRef } from '@angular/core';
+import * as React from 'react';
+import * as ReactDOM from 'react-dom';
+import { Subscription } from 'rxjs';
+
+const DEBUG = false;
+
+/**
+ * @internal
+ */
+export interface ReactTemplateProps {
+  /**
+   * Experimental rendering mode.
+   * Uses a similar approach to `router-outlet`, where the child elements are added to the parent, instead of this node, and this is hidden.
+   * @default false
+   */
+  legacyRenderMode?: boolean;
+}
+
+/**
+ * Creates a new `ReactTemplate` element.
+ * @param templateRef The template to render.
+ * @param context The context to inject the template.
+ * @param ngZone A zone used for tracking changes in the template.
+ * @param additionalProps _Optional_. @see `ReactTemplateProps`.
+ */
+export function createReactTemplateElement<TContext extends object | void>(
+  templateRef: TemplateRef<TContext>,
+  context: TContext,
+  ngZone: NgZone,
+  additionalProps?: ReactTemplateProps
+) {
+  return React.createElement(ReactTemplate, { ngZone, templateRef, context, ...additionalProps });
+}
+
+/**
+ * @internal
+ */
+interface InternalReactTemplateProps<TContext extends object | void> extends ReactTemplateProps {
+  ngZone: NgZone;
+  templateRef: TemplateRef<TContext>;
+  context: TContext;
+}
+
+/**
+ * Render an `ng-template` as a child of a React component.
+ * Supports two rendering modes:
+ *  1. `legacy` - append `<react-content>` as the root, and nest the `children-to-append` underneath it.
+ *  2. `new` (**default**) - append the `children-to-append` to the parent of this component, and hide the `<react-content>` element.
+ *     (similar to how `router-outlet` behaves in Angular).
+ */
+export class ReactTemplate<TContext extends object | void> extends React.Component<
+  InternalReactTemplateProps<TContext>
+> {
+  private _embeddedViewRef: EmbeddedViewRef<TContext>;
+  private _ngZoneSubscription: Subscription;
+
+  componentDidUpdate() {
+    // Context has changes, trigger change detection after pushing the new context in
+    Object.assign(this._embeddedViewRef.context, this.props.context);
+    this._embeddedViewRef.detectChanges();
+  }
+
+  componentDidMount() {
+    const { context, ngZone, templateRef } = this.props;
+
+    this._embeddedViewRef = templateRef.createEmbeddedView(context);
+    const element = ReactDOM.findDOMNode(this);
+    if (DEBUG) {
+      console.warn('ReactTemplate Component > componentDidMount > childrenToAppend:', {
+        rootNodes: this._embeddedViewRef.rootNodes,
+      });
+    }
+
+    const hostElement = this.props.legacyRenderMode ? element : element.parentElement;
+
+    this._embeddedViewRef.rootNodes.forEach(child => hostElement.appendChild(child));
+
+    // Detect the first cycle's changes, and then subscribe for subsequent ones
+    this._embeddedViewRef.detectChanges();
+    this._ngZoneSubscription = ngZone.onUnstable.subscribe(() => {
+      this._embeddedViewRef.detectChanges();
+    });
+  }
+
+  componentWillUnmount() {
+    this._ngZoneSubscription.unsubscribe();
+
+    if (this._embeddedViewRef) {
+      this._embeddedViewRef.destroy();
+    }
+  }
+
+  render() {
+    return React.createElement('react-template', !this.props.legacyRenderMode && { style: { display: 'none' } });
+  }
+}

libs/core/src/lib/renderer/renderprop-helpers.ts

@@ -1,8 +1,9 @@
 // Copyright (c) Microsoft Corporation. All rights reserved.
 // Licensed under the MIT License.
 
-import { ComponentRef, EmbeddedViewRef, TemplateRef } from '@angular/core';
+import { ComponentRef, NgZone, TemplateRef } from '@angular/core';
 import { createReactContentElement, ReactContentProps } from '../renderer/react-content';
+import { createReactTemplateElement } from './react-template';
 
 export interface RenderPropContext<TContext extends object> {
   readonly render: (context: TContext) => JSX.Element;
@@ -16,28 +17,16 @@ function renderReactContent(rootNodes: HTMLElement[], additionalProps?: ReactCon
  * Wrap a `TemplateRef` with a `JSX.Element`.
  *
  * @param templateRef The template to wrap
+ * @param ngZone A zone used for tracking & triggering updates to the template
  * @param additionalProps optional additional props to pass to the `ReactContent` object that will render the content.
  */
 export function createTemplateRenderer<TContext extends object>(
   templateRef: TemplateRef<TContext>,
+  ngZone: NgZone,
   additionalProps?: ReactContentProps
 ): RenderPropContext<TContext> {
-  let viewRef: EmbeddedViewRef<TContext> | null = null;
-  let renderedJsx: JSX.Element | null = null;
-
   return {
-    render: (context: TContext) => {
-      if (!viewRef) {
-        viewRef = templateRef.createEmbeddedView(context);
-        renderedJsx = renderReactContent(viewRef.rootNodes, additionalProps);
-      } else {
-        // Mutate the template's context
-        Object.assign(viewRef.context, context);
-      }
-      viewRef.detectChanges();
-
-      return renderedJsx;
-    },
+    render: (context: TContext) => createReactTemplateElement(templateRef, context, ngZone, additionalProps),
   };
 }
 

libs/core/src/public-api.ts

@@ -6,5 +6,6 @@ export * from './lib/components/wrapper-component';
 export * from './lib/declarations/public-api';
 export * from './lib/renderer/components/Disguise';
 export { getPassProps, passProp, PassProp } from './lib/renderer/pass-prop-decorator';
-export { ReactContent } from './lib/renderer/react-content';
+export { createReactContentElement, ReactContent, ReactContentProps } from './lib/renderer/react-content';
+export * from './lib/renderer/react-template';
 export { registerElement } from './lib/renderer/registry';