@automattic/charts 3.2.0 → 4.0.0

package/src/utils/test/bucket-info.test.ts

@@ -0,0 +1,185 @@
+import { getBucketInfo, getBucketResolution } from '../bucket-info';
+import type { SeriesData } from '../../types';
+
+const at = ( hoursFromStart: number ) =>
+	new Date( Date.UTC( 2026, 7, 1 ) + hoursFromStart * 60 * 60 * 1000 );
+
+const seriesOf = ( offsetsInHours: number[] ): SeriesData[] => [
+	{
+		label: 'views',
+		data: offsetsInHours.map( ( offset, index ) => ( { date: at( offset ), value: index } ) ),
+	},
+];
+
+const seriesSpacedHours = ( hours: number, count: number ): SeriesData[] =>
+	seriesOf( Array.from( { length: count }, ( _, index ) => index * hours ) );
+
+const pad = ( value: number ) => String( value ).padStart( 2, '0' );
+
+// Built from local components so it round-trips through `parseAsLocalDate`,
+// which reads a `dateString` as wall-clock time in the runtime's own zone.
+const seriesOfStrings = ( offsetsInHours: number[] ): SeriesData[] => [
+	{
+		label: 'views',
+		data: offsetsInHours.map( ( offset, index ) => {
+			const date = at( offset );
+			return {
+				dateString: `${ date.getFullYear() }-${ pad( date.getMonth() + 1 ) }-${ pad(
+					date.getDate()
+				) }T${ pad( date.getHours() ) }:${ pad( date.getMinutes() ) }:00`,
+				value: index,
+			};
+		} ),
+	},
+];
+
+const stringSeriesSpacedHours = ( hours: number, count: number ): SeriesData[] =>
+	seriesOfStrings( Array.from( { length: count }, ( _, index ) => index * hours ) );
+
+const hourlyDates = ( start: Date, hours: number ): Date[] =>
+	Array.from( { length: hours }, ( _, i ) => new Date( start.getTime() + i * 60 * 60 * 1000 ) );
+
+const dailyDates = ( start: Date, days: number ): Date[] =>
+	Array.from( { length: days }, ( _, i ) => new Date( start.getTime() + i * 24 * 60 * 60 * 1000 ) );
+
+const toSeries = ( dates: Date[] ): SeriesData[] => [
+	{
+		label: 'series',
+		data: dates.map( date => ( { date, value: 1 } ) ),
+	},
+];
+
+describe( 'getBucketInfo', () => {
+	it( 'preserves a declared week in bucket and collapses it for display', () => {
+		const data = seriesSpacedHours( 24 * 7, 6 );
+
+		expect( getBucketInfo( data, 'week' ) ).toEqual( {
+			bucket: 'week',
+			displayResolution: 'day',
+		} );
+	} );
+
+	it( 'passes a declared resolution through unchanged otherwise', () => {
+		const data = seriesSpacedHours( 1, 6 );
+
+		expect( getBucketInfo( data, 'hour' ) ).toEqual( {
+			bucket: 'hour',
+			displayResolution: 'hour',
+		} );
+	} );
+
+	it( 'infers from spacing when nothing is declared', () => {
+		expect( getBucketInfo( seriesSpacedHours( 1, 6 ) ) ).toEqual( {
+			bucket: 'hour',
+			displayResolution: 'hour',
+		} );
+		expect( getBucketInfo( seriesSpacedHours( 24, 6 ) ) ).toEqual( {
+			bucket: 'day',
+			displayResolution: 'day',
+		} );
+	} );
+
+	it( 'infers from dateString points, which the chart parses before it draws them', () => {
+		expect( getBucketInfo( stringSeriesSpacedHours( 1, 6 ) ) ).toEqual( {
+			bucket: 'hour',
+			displayResolution: 'hour',
+		} );
+		expect( getBucketInfo( stringSeriesSpacedHours( 24, 6 ) ) ).toEqual( {
+			bucket: 'day',
+			displayResolution: 'day',
+		} );
+	} );
+
+	it( 'reads a series the same whichever date field carries it', () => {
+		const offsets = [ 0, 1, 2, 3 ];
+
+		expect( getBucketInfo( seriesOfStrings( offsets ) ) ).toEqual(
+			getBucketInfo( seriesOf( offsets ) )
+		);
+	} );
+
+	it( 'never infers week, only reports it when declared', () => {
+		expect( getBucketInfo( seriesSpacedHours( 24 * 7, 6 ) ).bucket ).toBe( 'day' );
+	} );
+
+	it( 'reads the same bucket whatever order the points arrive in', () => {
+		const offsets = [ 0, 24, 48 ];
+		const shuffled = [ 0, 48, 24 ];
+
+		expect( getBucketInfo( seriesOf( shuffled ) ) ).toEqual( getBucketInfo( seriesOf( offsets ) ) );
+		expect( getBucketInfo( seriesOf( shuffled ) ).bucket ).toBe( 'day' );
+	} );
+
+	it( 'ignores a repeated instant, which pads a series rather than dating it', () => {
+		// A shorter comparison series can repeat its last date to match length.
+		expect( getBucketInfo( seriesOf( [ 0, 24, 48, 48 ] ) ).bucket ).toBe( 'day' );
+	} );
+} );
+
+describe( 'getBucketResolution', () => {
+	it( 'infers hourly buckets from sub-daily spacing', () => {
+		expect(
+			getBucketResolution( toSeries( hourlyDates( new Date( '2026-08-02T00:00:00' ), 6 ) ) )
+		).toBe( 'hour' );
+	} );
+
+	it( 'infers daily buckets from daily spacing', () => {
+		expect(
+			getBucketResolution( toSeries( dailyDates( new Date( '2026-08-01T00:00:00' ), 5 ) ) )
+		).toBe( 'day' );
+	} );
+
+	it( 'infers daily buckets from weekly spacing, which labels the same way', () => {
+		const weeklyDates = Array.from(
+			{ length: 5 },
+			( _, i ) => new Date( Date.UTC( 2026, 0, 5 + i * 7 ) )
+		);
+
+		expect( getBucketResolution( toSeries( weeklyDates ) ) ).toBe( 'day' );
+	} );
+
+	it( 'infers monthly buckets from a shortest-month gap', () => {
+		expect(
+			getBucketResolution(
+				toSeries( [ new Date( '2026-02-01T00:00:00' ), new Date( '2026-03-01T00:00:00' ) ] )
+			)
+		).toBe( 'month' );
+	} );
+
+	it( 'infers yearly buckets from a yearly gap', () => {
+		expect(
+			getBucketResolution(
+				toSeries( [ new Date( '2025-06-01T00:00:00' ), new Date( '2026-06-01T00:00:00' ) ] )
+			)
+		).toBe( 'year' );
+	} );
+
+	it( 'keeps a daily gap across spring-forward out of the hourly bucket', () => {
+		const start = new Date( '2026-03-08T00:00:00' );
+		const dstDates = [ 0, 23, 47 ].map(
+			offsetHours => new Date( start.getTime() + offsetHours * 60 * 60 * 1000 )
+		);
+
+		expect( getBucketResolution( toSeries( dstDates ) ) ).toBe( 'day' );
+	} );
+
+	it( 'reports daily buckets when no series has two points', () => {
+		// Unmeasurable spacing reads as Infinity, which must not be mistaken for a
+		// very coarse bucket.
+		expect( getBucketResolution( toSeries( [ new Date( '2026-08-02T00:00:00' ) ] ) ) ).toBe(
+			'day'
+		);
+	} );
+
+	it( 'reports a declared resolution over the measured spacing', () => {
+		const hourly = toSeries( hourlyDates( new Date( '2026-08-02T00:00:00' ), 6 ) );
+
+		expect( getBucketResolution( hourly, 'month' ) ).toBe( 'month' );
+	} );
+
+	it( 'reports a declared weekly resolution as daily', () => {
+		// Weeks and days are both calendar-date buckets as far as labelling goes,
+		// and 'week' is not a label format of its own.
+		expect( getBucketResolution( toSeries( [] ), 'week' ) ).toBe( 'day' );
+	} );
+} );

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

