fix(material/stepper): allow stepper to be labelled (#33137)

Fixes that users didn't have a way to label the stepper after we changed the internal roles.

Fixes #33130.

(cherry picked from commit cb9148d)

Author: crisbeto

goldens/material/stepper/index.api.md

@@ -114,6 +114,7 @@ export class MatStepper extends CdkStepper implements AfterViewInit, AfterConten
     readonly animationDone: EventEmitter<void>;
     get animationDuration(): string;
     set animationDuration(value: string);
+    ariaLabel: string | null;
     color: ThemePalette;
     disableRipple: boolean;
     // (undocumented)
@@ -136,7 +137,7 @@ export class MatStepper extends CdkStepper implements AfterViewInit, AfterConten
     readonly steps: QueryList<MatStep>;
     _steps: QueryList<MatStep>;
     // (undocumented)
-    static ɵcmp: i0.ɵɵComponentDeclaration<MatStepper, "mat-stepper, mat-vertical-stepper, mat-horizontal-stepper, [matStepper]", ["matStepper", "matVerticalStepper", "matHorizontalStepper"], { "disableRipple": { "alias": "disableRipple"; "required": false; }; "color": { "alias": "color"; "required": false; }; "labelPosition": { "alias": "labelPosition"; "required": false; }; "headerPosition": { "alias": "headerPosition"; "required": false; }; "headerPrefix": { "alias": "headerPrefix"; "required": false; "isSignal": true; }; "animationDuration": { "alias": "animationDuration"; "required": false; }; }, { "animationDone": "animationDone"; }, ["_steps", "_icons"], ["*"], true, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<MatStepper, "mat-stepper, mat-vertical-stepper, mat-horizontal-stepper, [matStepper]", ["matStepper", "matVerticalStepper", "matHorizontalStepper"], { "disableRipple": { "alias": "disableRipple"; "required": false; }; "color": { "alias": "color"; "required": false; }; "labelPosition": { "alias": "labelPosition"; "required": false; }; "headerPosition": { "alias": "headerPosition"; "required": false; }; "ariaLabel": { "alias": "aria-label"; "required": false; }; "headerPrefix": { "alias": "headerPrefix"; "required": false; "isSignal": true; }; "animationDuration": { "alias": "animationDuration"; "required": false; }; }, { "animationDone": "animationDone"; }, ["_steps", "_icons"], ["*"], true, never>;
     // (undocumented)
     static ɵfac: i0.ɵɵFactoryDeclaration<MatStepper, never>;
 }

src/material/stepper/stepper.html

@@ -55,8 +55,9 @@
             class="mat-vertical-content-container"
             [class.mat-stepper-vertical-line]="!$last"
             [class.mat-vertical-content-container-active]="selectedIndex === $index"
-            [attr.inert]="selectedIndex === $index ? null : ''">
-            <div 
+            [attr.inert]="selectedIndex === $index ? null : ''"
+            [attr.aria-label]="ariaLabel">
+            <div
               class="mat-vertical-stepper-content"
               role="region"
               [id]="_getStepContentId($index)"
@@ -105,10 +106,11 @@
 </ng-template>
 
 <ng-template #horizontalStepsTemplate let-steps="steps">
-  <div 
+  <div
     aria-orientation="horizontal"
-    class="mat-horizontal-stepper-header-container" 
-    role="tablist">
+    class="mat-horizontal-stepper-header-container"
+    role="tablist"
+    [attr.aria-label]="ariaLabel">
     @for (step of steps; track step) {
       <ng-container
         [ngTemplateOutlet]="stepTemplate"

src/material/stepper/stepper.spec.ts

@@ -1014,6 +1014,15 @@ describe('MatStepper', () => {
       expect(headers[2].classList.contains('mat-primary')).toBe(true);
       expect(headers[1].classList.contains('mat-accent')).toBe(true);
     });
+
+    it('should set an aria label on the content container', () => {
+      const fixture = createComponent(SimpleMatVerticalStepperApp);
+      fixture.componentInstance.ariaLabel.set('My Stepper');
+      fixture.detectChanges();
+
+      const container = fixture.nativeElement.querySelector('.mat-vertical-content-container');
+      expect(container.getAttribute('aria-label')).toBe('My Stepper');
+    });
   });
 
   describe('horizontal stepper', () => {
@@ -1214,6 +1223,17 @@ describe('MatStepper', () => {
 
       expect(stepperHost.classList).toContain('mat-stepper-header-position-bottom');
     });
+
+    it('should set an aria-label on the header container', () => {
+      const fixture = createComponent(SimpleMatHorizontalStepperApp);
+      fixture.componentInstance.ariaLabel.set('My Stepper');
+      fixture.detectChanges();
+
+      const container = fixture.nativeElement.querySelector(
+        '.mat-horizontal-stepper-header-container',
+      );
+      expect(container.getAttribute('aria-label')).toBe('My Stepper');
+    });
   });
 
   describe('linear stepper with valid step', () => {
@@ -1845,7 +1865,8 @@ class MatHorizontalStepperWithErrorsApp {
     <mat-stepper
       [disableRipple]="disableRipple()"
       [color]="stepperTheme()"
-      [headerPosition]="headerPosition()">
+      [headerPosition]="headerPosition()"
+      [aria-label]="ariaLabel()">
       <mat-step>
         <ng-template matStepLabel>Step 1</ng-template>
         Content 1
@@ -1876,6 +1897,7 @@ class MatHorizontalStepperWithErrorsApp {
 class SimpleMatHorizontalStepperApp {
   @ViewChild(MatStepper) stepper!: MatStepper;
   inputLabel = 'Step 3';
+  ariaLabel = signal<string | null>(null);
   disableRipple = signal(false);
   stepperTheme = signal<ThemePalette>(undefined);
   secondStepTheme = signal<ThemePalette>(undefined);
@@ -1884,7 +1906,7 @@ class SimpleMatHorizontalStepperApp {
 
 @Component({
   template: `
-    <mat-stepper orientation="vertical" [disableRipple]="disableRipple()" [color]="stepperTheme()">
+    <mat-stepper orientation="vertical" [disableRipple]="disableRipple()" [color]="stepperTheme()" [aria-label]="ariaLabel()">
       <mat-step>
         <ng-template matStepLabel>Step 1</ng-template>
         Content 1
@@ -1917,6 +1939,7 @@ class SimpleMatHorizontalStepperApp {
 class SimpleMatVerticalStepperApp {
   @ViewChild(MatStepper) stepper!: MatStepper;
   inputLabel = signal('Step 3');
+  ariaLabel = signal<string | null>(null);
   showStepTwo = signal(true);
   disableRipple = signal(false);
   stepperTheme = signal<ThemePalette>(undefined);

src/material/stepper/stepper.ts

@@ -188,6 +188,12 @@ export class MatStepper extends CdkStepper implements AfterViewInit, AfterConten
   @Input()
   headerPosition: 'top' | 'bottom' = 'top';
 
+  /**
+   * ARIA label for the stepper.
+   */
+  @Input('aria-label')
+  ariaLabel: string | null = null;
+
   /** The content prefix to use in the stepper header. */
   readonly headerPrefix = input<TemplateRef<unknown> | null>(null);