Implement layers (z-index) for layout items (#6241)

Author: kurkle

docs/axes/styling.md

@@ -23,6 +23,7 @@ The grid line configuration is nested under the scale configuration in the `grid
 | `zeroLineBorderDash` | `number[]` | `[]` | Length and spacing of dashes of the grid line for the first index (index 0). See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/setLineDash).
 | `zeroLineBorderDashOffset` | `number` | `0.0` | Offset for line dashes of the grid line for the first index (index 0). See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/lineDashOffset).
 | `offsetGridLines` | `boolean` | `false` | If true, grid lines will be shifted to be between labels. This is set to `true` for a category scale in a bar chart by default.
+| `z` | `number` | `0` | z-index of gridline layer. Values <= 0 are drawn under datasets, > 0 on top.
 
 ## Tick Configuration
 The tick configuration is nested under the scale configuration in the `ticks` key. It defines options for the tick marks that are generated by the axis.
@@ -40,6 +41,7 @@ The tick configuration is nested under the scale configuration in the `ticks` ke
 | `minor` | `object` | `{}` | Minor ticks configuration. Omitted options are inherited from options above.
 | `major` | `object` | `{}` | Major ticks configuration. Omitted options are inherited from options above.
 | `padding` | `number` | `0` | Sets the offset of the tick labels from the axis
+| `z` | `number` | `0` | z-index of tick layer. Useful when ticks are drawn on chart area. Values <= 0 are drawn under datasets, > 0 on top.
 
 ## Minor Tick Configuration
 The minorTick configuration is nested under the ticks configuration in the `minor` key. It defines options for the minor tick marks that are generated by the axis. Omitted options are inherited from `ticks` configuration.

src/core/core.controller.js

@@ -169,6 +169,7 @@ helpers.extend(Chart.prototype, /** @lends Chart */ {
 		me.aspectRatio = height ? width / height : null;
 		me.options = config.options;
 		me._bufferedRender = false;
+		me._layers = [];
 
 		/**
 		 * Provided for backward compatibility, Chart and Chart.Controller have been merged,
@@ -495,6 +496,12 @@ helpers.extend(Chart.prototype, /** @lends Chart */ {
 		// Do this before render so that any plugins that need final scale updates can use it
 		plugins.notify(me, 'afterUpdate');
 
+		me._layers.sort(function(a, b) {
+			return a.z === b.z
+				? a._idx - b._idx
+				: a.z - b.z;
+		});
+
 		if (me._bufferedRender) {
 			me._bufferedRequest = {
 				duration: config.duration,
@@ -520,6 +527,15 @@ helpers.extend(Chart.prototype, /** @lends Chart */ {
 
 		layouts.update(this, this.width, this.height);
 
+		me._layers = [];
+		helpers.each(me.boxes, function(box) {
+			me._layers.push.apply(me._layers, box._layers());
+		}, me);
+
+		me._layers.forEach(function(item, index) {
+			item._idx = index;
+		});
+
 		/**
 		 * Provided for backward compatibility, use `afterLayout` instead.
 		 * @method IPlugin#afterScaleUpdate
@@ -626,6 +642,7 @@ helpers.extend(Chart.prototype, /** @lends Chart */ {
 
 	draw: function(easingValue) {
 		var me = this;
+		var i, layers;
 
 		me.clear();
 
@@ -643,12 +660,21 @@ helpers.extend(Chart.prototype, /** @lends Chart */ {
 			return;
 		}
 
-		// Draw all the scales
-		helpers.each(me.boxes, function(box) {
-			box.draw(me.chartArea);
-		}, me);
+		// Because of plugin hooks (before/afterDatasetsDraw), datasets can't
+		// currently be part of layers. Instead, we draw
+		// layers <= 0 before(default, backward compat), and the rest after
+		layers = me._layers;
+		for (i = 0; i < layers.length && layers[i].z <= 0; ++i) {
+			layers[i].draw(me.chartArea);
+		}
 
 		me.drawDatasets(easingValue);
+
+		// Rest of layers
+		for (; i < layers.length; ++i) {
+			layers[i].draw(me.chartArea);
+		}
+
 		me._drawTooltip(easingValue);
 
 		plugins.notify(me, 'afterDraw', [easingValue]);

src/core/core.layouts.js

@@ -103,6 +103,14 @@ module.exports = {
 		item.fullWidth = item.fullWidth || false;
 		item.position = item.position || 'top';
 		item.weight = item.weight || 0;
+		item._layers = item._layers || function() {
+			return [{
+				z: 0,
+				draw: function() {
+					item.draw.apply(item, arguments);
+				}
+			}];
+		};
 
 		chart.boxes.push(item);
 	},