@@ -7,7 +7,6 @@ import {
 	hexToRgba,
 	validateHexColor,
 	parseHslString,
-	parseRgbString,
 	normalizeColorToHex,
 	relativeLuminance,
 	prefersLightText,
@@ -547,7 +546,7 @@ describe( 'lightenHexColor', () => {
 			expect( result ).toBe( '#8080ff' );
 		} );
 
-		it( 'lightens a theme color by 80%', () => {
+		it( 'lightens a color by 80%', () => {
 			const result = lightenHexColor( '#98C8DF', 0.8 );
 			// R: 152 + (255-152)*0.8 = 152 + 82.4 = 234
 			// G: 200 + (255-200)*0.8 = 200 + 44 = 244
@@ -668,52 +667,6 @@ describe( 'parseHslString', () => {
 	} );
 } );
 
-describe( 'parseRgbString', () => {
-	describe( 'Valid RGB strings', () => {
-		it( 'parses rgb(255, 0, 0) to #ff0000', () => {
-			expect( parseRgbString( 'rgb(255, 0, 0)' ) ).toBe( '#ff0000' );
-		} );
-
-		it( 'parses rgb(0, 255, 0) to #00ff00', () => {
-			expect( parseRgbString( 'rgb(0, 255, 0)' ) ).toBe( '#00ff00' );
-		} );
-
-		it( 'parses rgb(0, 0, 255) to #0000ff', () => {
-			expect( parseRgbString( 'rgb(0, 0, 255)' ) ).toBe( '#0000ff' );
-		} );
-
-		it( 'parses rgb with no spaces', () => {
-			expect( parseRgbString( 'rgb(128,128,128)' ) ).toBe( '#808080' );
-		} );
-
-		it( 'clamps values above 255', () => {
-			expect( parseRgbString( 'rgb(300, 0, 0)' ) ).toBe( '#ff0000' );
-		} );
-
-		it( 'clamps negative values to 0', () => {
-			expect( parseRgbString( 'rgb(-50, 0, 0)' ) ).toBe( '#000000' );
-		} );
-	} );
-
-	describe( 'Invalid RGB strings', () => {
-		it( 'returns null for hsl strings', () => {
-			expect( parseRgbString( 'hsl(0, 100%, 50%)' ) ).toBeNull();
-		} );
-
-		it( 'returns null for hex colors', () => {
-			expect( parseRgbString( '#ff0000' ) ).toBeNull();
-		} );
-
-		it( 'returns null for rgba strings', () => {
-			expect( parseRgbString( 'rgba(255, 0, 0, 1)' ) ).toBeNull();
-		} );
-
-		it( 'returns null for empty string', () => {
-			expect( parseRgbString( '' ) ).toBeNull();
-		} );
-	} );
-} );
-
 describe( 'normalizeColorToHex', () => {
 	describe( 'Hex colors', () => {
 		it( 'returns valid 6-digit hex as-is', () => {

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

@@ -0,0 +1,89 @@
+import { createDateFormatter, createZonedClock, sanitizeFormatting } from '../date-formatting';
+
+// `@wordpress/jest-console` 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(
+			{ month: 'short', day: 'numeric' },
+			{ locale: 'de-DE', timeZone: 'Asia/Tokyo' }
+		);
+
+		expect( format( NaN ) ).toBe( 'Invalid Date' );
+		expect( format( new Date( 'nope' ) ) ).toBe( 'Invalid Date' );
+	} );
+} );
+
+describe( 'createZonedClock', () => {
+	it( 'reads calendar fields in the supplied zone', () => {
+		// 00:30 on Aug 3 in Tokyo.
+		expect( createZonedClock( 'Asia/Tokyo' )( new Date( '2026-08-02T15:30:00Z' ) ) ).toEqual( {
+			month: 8,
+			hour: 0,
+		} );
+	} );
+
+	it.each( [
+		[ 'with a zone', 'Asia/Tokyo' ],
+		[ 'without one', undefined ],
+	] )( 'answers NaN for an invalid date %s', ( _label, timeZone ) => {
+		expect( createZonedClock( timeZone )( new Date( 'nope' ) ) ).toEqual( {
+			month: NaN,
+			hour: NaN,
+		} );
+	} );
+} );
+
+describe( 'sanitizeFormatting', () => {
+	it( 'keeps a usable locale and zone', () => {
+		const formatting = { locale: 'de-DE', timeZone: 'Asia/Tokyo' };
+
+		expect( sanitizeFormatting( formatting ) ).toEqual( formatting );
+	} );
+
+	it( 'keeps a UTC offset, which a WordPress site may store instead of a zone name', () => {
+		expect( sanitizeFormatting( { timeZone: '+05:30' } ) ).toEqual( {
+			locale: undefined,
+			timeZone: '+05:30',
+		} );
+	} );
+
+	it( 'repairs the underscored locale WordPress reports', () => {
+		expect( sanitizeFormatting( { locale: 'en_US', timeZone: 'Asia/Tokyo' } ) ).toEqual( {
+			locale: 'en-US',
+			timeZone: 'Asia/Tokyo',
+		} );
+	} );
+
+	it( 'drops a locale no underscore swap can rescue, keeping the zone', () => {
+		expect( sanitizeFormatting( { locale: 'nope!', timeZone: 'Asia/Tokyo' } ) ).toEqual( {
+			locale: undefined,
+			timeZone: 'Asia/Tokyo',
+		} );
+		expect( console ).toHaveWarned();
+	} );
+
+	it( 'drops the empty zone a site set to a manual offset reports, keeping the locale', () => {
+		expect( sanitizeFormatting( { locale: 'de-DE', timeZone: '' } ) ).toEqual( {
+			locale: 'de-DE',
+			timeZone: undefined,
+		} );
+		expect( console ).toHaveWarned();
+	} );
+
+	it( 'drops both when neither is usable', () => {
+		expect( sanitizeFormatting( { locale: '', timeZone: 'Mars/Olympus' } ) ).toEqual( {
+			locale: undefined,
+			timeZone: undefined,
+		} );
+		expect( console ).toHaveWarned();
+	} );
+} );

package/src/utils/test/get-styles.test.ts

@@ -13,8 +13,11 @@ describe( 'Series styling utility functions', () => {
 		options: {},
 	};
 
+	// `getSeriesStroke` takes the resolved palette as an argument rather than reading it
+	// off the theme, so this is a plain array of colors.
+	const palette = [ '#FF0000', '#00FF00', '#0000FF' ];
+
 	const mockTheme: Partial< ChartTheme > = {
-		colors: [ '#FF0000', '#00FF00', '#0000FF' ],
 		lineChart: {
 			lineStyles: {
 				comparison: {
@@ -40,17 +43,17 @@ describe( 'Series styling utility functions', () => {
 				options: { stroke: '#CUSTOM' },
 			};
 
-			const result = getSeriesStroke( seriesWithStroke, 0, mockTheme.colors );
+			const result = getSeriesStroke( seriesWithStroke, 0, palette );
 			expect( result ).toBe( '#CUSTOM' );
 		} );
 
-		it( 'returns theme color by index when no custom stroke', () => {
-			const result = getSeriesStroke( mockSeriesData, 1, mockTheme.colors );
+		it( 'returns the palette color by index when no custom stroke', () => {
+			const result = getSeriesStroke( mockSeriesData, 1, palette );
 			expect( result ).toBe( '#00FF00' ); // Second color
 		} );
 
-		it( 'wraps around theme colors when index exceeds array length', () => {
-			const result = getSeriesStroke( mockSeriesData, 5, mockTheme.colors );
+		it( 'wraps around the palette when index exceeds its length', () => {
+			const result = getSeriesStroke( mockSeriesData, 5, palette );
 			expect( result ).toBe( '#0000FF' ); // 5 % 3 = 2, third color
 		} );
 	} );
@@ -92,7 +95,7 @@ describe( 'Series styling utility functions', () => {
 		} );
 
 		it( 'returns empty object when no styles available', () => {
-			const themeWithoutStyles = { colors: [ '#FF0000' ] } as ChartTheme;
+			const themeWithoutStyles = { tickLength: 4 } as ChartTheme;
 			const result = getSeriesLineStyles( mockSeriesData, 0, themeWithoutStyles );
 			expect( result ).toEqual( {} );
 		} );

package/src/utils/test/merge-themes.test.ts

@@ -3,33 +3,24 @@ import type { ChartTheme } from '../../types';
 
 describe( 'mergeThemes', () => {
 	const baseTheme: ChartTheme = {
-		backgroundColor: '#FFFFFF',
-		colors: [ '#red', '#blue' ],
 		gridStyles: {
-			stroke: '#DCDCDE',
 			strokeWidth: 1,
 		},
 		tickLength: 4,
-		gridColor: '',
-		gridColorDark: '',
-		leaderboardChart: {
-			primaryColor: '#global-primary',
-			secondaryColor: '#global-secondary',
+		seriesLineStyles: [ { strokeWidth: 1 }, { strokeWidth: 2 } ],
+		sparkline: {
+			strokeWidth: 1.5,
+			margin: { top: 2, right: 2, bottom: 2, left: 2 },
 		},
 	};
 
 	const overrideTheme: ChartTheme = {
-		backgroundColor: '#F0F0F0',
-		colors: [ '#green', '#yellow' ],
 		gridStyles: {
-			stroke: '#000000',
 			strokeWidth: 2,
 		},
 		tickLength: 8,
-		gridColor: '',
-		gridColorDark: '',
-		leaderboardChart: {
-			primaryColor: '#local-primary',
+		sparkline: {
+			strokeWidth: 3,
 		},
 	};
 
@@ -41,60 +32,41 @@ describe( 'mergeThemes', () => {
 	it( 'should merge themes with local theme taking precedence for top-level properties', () => {
 		const result = mergeThemes( baseTheme, overrideTheme );
 
-		expect( result.backgroundColor ).toBe( '#F0F0F0' ); // from local
-		expect( result.tickLength ).toBe( 8 ); // from local
-		expect( result.colors ).toEqual( [ '#green', '#yellow' ] ); // from local (array replacement)
+		expect( result.tickLength ).toBe( 8 );
 	} );
 
 	it( 'should deeply merge nested objects with local theme taking precedence', () => {
 		const result = mergeThemes( baseTheme, overrideTheme );
 
-		// gridStyles should be merged
-		expect( result.gridStyles ).toEqual( {
-			stroke: '#000000', // from local
-			strokeWidth: 2, // from local
-		} );
+		expect( result.gridStyles ).toEqual( { strokeWidth: 2 } );
 
-		// leaderboardChart should be merged
-		expect( result.leaderboardChart ).toEqual( {
-			primaryColor: '#local-primary', // from local
-			secondaryColor: '#global-secondary', // from global (not overridden)
+		expect( result.sparkline ).toEqual( {
+			strokeWidth: 3, // from local
+			margin: { top: 2, right: 2, bottom: 2, left: 2 }, // from global (not overridden)
 		} );
 	} );
 
 	it( 'should use global theme properties when not defined in local theme', () => {
 		const partialLocalTheme: ChartTheme = {
-			backgroundColor: '#F0F0F0',
-			colors: [ '#green' ],
 			tickLength: 8,
-			gridColor: '',
-			gridColorDark: '',
 		};
 
 		const result = mergeThemes( baseTheme, partialLocalTheme );
 
-		expect( result.backgroundColor ).toBe( '#F0F0F0' ); // from local
-		expect( result.gridStyles ).toEqual( baseTheme.gridStyles ); // from global
-		expect( result.leaderboardChart ).toEqual( baseTheme.leaderboardChart ); // from global
+		expect( result.tickLength ).toBe( 8 );
+		expect( result.gridStyles ).toEqual( baseTheme.gridStyles );
+		expect( result.leaderboardChart ).toEqual( baseTheme.leaderboardChart );
 	} );
 
 	it( 'should handle array replacement correctly', () => {
-		const globalWithColors: ChartTheme = {
-			...baseTheme,
-			colors: [ '#red', '#blue', '#purple' ],
-		};
-
-		const localWithFewerColors: ChartTheme = {
+		const localWithFewerStyles: ChartTheme = {
 			...overrideTheme,
-			colors: [ '#green' ],
+			seriesLineStyles: [ { strokeWidth: 5 } ],
 		};
 
-		const result = mergeThemes( globalWithColors, localWithFewerColors );
+		const result = mergeThemes( baseTheme, localWithFewerStyles );
 
 		// Arrays should be replaced, not concatenated
-		expect( result.colors ).toEqual( [ '#green' ] );
-		expect( result.colors ).not.toContain( '#red' );
-		expect( result.colors ).not.toContain( '#blue' );
-		expect( result.colors ).not.toContain( '#purple' );
+		expect( result.seriesLineStyles ).toEqual( [ { strokeWidth: 5 } ] );
 	} );
 } );

package/src/visx/types.ts

@@ -24,8 +24,35 @@ export type XyChartTooltipProps< Datum extends object > = {
 	verticalCrosshairStyle?: SVGProps< SVGLineElement >;
 	horizontalCrosshairStyle?: SVGProps< SVGLineElement >;
 	glyphStyle?: SVGProps< SVGCircleElement >;
+	/**
+	 * Flip and clamp the tooltip box so it stays inside the nearest ancestor
+	 * that clips its overflow, or the viewport when there is none. The box may
+	 * leave the chart wrapper. (It used to keep a body-level portal inside the
+	 * viewport.)
+	 * @default true
+	 */
+	detectBounds?: boolean;
+	/**
+	 * Stacking order of the tooltip box inside the chart wrapper, which isolates
+	 * its stacking context: the value never competes with page chrome outside
+	 * the chart.
+	 * @default 3
+	 */
+	zIndex?: number;
+	/**
+	 * @deprecated Accepted and ignored. The box renders inside the chart wrapper
+	 * and moves with it, so it needs no scroll tracking.
+	 */
+	scroll?: boolean;
+	/**
+	 * @deprecated Accepted and ignored. Nothing measures the box any more, so
+	 * there is no measurement to debounce.
+	 */
+	debounce?: number;
+	/**
+	 * @deprecated Accepted and ignored. No ResizeObserver is used.
+	 */
 	resizeObserverPolyfill?: UseTooltipPortalOptions[ 'polyfill' ];
-} & Omit< VisxTooltipProps, 'left' | 'top' | 'children' > &
-	Pick< UseTooltipPortalOptions, 'debounce' | 'detectBounds' | 'scroll' | 'zIndex' >;
+} & Omit< VisxTooltipProps, 'left' | 'top' | 'children' | 'applyPositionStyle' >;
 
 export type { LineStyles, GridStyles } from '@visx/xychart';

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

@@ -1,28 +0,0 @@
-import { renderHook } from '@testing-library/react';
-import { GlobalChartsProvider } from '../../providers/chart-context/global-charts-provider';
-import { ChartScopeContext } from '../../providers/chart-scope';
-import { useXYChartTheme } from '../use-xychart-theme';
-import type { ReactNode } from 'react';
-
-// A `theme` prop override reaches CSS-painted elements through the inline `--a8c-charts-*` var GlobalChartsProvider writes on its wrapper, and reaches the values our own components read through `providerTheme`. Before the fix, `providerTheme` carried the override's literal directly, so an element-level `--a8c-charts-color-background` override set inside the provider tree had no effect on the JS-resolved value — the two paths could disagree. After the fix, `providerTheme` carries the catalog pointer for an overridden role, so both paths resolve through the same CSS cascade and the nearer element wins.
-describe( 'useXYChartTheme resolves a theme prop override through the CSS cascade', () => {
-	it( "an element override set inside the provider tree beats the provider's theme prop literal", () => {
-		const nestedOverride = document.createElement( 'div' );
-		nestedOverride.style.setProperty( '--a8c-charts-color-background', '#00ff00' );
-		document.body.appendChild( nestedOverride );
-
-		const wrapper = ( { children }: { children: ReactNode } ) => (
-			<GlobalChartsProvider theme={ { backgroundColor: 'rgb(255,0,0)' } }>
-				<ChartScopeContext.Provider value={ nestedOverride }>
-					{ children }
-				</ChartScopeContext.Provider>
-			</GlobalChartsProvider>
-		);
-
-		const { result } = renderHook( () => useXYChartTheme( [] ), { wrapper } );
-
-		expect( result.current.backgroundColor ).toBe( '#00ff00' );
-
-		document.body.removeChild( nestedOverride );
-	} );
-} );