fixup! fix(material/input): do not override existing aria-describedby…

… value

Add documentation

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

@@ -339,20 +339,33 @@ controlType = 'example-tel-input';
 
 #### `setDescribedByIds(ids: string[])`
 
-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 the element that represents our control.
+This method is used by the `<mat-form-field>` to set element ids that should be used for the
+`aria-describedby` attribute of your control. The ids are controlled through the form field
+as hints or errors are conditionally displayed and should be reflected in the control's
+`aria-describedby` attribute for an improved accessibility experience. 
 
-In our concrete example, these IDs would need to be applied to the group element. 
+The `setDescribedByIds` method is invoked whenever the control's state changes. Custom controls
+need to implement this method and update the `aria-describedby` attribute based on the specified
+element ids. Below is an example that shows how this can be achieved.
+
+Note that the method by default will not respect element ids that have been set manually on the
+control element through the `aria-describedby` attribute. To ensure that your control does not
+accidentally override existing element ids specified by consumers of your control, create an
+input called `userAriaDescribedby`  like followed:
 
 ```ts
-setDescribedByIds(ids: string[]) {
-  this.describedBy = ids.join(' ');
-}
+@Input('aria-describedby') userAriaDescribedBy: string;
 ```
 
-```html
-<div role="group" [formGroup]="parts" [attr.aria-describedby]="describedBy">
+The form field will then pick up the user specified `aria-describedby` ids and merge
+them with ids for hints or errors whenever `setDescribedByIds` is invoked.
+
+```ts
+setDescribedByIds(ids: string[]) {
+  const controlElement = this._elementRef.nativeElement
+    .querySelector('.example-tel-input-container')!;
+  controlElement.setAttribute('aria-describedby', ids.join(' '));
+}
 ```
 
 #### `onContainerClick(event: MouseEvent)`

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

@@ -1,7 +1,6 @@
 <div role="group" class="example-tel-input-container"
      [formGroup]="parts"
-     [attr.aria-labelledby]="_formField?.getLabelId()"
-     [attr.aria-describedby]="describedBy">
+     [attr.aria-labelledby]="_formField?.getLabelId()">
   <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

@@ -38,7 +38,6 @@ export class MyTelInput implements ControlValueAccessor, MatFormFieldControl<MyT
   errorState = false;
   controlType = 'example-tel-input';
   id = `example-tel-input-${MyTelInput.nextId++}`;
-  describedBy = '';
   onChange = (_: any) => {};
   onTouched = () => {};
 
@@ -50,6 +49,8 @@ export class MyTelInput implements ControlValueAccessor, MatFormFieldControl<MyT
 
   get shouldLabelFloat() { return this.focused || !this.empty; }
 
+  @Input('aria-describedby') userAriaDescribedBy: string;
+
   @Input()
   get placeholder(): string { return this._placeholder; }
   set placeholder(value: string) {
@@ -121,7 +122,9 @@ export class MyTelInput implements ControlValueAccessor, MatFormFieldControl<MyT
   }
 
   setDescribedByIds(ids: string[]) {
-    this.describedBy = ids.join(' ');
+    const controlElement = this._elementRef.nativeElement
+      .querySelector('.example-tel-input-container')!;
+    controlElement.setAttribute('aria-describedby', ids.join(' '));
   }
 
   onContainerClick(event: MouseEvent) {

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

@@ -1,7 +1,6 @@
 <div role="group" class="example-tel-input-container"
      [formGroup]="parts"
-     [attr.aria-labelledby]="_formField?.getLabelId()"
-     [attr.aria-describedby]="describedBy">
+     [attr.aria-labelledby]="_formField?.getLabelId()">
   <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

@@ -66,7 +66,6 @@ export class MyTelInput
   errorState = false;
   controlType = 'example-tel-input';
   id = `example-tel-input-${MyTelInput.nextId++}`;
-  describedBy = '';
   onChange = (_: any) => {};
   onTouched = () => {};
 
@@ -82,6 +81,8 @@ export class MyTelInput
     return this.focused || !this.empty;
   }
 
+  @Input('aria-describedby') userAriaDescribedBy: string;
+
   @Input()
   get placeholder(): string {
     return this._placeholder;
@@ -182,7 +183,9 @@ export class MyTelInput
   }
 
   setDescribedByIds(ids: string[]) {
-    this.describedBy = ids.join(' ');
+    const controlElement = this._elementRef.nativeElement
+      .querySelector('.example-tel-input-container')!;
+    controlElement.setAttribute('aria-describedby', ids.join(' '));
   }
 
   onContainerClick(event: MouseEvent) {