feat(form-field): expose label content element id for custom controls

guides/creating-a-custom-form-field-control.md

@@ -23,7 +23,7 @@ class MyTel {
 @Component({
   selector: 'example-tel-input',
   template: `
-    <div [formGroup]="parts">
+    <div role="group" [formGroup]="parts">
       <input class="area" formControlName="area" maxlength="3">
       <span>&ndash;</span>
       <input class="exchange" formControlName="exchange" maxlength="3">
@@ -45,7 +45,7 @@ class MyTel {
     }
   `],
 })
-class MyTelInput {
+export class MyTelInput {
   parts: FormGroup;
 
   @Input()
@@ -85,7 +85,7 @@ a provider to our component so that the form field will be able to inject it as
   ...
   providers: [{provide: MatFormFieldControl, useExisting: MyTelInput}],
 })
-class MyTelInput implements MatFormFieldControl<MyTel> {
+export class MyTelInput implements MatFormFieldControl<MyTel> {
   ...
 }
 ```
@@ -201,7 +201,7 @@ To resolve this, remove the `NG_VALUE_ACCESSOR` provider and instead set the val
     // },
   ],
 })
-class MyTelInput implements MatFormFieldControl<MyTel> {
+export class MyTelInput implements MatFormFieldControl<MyTel> {
   constructor(
     ...,
     @Optional() @Self() public ngControl: NgControl,
@@ -341,16 +341,20 @@ controlType = 'example-tel-input';
 
 This method is used by the `<mat-form-field>` to specify the IDs that should be used for the
 `aria-describedby` attribute of your component. The method has one parameter, the list of IDs, we
-just need to apply the given IDs to our host element.
+just need to apply the given IDs to the element that represents our control.
 
-```ts
-@HostBinding('attr.aria-describedby') describedBy = '';
+In our concrete example, these IDs would need to be applied to the group element. 
 
+```ts
 setDescribedByIds(ids: string[]) {
   this.describedBy = ids.join(' ');
 }
 ```
 
+```html
+<div role="group" [formGroup]="parts" [attr.aria-describedby]="describedBy">
+```
+
 #### `onContainerClick(event: MouseEvent)`
 
 This method will be called when the form field is clicked on. It allows your component to hook in
@@ -366,6 +370,41 @@ onContainerClick(event: MouseEvent) {
 }
 ```
 
+### Improving accessibility
+
+Our custom form field control consists of multiple inputs that describe segments of a phone
+number. For accessibility purposes, we put those inputs as part of a `div` element with
+`role="group"`. This ensures that screen reader users can tell that all those inputs belong
+together.
+
+One significant piece of information is missing for screen reader users though. They won't be able
+to tell what this input group represents. To improve this, we should add a label for the group
+element using either `aria-label` or `aria-labelledby`.
+
+It's recommended to link the group to the label that is displayed as part of the parent
+`<mat-form-field>`. This ensures that explicitly specified labels (using `<mat-label>`) are
+actually used for labelling the control.
+
+In our concrete example, we add an attribute binding for `aria-labelledby` and bind it
+to the label element id provided by the parent `<mat-form-field>`.
+
+```typescript
+export class MyTelInput implements MatFormFieldControl<MyTel> {
+  ...
+
+  constructor(...
+              @Optional() public parentFormField: MatFormField) {
+```
+
+```html
+@Component({
+  selector: 'example-tel-input',
+  template: `
+    <div role="group" [formGroup]="parts"
+         [attr.aria-describedby]="describedBy"
+         [attr.aria-labelledby]="parentFormField?.getLabelId()">
+```
+
 ### Trying it out
 
 Now that we've fully implemented the interface, we're ready to try our component out! All we need to

src/components-examples/material-experimental/mdc-form-field/mdc-form-field-custom-control/example-tel-input-example.html

@@ -1,4 +1,7 @@
-<div [formGroup]="parts" class="example-tel-input-container">
+<div role="group" class="example-tel-input-container"
+     [formGroup]="parts"
+     [attr.aria-labelledby]="_formField?.getLabelId()"
+     [attr.aria-describedby]="describedBy">
   <input
     class="example-tel-input-element"
     formControlName="area" size="3"

src/components-examples/material-experimental/mdc-form-field/mdc-form-field-custom-control/form-field-custom-control-example.ts

@@ -1,8 +1,9 @@
 import {FocusMonitor} from '@angular/cdk/a11y';
 import {coerceBooleanProperty} from '@angular/cdk/coercion';
-import {Component, ElementRef, Input, OnDestroy, Optional, Self} from '@angular/core';
-import {FormBuilder, FormGroup, ControlValueAccessor, NgControl, Validators} from '@angular/forms';
-import {MatFormFieldControl} from '@angular/material-experimental/mdc-form-field';
+import {Component, ElementRef, Inject, Input, OnDestroy, Optional, Self} from '@angular/core';
+import {ControlValueAccessor, FormBuilder, FormGroup, NgControl, Validators} from '@angular/forms';
+import {MatFormField, MatFormFieldControl} from '@angular/material-experimental/mdc-form-field';
+import {MAT_FORM_FIELD} from '@angular/material/form-field';
 import {Subject} from 'rxjs';
 
 /** @title Form field with custom telephone number input control. */
@@ -27,7 +28,6 @@ export class MyTel {
   host: {
     '[class.example-floating]': 'shouldLabelFloat',
     '[id]': 'id',
-    '[attr.aria-describedby]': 'describedBy',
   }
 })
 export class MyTelInput implements ControlValueAccessor, MatFormFieldControl<MyTel>, OnDestroy {
@@ -94,6 +94,7 @@ export class MyTelInput implements ControlValueAccessor, MatFormFieldControl<MyT
     formBuilder: FormBuilder,
     private _focusMonitor: FocusMonitor,
     private _elementRef: ElementRef<HTMLElement>,
+    @Optional() @Inject(MAT_FORM_FIELD) public _formField: MatFormField,
     @Optional() @Self() public ngControl: NgControl) {
 
     this.parts = formBuilder.group({

src/components-examples/material/form-field/form-field-custom-control/example-tel-input-example.html

@@ -1,4 +1,7 @@
-<div [formGroup]="parts" class="example-tel-input-container">
+<div role="group" class="example-tel-input-container"
+     [formGroup]="parts"
+     [attr.aria-labelledby]="_formField?.getLabelId()"
+     [attr.aria-describedby]="describedBy">
   <input class="example-tel-input-element"
          formControlName="area" size="3"
          maxLength="3"

src/components-examples/material/form-field/form-field-custom-control/form-field-custom-control-example.ts

@@ -3,22 +3,23 @@ import {coerceBooleanProperty} from '@angular/cdk/coercion';
 import {
   Component,
   ElementRef,
+  Inject,
   Input,
   OnDestroy,
   Optional,
   Self,
   ViewChild
 } from '@angular/core';
 import {
+  AbstractControl,
+  ControlValueAccessor,
   FormBuilder,
+  FormControl,
   FormGroup,
-  ControlValueAccessor,
   NgControl,
-  Validators,
-  FormControl,
-  AbstractControl
+  Validators
 } from '@angular/forms';
-import {MatFormFieldControl} from '@angular/material/form-field';
+import {MAT_FORM_FIELD, MatFormField, MatFormFieldControl} from '@angular/material/form-field';
 import {Subject} from 'rxjs';
 
 /** @title Form field with custom telephone number input control. */
@@ -51,7 +52,6 @@ export class MyTel {
   host: {
     '[class.example-floating]': 'shouldLabelFloat',
     '[id]': 'id',
-    '[attr.aria-describedby]': 'describedBy'
   }
 })
 export class MyTelInput
@@ -134,8 +134,9 @@ export class MyTelInput
     formBuilder: FormBuilder,
     private _focusMonitor: FocusMonitor,
     private _elementRef: ElementRef<HTMLElement>,
-    @Optional() @Self() public ngControl: NgControl
-  ) {
+    @Optional() @Inject(MAT_FORM_FIELD) public _formField: MatFormField,
+    @Optional() @Self() public ngControl: NgControl) {
+
     this.parts = formBuilder.group({
       area: [
         null,

src/material-experimental/mdc-form-field/form-field.ts

@@ -192,11 +192,11 @@ export class MatFormField implements AfterViewInit, OnDestroy, AfterContentCheck
   }
   private _hintLabel = '';
 
-  // Unique id for the hint label.
-  _hintLabelId = `mat-mdc-hint-${nextUniqueId++}`;
-
   // Unique id for the internal form field label.
-  _labelId = `mat-mdc-form-field-label-${nextUniqueId++}`;
+  readonly _labelId = `mat-mdc-form-field-label-${nextUniqueId++}`;
+
+  // Unique id for the hint label.
+  readonly _hintLabelId = `mat-mdc-hint-${nextUniqueId++}`;
 
   /** State of the mat-hint and mat-error animations. */
   _subscriptAnimationState = '';
@@ -358,6 +358,13 @@ export class MatFormField implements AfterViewInit, OnDestroy, AfterContentCheck
     this._destroyed.complete();
   }
 
+  /**
+   * Gets the id of the label element. If no label is present, returns `null`.
+   */
+  getLabelId(): string|null {
+    return this._hasFloatingLabel() ? this._labelId : null;
+  }
+
   /**
    * Gets an ElementRef for the element that a overlay attached to the form-field
    * should be positioned relative to.

src/material/form-field/form-field.ts

@@ -219,10 +219,10 @@ export class MatFormField extends _MatFormFieldMixinBase
   private _hintLabel = '';
 
   // Unique id for the hint label.
-  _hintLabelId: string = `mat-hint-${nextUniqueId++}`;
+  readonly _hintLabelId: string = `mat-hint-${nextUniqueId++}`;
 
-  // Unique id for the internal form field label.
-  _labelId = `mat-form-field-label-${nextUniqueId++}`;
+  // Unique id for the label element.
+  readonly _labelId = `mat-form-field-label-${nextUniqueId++}`;
 
   /**
    * Whether the label should always float, never float or float as the user types.
@@ -300,6 +300,13 @@ export class MatFormField extends _MatFormFieldMixinBase
         _defaults.hideRequiredMarker : false;
   }
 
+  /**
+   * Gets the id of the label element. If no label is present, returns `null`.
+   */
+  getLabelId(): string|null {
+    return this._hasFloatingLabel() ? this._labelId : null;
+  }
+
   /**
    * Gets an ElementRef for the element that a overlay attached to the form-field should be
    * positioned relative to.

src/material/select/select.ts

@@ -1168,7 +1168,7 @@ export class MatSelect extends _MatSelectMixinBase implements AfterContentInit,
       return null;
     }
 
-    return this._parentFormField._labelId || null;
+    return this._parentFormField.getLabelId();
   }
 
   /** Determines the `aria-activedescendant` to be set on the host. */

tools/public_api_guard/material/form-field.d.ts

@@ -28,12 +28,12 @@ export declare class MatFormField extends _MatFormFieldMixinBase implements Afte
     _elementRef: ElementRef;
     _errorChildren: QueryList<MatError>;
     _hintChildren: QueryList<MatHint>;
-    _hintLabelId: string;
+    readonly _hintLabelId: string;
     _inputContainerRef: ElementRef;
     get _labelChild(): MatLabel;
     _labelChildNonStatic: MatLabel;
     _labelChildStatic: MatLabel;
-    _labelId: string;
+    readonly _labelId: string;
     _placeholderChild: MatPlaceholder;
     _prefixChildren: QueryList<MatPrefix>;
     get _shouldAlwaysFloat(): boolean;
@@ -59,6 +59,7 @@ export declare class MatFormField extends _MatFormFieldMixinBase implements Afte
     _shouldLabelFloat(): boolean;
     protected _validateControlChild(): void;
     getConnectedOverlayOrigin(): ElementRef;
+    getLabelId(): string | null;
     ngAfterContentChecked(): void;
     ngAfterContentInit(): void;
     ngAfterViewInit(): void;