@automattic/charts 1.9.0 → 1.10.1

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

@@ -186,6 +186,11 @@ export const GlobalChartsProvider: FC< GlobalChartsProviderProps > = ( { childre
 		[ colorCache, groupToColorMap ]
 	);
 
+	const resolveThemeColor = useCallback< GlobalChartsContextValue[ 'resolveThemeColor' ] >(
+		value => ( value ? normalizeColorToHex( value, wrapperRef.current, resolveCssVariable ) : '' ),
+		[]
+	);
+
 	const getElementStyles = useCallback< GlobalChartsContextValue[ 'getElementStyles' ] >(
 		( { data, index, overrideColor, legendShape } ) => {
 			const isSeriesData = data && typeof data === 'object' && 'data' in data && 'options' in data;
@@ -264,6 +269,7 @@ export const GlobalChartsProvider: FC< GlobalChartsProviderProps > = ( { childre
 			getChartData,
 			theme: providerTheme,
 			getElementStyles,
+			resolveThemeColor,
 			toggleSeriesVisibility,
 			isSeriesVisible,
 			getHiddenSeries,
@@ -276,6 +282,7 @@ export const GlobalChartsProvider: FC< GlobalChartsProviderProps > = ( { childre
 			getChartData,
 			providerTheme,
 			getElementStyles,
+			resolveThemeColor,
 			toggleSeriesVisibility,
 			isSeriesVisible,
 			getHiddenSeries,

package/src/providers/chart-context/test/chart-context.test.tsx

@@ -2536,6 +2536,46 @@ describe( 'ChartContext', () => {
 				expect( afterRerenderColor ).toBe( '#ff0000' );
 			} );
 		} );
+
+		describe( 'resolveThemeColor', () => {
+			let contextValue: GlobalChartsContextValue;
+
+			const TestComponent = () => {
+				contextValue = useGlobalChartsContext();
+				return <div>Test</div>;
+			};
+
+			const mountProvider = () =>
+				render(
+					<GlobalChartsProvider>
+						<TestComponent />
+					</GlobalChartsProvider>
+				);
+
+			it( 'resolves a CSS variable against the provider scope, not the document root', () => {
+				window.getComputedStyle = jest.fn( ( element: Element ) => ( {
+					getPropertyValue: ( prop: string ) =>
+						prop === '--surface' && element !== document.documentElement ? '#1e1e1e' : '#ffffff',
+				} ) ) as unknown as typeof window.getComputedStyle;
+
+				mountProvider();
+
+				expect( contextValue.resolveThemeColor( 'var(--surface, #fff)' ) ).toBe( '#1e1e1e' );
+			} );
+
+			it( 'passes a resolved color through to hex', () => {
+				mountProvider();
+
+				expect( contextValue.resolveThemeColor( '#abcdef' ) ).toBe( '#abcdef' );
+				expect( contextValue.resolveThemeColor( 'rgb(255, 0, 0)' ) ).toBe( '#ff0000' );
+			} );
+
+			it( 'returns an empty string for an empty value', () => {
+				mountProvider();
+
+				expect( contextValue.resolveThemeColor( '' ) ).toBe( '' );
+			} );
+		} );
 	} );
 
 	describe( 'defaultTheme', () => {

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

@@ -4,7 +4,7 @@ import type { CompleteChartTheme } from '../../types';
  * Default theme configuration
  */
 const defaultTheme: CompleteChartTheme = {
-	backgroundColor: 'var(--wpds-color-bg-surface-neutral-strong, #fff)',
+	backgroundColor: 'var(--wpds-color-background-surface-neutral-strong, #fff)',
 	labelBackgroundColor: 'transparent', // label background color (transparent by default)
 	// White label text sits on top of arbitrary series colors, so it has no WPDS
 	// content-foreground equivalent and stays hardcoded (tokenization outlier).
@@ -21,7 +21,7 @@ const defaultTheme: CompleteChartTheme = {
 	xAxisLineStyles: { stroke: 'var(--wpds-color-stroke-surface-neutral, #dbdbdb)', strokeWidth: 1 },
 	legend: {
 		labelStyles: {
-			color: 'var(--wpds-color-fg-content-neutral, #1e1e1e)',
+			color: 'var(--wpds-color-foreground-content-neutral, #1e1e1e)',
 		},
 		containerStyles: {},
 		shapeStyles: [],
@@ -33,24 +33,27 @@ 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(--wpds-color-fg-content-neutral, #1e1e1e)', fontFamily: 'inherit' },
+	svgLabelSmall: {
+		fill: 'var(--wpds-color-foreground-content-neutral, #1e1e1e)',
+		fontFamily: 'inherit',
+	},
 	svgLabelBig: { fontFamily: 'inherit' },
 	annotationStyles: {
 		label: {
-			anchorLineStroke: 'var(--wpds-color-fg-content-neutral, #1e1e1e)',
-			backgroundFill: 'var(--wpds-color-bg-surface-neutral-strong, #fff)',
+			anchorLineStroke: 'var(--wpds-color-foreground-content-neutral, #1e1e1e)',
+			backgroundFill: 'var(--wpds-color-background-surface-neutral-strong, #fff)',
 		},
 		connector: {
-			stroke: 'var(--wpds-color-fg-content-neutral, #1e1e1e)',
+			stroke: 'var(--wpds-color-foreground-content-neutral, #1e1e1e)',
 		},
 		circleSubject: {
 			stroke: 'transparent',
-			fill: 'var(--wpds-color-fg-content-neutral, #1e1e1e)',
+			fill: 'var(--wpds-color-foreground-content-neutral, #1e1e1e)',
 			radius: 5,
 		},
 	},
 	geoChart: {
-		featureFillColor: 'var(--wpds-color-bg-surface-neutral-weak, #f4f4f4)',
+		featureFillColor: 'var(--wpds-color-background-surface-neutral-weak, #f4f4f4)',
 	},
 	leaderboardChart: {
 		rowGap: 12,
@@ -58,15 +61,15 @@ const defaultTheme: CompleteChartTheme = {
 		labelSpacing: 'xs',
 		// [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)',
+			'var(--wpds-color-foreground-content-error-weak, #cc1818)',
+			'var(--wpds-color-foreground-content-neutral-weak, #707070)',
+			'var(--wpds-color-foreground-content-success-weak, #008030)',
 		],
 	},
 	conversionFunnelChart: {
-		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)',
+		backgroundColor: 'var(--wpds-color-background-surface-neutral-weak, #f4f4f4)',
+		positiveChangeColor: 'var(--wpds-color-foreground-content-success-weak, #008030)',
+		negativeChangeColor: 'var(--wpds-color-foreground-content-error-weak, #cc1818)',
 	},
 	lineChart: {
 		lineStyles: {

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

@@ -38,6 +38,9 @@ export interface GlobalChartsContextValue {
 	getChartData: ( id: string ) => ChartRegistration | undefined;
 	theme: CompleteChartTheme;
 	getElementStyles: ( params: GetElementStylesParams ) => ElementStyles;
+	// Resolve a theme color or CSS variable to a hex string in the provider's scope.
+	// Resolves at call time so it tracks ambient theme changes (e.g. a light/dark switch).
+	resolveThemeColor: ( value: string ) => string;
 	// Series visibility management for interactive legends
 	toggleSeriesVisibility: ( chartId: string, seriesLabel: string ) => void;
 	isSeriesVisible: ( chartId: string, seriesLabel: string ) => boolean;

package/src/types.ts

@@ -191,9 +191,10 @@ export type LeaderboardEntry = {
 	currentValue: number;
 
 	/**
-	 * Value of the entry in the previous period
+	 * Value of the entry in the previous period. Omit when this row has no
+	 * matching comparison-period value.
 	 */
-	previousValue: number;
+	previousValue?: number;
 
 	/**
 	 * Width of current bar, as % of the current value
@@ -201,14 +202,16 @@ export type LeaderboardEntry = {
 	currentShare: number;
 
 	/**
-	 * Width of previous bar, as % of the current value
+	 * Width of previous bar, as % of the current value. Omit when this row has
+	 * no matching comparison-period value.
 	 */
-	previousShare: number;
+	previousShare?: number;
 
 	/**
-	 * Delta of the entry
+	 * Delta of the entry. Omit when this row has no matching comparison-period
+	 * value.
 	 */
-	delta: number;
+	delta?: number;
 
 	/**
 	 * Optional color for the entry's image/icon

package/src/utils/color-utils.ts

@@ -233,6 +233,34 @@ export const lightenHexColor = ( hex: string, blend: number ): string => {
 		.padStart( 2, '0' ) }${ newB.toString( 16 ).padStart( 2, '0' ) }`;
 };
 
+/**
+ * Blend one hex color toward another, per-channel in sRGB.
+ *
+ * @param  fromHex - Starting hex color, returned when blend is 0
+ * @param  toHex   - Target hex color, returned when blend is 1
+ * @param  blend   - Amount toward toHex, clamped to [0, 1]
+ * @return Blended hex color string
+ * @throws {Error} if either hex string is malformed
+ */
+export const mixHexColors = ( fromHex: string, toHex: string, blend: number ): string => {
+	validateHexColor( fromHex );
+	validateHexColor( toHex );
+
+	const amount = Math.min( 1, Math.max( 0, blend ) );
+	const channel = ( start: number, end: number ): string =>
+		Math.round( start + ( end - start ) * amount )
+			.toString( 16 )
+			.padStart( 2, '0' );
+
+	return `#${ channel(
+		parseInt( fromHex.slice( 1, 3 ), 16 ),
+		parseInt( toHex.slice( 1, 3 ), 16 )
+	) }${ channel(
+		parseInt( fromHex.slice( 3, 5 ), 16 ),
+		parseInt( toHex.slice( 3, 5 ), 16 )
+	) }${ channel( parseInt( fromHex.slice( 5, 7 ), 16 ), parseInt( toHex.slice( 5, 7 ), 16 ) ) }`;
+};
+
 /**
  * WCAG relative luminance of a hex color (0 = black, 1 = white).
  *

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

@@ -2,6 +2,7 @@ import { hsl as d3Hsl } from '@visx/vendor/d3-color';
 import {
 	getColorDistance,
 	lightenHexColor,
+	mixHexColors,
 	isValidHexColor,
 	hexToRgba,
 	validateHexColor,
@@ -585,6 +586,34 @@ describe( 'lightenHexColor', () => {
 	} );
 } );
 
+describe( 'mixHexColors', () => {
+	it( 'returns the from color at blend 0', () => {
+		expect( mixHexColors( '#ff0000', '#0000ff', 0 ) ).toBe( '#ff0000' );
+	} );
+
+	it( 'returns the to color at blend 1', () => {
+		expect( mixHexColors( '#ff0000', '#0000ff', 1 ) ).toBe( '#0000ff' );
+	} );
+
+	it( 'blends halfway between the two colors', () => {
+		expect( mixHexColors( '#000000', '#ffffff', 0.5 ) ).toBe( '#808080' );
+	} );
+
+	it( 'matches lightenHexColor when the target is white', () => {
+		expect( mixHexColors( '#98c8df', '#ffffff', 0.8 ) ).toBe( lightenHexColor( '#98c8df', 0.8 ) );
+	} );
+
+	it( 'clamps blend outside [0, 1]', () => {
+		expect( mixHexColors( '#123456', '#abcdef', -1 ) ).toBe( '#123456' );
+		expect( mixHexColors( '#123456', '#abcdef', 2 ) ).toBe( '#abcdef' );
+	} );
+
+	it( 'throws on a malformed hex', () => {
+		expect( () => mixHexColors( '#fff', '#000000', 0.5 ) ).toThrow();
+		expect( () => mixHexColors( '#000000', 'nope', 0.5 ) ).toThrow();
+	} );
+} );
+
 describe( 'parseHslString', () => {
 	describe( 'Valid HSL strings', () => {
 		it( 'parses hsl(120, 50%, 50%)', () => {