@automattic/charts 4.6.0 → 4.8.0

package/src/components/trend-indicator/trend-indicator.tsx

@@ -2,6 +2,7 @@ import clsx from 'clsx';
 import { useStandaloneScopeClass } from '../../providers/chart-scope';
 import styles from './trend-indicator.module.scss';
 import type { TrendIndicatorProps, TrendDirection } from './types';
+import type { JSX } from 'react';
 
 const DIRECTION_LABELS: Record< TrendDirection, string > = {
 	up: 'Increase',

package/src/hooks/index.ts

@@ -9,3 +9,4 @@ export { useZeroValueDisplay } from './use-zero-value-display';
 export { useDataWithPercentages } from './use-data-with-percentages';
 export { useLegendVisibilityData } from './use-legend-visibility-data';
 export { usePrefersReducedMotion } from './use-prefers-reduced-motion';
+export { useIsomorphicLayoutEffect } from './use-isomorphic-layout-effect';

package/src/hooks/test/use-chart-margin.test.tsx

@@ -282,16 +282,20 @@ describe( 'useChartMargin', () => {
 			expect( result.current.left ).toBe( 60 );
 		} );
 
-		it( 'reserves nothing for a hidden x axis', () => {
+		it.each( [ 'bottom', 'top' ] )( 'reserves nothing for a hidden %s x axis', orientation => {
 			mockGetEdgeTickWidths.mockReturnValue( { first: 120, last: 60 } );
+			const largeLabels = { axisLabel: { fontSize: 16 }, tickLength: 10 } as unknown as never;
+			const theme = {
+				...baseTheme,
+				axisStyles: { ...baseTheme.axisStyles, x: { top: largeLabels, bottom: largeLabels } },
+			} as XYChartTheme;
 
 			const { result } = renderHook( () =>
-				useChartMargin( 300, datedXOptions( { display: false } ), data, baseTheme )
+				useChartMargin( 300, datedXOptions( { display: false, orientation } ), data, theme )
 			);
 
 			expect( mockGetEdgeTickWidths ).not.toHaveBeenCalled();
-			expect( result.current.right ).toBe( 20 );
-			expect( result.current.left ).toBe( 51 );
+			expect( result.current ).toEqual( { top: 10, right: 20, bottom: 10, left: 51 } );
 		} );
 	} );
 

package/src/hooks/test/use-xychart-theme.test.tsx

@@ -1,4 +1,5 @@
 import { renderHook } from '@testing-library/react';
+import { CATALOG_POINTERS } from '../../providers/chart-context/private/catalog-pointers';
 import { ChartScopeContext } from '../../providers/chart-scope';
 import { useXYChartTheme } from '../use-xychart-theme';
 import type { ReactNode } from 'react';
@@ -48,8 +49,7 @@ describe( 'useXYChartTheme', () => {
 		document.body.removeChild( scope );
 	} );
 
-	// The one label color that has to arrive resolved: visx paints it on a portal container appended to `document.body`, where the catalog is not declared, and concatenates it into `box-shadow: 0 1px 2px ${color}55`, which a `var()` chain would invalidate.
-	it( 'resolves the tooltip label color while the tick labels keep the pointer', () => {
+	it( 'hands visx the label pointer for the HTML label, even with an override in scope', () => {
 		const scope = document.createElement( 'div' );
 		scope.style.setProperty( '--a8c-charts-color-label-axis', '#0000ff' );
 		document.body.appendChild( scope );
@@ -60,7 +60,7 @@ describe( 'useXYChartTheme', () => {
 
 		const { result } = renderHook( () => useXYChartTheme( [] ), { wrapper } );
 
-		expect( result.current.htmlLabel.color ).toBe( '#0000ff' );
+		expect( result.current.htmlLabel.color ).toBe( CATALOG_POINTERS.labelAxis );
 		expect( result.current.svgLabelSmall.fill ).toBe(
 			'var(--a8c-charts-color-label-axis, #1e1e1e)'
 		);

package/src/hooks/use-chart-margin.tsx

@@ -27,10 +27,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
@@ -168,23 +168,24 @@ export const useChartMargin = (
 			}
 		}
 
-		// Dynamically compute X-axis margin (bottom by default, or top if orientation is 'top').
-		// This mirrors Y-axis behavior where margin is based on label size and tick length,
-		// but keeps the padding minimal so consumers can control container spacing themselves.
-		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 );
-		}
-
-		// An X-axis label is centered on its tick, so the ones at either end of the
-		// scale hang half their width outside the plot area and clip at the SVG edge.
+		// A hidden x axis reserves nothing either, whichever side it sits on.
 		if ( options.axis?.x?.display !== false ) {
+			// Dynamically compute X-axis margin (bottom by default, or top if orientation is 'top').
+			// This mirrors Y-axis behavior where margin is based on label size and tick length,
+			// but keeps the padding minimal so consumers can control container spacing themselves.
+			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 );
+			}
+
+			// An X-axis label is centered on its tick, so the ones at either end of the
+			// scale hang half their width outside the plot area and clip at the SVG edge.
 			const { first, last } = getEdgeTickWidths(
 				options.axis?.x?.tickValues ?? [],
 				options.axis?.x?.tickFormat,
@@ -193,6 +194,8 @@ export const useChartMargin = (
 
 			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;

package/src/hooks/use-isomorphic-layout-effect.ts

@@ -0,0 +1,5 @@
+import { useEffect, useLayoutEffect } from 'react';
+
+// useLayoutEffect on the client, useEffect on the server to avoid React's SSR warning.
+export const useIsomorphicLayoutEffect =
+	typeof window !== 'undefined' ? useLayoutEffect : useEffect;

package/src/hooks/use-xychart-theme.ts

@@ -3,7 +3,7 @@ import { useMemo } from 'react';
 import { useGlobalChartsTheme } from '../providers';
 import { CATALOG_POINTERS } from '../providers/chart-context/private/catalog-pointers';
 import { useChartScopeElement } from '../providers/chart-scope';
-import { createCssVariableResolver, normalizeColorToHex } from '../utils';
+import { createCssVariableResolver } from '../utils';
 import type { SeriesData } from '../types';
 
 export const useXYChartTheme = ( data: SeriesData[] ) => {
@@ -18,9 +18,9 @@ export const useXYChartTheme = ( data: SeriesData[] ) => {
 	);
 
 	return useMemo( () => {
-		// Only what is read as a string is resolved: the palette, `backgroundColor`, `htmlLabel.color`.
+		// Only what is read as a string is resolved: the palette and `backgroundColor`.
 		// At the chart's scope element, never :root, so an override inside the provider tree is seen.
-		// One resolver for all three, so they share a single getComputedStyle call.
+		// One resolver for both, so they share a single getComputedStyle call.
 		const resolve = createCssVariableResolver( scopeElement );
 		const resolveColor = ( value?: string ): string | undefined =>
 			value ? ( resolve( value ) ?? value ) : value;
@@ -33,14 +33,6 @@ export const useXYChartTheme = ( data: SeriesData[] ) => {
 			.map( color => resolveColor( color ) )
 			.filter( ( color ): color is string => Boolean( color ) && ! color.includes( 'var(' ) );
 
-		// The tooltip is painted in a portal outside the scope, and visx concatenates this color into a `box-shadow` where a chain cannot take a suffix; see TOKENS.md#the-svg-bridge. Passing it explicitly leaves `svgLabelSmall.fill`, which visx derives it from, a chain for the SVG tick labels.
-		// Hex specifically: that concatenation appends `55`, which only yields a color
-		// after a 6-digit hex. An `rgb()` computed value takes the whole shadow down.
-		const resolvedLabelColor = resolveColor( CATALOG_POINTERS.labelAxis );
-		const htmlLabelColor = resolvedLabelColor
-			? normalizeColorToHex( resolvedLabelColor ) || resolvedLabelColor
-			: resolvedLabelColor;
-
 		// visx's fallbacks for whichever axis or grid style object it is not given. All four are
 		// supplied, so these reach nothing; they stay because the config type requires them.
 		return buildChartTheme( {
@@ -49,7 +41,7 @@ export const useXYChartTheme = ( data: SeriesData[] ) => {
 			gridColorDark: '',
 			colors: paletteColors,
 			backgroundColor: resolveColor( CATALOG_POINTERS.background ),
-			htmlLabel: htmlLabelColor ? { color: htmlLabelColor } : undefined,
+			htmlLabel: { color: CATALOG_POINTERS.labelAxis },
 			gridStyles: { ...theme.gridStyles, stroke: CATALOG_POINTERS.grid },
 			xAxisLineStyles: { ...theme.xAxisLineStyles, stroke: CATALOG_POINTERS.axisX },
 			xTickLineStyles: { ...theme.xTickLineStyles, stroke: CATALOG_POINTERS.tickX },

package/src/index.ts

@@ -21,7 +21,7 @@ export { PieSemiCircleChart, PieSemiCircleChartUnresponsive } from './charts/pie
 export { Sparkline, SparklineUnresponsive } from './charts/sparkline';
 
 // Components
-export { BaseTooltip } from './components/tooltip';
+export { BaseTooltip, TooltipBox } from './components/tooltip';
 export { Legend, useChartLegendItems } from './components/legend';
 export { TrendIndicator } from './components/trend-indicator';
 
@@ -97,8 +97,13 @@ export type { LineStyles, GridStyles, EventHandlerParams } from '@visx/xychart';
 export { useLeaderboardLegendItems } from './charts/leaderboard-chart/hooks';
 
 // Previously available via '@automattic/charts/tooltip', '@automattic/charts/legend'
-export { AccessibleTooltip } from './components/tooltip';
-export type { BaseTooltipProps, TooltipData, TooltipProps } from './components/tooltip';
+export { AccessibleTooltip, XYChartTooltip } from './components/tooltip';
+export type {
+	BaseTooltipProps,
+	TooltipBoxProps,
+	TooltipData,
+	TooltipProps,
+} from './components/tooltip';
 export type { LegendProps, BaseLegendProps, ChartLegendOptions } from './components/legend';
 
 // Previously available via '@automattic/charts/bar-chart', '@automattic/charts/line-chart', etc.

package/src/providers/chart-context/global-charts-provider.tsx

@@ -1,4 +1,3 @@
-import { color as d3Color } from '@visx/vendor/d3-color';
 import {
 	createContext,
 	useCallback,
@@ -14,6 +13,7 @@ import {
 import '../../styles/chart-scope.scss';
 import { CHART_SCOPE_CLASS } from '../../styles/chart-scope-class';
 import {
+	createCssVariableResolver,
 	getItemShapeStyles,
 	getSeriesBarStyles,
 	getSeriesLineStyles,
@@ -32,6 +32,7 @@ import {
 	LABEL_INVERSE_FALLBACK,
 } from './private/catalog-pointers';
 import { createPaletteGenerator } from './private/palette-generator';
+import { resolveOpaqueHex } from './private/resolve-opaque-hex';
 import { SERIES_PALETTE_POINTERS, SERIES_SLOT_1_FALLBACK } from './private/series-palette';
 import { defaultTheme } from './themes';
 import type { GlobalChartsContextValue, ChartRegistration } from './types';
@@ -45,17 +46,6 @@ interface ColorCache {
 	colorAt: ( index: number ) => string;
 }
 
-// A see-through color (transparent, or any alpha below 1) says nothing about what it will look like
-// over the chart, so it resolves to null rather than let its RGB leak into the palette.
-const resolveOpaqueHex = ( pointer: string, element: HTMLElement | null ): string | null => {
-	const raw = resolveCssVariable( pointer, element );
-	if ( ! raw || d3Color( 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 ];
 
 export const GlobalChartsContext = createContext< GlobalChartsContextValue | null >( null );
@@ -143,11 +133,12 @@ export const GlobalChartsProvider: FC< GlobalChartsProviderProps > = ( {
 			}
 		}
 
+		const resolveAtWrapper = createCssVariableResolver( wrapperRef.current );
 		const backgroundHex =
-			resolveOpaqueHex( CATALOG_POINTERS.background, wrapperRef.current ) ?? BACKGROUND_FALLBACK;
+			resolveOpaqueHex( CATALOG_POINTERS.background, resolveAtWrapper ) ?? BACKGROUND_FALLBACK;
 		// The two roles pie labels choose between on a fill; one left see-through is never painted there.
 		const labelColors = [ CATALOG_POINTERS.label, CATALOG_POINTERS.labelInverse ]
-			.map( pointer => resolveOpaqueHex( pointer, wrapperRef.current ) )
+			.map( pointer => resolveOpaqueHex( pointer, resolveAtWrapper ) )
 			.filter( ( hex ): hex is string => hex !== null );
 
 		setColorCache( {

package/src/providers/chart-context/hooks/use-default-hidden-series.ts

@@ -1,9 +1,7 @@
-import { useEffect, useLayoutEffect, useMemo, useRef } from 'react';
+import { useMemo, useRef } from 'react';
+import { useIsomorphicLayoutEffect } from '../../../hooks';
 import { useGlobalChartsContext } from './use-global-charts-context';
 
-// Hide seeded series before paint without triggering React's SSR warning.
-const useIsomorphicLayoutEffect = typeof window !== 'undefined' ? useLayoutEffect : useEffect;
-
 /**
  * Seeds a chart's hidden series once per chart ID, the first time the provider
  * sees that ID.
@@ -39,7 +37,7 @@ export const useDefaultHiddenSeries = (
 	// getHiddenSeries hands out a fresh copy per call, so hold the set still between
 	// visibility changes. Charts derive their rendered series from it, and a new
 	// identity every render invalidates every memo downstream — including the one
-	// the accessible tooltip watches, which closes a tooltip mid-navigation.
+	// `XYChartTooltip` watches, which closes a tooltip mid-navigation.
 	return useMemo(
 		() => ( shouldUseDefaults ? new Set( labelsRef.current ) : getHiddenSeries( chartId ) ),
 		[ shouldUseDefaults, getHiddenSeries, chartId ]

package/src/providers/chart-context/private/catalog-pointers.ts

@@ -24,6 +24,7 @@ export 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)',
 	// Only for `renderMainMetric`, which hands a consumer's own markup something to paint with.
 	trendUp: 'var(--a8c-charts-color-trend-up, #008030)',
 	trendDown: 'var(--a8c-charts-color-trend-down, #cc1818)',

package/src/providers/chart-context/private/perceptual-color.ts

@@ -2,6 +2,9 @@ import { relativeLuminance, validateHexColor } from '../../../utils';
 
 export type Lab = readonly [ number, number, number ];
 
+/** sRGB channels from 0 to 255, left unrounded. */
+export type Rgb = readonly [ number, number, number ];
+
 /** A color as seen in normal vision, then under deuteranopia and protanopia. */
 export type ColorViews = readonly [ Lab, Lab, Lab ];
 
@@ -23,13 +26,22 @@ const toLinear = ( channel: number ): number =>
 const fromLinear = ( channel: number ): number =>
 	channel <= 0.0031308 ? 12.92 * channel : 1.055 * Math.pow( channel, 1 / 2.4 ) - 0.055;
 
-const hexToLinear = ( hex: string ): number[] => {
+/**
+ * The sRGB channels of a hex color.
+ *
+ * @param  hex - A six-digit hex color.
+ * @return Channels from 0 to 255.
+ * @throws {Error} if the hex string is malformed
+ */
+export const hexToRgb = ( hex: string ): Rgb => {
 	validateHexColor( hex );
-	return [ 1, 3, 5 ].map( start =>
-		toLinear( parseInt( hex.slice( start, start + 2 ), 16 ) / 255 )
-	);
+	const [ r, g, b ] = [ 1, 3, 5 ].map( start => parseInt( hex.slice( start, start + 2 ), 16 ) );
+	return [ r, g, b ];
 };
 
+const hexToLinear = ( hex: string ): number[] =>
+	hexToRgb( hex ).map( channel => toLinear( channel / 255 ) );
+
 const linearToHex = ( linear: number[] ): string =>
 	'#' +
 	linear
@@ -197,6 +209,35 @@ export const hexToOklch = ( hex: string ): { chroma: number; hue: number } => {
 	};
 };
 
+/**
+ * `foreground` over `background` at `weight`, left unrounded as CSS `color-mix` and alpha compositing leave it.
+ *
+ * A mix rounded to hex can land on the other side of a contrast threshold from the fill the browser paints.
+ *
+ * @param foreground - The color weighted by `weight`.
+ * @param background - The color it is mixed over.
+ * @param weight     - Share of `foreground`, from 0 to 1.
+ * @return The mixed channels.
+ */
+export const blendRgb = ( foreground: Rgb, background: Rgb, weight: number ): Rgb => {
+	const share = Math.min( 1, Math.max( 0, weight ) );
+	const [ r, g, b ] = foreground.map(
+		( channel, i ) => background[ i ] + ( channel - background[ i ] ) * share
+	);
+	return [ r, g, b ];
+};
+
+/**
+ * WCAG relative luminance of unrounded sRGB channels.
+ *
+ * @param rgb - Channels from 0 to 255.
+ * @return Relative luminance from 0 to 1.
+ */
+export const rgbLuminance = ( rgb: Rgb ): number => {
+	const [ r, g, b ] = rgb.map( channel => toLinear( channel / 255 ) );
+	return 0.2126 * r + 0.7152 * g + 0.0722 * b;
+};
+
 /**
  * WCAG contrast ratio between two relative luminances.
  *

package/src/providers/chart-context/private/resolve-opaque-hex.ts

@@ -0,0 +1,16 @@
+import { color as d3Color } from '@visx/vendor/d3-color';
+import { isValidHexColor, normalizeColorToHex } from '../../../utils/color-utils';
+
+// A see-through color (transparent, or any alpha below 1) says nothing about what it will look like
+// over the chart, so it resolves to null rather than let its RGB stand in for the color.
+export const resolveOpaqueHex = (
+	pointer: string,
+	resolve: ( value: string ) => string | null
+): string | null => {
+	const raw = resolve( pointer );
+	if ( ! raw || d3Color( raw )?.opacity !== 1 ) {
+		return null;
+	}
+	const hex = normalizeColorToHex( raw );
+	return isValidHexColor( hex ) ? hex : null;
+};

package/src/providers/chart-context/test/perceptual-color.test.ts

@@ -3,6 +3,9 @@ import {
 	deltaE2000,
 	hexToOklch,
 	hexToViews,
+	blendRgb,
+	hexToRgb,
+	rgbLuminance,
 	oklchToHex,
 	viewDistance,
 } from '../private/perceptual-color';
@@ -73,3 +76,31 @@ describe( 'contrastRatio', () => {
 		expect( contrastRatio( '#3858e9', '#3858e9' ) ).toBe( 1 );
 	} );
 } );
+
+describe( 'hexToRgb', () => {
+	it( 'reads each channel', () => {
+		expect( hexToRgb( '#3858e9' ) ).toEqual( [ 56, 88, 233 ] );
+	} );
+} );
+
+describe( 'blendRgb', () => {
+	const blue = hexToRgb( '#3858e9' );
+	const white = hexToRgb( '#ffffff' );
+
+	it( 'matches each endpoint at full weight', () => {
+		expect( blendRgb( blue, white, 1 ) ).toEqual( [ 56, 88, 233 ] );
+		expect( blendRgb( blue, white, 0 ) ).toEqual( [ 255, 255, 255 ] );
+	} );
+
+	it( 'does not round the mix to a hex channel', () => {
+		expect( blendRgb( hexToRgb( '#000000' ), white, 0.5 ) ).toEqual( [ 127.5, 127.5, 127.5 ] );
+	} );
+} );
+
+describe( 'rgbLuminance', () => {
+	it( 'reads unrounded channels', () => {
+		// Rounded to #808080 this would read 0.2159.
+		expect( rgbLuminance( [ 127.5, 127.5, 127.5 ] ) ).toBeCloseTo( 0.214, 4 );
+		expect( rgbLuminance( [ 56, 88, 233 ] ) ).toBeCloseTo( 0.137, 4 );
+	} );
+} );

package/src/providers/chart-context/test/use-default-hidden-series.test.tsx

@@ -177,7 +177,7 @@ describe( 'useDefaultHiddenSeries', () => {
 
 	it( 'keeps the same set across renders until visibility changes', () => {
 		// Charts memoize their rendered series off this set. A fresh identity per
-		// render invalidates those memos, which re-runs the accessible tooltip's
+		// render invalidates those memos, which re-runs `XYChartTooltip`'s
 		// effect and closes a tooltip the user is still navigating with.
 		const Harness = () => (
 			<GlobalChartsProvider>

package/src/styles/chart-scope-class.ts

@@ -4,3 +4,8 @@
  * Deliberately unhashed: consumers are documented as being able to target it to override a token on the provider element.
  */
 export const CHART_SCOPE_CLASS = 'a8c-charts-scope';
+
+/**
+ * Carries the catalog on the tooltip box, re-declared under the tooltip's own theme. Separate from `CHART_SCOPE_CLASS` so a page-wide override on that class does not reach the dark box.
+ */
+export const TOOLTIP_SCOPE_CLASS = 'a8c-charts-tooltip-scope';

package/src/styles/chart-scope.scss

@@ -10,7 +10,9 @@
 // the same element wins. Chart roots deliberately do NOT re-declare these: an
 // element's own declaration beats an inherited one, so re-declaring lower down
 // would shadow a consumer override set inside the provider tree.
-:where(.a8c-charts-scope) {
+// The tooltip box re-declares the catalog under its own class, so a rule on
+// .a8c-charts-scope does not land on the dark box.
+:where(.a8c-charts-scope, .a8c-charts-tooltip-scope) {
 	// The series palette. GlobalChartsProvider resolves these five slots at its
 	// wrapper and seeds ColorCache with whatever resolves; a slot that resolves
 	// to nothing is skipped, so setting only slots 1 and 3 gives a two-color
@@ -49,14 +51,15 @@
 	--a8c-charts-color-trend-down: var(--wpds-color-foreground-content-error-weak);
 	--a8c-charts-color-trend-neutral: var(--wpds-color-foreground-content-neutral-weak);
 	--a8c-charts-color-background: var(--wpds-color-background-surface-neutral-strong);
-	// Surfaces floating over the chart — tooltips, the annotation label, the
-	// zoom-reset control. Same WPDS token as --a8c-charts-color-background but
+	// Surfaces floating over the chart — the annotation label, the zoom-reset
+	// control. Same WPDS token as --a8c-charts-color-background but
 	// deliberately not derived from it, so either can move without the other.
 	--a8c-charts-color-surface: var(--wpds-color-background-surface-neutral-strong);
 	--a8c-charts-color-surface-secondary: var(--wpds-color-background-surface-neutral-weak);
 	--a8c-charts-color-track: var(--wpds-color-background-track-neutral-weak);
-	// Translucent dark surface; no WPDS token carries this.
-	--a8c-charts-color-tooltip-surface: rgb(0 0 0 / 85%);
+	// The background @wordpress/ui's Tooltip themes its popup with; WPDS has
+	// no inverted surface token yet.
+	--a8c-charts-color-tooltip-surface: #1e1e1e;
 	--a8c-charts-color-zoom-selection: var(--wpds-color-background-interactive-brand-strong);
 	--a8c-charts-color-zoom-selection-stroke: var(--wpds-color-stroke-interactive-brand);
 
@@ -77,6 +80,7 @@
 	--a8c-charts-motion-duration-entrance: var(--wpds-motion-duration-xl);
 	--a8c-charts-motion-easing-entrance: var(--wpds-motion-easing-expressive);
 	--a8c-charts-border-radius-bar: var(--wpds-border-radius-md);
+	--a8c-charts-border-radius-bar-chart: 0;
 	--a8c-charts-border-radius-cell: var(--wpds-border-radius-sm);
 	// Pill shape; no WPDS radius reaches it.
 	--a8c-charts-border-radius-leaderboard-bar: 9999px;
@@ -87,7 +91,7 @@
 
 @media (forced-colors: active) {
 
-	:where(.a8c-charts-scope) {
+	:where(.a8c-charts-scope, .a8c-charts-tooltip-scope) {
 		--a8c-charts-color-label-axis: CanvasText;
 		--a8c-charts-color-grid: GrayText;
 		--a8c-charts-color-axis-x: GrayText;

package/src/styles/test/chart-scope.test.ts

@@ -127,7 +127,7 @@ describe( 'chart scope catalog', () => {
 			expect( mediaRules[ 0 ].cssRules ).toHaveLength( 1 );
 
 			const rule = mediaRules[ 0 ].cssRules[ 0 ] as CSSStyleRule;
-			expect( rule.selectorText ).toBe( ':where(.a8c-charts-scope)' );
+			expect( rule.selectorText ).toBe( ':where(.a8c-charts-scope, .a8c-charts-tooltip-scope)' );
 			expect(
 				Object.fromEntries(
 					Array.from( rule.style ).map( property => [
@@ -171,8 +171,8 @@ describe( 'chart scope catalog', () => {
 		expect( documented.get( token )?.fallback ).toEqual( declared.get( token )?.fallback );
 	} );
 
-	it( 'scopes the catalog to :where(.a8c-charts-scope) rather than :root', () => {
-		expect( stylesheet ).toMatch( /:where\(\.a8c-charts-scope\)\s*{/ );
+	it( 'scopes the catalog to the chart and tooltip scope classes rather than :root', () => {
+		expect( stylesheet ).toMatch( /:where\(\.a8c-charts-scope, \.a8c-charts-tooltip-scope\)\s*{/ );
 		expect( stylesheet ).not.toMatch( /(^|\s):root\s*{/ );
 	} );
 

package/src/test-utils/zoned-parsing-suite.ts

@@ -1,15 +1,5 @@
 import { parseAsLocalDate } from '../utils/date-parsing';
 
-// The `jetpack-js-tools` console guard registers the matcher but ships no types for it.
-declare global {
-	// eslint-disable-next-line @typescript-eslint/no-namespace
-	namespace jest {
-		interface Matchers< R > {
-			toHaveWarnedWith( ...args: unknown[] ): R;
-		}
-	}
-}
-
 // Every case asserts an absolute instant, so running the suite from more than one
 // worker zone is what proves the result does not depend on the viewer's.
 const CASES: Array< [ string, string, string ] > = [

package/src/utils/color-utils.ts

@@ -262,7 +262,8 @@ export const relativeLuminance = ( hex: string ): number => {
  * Whether light text reads better than dark text on the given background, using the W3C
  * luminance threshold (0.179) that maximizes contrast against black vs white.
  *
- * @param backgroundHex - Hex background color
+ * @deprecated Assumes black and white text, so it ignores label role overrides and cannot guarantee AA; charts no longer use it, and it will be removed in a future major version.
+ * @param      backgroundHex - Hex background color
  * @return true if light text should be used; false (dark text) for malformed colors
  */
 export const prefersLightText = ( backgroundHex: string ): boolean => {

package/src/utils/test/date-formatting.test.ts

@@ -1,15 +1,5 @@
 import { createDateFormatter, createZonedClock, sanitizeFormatting } from '../date-formatting';
 
-// The `jetpack-js-tools` console guard registers the matcher but ships no types for it.
-declare global {
-	// eslint-disable-next-line @typescript-eslint/no-namespace
-	namespace jest {
-		interface Matchers< R > {
-			toHaveWarned(): R;
-		}
-	}
-}
-
 describe( 'createDateFormatter', () => {
 	it( 'renders an invalid date rather than throwing', () => {
 		const format = createDateFormatter(

package/src/visx/types.ts

@@ -33,7 +33,7 @@ export type XyChartTooltipProps< Datum extends object > = {
 	tooltipPlacement?: TooltipPlacement;
 	/** Override the tooltip top anchor in SVG coordinates, including negative offsets. */
 	tooltipAnchorTop?: number;
-	/** Merge overrides with the default box styles; use `unstyled` to strip the box styling. */
+	/** Inline overrides on the tooltip surface; `unstyled` drops both. */
 	style?: VisxTooltipProps[ 'style' ];
 	snapTooltipToDatumX?: boolean;
 	snapTooltipToDatumY?: boolean;

package/src/charts/line-chart/test/crosshair-style-types.test.ts

@@ -1,31 +0,0 @@
-import type { LineChartProps } from '../types';
-
-type Crosshairs = NonNullable< LineChartProps[ 'withTooltipCrosshairs' ] >;
-
-describe( 'line chart crosshair style types', () => {
-	test( 'accepts paint attributes', () => {
-		const crosshairs: Crosshairs = { verticalStyle: { stroke: 'purple', strokeWidth: 2 } };
-
-		expect( crosshairs.verticalStyle?.stroke ).toBe( 'purple' );
-	} );
-
-	test( 'reserves geometry attributes for the chart', () => {
-		const crosshairs: Crosshairs = {
-			// @ts-expect-error Crosshair coordinates are computed from the active datum.
-			verticalStyle: { x1: 12 },
-		};
-
-		const transformedCrosshairs: Crosshairs = {
-			// @ts-expect-error Crosshair transforms are not paint attributes.
-			verticalStyle: { transform: 'translate(100 0)' },
-		};
-		const transformedStyles: Crosshairs = {
-			// @ts-expect-error Inline crosshair styles accept only paint properties.
-			horizontalStyle: { style: { transform: 'translateX(100px)' } },
-		};
-
-		expect( crosshairs ).toBeDefined();
-		expect( transformedCrosshairs ).toBeDefined();
-		expect( transformedStyles ).toBeDefined();
-	} );
-} );