chore: Split up monkey patches & type them.

Author: BenHenning

src/aria_monkey_patches.js

@@ -36,10 +36,15 @@ import {Mover} from './actions/mover';
 import {DuplicateAction} from './actions/duplicate';
 import {StackNavigationAction} from './actions/stack_navigation';
 
-import './aria_monkey_patches';
+import './screenreader/aria_monkey_patcher';
+import {FunctionStubber} from './screenreader/function_stubber_registry';
 
 const KeyCodes = BlocklyUtils.KeyCodes;
 
+// Note that prototype stubs must happen early in the page lifecycle in order to
+// take effect before Blockly loading.
+FunctionStubber.getInstance().stubPrototypes();
+
 /**
  * Class for registering shortcuts for keyboard navigation.
  */
@@ -292,5 +297,7 @@ export class NavigationController {
     }
     this.removeShortcutHandlers();
     this.navigation.dispose();
+
+    FunctionStubber.getInstance().unstubPrototypes();
   }
 }

src/navigation_controller.ts

@@ -0,0 +1,67 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * @fileoverview Overrides a bunch of methods throughout core Blockly in order
+ * to augment Blockly components with ARIA support.
+ */
+
+import * as aria from './aria';
+import './stuboverrides/override_block_svg'
+import './stuboverrides/override_collapsible_toolbox_category'
+import './stuboverrides/override_comment_icon'
+import './stuboverrides/override_field_checkbox'
+import './stuboverrides/override_field_dropdown'
+import './stuboverrides/override_field_image'
+import './stuboverrides/override_field_input'
+import './stuboverrides/override_field_label'
+import './stuboverrides/override_field'
+import './stuboverrides/override_flyout_button'
+import './stuboverrides/override_icon'
+import './stuboverrides/override_mutator_icon'
+import './stuboverrides/override_rendered_connection'
+import './stuboverrides/override_rendered_workspace_comment'
+import './stuboverrides/override_toolbox_category'
+import './stuboverrides/override_toolbox_separator'
+import './stuboverrides/override_toolbox'
+import './stuboverrides/override_warning_icon'
+import './stuboverrides/override_workspace_svg'
+
+const oldCreateElementNS = document.createElementNS;
+
+document.createElementNS = function (namepspaceURI, qualifiedName) {
+  const element = oldCreateElementNS.call(this, namepspaceURI, qualifiedName);
+  // Top-level SVG elements and groups are presentation by default. They will be
+  // specified more specifically elsewhere if they need to be readable.
+  if (qualifiedName === 'svg' || qualifiedName === 'g') {
+    aria.setRole(element, aria.Role.PRESENTATION);
+  }
+  return element;
+};
+
+const oldElementSetAttribute = Element.prototype.setAttribute;
+// TODO: Replace these cases with property augmentation here so that all aria
+// behavior is defined within this file.
+const ariaAttributeAllowlist = ['aria-disabled', 'aria-selected'];
+
+Element.prototype.setAttribute = function (name, value) {
+  // This is a hacky way to disable all aria changes in core Blockly since it's
+  // easier to just undefine everything globally and then conditionally reenable
+  // things with the correct definitions.
+  // TODO: Add an exemption for role here once all roles are properly defined
+  // within this file (see failing tests when role changes are ignored here).
+  if (
+    aria.isCurrentlyMutatingAriaProperty() ||
+    ariaAttributeAllowlist.includes(name) ||
+    !name.startsWith('aria-')
+  ) {
+    oldElementSetAttribute.call(this, name, value);
+  }
+};
+
+// TODO: Figure out how to patch CommentEditor. It doesn't seem to have any methods really to override, so it may actually require patching at the dom utility layer, or higher up.
+// TODO: Ditto for CommentBarButton and its children.
+// TODO: Ditto for Bubble and its children.

src/aria.ts renamed to src/screenreader/aria.ts

