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

Add documentation

Author: devversion

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

@@ -339,15 +339,30 @@ 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 our host element.
+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. 
+
+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
-@HostBinding('attr.aria-describedby') describedBy = '';
+@Input('aria-describedby') userAriaDescribedBy: string;
+```
 
+The form field will then pick up the user specified `aria-describedby` ids and merge
+them with the ids from hints or errors whenever `setDescribedByIds` is invoked.
+
+```ts
 setDescribedByIds(ids: string[]) {
-  this.describedBy = ids.join(' ');
+  this._elementRef.nativeElement.setAttribute('aria-describedby', ids.join(' '));
 }
 ```
 

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

@@ -26,7 +26,6 @@ export class MyTel {
   host: {
     '[class.example-floating]': 'shouldLabelFloat',
     '[id]': 'id',
-    '[attr.aria-describedby]': 'describedBy',
   }
 })
 export class MyTelInput implements ControlValueAccessor, MatFormFieldControl<MyTel>, OnDestroy {
@@ -38,7 +37,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 +48,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) {
@@ -120,7 +120,7 @@ export class MyTelInput implements ControlValueAccessor, MatFormFieldControl<MyT
   }
 
   setDescribedByIds(ids: string[]) {
-    this.describedBy = ids.join(' ');
+    this._elementRef.nativeElement.setAttribute('aria-describedby', ids.join(' '));
   }
 
   onContainerClick(event: MouseEvent) {

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

@@ -50,7 +50,6 @@ export class MyTel {
   host: {
     '[class.example-floating]': 'shouldLabelFloat',
     '[id]': 'id',
-    '[attr.aria-describedby]': 'describedBy'
   }
 })
 export class MyTelInput
@@ -66,7 +65,6 @@ export class MyTelInput
   errorState = false;
   controlType = 'example-tel-input';
   id = `example-tel-input-${MyTelInput.nextId++}`;
-  describedBy = '';
   onChange = (_: any) => {};
   onTouched = () => {};
 
@@ -82,6 +80,8 @@ export class MyTelInput
     return this.focused || !this.empty;
   }
 
+  @Input('aria-describedby') userAriaDescribedBy: string;
+
   @Input()
   get placeholder(): string {
     return this._placeholder;
@@ -181,7 +181,7 @@ export class MyTelInput
   }
 
   setDescribedByIds(ids: string[]) {
-    this.describedBy = ids.join(' ');
+    this._elementRef.nativeElement.setAttribute('aria-describedby', ids.join(' '));
   }
 
   onContainerClick(event: MouseEvent) {