Add custom legend for Heatmap chart.

[IDDT]

Explanation About What Code Achieves:

Allows to pass an optional parameter "legend" to Heatmap chart with own starting values and colors.
Remove logic to use 2nd color if the value is bigger than the starting number for the 1st color.
Therefore, use "legend" parameter in docs example as it supposed to highlight 1st commit, even though the distribution calculates starting number as 1.25 (which does not highlight 1st commit).

Screenshots/GIFs:

Example in docs.

Steps To Test:

Pass your own legend.
Look at the example in the docs with and without passing "legend" parameter.

TODOs:

None

[achillesrasquinha]

Screenshots!

[IDDT]

Passing random data from 0 to 100 inclusive.

new Chart({
	parent: "#chart-heatmap",
	data: heatmap_data,
	type: 'heatmap',
	legend: [
        {color: 'hsl(216, 14%, 93%)', start: 0}, // color can also be hex or html name.
        {color: 'hsl(0, 62%, 72%)', start: 20}, // start is inclusive starting value for the color to trigger.
        {color: 'hsl(0, 45%, 61%)', start: 35},
        {color: 'hsl(0, 63%, 37%)', start: 50},
        {color: 'hsl(21, 100%, 50%)', start: 100}
	],
	height: 115,
	discrete_domains: 1  // default 0
});

If the legend is not passed, default (green) colors are used and starting values calculated with following function (not changed):

get_distribution(data={}, mapper_array) {
		let data_values = Object.keys(data).map(key => data[key]);
		let data_max_value = Math.max(...data_values);

		let distribution_step = 1 / (mapper_array.length - 1);
		let distribution = [];

		mapper_array.map((color, i) => {
			let checkpoint = data_max_value * (distribution_step * i);
			distribution.push(checkpoint);
		});

		return distribution;
	}

with the same distribution (different random data) it calculates like [0, 25, 50, 75, 100]

new Chart({
	parent: "#chart-heatmap",
	data: heatmap_data,
	type: 'heatmap',
	height: 115,
	discrete_domains: 1  // default 0
});

Hope this is useful.

[pratu16x7]

@IDDT Thanks for contributing :)

Custom legend colors are great. However, having to provide manual start values for each defeats the purpose of the heatmap, as data passed is dynamic, and the breakpoints are calculated via get_distribution().

We recommend keeping the legend colors an array, instead of an object. Any distribution fix needs to be done in get_distribution() itself.

[pratu16x7]

As an aside, we'd like to include this feature quickly, as it involves simply exposing an existing property legend_colors.
(It would make it easy for users to make something like, say, Github's Halloween theme for example :)

[IDDT]

@pratu16x7 ,
Valid feedback,
I'd still encourage you to keep custom scale as the optional parameter. There are different scenarios where the scale doesn't have to be calculated linearly. Besides GitHub example in the docs needs it since it used to assign 2nd color for the 1st commit, even though the distribution was calculated at 1.25.

[pratu16x7]

"There are different scenarios where the scale doesn't have to be calculated linearly."

Example use case? Nevertheless, in that case, the only thing known about the scale before getting data would be the scale mappings, not the actual values. So it would make sense to pass the mappings (perhaps as percentages of the min-max (range)), rather than values :)

[IDDT]

For example using logistic function to put more highlight on minimal changes while keeping drastic changes less prominent.

Another use case would be centering around 0 or around some business target, where values might be generally negative (or positive) for almost all of the scale.

One more case I have in mind is visualizing body vitals, where normal and critical values are predetermined.

Let me know what you think.

[pratu16x7]

Added a few commits, be sure to check out the docs demonstrating your idea :)

Let's keep the distribution mapping as a level 2 feature (maybe a new GitHub issue? ;) ). We'll focus on covering the standard uses first.