chartjs-chart-sankey 0.6.0 → 0.8.1

package/dist/chartjs-chart-sankey.esm.js

@@ -1,12 +1,17 @@
 /*!
- * chartjs-chart-sankey v0.6.0
+ * chartjs-chart-sankey v0.8.1
  * https://github.com/kurkle/chartjs-chart-sankey#readme
- * (c) 2021 Jukka Kurkela
+ * (c) 2022 Jukka Kurkela
  * Released under the MIT license
  */
 import { DatasetController, Element } from 'chart.js';
-import { valueOrDefault, color } from 'chart.js/helpers';
+import { valueOrDefault, toFont, isNullOrUndef, color } from 'chart.js/helpers';
 
+/**
+ * @param {Map<string, SankeyNode>} nodes
+ * @param {Array<SankeyDataPoint>} data
+ * @return {number}
+ */
 function calculateX(nodes, data) {
   const to = new Set(data.map(x => x.to));
   const from = new Set(data.map(x => x.from));
@@ -33,42 +38,87 @@ function calculateX(nodes, data) {
   return x;
 }
 
+/**
+ * @param {Array<string>} keys
+ * @param {Set<string>} to
+ * @return {Array<string>}
+ */
 function nextColumn(keys, to) {
   const columnsNotInTo = keys.filter(key => !to.has(key));
   return columnsNotInTo.length ? columnsNotInTo : keys.slice(0, 1);
 }
 
+/**
+ * @param x {any}
+ * @return {boolean}
+ */
 const defined = x => x !== undefined;
+
+/**
+ * @param {SankeyNode} a
+ * @param {SankeyNode} b
+ * @return {number}
+ */
 const nodeByXY = (a, b) => a.x !== b.x ? a.x - b.x : a.y - b.y;
+
+/**
+ * @param {Array<FromToElement>} list
+ * @param {string} prop
+ * @return {number}
+ */
 const nodeCount = (list, prop) => list.reduce((acc, cur) => acc + cur.node[prop].length + nodeCount(cur.node[prop], prop), 0);
-const flowByNodeCount = (prop) => (a, b) => nodeCount(a.node[prop], prop) - nodeCount(b.node[prop], prop);
 
-function findLargestNode(nodeArray) {
-  return nodeArray.sort((a, b) => Math.max(b.in, b.out) - Math.max(a.in, a.out))[0];
-}
+/**
+ * @param {string} prop
+ * @return {function(FromToElement, FromToElement): number}
+ */
+const flowByNodeCount = (prop) => (a, b) => (nodeCount(a.node[prop], prop) - nodeCount(b.node[prop], prop)) || (a.node[prop].length - b.node[prop].length);
 
+/**
+ * @param {Array<SankeyNode>} nodeArray
+ * @return {SankeyNode}
+ */
+const findLargestNode = (nodeArray) => nodeArray.sort((a, b) => Math.max(b.in, b.out) - Math.max(a.in, a.out))[0];
+
+/**
+ * @param {SankeyNode} node
+ * @param {number} y
+ * @return {number}
+ */
 function processFrom(node, y) {
   node.from.sort(flowByNodeCount('from')).forEach(flow => {
     const n = flow.node;
     if (!defined(n.y)) {
       n.y = y;
-      y = Math.max(y + n.out, processFrom(n, y));
+      processFrom(n, y);
     }
+    y = Math.max(n.y + n.out, y);
   });
   return y;
 }
 
+/**
+ * @param {SankeyNode} node
+ * @param {number} y
+ * @return {number}
+ */
 function processTo(node, y) {
   node.to.sort(flowByNodeCount('to')).forEach(flow => {
     const n = flow.node;
     if (!defined(n.y)) {
       n.y = y;
-      y = Math.max(y + n.in, processTo(n, y));
+      processTo(n, y);
     }
+    y = Math.max(n.y + n.in, y);
   });
   return y;
 }
 
+/**
+ * @param {SankeyNode} node
+ * @param {number} value
+ * @return {number}
+ */
 function setOrGetY(node, value) {
   if (defined(node.y)) {
     return node.y;
@@ -77,14 +127,21 @@ function setOrGetY(node, value) {
   return value;
 }
 
+/**
+ * @param {Array<SankeyNode>} nodeArray
+ * @param {number} maxX
+ * @return {number}
+ */
 function processRest(nodeArray, maxX) {
   const leftNodes = nodeArray.filter(node => node.x === 0);
   const rightNodes = nodeArray.filter(node => node.x === maxX);
   const leftToDo = leftNodes.filter(node => !defined(node.y));
   const rightToDo = rightNodes.filter(node => !defined(node.y));
+  const centerToDo = nodeArray.filter(node => node.x > 0 && node.x < maxX && !defined(node.y));
 
   let leftY = leftNodes.reduce((acc, cur) => Math.max(acc, (cur.y + cur.out) || 0), 0);
   let rightY = rightNodes.reduce((acc, cur) => Math.max(acc, (cur.y + cur.in) || 0), 0);
+  let centerY = 0;
 
   if (leftY >= rightY) {
     leftToDo.forEach(node => {
@@ -107,10 +164,23 @@ function processRest(nodeArray, maxX) {
       leftY = Math.max(leftY + node.out, processTo(node, leftY));
     });
   }
+  centerToDo.forEach(node => {
+    let y = nodeArray.filter(n => n.x === node.x && defined(n.y))
+      .reduce((acc, cur) => Math.max(acc, cur.y + Math.max(cur.in, cur.out)), 0);
+    y = setOrGetY(node, y);
+    y = Math.max(y + node.in, processFrom(node, y));
+    y = Math.max(y + node.out, processTo(node, y));
+    centerY = Math.max(centerY, y);
+  });
 
-  return Math.max(leftY, rightY);
+  return Math.max(leftY, rightY, centerY);
 }
 
+/**
+ * @param {Array<SankeyNode>} nodeArray
+ * @param {number} maxX
+ * @return {number}
+ */
 function calculateY(nodeArray, maxX) {
   const start = findLargestNode(nodeArray);
   start.y = 0;
@@ -120,11 +190,18 @@ function calculateY(nodeArray, maxX) {
   return Math.max(left, right, rest);
 }
 
+/**
+ * @param {Array<SankeyNode>} nodeArray
+ * @param {number} maxX
+ * @return {number}
+ */
 function calculateYUsingPriority(nodeArray, maxX) {
   let maxY = 0;
+  let nextYStart = 0;
   for (let x = 0; x <= maxX; x++) {
-    let y = 0;
+    let y = nextYStart;
     const nodes = nodeArray.filter(node => node.x === x).sort((a, b) => a.priority - b.priority);
+    nextYStart = nodes[0].to.filter(to => to.node.x > x + 1).reduce((acc, cur) => acc + cur.flow, 0) || 0;
     for (const node of nodes) {
       node.y = y;
       y += Math.max(node.out, node.in);
@@ -134,6 +211,11 @@ function calculateYUsingPriority(nodeArray, maxX) {
   return maxY;
 }
 
+/**
+ * @param {Array<SankeyNode>} nodeArray
+ * @param {number} padding
+ * @return {number}
+ */
 function addPadding(nodeArray, padding) {
   let i = 1;
   let x = 0;
@@ -158,95 +240,150 @@ function addPadding(nodeArray, padding) {
         prev = i;
       }
       node.y += i * padding;
-      maxY = Math.max(maxY, node.y + Math.max(node.in, node.out));
       i++;
     }
+    maxY = Math.max(maxY, node.y + Math.max(node.in, node.out));
   });
   return maxY;
 }
 
-function sortFlows(nodeArray) {
-  nodeArray.forEach(node => {
+/**
+ * @param {Array<SankeyNode>} nodeArray
+ * @param {'min' | 'max'} size
+ */
+function sortFlows(nodeArray, size) {
+  nodeArray.forEach((node) => {
+    const nodeSize = Math[size](node.in || node.out, node.out || node.in);
+    const overlapFrom = nodeSize < node.in;
+    const overlapTo = nodeSize < node.out;
     let addY = 0;
-    node.from.sort((a, b) => (a.node.y + a.node.out / 2) - (b.node.y + b.node.out / 2)).forEach(flow => {
-      flow.addY = addY;
-      addY += flow.flow;
+    let len = node.from.length;
+    node.from.sort((a, b) => (a.node.y + a.node.out / 2) - (b.node.y + b.node.out / 2)).forEach((flow, idx) => {
+      if (overlapFrom) {
+        flow.addY = idx * (nodeSize - flow.flow) / (len - 1);
+      } else {
+        flow.addY = addY;
+        addY += flow.flow;
+      }
     });
     addY = 0;
-    node.to.sort((a, b) => (a.node.y + a.node.in / 2) - (b.node.y + b.node.in / 2)).forEach(flow => {
-      flow.addY = addY;
-      addY += flow.flow;
+    len = node.to.length;
+    node.to.sort((a, b) => (a.node.y + a.node.in / 2) - (b.node.y + b.node.in / 2)).forEach((flow, idx) => {
+      if (overlapTo) {
+        flow.addY = idx * (nodeSize - flow.flow) / (len - 1);
+      } else {
+        flow.addY = addY;
+        addY += flow.flow;
+      }
     });
   });
 }
 
-function layout(nodes, data, priority) {
+/**
+ * @param {Map<string, SankeyNode>} nodes
+ * @param {Array<SankeyDataPoint>} data
+ * @param {boolean} priority
+ * @param {'min' | 'max'} size
+ * @return {{maxY: number, maxX: number}}
+ */
+function layout(nodes, data, priority, size) {
   const nodeArray = [...nodes.values()];
   const maxX = calculateX(nodes, data);
   const maxY = priority ? calculateYUsingPriority(nodeArray, maxX) : calculateY(nodeArray, maxX);
   const padding = maxY * 0.03; // rows;
-
   const maxYWithPadding = addPadding(nodeArray, padding);
-  sortFlows(nodeArray);
-
+  sortFlows(nodeArray, size);
   return {maxX, maxY: maxYWithPadding};
 }
 
-function buildNodesFromFlows(data) {
+/**
+ * @param {Array<SankeyDataPoint>} data Array of raw data elements
+ * @return {Map<string, SankeyNode>}
+ */
+function buildNodesFromRawData(data) {
   const nodes = new Map();
   for (let i = 0; i < data.length; i++) {
-    const d = data[i];
-    if (!nodes.has(d.from)) {
-      nodes.set(d.from, {key: d.from, in: 0, out: d.flow, from: [], to: [{key: d.to, flow: d.flow}]});
+    const {from, to, flow} = data[i];
+
+    if (!nodes.has(from)) {
+      nodes.set(from, {
+        key: from,
+        in: 0,
+        out: flow,
+        from: [],
+        to: [{key: to, flow: flow, index: i}],
+      });
     } else {
-      const node = nodes.get(d.from);
-      node.out += d.flow;
-      node.to.push({key: d.to, flow: d.flow});
+      const node = nodes.get(from);
+      node.out += flow;
+      node.to.push({key: to, flow: flow, index: i});
     }
-    if (!nodes.has(d.to)) {
-      nodes.set(d.to, {key: d.to, in: d.flow, out: 0, from: [{key: d.from, flow: d.flow}], to: []});
+    if (!nodes.has(to)) {
+      nodes.set(to, {
+        key: to,
+        in: flow,
+        out: 0,
+        from: [{key: from, flow: flow, index: i}],
+        to: [],
+      });
     } else {
-      const node = nodes.get(d.to);
-      node.in += d.flow;
-      node.from.push({key: d.from, flow: d.flow});
+      const node = nodes.get(to);
+      node.in += flow;
+      node.from.push({key: from, flow: flow, index: i});
     }
   }
 
   const flowSort = (a, b) => b.flow - a.flow;
 
   [...nodes.values()].forEach(node => {
-    let tmp = 0;
     node.from = node.from.sort(flowSort);
     node.from.forEach(x => {
       x.node = nodes.get(x.key);
-      x.addY = tmp;
-      tmp += x.flow;
     });
 
-    tmp = 0;
     node.to = node.to.sort(flowSort);
     node.to.forEach(x => {
       x.node = nodes.get(x.key);
-      x.addY = tmp;
-      tmp += x.flow;
     });
   });
 
   return nodes;
 }
 
-
-function getAddY(arr, key) {
-  for (let i = 0; i < arr.length; i++) {
-    if (arr[i].key === key) {
-      return arr[i].addY;
+/**
+ * @param {Array<FromToElement>} arr
+ * @param {string} key
+ * @param {number} index
+ * @return {number}
+ */
+function getAddY(arr, key, index) {
+  for (const item of arr) {
+    if (item.key === key && item.index === index) {
+      return item.addY;
     }
   }
   return 0;
 }
 
-class SankeyController extends DatasetController {
+/**
+ * @param {any} size
+ * @return {'min' | 'max'}
+ */
+function validateSizeValue(size) {
+  if (!size || ['min', 'max'].indexOf(size) === -1) {
+    return 'max';
+  }
+  return size;
+}
 
+class SankeyController extends DatasetController {
+  /**
+   * @param {ChartMeta<Flow, Element>} meta
+   * @param {Array<SankeyDataPoint>} data Array of original data elements
+   * @param {number} start
+   * @param {number} count
+   * @return {Array<SankeyParsedData>}
+   */
   parseObjectData(meta, data, start, count) {
     // https://github.com/chartjs/Chart.js/pull/8379
     if (count === 0) {
@@ -254,9 +391,10 @@ class SankeyController extends DatasetController {
     }
     const me = this;
     const {xScale, yScale} = meta;
-    const parsed = [];
-    const nodes = me._nodes = buildNodesFromFlows(data);
-    const priority = me.getDataset().priority;
+    const parsed = []; /* Array<SankeyParsedData> */
+    const nodes = me._nodes = buildNodesFromRawData(data);
+    /* getDataset() => SankeyControllerDatasetOptions */
+    const {priority, size} = me.getDataset();
     if (priority) {
       for (const node of nodes.values()) {
         if (node.key in priority) {
@@ -265,17 +403,18 @@ class SankeyController extends DatasetController {
       }
     }
 
-    const {maxX, maxY} = layout(nodes, data, !!priority);
+    const {maxX, maxY} = layout(nodes, data, !!priority, validateSizeValue(size));
 
     me._maxX = maxX;
     me._maxY = maxY;
 
+    /* loop over raw data elements {SankeyDataPoint} */
     for (let i = 0, ilen = data.length; i < ilen; ++i) {
-      const flow = data[i];
-      const from = nodes.get(flow.from);
-      const to = nodes.get(flow.to);
-      const fromY = from.y + getAddY(from.to, flow.to);
-      const toY = to.y + getAddY(to.from, flow.from);
+      const dataPoint = data[i]; /* {SankeyDataPoint} */
+      const from = nodes.get(dataPoint.from); /* from {SankeyNode} */
+      const to = nodes.get(dataPoint.to); /* to {SankeyNode} */
+      const fromY = from.y + getAddY(from.to, dataPoint.to, i);
+      const toY = to.y + getAddY(to.from, dataPoint.from, i);
       parsed.push({
         x: xScale.parse(from.x, i),
         y: yScale.parse(fromY, i),
@@ -284,7 +423,7 @@ class SankeyController extends DatasetController {
           to,
           x: xScale.parse(to.x, i),
           y: yScale.parse(toY, i),
-          height: yScale.parse(flow.flow, i),
+          height: yScale.parse(dataPoint.flow, i),
         }
       });
     }
@@ -306,6 +445,12 @@ class SankeyController extends DatasetController {
     me.updateElements(meta.data, 0, meta.data.length, mode);
   }
 
+  /**
+   * @param {Array<Flow>} elems
+   * @param {number} start
+   * @param {number} count
+   * @param {"resize" | "reset" | "none" | "hide" | "show" | "normal" | "active"} mode
+   */
   updateElements(elems, start, count, mode) {
     const me = this;
     const {xScale, yScale} = me._cachedMeta;
@@ -316,6 +461,7 @@ class SankeyController extends DatasetController {
     const nodeWidth = valueOrDefault(dataset.nodeWidth, 10);
 
     for (let i = start; i < start + count; i++) {
+      /* getParsed(idx: number) => SankeyParsedData */
       const parsed = me.getParsed(i);
       const custom = parsed._custom;
       const y = yScale.getPixelForValue(parsed.y);
@@ -343,7 +489,8 @@ class SankeyController extends DatasetController {
     const me = this;
     const ctx = me._ctx;
     const nodes = me._nodes || new Map();
-    const dataset = me.getDataset();
+    const dataset = me.getDataset(); /* SankeyControllerDatasetOptions */
+    const size = validateSizeValue(dataset.size);
     const borderWidth = valueOrDefault(dataset.borderWidth, 1);
     const nodeWidth = valueOrDefault(dataset.nodeWidth, 10);
     const labels = dataset.labels;
@@ -351,11 +498,11 @@ class SankeyController extends DatasetController {
 
     ctx.save();
     const chartArea = me.chart.chartArea;
-
     for (const node of nodes.values()) {
       const x = xScale.getPixelForValue(node.x);
       const y = yScale.getPixelForValue(node.y);
-      const max = Math.max(node.in, node.out);
+
+      const max = Math[size](node.in || node.out, node.out || node.in);
       const height = Math.abs(yScale.getPixelForValue(node.y + max) - y);
       const label = labels && labels[node.key] || node.key;
       let textX = x;
@@ -368,16 +515,70 @@ class SankeyController extends DatasetController {
         ctx.textAlign = 'right';
         textX -= borderWidth + 4;
       }
-      ctx.fillText(label, textX, y + height / 2);
+      this._drawLabel(label, y, height, ctx, textX);
     }
     ctx.restore();
   }
 
+  /**
+   * @param {string} label
+   * @param {number} y
+   * @param {number} height
+   * @param {CanvasRenderingContext2D} ctx
+   * @param {number} textX
+   * @private
+   */
+  _drawLabel(label, y, height, ctx, textX) {
+    const me = this;
+    const font = toFont(me.options.font, me.chart.options.font);
+    const lines = isNullOrUndef(label) ? [] : me.toTextLines(label);
+    const linesLength = lines.length;
+    const middle = y + height / 2;
+    const textHeight = font.lineHeight;
+    const padding = valueOrDefault(me.options.padding, textHeight / 2);
+
+    ctx.font = font.string;
+
+    if (linesLength > 1) {
+      const top = middle - (textHeight * linesLength / 2) + padding;
+      for (let i = 0; i < linesLength; i++) {
+        ctx.fillText(lines[i], textX, top + (i * textHeight));
+      }
+    } else {
+      ctx.fillText(label, textX, middle);
+    }
+  }
+
+  /**
+   * @param {string | Array<string>} inputs
+   * @return {Array<string>}
+   * @todo move this in Chart.helpers.toTextLines
+   */
+  toTextLines(inputs) {
+    let lines = [];
+    let input;
+
+    inputs = [].concat(inputs);
+    while (inputs.length) {
+      input = inputs.pop();
+      if (typeof input === 'string') {
+        lines.unshift.apply(lines, input.split('\n'));
+      } else if (Array.isArray(input)) {
+        inputs.push.apply(inputs, input);
+      } else if (!isNullOrUndef(inputs)) {
+        lines.unshift('' + input);
+      }
+    }
+
+    return lines;
+  }
+
   _drawNodes() {
     const me = this;
     const ctx = me._ctx;
     const nodes = me._nodes || new Map();
-    const dataset = me.getDataset();
+    const dataset = me.getDataset();  /* SankeyControllerDatasetOptions */
+    const size = validateSizeValue(dataset.size);
     const {xScale, yScale} = me._cachedMeta;
     const borderWidth = valueOrDefault(dataset.borderWidth, 1);
     const nodeWidth = valueOrDefault(dataset.nodeWidth, 10);
@@ -390,7 +591,8 @@ class SankeyController extends DatasetController {
       ctx.fillStyle = node.color;
       const x = xScale.getPixelForValue(node.x);
       const y = yScale.getPixelForValue(node.y);
-      const max = Math.max(node.in, node.out);
+
+      const max = Math[size](node.in || node.out, node.out || node.in);
       const height = Math.abs(yScale.getPixelForValue(node.y + max) - y);
       if (borderWidth) {
         ctx.strokeRect(x, y, nodeWidth, height);
@@ -400,28 +602,35 @@ class SankeyController extends DatasetController {
     ctx.restore();
   }
 
+  /**
+   * That's where the drawing process happens
+   */
   draw() {
     const me = this;
     const ctx = me._ctx;
-    const data = me.getMeta().data || [];
+    const data = me.getMeta().data || []; /* Array<Flow> */
 
     for (let i = 0, ilen = data.length; i < ilen; ++i) {
-      const flow = data[i];
+      const flow = data[i]; /* Flow at index i */
       flow.from.color = flow.options.colorFrom;
       flow.to.color = flow.options.colorTo;
     }
 
+    /* draw SankeyNodes on the canvas */
     me._drawNodes();
 
+    /* draw Flow elements on the canvas */
     for (let i = 0, ilen = data.length; i < ilen; ++i) {
       data[i].draw(ctx);
     }
 
+    /* draw labels (for SankeyNodes) on the canvas */
     me._drawLabels();
   }
 }
 
 SankeyController.id = 'sankey';
+
 SankeyController.defaults = {
   dataElementType: 'flow',
   animations: {
@@ -457,9 +666,10 @@ SankeyController.defaults = {
           from: 'transparent'
         }
       }
-    },
+    }
   }
 };
+
 SankeyController.overrides = {
   interaction: {
     mode: 'nearest',
@@ -480,10 +690,10 @@ SankeyController.overrides = {
           const item = context.dataset.data[context.dataIndex];
           return item.from + ' -> ' + item.to + ': ' + item.flow;
         }
-      }
+      },
     },
     legend: {
-      display: false
+      display: false,
     },
   },
   scales: {
@@ -492,7 +702,7 @@ SankeyController.overrides = {
       bounds: 'data',
       display: false,
       min: 0,
-      offset: false
+      offset: false,
     },
     y: {
       type: 'linear',
@@ -500,19 +710,29 @@ SankeyController.overrides = {
       display: false,
       min: 0,
       reverse: true,
-      offset: false
-    }
+      offset: false,
+    },
   },
   layout: {
     padding: {
       top: 3,
       left: 3,
       right: 13,
-      bottom: 3
-    }
-  }
+      bottom: 3,
+    },
+  },
 };
 
+/**
+ * @typedef {{x: number, y: number}} ControlPoint
+ * @typedef {{cp1: ControlPoint, cp2: ControlPoint}} ControlPoints
+ *
+ * @param {number} x
+ * @param {number} y
+ * @param {number} x2
+ * @param {number} y2
+ * @return {ControlPoints}
+ */
 const controlPoints = (x, y, x2, y2) => x < x2
   ? {
     cp1: {x: x + (x2 - x) / 3 * 2, y},
@@ -523,9 +743,20 @@ const controlPoints = (x, y, x2, y2) => x < x2
     cp2: {x: x2 + (x - x2) / 3, y: 0}
   };
 
+/**
+ *
+ * @param {ControlPoint} p1
+ * @param {ControlPoint} p2
+ * @param {number} t
+ * @return {ControlPoint}
+ */
 const pointInLine = (p1, p2, t) => ({x: p1.x + t * (p2.x - p1.x), y: p1.y + t * (p2.y - p1.y)});
 
 class Flow extends Element {
+
+  /**
+   * @param {FlowConfig} cfg
+   */
   constructor(cfg) {
     super();
 
@@ -541,6 +772,9 @@ class Flow extends Element {
     }
   }
 
+  /**
+   * @param {CanvasRenderingContext2D} ctx
+   */
   draw(ctx) {
     const me = this;
     const {x, x2, y, y2, height, progress} = me;
@@ -587,6 +821,12 @@ class Flow extends Element {
     ctx.restore();
   }
 
+  /**
+   * @param {number} mouseX
+   * @param {number} mouseY
+   * @param {boolean} useFinalPosition
+   * @return {boolean}
+   */
   inRange(mouseX, mouseY, useFinalPosition) {
     const {x, y, x2, y2, height} = this.getProps(['x', 'y', 'x2', 'y2', 'height'], useFinalPosition);
     if (mouseX < x || mouseX > x2) {
@@ -605,11 +845,21 @@ class Flow extends Element {
     return mouseY >= topY && mouseY <= topY + height;
   }
 
+  /**
+   * @param {number} mouseX
+   * @param {boolean} useFinalPosition
+   * @return {boolean}
+   */
   inXRange(mouseX, useFinalPosition) {
     const {x, x2} = this.getProps(['x', 'x2'], useFinalPosition);
     return mouseX >= x && mouseX <= x2;
   }
 
+  /**
+   * @param {number} mouseY
+   * @param {boolean} useFinalPosition
+   * @return {boolean}
+   */
   inYRange(mouseY, useFinalPosition) {
     const {y, y2, height} = this.getProps(['y', 'y2', 'height'], useFinalPosition);
     const minY = Math.min(y, y2);
@@ -617,6 +867,10 @@ class Flow extends Element {
     return mouseY >= minY && mouseY <= maxY;
   }
 
+  /**
+   * @param {boolean} useFinalPosition
+   * @return {{x: number, y:number}}
+   */
   getCenterPoint(useFinalPosition) {
     const {x, y, x2, y2, height} = this.getProps(['x', 'y', 'x2', 'y2', 'height'], useFinalPosition);
     return {
@@ -625,10 +879,14 @@ class Flow extends Element {
     };
   }
 
-  tooltipPosition() {
-    return this.getCenterPoint();
+  tooltipPosition(useFinalPosition) {
+    return this.getCenterPoint(useFinalPosition);
   }
 
+  /**
+   * @param {"x" | "y"} axis
+   * @return {number}
+   */
   getRange(axis) {
     return axis === 'x' ? this.width / 2 : this.height / 2;
   }