## The basics
- [x] I [validated my changes](https://developers.google.com/blockly/guides/contribute/core#making_and_verifying_a_change)
## The details
### Resolves
Fixes part of https://github.com/RaspberryPiFoundation/blockly-keyboard-experimentation/issues/764
Fixes part of #9450 (infrastructure needs)
### Proposed Changes
Introduces support for two new "where am I?" shortcuts for helping to provide location context for users:
- `I`: re-reads the current selected block with full verbosity (i.e. also includes the block's field types with their values in the readout).
- `shift+I`: reads the current selected block's parent with full verbosity.
Note that this includes some functional changes to `Field` to allow for more powerful customization of a field's ARIA representation (by splitting up value and type), though a field's value defaults potentially to null which will be ignored in the final ARIA computed label. This seems necessary per the discussion here: https://github.com/RaspberryPiFoundation/blockly/pull/9470/files#r2541508565 but more consideration may be needed here as part of #9307.
Some limitations in the new shortcuts:
- They will not read out anything if a block is not selected (e.g. for fields and icons).
- They read out input blocks when the input block is selected.
- They cannot read out anything while in move mode (due to the behavior here in the plugin which automatically cancels moves if an unknown shortcut is pressed: a36f3662b0/src/actions/mover.ts (L166-L191)).
- The readout is limited by the problems of dynamic ARIA announcements (per #9460).
### Reason for Changes
https://github.com/RaspberryPiFoundation/blockly-keyboard-experimentation/issues/764 provides context on the specific needs addressed here.
### Test Coverage
Self tested. No new automated tests needed for experimental work.
### Documentation
No new documentation needed for experimental work.
### Additional Information
This was spun out of #9470 with the intent of getting shortcuts initially working checked in even if the entirety of the experience is incomplete.
## The basics
- [x] I [validated my changes](https://developers.google.com/blockly/guides/contribute/core#making_and_verifying_a_change)
## The details
### Resolves
Fixes#9301Fixes#9312Fixes#9313
Fixes part of #9304
### Proposed Changes
This introduces a variety of specific changes to resolve several issues for screen reader work, including introducing fundamental support for field labeling.
Specifically:
- Field labels have been simplified to only use their custom defined ARIA name otherwise they are null (and thus should be ignored for readout purposes) which wraps up the remaining high-level work for #9301 (#9450 tracks more specific follow-up work to improve upon what's been established at this point). The PR also introduces an ARIA override for number inputs in math blocks so that the readout is correct for them.
- Bubble labeling is more explicit now which is useful for mutators (#9312), warnings, and comments. The general improvement for bubbles wraps up the remaining work for #9313 as well since the core issue was resolved in #9351. By default a bubble has no ARIA label.
- #9304 is partly being addressed here with the change to field images: they are no longer being added to the accessibility node tree unless they are actually navigable (that is, clickable). Part of #9304's goal is to remove extraneous nodes.
- Finally, a typo was fixed for 'replaceable blocks' since these were not reading out correctly. This was noticed in passing and isn't directly related to the other issues.
### Reason for Changes
This PR is largely being used as a basis for one particularly significant issue: #9301. Field labeling has undergone several iterations over the past few months and the team seems comfortable sticking with a "do as little as possible" approach when determining the label, thus justifying the need for expecting more specific customization (i.e. #9450). To this end it's important to be clear that getting fields to a good state is not actually "done" but the need to track it as a large incomplete thing has ended. Note that one important part of #9301 was updating field plugins to be accessible--this largely seems unnecessary as-is as it will be completely dependent on the needs of future user tests. The long-term plan will need to account for making all fields in `blockly-samples` accessible (per #9307).
Some of the terminology used here (e.g. for bubbles) will likely need to change after user testing, but it's important to establish that _something_ correct is communicated even if the terminology may require scaffolding and/or refinement.
It's important to note that while non-clickable field images are no longer in the node graph, their ARIA presence still exists as part of the fluent block labeling solution. That is, `FieldImage`'s alt text is used as part of constructing a fluent block label (sometimes to confusing effect--see #9452).
### Test Coverage
No tests needed since these are experimental changes and do not change existing test behaviors.
### Documentation
No documentation changes are needed for these experimental changes.
### Additional Information
None.
## 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.
* refactor(VariableMap): Stop using deprecated wrapper methods
* fix format
* fix: Apply review suggestions
Co-authored-by: Christopher Allen <cpcallen+github@gmail.com>
* fix: restore blank line
---------
Co-authored-by: Christopher Allen <cpcallen+github@gmail.com>
* feat!: Make bubbles, comments, and icons focusable
* feat!: Make ISelectable and ICopyable focusable.
* feat: Consolidate selection calls.
Now everything is based on focus with selection only being used as a
proxy.
* feat: Invert responsibility for setSelected().
Now setSelected() is only for quasi-external use.
* feat: Push up shadow check to getters.
Needed new common-level helper.
* chore: Lint fixes.
* feat!: Allow IFocusableNode to disable focus.
* chore: post-merge lint fixes
* fix: Fix tests + text bubble focusing.
This fixed then regressed a circular dependency causing the node and
advanced compilation steps to fail. This investigation is ongoing.
* fix: Clean up & fix imports.
This ensures the node and advanced compilation test steps now pass.
* fix: Lint fixes + revert commented out logic.
* chore: Remove unnecessary cast.
Addresses reviewer comment.
* fix: Some issues and a bunch of clean-ups.
This addresses a bunch of review comments, and fixes selecting workspace
comments.
* chore: Lint fix.
* fix: Remove unnecessary shadow consideration.
* chore: Revert import.
* chore: Some doc updates & added a warn statement.
* fix: improve variable deletion behaviors.
* fix: don't prompt about deletion of only 1 variable block when triggered programmatically.
* fix: include the triggering block in the count of referencing blocks
* fix: only count the triggering block as a referencing block if it's not in the flyout
* chore(deps): Add pretter-plugin-organize-imports
* chore: Remove insignificant blank lines in import sections
Since prettier-plugin-organize-imports sorts imports within
sections separated by blank lines, but preserves the section
divisions, remove any blank lines that are not dividing imports
into meaningful sections.
Do not remove blank lines separating side-effect-only imports
from main imports.
* chore: Remove unneded eslint-disable directives
* chore: Organise imports
* docs(block): Improve documentation for well-known block methods
Improve the JSDocs for the declarations of well-known block
methods:
- getDeveloperVariables
- compose
- decompose
- saveConnections
* docs(blocks): Improve block comments
Fix JSDoc formatting in both core/block.ts and blocks/*, as well as
making various other minor improvments.
* chore(blocks): Remove one unexported const
* 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.
* chore: delete mocha tests for angle field
* feat! : delete angle field
* chore(tests): delete colour tests from generator tests and golden files
* chore: delete colour blocks and associated generators
* chore: remove colour blocks from playgrounds
* chore: delete mocha tests for colour fields
* chore: fix incorrect comment
* chore: delete colour field from core
* chore: delete multiline input tests from generators tests and golden files
* chore: delete multiline text block and associated generators
* chore: remove multiline text block from playgrounds
* chore: delete mocha tests for multiline input field
* chore: delete multiline input field from core
* refactor(generators): Migrate javascript_generator.js to TypeScript
* refactor(generators): Simplify getAdjusted
Slightly simplify the implementation of getAdjusted, in part to
make it more readable. Also improve its JSDoc comment.
* refactor(generators): Migrate generators/javascript/* to TypeScript
First pass doing very mechanistic migration, not attempting to fix
all the resulting type errors.
* fix(generators): Fix type errors in generator functions
This consists almost entirely of adding casts, so the code output
by tsc should be as similar as possible to the pre-migration .js
source files.
* refactor(generators): Migrate generators/javascript.js to TypeScript
The way the generator functions are added to
javascriptGenerator.forBlock has been modified so that incorrect
generator function signatures will cause tsc to generate a type
error.
* chore(generator): Format
One block protected with // prettier-ignore to preserve careful
comment formatting.
Where there are repeated concatenations prettier has made a pretty
mess of things, but the correct fix is probably to use template
literals instead (rather than just locally disabling prettier).
This has been added to the to-do list in #7600.
* fix(generators): Fixes for PR #7602
* fix(generators): Fix syntax error
* 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
Where certain block mixin methods had been marked @private,
and these annotations had been deleted while migrating the
containing files to TypeScript, mark those methods as
@internal.
* fix: input exports
* chore: fix build
* chore: attempt to fix build
* chore: attempt to fix build
* chore: create new align enum to replace old one
* chore: format
* fix: Tweak renamings entries
It appears that the goal is to map:
Blockly.Input.Align -> Blockly.inputs.Align
Blockly.Align -> Blockly.inputs.Align
Blockly.ALIGN_* -> Blockly.inputs.Align.*
I believe this commit achieves that in a more minimal (and correct)
way—but if I have misunderstood the intention then this will not
be a useful correction.
---------
Co-authored-by: Christopher Allen <cpcallen+git@google.com>
* feat: add basic mutator icon
* feat: add actual mutation behavior to icon
* chore: add bumping blocks back into the bubble
* fix: add updating block styles
* feat: add static methods to mutator icon
* chore: delete old mutator code
* fix: use the new mutator icon
* chore: docs and format
* chore: my own comments
* chore: first pass at PR comments
* chore: make type strings internal
* chore: add todo
* chore: format
* chore: move properties to module level
* chore: fix using in demos
* chore: move Mutator to icons.MutatorIcon
* chore: move reconnect to connection
* chore: move findParentWs to workspace
* chore: properly override and call super
* chore: remove bubbleIsVisible check
* chore: change imports to import type
* chore: use elvis operator
* chore: update renamings
* chore: reduce changes to js block files
* chore: remove render call from procedure blocks
* chore: have workspace queue renders when unhiding
* chore: remove forced rendering from flyouts
* chore: change mutators to use queueing
* chore: change shadows to use queueing
* chore: add comments about icon rendering
* chore: move input and input types into new directory
* feat: define and export new input types
* feat: modify blocks to construct individual inputs
* chore: transition code to use actual type checks
* chore: fixup input type type
* chore: format
* chore: fixup PR comments
* chore: fix build
* refactor(blocks): auto-migration of blocks/text.js to ts
* refactor(blocks): fix up some types in blocks/text.ts
* refactor(blocks): improve some types in text.ts
* refactor(blocks): additional type cleanups
* chore: format
* chore: fix typo
* chore: respond to PR comments
* chore: respond to PR comments
* refactor: run js2ts on variables
* refactor: clean up conversion of variables blocks to typescript
* refactor: add types for custom context menu options
* refactor: run js2ts on blocks/variables_dynamic.js
* refactor: clean up types in variables_dynamic
* chore: respond to PR comments
* chore: format
* refactor(blocks): Auto-migration of blocks/loops.js to ts
* fix(blocks): Manually migrate types and fix imports in loops.ts
* chore: respond to PR comments
* refactor(blocks): Auto-migration of blocks/lists.js to ts
* fix(blocks): Manually migrate & fix types in lists.ts
* chore(blocks): format lists.ts
Not running clang-format on this as for some reason it decides
half way through the file to indent everything after that by
an extra four spaces (and then has to re-wrap a bunch of lines
that are consequently too long).
* refactor(blocks): Improve types in lists.ts
It turns out that the way I originally specified the types for
the mixins meant that they were all 'any', which is a bit
useless. Change them so that tsc actually typechecks
properties (including method calls) on the mixed-in blocks,
and then fix the numerous additional type errors which
doing this revealed.
(By "fix", I mean apply "as" casts and "!"s as required to
suppress type errors from tsc. Actually fixing the code in a
way that makes the blocks meaningfully more bulletproof is
left as an exercise to the reader - sorry, I mean: will be
dealt with in a future PR.)
* fix(blocks): Additional fixes for comments PR #6902
* refactor(blocks): Auto-migration of blocks/math.js to ts
This is just the result of running js2ts on this file.
* fix(blocks): Manually migrate & fix types in math.ts
* chore(blocks): clang-format math.ts
* fix(blocks): Corrections for comments on PR #6900
* refactor(blocks): Define types for mixin-ed blocks, etc.
Define types to represent the union of Block and each of the
*_MIXINs, and use these types for the type of this in mixin
methods.
* refactor(blocks): Misc minor changes
Make sure validator functions explicitly return undefined.
Field.prototype.setValidator takes a FieldValidator<T>, which
must be a non-void function. I'm not sure why tsc was not
objecting to the void implementation here, but it does in
other very similar situations so for consistency explicitly
return undefined to signal the value should be used unchanged.
Also undo previous change of !. to ?.: I think it wisest to
try to preserve the existing behaviour as exactly as possible
for now, and make behaviour changes (i.e., ones that affect
the generated code) separately.
* fix(blocks): Fix erroneous typing of mixins
It turns out that the previous types for these were completely
wrong, for two reasons:
- They should be intersection types (which have the union of the
properties), not union types (which have the interseciton of the
properties).
- The *_MIXIN types were already declared as having type
BlockDefinition, which is ultimately an alias for any.
TypeScript doesn't like (some) kinds of circularly defined types,
so fixing the above necessitates declaring a few auxiliary types
just to make the type checker happy - but the end result is
excellent and caught an actual type error in the code.