@@ -0,0 +1,116 @@
+import * as Blockly from 'blockly/core';
+import * as aria from './aria';
+
+export function computeBlockAriaLabel(block: Blockly.BlockSvg): string {
+  // Guess the block's aria label based on its field labels.
+  if (block.isShadow()) {
+    // TODO: Shadows may have more than one field.
+    // Shadow blocks are best represented directly by their field since they
+    // effectively operate like a field does for keyboard navigation purposes.
+    const field = Array.from(block.getFields())[0];
+    return aria.getState(field.getFocusableElement(), aria.State.LABEL) ?? 'Unknown?';
+  }
+
+  const fieldLabels = [];
+  for (const field of block.getFields()) {
+    if (field instanceof Blockly.FieldLabel) {
+      fieldLabels.push(field.getText());
+    }
+  }
+  return fieldLabels.join(' ');
+};
+
+function collectSiblingBlocks(block: Blockly.BlockSvg, surroundParent: Blockly.BlockSvg | null): Blockly.BlockSvg[] {
+  // NOTE TO DEVELOPERS: it's very important that these are NOT sorted. The
+  // returned list needs to be relatively stable for consistency block indexes
+  // read out to users via screen readers.
+  if (surroundParent) {
+    // Start from the first sibling and iterate in navigation order.
+    const firstSibling: Blockly.BlockSvg = surroundParent.getChildren(false)[0];
+    const siblings: Blockly.BlockSvg[] = [firstSibling];
+    let nextSibling: Blockly.BlockSvg | null = firstSibling;
+    while (nextSibling = nextSibling.getNextBlock()) {
+      siblings.push(nextSibling);
+    }
+    return siblings;
+  } else {
+    // For top-level blocks, simply return those from the workspace.
+    return block.workspace.getTopBlocks(false);
+  }
+}
+
+function computeLevelInWorkspace(block: Blockly.BlockSvg): number {
+  const surroundParent = block.getSurroundParent();
+  return surroundParent ? computeLevelInWorkspace(surroundParent) + 1 : 0;
+};
+
+// TODO: Do this efficiently (probably centrally).
+export function recomputeAriaTreeItemDetailsRecursively(block: Blockly.BlockSvg) {
+  const elem = block.getFocusableElement();
+  const connection = (block as any).currentConnectionCandidate;
+  let childPosition: number;
+  let parentsChildCount: number;
+  let hierarchyDepth: number;
+  if (connection) {
+    // If the block is being inserted into a new location, the position is hypothetical.
+    // TODO: Figure out how to deal with output connections.
+    let surroundParent: Blockly.BlockSvg | null;
+    let siblingBlocks: Blockly.BlockSvg[];
+    if (connection.type === Blockly.ConnectionType.INPUT_VALUE) {
+      surroundParent = connection.sourceBlock_;
+      siblingBlocks = collectSiblingBlocks(block, surroundParent);
+      // The block is being added as a child since it's input.
+      // TODO: Figure out how to compute the correct position.
+      childPosition = 1;
+    } else {
+      surroundParent = connection.sourceBlock_.getSurroundParent();
+      siblingBlocks = collectSiblingBlocks(block, surroundParent);
+      // The block is being added after the connected block.
+      childPosition = siblingBlocks.indexOf(connection.sourceBlock_) + 2;
+    }
+    parentsChildCount = siblingBlocks.length + 1;
+    hierarchyDepth = surroundParent ? computeLevelInWorkspace(surroundParent) + 1 : 1;
+  } else {
+    const surroundParent = block.getSurroundParent();
+    const siblingBlocks = collectSiblingBlocks(block, surroundParent);
+    childPosition = siblingBlocks.indexOf(block) + 1;
+    parentsChildCount = siblingBlocks.length;
+    hierarchyDepth = computeLevelInWorkspace(block) + 1;
+  }
+  aria.setState(elem, aria.State.POSINSET, childPosition);
+  aria.setState(elem, aria.State.SETSIZE, parentsChildCount);
+  aria.setState(elem, aria.State.LEVEL, hierarchyDepth);
+  block.getChildren(false).forEach((child) => recomputeAriaTreeItemDetailsRecursively(child));
+}
+
+export function announceDynamicAriaStateForBlock(block: Blockly.BlockSvg, isMoving: boolean, isCanceled: boolean, newLoc?: Blockly.utils.Coordinate) {
+  const connection = (block as any).currentConnectionCandidate;
+  if (isCanceled) {
+    aria.announceDynamicAriaState('Canceled movement');
+    return;
+  }
+  if (!isMoving) return;
+  if (connection) {
+    // TODO: Figure out general detachment.
+    // TODO: Figure out how to deal with output connections.
+    let surroundParent: Blockly.BlockSvg | null = connection.sourceBlock_;
+    const announcementContext = [];
+    announcementContext.push('Moving'); // TODO: Specialize for inserting?
+    // NB: Old code here doesn't seem to handle parents correctly.
+    if (connection.type === Blockly.ConnectionType.INPUT_VALUE) {
+      announcementContext.push('to', 'input');
+    } else {
+      announcementContext.push('to', 'child');
+    }
+    if (surroundParent) {
+      announcementContext.push('of', computeBlockAriaLabel(surroundParent));
+    }
+
+    // If the block is currently being moved, announce the new block label so that the user understands where it is now.
+    // TODO: Figure out how much recomputeAriaTreeItemDetailsRecursively needs to anticipate position if it won't be reannounced, and how much of that context should be included in the liveannouncement.
+    aria.announceDynamicAriaState(announcementContext.join(' '));
+  } else if (newLoc) {
+    // The block is being freely dragged.
+    aria.announceDynamicAriaState(`Moving unconstrained to coordinate x ${Math.round(newLoc.x)} and y ${Math.round(newLoc.y)}.`);
+  }
+}

