fix(material/datepicker): add close button for screen readers (#20666)

Adds an invisible close button for screen reader users that becomes visible when the user tabs into it.

Fixes #14379.

Author: crisbeto

src/material/datepicker/datepicker-base.ts

@@ -64,6 +64,7 @@ import {
   MAT_DATE_RANGE_SELECTION_STRATEGY,
   MatDateRangeSelectionStrategy,
 } from './date-range-selection-strategy';
+import {MatDatepickerIntl} from './datepicker-intl';
 
 /** Used to generate a unique ID for each datepicker instance. */
 let datepickerUid = 0;
@@ -149,14 +150,27 @@ export class MatDatepickerContent<S, D = ExtractDateTypeFromSelection<S>>
   /** Emits when an animation has finished. */
   _animationDone = new Subject<void>();
 
+  /** Text for the close button. */
+  _closeButtonText: string;
+
+  /** Whether the close button currently has focus. */
+  _closeButtonFocused: boolean;
+
   constructor(
     elementRef: ElementRef,
     private _changeDetectorRef: ChangeDetectorRef,
     private _model: MatDateSelectionModel<S, D>,
     private _dateAdapter: DateAdapter<D>,
     @Optional() @Inject(MAT_DATE_RANGE_SELECTION_STRATEGY)
-        private _rangeSelectionStrategy: MatDateRangeSelectionStrategy<D>) {
+        private _rangeSelectionStrategy: MatDateRangeSelectionStrategy<D>,
+    /**
+     * @deprecated `intl` argument to become required.
+     * @breaking-change 12.0.0
+     */
+    intl?: MatDatepickerIntl) {
     super(elementRef);
+    // @breaking-change 12.0.0 Remove fallback for `intl`.
+    this._closeButtonText = intl?.closeCalendarLabel || 'Close calendar';
   }
 
   ngAfterViewInit() {

src/material/datepicker/datepicker-content.html

@@ -1,4 +1,5 @@
-<mat-calendar cdkTrapFocus
+<div cdkTrapFocus>
+  <mat-calendar
     [id]="datepicker.id"
     [ngClass]="datepicker.panelClass"
     [startAt]="datepicker.startAt"
@@ -15,5 +16,16 @@
     (yearSelected)="datepicker._selectYear($event)"
     (monthSelected)="datepicker._selectMonth($event)"
     (viewChanged)="datepicker._viewChanged($event)"
-    (_userSelection)="_handleUserSelection($event)">
-</mat-calendar>
+    (_userSelection)="_handleUserSelection($event)"></mat-calendar>
+
+  <!-- Invisible close button for screen reader users. -->
+  <button
+    type="button"
+    mat-raised-button
+    color="primary"
+    class="mat-datepicker-close-button"
+    [class.cdk-visually-hidden]="!_closeButtonFocused"
+    (focus)="_closeButtonFocused = true"
+    (blur)="_closeButtonFocused = false"
+    (click)="datepicker.close()">{{ _closeButtonText }}</button>
+</div>

src/material/datepicker/datepicker-content.scss

@@ -49,6 +49,13 @@ $mat-datepicker-touch-max-height: 788px;
   }
 }
 
