docs: add example for using ripples within table (#22797)

* docs: add example for using ripples within table

(cherry picked from commit d7e2109)

Author: devversion

src/components-examples/material/table/BUILD.bazel

@@ -21,6 +21,7 @@ ng_module(
         "//src/material/button",
         "//src/material/button-toggle",
         "//src/material/checkbox",
+        "//src/material/core",
         "//src/material/icon",
         "//src/material/input",
         "//src/material/paginator",

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

@@ -1,5 +1,6 @@
 import {CommonModule} from '@angular/common';
 import {NgModule} from '@angular/core';
+import {MatRippleModule} from '@angular/material/core';
 import {MatButtonModule} from '@angular/material/button';
 import {MatButtonToggleModule} from '@angular/material/button-toggle';
 import {MatCheckboxModule} from '@angular/material/checkbox';
@@ -42,6 +43,7 @@ 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 {TableWithRipplesExample} from './table-with-ripples/table-with-ripples-example';
 import {TableColumnStylingExample} from './table-column-styling/table-column-styling-example';
 import {TableRowBindingExample} from './table-row-binding/table-row-binding-example';
 
@@ -59,7 +61,7 @@ export {
   TableWrappedExample,        WrapperTable,
   TableReorderableExample,    TableRecycleRowsExample,
   TableHarnessExample,        TableColumnStylingExample,
-  TableRowBindingExample
+  TableRowBindingExample,     TableWithRipplesExample,
 };
 
 const EXAMPLES = [
@@ -76,7 +78,7 @@ const EXAMPLES = [
   TableWrappedExample,        WrapperTable,
   TableReorderableExample,    TableRecycleRowsExample,
   TableHarnessExample,        TableColumnStylingExample,
-  TableRowBindingExample
+  TableRowBindingExample,     TableWithRipplesExample,
 ];
 
 @NgModule({
@@ -89,6 +91,7 @@ const EXAMPLES = [
     MatInputModule,
     MatPaginatorModule,
     MatProgressSpinnerModule,
+    MatRippleModule,
     MatSortModule,
     MatTableModule,
     CdkTableModule,

src/components-examples/material/table/table-with-ripples/table-with-ripples-example.css

@@ -0,0 +1,9 @@
+<mat-table [dataSource]="dataSource" class="mat-elevation-z8">
+  <ng-container matColumnDef="name">
+    <mat-header-cell mat-header-cell *matHeaderCellDef> Name </mat-header-cell>
+    <mat-cell mat-cell *matCellDef="let element"> {{element.name}} </mat-cell>
+  </ng-container>
+
+  <mat-header-row *matHeaderRowDef="displayedColumns"></mat-header-row>
+  <mat-row matRipple *matRowDef="let row; columns: displayedColumns;"></mat-row>
+</mat-table>

src/components-examples/material/table/table-with-ripples/table-with-ripples-example.html

@@ -0,0 +1,27 @@
+import {Component} from '@angular/core';
+
+const ELEMENT_DATA = [
+  {name: 'Hydrogen'},
+  {name: 'Helium'},
+  {name: 'Lithium'},
+  {name: 'Beryllium'},
+  {name: 'Boron'},
+  {name: 'Carbon'},
+  {name: 'Nitrogen'},
+  {name: 'Oxygen'},
+  {name: 'Fluorine'},
+  {name: 'Neon'},
+];
+
+/**
+ * @title Tables with Material Design ripples.
+ */
+@Component({
+  selector: 'table-with-ripples-example',
+  styleUrls: ['table-with-ripples-example.css'],
+  templateUrl: 'table-with-ripples-example.html',
+})
+export class TableWithRipplesExample {
+  displayedColumns: string[] = ['name'];
+  dataSource = ELEMENT_DATA;
+}

src/components-examples/material/table/table-with-ripples/table-with-ripples-example.ts

@@ -421,3 +421,15 @@ selectors. For example, `<table mat-table>` becomes `<mat-table>`; `<tr mat-row>
 
 Note that this approach means you cannot include certain native-table features such colspan/rowspan
 or have columns that resize themselves based on their content.
+
+### Tables with `MatRipple`
+
+By default, `MatTable` does not set up Material Design ripples for rows. A ripple effect can be
+added to table rows by using the `MatRipple` directive from `@angular/material/core`. Due to
+limitations in browsers, ripples cannot be applied native `th` or `tr` elements. The recommended
+approach for setting up ripples is using the non-native `display: flex` variant of `MatTable`.
+
+<!--- example(table-with-ripples) -->
+
+More details about ripples on native table rows and their limitations can be found [in this issue](https://github.com/angular/components/issues/11883#issuecomment-634942981).
+