src/screenreader/aria_monkey_patcher.js

@@ -0,0 +1,96 @@
+export type StubCallback<T> = (instance: T, ...args: any) => void;
+
+class Registration<T> {
+  private oldMethod: ((...args: any) => any) | null = null;
+
+  constructor(
+    readonly callback: StubCallback<T>,
+    readonly methodNameToOverride: string,
+    readonly classPrototype: T,
+    readonly ensureOneCall: boolean
+  ) {}
+
+  stubPrototype(): void {
+    // TODO: Figure out how to make this work with minification.
+    if (this.oldMethod) {
+      throw new Error(`Function is already stubbed: ${this.methodNameToOverride}.`);
+    }
+    const genericPrototype = this.classPrototype as any;
+    const oldMethod =
+      genericPrototype[this.methodNameToOverride] as (...args: any) => any;
+    this.oldMethod = oldMethod;
+    const registration = this;
+    genericPrototype[this.methodNameToOverride] = function (...args: any): any {
+      let stubsCalled =
+        this._internalStubsCalled as {[key: string]: boolean} | undefined;
+      if (!stubsCalled) {
+        stubsCalled = {};
+        this._internalStubsCalled = stubsCalled;
+      }
+
+      const result = oldMethod.call(this, ...args);
+      if (!registration.ensureOneCall || !stubsCalled[registration.methodNameToOverride]) {
+        registration.callback(this as unknown as T, ...args);
+        stubsCalled[registration.methodNameToOverride] = true;
+      }
+      return result;
+    };
+  }
+
+  unstubPrototype(): void {
+    if (this.oldMethod) {
+      throw new Error(`Function is not currently stubbed: ${this.methodNameToOverride}.`);
+    }
+    const genericPrototype = this.classPrototype as any;
+    genericPrototype[this.methodNameToOverride] = this.oldMethod;
+    this.oldMethod = null;
+  }
+}
+
+export class FunctionStubber {
+  private registrations: Registration<any>[] = [];
+  private isFinalized: boolean = false;
+
+  public registerInitializationStub<T>(
+    callback: StubCallback<T>,
+    methodNameToOverride: string,
+    classPrototype: T
+  ) {
+    if (this.isFinalized) {
+      throw new Error('Cannot register a stub after initialization has been completed.');
+    }
+    const registration = new Registration(callback, methodNameToOverride, classPrototype, true);
+    this.registrations.push(registration);
+  }
+
+  public registerMethodStub<T>(
+    callback: StubCallback<T>,
+    methodNameToOverride: string,
+    classPrototype: T
+  ) {
+    if (this.isFinalized) {
+      throw new Error('Cannot register a stub after initialization has been completed.');
+    }
+    const registration = new Registration(callback, methodNameToOverride, classPrototype, false);
+    this.registrations.push(registration);
+  }
+
+  public stubPrototypes() {
+    this.isFinalized = true;
+    this.registrations.forEach((registration) => registration.stubPrototype());
+  }
+
+  public unstubPrototypes() {
+    this.registrations.forEach((registration) => registration.unstubPrototype());
+    this.isFinalized = false;
+  }
+
+  private static instance: FunctionStubber | null = null;
+
+  static getInstance(): FunctionStubber {
+    if (!FunctionStubber.instance) {
+      FunctionStubber.instance = new FunctionStubber();
+    }
+    return FunctionStubber.instance;
+  }
+}

src/screenreader/block_svg_utilities.ts