+.mat-datepicker-close-button {
+  position: absolute;
+  top: 100%;
+  left: 0;
+  margin-top: 8px;
+}
+
 @media all and (orientation: landscape) {
   .mat-datepicker-content-touch .mat-calendar {
     width: $mat-datepicker-touch-landscape-width;

src/material/datepicker/datepicker-intl.ts

@@ -25,6 +25,9 @@ export class MatDatepickerIntl {
   /** A label for the button used to open the calendar popup (used by screen readers). */
   openCalendarLabel: string = 'Open calendar';
 
+  /** Label for the button used to close the calendar popup. */
+  closeCalendarLabel: string = 'Close calendar';
+
   /** A label for the previous month button (used by screen readers). */
   prevMonthLabel: string = 'Previous month';
 

src/material/datepicker/datepicker.spec.ts

@@ -501,6 +501,38 @@ describe('MatDatepicker', () => {
         expect(event.defaultPrevented).toBe(false);
       }));
 
+      it('should show the invisible close button on focus', fakeAsync(() => {
+        testComponent.opened = true;
+        fixture.detectChanges();
+        flush();
+
+        const button = document.querySelector('.mat-datepicker-close-button') as HTMLButtonElement;
+        expect(button.classList).toContain('cdk-visually-hidden');
+
+        dispatchFakeEvent(button, 'focus');
+        fixture.detectChanges();
+        expect(button.classList).not.toContain('cdk-visually-hidden');
+
+        dispatchFakeEvent(button, 'blur');
+        fixture.detectChanges();
+        expect(button.classList).toContain('cdk-visually-hidden');
+      }));
+
+      it('should close the overlay when clicking on the invisible close button', fakeAsync(() => {
+        testComponent.opened = true;
+        fixture.detectChanges();
+        flush();
+
+        const button = document.querySelector('.mat-datepicker-close-button') as HTMLButtonElement;
+        expect(document.querySelector('.mat-datepicker-content')).not.toBeNull();
+
+        button.click();
+        fixture.detectChanges();
+        flush();
+
+        expect(document.querySelector('.mat-datepicker-content')).toBeNull();
+      }));
+
     });
 
     describe('datepicker with too many inputs', () => {

tools/public_api_guard/material/datepicker.d.ts

@@ -192,18 +192,21 @@ export declare class MatDatepickerContent<S, D = ExtractDateTypeFromSelection<S>
     _animationDone: Subject<void>;
     _animationState: 'enter' | 'void';
     _calendar: MatCalendar<D>;
+    _closeButtonFocused: boolean;
+    _closeButtonText: string;
     _isAbove: boolean;
     comparisonEnd: D | null;
     comparisonStart: D | null;
     datepicker: MatDatepickerBase<any, S, D>;
-    constructor(elementRef: ElementRef, _changeDetectorRef: ChangeDetectorRef, _model: MatDateSelectionModel<S, D>, _dateAdapter: DateAdapter<D>, _rangeSelectionStrategy: MatDateRangeSelectionStrategy<D>);
+    constructor(elementRef: ElementRef, _changeDetectorRef: ChangeDetectorRef, _model: MatDateSelectionModel<S, D>, _dateAdapter: DateAdapter<D>, _rangeSelectionStrategy: MatDateRangeSelectionStrategy<D>,
+    intl?: MatDatepickerIntl);
     _getSelected(): D | DateRange<D> | null;
     _handleUserSelection(event: MatCalendarUserEvent<D | null>): void;
     _startExitAnimation(): void;
     ngAfterViewInit(): void;
     ngOnDestroy(): void;
     static ɵcmp: i0.ɵɵComponentDefWithMeta<MatDatepickerContent<any, any>, "mat-datepicker-content", ["matDatepickerContent"], { "color": "color"; }, {}, never, never>;
-    static ɵfac: i0.ɵɵFactoryDef<MatDatepickerContent<any, any>, [null, null, null, null, { optional: true; }]>;
+    static ɵfac: i0.ɵɵFactoryDef<MatDatepickerContent<any, any>, [null, null, null, null, { optional: true; }, null]>;
 }
 
 export declare class MatDatepickerInput<D> extends MatDatepickerInputBase<D | null, D> implements MatDatepickerControl<D | null> {
@@ -245,6 +248,7 @@ export declare class MatDatepickerInputEvent<D, S = unknown> {
 export declare class MatDatepickerIntl {
     calendarLabel: string;
     readonly changes: Subject<void>;
+    closeCalendarLabel: string;
     nextMonthLabel: string;
     nextMultiYearLabel: string;
     nextYearLabel: string;