docs(material/datepicker): require communicating date format for a11y

zarend · zarend · commit 70181bbab91c · 2022-03-28T21:55:30.000Z
In the accessibility section of the datepicker documentation, require communicating the date format string (e.g. 'MM/DD/YYYY'). Update datepicker examples to show the date format string via `<mat-hint>` and use 'en-US' as the locale. This commit only changes examples and does not affect source code. Addresses #11127
diff --git a/src/components-examples/material/datepicker/date-range-picker-comparison/date-range-picker-comparison-example.html b/src/components-examples/material/datepicker/date-range-picker-comparison/date-range-picker-comparison-example.html
@@ -1,5 +1,6 @@
 <mat-form-field class="example-form-field" appearance="fill">
   <mat-label>First campaign</mat-label>
+  <mat-hint>MM/DD/YYYY – MM/DD/YYYY</mat-hint>
   <mat-date-range-input
     [formGroup]="campaignOne"
     [rangePicker]="campaignOnePicker"
@@ -14,6 +15,7 @@
 
 <mat-form-field class="example-form-field" appearance="fill">
   <mat-label>Second campaign</mat-label>
+  <mat-hint>MM/DD/YYYY – MM/DD/YYYY</mat-hint>
   <mat-date-range-input
     [formGroup]="campaignTwo"
     [rangePicker]="campaignTwoPicker"
diff --git a/src/components-examples/material/datepicker/date-range-picker-forms/date-range-picker-forms-example.html b/src/components-examples/material/datepicker/date-range-picker-forms/date-range-picker-forms-example.html
@@ -1,5 +1,6 @@
 <mat-form-field appearance="fill">
   <mat-label>Enter a date range</mat-label>
+  <mat-hint>MM/DD/YYYY – MM/DD/YYYY</mat-hint>
   <mat-date-range-input [formGroup]="range" [rangePicker]="picker">
     <input matStartDate formControlName="start" placeholder="Start date">
     <input matEndDate formControlName="end" placeholder="End date">
diff --git a/src/components-examples/material/datepicker/date-range-picker-overview/date-range-picker-overview-example.html b/src/components-examples/material/datepicker/date-range-picker-overview/date-range-picker-overview-example.html
@@ -1,5 +1,6 @@
 <mat-form-field appearance="fill">
   <mat-label>Enter a date range</mat-label>
+  <mat-hint>MM/DD/YYYY – MM/DD/YYYY</mat-hint>
   <mat-date-range-input [rangePicker]="picker">
     <input matStartDate placeholder="Start date">
     <input matEndDate placeholder="End date">
diff --git a/src/components-examples/material/datepicker/date-range-picker-selection-strategy/date-range-picker-selection-strategy-example.html b/src/components-examples/material/datepicker/date-range-picker-selection-strategy/date-range-picker-selection-strategy-example.html
@@ -1,5 +1,6 @@
 <mat-form-field appearance="fill">
   <mat-label>Enter a date range</mat-label>
+  <mat-hint>MM/DD/YYYY – MM/DD/YYYY</mat-hint>
   <mat-date-range-input [rangePicker]="picker">
     <input matStartDate placeholder="Start date">
     <input matEndDate placeholder="End date">
diff --git a/src/components-examples/material/datepicker/datepicker-actions/datepicker-actions-example.html b/src/components-examples/material/datepicker/datepicker-actions/datepicker-actions-example.html
@@ -1,5 +1,6 @@
 <mat-form-field appearance="fill" class="example-form-field">
   <mat-label>Choose a date</mat-label>
+  <mat-hint>MM/DD/YYYY</mat-hint>
   <input matInput [matDatepicker]="datepicker">
   <mat-datepicker-toggle matSuffix [for]="datepicker"></mat-datepicker-toggle>
 <!-- #docregion datepicker-actions -->
@@ -14,6 +15,7 @@
 
 <mat-form-field appearance="fill" class="example-form-field">
   <mat-label>Enter a date range</mat-label>
