add a method to clear accessible responses of a particular group, see phetsims/molecule-polarity#347

Author: jessegreenberg

js/accessibility/pdom/ParallelDOM.ts

@@ -3590,6 +3590,32 @@ export default class ParallelDOM extends PhetioObject {
     this.addAccessibleResponse( alertable, 'other', providedOptions );
   }
 
+  /**
+   * Remove any queued responses for the provided response groups across connected Displays.
+   * This does not cancel currently speaking responses.
+   */
+  public clearAccessibleResponseGroups( responseGroups: string | string[] ): void {
+    const groups = Array.isArray( responseGroups ) ? responseGroups : [ responseGroups ];
+
+    for ( let i = 0; i < groups.length; i++ ) {
+      const group = groups[ i ];
+      const responseGroupUtterance = responseGroupRegistry.getGroupUtterance( group );
+      if ( !responseGroupUtterance ) {
+        continue;
+      }
+
+      if ( globalDescriptionQueue.hasUtterance( responseGroupUtterance ) ) {
+        globalDescriptionQueue.removeUtterance( responseGroupUtterance );
+      }
+
+      this.forEachUtteranceQueue( queue => {
+        if ( queue.hasUtterance( responseGroupUtterance ) ) {
+          queue.removeUtterance( responseGroupUtterance );
+        }
+      } );
+    }
+  }
+
   /**
    * Apply a callback on each utteranceQueue that this Node has a connection to (via Display). Note that only
    * accessible Displays have utteranceQueues that this function will interface with.

js/accessibility/pdom/responseGroupRegistry.ts

@@ -45,6 +45,14 @@ class ResponseGroupRegistry {
     return utterance;
   }
 
+  /**
+   * Return the Utterance for a group, or null if none exists.
+   */
+  public getGroupUtterance( group: string ): Utterance | null {
+    assert && assert( group.trim().length > 0, 'group must be a non-empty string' );
+    return this.groupMap.get( group ) || null;
+  }
+
   /**
    * Remove a single group from the registry.
    */