fix: code review and add tests

Author: mikeharv

packages/blockly/core/css.ts

@@ -535,6 +535,5 @@ input[type=number] {
   width: 1px;
   height: 1px;
   overflow: hidden;
-  white-space: nowrap;
 }
 `;

packages/blockly/core/inject.ts

@@ -55,9 +55,6 @@ 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);
 
@@ -82,7 +79,7 @@ export function inject(
     common.globalShortcutHandler,
   );
 
-  aria.createLiveRegion(subContainer);
+  aria.initializeGlobalAriaLiveRegion(subContainer);
 
   return workspace;
 }

packages/blockly/core/utils/aria.ts

@@ -18,7 +18,7 @@ const ROLE_ATTRIBUTE = 'role';
  * ARIA state values for LivePriority.
  * Copied from Closure's goog.a11y.aria.LivePriority
  */
-export enum LivePriority {
+export enum LiveRegionAssertiveness {
   // 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
@@ -33,6 +33,23 @@ export enum LivePriority {
   POLITE = 'polite',
 }
 
+/**
+ * Customization options that can be passed when using `announceDynamicAriaState`.
+ */
+export interface DynamicAnnouncementOptions {
+  /** The custom ARIA `Role` that should be used for the announcement container. */
+  role?: Role;
+
+  /**
+   * How assertive the announcement should be.
+   *
+   * Important*: It was found through testing that `ASSERTIVE` announcements are
+   * often outright ignored by some screen readers, so it's generally recommended
+   * to always use `POLITE` unless specifically tested across supported readers.
+   */
+  assertiveness?: LiveRegionAssertiveness;
+}
+
 /**
  * ARIA role values.
  * Copied from Closure's goog.a11y.aria.Role
@@ -182,84 +199,74 @@ export function setState(
   element.setAttribute(attrStateName, `${value}`);
 }
 
+let liveRegionElement: HTMLElement | null = null;
+
 /**
- * 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.
+ * Creates an ARIA live region under the specified parent Element to be used
+ * for all dynamic announcements via `announceDynamicAriaState`. This must be
+ * called only once and before any dynamic announcements can be made.
  *
- * @param container The container element to which the live region will be
- *     appended.
+ * @param parent The container element to which the live region will be appended.
  */
-export function createLiveRegion(container: HTMLDivElement) {
+export function initializeGlobalAriaLiveRegion(parent: HTMLDivElement) {
+  if (liveRegionElement && document.contains(liveRegionElement)) {
+    return;
+  }
   const ariaAnnouncementDiv = document.createElement('div');
   ariaAnnouncementDiv.textContent = '';
   ariaAnnouncementDiv.id = 'blocklyAriaAnnounce';
   dom.addClass(ariaAnnouncementDiv, 'hiddenForAria');
-  setState(ariaAnnouncementDiv, State.LIVE, LivePriority.POLITE);
-  container.appendChild(ariaAnnouncementDiv);
+  setState(ariaAnnouncementDiv, State.LIVE, LiveRegionAssertiveness.POLITE);
+  setRole(ariaAnnouncementDiv, Role.STATUS);
+  ariaAnnouncementDiv.setAttribute('aria-atomic', 'true');
+  parent.appendChild(ariaAnnouncementDiv);
+  liveRegionElement = 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.
+ * Requests that the specified text be read to the user if a screen reader is
+ * currently active.
  *
- * A non-breaking space is alternated at the end of the message to ensure that
- * repeated messages are still announced by screen readers.
+ * This relies on a centrally managed ARIA live region that is hidden from the
+ * visual DOM. This live region is designed to try and ensure the text is read,
+ * including if the same text is issued multiple times consecutively. Note that
+ * `initializeGlobalAriaLiveRegion` must be called before this can be used.
  *
- * 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.
+ * Callers should use this judiciously. It's often considered bad practice to
+ * over-announce information that can be inferred from other sources on the page,
+ * so this ought to be used only when certain context cannot be easily determined
+ * (such as dynamic states that may not have perfect ARIA representations or
+ * indications).
  *
- * @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
+ * @param text The text to read to the user.
+ * @param options Custom options to configure the announcement. This defaults to no
+ *    custom `Role` and polite assertiveness.
  */
+
 export function announceDynamicAriaState(
   text: string,
-  options: {
-    assertiveness: LivePriority;
-    role: Role | null;
-  } = {
-    assertiveness: LivePriority.POLITE,
-    role: null,
-  },
+  options?: DynamicAnnouncementOptions,
 ) {
-  const ariaAnnouncementContainer = document.getElementById(
-    'blocklyAriaAnnounce',
-  );
-  if (!ariaAnnouncementContainer) {
-    throw new Error('Expected element with id blocklyAriaAnnounce to exist.');
+  if (!liveRegionElement) {
+    throw new Error('ARIA live region not initialized.');
   }
-  const {assertiveness, role} = options;
-
-  // Clear previous content.
-  ariaAnnouncementContainer.replaceChildren();
-  setState(ariaAnnouncementContainer, State.LIVE, assertiveness);
+  const ariaAnnouncementContainer = liveRegionElement;
+  const {assertiveness = LiveRegionAssertiveness.POLITE, role = null} =
+    options || {};
 
   clearTimeout(ariaAnnounceTimeout);
   ariaAnnounceTimeout = setTimeout(() => {
+    // Clear previous content.
+    ariaAnnouncementContainer.replaceChildren();
+    setState(ariaAnnouncementContainer, State.LIVE, assertiveness);
     setRole(ariaAnnouncementContainer, role);
-    const p = document.createElement('p');
-    p.textContent = text + (addBreakingSpace ? '\u00A0' : '');
+
+    const span = document.createElement('span');
+    span.textContent = text + (addBreakingSpace ? '\u00A0' : '');
     addBreakingSpace = !addBreakingSpace;
-    ariaAnnouncementContainer.appendChild(p);
+    ariaAnnouncementContainer.appendChild(span);
   }, 10);
 }

packages/blockly/tests/mocha/aria_live_region_test.js

@@ -0,0 +1,145 @@
+/**
+ * @license
+ * Copyright 2026 Raspberry Pi Foundation
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import {assert} from '../../node_modules/chai/index.js';
+import {
+  sharedTestSetup,
+  sharedTestTeardown,
+} from './test_helpers/setup_teardown.js';
+
+suite('Aria', function () {
+  setup(function () {
+    sharedTestSetup.call(this);
+    this.workspace = Blockly.inject('blocklyDiv', {});
+    this.liveRegion = document.getElementById('blocklyAriaAnnounce');
+    this.messageInLiveRegion = (message) => {
+      const liveRegion = this.liveRegion;
+      return !!(liveRegion && liveRegion.textContent === message);
+    };
+  });
+
+  teardown(function () {
+    sharedTestTeardown.call(this);
+  });
+
+  test('live region is created', function () {
+    assert.isNotNull(this.liveRegion);
+  });
+
+  test('live region has polite aria-live', function () {
+    assert.equal(this.liveRegion.getAttribute('aria-live'), 'polite');
+  });
+
+  test('live region has atomic true', function () {
+    assert.equal(this.liveRegion.getAttribute('aria-atomic'), 'true');
+  });
+
+  test('live region has status role by default', function () {
+    assert.equal(this.liveRegion.getAttribute('role'), 'status');
+  });
+
+  test('live region is visually hidden but not display none', function () {
+    const style = window.getComputedStyle(this.liveRegion);
+    assert.notEqual(style.display, 'none');
+  });
+
+  test('createLiveRegion only creates one region (singleton)', function () {
+    // Calling again should not create a duplicate.
+    Blockly.utils.aria.initializeGlobalAriaLiveRegion(
+      this.workspace.getInjectionDiv(),
+    );
+
+    const regions = this.workspace
+      .getInjectionDiv()
+      .querySelectorAll('#blocklyAriaAnnounce');
+
+    assert.equal(regions.length, 1);
+  });
+
+  test('announcement is delayed', function () {
+    Blockly.utils.aria.announceDynamicAriaState('Hello world');
+
+    assert.equal(this.liveRegion.textContent, '');
+
+    // Advance past the delay in announceDynamicAriaState.
+    this.clock.tick(11);
+    assert.include(this.liveRegion.textContent, 'Hello world');
+  });
+
+  test('repeated announcements are unique', function () {
+    Blockly.utils.aria.announceDynamicAriaState('Block moved');
+    this.clock.tick(11);
+
+    const first = this.liveRegion.textContent;
+
+    Blockly.utils.aria.announceDynamicAriaState('Block moved');
+    this.clock.tick(11);
+
+    const second = this.liveRegion.textContent;
+
+    assert.notEqual(first, second);
+  });
+
+  test('last write wins when called rapidly', function () {
+    Blockly.utils.aria.announceDynamicAriaState('First message');
+    Blockly.utils.aria.announceDynamicAriaState('Second message');
+    Blockly.utils.aria.announceDynamicAriaState('Final message');
+
+    this.clock.tick(11);
+
+    assert.include(this.liveRegion.textContent, 'Final message');
+  });
+
+  test('assertive option sets aria-live assertive', function () {
+    Blockly.utils.aria.announceDynamicAriaState('Warning', {
+      assertiveness: Blockly.utils.aria.LiveRegionAssertiveness.ASSERTIVE,
+      role: null,
+    });
+
+    this.clock.tick(11);
+
+    assert.equal(this.liveRegion.getAttribute('aria-live'), 'assertive');
+  });
+
+  test('role option updates role attribute', function () {
+    Blockly.utils.aria.announceDynamicAriaState('Alert message', {
+      assertiveness: Blockly.utils.aria.LiveRegionAssertiveness.POLITE,
+      role: Blockly.utils.aria.Role.GROUP,
+    });
+
+    this.clock.tick(11);
+
+    assert.equal(this.liveRegion.getAttribute('role'), 'group');
+  });
+
+  test('role and text update after delay', function () {
+    // Initial announcement to establish baseline role + text.
+    Blockly.utils.aria.announceDynamicAriaState('Initial message', {
+      assertiveness: Blockly.utils.aria.LiveRegionAssertiveness.POLITE,
+      role: Blockly.utils.aria.Role.STATUS,
+    });
+    this.clock.tick(11);
+
+    assert.equal(this.liveRegion.getAttribute('role'), 'status');
+    const initialText = this.liveRegion.textContent;
+
+    // Now announce with different role.
+    Blockly.utils.aria.announceDynamicAriaState('New message', {
+      assertiveness: Blockly.utils.aria.LiveRegionAssertiveness.POLITE,
+      role: null,
+    });
+
+    // Before delay: role and text should not have changed yet.
+    this.clock.tick(5);
+    assert.equal(this.liveRegion.getAttribute('role'), 'status');
+    assert.equal(this.liveRegion.textContent, initialText);
+
+    // After delay: both should update.
+    this.clock.tick(6);
+    assert.isNull(this.liveRegion.getAttribute('role'));
+    assert.include(this.liveRegion.textContent, 'New message');
+  });
+});

packages/blockly/tests/mocha/index.html

@@ -159,6 +159,7 @@
       import {javascriptGenerator} from '../../build/javascript.loader.mjs';
 
       // Import tests.
+      import './aria_live_region_test.js';
       import './block_json_test.js';
       import './block_test.js';
       import './clipboard_test.js';