+  <mat-hint>MM/DD/YYYY – MM/DD/YYYY</mat-hint>
   <mat-date-range-input [rangePicker]="rangePicker">
     <input matStartDate placeholder="Start date">
     <input matEndDate placeholder="End date">
diff --git a/src/components-examples/material/datepicker/datepicker-api/datepicker-api-example.html b/src/components-examples/material/datepicker/datepicker-api/datepicker-api-example.html
@@ -1,5 +1,6 @@
 <mat-form-field class="example-full-width" appearance="fill">
   <mat-label>Choose a date</mat-label>
+  <mat-hint>MM/DD/YYYY</mat-hint>
   <input matInput [matDatepicker]="picker">
   <mat-datepicker #picker></mat-datepicker>
 </mat-form-field>
diff --git a/src/components-examples/material/datepicker/datepicker-color/datepicker-color-example.html b/src/components-examples/material/datepicker/datepicker-color/datepicker-color-example.html
@@ -1,12 +1,14 @@
 <mat-form-field color="accent" appearance="fill">
   <mat-label>Inherited calendar color</mat-label>
+  <mat-hint>MM/DD/YYYY</mat-hint>
   <input matInput [matDatepicker]="picker1">
   <mat-datepicker-toggle matSuffix [for]="picker1"></mat-datepicker-toggle>
   <mat-datepicker #picker1></mat-datepicker>
 </mat-form-field>
 
 <mat-form-field color="accent" appearance="fill">
   <mat-label>Custom calendar color</mat-label>
+  <mat-hint>MM/DD/YYYY</mat-hint>
   <input matInput [matDatepicker]="picker2">
   <mat-datepicker-toggle matSuffix [for]="picker2"></mat-datepicker-toggle>
   <mat-datepicker #picker2 color="primary"></mat-datepicker>
diff --git a/src/components-examples/material/datepicker/datepicker-custom-header/datepicker-custom-header-example.html b/src/components-examples/material/datepicker/datepicker-custom-header/datepicker-custom-header-example.html
@@ -1,5 +1,6 @@
 <mat-form-field appearance="fill">
   <mat-label>Custom calendar header</mat-label>
+  <mat-hint>MM/DD/YYYY</mat-hint>
   <input matInput [matDatepicker]="picker">
   <mat-datepicker-toggle matSuffix [for]="picker"></mat-datepicker-toggle>
   <mat-datepicker #picker [calendarHeaderComponent]="exampleHeader"></mat-datepicker>
diff --git a/src/components-examples/material/datepicker/datepicker-custom-icon/datepicker-custom-icon-example.html b/src/components-examples/material/datepicker/datepicker-custom-icon/datepicker-custom-icon-example.html
@@ -1,5 +1,6 @@
 <mat-form-field class="example-full-width" appearance="fill">
   <mat-label>Choose a date</mat-label>
+  <mat-hint>MM/DD/YYYY</mat-hint>
   <input matInput [matDatepicker]="picker">
   <mat-datepicker-toggle matSuffix [for]="picker">
     <mat-icon matDatepickerToggleIcon>keyboard_arrow_down</mat-icon>
diff --git a/src/components-examples/material/datepicker/datepicker-date-class/datepicker-date-class-example.html b/src/components-examples/material/datepicker/datepicker-date-class/datepicker-date-class-example.html
@@ -1,5 +1,6 @@
 <mat-form-field class="example-full-width" appearance="fill">
   <mat-label>Choose a date</mat-label>
+  <mat-hint>MM/DD/YYYY</mat-hint>
   <input matInput [matDatepicker]="picker">
   <mat-datepicker-toggle matSuffix [for]="picker"></mat-datepicker-toggle>
   <mat-datepicker [dateClass]="dateClass" #picker></mat-datepicker>
diff --git a/src/components-examples/material/datepicker/datepicker-disabled/datepicker-disabled-example.html b/src/components-examples/material/datepicker/datepicker-disabled/datepicker-disabled-example.html
@@ -1,6 +1,7 @@
 <p>
   <mat-form-field appearance="fill">
     <mat-label>Completely disabled</mat-label>
