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

zarend · web-flow · commit 6118b68358bc · 2022-04-08T15:43:46.000-07:00
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
@@ -8,6 +8,7 @@
     <input matStartDate placeholder="Start date" formControlName="start">
     <input matEndDate placeholder="End date" formControlName="end">
   </mat-date-range-input>
+  <mat-hint>MM/DD/YYYY – MM/DD/YYYY</mat-hint>
   <mat-datepicker-toggle matSuffix [for]="campaignOnePicker"></mat-datepicker-toggle>
   <mat-date-range-picker #campaignOnePicker></mat-date-range-picker>
 </mat-form-field>
@@ -23,5 +24,6 @@
     <input matEndDate placeholder="End date" formControlName="end">
   </mat-date-range-input>
   <mat-datepicker-toggle matSuffix [for]="campaignTwoPicker"></mat-datepicker-toggle>
+  <mat-hint>MM/DD/YYYY – MM/DD/YYYY</mat-hint>
   <mat-date-range-picker #campaignTwoPicker></mat-date-range-picker>
 </mat-form-field>
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
@@ -4,6 +4,7 @@
     <input matStartDate formControlName="start" placeholder="Start date">
     <input matEndDate formControlName="end" placeholder="End date">
   </mat-date-range-input>
+  <mat-hint>MM/DD/YYYY – MM/DD/YYYY</mat-hint>
   <mat-datepicker-toggle matSuffix [for]="picker"></mat-datepicker-toggle>
   <mat-date-range-picker #picker></mat-date-range-picker>
 
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
@@ -4,6 +4,7 @@
     <input matStartDate placeholder="Start date">
     <input matEndDate placeholder="End date">
   </mat-date-range-input>
+  <mat-hint>MM/DD/YYYY – MM/DD/YYYY</mat-hint>
   <mat-datepicker-toggle matSuffix [for]="picker"></mat-datepicker-toggle>
   <mat-date-range-picker #picker></mat-date-range-picker>
 </mat-form-field>
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
@@ -4,6 +4,7 @@
     <input matStartDate placeholder="Start date">
     <input matEndDate placeholder="End date">
   </mat-date-range-input>
+  <mat-hint>MM/DD/YYYY – MM/DD/YYYY</mat-hint>
   <mat-datepicker-toggle matSuffix [for]="picker"></mat-datepicker-toggle>
   <mat-date-range-picker #picker></mat-date-range-picker>
 </mat-form-field>
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,6 +1,7 @@
 <mat-form-field appearance="fill" class="example-form-field">
   <mat-label>Choose a date</mat-label>
   <input matInput [matDatepicker]="datepicker">
+  <mat-hint>MM/DD/YYYY</mat-hint>
   <mat-datepicker-toggle matSuffix [for]="datepicker"></mat-datepicker-toggle>
 <!-- #docregion datepicker-actions -->
   <mat-datepicker #datepicker>
@@ -18,6 +19,7 @@
     <input matStartDate placeholder="Start date">
     <input matEndDate placeholder="End date">
   </mat-date-range-input>
+  <mat-hint>MM/DD/YYYY – MM/DD/YYYY</mat-hint>
   <mat-datepicker-toggle matSuffix [for]="rangePicker"></mat-datepicker-toggle>
 <!-- #docregion date-range-picker-actions -->
   <mat-date-range-picker #rangePicker>
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,6 +1,7 @@
 <mat-form-field class="example-full-width" appearance="fill">
   <mat-label>Choose a date</mat-label>
   <input matInput [matDatepicker]="picker">
+  <mat-hint>MM/DD/YYYY</mat-hint>
   <mat-datepicker #picker></mat-datepicker>
 </mat-form-field>
 <button mat-raised-button (click)="picker.open()">Open</button>
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,13 +1,15 @@
 <mat-form-field color="accent" appearance="fill">
   <mat-label>Inherited calendar color</mat-label>
   <input matInput [matDatepicker]="picker1">
+  <mat-hint>MM/DD/YYYY</mat-hint>
   <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>
   <input matInput [matDatepicker]="picker2">