@@ -0,0 +1,50 @@
+import {FunctionStubber} from '../function_stubber_registry';
+import * as Blockly from 'blockly/core';
+import * as aria from '../aria';
+import * as blockSvgUtils from '../block_svg_utilities';
+
+FunctionStubber.getInstance().registerInitializationStub((block) => {
+  const svgPath = block.getFocusableElement();
+  aria.setState(svgPath, aria.State.ROLEDESCRIPTION, 'block');
+  aria.setRole(svgPath, aria.Role.TREEITEM);
+  aria.setState(svgPath, aria.State.LABEL, blockSvgUtils.computeBlockAriaLabel(block));
+  svgPath.tabIndex = -1;
+  (block as any).currentConnectionCandidate = null;
+}, 'doInit_', Blockly.BlockSvg.prototype);
+
+FunctionStubber.getInstance().registerMethodStub((block) => {
+  block.workspace
+    .getTopBlocks(false)
+    .forEach((block) => blockSvgUtils.recomputeAriaTreeItemDetailsRecursively(block));
+}, 'setParent', Blockly.BlockSvg.prototype);
+
+FunctionStubber.getInstance().registerMethodStub((block) => {
+  (block as any).currentConnectionCandidate =
+  // @ts-expect-error Access to private property dragStrategy.
+  block.dragStrategy.connectionCandidate?.neighbour ?? null;
+  blockSvgUtils.announceDynamicAriaStateForBlock(block, true, false);
+}, 'startDrag', Blockly.BlockSvg.prototype);
+
+FunctionStubber.getInstance().registerMethodStub((block, newLoc: Blockly.utils.Coordinate) => {
+  (block as any).currentConnectionCandidate =
+  // @ts-expect-error Access to private property dragStrategy.
+  block.dragStrategy.connectionCandidate?.neighbour ?? null;
+  blockSvgUtils.announceDynamicAriaStateForBlock(block, true, false, newLoc);
+}, 'drag', Blockly.BlockSvg.prototype);
+
+FunctionStubber.getInstance().registerMethodStub((block) => {
+  (block as any).currentConnectionCandidate = null;
+  blockSvgUtils.announceDynamicAriaStateForBlock(block, false, false);
+}, 'endDrag', Blockly.BlockSvg.prototype);
+
+FunctionStubber.getInstance().registerMethodStub((block) => {
+  blockSvgUtils.announceDynamicAriaStateForBlock(block, false, true);
+}, 'revertDrag', Blockly.BlockSvg.prototype);
+
+FunctionStubber.getInstance().registerMethodStub((block) => {
+  aria.setState(block.getFocusableElement(), aria.State.SELECTED, true);
+}, 'onNodeFocus', Blockly.BlockSvg.prototype);
+
+FunctionStubber.getInstance().registerMethodStub((block) => {
+  aria.setState(block.getFocusableElement(), aria.State.SELECTED, false);
+}, 'onNodeBlur', Blockly.BlockSvg.prototype);

src/screenreader/function_stubber_registry.ts

@@ -0,0 +1,22 @@
+import {FunctionStubber} from '../function_stubber_registry';
+import * as Blockly from 'blockly/core';
+import * as aria from '../aria';
+import * as toolboxUtils from '../toolbox_utilities';
+
+FunctionStubber.getInstance().registerInitializationStub((category) => {
+  const element = category.getFocusableElement();
+  aria.setRole(element, aria.Role.GROUP);
+
+  // Ensure this group has properly set children.
+  const selectableChildren =
+  category.getChildToolboxItems().filter((item) => item.isSelectable()) ?? null;
+  const focusableChildIds = selectableChildren.map(
+    (selectable) => selectable.getFocusableElement().id,
+  );
+  aria.setState(
+    element,
+    aria.State.OWNS,
+    [...new Set(focusableChildIds)].join(' '),
+  );
+  toolboxUtils.recomputeAriaOwnersInToolbox(category.getFocusableTree() as Blockly.Toolbox);
+}, 'init', Blockly.CollapsibleToolboxCategory.prototype);

src/screenreader/stuboverrides/override_block_svg.ts

@@ -0,0 +1,12 @@
+import {FunctionStubber} from '../function_stubber_registry';
+import * as Blockly from 'blockly/core';
+import * as aria from '../aria';
+
+FunctionStubber.getInstance().registerInitializationStub((icon) => {
+  const element = icon.getFocusableElement();
+  aria.setState(
+    element,
+    aria.State.LABEL,
+    icon.bubbleIsVisible() ? 'Close Comment' : 'Open Comment',
+  );
+}, 'initView', Blockly.icons.CommentIcon.prototype);