## The basics
- [x] I [validated my changes](https://developers.google.com/blockly/guides/contribute/core#making_and_verifying_a_change)
## The details
### Resolves
Fixes#8206Fixes#8210Fixes#8213Fixes#8255Fixes#8211Fixes#8212Fixes#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.
* fix: improve screenreader output for workspace comments
* fix: run npm run messages to fully add new message
* fix: remove useless bubble label
* fix: use roledescription instead of description
* feat: Allow resetting alert/prompt/confirm to defaults.
* chore: Add unit tests for Blockly.dialog.
* fix: Removed TEST_ONLY hack from Blockly.dialog.
* feat: Add a default toast notification implementation.
* feat: Add support for toasts to Blockly.dialog.
* chore: Add tests for default toast implementation.
* chore: Fix docstring.
* refactor: Use default arguments for dialog functions.
* refactor: Add 'close' to the list of messages.
* chore: Add new message in several other places.
* chore: clarify docstrings.
* feat: Make toast assertiveness configurable.
* Correct list's "find" and "get" blocks help.
Both blocks were using the same help URL.
Two unrelated results of recompiling messages:
* Allow unwanted 'qqq' messages to be reverted.
* 'constants.json' is unchanged, but sorted.
Also improve python json dumping.
* feat: Invalid Blocks
* Rename the new json property from invalid to invalidReasons.
* Merged isValid into isEnabled.
* Minor fixes.
* More minor fixes.
* Reverting some stuff that didn't need to change.
* Addressing PR feedback.
* Update the BlockInfo interface to match State.
* Make BlockChange.disabledReason private.
On the desktop, widgetDispose_ will call onFinishEditing_ on close.
This was missing in the mobile counterpart, so any cleanups in onFinishEditing_ would not be called.
Also update the message string comment while we are touching this code.
* chore(messages): npm run messages
This is the raw changes made by `npm run messages`, without any
manual reverts / backporting.
* fix(messages): Backport TranslateWiki hints (with edits)
Backport changes made to qqq.json by TranslateWiki editors to
messages.json, with some modifications.
See https://translatewiki.net/wiki/Template:Optional for details
of how the {{Optional}} template works.
* chore(messages): Apply backported messages.js changes to qqq.json
Also manually revert deletion of translation credits.
Our files are up to a decade old, and have churned so much, that the initial author of the file no longer has much meaning.
Furthermore, this will encourage developers to post to the developer group, rather than emailing Googlers (usually me) directly.
There are some files in msg/json/ (currently en.json, qqq.json,
constants.json and synonyms.json) that are generated by
scripts/i18n/js_to_json.py as part of the language file build process
- but this only needs to be done when messages.js is updated and
and usually requires some manual cleanup, so remove this step from the
existing buildLangfiles gulp script and create a separate command
('npm run generate:langfiles') to do this when required.
* Google changed from an Inc to an LLC.
This happened back in 2017 but we didn’t notice. Officially we should update files from Inc to LLC when they are changed as part of regular edits, but this is a nightmare to remember for the next decade.
* Remove project description/titles from licenses
This is no longer part of Google’s header requirements. Our existing descriptions were useless (“Visual Blocks Editor”) or grossly obselete (“Visual Blocks Language”).
* License no longer requires URL.
* Fix license regexps.
* Add {{Optional}} to help URLs.
Fixes issue #898.
* Leakage from Blockly Games?
* Propagate msg-Blockly -> msg-blockly change back to messages.js
As made by wikitranslate in 69b10dba79
* variables_dynamic
* make test , and i18n
* Issue #1470
* Blockly.Constants.VariablesDynamic.CUSTOM_CONTEXT_MENU_VARIABLE_MUTATION
to make sure setCheck before event trigger
* Update built files from develop.
* fix copyright ,quotes , comments , and optimize some flow.
* quotes，change UI , change category custom name
* single setter , remove mutator , colour typo , typed variables create button message
* undo the indent edits.
* Convert more text blocks to JSON format
Converts text_charAt, text_indexOf, text_isEmpty, and text_length
to JSON.
Includes a rebuild to pick up message changes.
Replace URL usages of %28 and %29 with normal parenthesis characters. (They aren't replaced by JavaScript's encodeURIComponent() function, and seem to work just fine without them.)
Added missing semicolon in build.py.
This will be used to define constants accessible in JSON block definitions. Messages with descriptions that include `{{Notranslate}}` will not be included in the translation files sent to TranslateWiki. Instead, they are written to `msg/json/constants.json`, and later merged back into the `.js` files, similar to synonyms.
Template details: https://translatewiki.net/wiki/Template:Notranslate
