fix(material/datepicker): add aria description to calendar body cells tocommunicate start or end of date range

Add 'Start of date range' aria description to first cell in selected
date range, and add 'End of date range' aria description to last cell in
selected date range. Fix accessibility issue where screen reader does
not communicate if the selected cell is the start date or the end date.

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,32 @@ 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].hasAttribute('aria-description')).toBe(true);
+      expect(cells[1].getAttribute('aria-description')).toBe('Start date');
+      expect(cells[3].hasAttribute('aria-description')).toBe(true);
+      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].hasAttribute('aria-description')).toBe(true);
+      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

@@ -21,6 +21,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 +152,11 @@ 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,
+    private _intl: MatDatepickerIntl,
+  ) {
     _ngZone.runOutsideAngular(() => {
       const element = _elementRef.nativeElement;
       element.addEventListener('mouseenter', this._enterHandler, true);
@@ -174,6 +179,25 @@ 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.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

@@ -51,6 +51,15 @@ export class MatDatepickerIntl {
   /** A label for the 'switch to year view' button (used by screen readers). */
   switchToMultiYearViewLabel: string = 'Choose month and year';
 
+  /** A label for the first date of a range of dates. */
+  startDateLabel: string = 'Start date';
+
+  /** A label for the last date of a range of dates. */
+  endDateLabel: string = 'End date';
+
+  /** A label for a date range that starts and ends on the same day. */
+  startAndEndDateLabel: string = 'Start and end date';
+
   /** Formats a range of years. */
   formatYearRange(start: string, end: string): string {
     return `${start} \u2013 ${end}`;