## The basics
- [x] I [validated my changes](https://developers.google.com/blockly/guides/contribute/core#making_and_verifying_a_change)
## The details
### Resolves
Fixes#8965Fixes#8978Fixes#8970
Fixes https://github.com/google/blockly-keyboard-experimentation/issues/523
Fixes https://github.com/google/blockly-keyboard-experimentation/issues/547
Fixes part of #8910
### Proposed Changes
Fives groups of changes are included in this PR:
1. Support for automatic tab index management for focusable trees.
2. Support for automatic tab index management for focusable nodes.
3. Support for automatically hiding the flyout when back navigating from the toolbox.
4. A fix for `FocusManager` losing DOM syncing that was introduced in #9082.
5. Some cleanups for flyout and some tests for previous behavior changes to `FocusManager`.
### Reason for Changes
Infrastructure changes reasoning:
- Automatically managing tab indexes for both focusable trees and roots can largely reduce the difficulty of providing focusable nodes/trees and generally interacting with `FocusManager`. This facilitates a more automated navigation experience.
- The fix for losing DOM syncing is possibly not reliable, but there are at least now tests to cover for it. This may be a case where a `try{} finally{}` could be warranted, but the code will stay as-is unless requested otherwise.
`Flyout` changes:
- `Flyout` no longer needs to be a focusable tree, but removing that would be an API breakage. Instead, it throws for most of the normal tree/node calls as it should no longer be used as such. Instead, its workspace has been made top-level tabbable (in addition to the main workspace) which solves the extra tab stop issues and general confusing inconsistencies between the flyout, toolbox, and workspace.
- `Flyout` now correctly auto-selects the first block (#9103 notwithstanding). Technically it did before, however the extra `Flyout` tabstop before its workspace caused the inconsistency (since focusing the `Flyout` itself did not auto-select, only selecting its workspace did).
Important caveats:
- `getAttribute` is used in place of directly fetching `.tabIndex` since the latter can apparently default to `-1` (and possibly `0`) in cases when it's not actually set. This is a very surprising behavior that leads to incorrect test results.
- Sometimes tab index still needs to be introduced (such as in cases where native DOM focus is needed, e.g. via `focus()` calls or clicking). This is demonstrated both by updates to `FocusManager`'s tests as well as toolbox's category and separator. This can be slightly tricky to miss as large parts of Blockly now depend on focus to represent their state, so clicking either needs to be managed by Blockly (with corresponding `focusNode` calls) or automatic (with a tab index defined for the element that can be clicked, or which has a child that can be clicked).
Note that nearly all elements used for testing focus in the test `index.html` page have had their tab indexes removed to lean on `FocusManager`'s automatic tab management (though as mentioned above there is still some manual tab index management required for `focus()`-specific tests).
### Test Coverage
New tests were added for all of the updated behaviors to `FocusManager`, including a new need to explicitly provide (and reset) tab indexes for all `focus()`-esque tests. This also includes adding new tests for some behaviors introduced in past PRs (a la #8910).
Note that all of the new and affected conditionals in `FocusManager` have been verified as having at least 1 test that breaks when it's removed (inverted conditions weren't thoroughly tested, but it's expected that they should also be well covered now).
Additional tests to cover the actual navigation flows will be added to the keyboard experimentation plugin repository as part of https://github.com/google/blockly-keyboard-experimentation/pull/557 (this PR needs to be merged first).
For manual testing, I mainly verified keyboard navigation with some cursory mouse & click testing in the simple playground. @rachel-fenichel also performed more thorough mouse & click testing (that yielded an actual issue that was fixed--see discussion below).
The core webdriver tests have been verified to have seemingly the same existing failures with and without these changes.
All of the following new keyboard navigation plugin tests have been verified as failing without the fixes introduced in this branch (and passing with them):
- `Tab navigating to flyout should auto-select first block`
- `Keyboard nav to different toolbox category should auto-select first block`
- `Keyboard nav to different toolbox category and block should select different block`
- `Tab navigate away from toolbox restores focus to initial element`
- `Tab navigate away from toolbox closes flyout`
- `Tab navigate away from flyout to toolbox and away closes flyout`
- `Tabbing to the workspace after selecting flyout block should close the flyout`
- `Tabbing to the workspace after selecting flyout block via workspace toolbox shortcut should close the flyout`
- `Tabbing back from workspace should reopen the flyout`
- `Navigation position in workspace should be retained when tabbing to flyout and back`
- `Clicking outside Blockly with focused toolbox closes the flyout`
- `Clicking outside Blockly with focused flyout closes the flyout`
- `Clicking on toolbox category focuses it and opens flyout`
### Documentation
No documentation changes are needed beyond the code doc changes included in the PR.
### Additional Information
An additional PR will be introduced for the keyboard experimentation plugin repository to add tests there (see test coverage above). This description will be updated with a link to that PR once it exists.
## The basics
- [x] I [validated my changes](https://developers.google.com/blockly/guides/contribute/core#making_and_verifying_a_change)
## The details
### Resolves
Fixes#8930
Fixes part of #8771
### Proposed Changes
This PR introduces support for connections to be focusable (and thus navigable with keyboard navigation when paired with downstream changes to `LineCursor` and the keyboard navigation plugin). This is a largely isolated change in how it fundamentally works:
- `RenderedConnection` has been updated to be an `IFocusableNode` using a new unique ID maintained by `Connection` and automatically enabling/disabling the connection highlight based on whether it's focused (per keyboard navigation).
- The way that rendering works here has changed: rather than recreating the connection's highlight SVG each time, it's only created once and updated thereafter to ensure that it correctly fits block resizes or movements. Visibility of the highlight is controlled entirely through display visibility and can now be done synchronously (which was a requirement for focusability as only displayed elements can be focused).
- This employs the same type of ID schema strategy as fields in #8923.
### Reason for Changes
This is part of an ongoing effort to ensure key components of Blockly are focusable so that they can be keyboard-navigable (with other needed changes yet both in Core Blockly and the keyboard navigation plugin).
### Test Coverage
No new tests have been added. It's certainly possible to add unit tests for the focusable configurations being introduced in this PR, but it may not be highly beneficial. It's largely assumed that the individual implementations should work due to a highly tested FocusManager, and it may be the case that the interactions of the components working together is far more important to verify (that is, the end user flows). The latter is planned to be tackled as part of #8915.
### Documentation
No documentation changes should be needed here.
### Additional Information
This includes changes that have been pulled from #8875.
_Note: This is a roll forward of #8916 that was reverted in #8933. See Additional Information below._
## The basics
- [x] I [validated my changes](https://developers.google.com/blockly/guides/contribute/core#making_and_verifying_a_change)
## The details
### Resolves
Fixes#8913Fixes#8914
Fixes part of #8771
### Proposed Changes
This updates `WorkspaceSvg` and `BlockSvg` to be focusable, that is, it makes the workspace a `IFocusableTree` and blocks `IFocusableNode`s.
Some important details:
- While this introduces focusable tree support for `Workspace` it doesn't include two other components that are obviously needed by the keyboard navigation plugin's playground: fields and connections. These will be introduced in subsequent PRs.
- Blocks are set up to automatically synchronize their selection state with their focus state. This will eventually help to replace `LineCursor`'s responsibility for managing selection state itself.
- The tabindex property for the workspace and its ARIA label have been moved down to the `.blocklyWorkspace` element itself rather than its wrapper. This helps address some tab stop issues that are already addressed in the plugin (via monkey patches), but also to ensure that the workspace's main SVG group interacts correctly with `FocusManager`.
- `WorkspaceSvg` is being initially set up to default to its first top block when being focused for the first time. This is to match parity with the keyboard navigation plugin, however the latter also has functionality for defaulting to a position when no blocks are present. It's not clear how to actually support this under the new focus-based system (without adding an ephemeral element on which to focus), or if it's even necessary (since the workspace root can hold focus).
- `css.ts` was updated to remove `blocklyActiveFocus` and `blocklyPassiveFocus` since these have unintended highlighting consequences that aren't actually desirable yet. Instead, the exact styling for active/passive focus will be iterated in the keyboard navigation plugin project and moved to Core once finalized.
### Reason for Changes
This is part of an ongoing effort to ensure key components of Blockly are focusable so that they can be keyboard-navigable (with other needed changes yet both in Core Blockly and the keyboard navigation plugin).
### Test Coverage
No new tests have been added. It's certainly possible to add unit tests for the focusable configurations being introduced in this PR, but it may not be highly beneficial. It's largely assumed that the individual implementations should work due to a highly tested FocusManager, and it may be the case that the interactions of the components working together is far more important to verify (that is, the end user flows). The latter is planned to be tackled as part of #8915.
### Documentation
No documentation changes should be needed here.
### Additional Information
This includes changes that have been pulled from #8875.
This was originally merged in #8916 but was reverted in #8933 due to https://github.com/google/blockly-keyboard-experimentation/issues/481. This actually contains no differences from the original PR except for `css.ts` which are documented above. It does employ a new merge strategy: all of the necessary PRs to move both Core and the plugin over to using `FocusManager` will be staged and merged in quick succession as ensuring the plugin works for each constituent change (vs. the final one) is quite complex. Thus, this PR *does* break the plugin, and won't be merged until its subsequent PRs are approved and also ready for merging.
Edit: See https://github.com/google/blockly/pull/8938#issuecomment-2843589525 for why this actually is being merged a bit sooner than originally planned. Keeping the original reasoning above for context.
* Revert "feat: Make toolbox and flyout focusable (#8920)"
This reverts commit 5bc83808bf.
* Revert "feat: Make WorkspaceSvg and BlockSvg focusable (#8916)"
This reverts commit d7680cf32e.
## The basics
- [x] I [validated my changes](https://developers.google.com/blockly/guides/contribute/core#making_and_verifying_a_change)
## The details
### Resolves
Fixes#8913Fixes#8914
Fixes part of #8771
### Proposed Changes
This updates `WorkspaceSvg` and `BlockSvg` to be focusable, that is, it makes the workspace a `IFocusableTree` and blocks `IFocusableNode`s.
Some important details:
- While this introduces focusable tree support for `Workspace` it doesn't include two other components that are obviously needed by the keyboard navigation plugin's playground: fields and connections. These will be introduced in subsequent PRs.
- Blocks are set up to automatically synchronize their selection state with their focus state. This will eventually help to replace `LineCursor`'s responsibility for managing selection state itself.
- The tabindex property for the workspace and its ARIA label have been moved down to the `.blocklyWorkspace` element itself rather than its wrapper. This helps address some tab stop issues that are already addressed in the plugin (via monkey patches), but also to ensure that the workspace's main SVG group interacts correctly with `FocusManager`.
- `WorkspaceSvg` is being initially set up to default to its first top block when being focused for the first time. This is to match parity with the keyboard navigation plugin, however the latter also has functionality for defaulting to a position when no blocks are present. It's not clear how to actually support this under the new focus-based system (without adding an ephemeral element on which to focus), or if it's even necessary (since the workspace root can hold focus).
### Reason for Changes
This is part of an ongoing effort to ensure key components of Blockly are focusable so that they can be keyboard-navigable (with other needed changes yet both in Core Blockly and the keyboard navigation plugin).
### Test Coverage
No new tests have been added. It's certainly possible to add unit tests for the focusable configurations being introduced in this PR, but it may not be highly beneficial. It's largely assumed that the individual implementations should work due to a highly tested FocusManager, and it may be the case that the interactions of the components working together is far more important to verify (that is, the end user flows). The latter is planned to be tackled as part of #8915.
### Documentation
No documentation changes should be needed here.
### Additional Information
This includes changes that have been pulled from #8875.
* 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
* 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
* 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
* chore: remove AnyDuringMigration from common renderer
* chore: remove AnyDuringMigration in common drawer
* chore: format
* chore: add dividers back
* chore: format
* 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>
