fix(material/form-field): preserve aria-describedby set externally across all form controls

fix(material/form-field): preserve aria-describedby set externally across all form controls

add describedbyids and use to preserve existing ids

add describedByIds to input

add comment

Move better sync logic to formfield

add describedByIds to other controls

update api goldens

tweak comment

add more tests

Author: adolgachev

goldens/material/chips/index.api.md

@@ -172,6 +172,7 @@ export class MatChipGrid extends MatChipSet implements AfterContentInit, AfterVi
     readonly controlType: string;
     // (undocumented)
     protected _defaultRole: string;
+    get describedByIds(): string[];
     get disabled(): boolean;
     set disabled(value: boolean);
     get empty(): boolean;
@@ -250,6 +251,7 @@ export class MatChipInput implements MatChipTextControl, OnChanges, OnDestroy {
     // (undocumented)
     protected _chipGrid: MatChipGrid;
     clear(): void;
+    get describedByIds(): string[];
     get disabled(): boolean;
     set disabled(value: boolean);
     disabledInteractive: boolean;
@@ -514,6 +516,7 @@ export class MatChipsModule {
 
 // @public
 export interface MatChipTextControl {
+    readonly describedByIds?: string[];
     empty: boolean;
     focus(): void;
     focused: boolean;

goldens/material/datepicker/index.api.md

@@ -567,6 +567,7 @@ export class MatDateRangeInput<D> implements MatFormFieldControl<DateRange<D>>,
     controlType: string;
     get dateFilter(): DateFilterFn<D>;
     set dateFilter(value: DateFilterFn<D>);
+    get describedByIds(): string[];
     readonly disableAutomaticLabeling = true;
     get disabled(): boolean;
     set disabled(value: boolean);

goldens/material/form-field/index.api.md

@@ -156,6 +156,7 @@ export type MatFormFieldAppearance = 'fill' | 'outline';
 export abstract class MatFormFieldControl<T> {
     readonly autofilled?: boolean;
     readonly controlType?: string;
+    readonly describedByIds?: string[];
     readonly disableAutomaticLabeling?: boolean;
     readonly disabled: boolean;
     readonly empty: boolean;

goldens/material/input/index.api.md

@@ -152,6 +152,7 @@ export class MatInput implements MatFormFieldControl_2<any>, OnChanges, OnDestro
     constructor(...args: unknown[]);
     autofilled: boolean;
     controlType: string;
+    get describedByIds(): string[];
     protected _dirtyCheckNativeValue(): void;
     get disabled(): boolean;
     set disabled(value: BooleanInput);

goldens/material/select/index.api.md

@@ -266,6 +266,7 @@ export class MatSelect implements AfterContentInit, OnChanges, OnDestroy, OnInit
     customTrigger: MatSelectTrigger;
     // (undocumented)
     protected _defaultOptions: MatSelectConfig | null;
+    get describedByIds(): string[];
     protected readonly _destroy: Subject<void>;
     readonly disableAutomaticLabeling = true;
     disabled: boolean;

src/material/chips/chip-grid.ts

@@ -349,6 +349,14 @@ export class MatChipGrid
     this.stateChanges.next();
   }
 
+  /**
+   * Implemented as part of MatFormFieldControl.
+   * @docs-private
+   */
+  get describedByIds(): string[] {
+    return this._chipInput?.describedByIds || [];
+  }
+
   /**
    * Implemented as part of MatFormFieldControl.
    * @docs-private

src/material/chips/chip-input.spec.ts

@@ -155,6 +155,38 @@ describe('MatChipInput', () => {
       expect(inputNativeElement.classList).toContain('mat-mdc-chip-input');
       expect(inputNativeElement.classList).toContain('mdc-text-field__input');
     });
+
+    it('should set `aria-describedby` to the id of the mat-hint', () => {
+      expect(inputNativeElement.getAttribute('aria-describedby')).toBeNull();
+
+      fixture.componentInstance.hint = 'test';
+      fixture.changeDetectorRef.markForCheck();
+      fixture.detectChanges();
+      const hint = fixture.debugElement.query(By.css('mat-hint')).nativeElement;
+
+      expect(inputNativeElement.getAttribute('aria-describedby')).toBe(hint.getAttribute('id'));
+      expect(inputNativeElement.getAttribute('aria-describedby')).toMatch(/^mat-mdc-hint-\w+\d+$/);
+    });
+
+    it('should support user binding to `aria-describedby`', () => {
+      inputNativeElement.setAttribute('aria-describedby', 'test');
+      fixture.changeDetectorRef.markForCheck();
+      fixture.detectChanges();
+
+      expect(inputNativeElement.getAttribute('aria-describedby')).toBe('test');
+    });
+
+    it('should preserve aria-describedby set directly in the DOM', fakeAsync(() => {
+      inputNativeElement.setAttribute('aria-describedby', 'custom');
+      fixture.componentInstance.hint = 'test';
+      fixture.changeDetectorRef.markForCheck();
+      fixture.detectChanges();
+      const hint = fixture.debugElement.query(By.css('mat-hint')).nativeElement;
+
+      expect(inputNativeElement.getAttribute('aria-describedby')).toBe(
+        `${hint.getAttribute('id')} custom`,
+      );
+    }));
   });
 
   describe('[addOnBlur]', () => {
@@ -289,7 +321,7 @@ describe('MatChipInput', () => {
 
 @Component({
   template: `
-    <mat-form-field>
+    <mat-form-field [hintLabel]="hint">
       <mat-chip-grid #chipGrid [required]="required">
         <mat-chip-row>Hello</mat-chip-row>
         <input
@@ -309,6 +341,7 @@ class TestChipInput {
   placeholder = '';
   required = false;
   disabledInteractive = false;
+  hint: string;
 
   add(_: MatChipInputEvent) {}
 }

src/material/chips/chip-input.ts

@@ -218,6 +218,17 @@ export class MatChipInput implements MatChipTextControl, OnChanges, OnDestroy {
     this.inputElement.value = '';
   }
 
+  /**
+   * Implemented as part of MatChipTextControl.
+   * @docs-private
+   */
+  get describedByIds(): string[] {
+    const element = this._elementRef.nativeElement;
+    const existingDescribedBy = element.getAttribute('aria-describedby');
+
+    return existingDescribedBy?.split(' ') || [];
+  }
+
   setDescribedByIds(ids: string[]): void {
     const element = this._elementRef.nativeElement;
 

src/material/chips/chip-text-control.ts

@@ -23,6 +23,9 @@ export interface MatChipTextControl {
   /** Focuses the text control. */
   focus(): void;
 
+  /** Gets the list of ids the input is described by. */
+  readonly describedByIds?: string[];
+
   /** Sets the list of ids the input is described by. */
   setDescribedByIds(ids: string[]): void;
 }

src/material/datepicker/date-range-input.spec.ts

@@ -169,7 +169,7 @@ describe('MatDateRangeInput', () => {
     expect(rangeInput.getAttribute('aria-labelledby')).toBe(labelId);
   });
 
-  it('should point the range input aria-labelledby to the form field hint element', () => {
+  it('should point the range input aria-describedby to the form field hint element', () => {
     const fixture = createComponent(StandardRangePicker);
     fixture.detectChanges();
     const labelId = fixture.nativeElement.querySelector('.mat-mdc-form-field-hint').id;
@@ -179,6 +179,18 @@ describe('MatDateRangeInput', () => {
     expect(rangeInput.getAttribute('aria-describedby')).toBe(labelId);
   });
 
+  it('should preserve aria-describedby set directly in the DOM', fakeAsync(() => {
+    const fixture = createComponent(StandardRangePicker);
+    const rangeInput = fixture.nativeElement.querySelector('.mat-date-range-input');
+
+    rangeInput.setAttribute('aria-describedby', 'custom');
+    fixture.changeDetectorRef.markForCheck();
+    fixture.detectChanges();
+    const hint = fixture.nativeElement.querySelector('.mat-mdc-form-field-hint');
+
+    expect(rangeInput.getAttribute('aria-describedby')).toBe(`${hint.getAttribute('id')} custom`);
+  }));
+
   it('should not set aria-labelledby if the form field does not have a label', () => {
     const fixture = createComponent(RangePickerNoLabel);
     fixture.detectChanges();