feat(cdk-experimental/selection): add selection state to a list of items (#18424)

Author: yifange

.github/CODEOWNERS

@@ -120,6 +120,7 @@
 /src/cdk-experimental/dialog/**                    @jelbourn @crisbeto
 /src/cdk-experimental/popover-edit/**              @kseamon @andrewseguin
 /src/cdk-experimental/scrolling/**                 @mmalerba
+/src/cdk-experimental/selection/**                 @yifange @jelbourn
 
 # Docs examples & guides
 /guides/**                                         @jelbourn
@@ -196,6 +197,7 @@
 /src/dev-app/typography/**                         @crisbeto
 /src/dev-app/virtual-scroll/**                     @mmalerba
 /src/dev-app/youtube-player/**                     @nathantate
+/src/dev-app/selection/**                          @yifange @jelbourn
 
 # E2E app
 /src/e2e-app/*                                     @jelbourn

src/cdk-experimental/config.bzl

@@ -3,6 +3,7 @@ CDK_EXPERIMENTAL_ENTRYPOINTS = [
     "dialog",
     "popover-edit",
     "scrolling",
+    "selection",
 ]
 
 # List of all entry-point targets of the Angular cdk-experimental package.

src/cdk-experimental/selection/BUILD.bazel

@@ -0,0 +1,20 @@
+package(default_visibility = ["//visibility:public"])
+
+load("//tools:defaults.bzl", "ng_module")
+
+ng_module(
+    name = "selection",
+    srcs = glob(
+        ["**/*.ts"],
+        exclude = ["**/*.spec.ts"],
+    ),
+    module_name = "@angular/cdk-experimental/selection",
+    deps = [
+        "//src/cdk/coercion",
+        "//src/cdk/collections",
+        "//src/cdk/table",
+        "@npm//@angular/core",
+        "@npm//@angular/forms",
+        "@npm//rxjs",
+    ],
+)

src/cdk-experimental/selection/index.ts

@@ -0,0 +1,10 @@
+/**
+ * @license
+ * Copyright Google LLC 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
+ */
+
+export * from './public-api';
+

src/cdk-experimental/selection/public-api.ts

@@ -0,0 +1,15 @@
+/**
+ * @license
+ * Copyright Google LLC 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
+ */
+
+export * from './selection';
+export * from './select-all';
+export * from './selection-toggle';
+export * from './selection-column';
+export * from './row-selection';
+export * from './selection-set';
+export * from './selection-module';

src/cdk-experimental/selection/row-selection.ts

@@ -0,0 +1,39 @@
+/**
+ * @license
+ * Copyright Google LLC 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 {coerceNumberProperty, NumberInput} from '@angular/cdk/coercion';
+import {Directive, Input} from '@angular/core';
+
+import {CdkSelection} from './selection';
+
+/**
+ * Applies `cdk-selected` class and `aria-selected` to an element.
+ *
+ * Must be used within a parent `CdkSelection` directive.
+ * Must be provided with the value. The index is required if `trackBy` is used on the `CdkSelection`
+ * directive.
+ */
+@Directive({
+  selector: '[cdkRowSelection]',
+  host: {
+    '[class.cdk-selected]': '_selection.isSelected(this.value, this.index)',
+    '[attr.aria-selected]': '_selection.isSelected(this.value, this.index)',
+  },
+})
+export class CdkRowSelection<T> {
+  @Input('cdkRowSelectionValue') value: T;
+
+  @Input('cdkRowSelectionIndex')
+  get index(): number|undefined { return this._index; }
+  set index(index: number|undefined) { this._index = coerceNumberProperty(index); }
+  private _index?: number;
+
+  constructor(readonly _selection: CdkSelection<T>) {}
+
+  static ngAcceptInputType_index: NumberInput;
+}

src/cdk-experimental/selection/select-all.ts

