feat: finish core impl + tests

This adds new tests for the FocusableTreeTraverser and fixes a number of
issues with the original implementation (one of which required two new
API methods to be added to IFocusableTree). More tests have also been
added for FocusManager, and defocusing tracked nodes/trees has been
fully implemented in FocusManager.

tests/mocha/focusable_tree_traverser_test.js

@@ -0,0 +1,480 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import {FocusableTreeTraverser} from '../../build/src/core/utils/focusable_tree_traverser.js';
+import {assert} from '../../node_modules/chai/chai.js';
+import {
+  sharedTestSetup,
+  sharedTestTeardown,
+} from './test_helpers/setup_teardown.js';
+
+suite('FocusableTreeTraverser', function () {
+  setup(function () {
+    sharedTestSetup.call(this);
+
+    const FocusableNodeImpl = function (element, tree) {
+      this.getFocusableElement = function () {
+        return element;
+      };
+
+      this.getFocusableTree = function () {
+        return tree;
+      };
+    };
+    const FocusableTreeImpl = function (rootElement, nestedTrees) {
+      this.idToNodeMap = {};
+
+      this.addNode = function (element) {
+        const node = new FocusableNodeImpl(element, this);
+        this.idToNodeMap[element.id] = node;
+        return node;
+      };
+
+      this.getFocusedNode = function () {
+        throw Error('Unused in test suite.');
+      };
+
+      this.getRootFocusableNode = function () {
+        return this.rootNode;
+      };
+
+      this.getNestedTrees = function () {
+        return nestedTrees;
+      };
+
+      this.lookUpFocusableNode = function (id) {
+        return this.idToNodeMap[id];
+      };
+
+      this.findFocusableNodeFor = function (element) {
+        return FocusableTreeTraverser.findFocusableNodeFor(element, this);
+      };
+
+      this.rootNode = this.addNode(rootElement);
+    };
+
+    const createFocusableTree = function (rootElementId, nestedTrees) {
+      return new FocusableTreeImpl(
+        document.getElementById(rootElementId),
+        nestedTrees || [],
+      );
+    };
+    const createFocusableNode = function (tree, elementId) {
+      return tree.addNode(document.getElementById(elementId));
+    };
+
+    this.testFocusableTree1 = createFocusableTree('testFocusableTree1');
+    this.testFocusableTree1Node1 = createFocusableNode(
+      this.testFocusableTree1,
+      'testFocusableTree1.node1',
+    );
+    this.testFocusableTree1Node1Child1 = createFocusableNode(
+      this.testFocusableTree1,
+      'testFocusableTree1.node1.child1',
+    );
+    this.testFocusableTree1Node2 = createFocusableNode(
+      this.testFocusableTree1,
+      'testFocusableTree1.node2',
+    );
+    this.testFocusableNestedTree4 = createFocusableTree(
+      'testFocusableNestedTree4',
+    );
+    this.testFocusableNestedTree4Node1 = createFocusableNode(
+      this.testFocusableNestedTree4,
+      'testFocusableNestedTree4.node1',
+    );
+    this.testFocusableNestedTree5 = createFocusableTree(
+      'testFocusableNestedTree5',
+    );
+    this.testFocusableNestedTree5Node1 = createFocusableNode(
+      this.testFocusableNestedTree5,
+      'testFocusableNestedTree5.node1',
+    );
+    this.testFocusableTree2 = createFocusableTree('testFocusableTree2', [
+      this.testFocusableNestedTree4,
+      this.testFocusableNestedTree5,
+    ]);
+    this.testFocusableTree2Node1 = createFocusableNode(
+      this.testFocusableTree2,
+      'testFocusableTree2.node1',
+    );
+  });
+
+  teardown(function () {
+    sharedTestTeardown.call(this);
+
+    const removeFocusIndicators = function (element) {
+      element.classList.remove('blocklyActiveFocus', 'blocklyPassiveFocus');
+    };
+
+    // Ensure all node CSS styles are reset so that state isn't leaked between tests.
+    removeFocusIndicators(document.getElementById('testFocusableTree1'));
+    removeFocusIndicators(document.getElementById('testFocusableTree1.node1'));
+    removeFocusIndicators(
+      document.getElementById('testFocusableTree1.node1.child1'),
+    );
+    removeFocusIndicators(document.getElementById('testFocusableTree1.node2'));
+    removeFocusIndicators(document.getElementById('testFocusableTree2'));
+    removeFocusIndicators(document.getElementById('testFocusableTree2.node1'));
+    removeFocusIndicators(document.getElementById('testFocusableNestedTree4'));
+    removeFocusIndicators(
+      document.getElementById('testFocusableNestedTree4.node1'),
+    );
+    removeFocusIndicators(document.getElementById('testFocusableNestedTree5'));
+    removeFocusIndicators(
+      document.getElementById('testFocusableNestedTree5.node1'),
+    );
+  });
+
+  suite('findFocusedNode()', function () {
+    test('for tree with no highlights returns null', function () {
+      const tree = this.testFocusableTree1;
+
+      const finding = FocusableTreeTraverser.findFocusedNode(tree);
+
+      assert.isNull(finding);
+    });
+
+    test('for tree with root active highlight returns root node', function () {
+      const tree = this.testFocusableTree1;
+      const rootNode = tree.getRootFocusableNode();
+      rootNode.getFocusableElement().classList.add('blocklyActiveFocus');
+
+      const finding = FocusableTreeTraverser.findFocusedNode(tree);
+
+      assert.equal(finding, rootNode);
+    });
+
+    test('for tree with root passive highlight returns root node', function () {
+      const tree = this.testFocusableTree1;
+      const rootNode = tree.getRootFocusableNode();
+      rootNode.getFocusableElement().classList.add('blocklyPassiveFocus');
+
+      const finding = FocusableTreeTraverser.findFocusedNode(tree);
+
+      assert.equal(finding, rootNode);
+    });
+
+    test('for tree with node active highlight returns node', function () {
+      const tree = this.testFocusableTree1;
+      const node = this.testFocusableTree1Node1;
+      node.getFocusableElement().classList.add('blocklyActiveFocus');
+
+      const finding = FocusableTreeTraverser.findFocusedNode(tree);
+
+      assert.equal(finding, node);
+    });
+
+    test('for tree with node passive highlight returns node', function () {
+      const tree = this.testFocusableTree1;
+      const node = this.testFocusableTree1Node1;
+      node.getFocusableElement().classList.add('blocklyPassiveFocus');
+
+      const finding = FocusableTreeTraverser.findFocusedNode(tree);
+
+      assert.equal(finding, node);
+    });
+
+    test('for tree with nested node active highlight returns node', function () {
+      const tree = this.testFocusableTree1;
+      const node = this.testFocusableTree1Node1Child1;
+      node.getFocusableElement().classList.add('blocklyActiveFocus');
+
+      const finding = FocusableTreeTraverser.findFocusedNode(tree);
+
+      assert.equal(finding, node);
+    });
+
+    test('for tree with nested node passive highlight returns node', function () {
+      const tree = this.testFocusableTree1;
+      const node = this.testFocusableTree1Node1Child1;
+      node.getFocusableElement().classList.add('blocklyPassiveFocus');
+
+      const finding = FocusableTreeTraverser.findFocusedNode(tree);
+
+      assert.equal(finding, node);
+    });
+
+    test('for tree with nested tree root active no parent highlights returns null', function () {
+      const tree = this.testFocusableNestedTree4;
+      const rootNode = this.testFocusableNestedTree4.getRootFocusableNode();
+      rootNode.getFocusableElement().classList.add('blocklyActiveFocus');
+
+      const finding = FocusableTreeTraverser.findFocusedNode(tree);
+
+      assert.equal(finding, rootNode);
+    });
+
+    test('for tree with nested tree root passive no parent highlights returns null', function () {
+      const tree = this.testFocusableNestedTree4;
+      const rootNode = this.testFocusableNestedTree4.getRootFocusableNode();
+      rootNode.getFocusableElement().classList.add('blocklyPassiveFocus');
+
+      const finding = FocusableTreeTraverser.findFocusedNode(tree);
+
+      assert.equal(finding, rootNode);
+    });
+
+    test('for tree with nested tree root active no parent highlights returns null', function () {
+      const tree = this.testFocusableNestedTree4;
+      const node = this.testFocusableNestedTree4Node1;
+      node.getFocusableElement().classList.add('blocklyActiveFocus');
+
+      const finding = FocusableTreeTraverser.findFocusedNode(tree);
+
+      assert.equal(finding, node);
+    });
+
+    test('for tree with nested tree root passive no parent highlights returns null', function () {
+      const tree = this.testFocusableNestedTree4;
+      const node = this.testFocusableNestedTree4Node1;
+      node.getFocusableElement().classList.add('blocklyPassiveFocus');
+
+      const finding = FocusableTreeTraverser.findFocusedNode(tree);
+
+      assert.equal(finding, node);
+    });
+
+    test('for tree with nested tree root active parent node passive returns parent node', function () {
+      const tree = this.testFocusableNestedTree4;
+      const rootNode = this.testFocusableNestedTree4.getRootFocusableNode();
+      this.testFocusableTree2Node1
+        .getFocusableElement()
+        .classList.add('blocklyPassiveFocus');
+      rootNode.getFocusableElement().classList.add('blocklyActiveFocus');
+
+      const finding = FocusableTreeTraverser.findFocusedNode(
+        this.testFocusableTree2,
+      );
+
+      assert.equal(finding, this.testFocusableTree2Node1);
+    });
+
+    test('for tree with nested tree root passive parent node passive returns parent node', function () {
+      const tree = this.testFocusableNestedTree4;
+      const rootNode = this.testFocusableNestedTree4.getRootFocusableNode();
+      this.testFocusableTree2Node1
+        .getFocusableElement()
+        .classList.add('blocklyPassiveFocus');
+      rootNode.getFocusableElement().classList.add('blocklyPassiveFocus');
+
+      const finding = FocusableTreeTraverser.findFocusedNode(
+        this.testFocusableTree2,
+      );
+
+      assert.equal(finding, this.testFocusableTree2Node1);
+    });
+
+    test('for tree with nested tree node active parent node passive returns parent node', function () {
+      const tree = this.testFocusableNestedTree4;
+      const node = this.testFocusableNestedTree4Node1;
+      this.testFocusableTree2Node1
+        .getFocusableElement()
+        .classList.add('blocklyPassiveFocus');
+      node.getFocusableElement().classList.add('blocklyActiveFocus');
+
+      const finding = FocusableTreeTraverser.findFocusedNode(
+        this.testFocusableTree2,
+      );
+
+      assert.equal(finding, this.testFocusableTree2Node1);
+    });
+
+    test('for tree with nested tree node passive parent node passive returns parent node', function () {
+      const tree = this.testFocusableNestedTree4;
+      const node = this.testFocusableNestedTree4Node1;
+      this.testFocusableTree2Node1
+        .getFocusableElement()
+        .classList.add('blocklyPassiveFocus');
+      node.getFocusableElement().classList.add('blocklyPassiveFocus');
+
+      const finding = FocusableTreeTraverser.findFocusedNode(
+        this.testFocusableTree2,
+      );
+
+      assert.equal(finding, this.testFocusableTree2Node1);
+    });
+  });
+
+  suite('findFocusableNodeFor()', function () {
+    test('for root element returns root', function () {
+      const tree = this.testFocusableTree1;
+      const rootNode = tree.getRootFocusableNode();
+      const rootElem = rootNode.getFocusableElement();
+
+      const finding = FocusableTreeTraverser.findFocusableNodeFor(
+        rootElem,
+        tree,
+      );
+
+      assert.equal(finding, rootNode);
+    });
+
+    test('for element for different tree root returns null', function () {
+      const tree = this.testFocusableTree1;
+      const rootNode = this.testFocusableTree2.getRootFocusableNode();
+      const rootElem = rootNode.getFocusableElement();
+
+      const finding = FocusableTreeTraverser.findFocusableNodeFor(
+        rootElem,
+        tree,
+      );
+
+      assert.isNull(finding);
+    });
+
+    test('for element for different tree node returns null', function () {
+      const tree = this.testFocusableTree1;
+      const nodeElem = this.testFocusableTree2Node1.getFocusableElement();
+
+      const finding = FocusableTreeTraverser.findFocusableNodeFor(
+        nodeElem,
+        tree,
+      );
+
+      assert.isNull(finding);
+    });
+
+    test('for node element in tree returns node', function () {
+      const tree = this.testFocusableTree1;
+      const nodeElem = this.testFocusableTree1Node1.getFocusableElement();
+
+      const finding = FocusableTreeTraverser.findFocusableNodeFor(
+        nodeElem,
+        tree,
+      );
+
+      assert.equal(finding, this.testFocusableTree1Node1);
+    });
+
+    test('for non-node element in tree returns root', function () {
+      const tree = this.testFocusableTree1;
+      const unregElem = document.getElementById(
+        'testFocusableTree1.node2.unregisteredChild1',
+      );
+
+      const finding = FocusableTreeTraverser.findFocusableNodeFor(
+        unregElem,
+        tree,
+      );
+
+      // An unregistered element should map to the closest node.
+      assert.equal(finding, this.testFocusableTree1Node2);
+    });
+
+    test('for nested node element in tree returns node', function () {
+      const tree = this.testFocusableTree1;
+      const nodeElem = this.testFocusableTree1Node1Child1.getFocusableElement();
+
+      const finding = FocusableTreeTraverser.findFocusableNodeFor(
+        nodeElem,
+        tree,
+      );
+
+      // The nested node should be returned.
+      assert.equal(finding, this.testFocusableTree1Node1Child1);
+    });
+
+    test('for nested node element in tree returns node', function () {
+      const tree = this.testFocusableTree1;
+      const unregElem = document.getElementById(
+        'testFocusableTree1.node1.child1.unregisteredChild1',
+      );
+
+      const finding = FocusableTreeTraverser.findFocusableNodeFor(
+        unregElem,
+        tree,
+      );
+
+      // An unregistered element should map to the closest node.
+      assert.equal(finding, this.testFocusableTree1Node1Child1);
+    });
+
+    test('for nested node element in tree returns node', function () {
+      const tree = this.testFocusableTree1;
+      const unregElem = document.getElementById(
+        'testFocusableTree1.unregisteredChild1',
+      );
+
+      const finding = FocusableTreeTraverser.findFocusableNodeFor(
+        unregElem,
+        tree,
+      );
+
+      // An unregistered element should map to the closest node (or root).
+      assert.equal(finding, tree.getRootFocusableNode());
+    });
+
+    test('for nested tree root returns nested tree root', function () {
+      const tree = this.testFocusableNestedTree4;
+      const rootNode = tree.getRootFocusableNode();
+      const rootElem = rootNode.getFocusableElement();
+
+      const finding = FocusableTreeTraverser.findFocusableNodeFor(
+        rootElem,
+        tree,
+      );
+
+      assert.equal(finding, rootNode);
+    });
+
+    test('for nested tree node returns nested tree node', function () {
+      const tree = this.testFocusableNestedTree4;
+      const nodeElem = this.testFocusableNestedTree4Node1.getFocusableElement();
+
+      const finding = FocusableTreeTraverser.findFocusableNodeFor(
+        nodeElem,
+        tree,
+      );
+
+      // The node of the nested tree should be returned.
+      assert.equal(finding, this.testFocusableNestedTree4Node1);
+    });
+
+    test('for nested element in nested tree node returns nearest nested node', function () {
+      const tree = this.testFocusableNestedTree4;
+      const unregElem = document.getElementById(
+        'testFocusableNestedTree4.node1.unregisteredChild1',
+      );
+
+      const finding = FocusableTreeTraverser.findFocusableNodeFor(
+        unregElem,
+        tree,
+      );
+
+      // An unregistered element should map to the closest node.
+      assert.equal(finding, this.testFocusableNestedTree4Node1);
+    });
+
+    test('for nested tree node under root with different tree base returns null', function () {
+      const tree = this.testFocusableTree2;
+      const nodeElem = this.testFocusableNestedTree5Node1.getFocusableElement();
+
+      const finding = FocusableTreeTraverser.findFocusableNodeFor(
+        nodeElem,
+        tree,
+      );
+
+      // The nested node hierarchically sits below the outer tree, but using
+      // that tree as the basis should yield null since it's not a direct child.
+      assert.isNull(finding);
+    });
+
+    test('for nested tree node under node with different tree base returns null', function () {
+      const tree = this.testFocusableTree2;
+      const nodeElem = this.testFocusableNestedTree4Node1.getFocusableElement();
+
+      const finding = FocusableTreeTraverser.findFocusableNodeFor(
+        nodeElem,
+        tree,
+      );
+
+      // The nested node hierarchically sits below the outer tree, but using
+      // that tree as the basis should yield null since it's not a direct child.
+      assert.isNull(finding);
+    });
+  });
+});

