fix(table): allow for a caption to be projected (#14965)

Fixes consumers not being allowed to project a caption into a CDK table.

Fixes #14948.

Author: crisbeto

src/cdk/table/table.spec.ts

@@ -327,6 +327,16 @@ describe('CdkTable', () => {
     ]);
   });
 
+  it('should be able to project a caption', fakeAsync(() => {
+    setupTableTestApp(NativeHtmlTableWithCaptionApp);
+    fixture.detectChanges();
+
+    const caption = tableElement.querySelector('caption');
+
+    expect(caption).toBeTruthy();
+    expect(tableElement.firstElementChild).toBe(caption);
+  }));
+
   describe('with different data inputs other than data source', () => {
     let baseData: TestData[] = [
       {a: 'a_1', b: 'b_1', c: 'c_1'},
@@ -2182,6 +2192,27 @@ class NativeHtmlTableApp {
   @ViewChild(CdkTable) table: CdkTable<TestData>;
 }
 
+@Component({
+  template: `
+    <table cdk-table [dataSource]="dataSource">
+      <caption>Very important data</caption>
+      <ng-container cdkColumnDef="column_a">
+        <th cdk-header-cell *cdkHeaderCellDef> Column A</th>
+        <td cdk-cell *cdkCellDef="let row"> {{row.a}}</td>
+      </ng-container>
+
+      <tr cdk-header-row *cdkHeaderRowDef="columnsToRender"></tr>
+      <tr cdk-row *cdkRowDef="let row; columns: columnsToRender" class="customRowClass"></tr>
+    </table>
+  `
+})
+class NativeHtmlTableWithCaptionApp {
+  dataSource: FakeDataSource | undefined = new FakeDataSource();
+  columnsToRender = ['column_a'];
+
+  @ViewChild(CdkTable) table: CdkTable<TestData>;
+}
+
 function getElements(element: Element, query: string): Element[] {
   return [].slice.call(element.querySelectorAll(query));
 }

src/cdk/table/table.ts

@@ -106,10 +106,15 @@ export class FooterRowOutlet implements RowOutlet {
  * material library.
  * @docs-private
  */
-export const CDK_TABLE_TEMPLATE = `
+export const CDK_TABLE_TEMPLATE =
+// Note that according to MDN, the `caption` element has to be projected as the **first** element
+// in the table. See https://developer.mozilla.org/en-US/docs/Web/HTML/Element/caption
+`
+  <ng-content select="caption"></ng-content>
   <ng-container headerRowOutlet></ng-container>
   <ng-container rowOutlet></ng-container>
-  <ng-container footerRowOutlet></ng-container>`;
+  <ng-container footerRowOutlet></ng-container>
+`;
 
 /**
  * Interface used to conveniently type the possible context interfaces for the render row.

tools/public_api_guard/cdk/table.d.ts

@@ -30,7 +30,7 @@ export declare type CanStickCtor = Constructor<CanStick>;
 
 export declare const CDK_ROW_TEMPLATE = "<ng-container cdkCellOutlet></ng-container>";
 
-export declare const CDK_TABLE_TEMPLATE = "\n  <ng-container headerRowOutlet></ng-container>\n  <ng-container rowOutlet></ng-container>\n  <ng-container footerRowOutlet></ng-container>";
+export declare const CDK_TABLE_TEMPLATE = "\n  <ng-content select=\"caption\"></ng-content>\n  <ng-container headerRowOutlet></ng-container>\n  <ng-container rowOutlet></ng-container>\n  <ng-container footerRowOutlet></ng-container>\n";
 
 export declare class CdkCell extends BaseCdkCell {
     constructor(columnDef: CdkColumnDef, elementRef: ElementRef);