feat: aria live region for announcements

Author: mikeharv

packages/blockly/core/css.ts

@@ -529,4 +529,12 @@ input[type=number] {
 ) {
   outline: none;
 }
+.hiddenForAria {
+  position: absolute;
+  left: -9999px;
+  width: 1px;
+  height: 1px;
+  overflow: hidden;
+  white-space: nowrap;
+}
 `;

packages/blockly/core/inject.ts

@@ -17,6 +17,7 @@ import {Options} from './options.js';
 import {ScrollbarPair} from './scrollbar_pair.js';
 import * as Tooltip from './tooltip.js';
 import * as Touch from './touch.js';
+import * as aria from './utils/aria.js';
 import * as dom from './utils/dom.js';
 import {Svg} from './utils/svg.js';
 import * as WidgetDiv from './widgetdiv.js';
@@ -54,6 +55,9 @@ export function inject(
     dom.addClass(subContainer, 'blocklyRTL');
   }
 
+  // Ignore the subcontainer in aria since it is not focusable.
+  aria.setRole(subContainer, aria.Role.PRESENTATION);
+
   containerElement!.appendChild(subContainer);
   const svg = createDom(subContainer, options);
 
@@ -78,6 +82,8 @@ export function inject(
     common.globalShortcutHandler,
   );
 
+  aria.createLiveRegion(subContainer);
+
   return workspace;
 }
 

packages/blockly/core/utils/aria.ts

@@ -6,12 +6,33 @@
 
 // Former goog.module ID: Blockly.utils.aria
 
+import * as dom from './dom.js';
+
 /** ARIA states/properties prefix. */
 const ARIA_PREFIX = 'aria-';
 
 /** ARIA role attribute. */
 const ROLE_ATTRIBUTE = 'role';
 
+/**
+ * ARIA state values for LivePriority.
+ * Copied from Closure's goog.a11y.aria.LivePriority
+ */
+export enum LivePriority {
+  // This information has the highest priority and assistive technologies
+  // SHOULD notify the user immediately. Because an interruption may disorient
+  // users or cause them to not complete their current task, authors SHOULD NOT
+  // use the assertive value unless the interruption is imperative.
+  ASSERTIVE = 'assertive',
+  // Updates to the region will not be presented to the user unless the
+  // assistive teechnology is currently focused on that region.
+  OFF = 'off',
+  // (Background change) Assistive technologies SHOULD announce the updates at
+  // the next graceful opportunity, such as at the end of speaking the current
+  // sentence or when the users pauses typing.
+  POLITE = 'polite',
+}
+
 /**
  * ARIA role values.
  * Copied from Closure's goog.a11y.aria.Role
@@ -131,8 +152,12 @@ export enum State {
  * @param element DOM node to set role of.
  * @param roleName Role name.
  */
-export function setRole(element: Element, roleName: Role) {
-  element.setAttribute(ROLE_ATTRIBUTE, roleName);
+export function setRole(element: Element, roleName: Role | null) {
+  if (roleName) {
+    element.setAttribute(ROLE_ATTRIBUTE, roleName);
+  } else {
+    element.removeAttribute(ROLE_ATTRIBUTE);
+  }
 }
 
 /**
@@ -156,3 +181,85 @@ export function setState(
   const attrStateName = ARIA_PREFIX + stateName;
   element.setAttribute(attrStateName, `${value}`);
 }
+
+/**
+ * Creates the centralized ARIA live region used to announce dynamic state
+ * changes to screen readers. This live region is visually hidden but exposed to
+ * assistive technologies.
+ *
+ * Only one live region should exist per Blockly injection. This function should
+ * be called during workspace/injection setup to create the region inside the
+ * Blockly container.
+ *
+ * See: https://stackoverflow.com/a/48590836 for a reference.
+ *
+ * @param container The container element to which the live region will be
+ *     appended.
+ */
+export function createLiveRegion(container: HTMLDivElement) {
+  const ariaAnnouncementDiv = document.createElement('div');
+  ariaAnnouncementDiv.textContent = '';
+  ariaAnnouncementDiv.id = 'blocklyAriaAnnounce';
+  dom.addClass(ariaAnnouncementDiv, 'hiddenForAria');
+  setState(ariaAnnouncementDiv, State.LIVE, LivePriority.POLITE);
+  container.appendChild(ariaAnnouncementDiv);
+}
+
+let ariaAnnounceTimeout: ReturnType<typeof setTimeout>;
+let addBreakingSpace = false;
+
+/**
+ * Requests that the specified text be announced to the user via a centrally
+ * managed ARIA live region, if a screen reader is active.
+ *
+ * Announcements are scheduled asynchronously. If this function is called again
+ * before a pending announcement is inserted into the live region, the pending
+ * announcement is canceled and replaced with the new one.
+ *
+ * The live region element must have id `blocklyAriaAnnounce`. Its `aria-live`
+ * politeness setting and optional `role` are updated before the message is
+ * inserted so screen readers announce the content correctly.
+ *
+ * A non-breaking space is alternated at the end of the message to ensure that
+ * repeated messages are still announced by screen readers.
+ *
+ * Callers should use this judiciously. Over-announcing can reduce usability,
+ * so this should primarily be used for dynamic states or information that
+ * cannot be conveyed through standard ARIA semantics.
+ *
+ * @param text The text to announce to the user.
+ * @param options Configuration options for the announcement.
+ * @param options.assertiveness The ARIA live region priority
+ * @param options.role Optional ARIA role to apply to the live region before
+ */
+export function announceDynamicAriaState(
+  text: string,
+  options: {
+    assertiveness: LivePriority;
+    role: Role | null;
+  } = {
+    assertiveness: LivePriority.POLITE,
+    role: null,
+  },
+) {
+  const ariaAnnouncementContainer = document.getElementById(
+    'blocklyAriaAnnounce',
+  );
+  if (!ariaAnnouncementContainer) {
+    throw new Error('Expected element with id blocklyAriaAnnounce to exist.');
+  }
+  const {assertiveness, role} = options;
+
+  // Clear previous content.
+  ariaAnnouncementContainer.replaceChildren();
+  setState(ariaAnnouncementContainer, State.LIVE, assertiveness);
+
+  clearTimeout(ariaAnnounceTimeout);
+  ariaAnnounceTimeout = setTimeout(() => {
+    setRole(ariaAnnouncementContainer, role);
+    const p = document.createElement('p');
+    p.textContent = text + (addBreakingSpace ? '\u00A0' : '');
+    addBreakingSpace = !addBreakingSpace;
+    ariaAnnouncementContainer.appendChild(p);
+  }, 10);
+}