feat: Introduce initial screen reader support (experimental) (#684)

Fixes part of RaspberryPiFoundation/blockly#3370
Fixes part of RaspberryPiFoundation/blockly#9283

This PR introduces the plugin corresponding changes needed by RaspberryPiFoundation/blockly#9280.

In particular, this:
- Introduces CI workflow updates so that "tip-of-tree" is redefined as the corresponding experimental branch in core for screen reader support (to ensure CI passes here for changes that happen there).
- Removes some access error overrides since the corresponding field was made public in the core PR (which is the root of the CI failures here).
- Introduces some general instructions in the navigation plugin playground for folks testing Blockly with a screen reader (and points to #673 for discussion).

**Important**: Note that this PR's changes will NOT be merged into the `main` branch as-is. They will be reconsidered entirely (and likely largely reimplemented) separately from this experimental branch and submitted as a separate, future review for `main`. See RaspberryPiFoundation/blockly#9280 and Fixes part of RaspberryPiFoundation/blockly#9283 for more specifics on why the separate branch thing is being set up this way.

Author: BenHenning

.github/workflows/build.yml

@@ -6,14 +6,14 @@ on:
   pull_request:
   push:
     branches:
-      - main
+      - add-screen-reader-support-experimental
 
 permissions:
   contents: read
 
 jobs:
   build_tip_of_tree_v12:
-    name: Build test (against tip-of-tree core develop)
+    name: Build test (against add-screen-reader-support-experimental core develop)
     runs-on: ubuntu-latest
     steps:
       - name: Checkout experimentation plugin
@@ -25,7 +25,7 @@ jobs:
         uses: actions/checkout@v4
         with:
           repository: 'google/blockly'
-          ref: 'develop'
+          ref: 'add-screen-reader-support-experimental'
           path: core-blockly
 
       - name: Use Node.js 20.x
@@ -42,7 +42,7 @@ jobs:
           npm install
           cd ..
 
-      - name: Link latest Blockly develop
+      - name: Link latest Blockly add-screen-reader-support-experimental
         run: |
           cd core-blockly
           npm run package
@@ -57,26 +57,6 @@ jobs:
           cd main
           npm run build
 
-  build:
-    name: Build test (against pinned v12)
-    # Don't run pinned version checks for PRs.
-    if: ${{ !github.base_ref }}
-    runs-on: ubuntu-latest
-    steps:
-      - name: Checkout experimentation plugin
-        uses: actions/checkout@v4
-
-      - name: Use Node.js 20.x
-        uses: actions/setup-node@v4
-        with:
-          node-version: 20.x
-
-      - name: NPM install
-        run: npm install
-
-      - name: Verify build
-        run: npm run build
-
   lint:
     name: Eslint check
     timeout-minutes: 5

.github/workflows/test.yml

@@ -7,14 +7,14 @@ on:
   pull_request:
   push:
     branches:
-      - main
+      - add-screen-reader-support-experimental
 
 permissions:
   contents: read
 
 jobs:
-  webdriverio_tests_tip_of_tree_v12:
-    name: WebdriverIO tests (against tip-of-tree core develop)
+  webdriverio_tests:
+    name: WebdriverIO tests (against add-screen-reader-support-experimental core develop)
     timeout-minutes: 10
     runs-on: ${{ matrix.os }}
 
@@ -29,11 +29,11 @@ jobs:
         with:
           path: main
 
-      - name: Checkout core Blockly
+      - name: Checkout experimentation Blockly
         uses: actions/checkout@v4
         with:
           repository: 'google/blockly'
-          ref: 'develop'
+          ref: 'add-screen-reader-support-experimental'
           path: core-blockly
 
       - name: Use Node.js 20.x
@@ -50,7 +50,7 @@ jobs:
           npm install
           cd ..
 
-      - name: Link latest Blockly develop
+      - name: Link latest Blockly add-screen-reader-support-experimental
         run: |
           cd core-blockly
           npm run package
@@ -64,30 +64,3 @@ jobs:
         run: |
           cd main
           npm run test
-
-  webdriverio_tests:
-    name: WebdriverIO tests (against pinned v12)
-    # Don't run pinned version checks for PRs.
-    if: ${{ !github.base_ref }}
-    timeout-minutes: 10
-    runs-on: ${{ matrix.os }}
-
-    strategy:
-      fail-fast: false
-      matrix:
-        os: [ubuntu-latest, macos-latest]
-
-    steps:
-      - name: Checkout experimentation plugin
-        uses: actions/checkout@v4
-
-      - name: Use Node.js 20.x
-        uses: actions/setup-node@v4
-        with:
-          node-version: 20.x
-
-      - name: NPM install
-        run: npm install
-
-      - name: Run tests
-        run: npm run test

src/actions/mover.ts

@@ -244,11 +244,9 @@ export class Mover {
     this.patchDragger(info.dragger as dragging.Dragger, dragStrategy.moveType);
 
     // Save the position so we can put the cursor in a reasonable spot.
-    // @ts-expect-error Access to private property connectionCandidate.
     const target = dragStrategy.connectionCandidate?.neighbour;
 
     // Prevent the strategy connecting the block so we just delete one block.
-    // @ts-expect-error Access to private property connectionCandidate.
     dragStrategy.connectionCandidate = null;
 
     info.dragger.onDragEnd(

src/keyboard_drag_strategy.ts

@@ -50,7 +50,6 @@ export class KeyboardDragStrategy extends dragging.BlockDragStrategy {
     // to the top left of the workspace.
     // @ts-expect-error block and startLoc are private.
     this.block.moveDuringDrag(this.startLoc);
-    // @ts-expect-error connectionCandidate is private.
     this.connectionCandidate = this.createInitialCandidate();
     this.forceShowPreview();
     this.block.addIcon(new MoveIcon(this.block));
@@ -62,9 +61,7 @@ export class KeyboardDragStrategy extends dragging.BlockDragStrategy {
     super.drag(newLoc);
 
     // Handle the case when an unconstrained drag found a connection candidate.
-    // @ts-expect-error connectionCandidate is private.
     if (this.connectionCandidate) {
-      // @ts-expect-error connectionCandidate is private.
       const neighbour = (this.connectionCandidate as ConnectionCandidate)
         .neighbour;
       // The next constrained move will resume the search from the current
@@ -253,7 +250,6 @@ export class KeyboardDragStrategy extends dragging.BlockDragStrategy {
   private forceShowPreview() {
     // @ts-expect-error connectionPreviewer is private
     const previewer = this.connectionPreviewer;
-    // @ts-expect-error connectionCandidate is private
     const candidate = this.connectionCandidate as ConnectionCandidate;
     if (!candidate || !previewer) return;
     const block = this.block;

test/index.html

@@ -134,6 +134,34 @@
               </select>
             </div>
           </form>
+          <div>
+            <br />
+            Instructions for screen reader support:
+            <ul>
+              <li>
+                Enable a screen reader while on the page, and tab navigate/use
+                arrow keys as normal.
+              </li>
+              <li>
+                It's recommended to enable text output (sometimes a developer
+                feature) so that you can see what the screen reader will read
+                out (which allows it to be muted, or even just helps to follow
+                along).
+              </li>
+              <li>
+                It's recommended to use a keyboard shortcut for quickly
+                enabling/disabling the screen reader to avoid needing to
+                navigate back through menus to disable it.
+              </li>
+            </ul>
+            For the primary discussion around screen reader support, please read
+            and comment on: discussion
+            <a
+              href="https://github.com/google/blockly-keyboard-experimentation/discussions/673"
+              target="_blank"
+              >#673</a
+            >.
+          </div>
         </div>
       </div>
       <div id="blocklyDiv"></div>