## 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.
* chore: Use "pointer" instead of "mouse" in menu.ts.
* fix: Only highlight menu items on hover if the pointer has moved.
* fix: Don't blur menus on pointerleave.
* fix!: Remove the blocklyMenuItemHighlight CSS class and use the hover
* fix: Remove setHighlighted method in menuitem
* fix: Remove blocklymenuitemhighlight css class
* Remove redundant blocklyNonSelectable class and integrate non-selectability into existing classes
* Removed .gitpod file
* fix: remove redundant blocklyNonSelectable class and integrate non-selectability into existing classes https://github.com/google/blockly/issues/8328
* fix: remove redundant blocklyNonSelectable class and integrate non-selectability into existing classes #8328
* fix: remove redundant blocklyNonSelectable class and integrate non-selectability into existing classes #8328
* fix: remove redundant blocklyNonSelectable class and integrate non-selectability into existing classes #8328
* fix: remove redundant blocklyNonSelectable class and integrate non-selectability into existing classes #8328
* fix: remove redundant blocklyNonSelectable class and integrate non-selectability into existing classes
* fix(build): Restore erroneously-deleted filter function
This was deleted in PR #7406 as it was mainly being used to
filter core/ vs. test/mocha/ deps into separate deps files -
but it turns out also to be used for filtering error
messages too. Oops.
* refactor(tests): Migrate advanced compilation test to ES Modules
* refactor(build): Migrate main.js to TypeScript
This turns out to be pretty straight forward, even if it would
cause crashing if one actually tried to import this module
instead of just feeding it to Closure Compiler.
* chore(build): Remove goog.declareModuleId calls
Replace goog.declareModuleId calls with a comment recording the
former module ID for posterity (or at least until we decide
how to reformat the renamings file.
* chore(tests): Delete closure/goog/*
For the moment we still need something to serve as base.js for
the benefit of closure-make-deps, so we keep a vestigial
base.js around, containing only the @provideGoog declaration.
* refactor(build): Remove vestigial base.js
By changing slightly the command line arguments to
closure-make-deps and closure-calculate-chunks the need to have
any base.js is eliminated.
* chore: Typo fix for PR #7415
* Reduce usage of obsolete .keyCode property.
* Rename private properties/methods which violate eslint rules.
* Use arrays of bound events rather than individual properties.
* Improve typing info.
* Also fix O(n^2) recursive performance issue in theme's getComponentStyle function.
* And replace String(...) with '${...}' (smaller, faster).
* .toString() is considered harmful.
* refactor: Remove checks for PointerEvent support.
* refactor: Deprecate and remove calls to splitEventByTouches.
* refactor: Deprecate and remove calls to setClientFromTouch().
* refactor: Use PointerEvent in place of Event/MouseEvent/TouchEvent/PseudoEvent.
* refactor: Update references to mouse/touch events in code and documentation to reference pointer events.
* refactor: Merge Gesture and TouchGesture
* chore: clang-format changed files
* refactor: Bind and expect PointerEvents instead of MouseEvents.
* refactor: Rename TouchGesture to Gesture.
* fix: Fix test failures.
* chore: clang-format changed files.
* fix: Fix errant _ from merging
* refactor: Clean up dead code in browser_events.ts.
* chore: Update version in deprecation notices to reflect release schedule
* fix: Fixed a bug that caused the browser context menu to not be suppressed in Chrome.
* fix: Re-export Gesture as TouchGesture for backwards compatibility.
* refactor: Deprecate and remove uses of opt_noPreventDefault.
* chore: Fix error message in gesture.ts.
* chore: Removed obsolete todo.
* fix: stop using dom.addClass in most cases
* chore: format
* fix: remove use of dom.addClass in toolbox
* chore: lint and format
* fix: add checks around non-constant class names
* fix: switch back to quoted access
* chore: format
* fix: remove calls to removeClass
* chore: format
* chore: remove unused deps
* fix: remove uses of hasClass
* chore: format and lint
* chore: format
* refactor: Remove uses of AnyDuringMigration from flyout_base.ts.
* refactor: Remove uses of AnyDuringMigration from flyout_metrics_manager.ts.
* refactor: Remove uses of AnyDuringMigration from variables_dynamic.ts.
* refactor: Remove uses of AnyDuringMigration from procedures.ts.
* refactor: Remove uses of AnyDuringMigration from generator.ts.
* refactor: Remove some uses of AnyDuringMigration from menu.ts.
* refactor: Remove uses of AnyDuringMigration from mutator.ts.
* refactor: Remove uses of AnyDuringMigration from variables.ts.
* refactor: Remove uses of AnyDuringMigration from array.ts.
* refactor: Remove uses of AnyDuringMigration from aria.ts.
* refactor: Remove uses of AnyDuringMigration in basic_cursor.ts.
* refactor: Remove uses of AnyDuringMigration in dropdowndiv.ts.
* refactor: Remove uses of AnyDuringMigration in utils.ts.
* refactor: Remove uses of AnyDuringMigration from menuitem.ts.
* refactor: Remove uses of AnyDuringMigration from idgenerator.ts.
* refactor: Remove uses of AnyDuringMigration in block_animations.ts.
* refactor: Initialize definitions and functionNames in generator.ts by default.
* chore: add linting for tsdoc
* chore: don't require types on return
* chore: remove redundant fileoverview from ts
* chore: change return to returns and add some newlines
* chore: remove license tag
* chore: don't require params/return docs
* chore: remove spurious struct tags
* Revert "chore: change return to returns and add some newlines"
This reverts commit d6d8656a45.
* chore: don't auto-add param names
* chore: disable require-param bc it breaks on this
* return to returns and add line breaks
* chore: configure additional jsdoc rules
* chore: run format
* Revert "chore: remove license tag"
This reverts commit 173455588a.
* chore: allow license tag format
* chore: only require jsdoc on exported items
* chore: add missing jsdoc or silence where needed
* chore: run format
* chore: lint fixes
* fix: convert files to typescript
* fix: add alias for AnyDuringMigration so that tsc will run
* chore: format
* chore: enable ts for the clang-format workflow (#6233)
* chore: Restore @fileoverview comment locations (#6237)
* chore: add declareModuleId (#6238)
* fix: Revert comment change to app_controller.js (#6241)
* fix: Add missing import goog statements (#6240)
I've added the import statement immediately before the
goog.declareModuleId calls that depend on it.
There is an argument to be made that we should put the import
statement in their normal place amongst any other imports, and
move the declareModuleId statement to below the double blank
line below the imports, but as these are so tightly coupled,
replace the previous goog.module calls, and will both be deleted
at the same time once the transition to TypeScript is fully complete
I think it's fine (and certainly much easier) to do it this way.
* chore: Fix whitespace (#6243)
* fix: Remove spurious blank lines
Remove extraneous blank lines introduced by deletion of
'use strict'; pragmas.
Also fix the location of the goog.declareModuleId call in
core/utils/array.ts.
* fix: Add missing double-blank-line before body of modules
Our convention is to have two blank lines between the imports (or
module ID, if there are no imports) and the beginning of the body
of the module. Enforce this.
* fix: one addition format error for PR #6243
* fix(build): Skip npm prepare when running in CI (#6244)
Have npm prepare do nothing when running in CI.
We don't need to do any building, because npm test will build
everything needed in the workflows in which it is run, and we
don't want to build anything in other workflows because a tsc
error would prevent those workflows from completing.
* fix: re-add `@package` annotations as `@internal` annotations (#6232)
* fix: add ~70% of internal attributes
* fix: work on manually adding more @internal annotations
* fix: add more manual internal annotations
* fix: rename package typos to internal
* fix: final manual fixes for internal annotations
* chore: format
* chore: make unnecessary multiline jsdoc a single line
* fix: fix internal tags in serialization exceptions
* fix: tsc errors picked up from develop (#6224)
* fix: relative path for deprecation utils
* fix: checking if properties exist in svg_math
* fix: set all timeout PIDs to AnyDuringMigration
* fix: make nullability errors explicity in block drag surface
* fix: make null check in events_block_change explicit
* fix: make getEventWorkspace_ internal so we can access it from CommentCreateDeleteHelper
* fix: rename DIV -> containerDiv in tooltip
* fix: ignore backwards compat check in category
* fix: set block styles to AnyDuringMigration
* fix: type typo in KeyboardShortcut
* fix: constants name in row measurables
* fix: typecast in mutator
* fix: populateProcedures type of flattened array
* fix: ignore errors related to workspace comment deserialization
* chore: format files
* fix: renaming imports missing file extensions
* fix: remove check for sound.play
* fix: temporarily remove bad requireType.
All `export type` statements are stripped when tsc is run. This means
that when we attempt to require BlockDefinition from the block files, we
get an error because it does not exist.
We decided to temporarily remove the require, because this will no
longer be a problem when we conver the blocks to typescript, and
everything gets compiled together.
* fix: bad jsdoc in array
* fix: silence missing property errors
Closure was complaining about inexistant properties, but they actually
do exist, they're just not being transpiled by tsc in a way that closure
understands.
I.E. if things are initialized in a function called by the constructor,
rather than in a class field or in the custructor itself, closure would
error.
It would also error on enums, because they are transpiled to a weird
IIFE.
* fix: context menu action handler not knowing the type of this.
this: TypeX information gets stripped when tsc is run, so closure could
not know that this was not global. Fixed this by reorganizing to use the
option object directly instead of passing it to onAction to be bound to
this.
* fix: readd getDeveloperVars checks (should not be part of migration)
This was found because ALL_DEVELOPER_VARS_WARNINGS_BY_BLOCK_TYPE was no
longer being accessed.
* fix: silence closure errors about overriding supertype props
We propertly define the overrides in typescript, but these get removed
from the compiled output, so closure doesn't know they exist.
* fix: silence globalThis errors
this: TypeX annotations get stripped from the compiled output, so
closure can't know that we're accessing the correct things. However,
typescript makes sure that this always has the correct properties, so
silencing this should be fine.
* fix: bad jsdoc name
* chore: attempt compiling with blockly.js
* fix: attempt moving the import statement above the namespace line
* chore: add todo comments to block def files
* chore: remove todo from context menu
* chore: add comments abotu disabled errors
* chore: move comments back to their correct positions (#6249)
* fix: work on fixing comments
* chore: finish moving all comments
* chore: format
* chore: move some other messed up comments
* chore: format
* fix: Correct enum formatting, use merged `namespace`s for types that are class static members (#6246)
* fix: formatting of enum KeyCodes
* fix: Use merged namespace for ContextMenuRegistry static types
- Create a namespace to be merged with the ContextMenuRegistry
class containing the types that were formerly declared as static
properties on that class.
- Use type aliases to export them individually as well, for
compatibility with the changes made by MigranTS (and/or
@gonfunko) to how other modules in core/ now import these
types.
- Update renamings.json5 to reflect the availability of the
direct exports for modules that import this module directly
(though they are not available to, and will not be used by,
code that imports only via blockly.js/blockly.ts.)
* fix: Use merged namespace for Input.Align
- Create a merged namespace for the Input.Align enum.
- Use type/const aliases to export it as Input too.
- Update renamings.json5 to reflect the availability of the
direct export.
* fix: Use merged namespace for Names.NameType
- Create a merged namespace for the Names.NameType enum.
- Use type/const aliases to export it as NameType too.
- Update renamings.json5 to reflect the availability of the
direct export. (This ought to have happened in an earlier
version as it was already available by both routes.)
* chore: Fix minor issues for PR #6246
- Use `Align` instead of `Input.Align` where possible.
* fix(build): Suppress irrelevant JSC_UNUSED_LOCAL_ASSIGNMENT errors
tsc generates code for merged namespaces that looks like:
(function (ClassName) {
let EnumName;
(function (EnumName) {
EnumName[EnumNameAlign["v1"] = 0] = "v1";
// etc.
})(EnumName = ClassName.EnumName || (ClassName.EnumName = {}));
})(ClassName || (ClassName = {}));
and Closure Compiler complains about the fact that the EnumName let
binding is initialised but never used. (It exists so that any other
code that was in the namespace could see the enum.)
Suppress this message, since it is not actionable and lint and/or tsc
should tell us if we have actual unused variables in our .ts files.
* chore(build): Suppress spurious warnings from closure-make-deps (#6253)
A little bit of an ugly hack, but it works: pipe stderr through
grep -v to suppress error output starting with "WARNING in".
* fix: remaining enums that weren't properly exported (#6251)
* fix: remaining enums that weren't properly exported
* chore: format
* fix: add enum value exports
* chore: format
* fix: properly export interfaces that were typedefs (#6250)
* fix: properly export interfaces that were typedefs
* fix: allowCollsion -> allowCollision
* fix: convert unconverted enums
* fix: enums that were/are instance properties
* fix: revert changes to property enums
* fix: renamed protected parameter properties (#6252)
* fix: bad protected parameter properties
* chore:format
* fix: gesture constructor
* fix: overridden properties that were renamed
* refactor: Migrate `blockly.js` to TypeScript (#6261)
* chore: Apply changes to blockly.js to blockly.ts
* fix: Build using core/blockly.ts instead of .js
Compiles and runs in compressed mode correctly!
* fix(build): Don't depend on execSync running bash (#6262)
For some reason on Github CI servers execSync uses /bin/sh, which
is (on Ubuntu) dash rather than bash, and does not understand
the pipefail option.
So remove the grep pipe on stderr and just discard all error output
at all.
This is not ideal as errors in test deps will go unreported AND
not even cause test failure, but it's not clear that it's worth
investing more time to fix this at the moment.
* chore: use `import type` where possible (#6279)
* chore: automatically change imports to import types
* chore: revert changes that actually need to be imports
* chore: format
* chore: add more import type statements based on importsNotUsedAsValues
* chore: fix tsconfig
* chore: add link to compiler issue
* fix: add type information to blockly options (#6283)
* fix: add type information to blockly options
* chore: format
* chore: remove erroneous comment
* fix: bugs revealed by getting the built output working (#6282)
* fix: types of compose and decompose in block
* fix: workspace naming in toolbox
* chore: add jsdoc
* chore: restore registry comments to better positions
* chore: pr comments'
* fix(variables): Revert inadvertent change to allDeveloperVariables (#6290)
It appears that a function call got modified incorrectly (probably
in an effort to fix a typing issue). This fix trivially reverts
the line in question to match the original JS version from develop.
This causes the generator tests to pass.
* fix: circular dependencies (#6281)
* chore: fix circular dependencies w/ static workspace funcs
* remove preserved imports that aren't currently necessary (probably)
* fix circular dependency with workspaces and block using stub
* fix dependency between variables and xml by moving function to utils
* add stub for trashcan as well
* fix line endings from rebase
* fix goog/base order
* add trashcan patch
* fix: types of compose and decompose in block
* fix: workspace naming in toolbox
* chore: add jsdoc
* chore: restore registry comments to better positions
* chore: remove implementations in goog.js
* chore: fix types of stubs
* chore: remove added AnyDuringMigration casts
* chore: remove modifications to xml and variables
* chore: format
* chore: remove event requirements in workspace comments
* chore: fix circular dependency with xml and workspace comments
* fixup remove ContextMenu import
* chore: fix dependency between mutator and workspace
* chore: break circular dependency between names and procedures
* chore: get tests to run?
* chore: pr comments'
* chore: fix stubbing field registry fromJson
* chore: fix spying on fire
* chore: fix stubbing parts of connection checker
* chore: fix stubbing dialog
* chore: fix stubbing style
* chore: fix spying on duplicate
* chore: fix stubbing variables
* chore: fix stubbing copy
* chore: fix stubbing in workspace
* chore: remove unnecessary stubs
* chore: fix formatting
* chore: fix other formatting
* chore: add backwards compatible static properties to workspace
* chore: move static type properties
* chore: move and comment stubs
* chore: add newlines at EOF
* chore: improve errors for monkey patched functions
* chore: update comment with a pointer to the doc
* chore: update comment with a pointer to the doc
* chore: format
* chore: revert changes to playground used for testing (#6292)
* chore: get mocha tests to pass. (#6291)
* chore: fix undo and empty code blocks
* chore: skip IE test
* chore: fix gesture test
* chore: fix replace message references test
* chore: fix string table interpolation
* chore: skip getById tests
* chore: fix field tests
* chore: fix console errors by making workspace nullable
* chore: format
* chore: fix definition overwrite warning
* chore: update metadata
* chore: temporarily modify the the advanced compile test
* chore: fix gestures by fixing test instead
Co-authored-by: Neil Fraser <fraser@google.com>
Co-authored-by: Christopher Allen <cpcallen+git@google.com>