tests/mocha/index.html

@@ -35,26 +35,57 @@
       fill: #00f;
     }
   </style>
-  <body>
+  <body tabindex="-1">
     <div id="mocha"></div>
     <div id="failureCount" style="display: none" tests_failed="unset"></div>
     <div id="failureMessages" style="display: none"></div>
     <div id="testFocusableTree1" tabindex="-1">
-      <div id="testFocusableTree1.node1" tabindex="-1">
+      Focusable tree 1
+      <div id="testFocusableTree1.node1" style="margin-left: 1em"; tabindex="-1">
         Tree 1 node 1
-        <div id="testFocusableTree1.node1.child1" tabindex="-1">Tree 1 node 1 child 1</div>
+        <div id="testFocusableTree1.node1.child1" style="margin-left: 2em"; tabindex="-1">
+          Tree 1 node 1 child 1
+          <div id="testFocusableTree1.node1.child1.unregisteredChild1" style="margin-left: 3em"; tabindex="-1">
+            Tree 1 node 1 child 1 child 1 (unregistered)
+          </div>
+        </div>
       </div>
-      <div id="testFocusableTree1.node2" tabindex="-1">
+      <div id="testFocusableTree1.node2" style="margin-left: 1em"; tabindex="-1">
         Tree 1 node 2