+    <mat-hint>MM/DD/YYYY</mat-hint>
     <input matInput [matDatepicker]="dp1" disabled>
     <mat-datepicker-toggle matSuffix [for]="dp1"></mat-datepicker-toggle>
     <mat-datepicker #dp1></mat-datepicker>
@@ -10,6 +11,7 @@
 <p>
   <mat-form-field appearance="fill">
     <mat-label>Popup disabled</mat-label>
+    <mat-hint>MM/DD/YYYY</mat-hint>
     <input matInput [matDatepicker]="dp2">
     <mat-datepicker-toggle matSuffix [for]="dp2" disabled></mat-datepicker-toggle>
     <mat-datepicker #dp2></mat-datepicker>
@@ -19,6 +21,7 @@
 <p>
   <mat-form-field appearance="fill">
     <mat-label>Input disabled</mat-label>
+    <mat-hint>MM/DD/YYYY</mat-hint>
     <input matInput [matDatepicker]="dp3" disabled>
     <mat-datepicker-toggle matSuffix [for]="dp3"></mat-datepicker-toggle>
     <mat-datepicker #dp3 disabled="false"></mat-datepicker>
diff --git a/src/components-examples/material/datepicker/datepicker-events/datepicker-events-example.html b/src/components-examples/material/datepicker/datepicker-events/datepicker-events-example.html
@@ -1,5 +1,6 @@
 <mat-form-field appearance="fill">
   <mat-label>Input & change events</mat-label>
+  <mat-hint>MM/DD/YYYY</mat-hint>
   <input matInput [matDatepicker]="picker"
          (dateInput)="addEvent('input', $event)" (dateChange)="addEvent('change', $event)">
   <mat-datepicker-toggle matSuffix [for]="picker"></mat-datepicker-toggle>
diff --git a/src/components-examples/material/datepicker/datepicker-filter/datepicker-filter-example.html b/src/components-examples/material/datepicker/datepicker-filter/datepicker-filter-example.html
@@ -1,5 +1,6 @@
 <mat-form-field class="example-full-width" appearance="fill">
   <mat-label>Choose a date</mat-label>
+  <mat-hint>MM/DD/YYYY</mat-hint>
   <input matInput [matDatepickerFilter]="myFilter" [matDatepicker]="picker">
   <mat-datepicker-toggle matSuffix [for]="picker"></mat-datepicker-toggle>
   <mat-datepicker #picker></mat-datepicker>
diff --git a/src/components-examples/material/datepicker/datepicker-formats/datepicker-formats-example.html b/src/components-examples/material/datepicker/datepicker-formats/datepicker-formats-example.html
@@ -1,5 +1,6 @@
 <mat-form-field appearance="fill">
   <mat-label>Verbose datepicker</mat-label>
+  <mat-hint>MMMM DD, YYYY</mat-hint>
   <input matInput [matDatepicker]="dp" [formControl]="date">
   <mat-datepicker-toggle matSuffix [for]="dp"></mat-datepicker-toggle>
   <mat-datepicker #dp></mat-datepicker>
diff --git a/src/components-examples/material/datepicker/datepicker-locale/datepicker-locale-example.html b/src/components-examples/material/datepicker/datepicker-locale/datepicker-locale-example.html
@@ -1,8 +1,8 @@
 <mat-form-field appearance="fill">
+  <mat-hint>{{getDateFormatString()}}</mat-hint>
   <mat-label>Different locale</mat-label>
   <input matInput [matDatepicker]="dp">
   <mat-datepicker-toggle matSuffix [for]="dp"></mat-datepicker-toggle>
   <mat-datepicker #dp></mat-datepicker>
 </mat-form-field>
-
 <button mat-button (click)="french()">Dynamically switch to French</button>
