feat(material/list): support two-data binding on list option selected (#23125)

Adds support for two-way data binding on the `selected` property of `mat-list-option`.

Fixes #23122.

Author: crisbeto

src/material-experimental/mdc-list/list-option.ts

@@ -15,13 +15,15 @@ import {
   Component,
   ContentChildren,
   ElementRef,
+  EventEmitter,
   Inject,
   InjectionToken,
   Input,
   NgZone,
   OnDestroy,
   OnInit,
   Optional,
+  Output,
   QueryList,
   ViewChild,
   ViewEncapsulation
@@ -96,6 +98,14 @@ export class MatListOption extends MatListItemBase implements ListOption, OnInit
    */
   private _inputsInitialized = false;
 
+  /**
+   * Emits when the selected state of the option has changed.
+   * Use to facilitate two-data binding to the `selected` property.
+   * @docs-private
+   */
+  @Output()
+  readonly selectedChange: EventEmitter<boolean> = new EventEmitter<boolean>();
+
   @ViewChild('text') _itemText: ElementRef<HTMLElement>;
 
   @ContentChildren(MatLine, {read: ElementRef, descendants: true}) lines:
@@ -241,6 +251,7 @@ export class MatListOption extends MatListItemBase implements ListOption, OnInit
       this._selectionList.selectedOptions.deselect(this);
     }
 
+    this.selectedChange.emit(selected);
     this._changeDetectorRef.markForCheck();
     return true;
   }

src/material-experimental/mdc-list/selection-list.spec.ts

@@ -985,6 +985,44 @@ describe('MDC-based MatSelectionList without forms', () => {
     });
 
   });
+
+  describe('with single selection', () => {
+    let fixture: ComponentFixture<ListOptionWithTwoWayBinding>;
+    let optionElement: HTMLElement;
+    let option: MatListOption;
+
+    beforeEach(waitForAsync(() => {
+      TestBed.configureTestingModule({
+        imports: [MatListModule],
+        declarations: [ListOptionWithTwoWayBinding],
+      }).compileComponents();
+
+      fixture = TestBed.createComponent(ListOptionWithTwoWayBinding);
+      fixture.detectChanges();
+      const optionDebug = fixture.debugElement.query(By.directive(MatListOption));
+      option = optionDebug.componentInstance;
+      optionElement = optionDebug.nativeElement;
+    }));
+
+    it('should sync the value from the view to the option', () => {
+      expect(option.selected).toBe(false);
+
+      fixture.componentInstance.selected = true;
+      fixture.detectChanges();
+
+      expect(option.selected).toBe(true);
+    });
+
+    it('should sync the value from the option to the view', () => {
+      expect(fixture.componentInstance.selected).toBe(false);
+
+      optionElement.click();
+      fixture.detectChanges();
+
+      expect(fixture.componentInstance.selected).toBe(true);
+    });
+  });
+
 });
 
 describe('MDC-based MatSelectionList with forms', () => {
@@ -1651,3 +1689,13 @@ class SelectionListWithIndirectChildOptions {
 })
 class SelectionListWithIndirectDescendantLines {
 }
+
+
+@Component({template: `
+  <mat-selection-list>
+    <mat-list-option [(selected)]="selected">Item</mat-list-option>
+  </mat-selection-list>
+`})
+class ListOptionWithTwoWayBinding {
+  selected = false;
+}

src/material/list/selection-list.spec.ts

@@ -1145,6 +1145,43 @@ describe('MatSelectionList without forms', () => {
       });
 
   });
