feat(select): Implement compareWith so custom comparators can be used.

Fixes Issue #2250 and Issue #2785. Users can supply a custom comparator that tests for equality. The comparator can be changed dynamically at which point the selection may change. If the comparator throws an exception, it will log a warning in developer mode but will be swallowed in production mode.

Author: ppham27

src/demo-app/select/select-demo.html

@@ -129,5 +129,32 @@
     </md-card>
   </div>
 
+  <div *ngIf="showSelect">
+    <md-card>
+      <md-card-subtitle>compareWith</md-card-subtitle>
+      <md-card-content>
+        <md-select placeholder="Drink" [color]="drinksTheme"
+                   [ngModel]="currentDrinkObject"
+                   (ngModelChange)="setDrinkObjectByCopy($event)"
+                   [required]="drinkObjectRequired"
+                   [compareWith]="compareByValue ? compareDrinkObjectsByValue : compareByReference"
+                   #drinkObjectControl="ngModel">
+          <md-option *ngFor="let drink of drinks" [value]="drink" [disabled]="drink.disabled">
+            {{ drink.viewValue }}
+          </md-option>
+        </md-select>
+        <p> Value: {{ currentDrinkObject | json }} </p>
+        <p> Touched: {{ drinkObjectControl.touched }} </p>
+        <p> Dirty: {{ drinkObjectControl.dirty }} </p>
+        <p> Status: {{ drinkObjectControl.control?.status }} </p>
+        <p> Comparison Mode: {{ compareByValue ? 'VALUE' : 'REFERENCE' }} </p>
+
+        <button md-button (click)="drinkObjectRequired=!drinkObjectRequired">TOGGLE REQUIRED</button>
+        <button md-button (click)="compareByValue=!compareByValue">TOGGLE COMPARE BY VALUE</button>
+        <button md-button (click)="drinkObjectControl.reset()">RESET</button>
+      </md-card-content>
+    </md-card>
+  </div>
+
 </div>
 <div style="height: 500px">This div is for testing scrolled selects.</div>

src/demo-app/select/select-demo.ts

