@automattic/charts 1.8.1 → 1.9.0

package/src/charts/private/with-responsive/test/with-responsive.test.tsx

@@ -72,6 +72,20 @@ describe( 'withResponsive', () => {
 			const wrapper = screen.getByTestId( 'responsive-wrapper' );
 			expect( wrapper ).toHaveStyle( { width: '100%', height: 'auto' } );
 		} );
+
+		test( 'wrapper expresses aspectRatio in CSS and caps at maxWidth', () => {
+			render( <ResponsiveComponent data={ [] } aspectRatio={ 0.5 } maxWidth={ 800 } /> );
+			const wrapper = screen.getByTestId( 'responsive-wrapper' );
+			// CSS aspect-ratio is width/height, so 1 / 0.5 = 2.
+			expect( wrapper ).toHaveStyle( { aspectRatio: '2', maxWidth: '800px' } );
+		} );
+
+		test( 'wrapper omits the maxWidth cap when an explicit width is set', () => {
+			render( <ResponsiveComponent data={ [] } aspectRatio={ 0.5 } width={ 300 } /> );
+			const wrapper = screen.getByTestId( 'responsive-wrapper' );
+			expect( wrapper ).toHaveStyle( { aspectRatio: '2', width: '300px' } );
+			expect( wrapper ).not.toHaveStyle( { maxWidth: '1200px' } );
+		} );
 	} );
 
 	describe( 'configuration', () => {

package/src/charts/private/with-responsive/with-responsive.tsx

@@ -93,6 +93,17 @@ export function withResponsive< T extends Exclude< BaseChartProps< unknown >, 'o
 		const effectiveHeight = measuredHeight || height || 0;
 
 		const defaultHeight = hasAspectRatio ? 'auto' : '100%';
+		// Express the aspect ratio in CSS so the container height tracks its width
+		// fluidly, rather than snapping to a debounced measured height. Cap the width
+		// at maxWidth so the CSS-derived height matches the maxWidth-capped content
+		// (the wrapped chart is sized from the capped `measuredWidth`).
+		const aspectRatioStyle =
+			hasAspectRatio && aspectRatio
+				? {
+						aspectRatio: `${ 1 / aspectRatio }`,
+						maxWidth: width === undefined ? maxWidth : undefined,
+				  }
+				: null;
 
 		return (
 			<div
@@ -102,6 +113,7 @@ export function withResponsive< T extends Exclude< BaseChartProps< unknown >, 'o
 				style={ {
 					width: width ?? '100%',
 					height: height ?? defaultHeight,
+					...aspectRatioStyle,
 				} }
 			>
 				<WrappedComponent

package/src/charts/private/x-zoom.module.scss

@@ -1,5 +1,8 @@
 .x-zoom {
 
+	// The translucent rgba overlay colors (selection fill/stroke, reset
+	// background/border) have no WPDS equivalent and stay as-is; only the
+	// opaque foreground and focus colors are tokenized.
 	&__selection {
 		fill: var(--charts-zoom-selection-fill, rgba(56, 88, 233, 0.16));
 		stroke: var(--charts-zoom-selection-stroke, rgba(56, 88, 233, 0.65));
@@ -19,20 +22,20 @@
 		height: 28px;
 		padding: 0;
 		background: var(--charts-zoom-reset-bg, rgba(255, 255, 255, 0.92));
-		color: var(--charts-zoom-reset-fg, #1e1e1e);
+		color: var(--charts-zoom-reset-fg, var(--wpds-color-fg-content-neutral, #1e1e1e));
 		border:
 			var(--wpds-border-width-xs, 1px) solid
 			var(--charts-zoom-reset-border, rgba(0, 0, 0, 0.16));
 		border-radius: var(--wpds-border-radius-md, 4px);
 		cursor: pointer;
-		box-shadow: 0 1px 2px rgba(0, 0, 0, 0.08);
+		box-shadow: var(--wpds-elevation-xs, 0 1px 1px 0 #00000008, 0 1px 2px 0 #00000005, 0 3px 3px 0 #00000005, 0 4px 4px 0 #00000003);
 
 		&:hover {
 			background: var(--charts-zoom-reset-bg-hover, rgba(255, 255, 255, 1));
 		}
 
 		&:focus-visible {
-			outline: 2px solid var(--charts-zoom-reset-focus, #3858e9);
+			outline: 2px solid var(--charts-zoom-reset-focus, var(--wpds-color-stroke-focus-brand, #3858e9));
 			outline-offset: 1px;
 		}
 	}

package/src/components/legend/private/base-legend.module.scss

@@ -8,7 +8,9 @@
 	&--interactive {
 		cursor: pointer;
 		user-select: none;
-		transition: opacity 0.2s ease;
+		transition:
+			opacity var(--wpds-motion-duration-md, 200ms)
+			var(--wpds-motion-easing-subtle, cubic-bezier(0.15, 0, 0.15, 1));
 
 		&:hover {
 			opacity: 0.8;

package/src/components/tooltip/base-tooltip.module.scss

@@ -1,10 +1,13 @@
 .tooltip {
 	padding: var(--wpds-dimension-padding-sm, 8px);
+	// No WPDS token fits a translucent dark tooltip surface:
+	// bg-interactive-neutral-strong is opaque, and there is no
+	// white-on-dark content foreground token.
 	background-color: rgba(0, 0, 0, 0.85);
 	color: #fff;
 	border-radius: var(--wpds-border-radius-md, 4px);
 	font-size: var(--wpds-typography-font-size-md, 13px);
-	box-shadow: 0 1px 2px rgba(0, 0, 0, 0.1);
+	box-shadow: var(--wpds-elevation-sm, 0 1px 2px 0 #0000000d, 0 2px 3px 0 #0000000a, 0 6px 6px 0 #00000008, 0 8px 8px 0 #00000005);
 	position: absolute;
 	pointer-events: none;
 	transform: translate(-50%, -100%);

package/src/components/trend-indicator/trend-indicator.module.scss

@@ -6,16 +6,18 @@
 	font-weight: var(--wpds-typography-font-weight-medium, 499);
 	line-height: 1;
 
+	// Trend colors use the documented --charts-trend-* override API, falling
+	// back to the accessible WPDS semantic tokens.
 	&--up {
-		color: var(--charts-trend-up-color, #1a8917);
+		color: var(--charts-trend-up-color, var(--wpds-color-fg-content-success-weak, #008030));
 	}
 
 	&--down {
-		color: var(--charts-trend-down-color, #d63638);
+		color: var(--charts-trend-down-color, var(--wpds-color-fg-content-error-weak, #cc1818));
 	}
 
 	&--neutral {
-		color: var(--charts-trend-neutral-color, #646970);
+		color: var(--charts-trend-neutral-color, var(--wpds-color-fg-content-neutral-weak, #707070));
 	}
 
 	&__icon {

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

@@ -1,8 +1,15 @@
 import { buildChartTheme } from '@visx/xychart';
 import { useMemo } from 'react';
 import { useGlobalChartsTheme } from '../providers';
+import { resolveCssVariable } from '../utils';
 import type { SeriesData } from '../types';
 
+// visx applies grid, axis, and tick-label colors as SVG presentation attributes,
+// where CSS var() cannot resolve. Resolve WPDS tokens to concrete values (or their
+// fallbacks) before handing the theme to buildChartTheme.
+const resolveColor = ( value?: string ): string | undefined =>
+	value ? resolveCssVariable( value ) ?? value : value;
+
 export const useXYChartTheme = ( data: SeriesData[] ) => {
 	const theme = useGlobalChartsTheme();
 
@@ -14,6 +21,23 @@ export const useXYChartTheme = ( data: SeriesData[] ) => {
 		return buildChartTheme( {
 			...theme,
 			colors: [ ...seriesColors, ...( theme.colors ?? [] ) ],
+			backgroundColor: resolveColor( theme.backgroundColor ),
+			gridStyles: theme.gridStyles && {
+				...theme.gridStyles,
+				stroke: resolveColor( theme.gridStyles.stroke ),
+			},
+			xAxisLineStyles: theme.xAxisLineStyles && {
+				...theme.xAxisLineStyles,
+				stroke: resolveColor( theme.xAxisLineStyles.stroke ),
+			},
+			xTickLineStyles: theme.xTickLineStyles && {
+				...theme.xTickLineStyles,
+				stroke: resolveColor( theme.xTickLineStyles.stroke ),
+			},
+			svgLabelSmall: theme.svgLabelSmall && {
+				...theme.svgLabelSmall,
+				fill: resolveColor( theme.svgLabelSmall.fill ),
+			},
 		} );
 	}, [ theme, data ] );
 };

package/src/index.ts

@@ -4,6 +4,11 @@ export { BarChart, BarChartUnresponsive } from './charts/bar-chart';
 export { BarListChart, BarListChartUnresponsive } from './charts/bar-list-chart';
 export { ConversionFunnelChart } from './charts/conversion-funnel-chart';
 export { GeoChart, GeoChartUnresponsive } from './charts/geo-chart';
+export {
+	HeatmapChart,
+	HeatmapChartUnresponsive,
+	buildCalendarHeatmapData,
+} from './charts/heatmap-chart';
 export { LeaderboardChart, LeaderboardChartUnresponsive } from './charts/leaderboard-chart';
 export { LineChart, LineChartUnresponsive } from './charts/line-chart';
 export { PieChart, PieChartUnresponsive } from './charts/pie-chart';
@@ -96,6 +101,13 @@ export type {
 	MainMetricRenderProps,
 	TooltipRenderProps,
 } from './charts/conversion-funnel-chart';
+export type {
+	HeatmapChartProps,
+	HeatmapColumn,
+	HeatmapCell,
+	HeatmapTooltipData,
+	CalendarHeatmapResult,
+} from './charts/heatmap-chart';
 export type { LeaderboardChartProps } from './charts/leaderboard-chart';
 export type {
 	LineChartProps,

package/src/providers/chart-context/themes.ts

@@ -4,22 +4,24 @@ import type { CompleteChartTheme } from '../../types';
  * Default theme configuration
  */
 const defaultTheme: CompleteChartTheme = {
-	backgroundColor: '#FFFFFF', // chart background color
+	backgroundColor: 'var(--wpds-color-bg-surface-neutral-strong, #fff)',
 	labelBackgroundColor: 'transparent', // label background color (transparent by default)
-	labelTextColor: '#FFFFFF', // label text color (white to match original behavior)
+	// White label text sits on top of arbitrary series colors, so it has no WPDS
+	// content-foreground equivalent and stays hardcoded (tokenization outlier).
+	labelTextColor: '#FFFFFF',
 	colors: [ '#98C8DF', '#006DAB', '#A6DC80', '#1F9828', '#FF8C8F' ],
 	gridStyles: {
-		stroke: '#DCDCDE',
+		stroke: 'var(--wpds-color-stroke-surface-neutral, #dbdbdb)',
 		strokeWidth: 1,
 	},
 	tickLength: 4,
 	gridColor: '',
 	gridColorDark: '',
-	xTickLineStyles: { stroke: 'black' },
-	xAxisLineStyles: { stroke: '#DCDCDE', strokeWidth: 1 },
+	xTickLineStyles: { stroke: 'var(--wpds-color-stroke-surface-neutral, #dbdbdb)', strokeWidth: 1 },
+	xAxisLineStyles: { stroke: 'var(--wpds-color-stroke-surface-neutral, #dbdbdb)', strokeWidth: 1 },
 	legend: {
 		labelStyles: {
-			color: 'var(--jp-gray-80, #2c3338)',
+			color: 'var(--wpds-color-fg-content-neutral, #1e1e1e)',
 		},
 		containerStyles: {},
 		shapeStyles: [],
@@ -31,35 +33,40 @@ const defaultTheme: CompleteChartTheme = {
 	// that `buildChartTheme` injects as an inline style on SVG `<text>`
 	// elements for axis labels and ticks. Setting `inherit` lets SVG text
 	// pick up the host application's font-family via normal CSS inheritance.
-	svgLabelSmall: { fill: 'var(--jp-gray-80, #2c3338)', fontFamily: 'inherit' },
+	svgLabelSmall: { fill: 'var(--wpds-color-fg-content-neutral, #1e1e1e)', fontFamily: 'inherit' },
 	svgLabelBig: { fontFamily: 'inherit' },
 	annotationStyles: {
 		label: {
-			anchorLineStroke: 'var(--jp-gray-80, #2c3338)',
-			backgroundFill: '#fff',
+			anchorLineStroke: 'var(--wpds-color-fg-content-neutral, #1e1e1e)',
+			backgroundFill: 'var(--wpds-color-bg-surface-neutral-strong, #fff)',
 		},
 		connector: {
-			stroke: 'var(--jp-gray-80, #2c3338)',
+			stroke: 'var(--wpds-color-fg-content-neutral, #1e1e1e)',
 		},
 		circleSubject: {
 			stroke: 'transparent',
-			fill: 'var(--jp-gray-80, #2c3338)',
+			fill: 'var(--wpds-color-fg-content-neutral, #1e1e1e)',
 			radius: 5,
 		},
 	},
 	geoChart: {
-		featureFillColor: 'var(--jp-gray-0, #f6f7f7)',
+		featureFillColor: 'var(--wpds-color-bg-surface-neutral-weak, #f4f4f4)',
 	},
 	leaderboardChart: {
 		rowGap: 12,
 		columnGap: 4,
 		labelSpacing: 'xs',
-		deltaColors: [ '#FF8C8F', '#757575', '#1F9828' ], // [negative, neutral, positive]
+		// [negative, neutral, positive]
+		deltaColors: [
+			'var(--wpds-color-fg-content-error-weak, #cc1818)',
+			'var(--wpds-color-fg-content-neutral-weak, #707070)',
+			'var(--wpds-color-fg-content-success-weak, #008030)',
+		],
 	},
 	conversionFunnelChart: {
-		backgroundColor: '#F3F4F6',
-		positiveChangeColor: '#1F9828',
-		negativeChangeColor: '#FF8C8F',
+		backgroundColor: 'var(--wpds-color-bg-surface-neutral-weak, #f4f4f4)',
+		positiveChangeColor: 'var(--wpds-color-fg-content-success-weak, #008030)',
+		negativeChangeColor: 'var(--wpds-color-fg-content-error-weak, #cc1818)',
 	},
 	lineChart: {
 		lineStyles: {
@@ -81,6 +88,12 @@ const defaultTheme: CompleteChartTheme = {
 		margin: { top: 2, right: 2, bottom: 2, left: 2 },
 		strokeWidth: 1.5,
 	},
+	// `primaryColor` is left unset so it falls back to the palette's `colors[0]`. The compact
+	// 11px square / 2px gap is the contribution-graph rhythm, which has no WPDS dimension.
+	heatmapChart: {
+		compactCellGap: 2,
+		compactCellSize: 11,
+	},
 };
 
 export { defaultTheme };

package/src/types.ts

@@ -249,8 +249,8 @@ export type GradientStop = {
 
 export type SeriesDataOptions = {
 	gradient?: {
-		from: string;
-		to: string;
+		from?: string;
+		to?: string;
 		fromOpacity?: number;
 		toOpacity?: number;
 		stops?: GradientStop[];
@@ -413,6 +413,21 @@ export type ChartTheme = {
 		/** Stroke width for the sparkline line */
 		strokeWidth?: number;
 	};
+	/**
+	 * HeatmapChart settings. Cell gap, radius, value size and the selection ring come from
+	 * WPDS tokens in CSS, so only the scale color and the compact sizing live here.
+	 */
+	heatmapChart?: {
+		/**
+		 * Color the cell scale interpolates toward at the highest value (prop > this >
+		 * palette `colors[0]`), fed to CSS `color-mix`. Omit to use the palette color.
+		 */
+		primaryColor?: string;
+		/** Gap in px between cells in compact mode */
+		compactCellGap?: number;
+		/** Fixed square cell size in px for compact mode */
+		compactCellSize?: number;
+	};
 };
 
 /**
@@ -440,6 +455,8 @@ export type CompleteChartTheme = Required< ChartTheme > & {
 	sparkline: Required< NonNullable< ChartTheme[ 'sparkline' ] > > & {
 		margin: Required< NonNullable< ChartTheme[ 'sparkline' ] >[ 'margin' ] >;
 	};
+	heatmapChart: Omit< Required< NonNullable< ChartTheme[ 'heatmapChart' ] > >, 'primaryColor' > &
+		Pick< NonNullable< ChartTheme[ 'heatmapChart' ] >, 'primaryColor' >;
 };
 
 export type AxisOptions = {

package/src/utils/color-utils.ts

@@ -232,3 +232,39 @@ export const lightenHexColor = ( hex: string, blend: number ): string => {
 		.toString( 16 )
 		.padStart( 2, '0' ) }${ newB.toString( 16 ).padStart( 2, '0' ) }`;
 };
+
+/**
+ * WCAG relative luminance of a hex color (0 = black, 1 = white).
+ *
+ * @param  hex - Hex color string (e.g., '#98C8DF')
+ * @return Relative luminance in the range [0, 1]
+ * @throws {Error} if hex string is malformed
+ */
+export const relativeLuminance = ( hex: string ): number => {
+	validateHexColor( hex );
+
+	const toLinear = ( value: number ): number => {
+		const channel = value / 255;
+		return channel <= 0.03928 ? channel / 12.92 : Math.pow( ( channel + 0.055 ) / 1.055, 2.4 );
+	};
+
+	const r = toLinear( parseInt( hex.slice( 1, 3 ), 16 ) );
+	const g = toLinear( parseInt( hex.slice( 3, 5 ), 16 ) );
+	const b = toLinear( parseInt( hex.slice( 5, 7 ), 16 ) );
+
+	return 0.2126 * r + 0.7152 * g + 0.0722 * b;
+};
+
+/**
+ * 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
+ * @return true if light text should be used; false (dark text) for malformed colors
+ */
+export const prefersLightText = ( backgroundHex: string ): boolean => {
+	if ( ! isValidHexColor( backgroundHex ) ) {
+		return false;
+	}
+	return relativeLuminance( backgroundHex ) <= 0.179;
+};

package/src/utils/test/color-utils.test.ts

@@ -8,6 +8,8 @@ import {
 	parseHslString,
 	parseRgbString,
 	normalizeColorToHex,
+	relativeLuminance,
+	prefersLightText,
 } from '../color-utils';
 
 // Helper to convert hex to HSL tuple using d3-color
@@ -881,3 +883,34 @@ describe( 'normalizeColorToHex', () => {
 		} );
 	} );
 } );
+
+describe( 'relativeLuminance', () => {
+	it( 'returns 0 for black and 1 for white', () => {
+		expect( relativeLuminance( '#000000' ) ).toBeCloseTo( 0, 5 );
+		expect( relativeLuminance( '#ffffff' ) ).toBeCloseTo( 1, 5 );
+	} );
+
+	it( 'returns a higher luminance for a lighter color', () => {
+		expect( relativeLuminance( '#98c8df' ) ).toBeGreaterThan( relativeLuminance( '#006dab' ) );
+	} );
+
+	it( 'throws on a malformed hex', () => {
+		expect( () => relativeLuminance( 'not-a-color' ) ).toThrow();
+	} );
+} );
+
+describe( 'prefersLightText', () => {
+	it( 'prefers dark text on light backgrounds', () => {
+		expect( prefersLightText( '#ffffff' ) ).toBe( false );
+		expect( prefersLightText( '#98c8df' ) ).toBe( false );
+	} );
+
+	it( 'prefers light text on dark backgrounds', () => {
+		expect( prefersLightText( '#000000' ) ).toBe( true );
+		expect( prefersLightText( '#006dab' ) ).toBe( true );
+	} );
+
+	it( 'falls back to dark text for malformed colors', () => {
+		expect( prefersLightText( 'var(--token)' ) ).toBe( false );
+	} );
+} );