-        <div id="testFocusableTree1.node2.unregisteredChild1" tabindex="-1">Tree 1 node 2 child 2 (unregistered)</div>
+        <div id="testFocusableTree1.node2.unregisteredChild1" style="margin-left: 2em"; tabindex="-1">
+          Tree 1 node 2 child 2 (unregistered)
+        </div>
+      </div>
+      <div id="testFocusableTree1.unregisteredChild1" style="margin-left: 1em"; tabindex="-1">
+        Tree 1 child 1 (unregistered)
       </div>
     </div>
     <div id="testFocusableTree2" tabindex="-1">
-      <div id="testFocusableTree2.node1" tabindex="-1">Tree 2 node 1</div>
+      Focusable tree 2
+      <div id="testFocusableTree2.node1" style="margin-left: 1em"; tabindex="-1">
+        Tree 2 node 1
+        <div id="testFocusableNestedTree4" style="margin-left: 2em"; tabindex="-1">
+          Nested tree 4
+          <div id="testFocusableNestedTree4.node1" style="margin-left: 3em"; tabindex="-1">
+            Tree 4 node 1 (nested)
+            <div id="testFocusableNestedTree4.node1.unregisteredChild1" style="margin-left: 4em"; tabindex="-1">
+              Tree 4 node 1 child 1 (unregistered)
+            </div>
+          </div>
+        </div>
+      </div>
+      <div id="testFocusableNestedTree5" style="margin-left: 1em"; tabindex="-1">
+        Nested tree 5
+        <div id="testFocusableNestedTree5.node1" style="margin-left: 2em"; tabindex="-1">Tree 5 node 1 (nested)</div>
+      </div>
     </div>
     <div id="testUnregisteredFocusableTree3" tabindex="-1">
