Added docs to most public APIs

Author: Ben Grynhaus

libs/core/src/angular-react-browser.module.ts

@@ -1,5 +1,6 @@
 import { NgModule } from '@angular/core';
 import { BrowserModule, ɵDomRendererFactory2 } from '@angular/platform-browser';
+
 import { AngularReactRendererFactory } from './renderer/renderer';
 
 @NgModule({

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

@@ -12,12 +12,11 @@ import {
   HostBinding,
   Input
 } from '@angular/core';
+import toStyle from 'css-to-style';
+
 import { isReactNode } from '../renderer/react-node';
 import { renderComponent, renderFunc, renderTemplate } from '../renderer/renderprop-helpers';
 import { unreachable } from '../utils/types/unreachable';
-import toStyle from 'css-to-style';
-
-type PropMapper = (value: any) => [string, any];
 
 type AttributeNameAlternative = [string, string | undefined];
 
@@ -51,24 +50,49 @@ export type JsxRenderFunc<TContext> = (context: TContext) => JSX.Element;
  */
 // NOTE: TProps is not used at the moment, but a preparation for a potential future change.
 export abstract class ReactWrapperComponent<TProps extends {}> implements AfterViewInit, OnChanges {
+  private _rClass: string;
+  private _rStyle: string;
+
   protected abstract reactNodeRef: ElementRef;
 
+  /**
+   * Alternative to `class` using the same syntax.
+   *
+   * @description Since this is a wrapper component, sticking to the virtual DOM concept, this should have any styling of its own.
+   * Any value passes to `rClass` will be passed to the root component's class.
+   */
   @Input()
   set rClass(value: string) {
+    this._rClass = value;
     if (isReactNode(this.reactNodeRef.nativeElement)) {
       this.reactNodeRef.nativeElement.setProperty('className', value);
       this.changeDetectorRef.detectChanges();
     }
   }
 
+  get rClass(): string {
+    return this._rClass;
+  }
+
+  /**
+   * Alternative to `style` using the same syntax.
+   *
+   * @description Since this is a wrapper component, sticking to the virtual DOM concept, this should have any styling of its own.
+   * Any value passes to `rStyle` will be passed to the root component's style.
+   */
   @Input()
   set rStyle(value: string) {
+    this._rStyle = value;
     if (isReactNode(this.reactNodeRef.nativeElement)) {
       this.reactNodeRef.nativeElement.setProperty('style', toStyle(value));
       this.changeDetectorRef.detectChanges();
     }
   }
 
+  get rStyle(): string {
+    return this._rStyle;
+  }
+
   /**
    * Creates an instance of ReactWrapperComponent.
    * @param elementRef The host element.
@@ -94,6 +118,9 @@ export abstract class ReactWrapperComponent<TProps extends {}> implements AfterV
     this.detectChanges();
   }
 
+  /**
+   * Trigger change detection on the component.
+   */
   protected detectChanges() {
     if (isReactNode(this.reactNodeRef.nativeElement)) {
       this.reactNodeRef.nativeElement.setRenderPending();

libs/core/src/renderer/components/Disguise.ts

@@ -1,10 +1,14 @@
-import { ReactWrapperComponent } from '../../components/wrapper-component';
-import { passPropsSymbol, getPassProps, PassProp } from '../../renderer/pass-prop-decorator';
 import * as React from 'react';
 import * as ReactDOM from 'react-dom';
+
+import { ReactWrapperComponent } from '../../components/wrapper-component';
+import { passPropsSymbol, getPassProps, PassProp } from '../../renderer/pass-prop-decorator';
 import { ReactContent } from '../react-content';
 import removeUndefinedProperties from '../../utils/object/remove-undefined-properties';
 
+/**
+ * Props for `Disguise` component.
+ */
 export interface DisguiseProps {
   /**
    * The type to render the root component as.

libs/core/src/renderer/pass-prop-decorator.ts

@@ -22,6 +22,10 @@ const passPropRename: (propName: string) => PropertyDecorator =
 const passPropDirect: PropertyDecorator =
   (target, propertyKey) => passPropImpl(target, propertyKey, propertyKey);
 
+/**
+ * Decorator to specify a property that should be passed as a prop to the underlying React component implicitly.
+ * Mainly useful for passing child components using the `Disguise` component.
+ */
 export function passProp(): PropertyDecorator;
 export function passProp(propName: string): PropertyDecorator;
 export function passProp(...args: any[]) {

libs/core/src/renderer/react-node.ts

@@ -2,6 +2,7 @@
 
 import * as React from 'react';
 import * as ReactDOM from 'react-dom';
+
 import removeUndefinedProperties from '../utils/object/remove-undefined-properties';
 import { CHILDREN_TO_APPEND_PROP } from './react-content';
 import { getComponentClass } from "./registry";

libs/core/src/renderer/registry.ts

@@ -1,4 +1,5 @@
 import * as React from 'react';
+
 import { Disguise } from "./components/Disguise";
 import { ReactContent } from "./react-content";
 
@@ -7,16 +8,21 @@ export type ComponentResolver = () => React.ReactType;
 const elementMap = new Map<string, { resolver: ComponentResolver }>();
 const camelCaseSplit = /([a-z0-9])([A-Z])/g;
 
+/**
+ * Register an element to be renderer when the renderer sees the tag.
+ * @param elementName the tag
+ * @param resolver A resolver to the React component
+ */
 export function registerElement(
   elementName: string,
   resolver: ComponentResolver
 ): void {
   if (elementMap.has(elementName)) {
-     // Ignore multiple register attempts for the same component.
-     // Angular doesn't allow sharing whole NgModule instances (in this case, an @NgModule for React-wrapped components) with lazy-loaded @NgModules (in the app),
-     // To keep the API simple, allow multiple calls to `registerElement`.
-     // Disadvantage is that you can't replace (React) component implementations at runtime. This sounds far-fetched, but solvable with a `static forRoot()` pattern for every
-     // React-wrapper components' @NgModule, ensuring that `registerElement` is only called once.
+    // Ignore multiple register attempts for the same component.
+    // Angular doesn't allow sharing whole NgModule instances (in this case, an @NgModule for React-wrapped components) with lazy-loaded @NgModules (in the app),
+    // To keep the API simple, allow multiple calls to `registerElement`.
+    // Disadvantage is that you can't replace (React) component implementations at runtime. This sounds far-fetched, but solvable with a `static forRoot()` pattern for every
+    // React-wrapper components' @NgModule, ensuring that `registerElement` is only called once.
     return;
   } else {
     const entry = { resolver: resolver };

libs/core/src/renderer/renderer.ts

@@ -2,13 +2,14 @@
 
 import { Injectable, Renderer2, RendererStyleFlags2, RendererType2 } from '@angular/core';
 import { EventManager, ɵDomRendererFactory2, ɵDomSharedStylesHost } from '@angular/platform-browser';
+
 import { isReactNode, ReactNode } from './react-node';
 
 const DEBUG = false;
 
 @Injectable()
 export class AngularReactRendererFactory extends ɵDomRendererFactory2 {
-  private defaultReactRenderer: ReactRenderer;
+  private readonly defaultReactRenderer: ReactRenderer;
 
   // Collection of ReactNodes that can be evaluated and flushed at the
   // end of Render.  This is necessary as the flow of element creation

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

@@ -1,5 +1,6 @@
 import { ComponentRef, TemplateRef } from "@angular/core";
 import * as React from 'react';
+
 import { CHILDREN_TO_APPEND_PROP, ReactContent } from "../renderer/react-content";
 
 function renderReactContent(rootNodes: HTMLElement[]): JSX.Element {
@@ -11,19 +12,37 @@ function renderReactContent(rootNodes: HTMLElement[]): JSX.Element {
   );
 }
 
+/**
+ * Wrap a `TemplateRef` with a `JSX.Element`.
+ *
+ * @param templateRef The template to wrap
+ * @param context The context to pass to the template
+ */
 export function renderTemplate<TContext extends object>(templateRef: TemplateRef<TContext>, context?: TContext): JSX.Element {
   const viewRef = templateRef.createEmbeddedView(context);
   viewRef.detectChanges();
 
   return renderReactContent(viewRef.rootNodes);
 }
 
+/**
+ * Wrap a function resolving to an `HTMLElement` with a `JSX.Element`.
+ *
+ * @param htmlRenderFunc The function to wrap
+ * @param context The context to pass to the function
+ */
 export function renderFunc<TContext extends object>(htmlRenderFunc: (context: TContext) => HTMLElement, context?: TContext): JSX.Element {
   const rootHtmlElement = htmlRenderFunc(context);
 
   return renderReactContent([rootHtmlElement]);
 }
 
+/**
+ * Wrap a `ComponentRef` with a `JSX.Element`.
+ *
+ * @param htmlRenderFunc The component reference to wrap
+ * @param context The context to pass to the component as `@Input`
+ */
 export function renderComponent<TContext extends object>(componentRef: ComponentRef<TContext>, context?: TContext): JSX.Element {
   Object.assign(componentRef.instance, context);
   componentRef.changeDetectorRef.detectChanges();

libs/core/src/typings/css-to-style.d.ts

@@ -1,7 +1,5 @@
-
+// NOTE: a [PR in DefinitelyTyped has been sent](https://github.com/DefinitelyTyped/DefinitelyTyped/pull/27253).
+// Once it gets in this type can be remove from here and required from there instead.
 declare module 'css-to-style' {
-
-  function toStyle(cssText: string) : CSSStyleDeclaration;
-
-  export default toStyle;
+  export default function toStyle(cssText: string): CSSStyleDeclaration;
 }

libs/core/src/utils/object/remove-undefined-properties.ts

@@ -1,3 +1,9 @@
+/**
+ * Remove all undefined properties from obj.
+ *
+ * Does **not** modify the original object.
+ * @returns A clone of `obj`, with all `undefined` properties removed
+ */
 const clearUndefinedProperties = <T extends object>(obj: T): Partial<T> => {
   return Object.keys(obj).reduce((acc, key) => {
     const _acc = acc;