chore: Add docs & remove unnecessary bits.

This addresses all lint warnings.

Author: BenHenning

src/screenreader/aria.ts

@@ -7,57 +7,43 @@
 const ARIA_PREFIX = 'aria-';
 const ROLE_ATTRIBUTE = 'role';
 
-// TODO: Finalize this.
+/** Represents an ARIA role that an element may have. */
 export enum Role {
-  GRID = 'grid',
-  GRIDCELL = 'gridcell',
   GROUP = 'group',
   LISTBOX = 'listbox',
-  MENU = 'menu',
-  MENUITEM = 'menuitem',
-  MENUITEMCHECKBOX = 'menuitemcheckbox',
-  OPTION = 'option',
   PRESENTATION = 'presentation',
-  ROW = 'row',
   TREE = 'tree',
   TREEITEM = 'treeitem',
   SEPARATOR = 'separator',
-  STATUS = 'status',
-  REGION = 'region',
   IMAGE = 'image',
   FIGURE = 'figure',
   BUTTON = 'button',
   CHECKBOX = 'checkbox',
   TEXTBOX = 'textbox',
-  APPLICATION = 'application',
 }
 
-// TODO: Finalize this.
+/** Represents ARIA-specific state that can be configured for an element. */
 export enum State {
-  ACTIVEDESCENDANT = 'activedescendant',
-  COLCOUNT = 'colcount',
-  DISABLED = 'disabled',
-  EXPANDED = 'expanded',
-  INVALID = 'invalid',
   LABEL = 'label',
-  LABELLEDBY = 'labelledby',
   LEVEL = 'level',
-  ORIENTATION = 'orientation',
   POSINSET = 'posinset',
-  ROWCOUNT = 'rowcount',
   SELECTED = 'selected',
   SETSIZE = 'setsize',
-  VALUEMAX = 'valuemax',
-  VALUEMIN = 'valuemin',
   LIVE = 'live',
   HIDDEN = 'hidden',
   ROLEDESCRIPTION = 'roledescription',
-  ATOMIC = 'atomic',
   OWNS = 'owns',
 }
 
 let isMutatingAriaProperty = false;
 
