@automattic/charts 2.0.0 → 3.0.0

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

@@ -29,7 +29,7 @@ import {
 	useGlobalChartsContext,
 	useGlobalChartsTheme,
 } from '../../providers';
-import { attachSubComponents, resolveCssVariable } from '../../utils';
+import { attachSubComponents } from '../../utils';
 import { useChartChildren } from '../private/chart-composition';
 import { ChartLayout } from '../private/chart-layout';
 import { DefaultGlyph } from '../private/default-glyph';
@@ -192,11 +192,9 @@ const LineChartInternal = forwardRef< SingleChartRef, LineChartProps >(
 		const legendPosition = legend.position ?? 'bottom';
 
 		const providerTheme = useGlobalChartsTheme();
-		// Gradient stops apply this as an SVG attribute, where CSS var() cannot
-		// resolve, so resolve the WPDS token to a concrete value first.
-		const resolvedBackgroundColor =
-			resolveCssVariable( providerTheme.backgroundColor ) ?? providerTheme.backgroundColor;
 		const theme = useXYChartTheme( data );
+		// Gradient stops apply this as an SVG attribute, where CSS var() cannot resolve. useXYChartTheme has already resolved the same role inside its memo, against the chart's scope element, so read it back rather than paying another getComputedStyle on every render.
+		const resolvedBackgroundColor = theme.backgroundColor ?? providerTheme.backgroundColor;
 		const chartId = useChartId( providedChartId );
 		const chartRef = useRef< HTMLDivElement >( null );
 		const [ selectedIndex, setSelectedIndex ] = useState< number | undefined >( undefined );

package/src/charts/line-chart/private/line-chart-annotation.tsx

@@ -9,7 +9,7 @@ import {
 import { DataContext } from '@visx/xychart';
 import merge from 'deepmerge';
 import { useContext, useRef, useEffect, useState, useMemo } from 'react';
-import { useGlobalChartsTheme } from '../../../providers';
+import { useChartScopeElement, useGlobalChartsTheme } from '../../../providers';
 import { isSafari, resolveCssVariable } from '../../../utils';
 import LineChartAnnotationLabelWithPopover, {
 	POPOVER_BUTTON_SIZE,
@@ -152,6 +152,7 @@ const LineChartAnnotation: FC< LineChartAnnotationProps > = ( {
 	renderLabelPopover,
 } ) => {
 	const providerTheme = useGlobalChartsTheme();
+	const scopeElement = useChartScopeElement();
 	const { xScale, yScale } = useContext( DataContext ) || {};
 	const labelRef = useRef< SVGGElement >( null );
 	const [ height, setHeight ] = useState< number | null >( null );
@@ -159,10 +160,9 @@ const LineChartAnnotation: FC< LineChartAnnotationProps > = ( {
 	// Deep merge styles to preserve nested object properties
 	const styles = merge( providerTheme.annotationStyles ?? {}, datumStyles ?? {} );
 
-	// visx annotation parts apply these colors as SVG presentation attributes,
-	// where CSS var() cannot resolve. Resolve WPDS tokens to concrete values first.
+	// visx annotation parts apply these colours as SVG presentation attributes, where CSS var() cannot resolve. Resolve against the chart's scope element, never :root.
 	const resolveColor = ( value?: string ): string | undefined =>
-		value ? resolveCssVariable( value ) ?? value : value;
+		value ? resolveCssVariable( value, scopeElement ) ?? value : value;
 
 	// Measure the label height once after initial render
 	useEffect( () => {

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

@@ -19,6 +19,7 @@ import {
 	useGlobalChartsTheme,
 	GlobalChartsContext,
 } from '../../providers';
+import { CHART_SCOPE_CLASS } from '../../styles/chart-scope-class';
 import { attachSubComponents, resolveFontSize } from '../../utils';
 import { getStringWidth } from '../../visx/text';
 import { Center } from '../private/center';
@@ -328,7 +329,9 @@ const PieChartInternal = ( {
 					<>
 						{ withTooltips && tooltipOpen && tooltipData && (
 							<TooltipInPortal top={ tooltipTop || 0 } left={ tooltipLeft || 0 }>
-								<div role="tooltip">{ renderTooltip( { tooltipData } ) }</div>
+								<div className={ CHART_SCOPE_CLASS } role="tooltip">
+									{ renderTooltip( { tooltipData } ) }
+								</div>
 							</TooltipInPortal>
 						) }
 						{ htmlChildren }

package/src/charts/pie-semi-circle-chart/pie-semi-circle-chart.tsx

@@ -19,6 +19,7 @@ import {
 	useGlobalChartsContext,
 	GlobalChartsContext,
 } from '../../providers';
+import { CHART_SCOPE_CLASS } from '../../styles/chart-scope-class';
 import { attachSubComponents } from '../../utils';
 import { Center } from '../private/center';
 import { ChartSVG, ChartHTML, useChartChildren } from '../private/chart-composition';
@@ -375,7 +376,9 @@ const PieSemiCircleChartInternal: FC< PieSemiCircleChartProps > = ( {
 					<>
 						{ withTooltips && tooltipOpen && tooltipData && (
 							<TooltipInPortal top={ tooltipTop || 0 } left={ tooltipLeft || 0 }>
-								<div role="tooltip">{ renderTooltip( { tooltipData } ) }</div>
+								<div className={ CHART_SCOPE_CLASS } role="tooltip">
+									{ renderTooltip( { tooltipData } ) }
+								</div>
 							</TooltipInPortal>
 						) }
 						{ htmlChildren }

package/src/charts/private/svg-empty-state/svg-empty-state.module.scss

@@ -1,5 +1,5 @@
 .svg-empty-state {
 	text-align: center;
 	font-size: var(--wpds-typography-font-size-md, 13px);
-	color: var(--a8c-charts-color-label-secondary, var(--wpds-color-foreground-content-neutral-weak, #707070));
+	color: var(--a8c-charts-color-label-secondary);
 }

package/src/charts/private/test/time-axis.test.ts

@@ -1,4 +1,4 @@
-import { getFormatter } from '../time-axis';
+import { getBandTickValues, getBucketResolution, getFormatter } from '../time-axis';
 import type { useChartDataTransform } from '../../../hooks';
 
 type SortedData = ReturnType< typeof useChartDataTransform >;
@@ -17,7 +17,7 @@ const hourlyDates = ( start: Date, hours: number ): Date[] =>
 const dailyDates = ( start: Date, days: number ): Date[] =>
 	Array.from( { length: days }, ( _, i ) => new Date( start.getTime() + i * 24 * 60 * 60 * 1000 ) );
 
-// TZ is pinned to UTC by the test script, so local formatting is deterministic.
+// The test script pins TZ and locale, so local formatting is deterministic.
 describe( 'getFormatter', () => {
 	it( 'uses hour ticks within a single day', () => {
 		const formatter = getFormatter(
@@ -124,6 +124,46 @@ describe( 'getFormatter', () => {
 		expect( yearly( new Date( '2023-01-01T00:00:00' ).getTime() ) ).toBe( '2023' );
 	} );
 
+	it( 'keeps month ticks for monthly buckets spanning several years', () => {
+		const monthlyDates = Array.from(
+			{ length: 36 },
+			( _, i ) => new Date( Date.UTC( 2024, i, 1 ) )
+		);
+		const formatter = getFormatter( toSeries( monthlyDates ) );
+
+		// Year ticks here would render the same year for every tick the band scale
+		// samples out of a calendar year.
+		expect( formatter( new Date( '2024-10-01T00:00:00' ).getTime() ) ).toBe( 'Oct' );
+		expect( formatter( new Date( '2025-01-01T00:00:00' ).getTime() ) ).toBe( '2025' );
+	} );
+
+	it( 'uses year ticks for inferred yearly buckets that do not start in January', () => {
+		const formatter = getFormatter(
+			toSeries( [ new Date( '2023-07-01T00:00:00' ), new Date( '2024-07-01T00:00:00' ) ] )
+		);
+
+		// The month regime would print a bare "Jul" for both.
+		expect( formatter( new Date( '2023-07-01T00:00:00' ).getTime() ) ).toBe( '2023' );
+		expect( formatter( new Date( '2024-07-01T00:00:00' ).getTime() ) ).toBe( '2024' );
+	} );
+
+	it( 'ignores series with no dated points when measuring the span', () => {
+		const formatter = getFormatter( [
+			...toSeries( dailyDates( new Date( '2024-01-01T00:00:00' ), 14 ) ),
+			...toSeries( [] ),
+		] );
+
+		// An empty comparison series must not turn the span into NaN, which would
+		// fall through every span check to year ticks.
+		expect( formatter( new Date( '2024-01-03T00:00:00' ).getTime() ) ).toMatch( /Jan 3/ );
+	} );
+
+	it( 'falls back to date ticks when nothing is dated', () => {
+		const formatter = getFormatter( toSeries( [] ) );
+
+		expect( formatter( new Date( '2024-01-03T00:00:00' ).getTime() ) ).toMatch( /Jan 3/ );
+	} );
+
 	describe( 'with an explicit tickResolution', () => {
 		it( 'uses hour ticks for two hourly points a day apart, where spacing would read as daily', () => {
 			const formatter = getFormatter(
@@ -180,3 +220,208 @@ describe( 'getFormatter', () => {
 		} );
 	} );
 } );
+
+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' );
+	} );
+} );
+
+describe( 'tick format anchors', () => {
+	// The band axis steers ticks onto boundaries using the predicate the format
+	// hangs off itself. If the two ever disagree, the axis aims at buckets that
+	// do not actually print the coarser label.
+	it( 'marks exactly the buckets whose label carries the coarser unit', () => {
+		const hourly = Array.from( { length: 48 }, ( _, i ) => new Date( 2026, 7, 2, i ) );
+		const hourFormat = getFormatter( toSeries( hourly ) );
+
+		expect( hourFormat.isAnchor ).toBeDefined();
+		hourly.forEach( date => {
+			const isDateLabel = ! /(AM|PM)/.test( hourFormat( date.getTime() ) );
+			expect( hourFormat.isAnchor( date ) ).toBe( isDateLabel );
+		} );
+
+		const monthly = Array.from( { length: 36 }, ( _, i ) => new Date( 2023, 6 + i, 1 ) );
+		const monthFormat = getFormatter( toSeries( monthly ) );
+
+		expect( monthFormat.isAnchor ).toBeDefined();
+		monthly.forEach( date => {
+			const isYearLabel = /^\d{4}$/.test( monthFormat( date.getTime() ) );
+			expect( monthFormat.isAnchor( date ) ).toBe( isYearLabel );
+		} );
+	} );
+} );
+
+describe( 'getBandTickValues', () => {
+	const monthlyDomain = ( year: number, month: number, months: number ) =>
+		Array.from( { length: months }, ( _, i ) => new Date( year, month + i, 1 ) );
+
+	const hourlyDomain = ( start: Date, hours: number ) =>
+		Array.from( { length: hours }, ( _, i ) => new Date( start.getTime() + i * 60 * 60 * 1000 ) );
+
+	const labelsFor = ( domain: Date[], maxTicks = 4 ) => {
+		const formatter = getFormatter( toSeries( domain ) );
+		return getBandTickValues( domain, formatter, maxTicks ).map( date =>
+			formatter( date.getTime() )
+		);
+	};
+
+	it( 'shifts the sampling offset onto January for a monthly series starting mid-year', () => {
+		// Sampling from index 0 gives Aug, Nov, Feb, May, Aug — no year at all on a
+		// series that crosses one, and "Aug" twice.
+		expect( labelsFor( monthlyDomain( 2025, 7, 13 ) ) ).toContain( '2026' );
+	} );
+
+	it( 'lands on every January of a multi-year monthly series that starts mid-year', () => {
+		expect( labelsFor( monthlyDomain( 2023, 6, 36 ) ) ).toEqual( [ '2024', '2025', '2026' ] );
+	} );
+
+	it( 'keeps the dated midnight ticks for sub-daily data spanning days', () => {
+		// Index sampling already lands here; this pins that the steering keeps it.
+		expect( labelsFor( hourlyDomain( new Date( 2026, 7, 2 ), 48 ) ) ).toEqual( [
+			'Aug 2',
+			'12 PM',
+			'Aug 3',
+			'12 PM',
+		] );
+	} );
+
+	it( 'steps whole days once a sub-daily span is too long to date any other way', () => {
+		// No step inside a day fits four ticks across a week, so the offset sweep
+		// alone would leave every tick but the first a bare hour on an unnamed day.
+		expect( labelsFor( hourlyDomain( new Date( 2026, 7, 2 ), 168 ) ) ).toEqual( [
+			'Aug 2',
+			'Aug 4',
+			'Aug 6',
+			'Aug 8',
+		] );
+	} );
+
+	it( 'steps whole years once a monthly span is too long to reach January any other way', () => {
+		expect( labelsFor( monthlyDomain( 2023, 6, 120 ) ) ).toEqual( [
+			'2024',
+			'2027',
+			'2030',
+			'2033',
+		] );
+	} );
+
+	it( 'still names a year at the lowest tick counts a caller can ask for', () => {
+		// An anchor outranks a denser axis, so without a step that reaches two of
+		// them a two-tick axis would settle for a single January.
+		expect( labelsFor( monthlyDomain( 2023, 6, 36 ), 2 ) ).toEqual( [ '2024', '2026' ] );
+		expect( labelsFor( monthlyDomain( 2023, 6, 36 ), 3 ) ).toEqual( [ '2024', '2025', '2026' ] );
+	} );
+
+	it( 'never repeats a label on adjacent ticks', () => {
+		// 49 buckets put every fourth tick a whole year apart, so sampling by index
+		// spells the same month five times over: Feb, Feb, Feb, Feb, Feb.
+		const labels = labelsFor( monthlyDomain( 2023, 1, 49 ) );
+
+		expect( labels.some( ( label, i ) => i > 0 && label === labels[ i - 1 ] ) ).toBe( false );
+	} );
+
+	it( 'keeps the axis dense when only a sparser one could reach an anchor', () => {
+		// Ranking anchors above everything picked the two ticks that happened to be
+		// Januaries and dropped the rest of the axis with them.
+		expect( labelsFor( monthlyDomain( 2023, 3, 30 ) ) ).toEqual( [ 'Apr', '2024', 'Oct', 'Jul' ] );
+	} );
+
+	it( 'names the single year of a short series without thinning the axis to it', () => {
+		expect( labelsFor( monthlyDomain( 2023, 6, 9 ) ) ).toEqual( [ 'Jul', 'Oct', '2024' ] );
+	} );
+
+	it( 'reaches anchors that sit an uneven number of buckets apart', () => {
+		// A spring-forward day is 23 hourly buckets, not 24, so a fixed stride
+		// slides off midnight and leaves the rest of the week on bare hours.
+		const domain: Date[] = [];
+		for ( let day = 0; day < 7; day++ ) {
+			for ( let hour = 0; hour < 24; hour++ ) {
+				if ( day !== 2 || hour !== 2 ) {
+					domain.push( new Date( 2026, 2, 6 + day, hour ) );
+				}
+			}
+		}
+
+		expect( labelsFor( domain ) ).toEqual( [ 'Mar 6', 'Mar 8', 'Mar 10', 'Mar 12' ] );
+	} );
+
+	it( 'keeps the whole domain when it already fits', () => {
+		const domain = monthlyDomain( 2023, 0, 4 );
+
+		expect( getBandTickValues( domain, String, 4 ) ).toEqual( domain );
+	} );
+
+	it( 'never exceeds the requested tick count', () => {
+		const domain = monthlyDomain( 2023, 6, 36 );
+
+		expect( getBandTickValues( domain, String, 4 ).length ).toBeLessThanOrEqual( 4 );
+		expect( getBandTickValues( domain, String, 7 ).length ).toBeLessThanOrEqual( 7 );
+	} );
+
+	it( 'returns nothing for an empty domain', () => {
+		expect( getBandTickValues( [], String, 4 ) ).toEqual( [] );
+	} );
+} );