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

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

Currently, the form-field always creates a label element as sibling
to projected form-field controls. For native controls, the label is
associated with the controls using the `for` attribute.

This doesn't work for custom controls which might not be based
on native controls. e.g. the `mat-select`. In those cases, the
appropriate aria attributes need to be applied with `aria-labelledby`
that refers to the label content element.

Since this is a common pattern for custom controls that don't use
native controls, we need to expose the element id for the label content.

Currently we already do this for the select, but just prefixed it with
an underscore. This denotes it as private API while there is obviously a
use-case for exposing this publicly. Best example is how the select
_needs_ it.

* docs: improve accessibility for custom form-field control guide

Improves the accessibility for the control that is built as part
of the custom form-field control guide.

Author: devversion

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. */
@@ -26,7 +27,6 @@ export class MyTel {
   host: {
     '[class.example-floating]': 'shouldLabelFloat',
     '[id]': 'id',
-    '[attr.aria-describedby]': 'describedBy',
   }
 })
 export class MyTelInput implements ControlValueAccessor, MatFormFieldControl<MyTel>, OnDestroy {
@@ -93,6 +93,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. */
@@ -50,7 +51,6 @@ export class MyTel {
   host: {
     '[class.example-floating]': 'shouldLabelFloat',
     '[id]': 'id',
-    '[attr.aria-describedby]': 'describedBy'
   }
 })
 export class MyTelInput
@@ -133,8 +133,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

@@ -191,11 +191,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 = '';
@@ -357,6 +357,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.
@@ -301,6 +301,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

@@ -1184,7 +1184,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

@@ -35,11 +35,11 @@ export declare class MatFormField extends _MatFormFieldMixinBase implements Afte
     _elementRef: ElementRef;
     _errorChildren: QueryList<MatError>;
     _hintChildren: QueryList<MatHint>;
-    _hintLabelId: string;
+    readonly _hintLabelId: string;
     _inputContainerRef: ElementRef;
     _labelChildNonStatic: MatLabel;
     _labelChildStatic: MatLabel;
-    _labelId: string;
+    readonly _labelId: string;
     _placeholderChild: MatPlaceholder;
     _prefixChildren: QueryList<MatPrefix>;
     _subscriptAnimationState: string;
@@ -66,6 +66,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;