fix(material/datepicker): add aria descriptions to calendar for start/end dates

Add aria descriptions to calendar cells that are the first or last date
of a date range. Describe first date of a date range as 'Start date',
last date as 'End date'. Date ranges of exactly one day are described as
'Start and end date'. Fix accessibility issue where screen reader does
not communicate if the selected cell is the start date or the end date
(#23442).

Fixes #23442

Author: zarend

src/material/datepicker/calendar-body.html

@@ -60,6 +60,7 @@
         [class.mat-calendar-body-preview-end]="_isPreviewEnd(item.compareValue)"
         [class.mat-calendar-body-in-preview]="_isInPreview(item.compareValue)"
         [attr.aria-label]="item.ariaLabel"
+        [attr.aria-description]="_getAriaDescription(item.compareValue)"
         [attr.aria-disabled]="!item.enabled || null"
         [attr.aria-pressed]="_isSelected(item.compareValue)"
         [attr.aria-current]="todayValue === item.compareValue ? 'date' : null"

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

@@ -142,6 +142,13 @@ describe('MatCalendarBody', () => {
     it('should have a focus indicator', () => {
       expect(cellEls.every(element => !!element.querySelector('.mat-focus-indicator'))).toBe(true);
     });
+
+    it('should not have `aria-description` on cells', () => {
+      expect(
+        calendarBodyNativeElement.querySelectorAll('.mat-calendar-body-cell[aria-description]')
+          .length,
+      ).toBe(0);
+    });
   });
 
   describe('range calendar body', () => {
@@ -167,6 +174,29 @@ describe('MatCalendarBody', () => {
       cells = Array.from(fixture.nativeElement.querySelectorAll('.mat-calendar-body-cell'));
     });
 
+    it('should have aria-description on start and end days of a 3-day range', () => {
+      testComponent.startValue = 2;
+      testComponent.endValue = 4;
+      fixture.detectChanges();
+
+      expect(cells[1].getAttribute('aria-description')).toBe('Start date');
+      expect(cells[3].getAttribute('aria-description')).toBe('End date');
+      expect(
+        fixture.nativeElement.querySelectorAll('.mat-calendar-body-cell[aria-description]').length,
+      ).toBe(2);
+    });
+
+    it('should have aria-description on a cell that is both the first and last day of a date range', () => {
+      testComponent.startValue = 3;
+      testComponent.endValue = 3;
+      fixture.detectChanges();
+
+      expect(cells[2].getAttribute('aria-description')).toBe('Start and end date');
+      expect(
+        fixture.nativeElement.querySelectorAll('.mat-calendar-body-cell[aria-description]').length,
+      ).toBe(1);
+    });
+
     it('should render a range', () => {
       testComponent.startValue = 1;
       testComponent.endValue = 5;

src/material/datepicker/calendar-body.ts

@@ -7,6 +7,8 @@
  */
 
 import {
+  Optional,
+  SkipSelf,
   ChangeDetectionStrategy,
   Component,
   ElementRef,
@@ -21,6 +23,7 @@ import {
   AfterViewChecked,
 } from '@angular/core';
 import {take} from 'rxjs/operators';
+import {MatDatepickerIntl} from './datepicker-intl';
 
 /** Extra CSS classes that can be associated with a calendar cell. */
 export type MatCalendarCellCssClasses = string | string[] | Set<string> | {[key: string]: any};
@@ -151,7 +154,17 @@ export class MatCalendarBody implements OnChanges, OnDestroy, AfterViewChecked {
   /** Width of an individual cell. */
   _cellWidth: string;
 
-  constructor(private _elementRef: ElementRef<HTMLElement>, private _ngZone: NgZone) {
+  constructor(
+    private _elementRef: ElementRef<HTMLElement>,
+    private _ngZone: NgZone,
+    /**
+     * @deprecated `_intl` parameter to become required
+     * @breaking-change 15.0.0
+     */
+    @Optional()
+    @SkipSelf()
+    private _intl: MatDatepickerIntl | null,
+  ) {
     _ngZone.runOutsideAngular(() => {
       const element = _elementRef.nativeElement;
       element.addEventListener('mouseenter', this._enterHandler, true);
@@ -174,6 +187,28 @@ export class MatCalendarBody implements OnChanges, OnDestroy, AfterViewChecked {
     }
   }
 
+  /**
+   * Provides an aria-description for the cell to communicate if it is the
+   * start or end of the selected date range.
+   */
+  _getAriaDescription(value: number): string | null {
+    if (!this.isRange) {
+      return null;
+    }
+    if (this._intl === null) {
+      return null;
+    }
+
+    if (this.startValue === value && this.endValue === value) {
+      return this._intl.startAndEndDateLabel;
+    } else if (this.startValue === value) {
+      return this._intl.startDateLabel;
+    } else if (this.endValue === value) {
+      return this._intl.endDateLabel;
+    }
+    return null;
+  }
+
   /** Returns whether a cell should be marked as selected. */
   _isSelected(value: number) {
     return this.startValue === value || this.endValue === value;

src/material/datepicker/datepicker-intl.ts

@@ -57,6 +57,9 @@ export class MatDatepickerIntl {
   /** A label for the last date of a range of dates (used by screen readers). */
   endDateLabel = 'End date';
 
+  /** A label for a date range that starts and ends on the same day (used by screen readers). */
+  startAndEndDateLabel = 'Start and end date';
+
   /** Formats a range of years (used for visuals). */
   formatYearRange(start: string, end: string): string {
     return `${start} \u2013 ${end}`;

tools/public_api_guard/material/datepicker.md

@@ -198,7 +198,8 @@ export class MatCalendar<D> implements AfterContentInit, AfterViewChecked, OnDes
 
 // @public
 export class MatCalendarBody implements OnChanges, OnDestroy, AfterViewChecked {
-    constructor(_elementRef: ElementRef<HTMLElement>, _ngZone: NgZone);
+    constructor(_elementRef: ElementRef<HTMLElement>, _ngZone: NgZone,
+    _intl: MatDatepickerIntl | null);
     activeCell: number;
     // (undocumented)
     readonly activeDateChange: EventEmitter<MatCalendarUserEvent<number>>;
@@ -213,6 +214,7 @@ export class MatCalendarBody implements OnChanges, OnDestroy, AfterViewChecked {
     endValue: number;
     _firstRowOffset: number;
     _focusActiveCell(movePreview?: boolean): void;
+    _getAriaDescription(value: number): string | null;
     _isActiveCell(rowIndex: number, colIndex: number): boolean;
     _isComparisonBridgeEnd(value: number, rowIndex: number, colIndex: number): boolean;
     _isComparisonBridgeStart(value: number, rowIndex: number, colIndex: number): boolean;
@@ -248,7 +250,7 @@ export class MatCalendarBody implements OnChanges, OnDestroy, AfterViewChecked {
     // (undocumented)
     static ɵcmp: i0.ɵɵComponentDeclaration<MatCalendarBody, "[mat-calendar-body]", ["matCalendarBody"], { "label": "label"; "rows": "rows"; "todayValue": "todayValue"; "startValue": "startValue"; "endValue": "endValue"; "labelMinRequiredCells": "labelMinRequiredCells"; "numCols": "numCols"; "activeCell": "activeCell"; "isRange": "isRange"; "cellAspectRatio": "cellAspectRatio"; "comparisonStart": "comparisonStart"; "comparisonEnd": "comparisonEnd"; "previewStart": "previewStart"; "previewEnd": "previewEnd"; }, { "selectedValueChange": "selectedValueChange"; "previewChange": "previewChange"; "activeDateChange": "activeDateChange"; }, never, never, false>;
     // (undocumented)
-    static ɵfac: i0.ɵɵFactoryDeclaration<MatCalendarBody, never>;
+    static ɵfac: i0.ɵɵFactoryDeclaration<MatCalendarBody, [null, null, { optional: true; skipSelf: true; }]>;
 }
 
 // @public
@@ -535,6 +537,7 @@ export class MatDatepickerIntl {
     prevMonthLabel: string;
     prevMultiYearLabel: string;
     prevYearLabel: string;
+    startAndEndDateLabel: string;
     startDateLabel: string;
     switchToMonthViewLabel: string;
     switchToMultiYearViewLabel: string;