announce.es6.js 4.2 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117
  1. /**
  2. * @file
  3. * Adds an HTML element and method to trigger audio UAs to read system messages.
  4. *
  5. * Use {@link Drupal.announce} to indicate to screen reader users that an
  6. * element on the page has changed state. For instance, if clicking a link
  7. * loads 10 more items into a list, one might announce the change like this.
  8. *
  9. * @example
  10. * $('#search-list')
  11. * .on('itemInsert', function (event, data) {
  12. * // Insert the new items.
  13. * $(data.container.el).append(data.items.el);
  14. * // Announce the change to the page contents.
  15. * Drupal.announce(Drupal.t('@count items added to @container',
  16. * {'@count': data.items.length, '@container': data.container.title}
  17. * ));
  18. * });
  19. */
  20. (function (Drupal, debounce) {
  21. let liveElement;
  22. const announcements = [];
  23. /**
  24. * Builds a div element with the aria-live attribute and add it to the DOM.
  25. *
  26. * @type {Drupal~behavior}
  27. *
  28. * @prop {Drupal~behaviorAttach} attach
  29. * Attaches the behavior for drupalAnnouce.
  30. */
  31. Drupal.behaviors.drupalAnnounce = {
  32. attach(context) {
  33. // Create only one aria-live element.
  34. if (!liveElement) {
  35. liveElement = document.createElement('div');
  36. liveElement.id = 'drupal-live-announce';
  37. liveElement.className = 'visually-hidden';
  38. liveElement.setAttribute('aria-live', 'polite');
  39. liveElement.setAttribute('aria-busy', 'false');
  40. document.body.appendChild(liveElement);
  41. }
  42. },
  43. };
  44. /**
  45. * Concatenates announcements to a single string; appends to the live region.
  46. */
  47. function announce() {
  48. const text = [];
  49. let priority = 'polite';
  50. let announcement;
  51. // Create an array of announcement strings to be joined and appended to the
  52. // aria live region.
  53. const il = announcements.length;
  54. for (let i = 0; i < il; i++) {
  55. announcement = announcements.pop();
  56. text.unshift(announcement.text);
  57. // If any of the announcements has a priority of assertive then the group
  58. // of joined announcements will have this priority.
  59. if (announcement.priority === 'assertive') {
  60. priority = 'assertive';
  61. }
  62. }
  63. if (text.length) {
  64. // Clear the liveElement so that repeated strings will be read.
  65. liveElement.innerHTML = '';
  66. // Set the busy state to true until the node changes are complete.
  67. liveElement.setAttribute('aria-busy', 'true');
  68. // Set the priority to assertive, or default to polite.
  69. liveElement.setAttribute('aria-live', priority);
  70. // Print the text to the live region. Text should be run through
  71. // Drupal.t() before being passed to Drupal.announce().
  72. liveElement.innerHTML = text.join('\n');
  73. // The live text area is updated. Allow the AT to announce the text.
  74. liveElement.setAttribute('aria-busy', 'false');
  75. }
  76. }
  77. /**
  78. * Triggers audio UAs to read the supplied text.
  79. *
  80. * The aria-live region will only read the text that currently populates its
  81. * text node. Replacing text quickly in rapid calls to announce results in
  82. * only the text from the most recent call to {@link Drupal.announce} being
  83. * read. By wrapping the call to announce in a debounce function, we allow for
  84. * time for multiple calls to {@link Drupal.announce} to queue up their
  85. * messages. These messages are then joined and append to the aria-live region
  86. * as one text node.
  87. *
  88. * @param {string} text
  89. * A string to be read by the UA.
  90. * @param {string} [priority='polite']
  91. * A string to indicate the priority of the message. Can be either
  92. * 'polite' or 'assertive'.
  93. *
  94. * @return {function}
  95. * The return of the call to debounce.
  96. *
  97. * @see http://www.w3.org/WAI/PF/aria-practices/#liveprops
  98. */
  99. Drupal.announce = function (text, priority) {
  100. // Save the text and priority into a closure variable. Multiple simultaneous
  101. // announcements will be concatenated and read in sequence.
  102. announcements.push({
  103. text,
  104. priority,
  105. });
  106. // Immediately invoke the function that debounce returns. 200 ms is right at
  107. // the cusp where humans notice a pause, so we will wait
  108. // at most this much time before the set of queued announcements is read.
  109. return (debounce(announce, 200)());
  110. };
  111. }(Drupal, Drupal.debounce));