From 2cb1bde0902880c2eaa98603112baaf837f19375 Mon Sep 17 00:00:00 2001 From: Rachel Fenichel Date: Mon, 18 May 2026 12:48:26 -0700 Subject: [PATCH 1/3] chore(docs): update keyboard shortcut page for v13 --- .../guides/configure/web/keyboard-nav.mdx | 8 ++++ .../configure/web/keyboard-shortcuts.mdx | 39 +++++++++++-------- 2 files changed, 31 insertions(+), 16 deletions(-) diff --git a/packages/docs/docs/guides/configure/web/keyboard-nav.mdx b/packages/docs/docs/guides/configure/web/keyboard-nav.mdx index 70fe1876139..ef29a42a24d 100644 --- a/packages/docs/docs/guides/configure/web/keyboard-nav.mdx +++ b/packages/docs/docs/guides/configure/web/keyboard-nav.mdx @@ -68,6 +68,14 @@ From a computer science perspective a block program is an abstract syntax tree. Arrow keys allow for navigation up/down and left/right within the tree, while tab navigation only supports a fixed order. +## Why single-key shortcuts? + +Pressing multiple keys at the same time (e.g. `Ctrl + C`) requires manual +dexterity and awareness of keyboard layout that may not be fully developed +by the time children start using Blockly in school. It is also difficult to +create a set of keyboard shortcuts that work across all OS and browser +combinations. Single-key shortcuts address both issues. + ## Technical details Blockly keyboard navigation uses the [focus system](/guides/configure/web/focus) diff --git a/packages/docs/docs/guides/configure/web/keyboard-shortcuts.mdx b/packages/docs/docs/guides/configure/web/keyboard-shortcuts.mdx index 39a53aa9a64..acc2077dbab 100644 --- a/packages/docs/docs/guides/configure/web/keyboard-shortcuts.mdx +++ b/packages/docs/docs/guides/configure/web/keyboard-shortcuts.mdx @@ -7,10 +7,9 @@ image: images/blockly_banner.png # Keyboard shortcuts Blockly maintains a registry of keyboard shortcuts that map keys (or key -combinations like `ctrl-C`) to actions. The registry is -[prepopulated](#default-shortcuts) with a number of shortcuts, such as `ctrl-C` -and `meta-C` for copy. You can add shortcuts to and delete shortcuts from the -registry. +combinations) to actions. The registry is [prepopulated](#default-shortcuts) +with a number of shortcuts, such as `Ctrl + C` and `Meta + C` for copy. You can +add shortcuts to and delete shortcuts from the registry. ## How keyboard shortcuts work @@ -44,7 +43,8 @@ implements [`IFocusableNode`](/reference/blockly.ifocusablenode). This interface is implemented by all Blockly components that the user can focus on, including workspaces, blocks, fields, comments, and your own custom components; -for more information, see [Focus system](/guides/configure/web/focus). +for more information, see the documentation on the +[focus system](/guides/configure/web/focus). For example, a `preconditionFn` might use `focusedNode` to ensure that a shortcut only applies to blocks. @@ -73,6 +73,9 @@ const logFieldsShortcut = { }; ``` +You can use the shortcut name to associate keyboard shortcuts with +[context menu items](/guides/configure/web/context-menus#keyboard-shortcut). + ### preconditionFn (optional) Blockly calls this function to decide if a shortcut applies to the current @@ -128,8 +131,8 @@ const logFieldsShortcut = { }; ``` -Although `callback` is optional, there is generally no reason not to implement -it. +Although `callback` is optional, leaving it undefined means your shortcut will +not do anything. ### keyCodes (optional) @@ -270,12 +273,16 @@ Blockly.ShortcutRegistry.registry.register(modLogFieldsShortcut); The shortcut registry is prepopulated with a number of shortcuts. You can find these in [https://github.com/RaspberryPiFoundation/blockly/blob/main/packages/blockly/core/shortcut_items.ts](https://github.com/RaspberryPiFoundation/blockly/blob/main/packages/blockly/core/shortcut_items.ts). -The shortcuts are defined in the `registerXxxx` functions. - -## Keyboard navigation shortcuts - -The [keyboard navigation plugin](/guides/configure/web/keyboard-nav) -contains shortcuts that allow users to navigate Blockly with the keyboard, such -as by using arrow keys. Keyboard navigation is essential for users who cannot -use a mouse, such as those with motor or visual impairments. It is also useful -for power users who may want to use keyboard shortcuts for efficiency. +The shortcuts are defined in the `registerXxxx` functions. You can also view +all currently registered shortcuts by running +`Blockly.ShortcutRegistry.registry.getKeyMap()`. + +### Keyboard navigation + +Starting in v13, Blockly can be entirely +[controlled from the keyboard](/guides/configure/web/keyboard-nav). Where +possible developers should use the default keyboard navigation shortcuts rather +than overriding or remapping them. Keyboard navigation is essential for users +who cannot use a mouse, such as those with motor or visual impairments. It is +also useful for power users who may want to use keyboard shortcuts for +efficiency. From 9a1d93cb10fde8dc712210d29b9b5fb27335cb6c Mon Sep 17 00:00:00 2001 From: Rachel Fenichel Date: Mon, 18 May 2026 12:51:03 -0700 Subject: [PATCH 2/3] chore(docs): update nesting on keyboard nav documentation --- .../docs/guides/configure/web/keyboard-nav.mdx | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/packages/docs/docs/guides/configure/web/keyboard-nav.mdx b/packages/docs/docs/guides/configure/web/keyboard-nav.mdx index ef29a42a24d..51b3805326a 100644 --- a/packages/docs/docs/guides/configure/web/keyboard-nav.mdx +++ b/packages/docs/docs/guides/configure/web/keyboard-nav.mdx @@ -55,7 +55,13 @@ information about the cursor location and **control + enter** (Windows) or **command + enter** (Mac) to open the context menu. Cut, copy/paste, and undo/redo all follow conventions for keyboard shortcuts. -## Why not tab? +## Technical details + +Blockly keyboard navigation uses the [focus system](/guides/configure/web/focus) +to manage the location of the cursor. This code will be released in Blockly v13 +(targeted release: June 2026). + +### Why not tab? Blockly does not follow the convention to navigate around a page with **tab** and **shift + tab** because block code cannot usefully be compressed into a @@ -68,7 +74,7 @@ From a computer science perspective a block program is an abstract syntax tree. Arrow keys allow for navigation up/down and left/right within the tree, while tab navigation only supports a fixed order. -## Why single-key shortcuts? +### Why single-key shortcuts? Pressing multiple keys at the same time (e.g. `Ctrl + C`) requires manual dexterity and awareness of keyboard layout that may not be fully developed @@ -76,12 +82,6 @@ by the time children start using Blockly in school. It is also difficult to create a set of keyboard shortcuts that work across all OS and browser combinations. Single-key shortcuts address both issues. -## Technical details - -Blockly keyboard navigation uses the [focus system](/guides/configure/web/focus) -to manage the location of the cursor. This code will be released in Blockly v13 -(targeted release: June 2026). - ### Compliance Blockly's keyboard navigation system meets the following WCAG criteria: From 61ab35082343f8d229ad63a2dbab459697721d30 Mon Sep 17 00:00:00 2001 From: Rachel Fenichel Date: Mon, 18 May 2026 13:06:19 -0700 Subject: [PATCH 3/3] chore(docs): remove references to META keycode in favor of CTRL_CMD --- .../configure/web/keyboard-shortcuts.mdx | 38 +++++-------------- 1 file changed, 9 insertions(+), 29 deletions(-) diff --git a/packages/docs/docs/guides/configure/web/keyboard-shortcuts.mdx b/packages/docs/docs/guides/configure/web/keyboard-shortcuts.mdx index acc2077dbab..1877718cf4b 100644 --- a/packages/docs/docs/guides/configure/web/keyboard-shortcuts.mdx +++ b/packages/docs/docs/guides/configure/web/keyboard-shortcuts.mdx @@ -8,8 +8,8 @@ image: images/blockly_banner.png Blockly maintains a registry of keyboard shortcuts that map keys (or key combinations) to actions. The registry is [prepopulated](#default-shortcuts) -with a number of shortcuts, such as `Ctrl + C` and `Meta + C` for copy. You can -add shortcuts to and delete shortcuts from the registry. +with a number of shortcuts, such as `Ctrl + C` and `Command + C` for copy. You +can add shortcuts to and delete shortcuts from the registry. ## How keyboard shortcuts work @@ -158,41 +158,21 @@ This is not common. If your keyboard shortcut is activated by a combination of keys, such as holding `Control` and `C` simultaneously, create a serialized keycode by calling -`Blockly.ShortcutRegistry.registry.createSerializedKey`: +`Blockly.ShortcutRegistry.registry.createSerializedKey`. On Windows and Linux +many shortcuts are activated with the `Control` key. On Apple plaforms these +keyboard shortcuts use the `Command` key instead. Register your shortcuts with +the `CTRL_CMD` keycode whenever you want your shortcut to use the system's +primary modifier key. Blockly will map the key combination appropriately. ```js const ctrlC = Blockly.ShortcutRegistry.registry.createSerializedKey( - Blockly.utils.KeyCodes.C, // Keycode of main key - [Blockly.utils.KeyCodes.CTRL], // Array of modifier keys -); - -const copyShortcut = { - // ... - keyCodes: [ctrlC], // Use the serialized keycode - // ... -}; -``` - -#### Control and Meta - -On Windows, many shortcuts are activated with the `Control` key. On Mac, these -keyboard shortcuts use the `Command` key instead, which is recognized as the -`META` keycode. To support both operating systems, register your shortcuts with -both the `CTRL` keycode and the `META` keycode. - -```js -const ctrlC = Blockly.ShortcutRegistry.registry.createSerializedKey( - Blockly.utils.KeyCodes.C, - [Blockly.utils.KeyCodes.CTRL], -); -const metaC = Blockly.ShortcutRegistry.registry.createSerializedKey( Blockly.utils.KeyCodes.C, - [Blockly.utils.KeyCodes.META], + [Blockly.utils.KeyCodes.CTRL_CMD], ); const copyShortcut = { // ... - keyCodes: [ctrlC, metaC], + keyCodes: [ctrlC], // ... }; ```