feat(heatmap): add min/max to heatmap color domain

Author: tuckwat-dematic

packages/core/src/components/essentials/color-scale-legend.ts

@@ -5,7 +5,7 @@ import { legend as legendConfigs } from '@/configuration'
 import { ColorLegendType, Events, RenderTypes } from '@/interfaces/enums'
 import { Legend } from './legend'
 import { DOMUtils } from '@/services/essentials/dom-utils'
-import { getDomain } from '@/services/color-scale-utils'
+import { getDomain, type ColorDomainOptions } from '@/services/color-scale-utils'
 import type { ChartModel } from '@/model'
 
 export class ColorScaleLegend extends Legend {
@@ -107,7 +107,14 @@ export class ColorScaleLegend extends Legend {
 		}
 
 		const customColorsEnabled = !isEmpty(customColors)
-		const domain = getDomain(this.model.getDisplayData())
+
+		// Get custom color domain options for heatmap charts
+		const customDomain: ColorDomainOptions | undefined = getProperty(
+			options,
+			this.chartType,
+			'colorDomain'
+		)
+		const domain = getDomain(this.model.getDisplayData(), customDomain)
 
 		const useDefaultBarWidth = !(width <= legendConfigs.color.barWidth)
 		const barWidth = useDefaultBarWidth ? legendConfigs.color.barWidth : width

packages/core/src/interfaces/charts.ts

@@ -579,6 +579,22 @@ export interface HeatmapChartOptions extends AxisChartOptions {
 			title?: string
 			type?: ColorLegendType | string
 		}
+		/**
+		 * Optional explicit domain for the color scale.
+		 * When not specified, the domain is automatically calculated from the data values.
+		 */
+		colorDomain?: {
+			/**
+			 * Explicit minimum value for the color scale.
+			 * Values below this will use the minimum color.
+			 */
+			min?: number
+			/**
+			 * Explicit maximum value for the color scale.
+			 * Values above this will use the maximum color.
+			 */
+			max?: number
+		}
 	}
 }
 

packages/core/src/model/heatmap.ts

@@ -4,6 +4,7 @@ import { getProperty } from '@/tools'
 import { AxisFlavor, ScaleTypes } from '@/interfaces/enums'
 import { getColorScale } from '@/services'
 import { ChartModelCartesian } from './cartesian-charts'
+import type { ColorDomainOptions } from '@/services/color-scale-utils'
 
 /** The gauge chart model layer */
 export class HeatmapModel extends ChartModelCartesian {
@@ -37,9 +38,18 @@ export class HeatmapModel extends ChartModelCartesian {
 		}
 	}
 
+	/**
+	 * Get the custom color domain options from chart configuration
+	 * @returns ColorDomainOptions or undefined
+	 */
+	getColorDomainOptions(): ColorDomainOptions | undefined {
+		const options = this.getOptions()
+		return getProperty(options, 'heatmap', 'colorDomain')
+	}
+
 	/**
 	 * Get min and maximum value of the display data
-	 * @returns Array consisting of smallest and largest values in  data
+	 * @returns Array consisting of smallest and largest values in data
 	 */
 	getValueDomain() {
 		const limits = extent(this.getDisplayData(), (d: any) => d.value)
@@ -53,7 +63,8 @@ export class HeatmapModel extends ChartModelCartesian {
 			domain[0] = 0
 		} else if (domain[0] === 0 && domain[1] === 0) {
 			// Range cannot be between 0 and 0 (itself)
-			return [0, 1]
+			domain[0] = 0
+			domain[1] = 1
 		}
 
 		// Ensure the median of the range is 0 if domain extends into both negative & positive
@@ -65,6 +76,17 @@ export class HeatmapModel extends ChartModelCartesian {
 			}
 		}
 
+		// Apply custom domain overrides from options if provided
+		const customDomain = this.getColorDomainOptions()
+		if (customDomain) {
+			if (typeof customDomain.min === 'number') {
+				domain[0] = customDomain.min
+			}
+			if (typeof customDomain.max === 'number') {
+				domain[1] = customDomain.max
+			}
+		}
+
 		return domain
 	}
 
@@ -299,11 +321,12 @@ export class HeatmapModel extends ChartModelCartesian {
 			}
 		}
 