+
+  describe('with single selection', () => {
+    let fixture: ComponentFixture<ListOptionWithTwoWayBinding>;
+    let optionElement: HTMLElement;
+    let option: MatListOption;
+
+    beforeEach(waitForAsync(() => {
+      TestBed.configureTestingModule({
+        imports: [MatListModule],
+        declarations: [ListOptionWithTwoWayBinding],
+      }).compileComponents();
+
+      fixture = TestBed.createComponent(ListOptionWithTwoWayBinding);
+      fixture.detectChanges();
+      const optionDebug = fixture.debugElement.query(By.directive(MatListOption));
+      option = optionDebug.componentInstance;
+      optionElement = optionDebug.nativeElement;
+    }));
+
+    it('should sync the value from the view to the option', () => {
+      expect(option.selected).toBe(false);
+
+      fixture.componentInstance.selected = true;
+      fixture.detectChanges();
+
+      expect(option.selected).toBe(true);
+    });
+
+    it('should sync the value from the option to the view', () => {
+      expect(fixture.componentInstance.selected).toBe(false);
+
+      optionElement.click();
+      fixture.detectChanges();
+
+      expect(fixture.componentInstance.selected).toBe(true);
+    });
+  });
 });
 
 describe('MatSelectionList with forms', () => {
@@ -1828,3 +1865,13 @@ class SelectionListWithIndirectChildOptions {
 })
 class SelectionListWithIndirectDescendantLines {
 }
+
+
+@Component({template: `
+  <mat-selection-list>
+    <mat-list-option [(selected)]="selected">Item</mat-list-option>
+  </mat-selection-list>
+`})
+class ListOptionWithTwoWayBinding {
+  selected = false;
+}

src/material/list/selection-list.ts

@@ -127,6 +127,14 @@ export class MatListOption extends _MatListOptionBase implements AfterContentIni
   @ContentChild(MatListIconCssMatStyler) _icon: MatListIconCssMatStyler;
   @ContentChildren(MatLine, {descendants: true}) _lines: QueryList<MatLine>;
 
+  /**
+   * Emits when the selected state of the option has changed.
+   * Use to facilitate two-data binding to the `selected` property.
+   * @docs-private
+   */
+  @Output()
+  readonly selectedChange: EventEmitter<boolean> = new EventEmitter<boolean>();
+
   /** DOM element containing the item's text. */
   @ViewChild('text') _text: ElementRef;
 
@@ -300,6 +308,7 @@ export class MatListOption extends _MatListOptionBase implements AfterContentIni
       this.selectionList.selectedOptions.deselect(this);
     }
 
+    this.selectedChange.emit(selected);
     this._changeDetector.markForCheck();
     return true;
   }

tools/public_api_guard/material/list.d.ts

@@ -61,6 +61,7 @@ export declare class MatListOption extends _MatListOptionBase implements AfterCo
     set disabled(value: any);
     get selected(): boolean;
     set selected(value: boolean);
+    readonly selectedChange: EventEmitter<boolean>;
     selectionList: MatSelectionList;
     get value(): any;
     set value(newValue: any);
@@ -82,7 +83,7 @@ export declare class MatListOption extends _MatListOptionBase implements AfterCo
     static ngAcceptInputType_disableRipple: BooleanInput;
     static ngAcceptInputType_disabled: BooleanInput;
     static ngAcceptInputType_selected: BooleanInput;
-    static ɵcmp: i0.ɵɵComponentDeclaration<MatListOption, "mat-list-option", ["matListOption"], { "disableRipple": "disableRipple"; "checkboxPosition": "checkboxPosition"; "color": "color"; "value": "value"; "disabled": "disabled"; "selected": "selected"; }, {}, ["_avatar", "_icon", "_lines"], ["*", "[mat-list-avatar], [mat-list-icon], [matListAvatar], [matListIcon]"]>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<MatListOption, "mat-list-option", ["matListOption"], { "disableRipple": "disableRipple"; "checkboxPosition": "checkboxPosition"; "color": "color"; "value": "value"; "disabled": "disabled"; "selected": "selected"; }, { "selectedChange": "selectedChange"; }, ["_avatar", "_icon", "_lines"], ["*", "[mat-list-avatar], [mat-list-icon], [matListAvatar], [matListIcon]"]>;
     static ɵfac: i0.ɵɵFactoryDeclaration<MatListOption, never>;
 }