Code review feedback

Return the event directly, to speed up the code a bit.  Add JSDoc to help communicate its intent.  Update various comments.

src/core/core.controller.js

@@ -794,9 +794,8 @@ class Chart {
   }
 
   /**
-   * Checks whether the given point is in the chart area.  Point coordinates are
-   * relative to the chart.  (getRelativePosition may be helpful.)
-   * @param {Point} point
+   * Checks whether the given point is in the chart area.
+   * @param {Point} point - in relative coordinates (see, e.g., getRelativePosition)
    * @returns {boolean}
    */
   isPointInArea(point) {

src/core/core.interaction.js

@@ -84,7 +84,7 @@ function getDistanceMetricForAxis(axis) {
 /**
  * Helper function to get the items that intersect the event position
  * @param {Chart} chart - the chart
- * @param {Point} position - the point to be nearest to
+ * @param {Point} position - the point to be nearest to, in relative coordinates
  * @param {string} axis - the axis mode. x|y|xy|r
  * @param {boolean} [useFinalPosition] - use the element's animation target instead of current position
  * @return {InteractionItem[]} the nearest items
@@ -109,7 +109,7 @@ export function getIntersectItems(chart, position, axis, useFinalPosition) {
 /**
  * Helper function to get the items nearest to the event position for a radial chart
  * @param {Chart} chart - the chart to look at elements from
- * @param {Point} position - the point to be nearest to
+ * @param {Point} position - the point to be nearest to, in relative coordinates
  * @param {string} axis - the axes along which to measure distance
  * @param {boolean} [useFinalPosition] - use the element's animation target instead of current position
  * @return {InteractionItem[]} the nearest items
@@ -133,7 +133,7 @@ function getNearestRadialItems(chart, position, axis, useFinalPosition) {
 /**
  * Helper function to get the items nearest to the event position for a cartesian chart
  * @param {Chart} chart - the chart to look at elements from
- * @param {Point} position - the point to be nearest to
+ * @param {Point} position - the point to be nearest to, in relative coordinates
  * @param {string} axis - the axes along which to measure distance
  * @param {boolean} [intersect] - if true, only consider items that intersect the position
  * @param {boolean} [useFinalPosition] - use the element's animation target instead of current position
@@ -173,7 +173,7 @@ function getNearestCartesianItems(chart, position, axis, intersect, useFinalPosi
 /**
  * Helper function to get the items nearest to the event position considering all visible items in the chart
  * @param {Chart} chart - the chart to look at elements from
- * @param {Point} position - the point to be nearest to
+ * @param {Point} position - the point to be nearest to, in relative coordinates
  * @param {string} axis - the axes along which to measure distance
  * @param {boolean} [intersect] - if true, only consider items that intersect the position
  * @param {boolean} [useFinalPosition] - use the element's animation target instead of current position
@@ -192,7 +192,7 @@ export function getNearestItems(chart, position, axis, intersect, useFinalPositi
 /**
  * Helper function to get the items matching along the given X or Y axis
  * @param {Chart} chart - the chart to look at elements from
- * @param {Point} position - the point to be nearest to
+ * @param {Point} position - the point to be nearest to, in relative coordinates
  * @param {string} axis - the axis to match
  * @param {boolean} [intersect] - if true, only consider items that intersect the position
  * @param {boolean} [useFinalPosition] - use the element's animation target instead of current position

src/helpers/helpers.canvas.js

@@ -2,7 +2,10 @@ import {isArray, isNullOrUndef} from './helpers.core';
 import {PI, TAU, HALF_PI, QUARTER_PI, TWO_THIRDS_PI, RAD_PER_DEG} from './helpers.math';
 
 /**
- * @typedef { import("../core/core.controller").default } Chart
+ * Note: typedefs are auto-exported, so use a made-up `canvas` namespace where
+ * necessary to avoid duplicates with `export * from './helpers`; see
+ * https://github.com/microsoft/TypeScript/issues/46011
+ * @typedef { import("../core/core.controller").default } canvas.Chart
  * @typedef { import("../../types/index.esm").Point } Point
  */
 
@@ -95,7 +98,7 @@ export function _longestText(ctx, font, arrayOfThings, cache) {
 
 /**
  * Returns the aligned pixel value to avoid anti-aliasing blur
- * @param {Chart} chart - The chart instance.
+ * @param {canvas.Chart} chart - The chart instance.
  * @param {number} pixel - A pixel value.
  * @param {number} width - The width of the element.
  * @returns {number} The aligned pixel value.

src/helpers/helpers.dom.js

@@ -1,5 +1,13 @@
 import {INFINITY} from './helpers.math';
 
+/**
+ * Note: typedefs are auto-exported, so use a made-up `dom` namespace where
+ * necessary to avoid duplicates with `export * from './helpers`; see
+ * https://github.com/microsoft/TypeScript/issues/46011
+ * @typedef { import("../core/core.controller").default } dom.Chart
+ * @typedef { import('../../types/index.esm').ChartEvent } ChartEvent
+ */
+
 /**
  * @private
  */
@@ -83,12 +91,15 @@ function getCanvasPosition(e, canvas) {
   return {x, y, box};
 }
 
+/**
+ * Gets an event's x, y coordinates, relative to the chart area
+ * @param {Event|ChartEvent} evt
+ * @param {dom.Chart} chart
+ * @returns {{x: number, y: number}}
+ */
 export function getRelativePosition(evt, chart) {
   if ('native' in evt) {
-    return {
-      x: evt.x,
-      y: evt.y
-    };
+    return evt;
   }
 
   const {canvas, currentDevicePixelRatio} = chart;

test/specs/helpers.dom.tests.js

@@ -450,7 +450,7 @@ describe('DOM helpers tests', function() {
       const nativePosition = Chart.helpers.getRelativePosition(nativeEvent, chart);
 
       expect(chartPosition).not.toBeNull();
-      expect(nativePosition).toEqual(chartPosition);
+      expect(nativePosition).toEqual({x: chartPosition.x, y: chartPosition.y});
     });
   });
 });