diff --git a/packages/docs/docs/guides/configure/web/keyboard-nav.mdx b/packages/docs/docs/guides/configure/web/keyboard-nav.mdx index 38a84316667..24954206276 100644 --- a/packages/docs/docs/guides/configure/web/keyboard-nav.mdx +++ b/packages/docs/docs/guides/configure/web/keyboard-nav.mdx @@ -4,30 +4,88 @@ title: Keyboard navigation image: images/blockly_banner.png --- -# Keyboard navigation - -Blockly provides keyboard navigation through the `@blockly/keyboard-navigation` -plugin. This code uses the [focus system](/guides/configure/web/focus) -and will eventually be integrated into Blockly core. - -You can [download the plugin from -npm](https://www.npmjs.com/package/@blockly/keyboard-navigation) or get the code -from the [`blockly-keyboard-experimentation` -repository](https://github.com/RaspberryPiFoundation/blockly-keyboard-experimentation/) on -GitHub. - -If you want to play with the plugin, visit the [accessibility plugin -playground](https://raspberrypifoundation.github.io/blockly-keyboard-experimentation/). - -- To get started, click the workspace or press `tab` until you reach the - workspace. -- Use the arrow keys to move around. -- Press `T` to open the toolbox. -- Press `Enter` or `Space` to edit or confirm. -- Press `/` for a complete list of keyboard commands. - -For more information about our accessibility projects, visit [our accessibility -page](https://developers.google.com/blockly/accessibility#projects). +# Using Blockly with the keyboard + +Blockly’s keyboard navigation and screen reader support are implemented around +the concept of a **cursor** representing the user’s location on the workspace. +The user can move the cursor with either the keyboard or with the mouse, just +like in a text editor. Keyboard shortcuts act on the item under the cursor. +The screen reader reads information about the item under the cursor. + +## Basic operation + +A user has to be able to easily complete five basic operations when using +Blockly. Let’s walk through those operations, and how to accomplish them with +the keyboard. + +- Read an existing program by using the arrow keys to move around the workspace. + - **Up** and **down** let you move line-by-line, while **left** and **right** +move within a line of code. + - Blockly creates an appropriate text description of each cursor location that + can be read out by a screen reader. +- Edit values on blocks by moving the cursor to a modifiable value and pressing +**enter** to open the field editor. +- Move blocks in the workspace to create or modify a program by pressing **M** +to pick up a block, moving it with the **arrow keys**, and pressing **enter** to +drop the block in a new location. + - By default the arrow keys move a block between legal locations on the +workspace. + - Holding a modifier key moves the block as though it were being dragged with +a mouse. +- Insert blocks from the toolbox to create or modify a program by pressing **T** +to open the toolbox and using the **arrow keys** to select a block to insert. + - Pressing **enter** moves the block to the workspace in move mode. +- Delete blocks to modify a program by moving the cursor to a block and +pressing **delete** or **backspace**. + +### Try it! + +Try it yourself on the [Blockly playground](https://raspberrypifoundation.github.io/blockly/packages/blockly/tests/playground.html): +- Click on the workspace or press **tab** to move focus through the page to the workspace. +- Press **T** to open the toolbox and use the **arrow keys** to select a block. +- Press **enter** to insert the block. +- Repeat to build a program. +- Use the **arrow keys** to navigate to a field and press **enter** to edit the +field value. + +## Advanced operation + +Blockly provides many other keyboard shortcuts, including **I** to get +information about the cursor location and **meta + enter** to open the context +menu. Cut, copy/paste, and undo/redo all follow conventions for keyboard +shortcuts. + +## 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 +linear navigation order. Blocks can contain other blocks, both horizontally and +vertically, and require at least two dimensions to navigate. Tests with learners +showed that arrow key navigation supported their understanding of programming +concepts. + +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. + +## 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: +- [1.3.2 Meaningful Sequence (Level A)](https://www.w3.org/WAI/WCAG22/Understanding/meaningful-sequence) +- [2.1.1 Keyboard (Level A)](https://www.w3.org/WAI/WCAG22/Understanding/keyboard) +- [2.1.2 No Keyboard Trap (Level A)](https://www.w3.org/WAI/WCAG22/Understanding/no-keyboard-trap) +- [2.1.4 Character Key Shortcuts (Level A)](https://www.w3.org/WAI/WCAG22/Understanding/keyboard-no-exception) + - Character key shortcuts are active only on workspace focus. +- [2.4.3 Focus Order (Level A)](https://www.w3.org/WAI/WCAG22/Understanding/focus-order) +- [2.4.7 Focus Visible (Level AA)](https://www.w3.org/WAI/WCAG22/Understanding/focus-visible) +- [3.2.4 Consistent Identification (Level AA)](https://www.w3.org/WAI/WCAG22/Understanding/consistent-identification) +- [4.1.2 Name, Role, Value (Level A)](https://www.w3.org/WAI/WCAG22/Understanding/name-role-value) :::note The 0.6 version of the keyboard navigation plugin that existed prior to diff --git a/packages/docs/sidebars.js b/packages/docs/sidebars.js index 26de3719d5e..627ab67dc45 100644 --- a/packages/docs/sidebars.js +++ b/packages/docs/sidebars.js @@ -1273,6 +1273,17 @@ const sidebars = { }, ], }, + { + type: 'category', + label: 'Accessibility', + items: [ + { + type: 'doc', + label: 'Compliance', + id: 'guides/app-integration/compliance', + }, + ], + }, { type: 'doc', label: 'Attribute Blockly',