feat: Fix ARIA roles and setup for fields (experimental) (#9384)

## The basics - [x] I [validated my changes](https://developers.google.com/blockly/guides/contribute/core#making_and_verifying_a_change) ## The details ### Resolves Fixes #8206 Fixes #8210 Fixes #8213 Fixes #8255 Fixes #8211 Fixes #8212 Fixes #8254 Fixes part of #9301 Fixes part of #9304 ### Proposed Changes This PR completes the remaining ARIA roles and properties needed for all core fields. Specifically: - #8206: A better name needed to be used for the checkbox value, plus there was an ARIA property missing for actually representing the checkbox state. The latter needed to be updated upon toggling the checkbox, as well. These changes bring checkbox fields in compliance with the ARIA checkbox pattern documented here: https://www.w3.org/WAI/ARIA/apg/patterns/checkbox/. - #8210: This one required a lot of changes in order to adapt to the ARIA combobox pattern documented here: https://www.w3.org/WAI/ARIA/apg/patterns/combobox/. Specifically: - Menus needed to have a unique ID that's also exposed in order to link the combobox element to its menu when open. - ARIA's `activedescendant` proved very useful in ensuring that the current dropdown selection is correctly read when the combobox has focus but its menu isn't opened. - The default properties available for options (label and value) aren't very good for readout, so a custom ARIA property was added for much clearer option readouts. This is only demonstrated for the math arithmetic block for now. - The text element is normally hidden for ARIA but it's useful in conjunction with `activedescendant` to represent the current value selection. - Images have been handled here as well (partly as part of #8255) by leveraging their alt text for readouts. This actually seems to work quite well both for current value and selection. - #8213: Much of the improvements here come from the combobox (`FieldDropdown`) improvements explained above. However one additional bit was done to provide an explicit 'Variable <name>' readout for the purpose of clarity. This demonstrates some contextualization of the value of the field which may be a generally useful pattern to copy in other field contexts. - #8255: Image fields have been refined since they were redundantly specifying 'image' when an `image` ARIA role is already being used. Now only the alt text is supplied along with the role context. Note that images need special handling since they can sometimes be navigable (such as when they have click handlers). - #8211: Text input fields have had their labeling improved like all other fields, and the field's value is now exposed via its `text` element since this will show up as a `StaticText` node in the accessibility tree and automatically be read as part of the field's value. - #8212: This gets the same benefits as the previous point since those improvements were included for both text and number input. However, existing `valuemin` and `valuemax` ARIA properties have been removed. It seems these are really only useful when introducing a slider mechanism (see https://www.w3.org/WAI/ARIA/apg/patterns/slider/) and from testing seems to not really be utilized for the basic text input that `FieldNumber` currently uses. It may be the case that this is a better pattern to use in the future, but it's more likely that other custom fields could benefit from more specific patterns like slider rather than `FieldNumber` being changed in that way. - #8254 and part of #9304: Field labels have been completely removed from the accessibility node tree since they can never be navigated to (as #8254 explains all labels will be included as part of the block's ARIA label itself for readout parity with navigation options). Note that it doesn't cover external fields (such as those supplied in blockly-samples), nor does it fully set up the infrastructure work for those. Ultimately that work needs to happen as part of #9301. Beyond the role work above, this PR also introduces some fundamental work for #9301. Specifically: - It demonstrates how block definitions could be used to introduce accessibility label customizations (in this case for the options of the arithmetic operator block's drop-down field, plus the block itself). - It sets up some central label computation for all fields, though more thought is needed on whether this is sufficient for custom fields outside of core Blockly and on how to properly contextualize labels for field values. Core Blockly's fields are fairly simple for representing values which is why that aspect of #9301 didn't need to be solved in this PR. Note that the field labeling here is being used to improve all of the fields above, but also it tries to aggressively fall back to the _next best_ label to be used (though it's possible to run out of options which is why fields still need contextually-specific fallbacks). ### Reason for Changes Generally the initial approach for implementing labels is leveraging as specific ARIA roles as exist to directly represent the element. This PR is completing that work for all of core Blockly's built-in fields, and laying some of the groundwork for generalizing this support for custom fields. Having specific roles does potentially introduce inconsistencies across screen readers (though should improve consistency across sites for a single screen reader), and expectations for behaviors (like shortcuts) that may need to be ignored or only partially supported (#9313 is discussing this). ### Test Coverage Only manual testing has been completed since this is experimental work. Video demonstrating most of the changes: [Screen recording 2025-10-01 4.05.35 PM.webm](https://github.com/user-attachments/assets/c7961caa-eae0-4585-8fd9-87d7cbe65988) ### Documentation N/A -- Experimental work. ### Additional Information This has only been tested on ChromeVox.
2025-12-15 13:50:08 +01:00 · 2025-10-01 16:19:06 -07:00
parent 76c734598b
commit 3cf834a6a6
19 changed files with 193 additions and 74 deletions
--- a/blocks/math.ts
+++ b/blocks/math.ts
@@ -54,12 +54,13 @@ export const blocks = createBlockDefinitionsFromJsonArray([
      {
        'type': 'field_dropdown',
        'name': 'OP',
+        'ariaName': 'Arithmetic operation',
        'options': [
-          ['%{BKY_MATH_ADDITION_SYMBOL}', 'ADD'],
-          ['%{BKY_MATH_SUBTRACTION_SYMBOL}', 'MINUS'],
-          ['%{BKY_MATH_MULTIPLICATION_SYMBOL}', 'MULTIPLY'],
-          ['%{BKY_MATH_DIVISION_SYMBOL}', 'DIVIDE'],
-          ['%{BKY_MATH_POWER_SYMBOL}', 'POWER'],
+          ['%{BKY_MATH_ADDITION_SYMBOL}', 'ADD', 'Plus'],
+          ['%{BKY_MATH_SUBTRACTION_SYMBOL}', 'MINUS', 'Minus'],
+          ['%{BKY_MATH_MULTIPLICATION_SYMBOL}', 'MULTIPLY', 'Times'],
+          ['%{BKY_MATH_DIVISION_SYMBOL}', 'DIVIDE', 'Divided by'],
+          ['%{BKY_MATH_POWER_SYMBOL}', 'POWER', 'To the power of'],
        ],
      },
      {
--- a/core/css.ts
+++ b/core/css.ts
@@ -509,7 +509,7 @@ input[type=number] {
  outline: none;
 }

-#blocklyAriaAnnounce {
+.hiddenForAria {
  position: absolute;
  left: -9999px;
  width: 1px;
--- a/core/field.ts
+++ b/core/field.ts
@@ -199,6 +199,8 @@ export abstract class Field<T = any>
  /** The unique ID of this field. */
  private id_: string | null = null;

+  private config: FieldConfig | null = null;
+
  /**
   * @param value The initial value of the field.
   *     Also accepts Field.SKIP_SETUP if you wish to skip setup (only used by
@@ -251,6 +253,7 @@ export abstract class Field<T = any>
    if (config.tooltip) {
      this.setTooltip(parsing.replaceMessageReferences(config.tooltip));
    }
+    this.config = config;
  }

  /**
@@ -272,6 +275,17 @@ export abstract class Field<T = any>
    this.id_ = `${block.id}_field_${idGenerator.getNextUniqueId()}`;
  }

+  getAriaName(): string | null {
+    return (
+      this.config?.ariaName ??
+      this.config?.name ??
+      this.config?.type ??
+      this.getSourceBlock()?.type ??
+      this.name ??
+      null
+    );
+  }
+
  /**
   * Get the renderer constant provider.
   *
@@ -1418,7 +1432,10 @@ export abstract class Field<T = any>
 * Extra configuration options for the base field.
 */
 export interface FieldConfig {
+  type: string;
+  name?: string;
  tooltip?: string;
+  ariaName?: string;
 }

 /**
--- a/core/field_checkbox.ts
+++ b/core/field_checkbox.ts
@@ -113,13 +113,14 @@ export class FieldCheckbox extends Field<CheckboxBool> {
    dom.addClass(this.fieldGroup_!, 'blocklyCheckboxField');
    textElement.style.display = this.value_ ? 'block' : 'none';

+    this.recomputeAria();
+  }
+
+  private recomputeAria() {
    const element = this.getFocusableElement();
    aria.setRole(element, aria.Role.CHECKBOX);
-    aria.setState(
-      element,
-      aria.State.LABEL,
-      this.name ? `Checkbox ${this.name}` : 'Checkbox',
-    );
+    aria.setState(element, aria.State.LABEL, this.getAriaName() ?? 'Checkbox');
+    aria.setState(element, aria.State.CHECKED, !!this.value_);
  }

  override render_() {
@@ -147,6 +148,7 @@ export class FieldCheckbox extends Field<CheckboxBool> {
  /** Toggle the state of the checkbox on click. */
  protected override showEditor_() {
    this.setValue(!this.value_);
+    this.recomputeAria();
  }

  /**
--- a/core/field_dropdown.ts
+++ b/core/field_dropdown.ts
@@ -28,6 +28,7 @@ import {MenuItem} from './menuitem.js';
 import * as aria from './utils/aria.js';
 import {Coordinate} from './utils/coordinate.js';
 import * as dom from './utils/dom.js';
+import * as idGenerator from './utils/idgenerator.js';
 import * as parsing from './utils/parsing.js';
 import {Size} from './utils/size.js';
 import * as utilsString from './utils/string.js';
@@ -198,12 +199,28 @@ export class FieldDropdown extends Field<string> {
      dom.addClass(this.fieldGroup_, 'blocklyDropdownField');
    }

+    this.recomputeAria();
+  }
+
+  private recomputeAria() {
+    if (!this.fieldGroup_) return; // There's no element to set currently.
    const element = this.getFocusableElement();
-    aria.setRole(element, aria.Role.LISTBOX);
+    aria.setRole(element, aria.Role.COMBOBOX);
+    aria.setState(element, aria.State.HASPOPUP, aria.Role.LISTBOX);
+    aria.setState(element, aria.State.EXPANDED, !!this.menu_);
+    if (this.menu_) {
+      aria.setState(element, aria.State.CONTROLS, this.menu_.id);
+    } else {
+      aria.clearState(element, aria.State.CONTROLS);
+    }
+    aria.setState(element, aria.State.LABEL, this.getAriaName() ?? 'Dropdown');
+
+    // Ensure the selected item has its correct label presented since it may be
+    // different than the actual text presented to the user.
    aria.setState(
-      element,
+      this.getTextElement(),
      aria.State.LABEL,
-      this.name ? `Item ${this.name}` : 'Item',
+      this.computeLabelForOption(this.selectedOption),
    );
  }

@@ -335,7 +352,11 @@ export class FieldDropdown extends Field<string> {
        }
        return label;
      })();
-      const menuItem = new MenuItem(content, value);
+      const menuItem = new MenuItem(
+        content,
+        value,
+        this.computeLabelForOption(option),
+      );
      menuItem.setRole(aria.Role.OPTION);
      menuItem.setRightToLeft(block.RTL);
      menuItem.setCheckable(true);
@@ -346,6 +367,24 @@ export class FieldDropdown extends Field<string> {
      }
      menuItem.onAction(this.handleMenuActionEvent, this);
    }
+
+    this.recomputeAria();
+  }
+
+  private computeLabelForOption(option: MenuOption): string {
+    if (option === FieldDropdown.SEPARATOR) {
+      return ''; // Separators don't need labels.
+    } else if (!Array.isArray(option)) {
+      return ''; // Certain dynamic options aren't iterable. TODO: Figure this out. It breaks when opening certain test toolbox categories in the advanced playground.
+    }
+    const [label, value, optionalAriaLabel] = option;
+    const altText = isImageProperties(label) ? label.alt : null;
+    return (
+      altText ??
+      optionalAriaLabel ??
+      this.computeHumanReadableText(option) ??
+      String(value)
+    );
  }

  /**
@@ -358,6 +397,7 @@ export class FieldDropdown extends Field<string> {
    this.menu_ = null;
    this.selectedMenuItem = null;
    this.applyColour();
+    this.recomputeAria();
  }

  /**
@@ -380,6 +420,11 @@ export class FieldDropdown extends Field<string> {
    this.setValue(menuItem.getValue());
  }

+  override setValue(newValue: AnyDuringMigration, fireChangeEvent = true) {
+    super.setValue(newValue, fireChangeEvent);
+    this.recomputeAria();
+  }
+
  /**
   * @returns True if the option list is generated by a function.
   *     Otherwise false.
@@ -532,14 +577,11 @@ export class FieldDropdown extends Field<string> {
    if (!block) {
      throw new UnattachedFieldError();
    }
-    this.imageElement!.style.display = '';
-    this.imageElement!.setAttributeNS(
-      dom.XLINK_NS,
-      'xlink:href',
-      imageJson.src,
-    );
-    this.imageElement!.setAttribute('height', String(imageJson.height));
-    this.imageElement!.setAttribute('width', String(imageJson.width));
+    const imageElement = this.imageElement!;
+    imageElement.style.display = '';
+    imageElement.setAttributeNS(dom.XLINK_NS, 'xlink:href', imageJson.src);
+    imageElement.setAttribute('height', String(imageJson.height));
+    imageElement.setAttribute('width', String(imageJson.width));

    const imageHeight = Number(imageJson.height);
    const imageWidth = Number(imageJson.width);
@@ -567,15 +609,24 @@ export class FieldDropdown extends Field<string> {
    let arrowX = 0;
    if (block.RTL) {
      const imageX = xPadding + arrowWidth;
-      this.imageElement!.setAttribute('x', `${imageX}`);
+      imageElement.setAttribute('x', `${imageX}`);
    } else {
      arrowX = imageWidth + arrowWidth;
      this.getTextElement().setAttribute('text-anchor', 'end');
-      this.imageElement!.setAttribute('x', `${xPadding}`);
+      imageElement.setAttribute('x', `${xPadding}`);
    }
-    this.imageElement!.setAttribute('y', String(height / 2 - imageHeight / 2));
+    imageElement.setAttribute('y', String(height / 2 - imageHeight / 2));

    this.positionTextElement_(arrowX + xPadding, imageWidth + arrowWidth);
+
+    if (imageElement.id === '') {
+      imageElement.id = idGenerator.getNextUniqueId();
+      const element = this.getFocusableElement();
+      aria.setState(element, aria.State.ACTIVEDESCENDANT, imageElement.id);
+    }
+
+    aria.setRole(imageElement, aria.Role.IMAGE);
+    aria.setState(imageElement, aria.State.LABEL, imageJson.alt);
  }

  /** Renders the selected option, which must be text. */
@@ -585,6 +636,14 @@ export class FieldDropdown extends Field<string> {
    const textElement = this.getTextElement();
    dom.addClass(textElement, 'blocklyDropdownText');
    textElement.setAttribute('text-anchor', 'start');
+    // The field's text should be visible to readers since it will be read out
+    // as static text as part of the combobox (per the ARIA combobox pattern).
+    if (textElement.id === '') {
+      textElement.id = idGenerator.getNextUniqueId();
+      const element = this.getFocusableElement();
+      aria.setState(element, aria.State.ACTIVEDESCENDANT, textElement.id);
+    }
+    aria.setState(textElement, aria.State.HIDDEN, false);

    // Height and width include the border rect.
    const hasBorder = !!this.borderRect_;
@@ -654,7 +713,11 @@ export class FieldDropdown extends Field<string> {
    if (!this.selectedOption) {
      return null;
    }
-    const option = this.selectedOption[0];
+    return this.computeHumanReadableText(this.selectedOption);
+  }
+
+  private computeHumanReadableText(menuOption: MenuOption): string | null {
+    const option = menuOption[0];
    if (isImageProperties(option)) {
      return option.alt;
    } else if (
@@ -689,7 +752,7 @@ export class FieldDropdown extends Field<string> {
      throw new Error(
        'options are required for the dropdown field. The ' +
          'options property must be assigned an array of ' +
-          '[humanReadableValue, languageNeutralValue] tuples.',
+          '[humanReadableValue, languageNeutralValue, opt_ariaLabel] tuples.',
      );
    }
    // `this` might be a subclass of FieldDropdown if that class doesn't
@@ -713,9 +776,9 @@ export class FieldDropdown extends Field<string> {
        return option;
      }

-      const [label, value] = option;
+      const [label, value, opt_ariaLabel] = option;
      if (typeof label === 'string') {
-        return [parsing.replaceMessageReferences(label), value];
+        return [parsing.replaceMessageReferences(label), value, opt_ariaLabel];
      }

      hasNonTextContent = true;
@@ -724,14 +787,14 @@ export class FieldDropdown extends Field<string> {
      const imageLabel = isImageProperties(label)
        ? {...label, alt: parsing.replaceMessageReferences(label.alt)}
        : label;
-      return [imageLabel, value];
+      return [imageLabel, value, opt_ariaLabel];
    });

    if (hasNonTextContent || options.length < 2) {
      return {options: trimmedOptions};
    }

-    const stringOptions = trimmedOptions as [string, string][];
+    const stringOptions = trimmedOptions as [string, string, string?][];
    const stringLabels = stringOptions.map(([label]) => label);

    const shortest = utilsString.shortestStringLength(stringLabels);
@@ -770,13 +833,14 @@ export class FieldDropdown extends Field<string> {
   * @returns A new array with all of the option text trimmed.
   */
  private applyTrim(
-    options: [string, string][],
+    options: [string, string, string?][],
    prefixLength: number,
    suffixLength: number,
  ): MenuOption[] {
-    return options.map(([text, value]) => [
+    return options.map(([text, value, opt_ariaLabel]) => [
      text.substring(prefixLength, text.length - suffixLength),
      value,
+      opt_ariaLabel,
    ]);
  }

@@ -868,7 +932,7 @@ export interface ImageProperties {
 * the language-neutral value.
 */
 export type MenuOption =
-  | [string | ImageProperties | HTMLElement, string]
+  | [string | ImageProperties | HTMLElement, string, string?]
  | 'separator';

 /**
--- a/core/field_image.ts
+++ b/core/field_image.ts
@@ -155,16 +155,18 @@ export class FieldImage extends Field<string> {
      dom.addClass(this.fieldGroup_, 'blocklyImageField');
    }

+    const element = this.getFocusableElement();
    if (this.clickHandler) {
      this.imageElement.style.cursor = 'pointer';
+      aria.setRole(element, aria.Role.BUTTON);
+    } else {
+      aria.setRole(element, aria.Role.IMAGE);
    }

-    const element = this.getFocusableElement();
-    aria.setRole(element, aria.Role.IMAGE);
    aria.setState(
      element,
      aria.State.LABEL,
-      this.name ? `Image ${this.name}` : 'Image',
+      this.altText ?? this.getAriaName(),
    );
  }

--- a/core/field_input.ts
+++ b/core/field_input.ts
@@ -167,6 +167,8 @@ export abstract class FieldInput<T extends InputTypes> extends Field<
    const block = this.getSourceBlock();
    if (!block) throw new UnattachedFieldError();
    super.initView();
+    if (!this.textElement_)
+      throw new Error('Initialization failed for FieldInput');

    if (this.isFullBlockField()) {
      this.clickTarget_ = (this.sourceBlock_ as BlockSvg).getSvgRoot();
@@ -176,13 +178,13 @@ export abstract class FieldInput<T extends InputTypes> extends Field<
      dom.addClass(this.fieldGroup_, 'blocklyInputField');
    }

+    // Showing the text-based value with the input's textbox ensures that the
+    // input's value is correctly read out by screen readers with its role.
+    aria.setState(this.textElement_, aria.State.HIDDEN, false);
+
    const element = this.getFocusableElement();
    aria.setRole(element, aria.Role.TEXTBOX);
-    aria.setState(
-      element,
-      aria.State.LABEL,
-      this.name ? `Text ${this.name}` : 'Text',
-    );
+    aria.setState(element, aria.State.LABEL, this.getAriaName() ?? 'Text');
  }

  override isFullBlockField(): boolean {
--- a/core/field_label.ts
+++ b/core/field_label.ts
@@ -79,11 +79,7 @@ export class FieldLabel extends Field<string> {
      dom.addClass(this.fieldGroup_, 'blocklyLabelField');
    }

-    this.recomputeAriaLabel();
-  }
-
-  private recomputeAriaLabel() {
-    aria.setState(this.getFocusableElement(), aria.State.LABEL, this.getText());
+    aria.setState(this.getFocusableElement(), aria.State.HIDDEN, true);
  }

  /**
@@ -120,9 +116,6 @@ export class FieldLabel extends Field<string> {

  override setValue(newValue: any, fireChangeEvent?: boolean): void {
    super.setValue(newValue, fireChangeEvent);
-    if (this.fieldGroup_) {
-      this.recomputeAriaLabel();
-    }
  }

  /**
--- a/core/field_number.ts
+++ b/core/field_number.ts
@@ -18,9 +18,13 @@ import {
  FieldInputValidator,
 } from './field_input.js';
 import * as fieldRegistry from './field_registry.js';
-import * as aria from './utils/aria.js';
 import * as dom from './utils/dom.js';

+// TODO: Figure out how to either design this to be a 'number' input with proper
+// 'valuemin' and 'valuemax' ARIA properties, build it so that subtypes can do
+// this properly, or consider a separate field type altogether that handles that
+// case properly. See: https://github.com/google/blockly/pull/9384#discussion_r2395601092.
+
 /**
 * Class for an editable number field.
 */
@@ -296,14 +300,11 @@ export class FieldNumber extends FieldInput<number> {
  protected override widgetCreate_(): HTMLInputElement {
    const htmlInput = super.widgetCreate_() as HTMLInputElement;

-    // Set the accessibility state
    if (this.min_ > -Infinity) {
      htmlInput.min = `${this.min_}`;
-      aria.setState(htmlInput, aria.State.VALUEMIN, this.min_);
    }
    if (this.max_ < Infinity) {
      htmlInput.max = `${this.max_}`;
-      aria.setState(htmlInput, aria.State.VALUEMAX, this.max_);
    }
    return htmlInput;
  }
@@ -313,7 +314,6 @@ export class FieldNumber extends FieldInput<number> {
   *
   * @override
   */
-
  public override initView() {
    super.initView();
    if (this.fieldGroup_) {
--- a/core/field_variable.ts
+++ b/core/field_variable.ts
@@ -596,22 +596,28 @@ export class FieldVariable extends FieldDropdown {
    }
    variableModelList.sort(Variables.compareByName);

-    const options: [string, string][] = [];
+    const options: [string, string, string?][] = [];
    for (let i = 0; i < variableModelList.length; i++) {
      // Set the UUID as the internal representation of the variable.
      options[i] = [
        variableModelList[i].getName(),
        variableModelList[i].getId(),
+        Msg['ARIA_LABEL_FOR_VARIABLE_NAME'].replace(
+          '%1',
+          variableModelList[i].getName(),
+        ),
      ];
    }
    options.push([
      Msg['RENAME_VARIABLE'],
      internalConstants.RENAME_VARIABLE_ID,
+      Msg['RENAME_VARIABLE'],
    ]);
    if (Msg['DELETE_VARIABLE']) {
      options.push([
        Msg['DELETE_VARIABLE'].replace('%1', name),
        internalConstants.DELETE_VARIABLE_ID,
+        Msg['DELETE_VARIABLE'].replace('%1', name),
      ]);
    }

--- a/core/inject.ts
+++ b/core/inject.ts
@@ -85,6 +85,7 @@ export function inject(
  // See: https://stackoverflow.com/a/48590836 for a reference.
  const ariaAnnouncementSpan = document.createElement('span');
  ariaAnnouncementSpan.id = 'blocklyAriaAnnounce';
+  dom.addClass(ariaAnnouncementSpan, 'hiddenForAria');
  aria.setState(ariaAnnouncementSpan, aria.State.LIVE, 'polite');
  subContainer.appendChild(ariaAnnouncementSpan);

--- a/core/menu.ts
+++ b/core/menu.ts
@@ -16,6 +16,7 @@ import type {MenuSeparator} from './menu_separator.js';
 import {MenuItem} from './menuitem.js';
 import * as aria from './utils/aria.js';
 import {Coordinate} from './utils/coordinate.js';
+import * as idGenerator from './utils/idgenerator.js';
 import type {Size} from './utils/size.js';
 import * as style from './utils/style.js';

@@ -62,8 +63,12 @@ export class Menu {
  /** ARIA name for this menu. */
  private roleName: aria.Role | null = null;

+  id: string;
+
  /** Constructs a new Menu instance. */
-  constructor() {}
+  constructor() {
+    this.id = idGenerator.getNextUniqueId();
+  }

  /**
   * Add a new menu item to the bottom of this menu.
@@ -86,6 +91,7 @@ export class Menu {
    const element = document.createElement('div');
    element.className = 'blocklyMenu';
    element.tabIndex = 0;
+    element.id = this.id;
    if (this.roleName) {
      aria.setRole(element, this.roleName);
    }
--- a/core/menuitem.ts
+++ b/core/menuitem.ts
@@ -52,6 +52,7 @@ export class MenuItem {
  constructor(
    private readonly content: string | HTMLElement,
    private readonly opt_value?: string,
+    private readonly opt_ariaLabel?: string,
  ) {}

  /**
@@ -98,6 +99,9 @@ export class MenuItem {
      (this.checkable && this.checked) || false,
    );
    aria.setState(element, aria.State.DISABLED, !this.enabled);
+    if (this.opt_ariaLabel) {
+      aria.setState(element, aria.State.LABEL, this.opt_ariaLabel);
+    }

    return element;
  }
--- a/core/utils/aria.ts
+++ b/core/utils/aria.ts
@@ -51,6 +51,8 @@ export enum Role {
  BUTTON = 'button',
  CHECKBOX = 'checkbox',
  TEXTBOX = 'textbox',
+  COMBOBOX = 'combobox',
+  SPINBUTTON = 'spinbutton',
 }

 /**
@@ -99,6 +101,8 @@ export enum State {
  // ARIA property for slider minimum value. Value: number.
  VALUEMIN = 'valuemin',

+  VALUENOW = 'valuenow',
+
  // ARIA property for live region chattiness.
  // Value: one of {polite, assertive, off}.
  LIVE = 'live',
@@ -109,6 +113,9 @@ export enum State {

  ROLEDESCRIPTION = 'roledescription',
  OWNS = 'owns',
+  HASPOPUP = 'haspopup',
+  CONTROLS = 'controls',
+  CHECKED = 'checked',
 }

 /**
@@ -165,6 +172,17 @@ export function setState(
  element.setAttribute(attrStateName, `${value}`);
 }

+/**
+ * Clears the specified ARIA state by removing any related attributes from the
+ * specified element that have been set using setState().
+ *
+ * @param element The element whose ARIA state may be changed.
+ * @param stateName The state to clear from the provided element.
+ */
+export function clearState(element: Element, stateName: State) {
+  element.removeAttribute(ARIA_PREFIX + stateName);
+}
+
 /**
 * Returns a string representation of the specified state for the specified
 * element, or null if it's not defined or specified.
--- a/msg/json/en.json
+++ b/msg/json/en.json
@@ -1,7 +1,7 @@
 {
 	"@metadata": {
 		"author": "Ellen Spertus <ellen.spertus@gmail.com>",
-		"lastupdated": "2025-09-22 11:22:54.733649",
+		"lastupdated": "2025-09-23 23:27:37.312782",
 		"locale": "en",
 		"messagedocumentation" : "qqq"
 	},
@@ -32,6 +32,7 @@
 	"CHANGE_VALUE_TITLE": "Change value:",
 	"RENAME_VARIABLE": "Rename variable...",
 	"RENAME_VARIABLE_TITLE": "Rename all '%1' variables to:",
+	"ARIA_LABEL_FOR_VARIABLE_NAME": "Variable '%1'",
 	"NEW_VARIABLE": "Create variable...",
 	"NEW_STRING_VARIABLE": "Create string variable...",
 	"NEW_NUMBER_VARIABLE": "Create number variable...",
--- a/msg/json/qqq.json
+++ b/msg/json/qqq.json
@@ -39,6 +39,7 @@
 	"CHANGE_VALUE_TITLE": "prompt - This message is seen on mobile devices and the Opera browser.  With most browsers, users can edit numeric values in blocks by just clicking and typing.  Opera does not allow this and mobile browsers may have issues with in-line textareas. So we prompt users with this message (usually a popup) to change a value.",
 	"RENAME_VARIABLE": "dropdown choice - When the user clicks on a variable block, this is one of the dropdown menu choices.  It is used to rename the current variable.  See [https://github.com/google/blockly/wiki/Variables#dropdown-menu https://github.com/google/blockly/wiki/Variables#dropdown-menu].",
 	"RENAME_VARIABLE_TITLE": "prompt - Prompts the user to enter the new name for the selected variable.  See [https://github.com/google/blockly/wiki/Variables#dropdown-menu https://github.com/google/blockly/wiki/Variables#dropdown-menu].\n\nParameters:\n* %1 - the name of the variable to be renamed.",
+	"ARIA_LABEL_FOR_VARIABLE_NAME": "dropdown choice - Provides screen reader users with a label that contextualizes a variable as an actual variable with its name.",
 	"NEW_VARIABLE": "button text - Text on the button used to launch the variable creation dialogue.",
 	"NEW_STRING_VARIABLE": "button text - Text on the button used to launch the variable creation dialogue.",
 	"NEW_NUMBER_VARIABLE": "button text - Text on the button used to launch the variable creation dialogue.",
--- a/msg/messages.js
+++ b/msg/messages.js
@@ -9,13 +9,13 @@
 *
 * After modifying this file, run:
 *
- *     npm run generate:langfiles
+ *     npm run messages
 *
 * to regenerate json/{en,qqq,constants,synonyms}.json.
 *
 * To convert all of the json files to .js files, run:
 *
- *     npm run build:langfiles
+ *     npm run langfiles
 */
 'use strict';

@@ -146,6 +146,9 @@ Blockly.Msg.RENAME_VARIABLE = 'Rename variable...';
 /** @type {string} */
 /// prompt - Prompts the user to enter the new name for the selected variable.  See [https://github.com/google/blockly/wiki/Variables#dropdown-menu https://github.com/google/blockly/wiki/Variables#dropdown-menu].\n\nParameters:\n* %1 - the name of the variable to be renamed.
 Blockly.Msg.RENAME_VARIABLE_TITLE = 'Rename all "%1" variables to:';
+/** @type {string} */
+/// dropdown choice - Provides screen reader users with a label that contextualizes a variable as an actual variable with its name.
+Blockly.Msg.ARIA_LABEL_FOR_VARIABLE_NAME = 'Variable "%1"';

 // Variable creation
 /** @type {string} */
--- a/tests/mocha/field_dropdown_test.js
+++ b/tests/mocha/field_dropdown_test.js
@@ -230,9 +230,9 @@ suite('Dropdown Fields', function () {
      assert.deepEqual(this.field.prefixField, 'a');
      assert.deepEqual(this.field.suffixField, 'b');
      assert.deepEqual(this.field.getOptions(), [
-        ['d', 'D'],
-        ['e', 'E'],
-        ['f', 'F'],
+        ['d', 'D', undefined],
+        ['e', 'E', undefined],
+        ['f', 'F', undefined],
      ]);
    });
    test('With an empty array of options throws', function () {
--- a/tests/mocha/field_variable_test.js
+++ b/tests/mocha/field_variable_test.js
@@ -201,9 +201,7 @@ suite('Variable Fields', function () {
        Blockly.FieldVariable.dropdownCreate.call(fieldVariable);
      // Expect variable options, a rename option, and a delete option.
      assert.lengthOf(dropdownOptions, expectedVarOptions.length + 2);
-      for (let i = 0, option; (option = expectedVarOptions[i]); i++) {
-        assert.deepEqual(dropdownOptions[i], option);
-      }
+      assert.deepEqual(dropdownOptions.slice(0, -2), expectedVarOptions);
      assert.include(dropdownOptions[dropdownOptions.length - 2][0], 'Rename');

      assert.include(dropdownOptions[dropdownOptions.length - 1][0], 'Delete');
@@ -217,8 +215,8 @@ suite('Variable Fields', function () {
        new Blockly.FieldVariable('name2'),
      );
      assertDropdownContents(fieldVariable, [
-        ['name1', 'id1'],
-        ['name2', 'id2'],
+        ['name1', 'id1', "Variable 'name1'"],
+        ['name2', 'id2', "Variable 'name2'"],
      ]);
    });
    test('Contains variables created after field', function () {
@@ -230,8 +228,8 @@ suite('Variable Fields', function () {
      // Expect that variables created after field creation will show up too.
      this.workspace.createVariable('name2', '', 'id2');
      assertDropdownContents(fieldVariable, [
-        ['name1', 'id1'],
-        ['name2', 'id2'],
+        ['name1', 'id1', "Variable 'name1'"],
+        ['name2', 'id2', "Variable 'name2'"],
      ]);
    });
    test('Contains variables created before and after field', function () {
@@ -245,9 +243,9 @@ suite('Variable Fields', function () {
      // Expect that variables created after field creation will show up too.
      this.workspace.createVariable('name3', '', 'id3');
      assertDropdownContents(fieldVariable, [
-        ['name1', 'id1'],
-        ['name2', 'id2'],
-        ['name3', 'id3'],
+        ['name1', 'id1', "Variable 'name1'"],
+        ['name2', 'id2', "Variable 'name2'"],
+        ['name3', 'id3', "Variable 'name3'"],
      ]);
    });
  });