Enable label on ellipse annotation (#749)

* Enable label on ellipse annotation

* adds label reference in ellipse element

* adds test cases

* adds types

* adds documentation

* adds samples

* Add element diagrams to the annotation types guide

* fixes lint

* fixes CC similar code

* back to similar code

Author: stockiNail

docs/.vuepress/config.js

@@ -140,6 +140,8 @@ module.exports = {
           children: [
             'ellipse/basic',
             'ellipse/rotation',
+            'ellipse/label',
+            'ellipse/image',
           ]
         },
         {

docs/guide/types/_commonInnerLabel.md

@@ -0,0 +1,35 @@
+## Label
+
+Namespace: `options.annotations[annotationID].label`, it defines options for the the label of annotation.
+
+All of these options can be [Scriptable](../options#scriptable-options)
+
+| Name | Type | Default | Notes
+| ---- | ---- | :----: | ----
+| `color` | [`Color`](../options#color) | `'black'` | Text color.
+| `content` | `string`\|`string[]`\|[`Image`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLImageElement/Image)\|[`HTMLCanvasElement`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLCanvasElement) | `null` | The content to show in the label.
+| `display` | `boolean` | `false` | Whether or not the label is shown.
+| `drawTime` | `string` | `options.drawTime` | See [drawTime](../options#draw-time). Defaults to the annotation draw time if unset
+| `font` | [`Font`](../options#font) | `{ weight: 'bold' }` | Label font
+| `height` | `number`\|`string` | `undefined` | Overrides the height of the image or canvas element. Could be set in pixel by a number, or in percentage of current height of image or canvas element by a string. If undefined, uses the height of the image or canvas element. It is used only when the content is an image or canvas element.
+| `padding` | [`Padding`](../options#padding) | `6` | The padding to add around the text label.
+| [`position`](#position) | `string`\|`{x: string, y: string}` | `'center'` | Anchor position of label in the annotation.
+| `rotation` | `number` | `undefined` | Rotation of label, in degrees. If `undefined`, the annotation rotation is used.
+| `textAlign` | `string` | `'start'` | Text alignment of label content when there's more than one line. Possible options are: `'left'`, `'start'`, `'center'`, `'end'`, `'right'`.
+| `textStrokeColor` | [`Color`](../options#color) | `undefined` | The color of the stroke around the text.
+| `textStrokeWidth` | `number` | `0` | Stroke width around the text.
+| `width` | `number`\|`string` | `undefined` | Overrides the width of the image or canvas element. Could be set in pixel by a number, or in percentage of current width of image or canvas element by a string. If undefined, uses the width of the image or canvas element. It is used only when the content is an image or canvas element.
+| `xAdjust` | `number` | `0` | Adjustment along x-axis (left-right) of label relative to computed position. Negative values move the label left, positive right.
+| `yAdjust` | `number` | `0` | Adjustment along y-axis (top-bottom) of label relative to computed position. Negative values move the label up, positive down.
+| `z` | `number` | `0` | It determines the drawing stack level of the label element, with same `drawTime`.
+
+### Position
+
+A position can be set in 2 different values types:
+
+1. `'start'`, `'center'`, `'end'` which are defining where the label will be located
+2. a `string`, in percentage format `'number%'`, is representing the percentage on the size where the label will be located
+
+If this value is a string (possible options are `'start'`, `'center'`, `'end'` or a string in percentage format), it is applied to vertical and horizontal position in the annotation.
+
+If this value is an object, the `x` property defines the horizontal alignment in the annotation. Similarly, the `y` property defines the vertical alignment in the annotation. Possible options for both properties are `'start'`, `'center'`, `'end'`, a string in percentage format. Omitted property have value of the default, `'center'`.

docs/guide/types/box.md

@@ -104,41 +104,7 @@ If one of the axes does not match an axis in the chart, the box will take the en
 
 If this value is a number, it is applied to all corners of the rectangle (topLeft, topRight, bottomLeft, bottomRight). If this value is an object, the `topLeft` property defines the top-left corners border radius. Similarly, the `topRight`, `bottomLeft`, and `bottomRight` properties can also be specified. Omitted corners have radius of 0.
 
-## Label
-
-Namespace: `options.annotations[annotationID].label`, it defines options for the box annotation label.
-
-All of these options can be [Scriptable](../options#scriptable-options)
-
-| Name | Type | Default | Notes
-| ---- | ---- | :----: | ----
-| `color` | [`Color`](../options#color) | `'black'` | Text color.
-| `content` | `string`\|`string[]`\|[`Image`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLImageElement/Image)\|[`HTMLCanvasElement`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLCanvasElement) | `null` | The content to show in the label.
-| `display` | `boolean` | `false` | Whether or not the label is shown.
-| `drawTime` | `string` | `options.drawTime` | See [drawTime](../options#draw-time). Defaults to the box annotation draw time if unset
-| `font` | [`Font`](../options#font) | `{ weight: 'bold' }` | Label font
-| `height` | `number`\|`string` | `undefined` | Overrides the height of the image or canvas element. Could be set in pixel by a number, or in percentage of current height of image or canvas element by a string. If undefined, uses the height of the image or canvas element. It is used only when the content is an image or canvas element.
-| `padding` | [`Padding`](../options#padding) | `6` | The padding to add around the text label.
-| [`position`](#position) | `string`\|`{x: string, y: string}` | `'center'` | Anchor position of label in the box.
-| `rotation` | `number` | `undefined` | Rotation of label, in degrees. If `undefined`, the box rotation is used.
-| `textAlign` | `string` | `'start'` | Text alignment of label content when there's more than one line. Possible options are: `'left'`, `'start'`, `'center'`, `'end'`, `'right'`.
-| `textStrokeColor` | [`Color`](../options#color) | `undefined` | The color of the stroke around the text.
-| `textStrokeWidth` | `number` | `0` | Stroke width around the text.
-| `width` | `number`\|`string` | `undefined` | Overrides the width of the image or canvas element. Could be set in pixel by a number, or in percentage of current width of image or canvas element by a string. If undefined, uses the width of the image or canvas element. It is used only when the content is an image or canvas element.
-| `xAdjust` | `number` | `0` | Adjustment along x-axis (left-right) of label relative to computed position. Negative values move the label left, positive right.
-| `yAdjust` | `number` | `0` | Adjustment along y-axis (top-bottom) of label relative to computed position. Negative values move the label up, positive down.
-| `z` | `number` | `0` | It determines the drawing stack level of the label element, with same `drawTime`.
-
-### Position
-
-A position can be set in 2 different values types:
-
-1. `'start'`, `'center'`, `'end'` which are defining where the label will be located
-2. a `string`, in percentage format `'number%'`, is representing the percentage on the size where the label will be located
-
-If this value is a string (possible options are `'start'`, `'center'`, `'end'` or a string in percentage format), it is applied to vertical and horizontal position in the box.
-
-If this value is an object, the `x` property defines the horizontal alignment in the box. Similarly, the `y` property defines the vertical alignment in the box. Possible options for both properties are `'start'`, `'center'`, `'end'`, a string in percentage format. Omitted property have value of the default, `'center'`.
+!!!include(./guide/types/_commonInnerLabel.md)!!!
 
 ## Element
 

docs/guide/types/ellipse.md

@@ -55,6 +55,7 @@ The following options are available for ellipse annotations.
 | ---- | ---- | :----: | ----
 | [`backgroundShadowColor`](#styling) | [`Color`](../options#color) | Yes | `'transparent'`
 | [`borderWidth`](#styling) | `number`| Yes | `1`
+| [`label`](#label) | `object` | Yes |
 | [`rotation`](#general) | `number`| Yes | `0`
 
 !!!include(./guide/types/_commonOptions.md)!!!
@@ -93,6 +94,8 @@ If one of the axes does not match an axis in the chart, the ellipse will take th
 | `shadowOffsetX` | The distance that shadow will be offset horizontally. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/shadowOffsetX).
 | `shadowOffsetY` | The distance that shadow will be offset vertically. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/shadowOffsetY).
 
+!!!include(./guide/types/_commonInnerLabel.md)!!!
+
 ## Element
 
 The following diagram is showing the element properties about a `'ellipse'` annotation:

docs/samples/ellipse/image.md

@@ -0,0 +1,76 @@
+# Using images as labels
+
+```js chart-editor
+// <block:setup:2>
+const DATA_COUNT = 12;
+const MIN = 10;
+const MAX = 100;
+
+const numberCfg = {count: DATA_COUNT, min: MIN, max: MAX};
+
+const data = {
+  labels: ['January', 'February', 'March', 'April', 'May', 'June', 'July', 'August', 'September', 'October', 'November', 'December'],
+  datasets: [{
+    data: Utils.numbers(numberCfg)
+  }]
+};
+// </block:setup>
+
+// <block:annotation:1>
+const annotation = {
+  type: 'ellipse',
+  backgroundColor: 'rgba(0, 0, 0, 0.2)',
+  borderWidth: 1,
+  borderColor: '#F27173',
+  yMin: 30,
+  yMax: 80,
+  xMax: 2,
+  xMin: 5,
+  label: {
+    display: true,
+    content: Utils.getImage(),
+    width: 150,
+    height: 150,
+    position: 'center'
+  }
+};
+// </block:annotation>
+
+/* <block:config:0> */
+const config = {
+  type: 'line',
+  data,
+  options: {
+    scales: {
+      y: {
+        beginAtZero: true
+      }
+    },
+    plugins: {
+      annotation: {
+        annotations: {
+          annotation
+        }
+      }
+    }
+  }
+};
+/* </block:config> */
+
+const actions = [
+  {
+    name: 'Randomize',
+    handler: function(chart) {
+      chart.data.datasets.forEach(function(dataset, i) {
+        dataset.data = dataset.data.map(() => Utils.rand(MIN, MAX));
+      });
+      chart.update();
+    }
+  }
+];
+
+module.exports = {
+  actions: actions,
+  config: config
+};
+```

docs/samples/ellipse/label.md

@@ -0,0 +1,72 @@
+# Labeling
+
+```js chart-editor
+// <block:setup:2>
+const DATA_COUNT = 12;
+const MIN = 10;
+const MAX = 100;
+
+const numberCfg = {count: DATA_COUNT, min: MIN, max: MAX};
+
+const data = {
+  labels: ['January', 'February', 'March', 'April', 'May', 'June', 'July', 'August', 'September', 'October', 'November', 'December'],
+  datasets: [{
+    data: Utils.numbers(numberCfg)
+  }]
+};
+// </block:setup>
+
+// <block:annotation:1>
+const annotation = {
+  type: 'ellipse',
+  backgroundColor: 'rgba(208, 208, 208, 0.2)',
+  borderWidth: 0,
+  label: {
+    drawTime: 'afterDatasetsDraw',
+    display: true,
+    color: 'rgba(208, 208, 208, 0.6)',
+    content: 'whole year',
+    font: {
+      size: (ctx) => ctx.chart.chartArea.height / 4
+    },
+    position: {
+      x: 'center',
+      y: 'end'
+    }
+  }
+};
+// </block:annotation>
+
+/* <block:config:0> */
+const config = {
+  type: 'line',
+  data,
+  options: {
+    plugins: {
+      annotation: {
+        annotations: {
+          annotation
+        }
+      }
+    }
+  }
+};
+/* </block:config> */
+
+const actions = [
+  {
+    name: 'Randomize',
+    handler: function(chart) {
+      chart.data.datasets.forEach(function(dataset, i) {
+        dataset.data = dataset.data.map(() => Utils.rand(MIN, MAX));
+      });
+      chart.update();
+    }
+  }
+];
+
+module.exports = {
+  actions: actions,
+  config: config,
+};
+```

src/helpers/helpers.chart.js

@@ -1,5 +1,6 @@
-import {isFinite} from 'chart.js/helpers';
-import {isBoundToPoint} from './helpers.options';
+import {isFinite, toPadding} from 'chart.js/helpers';
+import {measureLabelSize} from './helpers.canvas';
+import {isBoundToPoint, getRelativePosition, toPosition} from './helpers.options';
 
 /**
  * @typedef { import("chart.js").Chart } Chart
@@ -144,6 +145,23 @@ export function resolvePointProperties(chart, options) {
   return getChartCircle(chart, options);
 }
 
+/**
+ * @param {Chart} chart
+ * @param {CoreAnnotationOptions} options
+ * @returns {AnnotationBoxModel}
+ */
+export function resolveBoxAndLabelProperties(chart, options) {
+  const properties = resolveBoxProperties(chart, options);
+  const {x, y} = properties;
+  properties.elements = [{
+    type: 'label',
+    optionScope: 'label',
+    properties: resolveLabelElementProperties(chart, properties, options)
+  }];
+  properties.initProperties = {x, y};
+  return properties;
+}
+
 function getChartCircle(chart, options) {
   const point = getChartPoint(chart, options);
   const size = options.radius * 2;
@@ -166,3 +184,54 @@ function getChartDimensionByScale(scale, options) {
     end: Math.max(result.start, result.end)
   };
 }
+
+function calculateX({properties, options}, labelSize, position, padding) {
+  const {x: start, x2: end, width: size} = properties;
+  return calculatePosition({start, end, size, borderWidth: options.borderWidth}, {
+    position: position.x,
+    padding: {start: padding.left, end: padding.right},
+    adjust: options.label.xAdjust,
+    size: labelSize.width
+  });
+}
+
+function calculateY({properties, options}, labelSize, position, padding) {
+  const {y: start, y2: end, height: size} = properties;
+  return calculatePosition({start, end, size, borderWidth: options.borderWidth}, {
+    position: position.y,
+    padding: {start: padding.top, end: padding.bottom},
+    adjust: options.label.yAdjust,
+    size: labelSize.height
+  });
+}
+
+function calculatePosition(boxOpts, labelOpts) {
+  const {start, end, borderWidth} = boxOpts;
+  const {position, padding: {start: padStart, end: padEnd}, adjust} = labelOpts;
+  const availableSize = end - borderWidth - start - padStart - padEnd - labelOpts.size;
+  return start + borderWidth / 2 + adjust + getRelativePosition(availableSize, position);
+}
+
+function resolveLabelElementProperties(chart, properties, options) {
+  const label = options.label;
+  label.backgroundColor = 'transparent';
+  label.callout.display = false;
+  const position = toPosition(label.position);
+  const padding = toPadding(label.padding);
+  const labelSize = measureLabelSize(chart.ctx, label);
+  const x = calculateX({properties, options}, labelSize, position, padding);
+  const y = calculateY({properties, options}, labelSize, position, padding);
+  const width = labelSize.width + padding.width;
+  const height = labelSize.height + padding.height;
+  return {
+    x,
+    y,
+    x2: x + width,
+    y2: y + height,
+    width,
+    height,
+    centerX: x + width / 2,
+    centerY: y + height / 2,
+    rotation: label.rotation
+  };
+}