feat(material/stepper): add a prefix section to the horizontal stepper header

Adds a prefix section to the header of the horizontal stepper header.

Author: thompsond

src/material/stepper/stepper.html

@@ -11,19 +11,16 @@
 @switch (orientation) {
   @case ('horizontal') {
     <div class="mat-horizontal-stepper-wrapper">
-      <div 
-        aria-orientation="horizontal"
-        class="mat-horizontal-stepper-header-container" 
-        role="tablist">
-        @for (step of steps; track step) {
-          <ng-container
-            [ngTemplateOutlet]="stepTemplate"
-            [ngTemplateOutletContext]="{step}"/>
-          @if (!$last) {
-            <div class="mat-stepper-horizontal-line"></div>
-          }
-        }
-      </div>
+      @if (headerPrefix()) {
+        <div class="mat-horizontal-stepper-header-wrapper">
+          <ng-container [ngTemplateOutlet]="headerPrefix()"/>
+          <ng-container [ngTemplateOutlet]="horizontalStepsTemplate"
+            [ngTemplateOutletContext]="{steps}"/>
+        </div>
+      } @else {
+        <ng-container [ngTemplateOutlet]="horizontalStepsTemplate"
+          [ngTemplateOutletContext]="{steps}"/>
+      }
 
       <div class="mat-horizontal-content-container">
         @for (step of steps; track step) {
@@ -102,3 +99,19 @@
     [disableRipple]="disableRipple || !step.isNavigable()"
     [color]="step.color || color"/>
 </ng-template>
+
+<ng-template #horizontalStepsTemplate let-steps="steps">
+  <div 
+    aria-orientation="horizontal"
+    class="mat-horizontal-stepper-header-container" 
+    role="tablist">
+    @for (step of steps; track step) {
+      <ng-container
+        [ngTemplateOutlet]="stepTemplate"
+        [ngTemplateOutletContext]="{step}"/>
+      @if (!$last) {
+        <div class="mat-stepper-horizontal-line"></div>
+      }
+    }
+  </div>
+</ng-template>

src/material/stepper/stepper.scss

@@ -19,10 +19,16 @@ $fallbacks: m3-stepper.get-tokens();
   background: token-utils.slot(stepper-container-color, $fallbacks);
 }
 
+.mat-horizontal-stepper-header-wrapper {
+  align-items: center;
+  display: flex;
+}
+
 .mat-horizontal-stepper-header-container {
   white-space: nowrap;
   display: flex;
   align-items: center;
+  flex-grow: 1;
 
   .mat-stepper-label-position-bottom & {
     align-items: flex-start;

src/material/stepper/stepper.spec.ts

@@ -1561,6 +1561,27 @@ describe('MatStepper', () => {
       expect(fixture.componentInstance.index).toBe(0);
     });
   });
+
+  describe('stepper with header prefix', () => {
+    it('should render the prefix content before the header', () => {
+      const fixture = createComponent(HorizontalStepperWithHeaderPrefix);
+      fixture.detectChanges();
+
+      const stepperHeaderWrapper = fixture.nativeElement.querySelector(
+        '.mat-horizontal-stepper-header-wrapper',
+      );
+
+      expect(stepperHeaderWrapper.children.length).toBe(2);
+
+      const stepperHeaderWrapperChildrenTags = Array.from(
+        stepperHeaderWrapper.children as HTMLElement[],
+      ).map((child: HTMLElement) => child.tagName);
+      const stepperHeaderPrefix = stepperHeaderWrapper.children[0];
+
+      expect(stepperHeaderWrapperChildrenTags).toEqual(['H2', 'DIV']);
+      expect(stepperHeaderPrefix.textContent).toContain('This is a header prefix');
+    });
+  });
 });
 
 /** Asserts that keyboard interaction works correctly. */
@@ -2258,3 +2279,21 @@ class HorizontalStepperWithDelayedStep {
 class StepperWithTwoWayBindingOnSelectedIndex {
   index: number = 0;
 }
+
+@Component({
+  template: `
+    <mat-stepper [headerPrefix]="stepHeaderPrefix" linear>
+      <mat-step label="One"></mat-step>
+      <mat-step label="Two"></mat-step>
+      <mat-step label="Three"></mat-step>
+    </mat-stepper>
+
+    <ng-template #stepHeaderPrefix>
+      <h2>This is a header prefix</h2>
+    </ng-template>
+  `,
+  imports: [MatStepperModule],
+})
+class HorizontalStepperWithHeaderPrefix {
+  @ViewChild(MatStepper) stepper: MatStepper;
+}

src/material/stepper/stepper.ts

@@ -18,6 +18,7 @@ import {
   EventEmitter,
   inject,
   Input,
+  input,
   NgZone,
   OnDestroy,
   Output,
@@ -187,6 +188,12 @@ export class MatStepper extends CdkStepper implements AfterViewInit, AfterConten
   @Input()
   headerPosition: 'top' | 'bottom' = 'top';
 
+  /**
+   * The content prefix to use in the stepper header.
+   * Only applies in the `horizontal` orientation.
+   */
+  readonly headerPrefix = input<TemplateRef<unknown> | null>(null);
+
   /** Consumer-specified template-refs to be used to override the header icons. */
   _iconOverrides: Record<string, TemplateRef<MatStepperIconContext>> = {};