diff --git a/src/components-examples/material/datepicker/datepicker-locale/datepicker-locale-example.ts b/src/components-examples/material/datepicker/datepicker-locale/datepicker-locale-example.ts
@@ -1,4 +1,4 @@
-import {Component} from '@angular/core';
+import {Component, Inject} from '@angular/core';
 import {
   MAT_MOMENT_DATE_FORMATS,
   MomentDateAdapter,
@@ -30,9 +30,22 @@ import 'moment/locale/fr';
   ],
 })
 export class DatepickerLocaleExample {
-  constructor(private _adapter: DateAdapter<any>) {}
+  constructor(
+    private _adapter: DateAdapter<any>,
+    @Inject(MAT_DATE_LOCALE) private _locale: string,
+  ) {}
 
   french() {
-    this._adapter.setLocale('fr');
+    this._locale = 'fr';
+    this._adapter.setLocale(this._locale);
+  }
+
+  getDateFormatString(): string {
+    if (this._locale === 'ja-JP') {
+      return 'YYYY/MM/DD';
+    } else if (this._locale === 'fr') {
+      return 'DD/MM/YYYY';
+    }
+    return '';
   }
 }
diff --git a/src/components-examples/material/datepicker/datepicker-min-max/datepicker-min-max-example.html b/src/components-examples/material/datepicker/datepicker-min-max/datepicker-min-max-example.html
@@ -1,5 +1,6 @@
 <mat-form-field class="example-full-width" appearance="fill">
   <mat-label>Choose a date</mat-label>
+  <mat-hint>MM/DD/YYYY</mat-hint>
   <input matInput [min]="minDate" [max]="maxDate" [matDatepicker]="picker">
   <mat-datepicker-toggle matSuffix [for]="picker"></mat-datepicker-toggle>
   <mat-datepicker #picker></mat-datepicker>
diff --git a/src/components-examples/material/datepicker/datepicker-moment/datepicker-moment-example.html b/src/components-examples/material/datepicker/datepicker-moment/datepicker-moment-example.html
@@ -1,5 +1,6 @@
 <mat-form-field appearance="fill">
   <mat-label>Moment.js datepicker</mat-label>
+  <mat-hint>MM/DD/YYYY</mat-hint>
   <input matInput [matDatepicker]="dp" [formControl]="date">
   <mat-datepicker-toggle matSuffix [for]="dp"></mat-datepicker-toggle>
   <mat-datepicker #dp></mat-datepicker>
diff --git a/src/components-examples/material/datepicker/datepicker-overview/datepicker-overview-example.html b/src/components-examples/material/datepicker/datepicker-overview/datepicker-overview-example.html
@@ -1,5 +1,6 @@
 <mat-form-field appearance="fill">
   <mat-label>Choose a date</mat-label>
+  <mat-hint>MM/DD/YYYY</mat-hint>
 <!-- #docregion toggle -->
   <input matInput [matDatepicker]="picker">
   <mat-datepicker-toggle matSuffix [for]="picker"></mat-datepicker-toggle>
diff --git a/src/components-examples/material/datepicker/datepicker-start-view/datepicker-start-view-example.html b/src/components-examples/material/datepicker/datepicker-start-view/datepicker-start-view-example.html
@@ -1,5 +1,6 @@
 <mat-form-field appearance="fill">
   <mat-label>Choose a date</mat-label>
+  <mat-hint>MM/DD/YYYY</mat-hint>
   <input matInput [matDatepicker]="picker">
   <mat-datepicker-toggle matSuffix [for]="picker"></mat-datepicker-toggle>
   <mat-datepicker #picker startView="year" [startAt]="startDate"></mat-datepicker>
diff --git a/src/components-examples/material/datepicker/datepicker-touch/datepicker-touch-example.html b/src/components-examples/material/datepicker/datepicker-touch/datepicker-touch-example.html
@@ -1,5 +1,6 @@
 <mat-form-field class="example-full-width" appearance="fill">
   <mat-label>Choose a date</mat-label>
+  <mat-hint>MM/DD/YYYY</mat-hint>
   <input matInput [matDatepicker]="picker">
   <mat-datepicker-toggle matSuffix [for]="picker"></mat-datepicker-toggle>
   <mat-datepicker touchUi #picker></mat-datepicker>
