@automattic/charts 4.7.0 → 4.8.0

package/dist/index.js

@@ -5,13 +5,13 @@ import { __, _x, sprintf } from "@wordpress/i18n";
 import clsx from "clsx";
 import * as React from "react";
 import { Children, Fragment, createContext, createContext as createContext$1, createElement, forwardRef, forwardRef as forwardRef$1, isValidElement, memo, useCallback, useCallback as useCallback$1, useContext, useContext as useContext$1, useEffect, useEffect as useEffect$1, useId, useImperativeHandle, useLayoutEffect, useMemo, useMemo as useMemo$1, useRef, useRef as useRef$1, useState, useState as useState$1 } from "react";
-import { color, hsl } from "@visx/vendor/d3-color";
 import { differenceInHours, differenceInYears, isValid, parse, parseISO } from "date-fns";
 import { tzOffset } from "@date-fns/tz";
 import { Text, getStringWidth } from "@visx/text";
 import deepmerge from "deepmerge";
+import { color, hsl } from "@visx/vendor/d3-color";
 import { Fragment as Fragment$1, jsx, jsxs } from "react/jsx-runtime";
-import { Tooltip, useTooltip } from "@visx/tooltip";
+import { useTooltip } from "@visx/tooltip";
 import { createScale, getTicks, scaleBand, scaleCanBeZeroed, scaleOrdinal, scaleTime } from "@visx/scale";
 import { Group } from "@visx/group";
 import { LegendItem, LegendLabel, LegendOrdinal, LegendShape } from "@visx/legend";
