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

@@ -19,8 +19,11 @@ import {
   SimpleChanges,
   OnDestroy,
   AfterViewChecked,
+  inject,
+  InjectFlags,
 } 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};
@@ -80,6 +83,8 @@ export class MatCalendarBody implements OnChanges, OnDestroy, AfterViewChecked {
    */
   private _focusActiveCellAfterViewChecked = false;
 
+  private _intl = inject(MatDatepickerIntl, InjectFlags.Optional);
+
   /** The label for the table. (e.g. "Jan 2017"). */
   @Input() label: string;
 
@@ -174,6 +179,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) {
+      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

@@ -213,6 +213,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;
@@ -535,6 +536,7 @@ export class MatDatepickerIntl {
     prevMonthLabel: string;
     prevMultiYearLabel: string;
     prevYearLabel: string;
+    startAndEndDateLabel: string;
     startDateLabel: string;
     switchToMonthViewLabel: string;
     switchToMultiYearViewLabel: string;