+  <mat-hint>MM/DD/YYYY</mat-hint>
   <mat-datepicker-toggle matSuffix [for]="picker2"></mat-datepicker-toggle>
   <mat-datepicker #picker2 color="primary"></mat-datepicker>
 </mat-form-field>
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,6 +1,7 @@
 <mat-form-field appearance="fill">
   <mat-label>Custom calendar header</mat-label>
   <input matInput [matDatepicker]="picker">
+  <mat-hint>MM/DD/YYYY</mat-hint>
   <mat-datepicker-toggle matSuffix [for]="picker"></mat-datepicker-toggle>
   <mat-datepicker #picker [calendarHeaderComponent]="exampleHeader"></mat-datepicker>
 </mat-form-field>
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,6 +1,7 @@
 <mat-form-field class="example-full-width" appearance="fill">
   <mat-label>Choose a date</mat-label>
   <input matInput [matDatepicker]="picker">
+  <mat-hint>MM/DD/YYYY</mat-hint>
   <mat-datepicker-toggle matSuffix [for]="picker">
     <mat-icon matDatepickerToggleIcon>keyboard_arrow_down</mat-icon>
   </mat-datepicker-toggle>
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,6 +1,7 @@
 <mat-form-field class="example-full-width" appearance="fill">
   <mat-label>Choose a date</mat-label>
   <input matInput [matDatepicker]="picker">
+  <mat-hint>MM/DD/YYYY</mat-hint>
   <mat-datepicker-toggle matSuffix [for]="picker"></mat-datepicker-toggle>
   <mat-datepicker [dateClass]="dateClass" #picker></mat-datepicker>
 </mat-form-field>
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
@@ -2,6 +2,7 @@
   <mat-form-field appearance="fill">
     <mat-label>Completely disabled</mat-label>
     <input matInput [matDatepicker]="dp1" disabled>
+    <mat-hint>MM/DD/YYYY</mat-hint>
     <mat-datepicker-toggle matSuffix [for]="dp1"></mat-datepicker-toggle>
     <mat-datepicker #dp1></mat-datepicker>
   </mat-form-field>
@@ -11,6 +12,7 @@
   <mat-form-field appearance="fill">
     <mat-label>Popup disabled</mat-label>
     <input matInput [matDatepicker]="dp2">
+    <mat-hint>MM/DD/YYYY</mat-hint>
     <mat-datepicker-toggle matSuffix [for]="dp2" disabled></mat-datepicker-toggle>
     <mat-datepicker #dp2></mat-datepicker>
   </mat-form-field>
@@ -20,6 +22,7 @@
   <mat-form-field appearance="fill">
     <mat-label>Input disabled</mat-label>
     <input matInput [matDatepicker]="dp3" disabled>
+    <mat-hint>MM/DD/YYYY</mat-hint>
     <mat-datepicker-toggle matSuffix [for]="dp3"></mat-datepicker-toggle>
     <mat-datepicker #dp3 disabled="false"></mat-datepicker>
   </mat-form-field>
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
@@ -2,6 +2,7 @@
   <mat-label>Input & change events</mat-label>
   <input matInput [matDatepicker]="picker"
          (dateInput)="addEvent('input', $event)" (dateChange)="addEvent('change', $event)">
+  <mat-hint>MM/DD/YYYY</mat-hint>
   <mat-datepicker-toggle matSuffix [for]="picker"></mat-datepicker-toggle>
   <mat-datepicker #picker></mat-datepicker>
 </mat-form-field>
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,6 +1,7 @@
 <mat-form-field class="example-full-width" appearance="fill">
   <mat-label>Choose a date</mat-label>
   <input matInput [matDatepickerFilter]="myFilter" [matDatepicker]="picker">
+  <mat-hint>MM/DD/YYYY</mat-hint>
   <mat-datepicker-toggle matSuffix [for]="picker"></mat-datepicker-toggle>
   <mat-datepicker #picker></mat-datepicker>
 </mat-form-field>
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,6 +1,7 @@
 <mat-form-field appearance="fill">
   <mat-label>Verbose datepicker</mat-label>
   <input matInput [matDatepicker]="dp" [formControl]="date">
+  <mat-hint>MMMM DD, YYYY</mat-hint>
   <mat-datepicker-toggle matSuffix [for]="dp"></mat-datepicker-toggle>
   <mat-datepicker #dp></mat-datepicker>
 </mat-form-field>
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-label>Different locale</mat-label>
   <input matInput [matDatepicker]="dp">