@@ -834,6 +834,7 @@ const CATALOG_POINTERS = {
 	annotation: "var(--a8c-charts-color-annotation, #1e1e1e)",
 	surface: "var(--a8c-charts-color-surface, #fff)",
 	surfaceSecondary: "var(--a8c-charts-color-surface-secondary, #f4f4f4)",
+	track: "var(--a8c-charts-color-track, #f0f0f0)",
 	trendUp: "var(--a8c-charts-color-trend-up, #008030)",
 	trendDown: "var(--a8c-charts-color-trend-down, #cc1818)",
 	series: SERIES_PALETTE_POINTERS
@@ -1063,6 +1064,15 @@ const rgbLuminance = (rgb) => {
 * @return Ratio from 1 to 21.
 */
 const luminanceContrastRatio = (first, second) => (Math.max(first, second) + .05) / (Math.min(first, second) + .05);
+/**
+* WCAG contrast ratio between two hex colors.
+*
+* @param  first  - First hex color.
+* @param  second - Second hex color.
+* @return Ratio from 1 to 21.
+* @throws {Error} if either hex string is malformed
+*/
+const contrastRatio = (first, second) => luminanceContrastRatio(relativeLuminance(first), relativeLuminance(second));
 /** WCAG 1.4.3 text contrast, which a label drawn on a fill needs from at least one label color. */
 const MIN_LABEL_CONTRAST = 4.5;
 /** Degrees of hue one unit of OKLCH chroma is worth when ranking candidates by hue. */
@@ -1253,6 +1263,14 @@ const buildPaletteGenerator = (normalizedSeeds, background, labelColors) => {
 	};
 };
 //#endregion
+//#region src/providers/chart-context/private/resolve-opaque-hex.ts
+const resolveOpaqueHex = (pointer, resolve) => {
+	const raw = resolve(pointer);
+	if (!raw || color(raw)?.opacity !== 1) return null;
+	const hex = normalizeColorToHex(raw);
+	return isValidHexColor(hex) ? hex : null;
+};
+//#endregion
 //#region src/providers/chart-context/themes.ts
 /**
 * Default theme configuration: the shape and spacing a consumer can override.
@@ -1301,12 +1319,6 @@ const defaultTheme = {
 };
 //#endregion
 //#region src/providers/chart-context/global-charts-provider.tsx
-const resolveOpaqueHex = (pointer, element) => {
-	const raw = resolveCssVariable(pointer, element);
-	if (!raw || color(raw)?.opacity !== 1) return null;
-	const hex = normalizeColorToHex(pointer, element, resolveCssVariable);
-	return isValidHexColor(hex) ? hex : null;
-};
 const PLACEHOLDER_LABEL_COLORS = [LABEL_FALLBACK, LABEL_INVERSE_FALLBACK];
 const GlobalChartsContext = createContext(null);
 const GlobalChartsProvider = ({ children, theme, locale, timeZone }) => {
@@ -1334,8 +1346,9 @@ const GlobalChartsProvider = ({ children, theme, locale, timeZone }) => {
 			const normalizedColor = normalizeColorToHex(color, wrapperRef.current, resolveCssVariable);
 			if (isValidHexColor(normalizedColor)) resolvedColors.push(normalizedColor);
 		}
-		const backgroundHex = resolveOpaqueHex(CATALOG_POINTERS.background, wrapperRef.current) ?? "#ffffff";
-		const labelColors = [CATALOG_POINTERS.label, CATALOG_POINTERS.labelInverse].map((pointer) => resolveOpaqueHex(pointer, wrapperRef.current)).filter((hex) => hex !== null);
+		const resolveAtWrapper = createCssVariableResolver(wrapperRef.current);
+		const backgroundHex = resolveOpaqueHex(CATALOG_POINTERS.background, resolveAtWrapper) ?? "#ffffff";
+		const labelColors = [CATALOG_POINTERS.label, CATALOG_POINTERS.labelInverse].map((pointer) => resolveOpaqueHex(pointer, resolveAtWrapper)).filter((hex) => hex !== null);
 		setColorCache({
 			colors: resolvedColors,
 			background: backgroundHex,
@@ -1671,10 +1684,10 @@ const DEFAULT_MARGIN_BOTTOM = 20;
 */
 const DEFAULT_MARGIN_LEFT = 20;
 /**
-* Bottom margin to use when the X-axis is rendered at the top.
+* Bottom margin when no X-axis sits below the chart, because it is on top or hidden.
 * We only need a small buffer below the chart in that case.
 */
-const DEFAULT_BOTTOM_FOR_TOP_AXIS = 10;
+const DEFAULT_BOTTOM_WITHOUT_X_AXIS = 10;
 /**
 * Fallback font size used when we cannot derive a font size
 * from the theme or axis styles for X-axis tick labels.
@@ -1754,18 +1767,18 @@ const useChartMargin = (height, options, data, theme, horizontal = false) => {
 			if (yAxisOrientation === "right") defaultMargin.right = yMarginValue;
 			else defaultMargin.left = yMarginValue;
 		}
-		const xOrientation = options.axis?.x?.orientation === "top" ? "top" : "bottom";
-		const { fontSize, tickLength, tickLabelStyle } = getXAxisLabelMetrics(theme, xOrientation);
-		const computedXMargin = fontSize + tickLength;
-		if (xOrientation === "top") {
-			defaultMargin.top = Math.max(defaultMargin.top, computedXMargin);
-			defaultMargin.bottom = DEFAULT_BOTTOM_FOR_TOP_AXIS;
-		} else defaultMargin.bottom = Math.max(defaultMargin.bottom, computedXMargin);
 		if (options.axis?.x?.display !== false) {
+			const xOrientation = options.axis?.x?.orientation === "top" ? "top" : "bottom";
+			const { fontSize, tickLength, tickLabelStyle } = getXAxisLabelMetrics(theme, xOrientation);
+			const computedXMargin = fontSize + tickLength;
+			if (xOrientation === "top") {
+				defaultMargin.top = Math.max(defaultMargin.top, computedXMargin);
+				defaultMargin.bottom = DEFAULT_BOTTOM_WITHOUT_X_AXIS;
+			} else defaultMargin.bottom = Math.max(defaultMargin.bottom, computedXMargin);
 			const { first, last } = getEdgeTickWidths(options.axis?.x?.tickValues ?? [], options.axis?.x?.tickFormat, tickLabelStyle);
 			defaultMargin.left = Math.max(defaultMargin.left, Math.ceil(first / 2));
 			defaultMargin.right = Math.max(defaultMargin.right, Math.ceil(last / 2));
-		}
+		} else defaultMargin.bottom = DEFAULT_BOTTOM_WITHOUT_X_AXIS;
 		return defaultMargin;
 	}, [
 		options,
@@ -2477,11 +2490,12 @@ function useChartLegendItems(data, options = {}, legendShape) {
 	]);
 }
 //#endregion
-//#region src/components/tooltip/base-tooltip.module.scss
-var base_tooltip_module_default = {
-	"surface": "a8ccharts--zY0xG-surface",
-	"tooltip": "a8ccharts--zY0xG-tooltip"
-};
+//#region src/components/tooltip/private/label-value-content.tsx
+const LabelValueContent = ({ data }) => /* @__PURE__ */ jsxs(Fragment$1, { children: [
+	data.label,
+	": ",
+	data.valueDisplay || formatNumber(data.value)
+] });
 //#endregion
 //#region src/components/tooltip/private/tooltip-theme.tsx
 const DEFAULT_SURFACE = "#1e1e1e";
@@ -2507,28 +2521,63 @@ const TooltipTheme = ({ children }) => {
 	});
 };
 //#endregion
+//#region src/components/tooltip/tooltip-box.module.scss
+var tooltip_box_module_default = { "surface": "a8ccharts-ddpU1W-surface" };
+//#endregion
+//#region src/components/tooltip/tooltip-box.tsx
+/**
+* The chart tooltip box: the dark surface every chart tooltip draws. It does not position itself; place it with `style` or a wrapper.
+*
+* @param props          - Div attributes, plus `unstyled`.
+* @param props.unstyled - Drop the surface, scope class and theme.
+* @param ref            - Forwarded to the box element.
+* @return The tooltip box.
+*/
+const TooltipBox = forwardRef(({ unstyled = false, role = "tooltip", className, children, ...rest }, ref) => {
+	const box = /* @__PURE__ */ jsx("div", {
+		ref,
+		role,
+		className: clsx("visx-tooltip", !unstyled && ["a8c-charts-tooltip-scope", tooltip_box_module_default.surface], className),
+		...rest,
+		children
+	});
+	return unstyled ? box : /* @__PURE__ */ jsx(TooltipTheme, { children: box });
+});
+TooltipBox.displayName = "TooltipBox";
+//#endregion
 //#region src/components/tooltip/base-tooltip.tsx
