feat(base): Add initialization, DOM events wrapper to component API. (google#4915)

* Adds an `initialize` constructor hook that is called after the root
  element is attached, but before `getDefaultFoundation` is called.
* Adds a simple way of adding / removing event listeners from a
  component's root node, without needing access to the root node itself.

Needed for google#4475
[#126819221]

Author: traviskaufman

packages/mdl-base/README.md

@@ -156,9 +156,12 @@ export class MyComponent extends MDLComponent {
 
 | method | description |
 | --- | --- |
+| `initialize(...args)` | Called after the root element is attached to the component, but _before_ the foundation is instantiated. Any positional arguments passed to the component constructor after the root element, along with the optional foundation 2nd argument, will be provided to this method. This is a good place to do any setup work normally done within a constructor function. |
 | `getDefaultFoundation()` | Returns an instance of a foundation class properly configured for the component. Called when no foundation instance is given within the constructor. Subclasses **must** implement this method. |
 | `initialSyncWithDOM()` | Called within the constructor. Subclasses may override this method if they wish to perform initial synchronization of state with the host DOM element. For example, a slider may want to check if its host element contains a pre-set value, and adjust its internal state accordingly. Note that the same caveats apply to this method as to foundation class lifecycle methods. Defaults to a no-op. |
 | `destroy()` | Subclasses may override this method if they wish to perform any additional cleanup work when a component is destroyed. For example, a component may want to deregister a window resize listener. |
+| `listen(type: string, handler: EventListener)` | Adds an event listener to the component's root node for the given `type`. Note that this is simply a proxy to `this.root_.addEventListener`. |
+| `unlisten(type: string, handler: EventListener)` | Removes an event listener from the component's root node. Note that this is simply a proxy to `this.root_.removeEventListener`. |
 | `emit(type: string, data: Object)` | Dispatches a custom event of type `type` with detail `data` from the component's root node. This is the preferred way of dispatching events within our vanilla components. |
 
 #### Static Methods
@@ -173,6 +176,41 @@ In addition to methods inherited, subclasses should implement the following two
 
 `MDLComponent` calls its foundation's `init()` function within its _constructor_, and its foundation's `destroy()` function within its own _destroy()_ function. Therefore it's important to remember to _always call super() when overriding destroy()_. Not doing so can lead to leaked resources.
 
+#### Initialization and constructor parameters
+
+If you need to pass in additional parameters into a component's constructor, you can make use of the
+`initialize` method, as shown above. An example of this is passing in a child component as a
+dependency.
+
+```js
+class MyComponent extends MDLComponent {
+  initialize(childComponent = null) {
+    this.child_ = childComponent ?
+      childComponent : new ChildComponent(this.root_.querySelector('.child'));
+  }
+
+  getDefaultFoundation() {
+    return new MyComponentFoundation({
+      doSomethingWithChildComponent: () => this.child_.doSomething(),
+      // ...
+    });
+  }
+}
+```
+
+You could call this code like so:
+
+```js
+const childComponent = new ChildComponent(document.querySelector('.some-child'));
+const myComponent = new MyComponent(
+  document.querySelector('.my-component'), /* foundation */ undefined, childComponent
+);
+// use myComponent
+```
+
+> NOTE: You could also pass in an initialized foundation if you wish. The example above simply
+> showcases how you could pass in initialization arguments without instantiating a foundation.
+
 #### Best Practice: Keep your adapters simple
 
 If you find your adapters getting too complex, you should consider refactoring the complex parts out into their own implementations.

packages/mdl-base/component.js

@@ -25,13 +25,20 @@ export default class MDLComponent {
     return new MDLComponent(root, new MDLFoundation());
   }
 
-  constructor(root, foundation) {
+  constructor(root, foundation, ...args) {
     this.root_ = root;
+    this.initialize(...args);
     this.foundation_ = foundation === undefined ? this.getDefaultFoundation() : foundation;
     this.foundation_.init();
     this.initialSyncWithDOM();
   }
 
+  initialize(/* ...args */) {
+    // Subclasses can override this to do any additional setup work that would be considered part of a
+    // "constructor". Essentially, it is a hook into the parent constructor before the foundation is
+    // initialized. Any additional arguments besides root and foundation will be passed in here.
+  }
+
   getDefaultFoundation() {
     // Subclasses must override this method to return a properly configured foundation class for the
     // component.
@@ -52,6 +59,18 @@ export default class MDLComponent {
     this.foundation_.destroy();
   }
 
+  // Wrapper method to add an event listener to the component's root element. This is most useful when
+  // listening for custom events.
+  listen(evtType, handler) {
+    this.root_.addEventListener(evtType, handler);
+  }
+
+  // Wrapper method to remove an event listener to the component's root element. This is most useful when
+  // unlistening for custom events.
+  unlisten(evtType, handler) {
+    this.root_.removeEventListener(evtType, handler);
+  }
+
   // Fires a cross-browser-compatible custom event from the component root of the given type,
   // with the given data.
   emit(evtType, evtData) {

test/unit/mdl-base/component.test.js

@@ -15,7 +15,9 @@
  */
 
 import test from 'tape';
+import domEvents from 'dom-events';
 import td from 'testdouble';
+
 import {MDLComponent} from '../../../packages/mdl-base';
 
 class FakeComponent extends MDLComponent {
@@ -34,6 +36,11 @@ class FakeComponent extends MDLComponent {
     });
   }
 
+  initialize(...args) {
+    this.initializeArgs = args;
+    this.initializeComesBeforeFoundation = !this.foundation_;
+  }
+
   initialSyncWithDOM() {
     this.synced = true;
   }
@@ -105,6 +112,39 @@ test("provides a default destroy() method which calls the foundation's destroy()
   t.end();
 });
 
+test('#initialize is called within constructor and passed any additional positional component args', t => {
+  const f = new FakeComponent(document.createElement('div'), /* foundation */ undefined, 'foo', 42);
+  t.deepEqual(f.initializeArgs, ['foo', 42]);
+  t.end();
+});
+
+test('#initialize is called before getDefaultFoundation()', t => {
+  const f = new FakeComponent(document.createElement('div'));
+  t.true(f.initializeComesBeforeFoundation);
+  t.end();
+});
+
+test('#listen adds an event listener to the root element', t => {
+  const root = document.createElement('div');
+  const f = new FakeComponent(root);
+  const handler = td.func('eventHandler');
+  f.listen('FakeComponent:customEvent', handler);
+  domEvents.emit(root, 'FakeComponent:customEvent');
+  t.doesNotThrow(() => td.verify(handler(td.matchers.anything())));
+  t.end();
+});
+
+test('#unlisten removes an event listener from the root element', t => {
+  const root = document.createElement('div');
+  const f = new FakeComponent(root);
+  const handler = td.func('eventHandler');
+  root.addEventListener('FakeComponent:customEvent', handler);
+  f.unlisten('FakeComponent:customEvent', handler);
+  domEvents.emit(root, 'FakeComponent:customEvent');
+  t.doesNotThrow(() => td.verify(handler(td.matchers.anything()), {times: 0}));
+  t.end();
+});
+
 test('#emit dispatches a custom event with the supplied data', t => {
   const root = document.createElement('div');
   const f = new FakeComponent(root);