@@ -10,11 +10,13 @@ import {MdSelectChange} from '@angular/material';
 })
 export class SelectDemo {
   drinksRequired = false;
+  drinkObjectRequired = false;
   pokemonRequired = false;
   drinksDisabled = false;
   pokemonDisabled = false;
   showSelect = false;
   currentDrink: string;
+  currentDrinkObject: {}|undefined = {value: 'tea-5', viewValue: 'Tea'};
   currentPokemon: string[];
   currentPokemonFromGroup: string;
   currentDigimon: string;
@@ -24,6 +26,7 @@ export class SelectDemo {
   topHeightCtrl = new FormControl(0);
   drinksTheme = 'primary';
   pokemonTheme = 'primary';
+  compareByValue = true;
 
   foods = [
     {value: null, viewValue: 'None'},
@@ -111,4 +114,16 @@ export class SelectDemo {
   setPokemonValue() {
     this.currentPokemon = ['eevee-4', 'psyduck-6'];
   }
+
+  setDrinkObjectByCopy(selectedDrink: {}) {
+    this.currentDrinkObject = selectedDrink ? {...selectedDrink} : undefined;
+  }
+
+  compareDrinkObjectsByValue(d1: {value: string}, d2: {value: string}) {
+    return d1 && d2 && d1.value === d2.value;
+  }
+
+  compareByReference(o1: any, o2: any) {
+    return o1 === o2;
+  }
 }

src/lib/select/select.spec.ts

@@ -73,7 +73,10 @@ describe('MdSelect', () => {
         BasicSelectWithoutFormsPreselected,
         BasicSelectWithoutFormsMultiple,
         SelectInsideFormGroup,
-        SelectWithCustomTrigger
+        SelectWithCustomTrigger,
+        FalsyValueSelect,
+        SelectInsideFormGroup,
+        NgModelCompareWithSelect,
       ],
       providers: [
         {provide: OverlayContainer, useFactory: () => {
@@ -2715,8 +2718,74 @@ describe('MdSelect', () => {
 
   });
 
-});
+  describe('compareWith behavior', () => {
+    let fixture: ComponentFixture<NgModelCompareWithSelect>;
+    let instance: NgModelCompareWithSelect;
+
+    beforeEach(async(() => {
+      fixture = TestBed.createComponent(NgModelCompareWithSelect);
+      instance = fixture.componentInstance;
+      fixture.detectChanges();
+    }));
+
+    it('should have a selection', () => {
+      const selectedOption = instance.select.selected as MdOption;
+      expect(selectedOption.value.value).toEqual('pizza-1');
+    });
+
+    it('should update when making a new selection', async(() => {
+      instance.options.last._selectViaInteraction();
+      fixture.detectChanges();
+      fixture.whenStable().then(() => {
+        const selectedOption = instance.select.selected as MdOption;
+        expect(instance.selectedFood.value).toEqual('tacos-2');
+        expect(selectedOption.value.value).toEqual('tacos-2');
+      });
+    }));
+
+    describe('when comparing by reference', () => {
+      beforeEach(async(() => {
+        spyOn(instance, 'compareByReference').and.callThrough();
+        instance.useCompareByReference();
+        fixture.detectChanges();
+      }));
+
+      it('should use the comparator', () => {
+        expect(instance.compareByReference).toHaveBeenCalled();
+      });
+
+      it('should initialize with no selection despite having a value', () => {
+        expect(instance.selectedFood.value).toBe('pizza-1');
+        expect(instance.select.selected).toBeUndefined();
+      });
+
+      it('should not update the selection when changing the value', async(() => {
+        instance.options.first._selectViaInteraction();
+        fixture.detectChanges();
+        fixture.whenStable().then(() => {
+          expect(instance.selectedFood.value).toEqual('steak-0');
+          expect(instance.select.selected).toBeUndefined();
+        });
+      }));
+
+    });
+
+    describe('when using a non-function comparator', () => {
+      beforeEach(() => {
+        instance.useNullComparator();
+      });
 
+      it('should throw an error', () => {
+        expect(() => {
+          fixture.detectChanges();
+        }).toThrowError('compareWith must be a function, but received null');
+      });
+
+    });
+
+  });
+
+});
 
 @Component({
   selector: 'basic-select',
@@ -3251,6 +3320,7 @@ class BasicSelectWithoutFormsMultiple {
   @ViewChild(MdSelect) select: MdSelect;
 }
 
+
 @Component({
   selector: 'select-with-custom-trigger',
   template: `
@@ -3271,3 +3341,40 @@ class SelectWithCustomTrigger {
   ];
   control = new FormControl();
 }
+
+
+@Component({
+  selector: 'ng-model-compare-with',
+  template: `
+    <md-select [ngModel]="selectedFood" (ngModelChange)="setFoodByCopy($event)"
+               [compareWith]="comparator">
+      <md-option *ngFor="let food of foods" [value]="food">{{ food.viewValue }}</md-option>
+    </md-select>
+  `
+})
+class NgModelCompareWithSelect {
+  foods: ({value: string, viewValue: string})[] = [
+    { value: 'steak-0', viewValue: 'Steak' },
+    { value: 'pizza-1', viewValue: 'Pizza' },
+    { value: 'tacos-2', viewValue: 'Tacos' },
+  ];
+  selectedFood: {value: string, viewValue: string} = { value: 'pizza-1', viewValue: 'Pizza' };
+  comparator: ((f1: any, f2: any) => boolean)|null = this.compareByValue;
+
+  @ViewChild(MdSelect) select: MdSelect;
+  @ViewChildren(MdOption) options: QueryList<MdOption>;
+
+  useCompareByValue() { this.comparator = this.compareByValue; }
+
+  useCompareByReference() { this.comparator = this.compareByReference; }
+
+  useNullComparator() { this.comparator = null; }
+
+  compareByValue(f1: any, f2: any) { return f1 && f2 && f1.value === f2.value; }
+
+  compareByReference(f1: any, f2: any) { return f1 === f2; }
+
+  setFoodByCopy(newValue: {value: string, viewValue: string}) {
+    this.selectedFood = Object.assign({}, newValue);
+  }
+}

src/lib/select/select.ts

@@ -29,6 +29,7 @@ import {
   ViewChild,
   ViewEncapsulation,
   Directive,
+  isDevMode,
 } from '@angular/core';
 import {ControlValueAccessor, FormGroupDirective, NgControl, NgForm} from '@angular/forms';
 import {DOWN_ARROW, END, ENTER, HOME, SPACE, UP_ARROW} from '@angular/cdk/keycodes';
@@ -220,6 +221,9 @@ export class MdSelect extends _MdSelectMixinBase implements AfterContentInit, On
   /** Whether the component is in multiple selection mode. */
   private _multiple: boolean = false;
 
+  /** Comparison function to specify which option is displayed. Defaults to object equality. */
+  private _compareWith = (o1: any, o2: any) => o1 === o2;
+
   /** Deals with the selection logic. */
   _selectionModel: SelectionModel<MdOption>;
 
@@ -337,6 +341,25 @@ export class MdSelect extends _MdSelectMixinBase implements AfterContentInit, On
     this._multiple = coerceBooleanProperty(value);
   }
 
+  /**
+   * A function to compare the option values with the selected values. The first argument
+   * is a value from an option. The second is a value from the selection. A boolean
+   * should be returned.
+   */
+  @Input()
+  get compareWith() { return this._compareWith; }
+  set compareWith(fn: (o1: any, o2: any) => boolean) {
+    if (typeof fn !== 'function') {
+      throw new TypeError(
+        `compareWith must be a function, but received ${JSON.stringify(fn)}`);
+    }
+    this._compareWith = fn;
+    if (this._selectionModel) {
+      // A different comparator means the selection could change.
+      this._initializeSelection();
+    }
+  }
+
   /** Whether to float the placeholder text. */
   @Input()
   get floatPlaceholder(): FloatPlaceholderType { return this._floatPlaceholder; }
@@ -434,12 +457,7 @@ export class MdSelect extends _MdSelectMixinBase implements AfterContentInit, On
 
     this._changeSubscription = startWith.call(this.options.changes, null).subscribe(() => {
       this._resetOptions();
-
-      // Defer setting the value in order to avoid the "Expression
-      // has changed after it was checked" errors from Angular.
-      Promise.resolve().then(() => {
-        this._setSelectionByValue(this._control ? this._control.value : this._value);
-      });
+      this._initializeSelection();
     });
   }
 
@@ -670,6 +688,14 @@ export class MdSelect extends _MdSelectMixinBase implements AfterContentInit, On
     scrollContainer!.scrollTop = this._scrollTop;
   }
 
+  private _initializeSelection(): void {
+    // Defer setting the value in order to avoid the "Expression
+    // has changed after it was checked" errors from Angular.
+    Promise.resolve().then(() => {
+      this._setSelectionByValue(this._control ? this._control.value : this._value);
+    });
+  }
+
   /**
    * Sets the selected option based on a value. If no option can be
    * found with the designated value, the select trigger is cleared.
@@ -710,18 +736,28 @@ export class MdSelect extends _MdSelectMixinBase implements AfterContentInit, On
    * @returns Option that has the corresponding value.
    */
   private _selectValue(value: any, isUserInput = false): MdOption | undefined {
-    let correspondingOption = this.options.find(option => {
-      return option.value != null && option.value === value;
+    const correspondingOption = this.options.find((option: MdOption) => {
+      try {
+        // Treat null as a special reset value.
+        return option.value != null && this._compareWith(option.value,  value);
+      } catch (error) {
+        if (isDevMode()) {
+          // Notify developers of errors in their comparator.
+          console.warn(error);
+        }
+        return false;
+      }
     });
 
     if (correspondingOption) {
       isUserInput ? correspondingOption._selectViaInteraction() : correspondingOption.select();
       this._selectionModel.select(correspondingOption);
     }
-
+      
     return correspondingOption;
   }
 
+
   /**
    * Clears the select trigger and deselects every option in the list.
    * @param skip Option that should not be deselected.