-		// Save scale type
+		// Save scale type with custom domain support
 		this._colorScale = scaleQuantize()
 			.domain(domain as [number, number])
 			.range(colorPairing)
 		const colorOptions = getProperty(this.getOptions(), 'color')
-		this._colorScale = getColorScale(this.getDisplayData(), colorOptions)
+		const customDomain = this.getColorDomainOptions()
+		this._colorScale = getColorScale(this.getDisplayData(), colorOptions, customDomain)
 	}
 }

packages/core/src/services/color-scale-utils.ts

@@ -2,7 +2,21 @@ import { extent, scaleLinear, scaleQuantize } from 'd3'
 import { isEmpty } from 'lodash-es'
 import { getProperty } from '@/tools'
 
-export function getDomain(data: any) {
+/**
+ * Custom domain configuration for color scales
+ */
+export interface ColorDomainOptions {
+	min?: number
+	max?: number
+}
+
+/**
+ * Calculate the domain for a color scale from data values
+ * @param data - Array of data objects with value property
+ * @param customDomain - Optional explicit min/max values to override calculated domain
+ * @returns [min, max] domain array
+ */
+export function getDomain(data: any, customDomain?: ColorDomainOptions) {
 	const limits = extent(data, (d: any) => d.value)
 	const domain = scaleLinear()
 		.domain(limits as [number, number])
@@ -14,7 +28,8 @@ export function getDomain(data: any) {
 		domain[0] = 0
 	} else if (domain[0] === 0 && domain[1] === 0) {
 		// Range cannot be between 0 and 0 (itself)
-		return [0, 1]
+		domain[0] = 0
+		domain[1] = 1
 	}
 
 	// Ensure the median of the range is 0 if domain extends into both negative & positive
@@ -26,17 +41,27 @@ export function getDomain(data: any) {
 		}
 	}
 
+	// Apply custom domain overrides if provided
+	if (customDomain) {
+		if (typeof customDomain.min === 'number') {
+			domain[0] = customDomain.min
+		}
+		if (typeof customDomain.max === 'number') {
+			domain[1] = customDomain.max
+		}
+	}
+
 	return domain
 }
 
-export function getColorScale(displayData: any, colorOptions: any) {
+export function getColorScale(displayData: any, colorOptions: any, customDomain?: ColorDomainOptions) {
 	const customColors = getProperty(colorOptions, 'gradient', 'colors')
 	const customColorsEnabled = !isEmpty(customColors)
 
 	let colorPairingOption = getProperty(colorOptions, 'pairing', 'option')
 
 	// If domain consists of negative and positive values, use diverging palettes
-	const domain = getDomain(displayData)
+	const domain = getDomain(displayData, customDomain)
 	const colorScheme = domain[0] < 0 && domain[1] > 0 ? 'diverge' : 'mono'
 
 	// Use default color pairing options if not in defined range

packages/docs/src/lib/heatmap/index.ts

@@ -112,6 +112,30 @@ const heatmapMissingDataOptions: HeatmapChartOptions = {
 	height: '400px'
 }
 
+const heatmapCustomColorDomainOptions: HeatmapChartOptions = {
+	title: 'Heatmap (Custom color domain)',
+	axes: {
+		bottom: {
+			title: 'Letters',
+			mapsTo: 'letter',
+			scaleType: ScaleTypes.LABELS
+		},
+		left: {
+			title: 'Months',
+			mapsTo: 'month',
+			scaleType: ScaleTypes.LABELS
+		}
+	},
+	heatmap: {
+		colorLegend: { title: 'Score (0, 150)' },
+		colorDomain: {
+			min: 0,
+			max: 150
+		}
+	},
+	height: '400px'
+}
+
 const heatmapData: ChartTabularData = [
 	{
 		letter: 'A',
@@ -1302,6 +1326,11 @@ export const examples: Example[] = [
 		data: heatmapMissingData,
 		tags: ['test']
 	},
+	{
+		options: heatmapCustomColorDomainOptions,
+		data: heatmapData,
+		tags: ['test']
+	},
 	{
 		options: heatmapDomainOptions,
 		data: heatmapData,

packages/docs/src/searchIndex.ts

@@ -552,7 +552,11 @@ export default [
 			'Heatmap (Missing data)',
 			'Letters',
 			'Months',
-			'Legend title'
+			'Legend title',
+			'Heatmap (Custom color domain)',
+			'Letters',
+			'Months',
+			'Score (0-150)'
 		]
 	},
 	{