docs(material/table): add docs on row/column styles and bindings (#22778)

* docs(material/table): add docs on row/column styles and bindings

* docs(material/table): fix CSS classname to match demo-

* docs(material/table): review

* docs(material/table): review2

* docs(material/table): use set

Author: andrewseguin

src/components-examples/material/table/index.ts

@@ -42,6 +42,8 @@ import {TableWrappedExample, WrapperTable} from './table-wrapped/table-wrapped-e
 import {TableReorderableExample} from './table-reorderable/table-reorderable-example';
 import {TableRecycleRowsExample} from './table-recycle-rows/table-recycle-rows-example';
 import {TableHarnessExample} from './table-harness/table-harness-example';
+import {TableColumnStylingExample} from './table-column-styling/table-column-styling-example';
+import {TableRowBindingExample} from './table-row-binding/table-row-binding-example';
 
 export {
   TableBasicExample,          TableFlexBasicExample,
@@ -56,7 +58,8 @@ export {
   TableTextColumnExample,     TableTextColumnAdvancedExample,
   TableWrappedExample,        WrapperTable,
   TableReorderableExample,    TableRecycleRowsExample,
-  TableHarnessExample,
+  TableHarnessExample,        TableColumnStylingExample,
+  TableRowBindingExample
 };
 
 const EXAMPLES = [
@@ -72,7 +75,8 @@ const EXAMPLES = [
   TableTextColumnExample,     TableTextColumnAdvancedExample,
   TableWrappedExample,        WrapperTable,
   TableReorderableExample,    TableRecycleRowsExample,
-  TableHarnessExample,
+  TableHarnessExample,        TableColumnStylingExample,
+  TableRowBindingExample
 ];
 
 @NgModule({

src/components-examples/material/table/table-column-styling/table-column-styling-example.css

@@ -0,0 +1,25 @@
+.demo-table {
+  width: 100%;
+}
+
+.mat-column-demo-position {
+  width: 32px;
+  border-right: 1px solid currentColor;
+  padding-right: 24px;
+  text-align: center;
+}
+
+.mat-column-demo-name {
+  padding-left: 16px;
+  font-size: 20px;
+}
+
+.mat-column-demo-weight {
+  font-style: italic;
+}
+
+.mat-column-demo-symbol {
+  width: 32px;
+  text-align: center;
+  font-weight: bold;
+}

src/components-examples/material/table/table-column-styling/table-column-styling-example.html

@@ -0,0 +1,29 @@
+<table mat-table [dataSource]="dataSource" class="mat-elevation-z8 demo-table">
+  <!-- Position Column -->
+  <ng-container matColumnDef="demo-position">
+    <th mat-header-cell *matHeaderCellDef> No. </th>
+    <td mat-cell *matCellDef="let element"> {{element.position}} </td>
+  </ng-container>
+
+  <!-- Name Column -->
+  <ng-container matColumnDef="demo-name">
+    <th mat-header-cell *matHeaderCellDef> Name </th>
+    <td mat-cell *matCellDef="let element"> {{element.name}} </td>
+  </ng-container>
+
+  <!-- Weight Column -->
+  <ng-container matColumnDef="demo-weight">
+    <th mat-header-cell *matHeaderCellDef> Weight </th>
+    <td mat-cell *matCellDef="let element"> {{element.weight}} </td>
+  </ng-container>
+
+  <!-- Symbol Column -->
+  <ng-container matColumnDef="demo-symbol">
+    <th mat-header-cell *matHeaderCellDef> Symbol </th>
+    <td mat-cell *matCellDef="let element"> {{element.symbol}} </td>
+  </ng-container>
+
+  <tr mat-header-row *matHeaderRowDef="displayedColumns"></tr>
+  <tr mat-row *matRowDef="let row; columns: displayedColumns;"></tr>
+</table>
+

src/components-examples/material/table/table-column-styling/table-column-styling-example.ts

@@ -0,0 +1,34 @@
+import {Component} from '@angular/core';
+
+export interface PeriodicElement {
+  name: string;
+  position: number;
+  weight: number;
+  symbol: string;
+}
+
+const ELEMENT_DATA: PeriodicElement[] = [
+  {position: 1, name: 'Hydrogen', weight: 1.0079, symbol: 'H'},
+  {position: 2, name: 'Helium', weight: 4.0026, symbol: 'He'},
+  {position: 3, name: 'Lithium', weight: 6.941, symbol: 'Li'},
+  {position: 4, name: 'Beryllium', weight: 9.0122, symbol: 'Be'},
+  {position: 5, name: 'Boron', weight: 10.811, symbol: 'B'},
+  {position: 6, name: 'Carbon', weight: 12.0107, symbol: 'C'},
+  {position: 7, name: 'Nitrogen', weight: 14.0067, symbol: 'N'},
+  {position: 8, name: 'Oxygen', weight: 15.9994, symbol: 'O'},
+  {position: 9, name: 'Fluorine', weight: 18.9984, symbol: 'F'},
+  {position: 10, name: 'Neon', weight: 20.1797, symbol: 'Ne'},
+];
+
+/**
+ * @title Styling columns using their auto-generated column names
+ */
+@Component({
+  selector: 'table-column-styling-example',
+  styleUrls: ['table-column-styling-example.css'],
+  templateUrl: 'table-column-styling-example.html',
+})
+export class TableColumnStylingExample {
+  displayedColumns: string[] = ['demo-position', 'demo-name', 'demo-weight', 'demo-symbol'];
+  dataSource = ELEMENT_DATA;
+}

src/components-examples/material/table/table-row-binding/table-row-binding-example.css

@@ -0,0 +1,17 @@
+.demo-table {
+  width: 100%;
+}
+
+.mat-row .mat-cell {
+  border-bottom: 1px solid transparent;
+  border-top: 1px solid transparent;
+  cursor: pointer;
+}
+
+.mat-row:hover .mat-cell {
+  border-color: currentColor;
+}
+
+.demo-row-is-clicked {
+  font-weight: bold;
+}

src/components-examples/material/table/table-row-binding/table-row-binding-example.html

@@ -0,0 +1,49 @@
+<table mat-table [dataSource]="dataSource" class="mat-elevation-z8 demo-table">
+  <!-- Position Column -->
+  <ng-container matColumnDef="position">
+    <th mat-header-cell *matHeaderCellDef>No.</th>
+    <td mat-cell *matCellDef="let element">{{element.position}}</td>
+  </ng-container>
+
+  <!-- Name Column -->
+  <ng-container matColumnDef="name">
+    <th mat-header-cell *matHeaderCellDef>Name</th>
+    <td mat-cell *matCellDef="let element">{{element.name}}</td>
+  </ng-container>
+
+  <!-- Weight Column -->
+  <ng-container matColumnDef="weight">
+    <th mat-header-cell *matHeaderCellDef>Weight</th>
+    <td mat-cell *matCellDef="let element">{{element.weight}}</td>
+  </ng-container>
+
+  <!-- Symbol Column -->
+  <ng-container matColumnDef="symbol">
+    <th mat-header-cell *matHeaderCellDef>Symbol</th>
+    <td mat-cell *matCellDef="let element">{{element.symbol}}</td>
+  </ng-container>
+
+  <tr mat-header-row *matHeaderRowDef="displayedColumns"></tr>
+  <tr
+      mat-row
+      (click)="clickedRows.add(row)"
+      [class.demo-row-is-clicked]="clickedRows.has(row)"
+      *matRowDef="let row; columns: displayedColumns;"
+  ></tr>
+</table>
+
+<div>
+  <h3>
+    Click Log
+  </h3>
+</div>
+
+<div *ngIf="!clickedRows.size">
+  Clicked rows will be logged here
+</div>
+
+<ul>
+  <li *ngFor="let clickedRow of clickedRows">
+    Clicked on {{clickedRow.name}}
+  </li>
+</ul>

src/components-examples/material/table/table-row-binding/table-row-binding-example.ts

@@ -0,0 +1,35 @@
+import {Component} from '@angular/core';
+
+export interface PeriodicElement {
+  name: string;
+  position: number;
+  weight: number;
+  symbol: string;
+}
+
+const ELEMENT_DATA: PeriodicElement[] = [
+  {position: 1, name: 'Hydrogen', weight: 1.0079, symbol: 'H'},
+  {position: 2, name: 'Helium', weight: 4.0026, symbol: 'He'},
+  {position: 3, name: 'Lithium', weight: 6.941, symbol: 'Li'},
+  {position: 4, name: 'Beryllium', weight: 9.0122, symbol: 'Be'},
+  {position: 5, name: 'Boron', weight: 10.811, symbol: 'B'},
+  {position: 6, name: 'Carbon', weight: 12.0107, symbol: 'C'},
+  {position: 7, name: 'Nitrogen', weight: 14.0067, symbol: 'N'},
+  {position: 8, name: 'Oxygen', weight: 15.9994, symbol: 'O'},
+  {position: 9, name: 'Fluorine', weight: 18.9984, symbol: 'F'},
+  {position: 10, name: 'Neon', weight: 20.1797, symbol: 'Ne'},
+];
+
+/**
+ * @title Binding event handlers and properties to the table rows.
+ */
+@Component({
+  selector: 'table-row-binding-example',
+  styleUrls: ['table-row-binding-example.css'],
+  templateUrl: 'table-row-binding-example.html',
+})
+export class TableRowBindingExample {
+  displayedColumns: string[] = ['position', 'name', 'weight', 'symbol'];
+  dataSource = ELEMENT_DATA;
+  clickedRows = new Set<PeriodicElement>();
+}

src/material/table/table.md

@@ -124,6 +124,21 @@ functionality by extending a different base class, the `DataSource` base class c
 implemented instead (`MyCustomDataSource extends SomeOtherBaseClass implements DataSource`) to
 respect Typescript's restriction to only implement one base class.
 
+### Styling Columns
+
+Each table cell has an automatically generated class based on which column it appears in. The format for this
+generated class is `mat-column-NAME`. For example, cells in a column named "symbol" can be targeted with the
+selector `.mat-column-symbol`.
+
+<!-- example(table-column-styling) -->
+
+### Row Templates
+
+Event handlers and property binding on the row templates will be applied to each row rendered by the table. For example,
+adding a `(click)` handler to the row template will cause each individual row to call the handler when clicked.
+
+<!-- example(table-row-binding) -->
+
 ### Features
 
 The `MatTable` is focused on a single responsibility: efficiently render rows of data in a