Delegate getShapesAtPoint to Group and add tests

Moved the getShapesAtPoint logic from Two to Group, allowing scene groups to perform hit testing directly. Updated Two#getShapesAtPoint to delegate to the root scene group. Added and expanded tests to verify correct delegation and option handling. Updated type definitions to include Group#getShapesAtPoint.

Author: jonobr1

src/group.js

@@ -1,6 +1,7 @@
 import { Events } from './events.js';
 import { _ } from './utils/underscore.js';
 import { getEffectFromObject } from './utils/shape.js';
+import { boundsContains } from './utils/hit-test.js';
 
 import { Shape } from './shape.js';
 import { Children } from './children.js';
@@ -487,6 +488,131 @@ export class Group extends Shape {
     return this;
   }
 
+  getShapesAtPoint(x, y, options) {
+    const opts = options || {};
+    const mode =
+      opts.mode === 'deepest' || opts.deepest ? 'deepest' : 'all';
+    const visibleOnly = opts.visibleOnly !== false;
+    const includeGroups = !!opts.includeGroups;
+    const filter = typeof opts.filter === 'function' ? opts.filter : null;
+    const tolerance =
+      typeof opts.tolerance === 'number' ? opts.tolerance : 0;
+
+    const hitOptions = {};
+
+    if (typeof opts.precision === 'number') {
+      hitOptions.precision = opts.precision;
+    }
+    if (typeof opts.fill !== 'undefined') {
+      hitOptions.fill = opts.fill;
+    }
+    if (typeof opts.stroke !== 'undefined') {
+      hitOptions.stroke = opts.stroke;
+    }
+    hitOptions.tolerance = tolerance;
+    hitOptions.ignoreVisibility = !visibleOnly;
+
+    const stopOnFirst = mode === 'deepest';
+    const results = [];
+
+    const isVisible = (element) => {
+      if (!visibleOnly) {
+        return true;
+      }
+
+      let current = element;
+      while (current) {
+        if (typeof current.visible === 'boolean' && !current.visible) {
+          return false;
+        }
+        if (
+          typeof current.opacity === 'number' &&
+          current.opacity <= 0
+        ) {
+          return false;
+        }
+        current = current.parent;
+      }
+
+      return true;
+    };
+
+    const visit = (group) => {
+      const children = group && group.children;
+      if (!children) {
+        return false;
+      }
+
+      for (let i = children.length - 1; i >= 0; i--) {
+        const child = children[i];
+
+        if (!child) {
+          continue;
+        }
+
+        if (!isVisible(child)) {
+          continue;
+        }
+
+        const rect =
+          typeof child.getBoundingClientRect === 'function'
+            ? child.getBoundingClientRect()
+            : null;
+
+        if (rect && !boundsContains(rect, x, y, tolerance)) {
+          continue;
+        }
+
+        if (child instanceof Group) {
+          if (
+            includeGroups &&
+            (!filter || filter(child)) &&
+            typeof child.contains === 'function' &&
+            child.contains(x, y, hitOptions)
+          ) {
+            results.push(child);
+            if (stopOnFirst) {
+              return true;
+            }
+          }
+          if (visit(child)) {
+            return true;
+          }
+          continue;
+        }
+
+        if (!(child instanceof Shape)) {
+          continue;
+        }
+
+        if (filter && !filter(child)) {
+          continue;
+        }
+
+        if (typeof child.contains !== 'function') {
+          continue;
+        }
+
+        if (child.contains(x, y, hitOptions)) {
+          results.push(child);
+          if (stopOnFirst) {
+            return true;
+          }
+        }
+      }
+
+      return false;
+    };
+
+    visit(this);
+
+    if (stopOnFirst) {
+      return results.length > 0 ? [results[0]] : [];
+    }
+
+    return results;
+  }
+
   /**
    * @name Two.Group#corner
    * @function

src/two.js

@@ -10,7 +10,6 @@ import * as math from './utils/math.js';
 import { Commands } from './utils/path-commands.js';
 import { _ } from './utils/underscore.js';
 import { xhr } from './utils/xhr.js';
-import { boundsContains } from './utils/hit-test.js';
 
 // Core Classes
 
@@ -549,131 +548,16 @@ export default class Two {
    * @param {Function} [options.filter] - Predicate to filter shapes from the result set.
    * @returns {Two.Shape[]} Ordered list of shapes under the specified point, front to back.
    * @description Returns shapes underneath the provided coordinates. Coordinates are expected in world space (matching the renderer output).
+   * @nota-bene Delegates to {@link Two.Group#getShapesAtPoint} on the root scene.
    */
   getShapesAtPoint(x, y, options) {
-    const opts = options || {};
-    const mode =
-      opts.mode === 'deepest' || opts.deepest ? 'deepest' : 'all';
-    const visibleOnly = opts.visibleOnly !== false;
-    const includeGroups = !!opts.includeGroups;
-    const filter =
-      typeof opts.filter === 'function' ? opts.filter : null;
-    const tolerance =
-      typeof opts.tolerance === 'number' ? opts.tolerance : 0;
-    const hitOptions = {};
-
-    if (typeof opts.precision === 'number') {
-      hitOptions.precision = opts.precision;
-    }
-    if (typeof opts.fill !== 'undefined') {
-      hitOptions.fill = opts.fill;
-    }
-    if (typeof opts.stroke !== 'undefined') {
-      hitOptions.stroke = opts.stroke;
-    }
-    hitOptions.tolerance = tolerance;
-    hitOptions.ignoreVisibility = !visibleOnly;
-
-    const stopOnFirst = mode === 'deepest';
-    const results = [];
-
-    const isVisible = (element) => {
-      if (!visibleOnly) {
-        return true;
-      }
-
-      let current = element;
-      while (current) {
-        if (typeof current.visible === 'boolean' && !current.visible) {
-          return false;
-        }
-        if (
-          typeof current.opacity === 'number' &&
-          current.opacity <= 0
-        ) {
-          return false;
-        }
-        current = current.parent;
-      }
-
-      return true;
-    };
-
-    const visit = (group) => {
-      if (!group || !group.children) {
-        return false;
-      }
-
-      const children = group.children;
-      for (let i = children.length - 1; i >= 0; i--) {
-        const child = children[i];
-
-        if (!child) {
-          continue;
-        }
-
-        if (!isVisible(child)) {
-          continue;
-        }
-
-        const rect =
-          typeof child.getBoundingClientRect === 'function'
-            ? child.getBoundingClientRect()
-            : null;
-
-        if (rect && !boundsContains(rect, x, y, tolerance)) {
-          continue;
-        }
-
-        if (child instanceof Group) {
-          if (includeGroups && typeof child.contains === 'function') {
-            if (!filter || filter(child)) {
-              if (child.contains(x, y, hitOptions)) {
-                results.push(child);
-                if (stopOnFirst) {
-                  return true;
-                }
-              }
-            }
-          }
-
-          if (visit(child)) {
-            return true;
-          }
-
-          continue;
-        }
-
-        if (!(child instanceof Shape)) {
-          continue;
-        }
-
-        if (filter && !filter(child)) {
-          continue;
-        }
-
-        if (typeof child.contains !== 'function') {
-          continue;
-        }
-
-        if (child.contains(x, y, hitOptions)) {
-          results.push(child);
-          if (stopOnFirst) {
-            return true;
-          }
-        }
-      }
-
-      return false;
-    };
-
-    visit(this.scene);
-
-    if (stopOnFirst) {
-      return results.length > 0 ? [results[0]] : [];
+    if (
+      this.scene &&
+      typeof this.scene.getShapesAtPoint === 'function'
+    ) {
+      return this.scene.getShapesAtPoint(x, y, options);
     }
-
-    return results;
+    return [];
   }
 
   /**

tests/suite/hit-test.js

@@ -44,7 +44,7 @@ QUnit.test('Shape.contains evaluates fill and stroke geometry', function (assert
 });
 
 QUnit.test('Two#getShapesAtPoint respects options', function (assert) {
-  assert.expect(4);
+  assert.expect(6);
 
   var two = new Two({ width: 400, height: 400, autostart: false });
 
@@ -68,6 +68,12 @@ QUnit.test('Two#getShapesAtPoint respects options', function (assert) {
   var circleHits = two.getShapesAtPoint(100, 100);
   assert.ok(circleHits.indexOf(circle) > -1, 'Circle reported at its center.');
 
+  var sceneHits = two.scene.getShapesAtPoint(100, 100);
+  assert.ok(
+    sceneHits.indexOf(circle) > -1,
+    'Scene group reports circle at its center.'
+  );
+
   var deepest = two.getShapesAtPoint(50, 4, { mode: 'deepest' });
   assert.deepEqual(deepest, [line], 'Deepest mode returns top-most shape only.');
 
@@ -83,4 +89,12 @@ QUnit.test('Two#getShapesAtPoint respects options', function (assert) {
     allHits.indexOf(hidden) > -1,
     'Hidden shapes included when visibleOnly is false.'
   );
+
+  var sceneAll = two.scene.getShapesAtPoint(200, 200, {
+    visibleOnly: false,
+  });
+  assert.ok(
+    sceneAll.indexOf(hidden) > -1,
+    'Scene group honours visibleOnly option.'
+  );
 });

types.d.ts

@@ -1751,6 +1751,20 @@ declare module 'two.js/src/group' {
      * to a new renderer.
      */
     dispose(): Group;
+    /**
+     * @name Two.Group#getShapesAtPoint
+     * @function
+     * @param {Number} x - X coordinate in world space.
+     * @param {Number} y - Y coordinate in world space.
+     * @param {SceneHitTestOptions} [options]
+     * @returns {Shape[]} Ordered list of intersecting shapes, front to back.
+     * @description Traverse the group hierarchy and return shapes that contain the specified point.
+     */
+    getShapesAtPoint(
+      x: number,
+      y: number,
+      options?: SceneHitTestOptions
+    ): Shape[];
     /**
      * @name Two.Group#corner
      * @function
@@ -1871,7 +1885,7 @@ declare module 'two.js/src/group' {
   import { Children } from 'two.js/src/children';
   import { Gradient } from 'two.js/src/effects/gradient';
   import { Texture } from 'two.js/src/effects/texture';
-  import { BoundingBox } from 'two.js';
+  import { BoundingBox, SceneHitTestOptions } from 'two.js';
 }
 declare module 'two.js/src/renderers/canvas' {
   /**