Chris@0: /**
Chris@0:  * @file
Chris@0:  * Adds an HTML element and method to trigger audio UAs to read system messages.
Chris@0:  *
Chris@0:  * Use {@link Drupal.announce} to indicate to screen reader users that an
Chris@0:  * element on the page has changed state. For instance, if clicking a link
Chris@0:  * loads 10 more items into a list, one might announce the change like this.
Chris@0:  *
Chris@0:  * @example
Chris@0:  * $('#search-list')
Chris@0:  *   .on('itemInsert', function (event, data) {
Chris@0:  *     // Insert the new items.
Chris@0:  *     $(data.container.el).append(data.items.el);
Chris@0:  *     // Announce the change to the page contents.
Chris@0:  *     Drupal.announce(Drupal.t('@count items added to @container',
Chris@0:  *       {'@count': data.items.length, '@container': data.container.title}
Chris@0:  *     ));
Chris@0:  *   });
Chris@0:  */
Chris@0: 
Chris@17: (function(Drupal, debounce) {
Chris@0:   let liveElement;
Chris@0:   const announcements = [];
Chris@0: 
Chris@0:   /**
Chris@0:    * Builds a div element with the aria-live attribute and add it to the DOM.
Chris@0:    *
Chris@0:    * @type {Drupal~behavior}
Chris@0:    *
Chris@0:    * @prop {Drupal~behaviorAttach} attach
Chris@17:    *   Attaches the behavior for drupalAnnounce.
Chris@0:    */
Chris@0:   Drupal.behaviors.drupalAnnounce = {
Chris@0:     attach(context) {
Chris@0:       // Create only one aria-live element.
Chris@0:       if (!liveElement) {
Chris@0:         liveElement = document.createElement('div');
Chris@0:         liveElement.id = 'drupal-live-announce';
Chris@0:         liveElement.className = 'visually-hidden';
Chris@0:         liveElement.setAttribute('aria-live', 'polite');
Chris@0:         liveElement.setAttribute('aria-busy', 'false');
Chris@0:         document.body.appendChild(liveElement);
Chris@0:       }
Chris@0:     },
Chris@0:   };
Chris@0: 
Chris@0:   /**
Chris@0:    * Concatenates announcements to a single string; appends to the live region.
Chris@0:    */
Chris@0:   function announce() {
Chris@0:     const text = [];
Chris@0:     let priority = 'polite';
Chris@0:     let announcement;
Chris@0: 
Chris@0:     // Create an array of announcement strings to be joined and appended to the
Chris@0:     // aria live region.
Chris@0:     const il = announcements.length;
Chris@0:     for (let i = 0; i < il; i++) {
Chris@0:       announcement = announcements.pop();
Chris@0:       text.unshift(announcement.text);
Chris@0:       // If any of the announcements has a priority of assertive then the group
Chris@0:       // of joined announcements will have this priority.
Chris@0:       if (announcement.priority === 'assertive') {
Chris@0:         priority = 'assertive';
Chris@0:       }
Chris@0:     }
Chris@0: 
Chris@0:     if (text.length) {
Chris@0:       // Clear the liveElement so that repeated strings will be read.
Chris@0:       liveElement.innerHTML = '';
Chris@0:       // Set the busy state to true until the node changes are complete.
Chris@0:       liveElement.setAttribute('aria-busy', 'true');
Chris@0:       // Set the priority to assertive, or default to polite.
Chris@0:       liveElement.setAttribute('aria-live', priority);
Chris@0:       // Print the text to the live region. Text should be run through
Chris@0:       // Drupal.t() before being passed to Drupal.announce().
Chris@0:       liveElement.innerHTML = text.join('\n');
Chris@0:       // The live text area is updated. Allow the AT to announce the text.
Chris@0:       liveElement.setAttribute('aria-busy', 'false');
Chris@0:     }
Chris@0:   }
Chris@0: 
Chris@0:   /**
Chris@0:    * Triggers audio UAs to read the supplied text.
Chris@0:    *
Chris@0:    * The aria-live region will only read the text that currently populates its
Chris@0:    * text node. Replacing text quickly in rapid calls to announce results in
Chris@0:    * only the text from the most recent call to {@link Drupal.announce} being
Chris@0:    * read. By wrapping the call to announce in a debounce function, we allow for
Chris@0:    * time for multiple calls to {@link Drupal.announce} to queue up their
Chris@0:    * messages. These messages are then joined and append to the aria-live region
Chris@0:    * as one text node.
Chris@0:    *
Chris@0:    * @param {string} text
Chris@0:    *   A string to be read by the UA.
Chris@0:    * @param {string} [priority='polite']
Chris@0:    *   A string to indicate the priority of the message. Can be either
Chris@0:    *   'polite' or 'assertive'.
Chris@0:    *
Chris@0:    * @return {function}
Chris@0:    *   The return of the call to debounce.
Chris@0:    *
Chris@0:    * @see http://www.w3.org/WAI/PF/aria-practices/#liveprops
Chris@0:    */
Chris@17:   Drupal.announce = function(text, priority) {
Chris@0:     // Save the text and priority into a closure variable. Multiple simultaneous
Chris@0:     // announcements will be concatenated and read in sequence.
Chris@0:     announcements.push({
Chris@0:       text,
Chris@0:       priority,
Chris@0:     });
Chris@0:     // Immediately invoke the function that debounce returns. 200 ms is right at
Chris@0:     // the cusp where humans notice a pause, so we will wait
Chris@0:     // at most this much time before the set of queued announcements is read.
Chris@17:     return debounce(announce, 200)();
Chris@0:   };
Chris@17: })(Drupal, Drupal.debounce);