From 2b8194d5232a7bf6f697d730111240b356faed87 Mon Sep 17 00:00:00 2001
From: Ruslan Lekhman <lekhman112@gmail.com>
Date: Thu, 8 Oct 2026 01:48:27 -0600
Subject: [PATCH] fix(material/sort): show start direction as hover hint on
 unsorted headers

The hover hint arrow on an unsorted header used the table's active sort
direction instead of the direction the header would sort in when clicked
(its start direction).

close #33933

Signed-off-by: Ruslan Lekhman <lekhman112@gmail.com>
---
 goldens/material/sort/index.api.md |  1 +
 src/material/sort/sort-header.html |  4 ++--
 src/material/sort/sort-header.ts   |  9 +++++++++
 src/material/sort/sort.spec.ts     | 30 ++++++++++++++++++++++++++++++
 4 files changed, 42 insertions(+), 2 deletions(-)

diff --git a/goldens/material/sort/index.api.md b/goldens/material/sort/index.api.md
index 78aaf8ae73d4..e12711d38ed4 100644
--- a/goldens/material/sort/index.api.md
+++ b/goldens/material/sort/index.api.md
@@ -73,6 +73,7 @@ export class MatSortHeader implements MatSortable, OnDestroy, OnInit, AfterViewI
     disableClear: boolean;
     disabled: boolean;
     _getAriaSortAttribute(): "ascending" | "descending" | "none";
+    _getArrowDirection(): SortDirection;
     // (undocumented)
     _handleKeydown(event: KeyboardEvent): void;
     id: string;
diff --git a/src/material/sort/sort-header.html b/src/material/sort/sort-header.html
index 9cc1c26493a7..090dd526326a 100644
--- a/src/material/sort/sort-header.html
+++ b/src/material/sort/sort-header.html
@@ -11,8 +11,8 @@
 <div class="mat-sort-header-container mat-focus-indicator"
      [class.mat-sort-header-sorted]="_isSorted()"
      [class.mat-sort-header-position-before]="arrowPosition === 'before'"
-     [class.mat-sort-header-descending]="_sort.direction === 'desc'"
-     [class.mat-sort-header-ascending]="_sort.direction === 'asc'"
+     [class.mat-sort-header-descending]="_getArrowDirection() === 'desc'"
+     [class.mat-sort-header-ascending]="_getArrowDirection() === 'asc'"
      [class.mat-sort-header-recently-cleared-ascending]="_recentlyCleared() === 'asc'"
      [class.mat-sort-header-recently-cleared-descending]="_recentlyCleared() === 'desc'"
      [class.mat-sort-header-animations-disabled]="_animationsDisabled"
diff --git a/src/material/sort/sort-header.ts b/src/material/sort/sort-header.ts
index ec1ee5d15fb1..91ac1f715879 100644
--- a/src/material/sort/sort-header.ts
+++ b/src/material/sort/sort-header.ts
@@ -217,6 +217,15 @@ export class MatSortHeader implements MatSortable, OnDestroy, OnInit, AfterViewI
     return !this._isDisabled() || this._isSorted();
   }
 
+  /**
+   * Gets the direction the arrow should be pointing. If the header is sorted, the arrow
+   * points in the currently active sorted direction. Otherwise the arrow points in the
+   * direction the header would be sorted by if it was clicked (its start direction).
+   */
+  _getArrowDirection(): SortDirection {
+    return this._isSorted() ? this._sort.direction : this.start || this._sort.start;
+  }
+
   private _updateSortActionDescription(newDescription: string) {
     // We use AriaDescriber for the sort button instead of setting an `aria-label` because some
     // screen readers (notably VoiceOver) will read both the column header *and* the button's label
diff --git a/src/material/sort/sort.spec.ts b/src/material/sort/sort.spec.ts
index 48a0c7a62d4c..6333c74d6ab5 100644
--- a/src/material/sort/sort.spec.ts
+++ b/src/material/sort/sort.spec.ts
@@ -209,6 +209,36 @@ describe('MatSort', () => {
       expect(sortHeaderElement.getAttribute('aria-sort')).toBe('none');
     });
 
+    it('should show the start direction as hint for unsorted headers', () => {
+      // Sort defaultA descending so the table's active direction is `desc`.
+      component.sort('defaultA');
+      component.sort('defaultA');
+      fixture.detectChanges();
+      expect(component.matSort.active).toBe('defaultA');
+      expect(component.matSort.direction).toBe('desc');
+
+      // Sorted header follows the active direction.
+      const sortedContainer = fixture.nativeElement.querySelector(
+        '#defaultA .mat-sort-header-container',
+      );
+      expect(sortedContainer.classList.contains('mat-sort-header-descending')).toBe(true);
+      expect(sortedContainer.classList.contains('mat-sort-header-ascending')).toBe(false);
+
+      // Unsorted header with default start (`asc`) hints `asc`, not the table's `desc`.
+      const unsortedContainer = fixture.nativeElement.querySelector(
+        '#defaultB .mat-sort-header-container',
+      );
+      expect(unsortedContainer.classList.contains('mat-sort-header-ascending')).toBe(true);
+      expect(unsortedContainer.classList.contains('mat-sort-header-descending')).toBe(false);
+
+      // Unsorted header with `start="desc"` hints `desc`.
+      const descStartContainer = fixture.nativeElement.querySelector(
+        '#overrideStart .mat-sort-header-container',
+      );
+      expect(descStartContainer.classList.contains('mat-sort-header-descending')).toBe(true);
+      expect(descStartContainer.classList.contains('mat-sort-header-ascending')).toBe(false);
+    });
+
     it('should not render the arrow if sorting is disabled for that column', async () => {
       const sortHeaderElement = fixture.nativeElement.querySelector('#defaultA');