+/**
+ * Updates the specific role for the specified element.
+ *
+ * @param element The element whose ARIA role should be changed.
+ * @param roleName The new role for the specified element, or null if its role
+ *     should be cleared.
+ */
 export function setRole(element: Element, roleName: Role | null) {
   isMutatingAriaProperty = true;
   if (roleName) {
@@ -66,6 +52,13 @@ export function setRole(element: Element, roleName: Role | null) {
   isMutatingAriaProperty = false;
 }
 
+/**
+ * Returns the ARIA role of the specified element, or null if it either doesn't
+ * have a designated role or if that role is unknown.
+ *
+ * @param element The element from which to retrieve its ARIA role.
+ * @returns The ARIA role of the element, or null if undefined or unknown.
+ */
 export function getRole(element: Element): Role | null {
   // This is an unsafe cast which is why it needs to be checked to ensure that
   // it references a valid role.
@@ -76,6 +69,18 @@ export function getRole(element: Element): Role | null {
   return null;
 }
 
+/**
+ * Sets the specified ARIA state by its name and value for the specified
+ * element.
+ *
+ * Note that the type of value is not validated against the specific type of
+ * state being changed, so it's up to callers to ensure the correct value is
+ * used for the given state.
+ *
+ * @param element The element whose ARIA state may be changed.
+ * @param stateName The state to change.
+ * @param value The new value to specify for the provided state.
+ */
 export function setState(
   element: Element,
   stateName: State,
@@ -90,11 +95,39 @@ export function setState(
   isMutatingAriaProperty = false;
 }
 
+/**
+ * Returns a string representation of the specified state for the specified
+ * element, or null if it's not defined or specified.
+ *
+ * Note that an explicit set state of 'null' will return the 'null' string, not
+ * the value null.
+ *
+ * @param element The element whose state is being retrieved.
+ * @param stateName The state to retrieve.
+ * @returns The string representation of the requested state for the specified
+ *     element, or null if not defined.
+ */
 export function getState(element: Element, stateName: State): string | null {
   const attrStateName = ARIA_PREFIX + stateName;
   return element.getAttribute(attrStateName);
 }
 
+/**
+ * Softly requests that the specified text be read to the user if a screen
+ * reader is currently active.
+ *
+ * This relies on a centrally managed ARIA live region that should not interrupt
+ * existing announcements (that is, this is what's considered a polite
+ * announcement).
+ *
+ * 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 only be used 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 politely read to the user.
+ */
 export function announceDynamicAriaState(text: string) {
   const ariaAnnouncementSpan = document.getElementById('blocklyAriaAnnounce');
   if (!ariaAnnouncementSpan) {
@@ -103,6 +136,12 @@ export function announceDynamicAriaState(text: string) {
   ariaAnnouncementSpan.innerHTML = text;
 }
 
+/**
+ * Determines whether an ARIA property is in the process of being changed.
+ *
+ * @returns Returns whether an ARIA property is changing for any element,
+ *     specifically via setRole() or stateState().
+ */
 export function isCurrentlyMutatingAriaProperty(): boolean {
   return isMutatingAriaProperty;
 }

src/screenreader/block_svg_utilities.ts

@@ -1,6 +1,18 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
 import * as Blockly from 'blockly/core';
 import * as aria from './aria';
 
+/**
+ * Computes the human-readable ARIA label for the specified block.
+ *
+ * @param block The block whose label should be computed.
+ * @returns A human-readable ARIA label/representation for the block.
+ */
 export function computeBlockAriaLabel(block: Blockly.BlockSvg): string {
   // Guess the block's aria label based on its field labels.
   if (block.isShadow()) {
@@ -49,12 +61,27 @@ function computeLevelInWorkspace(block: Blockly.BlockSvg): number {
   return surroundParent ? computeLevelInWorkspace(surroundParent) + 1 : 0;
 }
 
-// TODO: Do this efficiently (probably centrally).
-export function recomputeAriaTreeItemDetailsRecursively(
-  block: Blockly.BlockSvg,
+/**
+ * Recomputes all BlockSvg ARIA tree structures in the workspace.
+ *
+ * This is a fairly expensive operation and should ideally only be performed
+ * when a block structure or relationship change has been made.
+ *
+ * @param workspace The workspace whose top-level blocks may need a tree
+ *     structure recomputation.
+ */
+export function recomputeAllWorkspaceAriaTrees(
+  workspace: Blockly.WorkspaceSvg,
 ) {
+  // TODO: Do this efficiently (probably increementally).
+  workspace
+    .getTopBlocks(false)
+    .forEach((block) => recomputeAriaTreeItemDetailsRecursively(block));
+}
+
+function recomputeAriaTreeItemDetailsRecursively(block: Blockly.BlockSvg) {
   const elem = block.getFocusableElement();
-  const connection = (block as any).currentConnectionCandidate;
+  const connection = getCurrentConnectionCandidate(block);
   let childPosition: number;
   let parentsChildCount: number;
   let hierarchyDepth: number;
@@ -94,13 +121,26 @@ export function recomputeAriaTreeItemDetailsRecursively(
     .forEach((child) => recomputeAriaTreeItemDetailsRecursively(child));
 }
 
+/**
+ * Announces the current dynamic state of the specified block, if any.
+ *
+ * An example of dynamic state is whether the block is currently being moved,
+ * and in what way. These states aren't represented through ARIA directly, so
+ * they need to be determined and announced using an ARIA live region
+ * (see aria.announceDynamicAriaState).
+ *
+ * @param block The block whose dynamic state should maybe be announced.
+ * @param isMoving Whether the specified block is currently being moved.
+ * @param isCanceled Whether the previous movement operation has been canceled.
+ * @param newLoc The new location the block is moving to (if unconstrained).
+ */
 export function announceDynamicAriaStateForBlock(
   block: Blockly.BlockSvg,
   isMoving: boolean,
   isCanceled: boolean,
   newLoc?: Blockly.utils.Coordinate,
 ) {
-  const connection = (block as any).currentConnectionCandidate;
+  const connection = getCurrentConnectionCandidate(block);
   if (isCanceled) {
     aria.announceDynamicAriaState('Canceled movement');
     return;
@@ -132,3 +172,33 @@ export function announceDynamicAriaStateForBlock(
     );
   }
 }
+
+interface ConnectionCandidateHolder {
+  currentConnectionCandidate: Blockly.RenderedConnection | null;
+}
+
+function getCurrentConnectionCandidate(
+  block: Blockly.BlockSvg,
+): Blockly.RenderedConnection | null {
+  const connectionHolder = block as unknown as ConnectionCandidateHolder;
+  return connectionHolder.currentConnectionCandidate;
+}
+
+/**
+ * Updates the current connection candidate for the specified block (that is,
+ * the connection the block is being connected to).
+ *
+ * This corresponds to a temporary property used when determining specifics of
+ * a block's location when being moved.
+ *
+ * @param block The block which may have a new connection candidate.
+ * @param connection The latest connection candidate for the block, or null if
+ *     none.
+ */
+export function setCurrentConnectionCandidate(
+  block: Blockly.BlockSvg,
+  connection: Blockly.RenderedConnection | null,
+) {
+  const connectionHolder = block as unknown as ConnectionCandidateHolder;
+  connectionHolder.currentConnectionCandidate = connection;
+}

src/screenreader/function_stubber_registry.ts

@@ -1,6 +1,18 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * A function callback used to run after an overridden stub method using
+ * FunctionStubber.
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
 export type StubCallback<T> = (instance: T, ...args: any) => void;
 
 class Registration<T> {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
   private oldMethod: ((...args: any) => any) | null = null;
 
   constructor(
@@ -17,13 +29,17 @@ class Registration<T> {
         `Function is already stubbed: ${this.methodNameToOverride}.`,
       );
     }
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
     const genericPrototype = this.classPrototype as any;
     const oldMethod = genericPrototype[this.methodNameToOverride] as (
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
       ...args: any
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
     ) => any;
     this.oldMethod = oldMethod;
     // eslint-disable-next-line @typescript-eslint/no-this-alias
     const registration = this;
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
     genericPrototype[this.methodNameToOverride] = function (...args: any): any {
       let stubsCalled = this._internalStubsCalled as
         | {[key: string]: boolean}
@@ -46,10 +62,43 @@ class Registration<T> {
   }
 }
 
+/**
+ * Utility for augmenting a class's functionality by monkey-patching a
+ * function's prototype in order to call a custom function.
+ *
+ * Note that all custom functions are always run after the original function
+ * runs. This order cannot be configured, nor can the original function be
+ * disabled.
+ *
+ * There are two types of overrides possible: initialization via
+ * registerInitializationStub() and regular class methods via
+ * registerMethodStub().
+ *
+ * Instances of this class should retrieved using getInstance().
+ *
+ * IMPORTANT: In order for stubbing to work correctly, see the caveats of
+ * stubPrototypes().
+ */
 export class FunctionStubber {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
   private registrations: Array<Registration<any>> = [];
   private isFinalized = false;
 
+  /**
+   * Registers a new initialization stub.
+   *
+   * Initialization stub callbacks are only invoked once per instance of a given
+   * object, even if that function is called multiple times. This allows for
+   * methods called in a class's constructor to be used as a proxy for the
+   * constructor itself.
+   *
+   * This will throw an error if called after stubPrototypes() has been called.
+   *
+   * @param callback The function to run when the stubbed method executes for
+   *     the first time.
+   * @param methodNameToOverride The name of the method to override.
+   * @param classPrototype The prototype of the class being stubbed.
+   */
   registerInitializationStub<T>(
     callback: StubCallback<T>,
     methodNameToOverride: string,
@@ -69,6 +118,18 @@ export class FunctionStubber {
     this.registrations.push(registration);
   }
 
+  /**
+   * Registers a new method stub.
+   *
+   * Method stub callbacks are invoked every time the overridden method is
+   * invoked.
+   *
+   * This will throw an error if called after stubPrototypes() has been called.
+   *
+   * @param callback The function to run when the stubbed method executes.
+   * @param methodNameToOverride The name of the method to override.
+   * @param classPrototype The prototype of the class being stubbed.
+   */
   registerMethodStub<T>(
     callback: StubCallback<T>,
     methodNameToOverride: string,
@@ -88,13 +149,23 @@ export class FunctionStubber {
     this.registrations.push(registration);
   }
 
+  /**
+   * Performs the actual monkey-patching to enable the custom registered
+   * callbacks from registerInitializationStub() and registerMethodStub() to
+   * work correctly.
+   *
+   * IMPORTANT: This must be called after all registration is completed, and
+   * before any of the stubbed classes are actually used. This cannot be undone
+   * (that is, there is no deregistration).
+   */
   stubPrototypes() {
     this.isFinalized = true;
     this.registrations.forEach((registration) => registration.stubPrototype());
   }
 
   private static instance: FunctionStubber | null = null;
 
+  /** Returns the page-global instance of this FunctionStubber. */
   static getInstance(): FunctionStubber {
     if (!FunctionStubber.instance) {
       FunctionStubber.instance = new FunctionStubber();