refactor(upgrade): move shareable functionality to `UpgradeHelper` class (#17971)

This functionality can be potentionally re-used by the dynamic version.

packages/upgrade/src/common/upgrade_helper.ts

@@ -0,0 +1,238 @@
+/**
+ * @license
+ * Copyright Google Inc. All Rights Reserved.
+ *
+ * Use of this source code is governed by an MIT-style license that can be
+ * found in the LICENSE file at https://angular.io/license
+ */
+
+import {ElementRef, Injector, SimpleChanges} from '@angular/core';
+
+import * as angular from './angular1';
+import {$COMPILE, $CONTROLLER, $HTTP_BACKEND, $INJECTOR, $TEMPLATE_CACHE} from './constants';
+import {controllerKey, directiveNormalize, isFunction} from './util';
+
+
+// Constants
+export const REQUIRE_PREFIX_RE = /^(\^\^?)?(\?)?(\^\^?)?/;
+
+// Interfaces
+export interface IBindingDestination {
+  [key: string]: any;
+  $onChanges?: (changes: SimpleChanges) => void;
+}
+
+export interface IControllerInstance extends IBindingDestination {
+  $doCheck?: () => void;
+  $onDestroy?: () => void;
+  $onInit?: () => void;
+  $postLink?: () => void;
+}
+
+// Classes
+export class UpgradeHelper {
+  public readonly $injector: angular.IInjectorService;
+  public readonly element: Element;
+  public readonly $element: angular.IAugmentedJQuery;
+  public readonly directive: angular.IDirective;
+
+  private readonly $compile: angular.ICompileService;
+  private readonly $controller: angular.IControllerService;
+  private readonly $templateCache: angular.ITemplateCacheService;
+
+  constructor(private injector: Injector, private name: string, elementRef: ElementRef) {
+    this.$injector = injector.get($INJECTOR);
+    this.$compile = this.$injector.get($COMPILE);
+    this.$controller = this.$injector.get($CONTROLLER);
+    this.$templateCache = this.$injector.get($TEMPLATE_CACHE);
+
+    this.element = elementRef.nativeElement;
+    this.$element = angular.element(this.element);
+
+    this.directive = this.getDirective();
+  }
+
+  buildController(controllerType: angular.IController, $scope: angular.IScope) {
+    // TODO: Document that we do not pre-assign bindings on the controller instance.
+    // Quoted properties below so that this code can be optimized with Closure Compiler.
+    const locals = {'$scope': $scope, '$element': this.$element};
+    const controller = this.$controller(controllerType, locals, null, this.directive.controllerAs);
+
+    this.$element.data !(controllerKey(this.directive.name !), controller);
+
+    return controller;
+  }
+
+  compileTemplate(): angular.ILinkFn {
+    if (this.directive.template !== undefined) {
+      return this.compileHtml(this.getOrCall<string>(this.directive.template));
+    } else if (this.directive.templateUrl) {
+      const url = this.getOrCall<string>(this.directive.templateUrl);
+      const html = this.$templateCache.get(url) as string;
+      if (html !== undefined) {
+        return this.compileHtml(html);
+      } else {
+        throw new Error('loading directive templates asynchronously is not supported');
+      }
+    } else {
+      throw new Error(`Directive '${this.name}' is not a component, it is missing template.`);
+    }
+  }
+
+  getDirective(): angular.IDirective {
+    const directives: angular.IDirective[] = this.$injector.get(this.name + 'Directive');
+    if (directives.length > 1) {
+      throw new Error(`Only support single directive definition for: ${this.name}`);
+    }
+
+    const directive = directives[0];
+    if (directive.replace) this.notSupported('replace');
+    if (directive.terminal) this.notSupported('terminal');
+    if (directive.compile) this.notSupported('compile');
+
+    const link = directive.link;
+    // QUESTION: why not support link.post?
+    if (typeof link == 'object') {
+      if (link.post) this.notSupported('link.post');
+    }
+
+    return directive;
+  }
+
+  prepareTransclusion(): angular.ILinkFn|undefined {
+    const transclude = this.directive.transclude;
+    const contentChildNodes = this.extractChildNodes();
+    let $template = contentChildNodes;
+    let attachChildrenFn: angular.ILinkFn|undefined = (scope, cloneAttach) =>
+        cloneAttach !($template, scope);
+
+    if (transclude) {
+      const slots = Object.create(null);
+
+      if (typeof transclude === 'object') {
+        $template = [];
+
+        const slotMap = Object.create(null);
+        const filledSlots = Object.create(null);
+
+        // Parse the element selectors.
+        Object.keys(transclude).forEach(slotName => {
+          let selector = transclude[slotName];
+          const optional = selector.charAt(0) === '?';
+          selector = optional ? selector.substring(1) : selector;
+
+          slotMap[selector] = slotName;
+          slots[slotName] = null;            // `null`: Defined but not yet filled.
+          filledSlots[slotName] = optional;  // Consider optional slots as filled.
+        });
+
+        // Add the matching elements into their slot.
+        contentChildNodes.forEach(node => {
+          const slotName = slotMap[directiveNormalize(node.nodeName.toLowerCase())];
+          if (slotName) {
+            filledSlots[slotName] = true;
+            slots[slotName] = slots[slotName] || [];
+            slots[slotName].push(node);
+          } else {
+            $template.push(node);
+          }
+        });
+
+        // Check for required slots that were not filled.
+        Object.keys(filledSlots).forEach(slotName => {
+          if (!filledSlots[slotName]) {
+            throw new Error(`Required transclusion slot '${slotName}' on directive: ${this.name}`);
+          }
+        });
+
+        Object.keys(slots).filter(slotName => slots[slotName]).forEach(slotName => {
+          const nodes = slots[slotName];
+          slots[slotName] = (scope: angular.IScope, cloneAttach: angular.ICloneAttachFunction) =>
+              cloneAttach !(nodes, scope);
+        });
+      }
+
+      // Attach `$$slots` to default slot transclude fn.
+      attachChildrenFn.$$slots = slots;
+
+      // AngularJS v1.6+ ignores empty or whitespace-only transcluded text nodes. But Angular
+      // removes all text content after the first interpolation and updates it later, after
+      // evaluating the expressions. This would result in AngularJS failing to recognize text
+      // nodes that start with an interpolation as transcluded content and use the fallback
+      // content instead.
+      // To avoid this issue, we add a
+      // [zero-width non-joiner character](https://en.wikipedia.org/wiki/Zero-width_non-joiner)
+      // to empty text nodes (which can only be a result of Angular removing their initial content).
+      // NOTE: Transcluded text content that starts with whitespace followed by an interpolation
+      //       will still fail to be detected by AngularJS v1.6+
+      $template.forEach(node => {
+        if (node.nodeType === Node.TEXT_NODE && !node.nodeValue) {
+          node.nodeValue = '\u200C';
+        }
+      });
+    }
+
+    return attachChildrenFn;
+  }
+
+  resolveRequire(require: angular.DirectiveRequireProperty):
+      angular.SingleOrListOrMap<IControllerInstance>|null {
+    if (!require) {
+      return null;
+    } else if (Array.isArray(require)) {
+      return require.map(req => this.resolveRequire(req));
+    } else if (typeof require === 'object') {
+      const value: {[key: string]: IControllerInstance} = {};
+      Object.keys(require).forEach(key => value[key] = this.resolveRequire(require[key]) !);
+      return value;
+    } else if (typeof require === 'string') {
+      const match = require.match(REQUIRE_PREFIX_RE) !;
+      const inheritType = match[1] || match[3];
+
+      const name = require.substring(match[0].length);
+      const isOptional = !!match[2];
+      const searchParents = !!inheritType;
+      const startOnParent = inheritType === '^^';
+
+      const ctrlKey = controllerKey(name);
+      const elem = startOnParent ? this.$element.parent !() : this.$element;
+      const value = searchParents ? elem.inheritedData !(ctrlKey) : elem.data !(ctrlKey);
+
+      if (!value && !isOptional) {
+        throw new Error(
+            `Unable to find required '${require}' in upgraded directive '${this.name}'.`);
+      }
+
+      return value;
+    } else {
+      throw new Error(
+          `Unrecognized 'require' syntax on upgraded directive '${this.name}': ${require}`);
+    }
+  }
+
+  private compileHtml(html: string): angular.ILinkFn {
+    this.element.innerHTML = html;
+    return this.$compile(this.element.childNodes);
+  }
+
+  private extractChildNodes(): Node[] {
+    const childNodes: Node[] = [];
+    let childNode: Node|null;
+
+    while (childNode = this.element.firstChild) {
+      this.element.removeChild(childNode);
+      childNodes.push(childNode);
+    }
+
+    return childNodes;
+  }
+
+  private getOrCall<T>(property: T|Function): T {
+    return isFunction(property) ? property() : property;
+  }
+
+  private notSupported(feature: string) {
+    throw new Error(
+        `Upgraded directive '${this.name}' contains unsupported feature: '${feature}'.`);
+  }
+}

packages/upgrade/src/common/util.ts

@@ -50,6 +50,10 @@ export function getComponentName(component: Type<any>): string {
   return (component as any).overriddenName || component.name || component.toString().split('\n')[0];
 }
 
+export function isFunction(value: any): value is Function {
+  return typeof value === 'function';
+}
+
 export class Deferred<R> {
   promise: Promise<R>;
   resolve: (value?: R|PromiseLike<R>) => void;

packages/upgrade/src/static/upgrade_component.ts

@@ -8,10 +8,10 @@
 
 import {DoCheck, ElementRef, EventEmitter, Injector, OnChanges, OnDestroy, OnInit, SimpleChanges, ɵlooseIdentical as looseIdentical} from '@angular/core';
 import * as angular from '../common/angular1';
-import {$COMPILE, $CONTROLLER, $HTTP_BACKEND, $INJECTOR, $SCOPE, $TEMPLATE_CACHE} from '../common/constants';
+import {$SCOPE} from '../common/constants';
-import {controllerKey, directiveNormalize} from '../common/util';
+import {IBindingDestination, IControllerInstance, REQUIRE_PREFIX_RE, UpgradeHelper} from '../common/upgrade_helper';
+import {isFunction} from '../common/util';
 
-const REQUIRE_PREFIX_RE = /^(\^\^?)?(\?)?(\^\^?)?/;
 const NOT_SUPPORTED: any = 'NOT_SUPPORTED';
 const INITIAL_VALUE = {
   __UNINITIALIZED__: true
@@ -26,20 +26,6 @@ class Bindings {
   propertyToOutputMap: {[propName: string]: string} = {};
 }
 
-interface IBindingDestination {
-  [key: string]: any;
-  $onChanges?: (changes: SimpleChanges) => void;
-}
-
-interface IControllerInstance extends IBindingDestination {
-  $doCheck?: () => void;
-  $onDestroy?: () => void;
-  $onInit?: () => void;
-  $postLink?: () => void;
-}
-
-type LifecycleHook = '$doCheck' | '$onChanges' | '$onDestroy' | '$onInit' | '$postLink';
-
 /**
  * @whatItDoes
  *
@@ -81,11 +67,9 @@ type LifecycleHook = '$doCheck' | '$onChanges' | '$onDestroy' | '$onInit' | '$po
  * @experimental
  */
 export class UpgradeComponent implements OnInit, OnChanges, DoCheck, OnDestroy {
+  private helper: UpgradeHelper;
+
   private $injector: angular.IInjectorService;
-  private $compile: angular.ICompileService;
-  private $templateCache: angular.ITemplateCacheService;
-  private $httpBackend: angular.IHttpBackendService;
-  private $controller: angular.IControllerService;
 
   private element: Element;
   private $element: angular.IAugmentedJQuery;
@@ -120,16 +104,14 @@ export class UpgradeComponent implements OnInit, OnChanges, DoCheck, OnDestroy {
    * already implements them and so does not wire up calls to them at runtime.
    */
   constructor(private name: string, private elementRef: ElementRef, private injector: Injector) {
-    this.$injector = injector.get($INJECTOR);
+    this.helper = new UpgradeHelper(injector, name, elementRef);
-    this.$compile = this.$injector.get($COMPILE);
-    this.$templateCache = this.$injector.get($TEMPLATE_CACHE);
-    this.$httpBackend = this.$injector.get($HTTP_BACKEND);
-    this.$controller = this.$injector.get($CONTROLLER);
 
-    this.element = elementRef.nativeElement;
+    this.$injector = this.helper.$injector;
-    this.$element = angular.element(this.element);
 
-    this.directive = this.getDirective(name);
+    this.element = this.helper.element;
+    this.$element = this.helper.$element;
+
+    this.directive = this.helper.directive;
     this.bindings = this.initializeBindings(this.directive);
 
     // We ask for the AngularJS scope from the Angular injector, since
@@ -144,16 +126,14 @@ export class UpgradeComponent implements OnInit, OnChanges, DoCheck, OnDestroy {
 
   ngOnInit() {
     // Collect contents, insert and compile template
-    const attachChildNodes: angular.ILinkFn|undefined =
+    const attachChildNodes: angular.ILinkFn|undefined = this.helper.prepareTransclusion();
-        this.prepareTransclusion(this.directive.transclude);
+    const linkFn = this.helper.compileTemplate();
-    const linkFn = this.compileTemplate(this.directive);
 
     // Instantiate controller
     const controllerType = this.directive.controller;
     const bindToController = this.directive.bindToController;
     if (controllerType) {
-      this.controllerInstance = this.buildController(
+      this.controllerInstance = this.helper.buildController(controllerType, this.$componentScope);
-          controllerType, this.$componentScope, this.$element, this.directive.controllerAs !);
     } else if (bindToController) {
       throw new Error(
           `Upgraded directive '${this.directive.name}' specifies 'bindToController' but no controller.`);
@@ -165,8 +145,7 @@ export class UpgradeComponent implements OnInit, OnChanges, DoCheck, OnDestroy {
 
     // Require other controllers
     const directiveRequire = this.getDirectiveRequire(this.directive);
-    const requiredControllers =
+    const requiredControllers = this.helper.resolveRequire(directiveRequire);
-        this.resolveRequire(this.directive.name !, this.$element, directiveRequire);
 
     if (this.directive.bindToController && isMap(directiveRequire)) {
       const requiredControllersMap = requiredControllers as{[key: string]: IControllerInstance};
@@ -253,23 +232,6 @@ export class UpgradeComponent implements OnInit, OnChanges, DoCheck, OnDestroy {
     this.$componentScope.$destroy();
   }
 
-  private getDirective(name: string): angular.IDirective {
-    const directives: angular.IDirective[] = this.$injector.get(name + 'Directive');
-    if (directives.length > 1) {
-      throw new Error('Only support single directive definition for: ' + this.name);
-    }
-    const directive = directives[0];
-    if (directive.replace) this.notSupported('replace');
-    if (directive.terminal) this.notSupported('terminal');
-    if (directive.compile) this.notSupported('compile');
-    const link = directive.link;
-    // QUESTION: why not support link.post?
-    if (typeof link == 'object') {
-      if ((<angular.IDirectivePrePost>link).post) this.notSupported('link.post');
-    }
-    return directive;
-  }
-
   private getDirectiveRequire(directive: angular.IDirective): angular.DirectiveRequireProperty {
     const require = directive.require || (directive.controller && directive.name) !;
 
@@ -332,158 +294,6 @@ export class UpgradeComponent implements OnInit, OnChanges, DoCheck, OnDestroy {
     return bindings;
   }
 
-  private prepareTransclusion(transclude: angular.DirectiveTranscludeProperty = false):
-      angular.ILinkFn|undefined {
-    const contentChildNodes = this.extractChildNodes(this.element);
-    let $template = contentChildNodes;
-    let attachChildrenFn: angular.ILinkFn|undefined = (scope, cloneAttach) =>
-        cloneAttach !($template, scope);
-
-    if (transclude) {
-      const slots = Object.create(null);
-
-      if (typeof transclude === 'object') {
-        $template = [];
-
-        const slotMap = Object.create(null);
-        const filledSlots = Object.create(null);
-
-        // Parse the element selectors.
-        Object.keys(transclude).forEach(slotName => {
-          let selector = transclude[slotName];
-          const optional = selector.charAt(0) === '?';
-          selector = optional ? selector.substring(1) : selector;
-
-          slotMap[selector] = slotName;
-          slots[slotName] = null;            // `null`: Defined but not yet filled.
-          filledSlots[slotName] = optional;  // Consider optional slots as filled.
-        });
-
-        // Add the matching elements into their slot.
-        contentChildNodes.forEach(node => {
-          const slotName = slotMap[directiveNormalize(node.nodeName.toLowerCase())];
-          if (slotName) {
-            filledSlots[slotName] = true;
-            slots[slotName] = slots[slotName] || [];
-            slots[slotName].push(node);
-          } else {
-            $template.push(node);
-          }
-        });
-
-        // Check for required slots that were not filled.
-        Object.keys(filledSlots).forEach(slotName => {
-          if (!filledSlots[slotName]) {
-            throw new Error(`Required transclusion slot '${slotName}' on directive: ${this.name}`);
-          }
-        });
-
-        Object.keys(slots).filter(slotName => slots[slotName]).forEach(slotName => {
-          const nodes = slots[slotName];
-          slots[slotName] = (scope: angular.IScope, cloneAttach: angular.ICloneAttachFunction) =>
-              cloneAttach !(nodes, scope);
-        });
-      }
-
-      // Attach `$$slots` to default slot transclude fn.
-      attachChildrenFn.$$slots = slots;
-    }
-
-    return attachChildrenFn;
-  }
-
-  private extractChildNodes(element: Element): Node[] {
-    const childNodes: Node[] = [];
-    let childNode: Node|null;
-
-    while (childNode = element.firstChild) {
-      element.removeChild(childNode);
-      childNodes.push(childNode);
-    }
-
-    return childNodes;
-  }
-
-  private compileTemplate(directive: angular.IDirective): angular.ILinkFn {
-    if (this.directive.template !== undefined) {
-      return this.compileHtml(getOrCall(this.directive.template));
-    } else if (this.directive.templateUrl) {
-      const url = getOrCall(this.directive.templateUrl);
-      const html = this.$templateCache.get(url) as string;
-      if (html !== undefined) {
-        return this.compileHtml(html);
-      } else {
-        throw new Error('loading directive templates asynchronously is not supported');
-        // return new Promise((resolve, reject) => {
-        //   this.$httpBackend('GET', url, null, (status: number, response: string) => {
-        //     if (status == 200) {
-        //       resolve(this.compileHtml(this.$templateCache.put(url, response)));
-        //     } else {
-        //       reject(`GET component template from '${url}' returned '${status}: ${response}'`);
-        //     }
-        //   });
-        // });
-      }
-    } else {
-      throw new Error(`Directive '${this.name}' is not a component, it is missing template.`);
-    }
-  }
-
-  private buildController(
-      controllerType: angular.IController, $scope: angular.IScope,
-      $element: angular.IAugmentedJQuery, controllerAs: string) {
-    // TODO: Document that we do not pre-assign bindings on the controller instance
-    // Quoted properties below so that this code can be optimized with Closure Compiler.
-    const locals = {'$scope': $scope, '$element': $element};
-    const controller = this.$controller(controllerType, locals, null, controllerAs);
-    $element.data !(controllerKey(this.directive.name !), controller);
-    return controller;
-  }
-
-  private resolveRequire(
-      directiveName: string, $element: angular.IAugmentedJQuery,
-      require: angular.DirectiveRequireProperty):
-      angular.SingleOrListOrMap<IControllerInstance>|null {
-    if (!require) {
-      return null;
-    } else if (Array.isArray(require)) {
-      return require.map(req => this.resolveRequire(directiveName, $element, req));
-    } else if (typeof require === 'object') {
-      const value: {[key: string]: IControllerInstance} = {};
-
-      Object.keys(require).forEach(
-          key => value[key] = this.resolveRequire(directiveName, $element, require[key]) !);
-
-      return value;
-    } else if (typeof require === 'string') {
-      const match = require.match(REQUIRE_PREFIX_RE) !;
-      const inheritType = match[1] || match[3];
-
-      const name = require.substring(match[0].length);
-      const isOptional = !!match[2];
-      const searchParents = !!inheritType;
-      const startOnParent = inheritType === '^^';
-
-      const ctrlKey = controllerKey(name);
-
-      if (startOnParent) {
-        $element = $element.parent !();
-      }
-
-      const value = searchParents ? $element.inheritedData !(ctrlKey) : $element.data !(ctrlKey);
-
-      if (!value && !isOptional) {
-        throw new Error(
-            `Unable to find required '${require}' in upgraded directive '${directiveName}'.`);
-      }
-
-      return value;
-    } else {
-      throw new Error(
-          `Unrecognized require syntax on upgraded directive '${directiveName}': ${require}`);
-    }
-  }
-
   private initializeOutputs() {
     // Initialize the outputs for `=` and `&` bindings
     this.bindings.twoWayBoundProperties.concat(this.bindings.expressionBoundProperties)
@@ -512,24 +322,6 @@ export class UpgradeComponent implements OnInit, OnChanges, DoCheck, OnDestroy {
       this.bindingDestination.$onChanges(changes);
     }
   }
-
-  private notSupported(feature: string) {
-    throw new Error(
-        `Upgraded directive '${this.name}' contains unsupported feature: '${feature}'.`);
-  }
-
-  private compileHtml(html: string): angular.ILinkFn {
-    this.element.innerHTML = html;
-    return this.$compile(this.element.childNodes);
-  }
-}
-
-function getOrCall<T>(property: Function | T): T {
-  return isFunction(property) ? property() : property;
-}
-
-function isFunction(value: any): value is Function {
-  return typeof value === 'function';
 }
 
 // NOTE: Only works for `typeof T !== 'object'`.