feat(material/sort): add content projection slot for custom icon (#32016)

Adds the `matSortHeaderIcon` content projection slot that users can use to customize the sorting icon.

Fixes #32002.

Author: crisbeto

goldens/material/sort/index.api.md

@@ -113,7 +113,7 @@ export class MatSortHeader implements MatSortable, OnDestroy, OnInit, AfterViewI
     start: SortDirection;
     _toggleOnInteraction(): void;
     // (undocumented)
-    static ɵcmp: i0.ɵɵComponentDeclaration<MatSortHeader, "[mat-sort-header]", ["matSortHeader"], { "id": { "alias": "mat-sort-header"; "required": false; }; "arrowPosition": { "alias": "arrowPosition"; "required": false; }; "start": { "alias": "start"; "required": false; }; "disabled": { "alias": "disabled"; "required": false; }; "sortActionDescription": { "alias": "sortActionDescription"; "required": false; }; "disableClear": { "alias": "disableClear"; "required": false; }; }, {}, never, ["*"], true, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<MatSortHeader, "[mat-sort-header]", ["matSortHeader"], { "id": { "alias": "mat-sort-header"; "required": false; }; "arrowPosition": { "alias": "arrowPosition"; "required": false; }; "start": { "alias": "start"; "required": false; }; "disabled": { "alias": "disabled"; "required": false; }; "sortActionDescription": { "alias": "sortActionDescription"; "required": false; }; "disableClear": { "alias": "disableClear"; "required": false; }; }, {}, never, ["*", "[matSortHeaderIcon]"], true, never>;
     // (undocumented)
     static ɵfac: i0.ɵɵFactoryDeclaration<MatSortHeader, never>;
 }

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

@@ -18,6 +18,7 @@ ng_project(
         "//:node_modules/@types/jasmine",
         "//src/cdk/testing",
         "//src/cdk/testing/testbed",
+        "//src/material/icon",
         "//src/material/sort",
         "//src/material/sort/testing",
     ],

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

@@ -1,2 +1,3 @@
 export {SortOverviewExample} from './sort-overview/sort-overview-example';
 export {SortHarnessExample} from './sort-harness/sort-harness-example';
+export {SortCustomIconExample} from './sort-custom-icon/sort-custom-icon-example';

src/components-examples/material/sort/sort-custom-icon/sort-custom-icon-example.html

@@ -0,0 +1,19 @@
+<table matSort matSortActive="emoji" matSortDirection="asc">
+  <tr>
+    <th mat-sort-header="emoji">
+      Emoji icon
+      <span matSortHeaderIcon>⬆️</span>
+    </th>
+    <th mat-sort-header="material">
+      Material Icon
+      <mat-icon matSortHeaderIcon>keyboard_arrow_up</mat-icon>
+    </th>
+  </tr>
+
+  <tbody>
+    <tr>
+      <td>Lorem, ipsum dolor sit amet.</td>
+      <td>Lorem, ipsum dolor sit amet.</td>
+    </tr>
+  </tbody>
+</table>

src/components-examples/material/sort/sort-custom-icon/sort-custom-icon-example.ts

@@ -0,0 +1,13 @@
+import {Component} from '@angular/core';
+import {MatIcon} from '@angular/material/icon';
+import {MatSortModule} from '@angular/material/sort';
+
+/**
+ * @title Sort header with a custom icon
+ */
+@Component({
+  selector: 'sort-custom-icon-example',
+  templateUrl: 'sort-custom-icon-example.html',
+  imports: [MatSortModule, MatIcon],
+})
+export class SortCustomIconExample {}

src/material/sort/sort-header.html

@@ -32,9 +32,11 @@
   <!-- Disable animations while a current animation is running -->
   @if (_renderArrow()) {
     <div class="mat-sort-header-arrow">
-      <svg viewBox="0 -960 960 960" focusable="false" aria-hidden="true">
-        <path d="M440-240v-368L296-464l-56-56 240-240 240 240-56 56-144-144v368h-80Z"/>
-      </svg>
+      <ng-content select="[matSortHeaderIcon]">
+        <svg viewBox="0 -960 960 960" focusable="false" aria-hidden="true">
+          <path d="M440-240v-368L296-464l-56-56 240-240 240 240-56 56-144-144v368h-80Z"/>
+        </svg>
+      </ng-content>
     </div>
   }
 </div>

src/material/sort/sort-header.scss

@@ -114,7 +114,7 @@ $fallbacks: m3-sort.get-tokens();
     animation-duration: 0ms;
   }
 
-  svg {
+  > svg, [matSortHeaderIcon] {
     // Even though this is 24x24, the actual `path` inside ends up being 12x12.
     width: 24px;
     height: 24px;

src/material/sort/sort.md

@@ -39,6 +39,13 @@ by default it will use the id of the column.
 
 <!-- example(table-sorting) -->
 
+#### Customizing the icon
+
+You can set your own icon for a `mat-sort-header` by projecting in an element with the
+`matSortHeaderIcon` attribute.
+
+<!-- example(sort-custom-icon) -->
+
 ### Accessibility
 
 When you apply `MatSortHeader` to a header cell element, the component wraps the content of the
@@ -55,4 +62,4 @@ remedy this, use the `matSortChange` event on the `MatSort` directive to announc
 updates with the `LiveAnnouncer` service from `@angular/cdk/a11y`.
 
 If your application contains many tables and sort headers, consider creating a custom
-directives to consistently apply `sortActionDescription` and announce sort state changes. 
+directives to consistently apply `sortActionDescription` and announce sort state changes.