-      <div id="testUnregisteredFocusableTree3.node1" tabindex="-1">Tree 3 node 1 (unregistered)</div>
+      Unregistered tree 3
+      <div id="testUnregisteredFocusableTree3.node1" style="margin-left: 1em"; tabindex="-1">
+        Tree 3 node 1 (unregistered)
+      </div>
     </div>
+    <div id="testUnfocusableElement">Unfocusable element</div>
     <div id="nonTreeElementForEphemeralFocus" tabindex="-1" />
     <svg width="250" height="250">
       <g id="testFocusableGroup1" tabindex="-1">
@@ -71,7 +102,9 @@
           <text x="10" y="80" class="svgText">Group 1 node 2</text>
           <g id="testFocusableGroup1.node2.unregisteredChild1" tabindex="-1">
             <rect x="0" y="90" width="250" height="30" fill="lightgrey" />
-            <text x="10" y="110" class="svgText">Tree 1 node 2 child 2 (unregistered)</text>
+            <text x="10" y="110" class="svgText">
+              Tree 1 node 2 child 2 (unregistered)
+            </text>
           </g>
         </g>
       </g>
@@ -80,11 +113,19 @@
           <rect x="0" y="120" width="250" height="30" fill="grey" />
           <text x="10" y="140" class="svgText">Group 2 node 1</text>
         </g>
+        <g id="testFocusableNestedGroup4" tabindex="-1">
+          <g id="testFocusableNestedGroup4.node1" tabindex="-1">
+            <rect x="0" y="150" width="250" height="30" fill="lightgrey" />
+            <text x="10" y="170" class="svgText">Group 4 node 1 (nested)</text>
+          </g>
+        </g>
       </g>
       <g id="testUnregisteredFocusableGroup3" tabindex="-1">
         <g id="testUnregisteredFocusableGroup3.node1" tabindex="-1">
-          <rect x="0" y="150" width="250" height="30" fill="grey" />
-          <text x="10" y="170" class="svgText">Tree 3 node 1 (unregistered)</text>
+          <rect x="0" y="180" width="250" height="30" fill="grey" />
+          <text x="10" y="200" class="svgText">
+            Tree 3 node 1 (unregistered)
+          </text>
         </g>
       </g>
       <g id="nonTreeGroupForEphemeralFocus" tabindex="-1"></g>
@@ -162,6 +203,7 @@
       import './field_variable_test.js';
       import './flyout_test.js';
       import './focus_manager_test.js';
+      import './focusable_tree_traverser_test.js';
       // import './test_event_reduction.js';
       import './generator_test.js';
       import './gesture_test.js';