-const DefaultTooltipContent = ({ data }) => /* @__PURE__ */ jsxs(Fragment$1, { children: [
-	data?.label,
-	": ",
-	data?.valueDisplay || formatNumber(data?.value)
-] });
-const BaseTooltip = ({ data, top, left, component: Component = DefaultTooltipContent, children, className, style, renderContainer = true }) => {
+/**
+* A tooltip box with children or `label: value` content. Prefer `TooltipBox`.
+*
+* @param props                 - Tooltip props.
+* @param props.data            - Data for the default content.
+* @param props.top             - Deprecated vertical position.
+* @param props.left            - Deprecated horizontal position.
+* @param props.component       - Deprecated content component.
+* @param props.children        - Tooltip content.
+* @param props.className       - Class name passed to the content component.
+* @param props.style           - Styles for the box.
+* @param props.renderContainer - Deprecated; render the content alone when false.
+* @return The tooltip.
+*/
+const BaseTooltip = ({ data, top, left, component: Component = LabelValueContent, children, className, style, renderContainer = true }) => {
 	const content = children || data && /* @__PURE__ */ jsx(Component, {
 		data,
 		className
 	});
 	if (!renderContainer) return content;
-	return /* @__PURE__ */ jsx(TooltipTheme, { children: /* @__PURE__ */ jsx("div", {
-		className: clsx(CHART_SCOPE_CLASS, base_tooltip_module_default.tooltip),
+	return /* @__PURE__ */ jsx(TooltipBox, {
 		style: {
-			top,
-			left,
+			...top === void 0 && left === void 0 ? void 0 : {
+				position: "absolute",
+				top,
+				left,
+				transform: "translate(-50%, -100%)"
+			},
 			...style
 		},
-		role: "tooltip",
 		children: content
-	}) });
+	});
 };
 //#endregion
 //#region src/components/tooltip/private/bounded-tooltip.tsx
@@ -2608,7 +2657,7 @@ const getBoundedPosition = ({ left, top, offsetLeft, offsetTop, box, wrapper, bo
 	};
 };
 /**
-* visx's `Tooltip`, positioned like its `TooltipWithBounds` but kept inside the
+* A `TooltipBox`, positioned like visx's `TooltipWithBounds` but kept inside the
 * nearest clipping ancestor — or the viewport when there is none — rather than
 * inside its own parent. Rendered in-tree, a tooltip's parent is the chart
 * wrapper, which is often narrower than the box; measuring against the parent
@@ -2617,7 +2666,7 @@ const getBoundedPosition = ({ left, top, offsetLeft, offsetTop, box, wrapper, bo
 * Re-measures on every render, so a box whose content changes width between
 * two hovers is placed for its current size.
 *
-* @param props            - visx `Tooltip` props.
+* @param props            - `TooltipBox` props plus placement.
 * @param props.left       - Anchor x, in wrapper coordinates.
 * @param props.top        - Anchor y, in wrapper coordinates.
 * @param props.offsetLeft - Gap between the anchor and the box, horizontally.
@@ -2683,9 +2732,11 @@ const BoundedTooltip = ({ left = 0, top = 0, offsetLeft = DEFAULT_OFFSET, offset
 	]);
 	const x = position?.x ?? left + offsetLeft;
 	const y = position?.y ?? top + (placement === "below-axis" ? POINTER_HEIGHT : offsetTop);
-	const box = /* @__PURE__ */ jsxs(Tooltip, {
+	return /* @__PURE__ */ jsxs(TooltipBox, {
 		ref: nodeRef,
-		className: clsx(!unstyled && ["a8c-charts-tooltip-scope", base_tooltip_module_default.surface], className),
+		role: "presentation",
+		unstyled,
+		className,
 		style: {
 			position: "absolute",
 			left: 0,
@@ -2708,10 +2759,9 @@ const BoundedTooltip = ({ left = 0, top = 0, offsetLeft = DEFAULT_OFFSET, offset
 			}
 		}), children]
 	});
-	return unstyled ? box : /* @__PURE__ */ jsx(TooltipTheme, { children: box });
 };
 //#endregion
-//#region src/components/tooltip/xy-chart-tooltip.tsx
+//#region src/components/tooltip/private/xy-chart-tooltip-overlay.tsx
 const CROSSHAIR_STROKE_WIDTH = 1.5;
 const CROSSHAIR_PAINT_PROPERTIES = /* @__PURE__ */ new Set([
 	"stroke",
@@ -2813,21 +2863,35 @@ const XyChartTooltipContent = ({ tooltipContext, container, renderTooltip, rende
 	const crosshairStroke = theme?.gridStyles?.stroke ?? theme?.htmlLabel?.color ?? FALLBACK_COLOR;
 	const marginTop = margin?.top ?? 0;
 	const marginLeft = margin?.left ?? 0;
-	const TooltipComponent = detectBounds || tooltipPlacement !== "auto" ? BoundedTooltip : Tooltip;
 	const boxStyle = {
 		zIndex,
 		...style
 	};
-	const themesOwnBox = TooltipComponent === Tooltip && !tooltipProps.unstyled;
-	const box = /* @__PURE__ */ jsx(TooltipComponent, {
+	const { offsetLeft = 10, offsetTop = 10, unstyled, className, ...boxProps } = tooltipProps;
+	const anchorTop = tooltipPlacement === "below-axis" ? marginTop + innerHeight + (margin?.bottom ?? 0) : tooltipAnchorTop ?? tooltipTop;
+	const box = detectBounds || tooltipPlacement !== "auto" ? /* @__PURE__ */ jsx(BoundedTooltip, {
 		left: tooltipLeft,
-		top: tooltipPlacement === "below-axis" ? marginTop + innerHeight + (margin?.bottom ?? 0) : tooltipAnchorTop ?? tooltipTop,
+		top: anchorTop,
+		offsetLeft,
+		offsetTop,
+		unstyled,
+		className,
 		style: boxStyle,
-		applyPositionStyle: true,
-		...tooltipProps,
-		className: clsx(themesOwnBox && ["a8c-charts-scope", base_tooltip_module_default.surface], tooltipProps.className),
+		...boxProps,
 		...tooltipPlacement !== "auto" && { placement: tooltipPlacement },
 		children: tooltipContent
+	}) : /* @__PURE__ */ jsx(TooltipBox, {
+		role: "presentation",
+		unstyled,
+		className,
+		style: {
+			position: "absolute",
+			left: (tooltipLeft ?? 0) + offsetLeft,
+			top: (anchorTop ?? 0) + offsetTop,
+			...!unstyled && boxStyle
+		},
+		...boxProps,
+		children: tooltipContent
 	});
 	return /* @__PURE__ */ jsxs(Fragment$1, { children: [/* @__PURE__ */ jsxs("g", {
 		className: "visx-tooltip-overlay",
@@ -2855,7 +2919,7 @@ const XyChartTooltipContent = ({ tooltipContext, container, renderTooltip, rende
 			}),
 			glyphs
 		]
-	}), container && createPortal(themesOwnBox ? /* @__PURE__ */ jsx(TooltipTheme, { children: box }) : box, container)] });
+	}), container && createPortal(box, container)] });
 };
 /**
 * In-tree replacement for `@visx/xychart`'s `Tooltip`.
@@ -2880,7 +2944,7 @@ const XyChartTooltipContent = ({ tooltipContext, container, renderTooltip, rende
 * @param props - visx's `Tooltip` options. `scroll`, `debounce` and `resizeObserverPolyfill` are accepted and ignored.
 * @return An anchor in the SVG, plus the overlay and the tooltip box while the tooltip is open.
 */