@@ -0,0 +1,106 @@
+/**
+ * @license
+ * Copyright Google LLC 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 {Directive, Inject, isDevMode, OnDestroy, OnInit, Optional, Self} from '@angular/core';
+import {ControlValueAccessor, NG_VALUE_ACCESSOR} from '@angular/forms';
+import {Observable, of as observableOf, Subject} from 'rxjs';
+import {switchMap, takeUntil} from 'rxjs/operators';
+
+import {CdkSelection} from './selection';
+
+/**
+ * Makes the element a select-all toggle.
+ *
+ * Must be used within a parent `CdkSelection` directive. It toggles the selection states
+ * of all the selection toggles connected with the `CdkSelection` directive.
+ * If the element implements `ControlValueAccessor`, e.g. `MatCheckbox`, the directive
+ * automatically connects it with the select-all state provided by the `CdkSelection` directive. If
+ * not, use `checked$` to get the checked state, `indeterminate$` to get the indeterminate state,
+ * and `toggle()` to change the selection state.
+ */
+@Directive({
+  selector: '[cdkSelectAll]',
+  exportAs: 'cdkSelectAll',
+})
+export class CdkSelectAll<T> implements OnDestroy, OnInit {
+  /**
+   * The checked state of the toggle.
+   * Resolves to `true` if all the values are selected, `false` if no value is selected.
+   */
+  readonly checked: Observable<boolean> = this._selection.change.pipe(
+      switchMap(() => observableOf(this._selection.isAllSelected())),
+  );
+
+  /**
+   * The indeterminate state of the toggle.
+   * Resolves to `true` if part (not all) of the values are selected, `false` if all values or no
+   * value at all are selected.
+   */
+  readonly indeterminate: Observable<boolean> = this._selection.change.pipe(
+      switchMap(() => observableOf(this._selection.isPartialSelected())),
+  );
+
+  /**
+   * Toggles the select-all state.
+   * @param event The click event if the toggle is triggered by a (mouse or keyboard) click. If
+   *     using with a native `<input type="checkbox">`, the parameter is required for the
+   *     indeterminate state to work properly.
+   */
+  toggle(event?: MouseEvent) {
+    // This is needed when applying the directive on a native <input type="checkbox">
+    // checkbox. The default behavior needs to be prevented in order to support the indeterminate
+    // state. The timeout is also needed so the checkbox can show the latest state.
+    if (event) {
+      event.preventDefault();
+    }
+
+    setTimeout(() => {
+      this._selection.toggleSelectAll();
+    });
+  }
+
+  private readonly _destroyed = new Subject<void>();
+
+  constructor(
+      @Optional() private readonly _selection: CdkSelection<T>,
+      @Optional() @Self() @Inject(NG_VALUE_ACCESSOR) private readonly _controlValueAccessor:
+          ControlValueAccessor[]) {}
+
+  ngOnInit() {
+    this._assertValidParentSelection();
+    this._configureControlValueAccessor();
+  }
+
+  private _configureControlValueAccessor() {
+    if (this._controlValueAccessor && this._controlValueAccessor.length) {
+      this._controlValueAccessor[0].registerOnChange((e: unknown) => {
+        if (e === true || e === false) {
+          this.toggle();
+        }
+      });
+      this.checked.pipe(takeUntil(this._destroyed)).subscribe((state) => {
+        this._controlValueAccessor[0].writeValue(state);
+      });
+    }
+  }
+
+  private _assertValidParentSelection() {
+    if (!this._selection && isDevMode()) {
+      throw Error('CdkSelectAll: missing CdkSelection in the parent');
+    }
+
+    if (!this._selection.multiple && isDevMode()) {
+      throw Error('CdkSelectAll: CdkSelection must have cdkSelectionMultiple set to true');
+    }
+  }
+
+  ngOnDestroy() {
+    this._destroyed.next();
+    this._destroyed.complete();
+  }
+}

src/cdk-experimental/selection/selection-column.ts

