fix(cdk/a11y): allow for multiple browser-generated description containers (angular#23507)

Currently the `AriaDescriber` is set up to clear all description containers whenever it is instantiated, in order to avoid duplicates coming in from the server. The problem is that there are legitimate use cases where we could have multiple containers (e.g. multiple CDK instances in a micro frontend architecture).

These changes rework the internal setup of the `AriaDescriber` so that it only clears containers from server and it doesn't touch containers coming from other describer instances.

Fixes angular#23499.

Author: crisbeto

src/cdk/a11y/aria-describer/aria-describer.spec.ts

@@ -1,5 +1,5 @@
 import {A11yModule, CDK_DESCRIBEDBY_HOST_ATTRIBUTE} from '../index';
-import {AriaDescriber, MESSAGES_CONTAINER_ID} from './aria-describer';
+import {AriaDescriber} from './aria-describer';
 import {ComponentFixture, TestBed} from '@angular/core/testing';
 import {Component, ElementRef, ViewChild, Provider} from '@angular/core';
 
@@ -209,16 +209,28 @@ describe('AriaDescriber', () => {
     expect(() => ariaDescriber.describe(node, 'This looks like an element')).not.toThrow();
   });
 
-  it('should clear any pre-existing containers', () => {
+  it('should clear any pre-existing containers coming in from the server', () => {
     createFixture();
     const extraContainer = document.createElement('div');
-    extraContainer.id = MESSAGES_CONTAINER_ID;
+    extraContainer.classList.add('cdk-describedby-message-container');
+    extraContainer.setAttribute('platform', 'server');
     document.body.appendChild(extraContainer);
 
     ariaDescriber.describe(component.element1, 'Hello');
 
-    // Use `querySelectorAll` with an attribute since `getElementById` will stop at the first match.
-    expect(document.querySelectorAll(`[id='${MESSAGES_CONTAINER_ID}']`).length).toBe(1);
+    expect(document.querySelectorAll('.cdk-describedby-message-container').length).toBe(1);
+    extraContainer.remove();
+  });
+
+  it('should not clear any pre-existing containers coming from the browser', () => {
+    createFixture();
+    const extraContainer = document.createElement('div');
+    extraContainer.classList.add('cdk-describedby-message-container');
+    document.body.appendChild(extraContainer);
+
+    ariaDescriber.describe(component.element1, 'Hello');
+
+    expect(document.querySelectorAll('.cdk-describedby-message-container').length).toBe(2);
     extraContainer.remove();
   });
 
@@ -337,7 +349,7 @@ describe('AriaDescriber', () => {
 });
 
 function getMessagesContainer() {
-  return document.querySelector(`#${MESSAGES_CONTAINER_ID}`)!;
+  return document.querySelector('.cdk-describedby-message-container')!;
 }
 
 function getMessageElements(): Element[] | null {

src/cdk/a11y/aria-describer/aria-describer.ts

@@ -8,6 +8,7 @@
 
 import {DOCUMENT} from '@angular/common';
 import {Inject, Injectable, OnDestroy} from '@angular/core';
+import {Platform} from '@angular/cdk/platform';
 import {addAriaReferencedId, getAriaReferenceIds, removeAriaReferencedId} from './aria-reference';
 
 /**
@@ -22,24 +23,30 @@ export interface RegisteredMessage {
   referenceCount: number;
 }
 
-/** ID used for the body container where all messages are appended. */
+/**
+ * ID used for the body container where all messages are appended.
+ * @deprecated No longer being used. To be removed.
+ * @breaking-change 14.0.0
+ */
 export const MESSAGES_CONTAINER_ID = 'cdk-describedby-message-container';
 
-/** ID prefix used for each created message element. */
+/**
+ * ID prefix used for each created message element.
+ * @deprecated To be turned into a private variable.
+ * @breaking-change 14.0.0
+ */
 export const CDK_DESCRIBEDBY_ID_PREFIX = 'cdk-describedby-message';
 
-/** Attribute given to each host element that is described by a message element. */
+/**
+ * Attribute given to each host element that is described by a message element.
+ * @deprecated To be turned into a private variable.
+ * @breaking-change 14.0.0
+ */
 export const CDK_DESCRIBEDBY_HOST_ATTRIBUTE = 'cdk-describedby-host';
 
 /** Global incremental identifier for each registered message element. */
 let nextId = 0;
 
-/** Global map of all registered message elements that have been placed into the document. */
-const messageRegistry = new Map<string | Element, RegisteredMessage>();
-
-/** Container for all registered messages. */
-let messagesContainer: HTMLElement | null = null;
-
 /**
  * Utility that creates visually hidden elements with a message content. Useful for elements that
  * want to use aria-describedby to further describe themselves without adding additional visual
@@ -49,7 +56,23 @@ let messagesContainer: HTMLElement | null = null;
 export class AriaDescriber implements OnDestroy {
   private _document: Document;
 
-  constructor(@Inject(DOCUMENT) _document: any) {
+  /** Map of all registered message elements that have been placed into the document. */
+  private _messageRegistry = new Map<string | Element, RegisteredMessage>();
+
+  /** Container for all registered messages. */
+  private _messagesContainer: HTMLElement | null = null;
+
+  /** Unique ID for the service. */
+  private readonly _id = `${nextId++}`;
+
+  constructor(
+    @Inject(DOCUMENT) _document: any,
+    /**
+     * @deprecated To be turned into a required parameter.
+     * @breaking-change 14.0.0
+     */
+    private _platform?: Platform,
+  ) {
     this._document = _document;
   }
 
@@ -75,8 +98,8 @@ export class AriaDescriber implements OnDestroy {
     if (typeof message !== 'string') {
       // We need to ensure that the element has an ID.
       setMessageId(message);
-      messageRegistry.set(key, {messageElement: message, referenceCount: 0});
-    } else if (!messageRegistry.has(key)) {
+      this._messageRegistry.set(key, {messageElement: message, referenceCount: 0});
+    } else if (!this._messageRegistry.has(key)) {
       this._createMessageElement(message, role);
     }
 
@@ -105,33 +128,32 @@ export class AriaDescriber implements OnDestroy {
     // If the message is a string, it means that it's one that we created for the
     // consumer so we can remove it safely, otherwise we should leave it in place.
     if (typeof message === 'string') {
-      const registeredMessage = messageRegistry.get(key);
+      const registeredMessage = this._messageRegistry.get(key);
       if (registeredMessage && registeredMessage.referenceCount === 0) {
         this._deleteMessageElement(key);
       }
     }
 
-    if (messagesContainer && messagesContainer.childNodes.length === 0) {
-      this._deleteMessagesContainer();
+    if (this._messagesContainer?.childNodes.length === 0) {
+      this._messagesContainer.remove();
+      this._messagesContainer = null;
     }
   }
 
   /** Unregisters all created message elements and removes the message container. */
   ngOnDestroy() {
     const describedElements = this._document.querySelectorAll(
-      `[${CDK_DESCRIBEDBY_HOST_ATTRIBUTE}]`,
+      `[${CDK_DESCRIBEDBY_HOST_ATTRIBUTE}="${this._id}"]`,
     );
 
     for (let i = 0; i < describedElements.length; i++) {
       this._removeCdkDescribedByReferenceIds(describedElements[i]);
       describedElements[i].removeAttribute(CDK_DESCRIBEDBY_HOST_ATTRIBUTE);
     }
 
-    if (messagesContainer) {
-      this._deleteMessagesContainer();
-    }
-
-    messageRegistry.clear();
+    this._messagesContainer?.remove();
+    this._messagesContainer = null;
+    this._messageRegistry.clear();
   }
 
   /**
@@ -148,49 +170,54 @@ export class AriaDescriber implements OnDestroy {
     }
 
     this._createMessagesContainer();
-    messagesContainer!.appendChild(messageElement);
-    messageRegistry.set(getKey(message, role), {messageElement, referenceCount: 0});
+    this._messagesContainer!.appendChild(messageElement);
+    this._messageRegistry.set(getKey(message, role), {messageElement, referenceCount: 0});
   }
 
   /** Deletes the message element from the global messages container. */
   private _deleteMessageElement(key: string | Element) {
-    const registeredMessage = messageRegistry.get(key);
-    registeredMessage?.messageElement?.remove();
-    messageRegistry.delete(key);
+    this._messageRegistry.get(key)?.messageElement?.remove();
+    this._messageRegistry.delete(key);
   }
 
   /** Creates the global container for all aria-describedby messages. */
   private _createMessagesContainer() {
-    if (!messagesContainer) {
-      const preExistingContainer = this._document.getElementById(MESSAGES_CONTAINER_ID);
+    if (this._messagesContainer) {
+      return;
+    }
 
+    const containerClassName = 'cdk-describedby-message-container';
+    const serverContainers = this._document.querySelectorAll(
+      `.${containerClassName}[platform="server"]`,
+    );
+
+    for (let i = 0; i < serverContainers.length; i++) {
       // When going from the server to the client, we may end up in a situation where there's
       // already a container on the page, but we don't have a reference to it. Clear the
       // old container so we don't get duplicates. Doing this, instead of emptying the previous
       // container, should be slightly faster.
-      preExistingContainer?.remove();
-
-      messagesContainer = this._document.createElement('div');
-      messagesContainer.id = MESSAGES_CONTAINER_ID;
-      // We add `visibility: hidden` in order to prevent text in this container from
-      // being searchable by the browser's Ctrl + F functionality.
-      // Screen-readers will still read the description for elements with aria-describedby even
-      // when the description element is not visible.
-      messagesContainer.style.visibility = 'hidden';
-      // Even though we use `visibility: hidden`, we still apply `cdk-visually-hidden` so that
-      // the description element doesn't impact page layout.
-      messagesContainer.classList.add('cdk-visually-hidden');
-
-      this._document.body.appendChild(messagesContainer);
+      serverContainers[i].remove();
     }
-  }
 
-  /** Deletes the global messages container. */
-  private _deleteMessagesContainer() {
-    if (messagesContainer) {
-      messagesContainer.remove();
-      messagesContainer = null;
+    const messagesContainer = this._document.createElement('div');
+
+    // We add `visibility: hidden` in order to prevent text in this container from
+    // being searchable by the browser's Ctrl + F functionality.
+    // Screen-readers will still read the description for elements with aria-describedby even
+    // when the description element is not visible.
+    messagesContainer.style.visibility = 'hidden';
+    // Even though we use `visibility: hidden`, we still apply `cdk-visually-hidden` so that
+    // the description element doesn't impact page layout.
+    messagesContainer.classList.add(containerClassName);
+    messagesContainer.classList.add('cdk-visually-hidden');
+
+    // @breaking-change 14.0.0 Remove null check for `_platform`.
+    if (this._platform && !this._platform.isBrowser) {
+      messagesContainer.setAttribute('platform', 'server');
     }
+
+    this._document.body.appendChild(messagesContainer);
+    this._messagesContainer = messagesContainer;
   }
 
   /** Removes all cdk-describedby messages that are hosted through the element. */
@@ -207,12 +234,12 @@ export class AriaDescriber implements OnDestroy {
    * message's reference count.
    */
   private _addMessageReference(element: Element, key: string | Element) {
-    const registeredMessage = messageRegistry.get(key)!;
+    const registeredMessage = this._messageRegistry.get(key)!;
 
     // Add the aria-describedby reference and set the
     // describedby_host attribute to mark the element.
     addAriaReferencedId(element, 'aria-describedby', registeredMessage.messageElement.id);
-    element.setAttribute(CDK_DESCRIBEDBY_HOST_ATTRIBUTE, '');
+    element.setAttribute(CDK_DESCRIBEDBY_HOST_ATTRIBUTE, this._id);
     registeredMessage.referenceCount++;
   }
 
@@ -221,7 +248,7 @@ export class AriaDescriber implements OnDestroy {
    * and decrements the registered message's reference count.
    */
   private _removeMessageReference(element: Element, key: string | Element) {
-    const registeredMessage = messageRegistry.get(key)!;
+    const registeredMessage = this._messageRegistry.get(key)!;
     registeredMessage.referenceCount--;
 
     removeAriaReferencedId(element, 'aria-describedby', registeredMessage.messageElement.id);
@@ -231,7 +258,7 @@ export class AriaDescriber implements OnDestroy {
   /** Returns true if the element has been described by the provided message ID. */
   private _isElementDescribedByMessage(element: Element, key: string | Element): boolean {
     const referenceIds = getAriaReferenceIds(element, 'aria-describedby');
-    const registeredMessage = messageRegistry.get(key);
+    const registeredMessage = this._messageRegistry.get(key);
     const messageId = registeredMessage && registeredMessage.messageElement.id;
 
     return !!messageId && referenceIds.indexOf(messageId) != -1;

tools/public_api_guard/cdk/a11y.md

@@ -43,7 +43,8 @@ export class ActiveDescendantKeyManager<T> extends ListKeyManager<Highlightable
 
 // @public
 export class AriaDescriber implements OnDestroy {
-    constructor(_document: any);
+    constructor(_document: any,
+    _platform?: Platform | undefined);
     describe(hostElement: Element, message: string, role?: string): void;
     describe(hostElement: Element, message: HTMLElement): void;
     ngOnDestroy(): void;
@@ -58,10 +59,10 @@ export class AriaDescriber implements OnDestroy {
 // @public
 export type AriaLivePoliteness = 'off' | 'polite' | 'assertive';
 
-// @public
+// @public @deprecated
 export const CDK_DESCRIBEDBY_HOST_ATTRIBUTE = "cdk-describedby-host";
 
-// @public
+// @public @deprecated
 export const CDK_DESCRIBEDBY_ID_PREFIX = "cdk-describedby-message";
 
 // @public
@@ -398,7 +399,7 @@ export interface LiveAnnouncerDefaultOptions {
     politeness?: AriaLivePoliteness;
 }
 
-// @public
+// @public @deprecated
 export const MESSAGES_CONTAINER_ID = "cdk-describedby-message-container";
 
 // @public