+  <mat-hint>{{getDateFormatString()}}</mat-hint>
   <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,6 +1,7 @@
 <mat-form-field class="example-full-width" appearance="fill">
   <mat-label>Choose a date</mat-label>
   <input matInput [min]="minDate" [max]="maxDate" [matDatepicker]="picker">
+  <mat-hint>MM/DD/YYYY</mat-hint>
   <mat-datepicker-toggle matSuffix [for]="picker"></mat-datepicker-toggle>
   <mat-datepicker #picker></mat-datepicker>
 </mat-form-field>
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,6 +1,7 @@
 <mat-form-field appearance="fill">
   <mat-label>Moment.js datepicker</mat-label>
   <input matInput [matDatepicker]="dp" [formControl]="date">
+  <mat-hint>MM/DD/YYYY</mat-hint>
   <mat-datepicker-toggle matSuffix [for]="dp"></mat-datepicker-toggle>
   <mat-datepicker #dp></mat-datepicker>
 </mat-form-field>
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
@@ -2,6 +2,7 @@
   <mat-label>Choose a date</mat-label>
 <!-- #docregion toggle -->
   <input matInput [matDatepicker]="picker">
+  <mat-hint>MM/DD/YYYY</mat-hint>
   <mat-datepicker-toggle matSuffix [for]="picker"></mat-datepicker-toggle>
   <mat-datepicker #picker></mat-datepicker>
 <!-- #enddocregion 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,6 +1,7 @@
 <mat-form-field appearance="fill">
   <mat-label>Choose a date</mat-label>
   <input matInput [matDatepicker]="picker">
+  <mat-hint>MM/DD/YYYY</mat-hint>
   <mat-datepicker-toggle matSuffix [for]="picker"></mat-datepicker-toggle>
   <mat-datepicker #picker startView="year" [startAt]="startDate"></mat-datepicker>
 </mat-form-field>
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,6 +1,7 @@
 <mat-form-field class="example-full-width" appearance="fill">
   <mat-label>Choose a date</mat-label>
   <input matInput [matDatepicker]="picker">
+  <mat-hint>MM/DD/YYYY</mat-hint>
   <mat-datepicker-toggle matSuffix [for]="picker"></mat-datepicker-toggle>
   <mat-datepicker touchUi #picker></mat-datepicker>
 </mat-form-field>
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,6 +1,7 @@
 <mat-form-field appearance="fill">
   <mat-label>Angular forms</mat-label>
   <input matInput [matDatepicker]="picker1" [formControl]="date">
+  <mat-hint>MM/DD/YYYY</mat-hint>
   <mat-datepicker-toggle matSuffix [for]="picker1"></mat-datepicker-toggle>
   <mat-datepicker #picker1></mat-datepicker>
 </mat-form-field>
@@ -9,13 +10,15 @@
   <mat-label>Angular forms (w/ deserialization)</mat-label>
   <input matInput [matDatepicker]="picker2"
          [formControl]="serializedDate">
+  <mat-hint>MM/DD/YYYY</mat-hint>
   <mat-datepicker-toggle matSuffix [for]="picker2"></mat-datepicker-toggle>
   <mat-datepicker #picker2></mat-datepicker>
 </mat-form-field>
 
 <mat-form-field appearance="fill">
   <mat-label>Value binding</mat-label>
   <input matInput [matDatepicker]="picker3" [value]="date.value">
+  <mat-hint>MM/DD/YYYY</mat-hint>
   <mat-datepicker-toggle matSuffix [for]="picker3"></mat-datepicker-toggle>
   <mat-datepicker #picker3></mat-datepicker>
 </mat-form-field>
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,6 +1,7 @@
 <mat-form-field appearance="fill">
   <mat-label>Month and Year</mat-label>
   <input matInput [matDatepicker]="dp" [formControl]="date">
+  <mat-hint>MM/YYYY</mat-hint>
   <mat-datepicker-toggle matSuffix [for]="dp"></mat-datepicker-toggle>
   <mat-datepicker #dp
                   startView="multi-year"
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
@@ -588,6 +588,9 @@ 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>`
+or by providing an additional label adjacent to the form field.
+
 `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
