@automattic/charts 1.9.0 → 1.10.1

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@automattic/charts",
-	"version": "1.9.0",
+	"version": "1.10.1",
 	"description": "Display charts within Automattic products.",
 	"homepage": "https://github.com/Automattic/jetpack/tree/HEAD/projects/js-packages/charts/#readme",
 	"bugs": {
@@ -63,7 +63,7 @@
 		"typecheck": "tsgo --noEmit"
 	},
 	"dependencies": {
-		"@automattic/number-formatters": "^1.2.5",
+		"@automattic/number-formatters": "^1.2.6",
 		"@babel/runtime": "7.29.7",
 		"@react-spring/web": "10.1.1",
 		"@visx/annotation": "^4.0.0",
@@ -83,9 +83,9 @@
 		"@visx/vendor": "^4.0.0",
 		"@visx/xychart": "^4.0.0",
 		"@wordpress/i18n": "^6.0.0",
-		"@wordpress/icons": "^13.0.0",
-		"@wordpress/theme": "0.15.1",
-		"@wordpress/ui": "0.13.0",
+		"@wordpress/icons": "^15.0.0",
+		"@wordpress/theme": "0.17.0",
+		"@wordpress/ui": "0.17.0",
 		"clsx": "2.1.1",
 		"date-fns": "^4.1.0",
 		"deepmerge": "4.3.1",

package/src/charts/conversion-funnel-chart/conversion-funnel-chart.module.scss

@@ -12,7 +12,7 @@
 
 .main-rate {
 	overflow: hidden;
-	color: var(--wpds-color-fg-content-neutral, #1e1e1e);
+	color: var(--wpds-color-foreground-content-neutral, #1e1e1e);
 	text-overflow: ellipsis;
 	font-size: var(--wpds-typography-font-size-xl, 18px);
 	font-style: normal;
@@ -54,7 +54,7 @@
 }
 
 .step-label {
-	color: var(--wpds-color-fg-content-neutral-weak, #707070);
+	color: var(--wpds-color-foreground-content-neutral-weak, #707070);
 	font-size: var(--wpds-typography-font-size-sm, 12px);
 	font-weight: var(--wpds-typography-font-weight-regular, 400);
 	line-height: var(--wpds-typography-line-height-xs, 16px);
@@ -64,7 +64,7 @@
 }
 
 .step-rate {
-	color: var(--wpds-color-fg-content-neutral, #1e1e1e);
+	color: var(--wpds-color-foreground-content-neutral, #1e1e1e);
 	font-size: var(--wpds-typography-font-size-md, 13px);
 	font-weight: var(--wpds-typography-font-weight-medium, 499);
 	line-height: var(--wpds-typography-line-height-xs, 16px);
@@ -100,7 +100,7 @@
 }
 
 .tooltip-wrapper {
-	background: var(--wpds-color-bg-surface-neutral-strong, #fff);
+	background: var(--wpds-color-background-surface-neutral-strong, #fff);
 
 	// Override .visx-tooltip inline styles.
 	border-radius: var(--wpds-border-radius-md, 4px) !important;
@@ -110,7 +110,7 @@
 }
 
 .tooltip-title {
-	color: var(--wpds-color-fg-content-neutral, #1e1e1e);
+	color: var(--wpds-color-foreground-content-neutral, #1e1e1e);
 	font-size: var(--wpds-typography-font-size-sm, 12px);
 	font-style: normal;
 	font-weight: var(--wpds-typography-font-weight-regular, 400);
@@ -118,7 +118,7 @@
 }
 
 .tooltip-content {
-	color: var(--wpds-color-fg-content-neutral, #1e1e1e);
+	color: var(--wpds-color-foreground-content-neutral, #1e1e1e);
 	font-size: var(--wpds-typography-font-size-md, 13px);
 	font-style: normal;
 	font-weight: var(--wpds-typography-font-weight-medium, 499);
@@ -127,6 +127,6 @@
 
 .empty-state {
 	text-align: center;
-	color: var(--wpds-color-fg-content-neutral-weak, #707070);
+	color: var(--wpds-color-foreground-content-neutral-weak, #707070);
 	font-size: var(--wpds-typography-font-size-lg, 16px);
 }

package/src/charts/geo-chart/geo-chart.tsx

@@ -3,8 +3,8 @@
  */
 import { __ } from '@wordpress/i18n';
 import clsx from 'clsx';
-import { FC, useContext, useMemo } from 'react';
-import { Chart, type GoogleChartPackages } from 'react-google-charts';
+import { FC, useContext, useEffect, useMemo, useRef } from 'react';
+import { Chart, type GoogleChartPackages, type ReactGoogleChartEvent } from 'react-google-charts';
 /**
  * Internal dependencies
  */
@@ -15,7 +15,7 @@ import { sanitizeHtml } from '../../utils/sanitize-html';
 import { Center } from '../private/center';
 import { withResponsive } from '../private/with-responsive';
 import styles from './geo-chart.module.scss';
-import { GeoChartProps } from './types';
+import type { GeoChartError, GeoChartProps } from './types';
 
 const DEFAULT_FEATURE_FILL_COLOR = '#ffffff';
 const DEFAULT_BACKGROUND_COLOR = '#ffffff';
@@ -25,6 +25,89 @@ const DEFAULT_BACKGROUND_COLOR = '#ffffff';
 const GEO_CHART_PACKAGES: GoogleChartPackages[] = [ 'corechart', 'controls', 'geochart' ];
 
 type GoogleChartOptions = Record< string, unknown >;
+type GoogleChartErrorPayload = {
+	id?: unknown;
+	message?: unknown;
+	detailedMessage?: unknown;
+	options?: unknown;
+};
+
+// Google Charts renders draw errors as DOM elements injected into the chart
+// container: a wrapper `<div id="google-visualization-errors-all-N">` holding
+// one `<span id="google-visualization-errors-N">` per error. The span id is the
+// error id accepted by `google.visualization.errors.removeError()`.
+const GOOGLE_CHARTS_ERROR_ID_PREFIX = 'google-visualization-errors-';
+const GOOGLE_CHARTS_ERROR_WRAPPER_INFIX = '-all-';
+
+/**
+ * Collects Google Charts error elements rendered inside a chart container.
+ *
+ * @param container - The chart container element to scan.
+ * @return Errors found in the container, one per error span.
+ */
+function collectRenderedGeoChartErrors(
+	container: HTMLElement
+): Required< Pick< GeoChartError, 'id' | 'message' > >[] {
+	const elements = container.querySelectorAll< HTMLElement >(
+		`[id^="${ GOOGLE_CHARTS_ERROR_ID_PREFIX }"]`
+	);
+
+	return Array.from( elements )
+		.filter( element => ! element.id.includes( GOOGLE_CHARTS_ERROR_WRAPPER_INFIX ) )
+		.map( element => ( {
+			id: element.id,
+			message: element.textContent?.trim() ?? '',
+		} ) )
+		.filter( error => error.message.length > 0 );
+}
+
+/**
+ * Whether a node added to the chart container is — or contains — a Google
+ * Charts error element. Also matches text appended into an existing error
+ * span, in case Google fills the message after inserting the element.
+ *
+ * @param node - The added DOM node to inspect.
+ * @return Whether the node involves a Google Charts error element.
+ */
+function involvesGeoChartErrorElement( node: Node ): boolean {
+	if ( node.nodeType === Node.TEXT_NODE ) {
+		return !! node.parentElement?.id.startsWith( GOOGLE_CHARTS_ERROR_ID_PREFIX );
+	}
+
+	if ( ! ( node instanceof HTMLElement ) ) {
+		return false;
+	}
+
+	return (
+		node.id.startsWith( GOOGLE_CHARTS_ERROR_ID_PREFIX ) ||
+		node.querySelector( `[id^="${ GOOGLE_CHARTS_ERROR_ID_PREFIX }"]` ) !== null
+	);
+}
+
+/**
+ * Normalizes the raw Google Charts error event into the GeoChart error shape.
+ *
+ * @param eventArgs - Error event payload from react-google-charts.
+ * @return Normalized GeoChart error.
+ */
+function normalizeGeoChartError( eventArgs: unknown ): GeoChartError {
+	const payload = Array.isArray( eventArgs ) ? eventArgs[ 0 ] : eventArgs;
+
+	if ( ! payload || typeof payload !== 'object' ) {
+		return {};
+	}
+
+	const { id, message, detailedMessage, options } = payload as GoogleChartErrorPayload;
+
+	return {
+		...( typeof id === 'string' && { id } ),
+		...( typeof message === 'string' && { message } ),
+		...( typeof detailedMessage === 'string' && { detailedMessage } ),
+		...( options &&
+			typeof options === 'object' &&
+			! Array.isArray( options ) && { options: options as Record< string, unknown > } ),
+	};
+}
 
 /**
  * Renders a geographical chart using Google Charts GeoChart to visualize data.
@@ -41,6 +124,7 @@ type GoogleChartOptions = Record< string, unknown >;
  * @param props.height            - Height of the chart in pixels
  * @param props.region            - Region to display ('world', 'US', or ISO 3166-1 alpha-2 code)
  * @param props.resolution        - Resolution level ('countries', 'provinces', or 'metros')
+ * @param props.onError           - Optional callback for Google Charts errors
  * @param props.className         - Additional CSS class name for the chart container
  * @param props.renderPlaceholder - Optional render function for the loading placeholder
  * @return A React component displaying an interactive map with data visualization
@@ -52,6 +136,7 @@ const GeoChartInternal: FC< GeoChartProps > = ( {
 	height,
 	region = 'world',
 	resolution = 'countries',
+	onError,
 	renderPlaceholder,
 } ) => {
 	const {
@@ -61,6 +146,49 @@ const GeoChartInternal: FC< GeoChartProps > = ( {
 			backgroundColor,
 		},
 	} = useGlobalChartsContext();
+	const containerRef = useRef< HTMLDivElement >( null );
+	const reportedErrorIdsRef = useRef< Set< string > >( new Set() );
+
+	// The ChartWrapper `error` event does not fire for every draw failure —
+	// notably not when GeoChart's asynchronous map-file load fails (e.g.
+	// `resolution: 'provinces'` for a country without a provinces map). Those
+	// errors only surface as DOM elements Google injects into the container, so
+	// watch the container and report them through the same `onError` callback.
+	useEffect( () => {
+		const container = containerRef.current;
+
+		if ( ! onError || ! container || typeof MutationObserver === 'undefined' ) {
+			return undefined;
+		}
+
+		const reportRenderedErrors = () => {
+			for ( const error of collectRenderedGeoChartErrors( container ) ) {
+				if ( reportedErrorIdsRef.current.has( error.id ) ) {
+					continue;
+				}
+
+				reportedErrorIdsRef.current.add( error.id );
+				onError( error );
+			}
+		};
+
+		// GeoChart mutates the container heavily while drawing and resizing;
+		// only rescan when an added node involves a Google error element.
+		const observer = new MutationObserver( records => {
+			const hasErrorNodes = records.some( record =>
+				Array.from( record.addedNodes ).some( involvesGeoChartErrorElement )
+			);
+
+			if ( hasErrorNodes ) {
+				reportRenderedErrors();
+			}
+		} );
+		observer.observe( container, { childList: true, subtree: true } );
+		// Report errors already rendered before the observer attached.
+		reportRenderedErrors();
+
+		return () => observer.disconnect();
+	}, [ onError ] );
 
 	// Render loading placeholder
 	const loadingPlaceholder = (
@@ -150,8 +278,24 @@ const GeoChartInternal: FC< GeoChartProps > = ( {
 		]
 	);
 
+	const chartEvents = useMemo< ReactGoogleChartEvent[] | undefined >( () => {
+		if ( ! onError ) {
+			return undefined;
+		}
+
+		return [
+			{
+				eventName: 'error',
+				callback: ( { eventArgs } ) => {
+					onError( normalizeGeoChartError( eventArgs ) );
+				},
+			},
+		];
+	}, [ onError ] );
+
 	return (
 		<Center
+			ref={ containerRef }
 			className={ clsx( 'geo-chart', styles.container, className ) }
 			data-testid="geo-chart"
 			style={ { width, height, backgroundColor } }
@@ -163,6 +307,7 @@ const GeoChartInternal: FC< GeoChartProps > = ( {
 				height={ height }
 				data={ sanitizedData.data }
 				options={ options }
+				chartEvents={ chartEvents }
 				loader={ loadingPlaceholder }
 			/>
 		</Center>

package/src/charts/geo-chart/index.ts

@@ -1,2 +1,2 @@
 export { default as GeoChart, GeoChartUnresponsive } from './geo-chart';
-export type { GeoChartProps, GeoRegion, GeoResolution } from './types';
+export type { GeoChartProps, GeoRegion, GeoResolution, GeoChartError } from './types';

package/src/charts/geo-chart/test/geo-chart.test.tsx

@@ -1,12 +1,16 @@
-import { render, screen } from '@testing-library/react';
+import { render, screen, waitFor } from '@testing-library/react';
+import { Chart } from 'react-google-charts';
 import { GlobalChartsProvider } from '../../../providers';
 import GeoChart, { GeoChartUnresponsive } from '../geo-chart';
 
 // Mock react-google-charts
 jest.mock( 'react-google-charts', () => ( {
-	Chart: jest.fn( ( { chartPackages, data, options, width, height } ) => {
+	Chart: jest.fn( ( { chartEvents, chartPackages, data, options, width, height } ) => {
 		return (
 			<div data-testid="google-chart-mock" data-width={ width } data-height={ height }>
+				<div data-testid="chart-events">
+					{ JSON.stringify( chartEvents?.map( event => event.eventName ) ?? [] ) }
+				</div>
 				<div data-testid="chart-packages">{ JSON.stringify( chartPackages ) }</div>
 				<div data-testid="chart-data">{ JSON.stringify( data ) }</div>
 				<div data-testid="chart-options">{ JSON.stringify( options ) }</div>
@@ -16,6 +20,8 @@ jest.mock( 'react-google-charts', () => ( {
 } ) );
 
 describe( 'GeoChart', () => {
+	const ChartMock = Chart as jest.Mock;
+
 	const defaultProps = {
 		width: 800,
 		height: 400,
@@ -258,6 +264,120 @@ describe( 'GeoChart', () => {
 		} );
 	} );
 
+	describe( 'Chart Events', () => {
+		test( 'does not pass chart events when onError is omitted', () => {
+			renderWithTheme();
+
+			const chartEvents = screen.getByTestId( 'chart-events' );
+			const events = JSON.parse( chartEvents.textContent || '[]' );
+
+			expect( events ).toEqual( [] );
+		} );
+
+		test( 'calls onError when Google Charts emits an error', () => {
+			const onError = jest.fn();
+			renderWithTheme( { onError } );
+
+			const chartProps = ChartMock.mock.calls[ ChartMock.mock.calls.length - 1 ]?.[ 0 ];
+			const errorEvent = chartProps.chartEvents.find(
+				( event: { eventName: string } ) => event.eventName === 'error'
+			);
+
+			errorEvent.callback( {
+				eventArgs: [
+					{
+						id: 'map-error',
+						message: 'Requested map does not exist.',
+						detailedMessage: 'The requested map is not available.',
+						options: { region: 'SG', resolution: 'provinces' },
+					},
+				],
+			} );
+
+			expect( onError ).toHaveBeenCalledWith( {
+				id: 'map-error',
+				message: 'Requested map does not exist.',
+				detailedMessage: 'The requested map is not available.',
+				options: { region: 'SG', resolution: 'provinces' },
+			} );
+		} );
+
+		test( 'reports error elements Google injects into the chart container', async () => {
+			const onError = jest.fn();
+			renderWithTheme( { onError } );
+
+			// Simulate Google Charts rendering a draw error into the container,
+			// as happens when an async map-file load fails without firing the
+			// ChartWrapper error event.
+			const container = screen.getByTestId( 'geo-chart' );
+			const errorWrapper = document.createElement( 'div' );
+			errorWrapper.id = 'google-visualization-errors-all-1';
+			const errorSpan = document.createElement( 'span' );
+			errorSpan.id = 'google-visualization-errors-1';
+			errorSpan.textContent = 'Requested map does not exist.';
+			errorWrapper.appendChild( errorSpan );
+			container.appendChild( errorWrapper );
+
+			await waitFor( () =>
+				expect( onError ).toHaveBeenCalledWith( {
+					id: 'google-visualization-errors-1',
+					message: 'Requested map does not exist.',
+				} )
+			);
+		} );
+
+		test( 'reports error elements nested inside an added plain node', async () => {
+			const onError = jest.fn();
+			renderWithTheme( { onError } );
+
+			// The observer filters mutation records by the added node; an error
+			// element arriving inside a plain wrapper must still be found.
+			const container = screen.getByTestId( 'geo-chart' );
+			const plainWrapper = document.createElement( 'div' );
+			const errorSpan = document.createElement( 'span' );
+			errorSpan.id = 'google-visualization-errors-9';
+			errorSpan.textContent = 'Requested map does not exist.';
+			plainWrapper.appendChild( errorSpan );
+			container.appendChild( plainWrapper );
+
+			await waitFor( () =>
+				expect( onError ).toHaveBeenCalledWith( {
+					id: 'google-visualization-errors-9',
+					message: 'Requested map does not exist.',
+				} )
+			);
+		} );
+
+		test( 'reports each rendered error element only once', async () => {
+			const onError = jest.fn();
+			renderWithTheme( { onError } );
+
+			const container = screen.getByTestId( 'geo-chart' );
+			const errorSpan = document.createElement( 'span' );
+			errorSpan.id = 'google-visualization-errors-2';
+			errorSpan.textContent = 'Requested map does not exist.';
+			container.appendChild( errorSpan );
+
+			await waitFor( () => expect( onError ).toHaveBeenCalledTimes( 1 ) );
+
+			// A later mutation makes the observer re-scan the container; the first
+			// error is seen again but must not be re-reported. The second error
+			// being reported proves the re-scan happened.
+			const secondErrorSpan = document.createElement( 'span' );
+			secondErrorSpan.id = 'google-visualization-errors-3';
+			secondErrorSpan.textContent = 'Requested map does not exist.';
+			container.appendChild( secondErrorSpan );
+
+			await waitFor( () =>
+				expect( onError ).toHaveBeenCalledWith( {
+					id: 'google-visualization-errors-3',
+					message: 'Requested map does not exist.',
+				} )
+			);
+			expect( onError ).toHaveBeenCalledTimes( 2 );
+		} );
+	} );
+
 	describe( 'Loading State', () => {
 		test( 'provides loading placeholder to Google Charts', () => {
 			// The loading placeholder is passed to the Chart component's loader prop

package/src/charts/geo-chart/types.ts

@@ -15,6 +15,13 @@ export type GeoRegion = 'world' | ( string & {} );
  */
 export type GeoResolution = 'countries' | 'provinces' | 'metros';
 
+export interface GeoChartError {
+	id?: string;
+	message?: string;
+	detailedMessage?: string;
+	options?: Record< string, unknown >;
+}
+
 export interface GeoChartProps
 	extends Pick< BaseChartProps, 'className' | 'chartId' | 'width' | 'height' > {
 	/**
@@ -39,6 +46,10 @@ export interface GeoChartProps
 	 * @default 'countries'
 	 */
 	resolution?: GeoResolution;
+	/**
+	 * Callback fired when Google Charts emits a chart error.
+	 */
+	onError?: ( error: GeoChartError ) => void;
 	/**
 	 * Optional render function for the loading placeholder.
 	 * Called while Google Charts is loading.

package/src/charts/heatmap-chart/heatmap-chart.module.scss

@@ -7,7 +7,7 @@
 
 .heatmap-chart__empty {
 	padding: var(--wpds-dimension-padding-lg, 16px);
-	color: var(--wpds-color-fg-content-neutral-weak, #707070);
+	color: var(--wpds-color-foreground-content-neutral-weak, #707070);
 }
 
 // Track template is set inline because CSS `repeat()` won't take a `var()`
@@ -17,13 +17,13 @@
 	gap: var(--heatmap-cell-gap, var(--wpds-dimension-gap-xs, 4px));
 	flex: 1 1 0;
 	width: 100%;
-	// Floor so the grid stays usable when the parent has no explicit height.
-	min-height: 200px;
+	// Override flex's auto minimum so short widgets do not scroll.
+	min-height: 0;
 
 	&:focus-visible {
 		outline:
 			var(--wpds-border-width-focus, var(--wp-admin-border-width-focus, 2px)) solid
-			var(--wpds-color-stroke-focus-brand, var(--wp-admin-theme-color, #3858e9));
+			var(--wpds-color-stroke-focus, var(--wp-admin-theme-color, #3858e9));
 		outline-offset: 2px;
 		border-radius: var(--wpds-border-radius-sm, 2px);
 	}
@@ -42,7 +42,7 @@
 
 .heatmap-chart__col-label,
 .heatmap-chart__row-label {
-	color: var(--wpds-color-fg-content-neutral-weak, #707070);
+	color: var(--wpds-color-foreground-content-neutral-weak, #707070);
 	font-size: var(--wpds-typography-font-size-xs, 11px);
 	white-space: nowrap;
 	overflow: visible;
@@ -68,36 +68,36 @@
 	min-height: 0;
 	border-radius: var(--wpds-border-radius-sm, 2px);
 	// Empty (no-data) default; cells with a value override it below.
-	background: var(--wpds-color-bg-track-neutral-weak, #f0f0f0);
+	background: var(--wpds-color-background-track-neutral-weak, #f0f0f0);
 }
 
 // Floor the mix at 15% so the lowest value stays visibly tinted, distinct from
 // an empty cell.
 .heatmap-chart__cell--filled {
-	background: color-mix(in sRGB, var(--heatmap-primary) calc((0.15 + 0.85 * var(--intensity)) * 100%), transparent);
+	background: color-mix(in sRGB, var(--heatmap-primary) calc((0.15 + 0.85 * var(--intensity)) * 100%), var(--heatmap-bg, #fff));
 }
 
 .heatmap-chart__cell--selected {
 	outline:
 		var(--wpds-border-width-focus, var(--wp-admin-border-width-focus, 2px)) solid
-		var(--wpds-color-stroke-focus-brand, var(--wp-admin-theme-color, #3858e9));
+		var(--wpds-color-stroke-focus, var(--wp-admin-theme-color, #3858e9));
 	outline-offset: calc(-1 * var(--wpds-border-width-focus, var(--wp-admin-border-width-focus, 2px)));
 }
 
 .heatmap-chart__cell-value {
-	color: var(--wpds-color-fg-content-neutral, #1e1e1e);
+	color: var(--wpds-color-foreground-content-neutral, #1e1e1e);
 	font-size: var(--wpds-typography-font-size-md, 13px);
 }
 
 // Light text on fills dark enough to out-contrast dark text (decided in JS from
 // the blended fill luminance).
 .heatmap-chart__cell--strong .heatmap-chart__cell-value {
-	color: var(--wpds-color-fg-interactive-neutral-strong, #f0f0f0);
+	color: var(--wpds-color-foreground-interactive-neutral-strong, #f0f0f0);
 }
 
 .heatmap-chart__legend-swatch {
 	width: var(--wpds-dimension-size-3xs, 12px);
 	height: var(--wpds-dimension-size-3xs, 12px);
 	border-radius: var(--wpds-border-radius-sm, 2px);
-	background: color-mix(in sRGB, var(--heatmap-primary) calc((0.15 + 0.85 * var(--intensity)) * 100%), transparent);
+	background: color-mix(in sRGB, var(--heatmap-primary) calc((0.15 + 0.85 * var(--intensity)) * 100%), var(--heatmap-bg, #fff));
 }