diff --git a/src/components-examples/material/datepicker/datepicker-value/datepicker-value-example.html b/src/components-examples/material/datepicker/datepicker-value/datepicker-value-example.html
@@ -1,12 +1,14 @@
 <mat-form-field appearance="fill">
   <mat-label>Angular forms</mat-label>
+  <mat-hint>MM/DD/YYYY</mat-hint>
   <input matInput [matDatepicker]="picker1" [formControl]="date">
   <mat-datepicker-toggle matSuffix [for]="picker1"></mat-datepicker-toggle>
   <mat-datepicker #picker1></mat-datepicker>
 </mat-form-field>
 
 <mat-form-field appearance="fill">
   <mat-label>Angular forms (w/ deserialization)</mat-label>
+  <mat-hint>MM/DD/YYYY</mat-hint>
   <input matInput [matDatepicker]="picker2"
          [formControl]="serializedDate">
   <mat-datepicker-toggle matSuffix [for]="picker2"></mat-datepicker-toggle>
@@ -15,6 +17,7 @@
 
 <mat-form-field appearance="fill">
   <mat-label>Value binding</mat-label>
+  <mat-hint>MM/DD/YYYY</mat-hint>
   <input matInput [matDatepicker]="picker3" [value]="date.value">
   <mat-datepicker-toggle matSuffix [for]="picker3"></mat-datepicker-toggle>
   <mat-datepicker #picker3></mat-datepicker>
diff --git a/src/components-examples/material/datepicker/datepicker-views-selection/datepicker-views-selection-example.html b/src/components-examples/material/datepicker/datepicker-views-selection/datepicker-views-selection-example.html
@@ -1,5 +1,6 @@
 <mat-form-field appearance="fill">
   <mat-label>Month and Year</mat-label>
+  <mat-hint>MM/YYYY</mat-hint>
   <input matInput [matDatepicker]="dp" [formControl]="date">
   <mat-datepicker-toggle matSuffix [for]="dp"></mat-datepicker-toggle>
   <mat-datepicker #dp
diff --git a/src/components-examples/material/datepicker/index.ts b/src/components-examples/material/datepicker/index.ts
@@ -3,7 +3,7 @@ import {NgModule} from '@angular/core';
 import {FormsModule, ReactiveFormsModule} from '@angular/forms';
 import {MatButtonModule} from '@angular/material/button';
 import {MatCardModule} from '@angular/material/card';
-import {MatNativeDateModule} from '@angular/material/core';
+import {MatNativeDateModule, MAT_DATE_LOCALE} from '@angular/material/core';
 import {MatDatepickerModule} from '@angular/material/datepicker';
 import {MatIconModule} from '@angular/material/icon';
 import {MatInputModule} from '@angular/material/input';
@@ -106,5 +106,11 @@ const EXAMPLES = [
   ],
   declarations: EXAMPLES,
   exports: EXAMPLES,
+  providers: [
+    // Except in specific examples, use 'en-US' locale in datepicker examples. This ensures that
+    // the hardcoded date format strings displayed in `<mat-hint>` will match the format used by
+    // `NativeDateModule`.
+    {provide: MAT_DATE_LOCALE, useValue: 'en-US'},
+  ],
 })
 export class DatepickerExamplesModule {}
diff --git a/src/material/datepicker/datepicker.md b/src/material/datepicker/datepicker.md
@@ -581,6 +581,8 @@ attribute to the native input and button elements, respectively.
 the datepicker text input a meaningful label via `<mat-label>`, `aria-label`, `aria-labelledby` or
 `MatDatepickerIntl`.
 
+Always communicate the date format (e.g. 'MM/DD/YYYY'). This can be accomplished using `<mat-hint>`.
+
 `MatDatepickerInput` adds <kbd>>Alt</kbd> + <kbd>Down Arrow</kbd> as a keyboard short to open the
 datepicker pop-up. However, ChromeOS intercepts this key combination at the OS level such that the
 browser only receives a `PageDown` key event. Because of this behavior, you should always include an