-const XyChartTooltip = (props) => {
+const XyChartTooltipOverlay = (props) => {
 	const tooltipContext = useContext(TooltipContext);
 	const [container, setContainer] = useState(null);
 	const anchorRef = useCallback((node) => {
@@ -2893,8 +2957,8 @@ const XyChartTooltip = (props) => {
 	})] });
 };
 //#endregion
-//#region src/components/tooltip/accessible-tooltip.tsx
-const AccessibleTooltip = ({ renderTooltip, selectedIndex, tooltipRef, keyboardFocusedClassName, series = [], mode = "group", verticalCrosshairStyle, horizontalCrosshairStyle, ...props }) => {
+//#region src/components/tooltip/xy-chart-tooltip.tsx
+const XYChartTooltip = ({ renderTooltip, selectedIndex, tooltipRef, keyboardFocusedClassName, series = [], mode = "group", verticalCrosshairStyle, horizontalCrosshairStyle, ...props }) => {
 	const tooltipContext = useContext(TooltipContext);
 	const scopeElement = useChartScopeElement();
 	const crosshairStroke = useMemo(() => {
@@ -3000,7 +3064,7 @@ const AccessibleTooltip = ({ renderTooltip, selectedIndex, tooltipRef, keyboardF
 		keyboardFocusedClassName,
 		standaloneScopeClass
 	]);
-	return /* @__PURE__ */ jsx(XyChartTooltip, {
+	return /* @__PURE__ */ jsx(XyChartTooltipOverlay, {
 		...props,
 		verticalCrosshairStyle: {
 			...crosshairStroke,
@@ -3013,6 +3077,8 @@ const AccessibleTooltip = ({ renderTooltip, selectedIndex, tooltipRef, keyboardF
 		renderTooltip: focusableRenderTooltip
 	});
 };
+/** @deprecated Use `XYChartTooltip`. */
+const AccessibleTooltip = XYChartTooltip;
 const useKeyboardNavigation = ({ selectedIndex, setSelectedIndex, isNavigating, setIsNavigating, chartRef, totalPoints, onActivate, preventTooltipScroll = false, visibleSeriesKey }) => {
 	const getChartRoot = useCallback(() => chartRef.current?.closest("[role=\"grid\"]") ?? chartRef.current, [chartRef]);
 	const focusWithoutScrollIfNeeded = useCallback((element) => {
@@ -5018,7 +5084,7 @@ const LineChartInternal = forwardRef(({ data, chartId: providedChartId, width, h
 										] }, seriesData?.label || index);
 									})
 								}),
-								withTooltips && /* @__PURE__ */ jsx(AccessibleTooltip, {
+								withTooltips && /* @__PURE__ */ jsx(XYChartTooltip, {
 									detectBounds: true,
 									snapTooltipToDatumX: true,
 									tooltipPlacement,
@@ -5494,7 +5560,7 @@ const AreaChartInternal = forwardRef(({ data, chartId: providedChartId, width, h
 										children: seriesWithVisibility.map(renderSeries)
 									}), !allSeriesHidden && !stacked && seriesWithVisibility.map(renderSeries)]
 								}),
-								withTooltips && /* @__PURE__ */ jsxs(Fragment$1, { children: [/* @__PURE__ */ jsx(AccessibleTooltip, {
+								withTooltips && /* @__PURE__ */ jsxs(Fragment$1, { children: [/* @__PURE__ */ jsx(XYChartTooltip, {
 									detectBounds: true,
 									snapTooltipToDatumX: true,
 									snapTooltipToDatumY: !stacked,
@@ -6105,6 +6171,7 @@ const ComparisonBars = ({ comparisonEntries, primaryKeys, groupPadding, horizont
 				widthFactor
 			});
 			rects.push(/* @__PURE__ */ jsx("rect", {
+				className: "bar-chart__comparison-bar",
 				x: rect.x,
 				y: rect.y,
 				width: rect.width,
@@ -6520,7 +6587,7 @@ const BarChartInternal = ({ data, chartId: providedChartId, width, height, class
 		const patternId = getPatternId(chartId, index);
 		return `
 			.visx-bar[fill="url(#${patternId})"],
-			.bar-chart__comparison-bars rect[fill="url(#${patternId})"] {
+			.bar-chart__comparison-bar[fill="url(#${patternId})"] {
 				stroke: ${color};
 				stroke-width: 1;
 				}
@@ -6702,15 +6769,15 @@ const BarChartInternal = ({ data, chartId: providedChartId, width, height, class
 								}),
 								!allSeriesHidden && /* @__PURE__ */ jsx(WholeNumberTicks, {
 									...wholeNumberTicksProps,
-									children: (valueTicks) => /* @__PURE__ */ jsxs(Fragment$1, { children: [/* @__PURE__ */ jsx(Axis, {
+									children: (valueTicks) => /* @__PURE__ */ jsxs(Fragment$1, { children: [chartOptions.axis.x.display !== false && /* @__PURE__ */ jsx(Axis, {
 										...chartOptions.axis.x,
 										...horizontal && valueTicks ? { tickValues: valueTicks } : {}
-									}), /* @__PURE__ */ jsx(Axis, {
+									}), chartOptions.axis.y.display !== false && /* @__PURE__ */ jsx(Axis, {
 										...chartOptions.axis.y,
 										...!horizontal && valueTicks ? { tickValues: valueTicks } : {}
 									})] })
 								}),
-								withTooltips && /* @__PURE__ */ jsx(AccessibleTooltip, {
+								withTooltips && /* @__PURE__ */ jsx(XYChartTooltip, {
 									tooltipPlacement,
 									tooltipAnchorTop,
 									style: tooltipStyle,
@@ -7237,7 +7304,10 @@ const ConversionFunnelChartInternal = ({ mainRate, changeIndicator, steps, loadi
 				left: tooltipLeft,
 				className: standaloneScopeClass,
 				style: tooltipStyle,
-				children: tooltipContent
+				children: /* @__PURE__ */ jsx("div", {
+					role: "tooltip",
+					children: tooltipContent
+				})
 			});
 		})()]
 	});
@@ -7624,30 +7694,44 @@ var heatmap_chart_module_default = {
 //#region src/charts/heatmap-chart/private/use-heatmap-colors.ts
 const isPresent = (value) => value !== null && value !== void 0 && !isNaN(value);
 /**
-* Get the min and max values from heatmap data, ignoring null/NaN. Summary
-* columns stay out: a roll-up on the scale would flatten every real cell.
+* Get the min and max values from heatmap data, ignoring null/NaN and the zeros
+* `isEmptyValue` paints as empty. Summary columns stay out: a roll-up on the
+* scale would flatten every real cell.
 * @param data - The heatmap columns
 * @return Tuple of [min, max] values
 */
 const getValueExtent = (data) => {
 	let min = Infinity;
 	let max = -Infinity;
+	let hasZero = false;
 	for (const column of data) {
 		if (column.summary) continue;
 		for (const cell of column.data) {
 			if (!isPresent(cell.value)) continue;
+			if (cell.value === 0) {
+				hasZero = true;
+				continue;
+			}
 			if (cell.value < min) min = cell.value;
 			if (cell.value > max) max = cell.value;
 		}
 	}
+	if (hasZero && min < 0) max = Math.max(max, 0);
 	if (min === Infinity) return [0, 0];
 	return [min, max];
 };
 /**
+* Whether a value paints as an empty cell: a zero in data with no negatives
+* counts nothing, so it must not look like the lowest step of activity.
+*
+* @param value  - The cell value
+* @param extent - The extent from `getValueExtent`
+* @return True when the cell takes the empty-cell color
+*/
+const isEmptyValue = (value, extent) => value === 0 && extent[0] >= 0;
+/**
 * Normalize a value to 0–1 within the extent. A flat extent (min === max)
-* maps to 1 — every cell is equally the "highest" — except an all-zero
-* extent, which maps to 0 so a no-activity grid renders at the scale's
-* bottom instead of full intensity.
+* maps to 1, since every cell is equally the "highest".
 *
 * @param value  - The value to normalize
 * @param extent - Tuple of [min, max] values for the normalization range
@@ -7655,9 +7739,40 @@ const getValueExtent = (data) => {
 */
 const getNormalizedValue = (value, extent) => {
 	const [min, max] = extent;
-	if (min === max) return max === 0 ? 0 : 1;
+	if (min === max) return 1;
 	return Math.min(1, Math.max(0, (value - min) / (max - min)));
 };
+const STEPS = 200;
+const firstMeeting = (from, to, meets) => {
+	for (let step = 0; step <= STEPS; step++) {
+		const color = mixHexColors(from, to, step / STEPS);
+		if (meets(color)) return color;
+	}
+	return null;
+};
+/**
+* The two ends of the heatmap fill scale: 3:1 against the background and the empty cell at the
+* low end, toward 9:1 against the background at the high end.
+*
+* @param primary    - The resolved primary color, as six-digit hex.
+* @param background - The resolved chart background, as six-digit hex.
+* @param emptyCell  - The resolved empty-cell color, as six-digit hex, when it is opaque.
+* @return The scale ends, as six-digit hex.
+*/
+const getHeatmapScale = (primary, background, emptyCell) => {
+	const primaryStandsOut = contrastRatio(primary, background) >= 3;
+	const extreme = (primaryStandsOut ? relativeLuminance(primary) > relativeLuminance(background) : contrastRatio("#ffffff", background) > contrastRatio("#000000", background)) ? "#ffffff" : "#000000";
+	const lowAgainst = (references) => {
+		const meets = (color) => references.every((reference) => contrastRatio(color, reference) >= 3);
+		return (primaryStandsOut ? firstMeeting(background, primary, meets) : null) ?? firstMeeting(primary, extreme, meets);
+	};
+	const high = firstMeeting(primary, extreme, (color) => contrastRatio(color, background) >= 9) ?? extreme;
+	const againstEmptyCell = emptyCell ? lowAgainst([background, emptyCell]) : null;
+	return {
+		low: (againstEmptyCell && contrastRatio(againstEmptyCell, background) <= contrastRatio(high, background) ? againstEmptyCell : lowAgainst([background])) ?? extreme,
+		high
+	};
+};
 //#endregion
 //#region src/charts/heatmap-chart/private/heatmap-context.ts
 /** Shared by the chart and legend without importing back from `heatmap-chart.tsx`. */
@@ -7668,7 +7783,7 @@ const HeatmapLegend = ({ steps = 5, variant = "swatches", lessLabel, moreLabel }
 	const context = useContext(HeatmapContext);
 	const { legend } = useGlobalChartsTheme();
 	if (!context) return null;
-	const { primaryColorHex } = context;
+	const { fillVars } = context;
 	const labelStyle = legend.labelStyles;
 	return /* @__PURE__ */ jsxs(Stack, {
 		direction: "row",
@@ -7691,7 +7806,7 @@ const HeatmapLegend = ({ steps = 5, variant = "swatches", lessLabel, moreLabel }
 					return /* @__PURE__ */ jsx("span", {
 						className: heatmap_chart_module_default["heatmap-chart__legend-swatch"],
 						style: {
-							"--a8c-charts-color-heatmap-primary": primaryColorHex,
+							...fillVars,
 							"--a8c-charts-heatmap-cell-intensity": intensity
 						}
 					}, index);
@@ -7895,7 +8010,6 @@ const stepCalendarCell = (grid, blocks, from, key) => {
 };
 //#endregion
 //#region src/charts/heatmap-chart/heatmap-chart.tsx
-const CELL_MIX_FLOOR = .15;
 const CELL_VALUE_MODIFIER = {
 	label: void 0,
 	"label-inverse": heatmap_chart_module_default["heatmap-chart__cell-value--inverse"],
@@ -7929,13 +8043,23 @@ const HeatmapChartInternal = ({ data, chartId: providedChartId, width = 0, heigh
 		index: 0,
 		overrideColor: primaryColor
 	});
-	const chartBackgroundHex = normalizeColorToHex(CATALOG_POINTERS.background, scopeElement, resolveCssVariable);
+	const resolveAtScope = createCssVariableResolver(scopeElement);
+	const chartBackgroundHex = resolveOpaqueHex(CATALOG_POINTERS.background, resolveAtScope) ?? "#ffffff";
+	const emptyCellHex = resolveOpaqueHex(CATALOG_POINTERS.track, resolveAtScope);
 	const primaryHex = normalizeColorToHex(primaryColorHex);
-	const cellMix = isValidHexColor(primaryHex) && isValidHexColor(chartBackgroundHex) ? {
-		primary: hexToRgb(primaryHex),
-		background: hexToRgb(chartBackgroundHex)
-	} : null;
-	const cellTextColor = (intensity) => cellMix ? pickLabelTextColorForFill(blendRgb(cellMix.primary, cellMix.background, CELL_MIX_FLOOR + .85 * intensity), labelRoles, "label") : "label";
+	const scale = useMemo(() => isValidHexColor(primaryHex) ? getHeatmapScale(primaryHex, chartBackgroundHex, emptyCellHex) : null, [
+		primaryHex,
+		chartBackgroundHex,
+		emptyCellHex
+	]);
+	const fillVars = useMemo(() => ({
+		"--a8c-charts-color-heatmap-primary": primaryColorHex,
+		...scale && {
+			"--a8c-charts-color-heatmap-low": scale.low,
+			"--a8c-charts-color-heatmap-high": scale.high
+		}
+	}), [primaryColorHex, scale]);
+	const cellTextColor = (intensity) => scale ? pickLabelTextColorForFill(blendRgb(hexToRgb(scale.high), hexToRgb(scale.low), intensity), labelRoles, "label") : "label";
 	useIsomorphicLayoutEffect(() => {
 		if (!containerRef.current) return;
 		const next = resolveLabelRoles(createCssVariableResolver(containerRef.current));
@@ -7949,8 +8073,8 @@ const HeatmapChartInternal = ({ data, chartId: providedChartId, width = 0, heigh
 	const extent = useMemo(() => getValueExtent(data), [data]);
 	const heatmapContext = useMemo(() => ({
 		extent,
-		primaryColorHex
-	}), [extent, primaryColorHex]);
+		fillVars
+	}), [extent, fillVars]);
 	const columns = data.length;
 	const rows = Math.max(0, ...data.map((column) => column.data.length));
 	const groupLayout = useMemo(() => resolveColumnGroups(columnGroups, columns, 2), [columnGroups, columns]);
@@ -8101,9 +8225,10 @@ const HeatmapChartInternal = ({ data, chartId: providedChartId, width = 0, heigh
 	const firstDataRow = hasColumnLabels ? 2 : 1;
 	const dataTrack = (column) => column.summary ? "minmax(auto, max-content)" : columnTrack;
 	const gapTrack = compact ? `minmax(${groupGap}px, 1fr)` : `${groupGap}px`;
+	const columnTracks = data.map((column, columnIndex) => groupLayout.columns[columnIndex].gapBefore ? `${gapTrack} ${dataTrack(column)}` : dataTrack(column)).join(" ");
 	const gridStyle = {
-		"--a8c-charts-color-heatmap-primary": primaryColorHex,
-		gridTemplateColumns: `auto ${data.map((column, columnIndex) => groupLayout.columns[columnIndex].gapBefore ? `${gapTrack} ${dataTrack(column)}` : dataTrack(column)).join(" ")}`,
+		...fillVars,
+		gridTemplateColumns: `auto ${columnTracks}`,
 		gridTemplateRows: `${hasColumnLabels ? "auto " : ""}repeat(${rows}, ${rowTrack})${hasGroups ? " auto" : ""}`
 	};
 	if (compact) {
@@ -8203,7 +8328,7 @@ const HeatmapChartInternal = ({ data, chartId: providedChartId, width = 0, heigh
 									}, `cell-${columnIndex}-${rowIndex}`);
 									const value = cell?.value ?? null;
 									const present = isPresent(value);
-									const filled = present && !column.summary;
+									const filled = present && !column.summary && !isEmptyValue(value, extent);
 									const normalized = filled ? getNormalizedValue(value, extent) : 0;
 									const info = buildTooltipData(columnIndex, rowIndex);
 									const accessibleLabel = `${cellName(info)}: ${info.value === null ? __("No data", "jetpack-charts") : formatNumber(info.value)}`;
@@ -11488,18 +11613,13 @@ var pie_chart_module_default = {
 //#region src/charts/pie-chart/pie-chart.tsx
 /**
 * Default tooltip renderer for pie charts.
-* Renders a BaseTooltip with the hovered segment's data.
+* Renders the default `label: value` tooltip content for the hovered segment.
 *
 * @param {PieChartRenderTooltipParams} params - The tooltip parameters containing the hovered data point
 * @return {ReactNode} The rendered tooltip content
 */
 const renderDefaultPieTooltip = ({ tooltipData }) => {
-	return /* @__PURE__ */ jsx(BaseTooltip, {
-		data: tooltipData,
-		top: 0,
-		left: 0,
-		renderContainer: false
-	});
+	return /* @__PURE__ */ jsx(LabelValueContent, { data: tooltipData });
 };
 /**
 * Validates the pie chart data
@@ -11785,18 +11905,13 @@ var pie_semi_circle_chart_module_default = {
 //#region src/charts/pie-semi-circle-chart/pie-semi-circle-chart.tsx
 /**
 * Default tooltip renderer for semi-circle pie charts.
-* Renders a BaseTooltip with the hovered segment's data.
+* Renders the default `label: value` tooltip content for the hovered segment.
 *
 * @param {PieSemiCircleChartRenderTooltipParams} params - The tooltip parameters containing the hovered data point
 * @return {ReactNode} The rendered tooltip content
 */
 const renderDefaultPieSemiCircleTooltip = ({ tooltipData }) => {
-	return /* @__PURE__ */ jsx(BaseTooltip, {
-		data: tooltipData,
-		top: 0,
-		left: 0,
-		renderContainer: false
-	});
+	return /* @__PURE__ */ jsx(LabelValueContent, { data: tooltipData });
 };
 const PAD_ANGLE = .03;
 const DEFAULT_WIDTH$1 = 400;
@@ -12236,6 +12351,6 @@ function TrendIndicator({ direction, value, className, style, showIcon = true })
 	});
 }
 //#endregion
-export { AccessibleTooltip, AreaChartResponsive as AreaChart, AreaChart as AreaChartUnresponsive, BarChartResponsive as BarChart, BarChart as BarChartUnresponsive, BarListChartResponsive as BarListChart, BarListChart as BarListChartUnresponsive, BaseTooltip, ConversionFunnelChartWithProvider as ConversionFunnelChart, GeoChartResponsive as GeoChart, GeoChartWithProvider as GeoChartUnresponsive, GlobalChartsContext, GlobalChartsProvider, GlobalChartsProvider as ThemeProvider, GoogleDataTableColumnRoleType, HeatmapChartResponsive as HeatmapChart, HeatmapChart as HeatmapChartUnresponsive, LeaderboardChartResponsive as LeaderboardChart, LeaderboardChart as LeaderboardChartUnresponsive, Legend, LineChartResponsive as LineChart, LineChart as LineChartUnresponsive, PieChartResponsive as PieChart, PieChart as PieChartUnresponsive, PieSemiCircleChartResponsive as PieSemiCircleChart, PieSemiCircleChart as PieSemiCircleChartUnresponsive, Sparkline, SparklineUnresponsive, TrendIndicator, buildCalendarHeatmapData, buildMonthCalendarHeatmapData, defaultTheme, formatMetricValue, formatPercentage, getBucketInfo, getColorDistance, hexToRgba, isValidHexColor, lightenHexColor, mergeThemes, mixHexColors, normalizeColorToHex, parseAsLocalDate, parseHslString, prefersLightText, relativeLuminance, resolveCssVariable, useCalendarHeatmapData, useChartFormatting, useChartLegendItems, useChartRegistration, useChartScopeElement, useGlobalChartsContext, useGlobalChartsTheme, useLeaderboardLegendItems, useMonthCalendarHeatmapData, validateHexColor };
+export { AccessibleTooltip, AreaChartResponsive as AreaChart, AreaChart as AreaChartUnresponsive, BarChartResponsive as BarChart, BarChart as BarChartUnresponsive, BarListChartResponsive as BarListChart, BarListChart as BarListChartUnresponsive, BaseTooltip, ConversionFunnelChartWithProvider as ConversionFunnelChart, GeoChartResponsive as GeoChart, GeoChartWithProvider as GeoChartUnresponsive, GlobalChartsContext, GlobalChartsProvider, GlobalChartsProvider as ThemeProvider, GoogleDataTableColumnRoleType, HeatmapChartResponsive as HeatmapChart, HeatmapChart as HeatmapChartUnresponsive, LeaderboardChartResponsive as LeaderboardChart, LeaderboardChart as LeaderboardChartUnresponsive, Legend, LineChartResponsive as LineChart, LineChart as LineChartUnresponsive, PieChartResponsive as PieChart, PieChart as PieChartUnresponsive, PieSemiCircleChartResponsive as PieSemiCircleChart, PieSemiCircleChart as PieSemiCircleChartUnresponsive, Sparkline, SparklineUnresponsive, TooltipBox, TrendIndicator, XYChartTooltip, buildCalendarHeatmapData, buildMonthCalendarHeatmapData, defaultTheme, formatMetricValue, formatPercentage, getBucketInfo, getColorDistance, hexToRgba, isValidHexColor, lightenHexColor, mergeThemes, mixHexColors, normalizeColorToHex, parseAsLocalDate, parseHslString, prefersLightText, relativeLuminance, resolveCssVariable, useCalendarHeatmapData, useChartFormatting, useChartLegendItems, useChartRegistration, useChartScopeElement, useGlobalChartsContext, useGlobalChartsTheme, useLeaderboardLegendItems, useMonthCalendarHeatmapData, validateHexColor };
 
 //# sourceMappingURL=index.js.map