fix(material/datepicker): add aria description to calendar body cells…

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;