## 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.
* chore: rollup of updates from TranslateWiki
* chore: Roll up additional translatewiki changes
Not sure how these were omitted from PR originally.
---------
Co-authored-by: Christopher Allen <cpcallen+git@google.com>
* 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.
* docs(messages): Add a msg/json/README.md
Add a README.md file to msg/json/ explaining the purpose of the
files therein, mentioning that PRs are not accepted but that
translation updates should be made via TranslateWiki, and with a
short description of how to build the langfiles that are generated
from them.
* docs(messages): Add note about the Klingon exception
* feat(build): Make build tasks invoke their prerequisites
- Divide gulp targets into three kinds: main sequence,
manually invokable, and script-only. The first two categories
automatically invoke their prerequisites.
- Give (most of) the affected gulp targets shorter and more memorable
names that could become their npm script names in future.
* feat(build): Make package tasks invoke their prerequisites
Have the package task invoke the cleanBuildDir (as well as
cleanPackageDir) and build tasks. Remove the checkBuildDir
task as it is now redundant since a fresh build is done every
time.
* feat(build): Make git tasks invoke their prerequisites
* feat(build): Make cleanup, license [sic] tasks invoke their prerequisites
Turns out they don't have any, so this commit just classifies
their gulp targets according to the established scheme.
* feat(build): Make appengine tasks invoke their prerequisites
In this case prepareDeployDir will eventually depend on package
but does not for now.
* feat(build): Have npm scripts run npm ci first where applicable
Have any npm script that have external effects (e.g. publishing an
npm package, pushing a new version to appengine, or updating GitHub
Pages) start by running npm ci to ensure that all dependencies are
up-to-date with respect to package-lock.json.
(This is done by npm and not a gulp script because gulp itself
might need updating. So might npm, but that is less likely to
make any difference to what gets published/pushed.)
* chore(build): have tests use package target
Have the tests just run the package target (with debug flags)
since that runs the the build target automatically.
* feat(tests): Write Closure Compiler output directly to dist/
Since they are already UMD-wrapped, have Closure Compiler write
output chunks directly to RELEASE_DIR, i.e. dist/.
* chore(tests): Use freshly-build files in compressed mode.
Use the freshly-built build/*_compresssed.js files when bootstrapping
in compressed mode, rather than using the checked-in files in the
repository root.
This helps ensure that compressed and uncompressed mode will be
testing (as closely as possible) the same code.
Obsoletes #6218 (though the issues discussed there have not actually
yet been addressed in this branch).
* chore(build): Write intermediate langfiles to build/msg
Write the results of create_messages.py to build/msg instead of
build/msg/js.
* fix(build): Use build/msg/en.js instead of msg/messages.js in tests
This has no direct effect but fixes a long-standing misdesign
where we are testing against the input to, rather than the output
of, the language file processing pipeline.
* feat(demos): Use freshly-built files
Use the freshly-built dist/*_compresssed.js and build/msg/* files
rather than using the checked-in files in the repository root.
This helps ensure that these demos are using the most recent
version of Blockly (even in the develop branch).
* fix(build): Update appengine deployment to include built files
Modify the prepareDemos task as follows:
- Use the git index instead of HEAD, so that most local changes
will be applied (without copying whatever .gitignored cruft
might be in the local directory).
- Run clean and build and then copy build/msg and
dist/*_compressed.js* to the deploy directory.
This fixes the problem created by the previous commit, wherein the
demos relied on built files that were not being deployed to
appengine.
* fix(build): Update GitHub Pages deployment to include built files
Modify the updateGithubPages task to run clean and build and
then git add build/msg dist/*_compressed.js*, so that they will
be included in the deployed pages.
This fixes the problem created by the previous^2 commit,
wherein the demos relied on built files that were not being
deployed to GitHub Pages.
* chore(build): Remove build products from repository
Remove *_compressed.js* and msg/js/* from the blockly repository.
Also remove the now-obsolete checkinBuilt gulp task.
* chore(build): Apply relevant changes to test_tasks.js
Apply changes made to run_all_tests.sh and check_metadata.sh to
the corresponding parts of their JS replacements in
test_tasks.js.
* chore(build): Make updates suggested in PR #6475
- Remove `clean:builddir` and `clean:releasedir` - `clean`
is sufficient.
- Remove duplicate `require` from `appengine_tasks.js`.
* feat(build): Use shorter npm script names
Since scripts that run build tasks now automatically run their
prerequisite tasks, the previous naming scheme of task `build`
running all the `build:subtask`s no longe really makes very
much sense.
Additionally, following a chat discussion, there seems to be a
rough consensus to use "messages" to refer to the .json input
files, and "langfiles" to the generated .js output files.
Consequently, simplify npm script names by renaming as follows:
- "generate:langfiles" -> "messages"
- "build:langfiles" -> "langfiles"
- "build:js" -> "tsc"
- "build:deps" -> "deps"
- "build:compiled" -> "minify"
- "build:compressed": delete this synonym for "build:compiled",
("minify" was chosen as agnostic to Closure Compiler vs. WebPack.)
* chores(build): Add deprecation notice for old scripts
To reduce potential confusion/frustration, restore the previous
npm scripts but have them display a deprecation notice instead
(note that npm prints the script contents before running it, so
echo is not needed).
* docs(build): Add comments distinguishing 'messages' from 'langfiles'
* Bump ws from 7.4.4 to 7.5.1
Bumps [ws](https://github.com/websockets/ws) from 7.4.4 to 7.5.1.
- [Release notes](https://github.com/websockets/ws/releases)
- [Commits](https://github.com/websockets/ws/compare/7.4.4...7.5.1)
---
updated-dependencies:
- dependency-name: ws
dependency-type: indirect
...
Signed-off-by: dependabot[bot] <support@github.com>
* Bump lodash from 4.17.19 to 4.17.21
Bumps [lodash](https://github.com/lodash/lodash) from 4.17.19 to 4.17.21.
- [Release notes](https://github.com/lodash/lodash/releases)
- [Commits](https://github.com/lodash/lodash/compare/4.17.19...4.17.21)
---
updated-dependencies:
- dependency-name: lodash
dependency-type: indirect
...
Signed-off-by: dependabot[bot] <support@github.com>
* Initial commit for appengine deploy action
* Update comments to be more descriptive
* Get deploy files from the correct directory
Previous path was `_deploy/`. New path is `../_deploy`.
* Create Github Action to comment on PR while develop is frozen (#5006)
* Create develop_freeze_comment.yml
* Update comments
* Fix typo and update uses
* Add test message
* Revert "Create Github Action to comment on PR while develop is frozen (#5006)" (#5013)
This reverts commit 8c635b5fbc.
* Revert "Get deploy files from the correct directory"
* Bump hosted-git-info from 2.8.4 to 2.8.9 (#4980)
Bumps [hosted-git-info](https://github.com/npm/hosted-git-info) from 2.8.4 to 2.8.9.
- [Release notes](https://github.com/npm/hosted-git-info/releases)
- [Changelog](https://github.com/npm/hosted-git-info/blob/v2.8.9/CHANGELOG.md)
- [Commits](https://github.com/npm/hosted-git-info/compare/v2.8.4...v2.8.9)
---
updated-dependencies:
- dependency-name: hosted-git-info
dependency-type: indirect
...
Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
* Pull Request template for goog.module PRs
Provide a standard pull request template more suited to PRs doing
goog.module conversions.
There's no way to pick a non-default template when creating a PR
manually, but this one can be used by adding
"&?template=goog_module.md" to the
https://github.com/cpcallen/bugs/compare/ URL.
* Update goog_module.md with suggested fixes
* Fix typos.
* Reinstate "Proposed Changes" section.
* Mark text that should be edit with ALL CAPS.
* Bump normalize-url from 4.5.0 to 4.5.1
Bumps [normalize-url](https://github.com/sindresorhus/normalize-url) from 4.5.0 to 4.5.1.
- [Release notes](https://github.com/sindresorhus/normalize-url/releases)
- [Commits](https://github.com/sindresorhus/normalize-url/commits)
---
updated-dependencies:
- dependency-name: normalize-url
dependency-type: indirect
...
Signed-off-by: dependabot[bot] <support@github.com>
* Bump trim-newlines from 3.0.0 to 3.0.1
Bumps [trim-newlines](https://github.com/sindresorhus/trim-newlines) from 3.0.0 to 3.0.1.
- [Release notes](https://github.com/sindresorhus/trim-newlines/releases)
- [Commits](https://github.com/sindresorhus/trim-newlines/commits)
---
updated-dependencies:
- dependency-name: trim-newlines
dependency-type: indirect
...
Signed-off-by: dependabot[bot] <support@github.com>
* Bump path-parse from 1.0.6 to 1.0.7
Bumps [path-parse](https://github.com/jbgutierrez/path-parse) from 1.0.6 to 1.0.7.
- [Release notes](https://github.com/jbgutierrez/path-parse/releases)
- [Commits](https://github.com/jbgutierrez/path-parse/commits/v1.0.7)
---
updated-dependencies:
- dependency-name: path-parse
dependency-type: indirect
...
Signed-off-by: dependabot[bot] <support@github.com>
* Bump postcss from 7.0.35 to 7.0.36 (#4928)
Bumps [postcss](https://github.com/postcss/postcss) from 7.0.35 to 7.0.36.
- [Release notes](https://github.com/postcss/postcss/releases)
- [Changelog](https://github.com/postcss/postcss/blob/main/CHANGELOG.md)
- [Commits](https://github.com/postcss/postcss/compare/7.0.35...7.0.36)
---
updated-dependencies:
- dependency-name: postcss
dependency-type: indirect
...
Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
* Rollup of all Q3 message changes (#5565)
Courtesy of Translatewiki
* Add Croatian to Code demo (#5583) (#5611)
Contributed courtesy of Lidija Kralj.
* chore: create release.yml (#5588)
* Create release.yml
* chore: update release.yml
* chore: update dependabot messages and labels (#5653)
The same as #5618, but against master because dependabot ignores changes on develop.
* chore: Create separate report_clang_format workflow in master branch (#5670)
The initial version of this workflow just uses `console.log` to report
the context of the `context` object. It is hoped that there will
be enough information in this context to identify the PR to comment on,
without the `check_clang_format` workflow having to upload a
'build artefact' of some kind - see example of what I hoe to avoid
starting at `ReceivePR.yml` here:
https://securitylab.github.com/research/github-actions-preventing-pwn-requests/
A follow-up PR will (if possible) add the code to create comments
when `check_clang_format` fails.
Part of #5659.
* chore: Remove spurious extra `on` clause in report_clang_format.yml (#5671)
Removes an unwanted `on` clause that was overlooked in #5670 by author and reviewer.
* chore: More spelunking in GitHub Action data (#5673)
Looking for information about PR that triggered original
check_clang_format run.
* chore: revert github action (#5675)
* fix: Don't try to set text fields to null on cancel (#5692)
Mobile users get a window.prompt as an input, if they press the cancel button the return value is null. Don't attempt to set the value of the field to null.
Caused errors in the custom note field which inherits from FieldTextInput. Detected in Blockly Games Music.
This PR is for the master branch and includes a recompile. The develop branch has changed enough that a cherrypick from develop to master won't work. The bug in question represents a significant number of the errors being reported from Blockly Games.
* Update dependabot.yml (#5705)
* chore: run clang-format
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
Co-authored-by: Monica Kozbial <6621618+moniika@users.noreply.github.com>
Co-authored-by: Christopher Allen <cpcallen+git@google.com>
Co-authored-by: Neil Fraser <fraser@google.com>
Co-authored-by: alschmiedt <aschmiedt@google.com>
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.