@@ -0,0 +1,107 @@
+/**
+ * @license
+ * Copyright Google LLC 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 {CdkCellDef, CdkColumnDef, CdkHeaderCellDef, CdkTable} from '@angular/cdk/table';
+import {
+  Component,
+  Input,
+  isDevMode,
+  OnDestroy,
+  OnInit,
+  Optional,
+  ViewChild,
+  ChangeDetectionStrategy,
+  ViewEncapsulation,
+} from '@angular/core';
+
+import {CdkSelection} from './selection';
+
+/**
+ * Column that adds row selecting checkboxes and a select-all checkbox if `cdkSelectionMultiple` is
+ * `true`.
+ *
+ * Must be used within a parent `CdkSelection` directive.
+ */
+@Component({
+  selector: 'cdk-selection-column',
+  template: `
+    <ng-container cdkColumnDef>
+      <th cdkHeaderCell *cdkHeaderCellDef>
+        <input type="checkbox" *ngIf="selection.multiple"
+            cdkSelectAll
+            #allToggler="cdkSelectAll"
+            [checked]="allToggler.checked | async"
+            [indeterminate]="allToggler.indeterminate | async"
+            (click)="allToggler.toggle($event)">
+      </th>
+      <td cdkCell *cdkCellDef="let row; let i = $index">
+        <input type="checkbox"
+            #toggler="cdkSelectionToggle"
+            cdkSelectionToggle
+            [cdkSelectionToggleValue]="row"
+            [cdkSelectionToggleIndex]="i"
+            (click)="toggler.toggle()"
+            [checked]="toggler.checked | async">
+      </td>
+    </ng-container>
+  `,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  encapsulation: ViewEncapsulation.None,
+})
+export class CdkSelectionColumn<T> implements OnInit, OnDestroy {
+  /** Column name that should be used to reference this column. */
+  @Input('cdkSelectionColumnName')
+  get name(): string {
+    return this._name;
+  }
+  set name(name: string) {
+    this._name = name;
+
+    this._syncColumnDefName();
+  }
+  private _name: string;
+
+  @ViewChild(CdkColumnDef, {static: true}) private readonly _columnDef: CdkColumnDef;
+  @ViewChild(CdkCellDef, {static: true}) private readonly _cell: CdkCellDef;
+  @ViewChild(CdkHeaderCellDef, {static: true}) private readonly _headerCell: CdkHeaderCellDef;
+
+  constructor(
+      @Optional() private _table: CdkTable<T>,
+      @Optional() readonly selection: CdkSelection<T>,
+  ) {}
+
+  ngOnInit() {
+    if (!this.selection && isDevMode()) {
+      throw Error('CdkSelectionColumn: missing CdkSelection in the parent');
+    }
+
+    this._syncColumnDefName();
+
+    if (this._table) {
+      this._columnDef.cell = this._cell;
+      this._columnDef.headerCell = this._headerCell;
+      this._table.addColumnDef(this._columnDef);
+    } else {
+      if (isDevMode()) {
+        throw Error('CdkSelectionColumn: missing parent table');
+      }
+    }
+  }
+
+  ngOnDestroy() {
+    if (this._table) {
+      this._table.removeColumnDef(this._columnDef);
+    }
+  }
+
+  private _syncColumnDefName() {
+    if (this._columnDef) {
+      this._columnDef.name = this._name;
+    }
+  }
+}

src/cdk-experimental/selection/selection-module.ts

@@ -0,0 +1,40 @@
+/**
+ * @license
+ * Copyright Google LLC 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 {CdkTableModule} from '@angular/cdk/table';
+import {CommonModule} from '@angular/common';
+import {NgModule} from '@angular/core';
+
+import {CdkRowSelection} from './row-selection';
+import {CdkSelectAll} from './select-all';
+import {CdkSelection} from './selection';
+import {CdkSelectionColumn} from './selection-column';
+import {CdkSelectionToggle} from './selection-toggle';
+
+@NgModule({
+  imports: [
+    CommonModule,
+    CdkTableModule,
+  ],
+  exports: [
+    CdkSelection,
+    CdkSelectionToggle,
+    CdkSelectAll,
+    CdkSelectionColumn,
+    CdkRowSelection,
+  ],
+  declarations: [
+    CdkSelection,
+    CdkSelectionToggle,
+    CdkSelectAll,
+    CdkSelectionColumn,
+    CdkRowSelection,
+  ],
+})
+export class CdkSelectionModule {
+}