fix(material/datepicker): screen reader not announcing view switch button value (#21229)

The button for switching between calendar views has an `aria-label` along the
lines of "Choose month" which overrides its default text. This means that the
user has no way of knowing what is inside the button.

These changes add a further `aria-describedby` pointing to the content which
lets the screen reader announce both pieces of text.

Note that an alternate approach is to concatenate the content into the `aria-label`,
but I don't know how well that would work in RTL languages.

Author: crisbeto

src/material/datepicker/calendar-header.html

@@ -2,10 +2,11 @@
   <div class="mat-calendar-controls">
     <button mat-button type="button" class="mat-calendar-period-button"
             (click)="currentPeriodClicked()" [attr.aria-label]="periodButtonLabel"
+            [attr.aria-describedby]="_buttonDescriptionId"
             cdkAriaLive="polite">
-      {{periodButtonText}}
+      <span [attr.id]="_buttonDescriptionId">{{periodButtonText}}</span>
       <div class="mat-calendar-arrow"
-           [class.mat-calendar-invert]="calendar.currentView != 'month'"></div>
+           [class.mat-calendar-invert]="calendar.currentView !== 'month'"></div>
     </button>
 
     <div class="mat-calendar-spacer"></div>

src/material/datepicker/calendar-header.spec.ts

@@ -203,6 +203,14 @@ describe('MatCalendarHeader', () => {
       expect(calendarInstance.currentView).toBe('multi-year');
       expect(periodButton.textContent).toContain('FAKE_YEAR');
     });
+
+    it('should label and describe period button for assistive technology', () => {
+      const description = periodButton.querySelector('span[id]');
+      expect(periodButton.hasAttribute('aria-label')).toBe(true);
+      expect(periodButton.hasAttribute('aria-describedby')).toBe(true);
+      expect(periodButton.getAttribute('aria-describedby')).toBe(description?.getAttribute('id')!);
+    });
+
   });
 
   describe('calendar with minDate only', () => {

src/material/datepicker/calendar.ts

@@ -50,6 +50,9 @@ import {MAT_SINGLE_DATE_SELECTION_MODEL_PROVIDER, DateRange} from './date-select
  */
 export type MatCalendarView = 'month' | 'year' | 'multi-year';
 
+/** Counter used to generate unique IDs. */
+let uniqueId = 0;
+
 /** Default header for MatCalendar */
 @Component({
   selector: 'mat-calendar-header',
@@ -59,6 +62,8 @@ export type MatCalendarView = 'month' | 'year' | 'multi-year';
   changeDetection: ChangeDetectionStrategy.OnPush,
 })
 export class MatCalendarHeader<D> {
+  _buttonDescriptionId = `mat-calendar-button-${uniqueId++}`;
+
   constructor(private _intl: MatDatepickerIntl,
               @Inject(forwardRef(() => MatCalendar)) public calendar: MatCalendar<D>,
               @Optional() private _dateAdapter: DateAdapter<D>,

tools/public_api_guard/material/datepicker.d.ts

@@ -156,6 +156,7 @@ export declare type MatCalendarCellCssClasses = string | string[] | Set<string>
 };
 
 export declare class MatCalendarHeader<D> {
+    _buttonDescriptionId: string;
     calendar: MatCalendar<D>;
     get nextButtonLabel(): string;
     get periodButtonLabel(): string;