@automattic/charts 1.8.0 → 1.9.0

package/src/charts/heatmap-chart/test/build-calendar-data.test.ts

@@ -0,0 +1,88 @@
+import { buildCalendarHeatmapData } from '../private/build-calendar-data';
+import type { DataPointDate } from '../../../types';
+
+const series: DataPointDate[] = [
+	{ dateString: '2024-01-01', value: 3 }, // Mon
+	{ dateString: '2024-01-03', value: 5 }, // Wed
+	{ dateString: '2024-01-15', value: 2 }, // Mon (3rd week)
+];
+
+describe( 'buildCalendarHeatmapData', () => {
+	test( 'returns empty result for empty input', () => {
+		expect( buildCalendarHeatmapData( [] ) ).toEqual( { data: [], rowLabels: [] } );
+	} );
+
+	test( 'groups days into week columns of 7 rows', () => {
+		const { data } = buildCalendarHeatmapData( series );
+		expect( data ).toHaveLength( 3 ); // weeks containing Jan 1, Jan 8, Jan 15
+		data.forEach( column => expect( column.data ).toHaveLength( 7 ) );
+	} );
+
+	test( 'Monday week start places Jan 1 (Mon) in row 0', () => {
+		const { data, rowLabels } = buildCalendarHeatmapData( series, { weekStartsOn: 1 } );
+		expect( data[ 0 ].data[ 0 ].value ).toBe( 3 );
+		expect( data[ 0 ].data[ 2 ].value ).toBe( 5 ); // Wed
+		expect( rowLabels[ 0 ] ).toBe( 'Mon' );
+		expect( rowLabels[ 2 ] ).toBe( 'Wed' );
+		expect( rowLabels[ 4 ] ).toBe( 'Fri' );
+		expect( rowLabels[ 1 ] ).toBe( '' );
+	} );
+
+	test( 'fills missing days with null', () => {
+		const { data } = buildCalendarHeatmapData( series );
+		expect( data[ 0 ].data[ 1 ].value ).toBeNull(); // Tue Jan 2 has no datum
+	} );
+
+	test( 'labels only the first column of each month', () => {
+		const multiMonth: DataPointDate[] = [
+			{ dateString: '2024-01-29', value: 1 },
+			{ dateString: '2024-02-05', value: 1 },
+		];
+		const { data } = buildCalendarHeatmapData( multiMonth );
+		expect( data[ 0 ].label ).toBe( 'Jan' );
+		const labels = data.map( c => c.label ).filter( Boolean );
+		expect( labels ).toContain( 'Feb' );
+	} );
+
+	test( 'filters out entries with unparseable or missing dates', () => {
+		const mixed: DataPointDate[] = [
+			{ dateString: '2024-01-01', value: 3 },
+			{ dateString: 'not-a-date', value: 9 },
+			{ date: new Date( NaN ), value: 7 },
+			{ value: 1 }, // neither date nor dateString
+		];
+		const { data } = buildCalendarHeatmapData( mixed );
+		expect( data ).toHaveLength( 1 ); // only Jan 1 survives -> one week column
+		const values = data.flatMap( column => column.data.map( cell => cell.value ) );
+		expect( values ).toContain( 3 );
+		expect( values ).not.toContain( 9 );
+		expect( values ).not.toContain( 7 );
+	} );
+
+	test( 'returns empty result when every entry has an invalid date', () => {
+		const allInvalid: DataPointDate[] = [
+			{ dateString: 'nope', value: 1 },
+			{ date: new Date( NaN ), value: 2 },
+		];
+		expect( buildCalendarHeatmapData( allInvalid ) ).toEqual( { data: [], rowLabels: [] } );
+	} );
+
+	test( 'duplicate days keep the last value (no aggregation)', () => {
+		const dupes: DataPointDate[] = [
+			{ dateString: '2024-01-01', value: 3 },
+			{ dateString: '2024-01-01', value: 8 },
+		];
+		const { data } = buildCalendarHeatmapData( dupes, { weekStartsOn: 1 } );
+		expect( data[ 0 ].data[ 0 ].value ).toBe( 8 ); // last write wins, not summed to 11
+	} );
+
+	test( 'Sunday week start shifts rows and labels (Sun/Tue/Thu)', () => {
+		// gridStart snaps to Sun Dec 31 2023, so Mon Jan 1 lands in row 1.
+		const { data, rowLabels } = buildCalendarHeatmapData( series, { weekStartsOn: 0 } );
+		expect( data[ 0 ].data[ 1 ].value ).toBe( 3 ); // Mon Jan 1
+		expect( data[ 0 ].data[ 3 ].value ).toBe( 5 ); // Wed Jan 3
+		expect( rowLabels[ 0 ] ).toBe( 'Sun' );
+		expect( rowLabels[ 2 ] ).toBe( 'Tue' );
+		expect( rowLabels[ 4 ] ).toBe( 'Thu' );
+	} );
+} );

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

@@ -0,0 +1,301 @@
+import { render, screen, within } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { GlobalChartsProvider } from '../../../providers';
+import HeatmapChart, { HeatmapChartUnresponsive } from '../heatmap-chart';
+import type { HeatmapColumn } from '../types';
+
+const mockRefCallback = jest.fn();
+jest.mock( '../../../hooks/use-element-size', () => ( {
+	useElementSize: () => [ mockRefCallback, 500, 300 ],
+} ) );
+
+const data: HeatmapColumn[] = [
+	{ label: 'W1', data: [ { value: 1 }, { value: 2 }, { value: null } ] },
+	{ label: 'W2', data: [ { value: 3 }, { value: 0 }, { value: 4 } ] },
+];
+
+const renderChart = ( props = {} ) =>
+	render(
+		<GlobalChartsProvider>
+			<HeatmapChart width={ 500 } height={ 300 } data={ data } { ...props } />
+		</GlobalChartsProvider>
+	);
+
+describe( 'HeatmapChart', () => {
+	test( 'renders a grid with an accessible label', () => {
+		renderChart();
+		expect( screen.getByRole( 'grid', { name: /heatmap/i } ) ).toBeInTheDocument();
+	} );
+
+	test( 'renders one cell per data point', () => {
+		renderChart();
+		// 2 columns x 3 rows = 6 cells
+		expect( screen.getAllByTestId( 'heatmap-cell' ) ).toHaveLength( 6 );
+	} );
+
+	test( 'shows an empty-state message for empty data', () => {
+		renderChart( { data: [] } );
+		expect( screen.getByText( /no data available/i ) ).toBeInTheDocument();
+	} );
+
+	test( 'renders column and row labels', () => {
+		renderChart( { rowLabels: [ 'Mon', '', 'Wed' ] } );
+		expect( screen.getAllByText( 'W1' ).length ).toBeGreaterThan( 0 );
+		expect( screen.getAllByText( 'Mon' ).length ).toBeGreaterThan( 0 );
+		expect( screen.getAllByText( 'Wed' ).length ).toBeGreaterThan( 0 );
+	} );
+
+	test( 'shows in-cell values by default and hides them in compact mode', () => {
+		const { rerender } = renderChart();
+		// value 3 appears in a cell
+		expect( screen.getAllByText( '3' ).length ).toBeGreaterThan( 0 );
+
+		rerender(
+			<GlobalChartsProvider>
+				<HeatmapChart width={ 500 } height={ 300 } data={ data } compact />
+			</GlobalChartsProvider>
+		);
+		expect( screen.queryByText( '3' ) ).not.toBeInTheDocument();
+	} );
+
+	test( 'formats large in-cell values compactly', () => {
+		render(
+			<GlobalChartsProvider>
+				<HeatmapChart
+					width={ 500 }
+					height={ 300 }
+					data={ [ { label: 'W1', data: [ { value: 748500 } ] } ] }
+				/>
+			</GlobalChartsProvider>
+		);
+		expect( screen.getByText( /748\.5\s?K/i ) ).toBeInTheDocument();
+	} );
+
+	test( 'gives each cell an accessible name for screen readers', () => {
+		renderChart( { rowLabels: [ 'Mon', 'Tue', 'Wed' ] } );
+		// The gridcell's accessible name is its aria-label (column + row + value).
+		expect( screen.getByRole( 'gridcell', { name: 'W1 Mon: 1' } ) ).toBeInTheDocument();
+	} );
+
+	test( 'shows a tooltip on cell hover when withTooltips is set', async () => {
+		renderChart( { withTooltips: true, rowLabels: [ 'Mon', 'Tue', 'Wed' ] } );
+		const cell = screen.getAllByTestId( 'heatmap-cell' )[ 0 ];
+		await userEvent.setup().hover( cell );
+		await expect( screen.findByRole( 'tooltip' ) ).resolves.toBeInTheDocument();
+	} );
+
+	test( 'shows a tooltip on keyboard navigation when withTooltips is set', async () => {
+		renderChart( { withTooltips: true, rowLabels: [ 'Mon', 'Tue', 'Wed' ] } );
+		const grid = screen.getByRole( 'grid', { name: /heatmap/i } );
+		grid.focus();
+		await userEvent.setup().keyboard( '{ArrowDown}' );
+		await expect( screen.findByRole( 'tooltip' ) ).resolves.toBeInTheDocument();
+	} );
+
+	test( 'hides the keyboard tooltip on Escape', async () => {
+		renderChart( { withTooltips: true, rowLabels: [ 'Mon', 'Tue', 'Wed' ] } );
+		const grid = screen.getByRole( 'grid', { name: /heatmap/i } );
+		const user = userEvent.setup();
+		grid.focus();
+		await user.keyboard( '{ArrowDown}' );
+		await expect( screen.findByRole( 'tooltip' ) ).resolves.toBeInTheDocument();
+		await user.keyboard( '{Escape}' );
+		expect( screen.queryByRole( 'tooltip' ) ).not.toBeInTheDocument();
+	} );
+
+	test( 'renders a composition legend with Less/More labels', () => {
+		render(
+			<GlobalChartsProvider>
+				<HeatmapChart width={ 500 } height={ 300 } data={ data }>
+					<HeatmapChart.Legend />
+				</HeatmapChart>
+			</GlobalChartsProvider>
+		);
+		expect( screen.getByText( /less/i ) ).toBeInTheDocument();
+		expect( screen.getByText( /more/i ) ).toBeInTheDocument();
+	} );
+
+	test( 'ArrowDown moves focus within a column, ArrowRight moves to next column', async () => {
+		renderChart( { rowLabels: [ 'Mon', 'Tue', 'Wed' ] } );
+		const grid = screen.getByRole( 'grid', { name: /heatmap/i } );
+		const user = userEvent.setup();
+
+		// First ArrowDown lands on cell (0,0)
+		grid.focus();
+		await user.keyboard( '{ArrowDown}' );
+		expect( grid ).toHaveAttribute(
+			'aria-activedescendant',
+			expect.stringMatching( /-cell-0-0$/ )
+		);
+
+		// Second ArrowDown moves row 0→1 in col 0
+		await user.keyboard( '{ArrowDown}' );
+		expect( grid ).toHaveAttribute(
+			'aria-activedescendant',
+			expect.stringMatching( /-cell-0-1$/ )
+		);
+
+		// ArrowRight moves to next column, same row (col 0→1, row 1)
+		await user.keyboard( '{ArrowRight}' );
+		expect( grid ).toHaveAttribute(
+			'aria-activedescendant',
+			expect.stringMatching( /-cell-1-1$/ )
+		);
+	} );
+
+	test( 'ArrowUp and ArrowLeft move focus in the opposite direction', async () => {
+		renderChart( { rowLabels: [ 'Mon', 'Tue', 'Wed' ] } );
+		const grid = screen.getByRole( 'grid', { name: /heatmap/i } );
+		const user = userEvent.setup();
+
+		// Navigate to col 1, row 2 (bottom-right of a 2-col × 3-row grid)
+		// First ArrowDown lands on (0,0); subsequent presses move from there.
+		grid.focus();
+		await user.keyboard( '{ArrowDown}{ArrowDown}{ArrowDown}{ArrowRight}' );
+		expect( grid ).toHaveAttribute(
+			'aria-activedescendant',
+			expect.stringMatching( /-cell-1-2$/ )
+		);
+
+		// ArrowUp moves row 2→1 within col 1
+		await user.keyboard( '{ArrowUp}' );
+		expect( grid ).toHaveAttribute(
+			'aria-activedescendant',
+			expect.stringMatching( /-cell-1-1$/ )
+		);
+
+		// ArrowLeft moves col 1→0, same row
+		await user.keyboard( '{ArrowLeft}' );
+		expect( grid ).toHaveAttribute(
+			'aria-activedescendant',
+			expect.stringMatching( /-cell-0-1$/ )
+		);
+	} );
+
+	test( 'ArrowLeft at column 0 and ArrowUp at row 0 clamp (no wrap)', async () => {
+		renderChart( { rowLabels: [ 'Mon', 'Tue', 'Wed' ] } );
+		const grid = screen.getByRole( 'grid', { name: /heatmap/i } );
+		const user = userEvent.setup();
+
+		// Start at col 0, row 0 (first ArrowDown sets index to row 1; press ArrowUp back to row 0)
+		grid.focus();
+		await user.keyboard( '{ArrowDown}{ArrowUp}' );
+		expect( grid ).toHaveAttribute(
+			'aria-activedescendant',
+			expect.stringMatching( /-cell-0-0$/ )
+		);
+
+		// ArrowUp at row 0 stays at row 0
+		await user.keyboard( '{ArrowUp}' );
+		expect( grid ).toHaveAttribute(
+			'aria-activedescendant',
+			expect.stringMatching( /-cell-0-0$/ )
+		);
+
+		// ArrowLeft at col 0 stays at col 0
+		await user.keyboard( '{ArrowLeft}' );
+		expect( grid ).toHaveAttribute(
+			'aria-activedescendant',
+			expect.stringMatching( /-cell-0-0$/ )
+		);
+	} );
+
+	test( 'Escape clears the selection (aria-activedescendant removed)', async () => {
+		renderChart( { rowLabels: [ 'Mon', 'Tue', 'Wed' ] } );
+		const grid = screen.getByRole( 'grid', { name: /heatmap/i } );
+		const user = userEvent.setup();
+
+		grid.focus();
+		await user.keyboard( '{ArrowDown}' );
+		expect( grid ).toHaveAttribute( 'aria-activedescendant' );
+
+		await user.keyboard( '{Escape}' );
+		expect( grid ).not.toHaveAttribute( 'aria-activedescendant' );
+	} );
+
+	test( 'rows contain gridcell children in the ARIA hierarchy', () => {
+		renderChart();
+		const rows = screen.getAllByRole( 'row' );
+		expect( rows.length ).toBeGreaterThan( 0 );
+		rows.forEach( row => {
+			expect( within( row ).getAllByRole( 'gridcell' ).length ).toBeGreaterThan( 0 );
+		} );
+	} );
+
+	test( 'leaves cell gap and radius to WPDS tokens (no inline overrides)', () => {
+		renderChart();
+		const grid = screen.getByRole( 'grid', { name: /heatmap/i } );
+		// Non-compact sets no inline gap/radius — the SCSS falls back to the WPDS tokens.
+		expect( grid.style.getPropertyValue( '--heatmap-cell-gap' ) ).toBe( '' );
+		expect( grid.style.getPropertyValue( '--heatmap-cell-radius' ) ).toBe( '' );
+	} );
+
+	test( 'applies the compact gap inline from the theme compactCellGap', () => {
+		render(
+			<GlobalChartsProvider theme={ { heatmapChart: { compactCellGap: 3 } } }>
+				<HeatmapChart width={ 500 } height={ 300 } data={ data } compact />
+			</GlobalChartsProvider>
+		);
+		const grid = screen.getByRole( 'grid', { name: /heatmap/i } );
+		expect( grid.style.getPropertyValue( '--heatmap-cell-gap' ) ).toBe( '3px' );
+	} );
+
+	test( 'sizes compact cells to the theme compactCellSize', () => {
+		render(
+			<GlobalChartsProvider theme={ { heatmapChart: { compactCellSize: 20 } } }>
+				<HeatmapChart width={ 500 } height={ 300 } data={ data } compact />
+			</GlobalChartsProvider>
+		);
+		const grid = screen.getByRole( 'grid', { name: /heatmap/i } );
+		expect( grid.style.getPropertyValue( '--heatmap-cell-size' ) ).toBe( '20px' );
+		// Compact track template is built from the fixed cell size.
+		expect( grid.style.gridTemplateColumns ).toContain( 'var(--heatmap-cell-size)' );
+	} );
+
+	test( 'applies the primaryColor prop as the cell-scale color', () => {
+		renderChart( { primaryColor: '#abcdef' } );
+		const grid = screen.getByRole( 'grid', { name: /heatmap/i } );
+		expect( grid.style.getPropertyValue( '--heatmap-primary' ) ).toBe( '#abcdef' );
+	} );
+
+	test( 'resolves primaryColor from the chart theme', () => {
+		render(
+			<GlobalChartsProvider theme={ { heatmapChart: { primaryColor: '#0a0b0c' } } }>
+				<HeatmapChart width={ 500 } height={ 300 } data={ data } />
+			</GlobalChartsProvider>
+		);
+		const grid = screen.getByRole( 'grid', { name: /heatmap/i } );
+		expect( grid.style.getPropertyValue( '--heatmap-primary' ) ).toBe( '#0a0b0c' );
+	} );
+
+	test( 'falls back to the palette colors[0] when no prop or theme primaryColor is set', () => {
+		render(
+			<GlobalChartsProvider theme={ { colors: [ '#0a0b0c' ] } }>
+				<HeatmapChart width={ 500 } height={ 300 } data={ data } />
+			</GlobalChartsProvider>
+		);
+		const grid = screen.getByRole( 'grid', { name: /heatmap/i } );
+		expect( grid.style.getPropertyValue( '--heatmap-primary' ) ).toBe( '#0a0b0c' );
+	} );
+
+	test( 'the unresponsive export pins explicit width and height', () => {
+		render(
+			<GlobalChartsProvider>
+				<HeatmapChartUnresponsive width={ 480 } height={ 240 } data={ data } />
+			</GlobalChartsProvider>
+		);
+		const chart = screen.getByTestId( 'heatmap-chart' );
+		expect( chart ).toHaveStyle( { width: '480px', height: '240px' } );
+	} );
+
+	test( 'the responsive export leaves the chart unpinned so it fills its container', () => {
+		render(
+			<GlobalChartsProvider>
+				<HeatmapChart width={ 500 } height={ 300 } data={ data } />
+			</GlobalChartsProvider>
+		);
+		const chart = screen.getByTestId( 'heatmap-chart' );
+		expect( chart ).not.toHaveStyle( { width: '500px' } );
+		expect( chart ).not.toHaveStyle( { height: '300px' } );
+	} );
+} );

package/src/charts/heatmap-chart/test/use-heatmap-colors.test.ts

@@ -0,0 +1,34 @@
+import { getValueExtent, getNormalizedValue } from '../private/use-heatmap-colors';
+import type { HeatmapColumn } from '../types';
+
+const data: HeatmapColumn[] = [
+	{ label: 'A', data: [ { value: 0 }, { value: null }, { value: 10 } ] },
+	{ label: 'B', data: [ { value: 5 }, { value: 20 }, { value: null } ] },
+];
+
+describe( 'getValueExtent', () => {
+	test( 'returns [min, max] ignoring null/NaN', () => {
+		expect( getValueExtent( data ) ).toEqual( [ 0, 20 ] );
+	} );
+
+	test( 'returns [0, 0] for all-empty data', () => {
+		expect( getValueExtent( [ { data: [ { value: null } ] } ] ) ).toEqual( [ 0, 0 ] );
+	} );
+} );
+
+describe( 'getNormalizedValue', () => {
+	test( 'returns 0 at min and 1 at max', () => {
+		expect( getNormalizedValue( 0, [ 0, 20 ] ) ).toBe( 0 );
+		expect( getNormalizedValue( 20, [ 0, 20 ] ) ).toBe( 1 );
+	} );
+
+	test( 'returns a clamped value for points inside and outside the extent', () => {
+		expect( getNormalizedValue( 10, [ 0, 20 ] ) ).toBe( 0.5 );
+		expect( getNormalizedValue( 30, [ 0, 20 ] ) ).toBe( 1 );
+		expect( getNormalizedValue( -5, [ 0, 20 ] ) ).toBe( 0 );
+	} );
+
+	test( 'returns 1 when min === max', () => {
+		expect( getNormalizedValue( 7, [ 7, 7 ] ) ).toBe( 1 );
+	} );
+} );

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

@@ -0,0 +1,42 @@
+import type { BaseChartProps } from '../../types';
+import type { ReactNode } from 'react';
+
+/** A single heatmap cell. `value: null` marks an empty cell. */
+export type HeatmapCell = {
+	/** Per-cell label used in the tooltip / accessible name. */
+	label?: string;
+	value: number | null;
+};
+
+/** A heatmap column (rendered left→right); its cells render top→bottom. */
+export type HeatmapColumn = {
+	/** x-axis label for this column. Empty/omitted renders blank. */
+	label?: string;
+	data: HeatmapCell[];
+};
+
+export type HeatmapTooltipData = {
+	value: number | null;
+	rowLabel?: string;
+	columnLabel?: string;
+	cellLabel?: string;
+	row: number;
+	column: number;
+};
+
+export interface HeatmapChartProps
+	extends Omit< BaseChartProps< HeatmapColumn[] >, 'showLegend' | 'legend' | 'gridVisibility' > {
+	/** y-axis labels by row index. Empty entries render blank. */
+	rowLabels?: string[];
+	/** Compact mode: hide in-cell values, tighten gap, thin axis labels. Default false. */
+	compact?: boolean;
+	/** Render the numeric value inside each cell. Default `! compact`. */
+	showValues?: boolean;
+	/**
+	 * Color the cell scale interpolates toward at the highest value
+	 * (this prop > theme `heatmapChart.primaryColor` > palette `colors[0]`).
+	 */
+	primaryColor?: string;
+	renderTooltip?: ( data: HeatmapTooltipData ) => ReactNode;
+	children?: ReactNode;
+}

package/src/charts/index.ts

@@ -1,6 +1,7 @@
 export * from './bar-chart';
 export * from './bar-list-chart';
 export * from './conversion-funnel-chart';
+export * from './heatmap-chart';
 export * from './leaderboard-chart';
 export * from './line-chart';
 export * from './pie-chart';

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

@@ -1,5 +1,7 @@
 .leaderboardChart {
-	transition: opacity 0.3s ease-in-out;
+	transition:
+		opacity var(--wpds-motion-duration-lg, 300ms)
+		var(--wpds-motion-easing-subtle, cubic-bezier(0.15, 0, 0.15, 1));
 
 	&--responsive {
 		height: 100%;
@@ -56,7 +58,9 @@
 			transform-origin: left;
 			transform-box: fill-box;
 			transform: scaleX(0);
-			animation: stretch 1s ease-out forwards;
+			animation:
+				stretch var(--wpds-motion-duration-xl, 400ms)
+				var(--wpds-motion-easing-expressive, cubic-bezier(0.25, 0, 0, 1)) forwards;
 		}
 
 		@keyframes stretch {
@@ -79,7 +83,7 @@
 .emptyState {
 	padding: var(--wpds-dimension-padding-3xl, 32px) var(--wpds-dimension-padding-lg, 16px);
 	text-align: center;
-	color: #666;
+	color: var(--wpds-color-fg-content-neutral-weak, #707070);
 	font-size: var(--wpds-typography-font-size-md, 13px);
 	font-style: italic;
 }
@@ -118,11 +122,17 @@
 	// a grid item aligned to the inline start, so its inset mirrors in RTL; the
 	// value slide is given an RTL override below. No row background.
 	.bar {
-		transition: opacity 0.15s ease, width 0.15s ease;
+		transition:
+			opacity var(--wpds-motion-duration-sm, 100ms)
+			var(--wpds-motion-easing-subtle, cubic-bezier(0.15, 0, 0.15, 1)),
+			width var(--wpds-motion-duration-sm, 100ms)
+			var(--wpds-motion-easing-subtle, cubic-bezier(0.15, 0, 0.15, 1));
 	}
 
 	.valueContainer {
-		transition: transform 0.15s ease;
+		transition:
+			transform var(--wpds-motion-duration-sm, 100ms)
+			var(--wpds-motion-easing-subtle, cubic-bezier(0.15, 0, 0.15, 1));
 	}
 
 	&:hover,
@@ -172,7 +182,9 @@
 	margin-block: auto;
 	opacity: 0;
 	color: var(--wpds-color-fg-content-neutral-weak, #707070);
-	transition: opacity 0.15s ease;
+	transition:
+		opacity var(--wpds-motion-duration-sm, 100ms)
+		var(--wpds-motion-easing-subtle, cubic-bezier(0.15, 0, 0.15, 1));
 	pointer-events: none;
 
 	// The glyph points toward the inline end, so flip it to point left in RTL.

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

@@ -6,7 +6,9 @@
 		path {
 			transform-origin: 0 95%;
 			transform: scaleY(0);
-			animation: rise 1s ease-out forwards;
+			animation:
+				rise var(--wpds-motion-duration-xl, 400ms)
+				var(--wpds-motion-easing-expressive, cubic-bezier(0.25, 0, 0, 1)) forwards;
 		}
 	}
 
@@ -16,7 +18,8 @@
 
 	&__tooltip,
 	&__annotation-label-popover {
-		background: #fff;
+		background: var(--wpds-color-bg-surface-neutral-strong, #fff);
+		color: var(--wpds-color-fg-content-neutral, #1e1e1e);
 		padding: var(--wpds-dimension-padding-sm, 8px);
 	}
 
@@ -59,11 +62,10 @@
 
 	&__annotation-label-popover {
 		min-width: 125px;
-		background: #fff;
 		border: none;
 		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: fixed;
 		// Without margin set, the popover has margin:auto which upsets the
 		// positioning relative to the trigger button. A gap token is appropriate

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

@@ -29,7 +29,7 @@ import {
 	useGlobalChartsContext,
 	useGlobalChartsTheme,
 } from '../../providers';
-import { attachSubComponents } from '../../utils';
+import { attachSubComponents, resolveCssVariable } from '../../utils';
 import { useChartChildren } from '../private/chart-composition';
 import { ChartLayout } from '../private/chart-layout';
 import { DefaultGlyph } from '../private/default-glyph';
@@ -190,6 +190,10 @@ 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 );
 		const chartId = useChartId( providedChartId );
 		const chartRef = useRef< HTMLDivElement >( null );
@@ -485,7 +489,7 @@ const LineChartInternal = forwardRef< SingleChartRef, LineChartProps >(
 																		from={ color }
 																		fromOpacity={ 0.4 }
 																		toOpacity={ 0.1 }
-																		to={ providerTheme.backgroundColor }
+																		to={ resolvedBackgroundColor }
 																		{ ...seriesData.options?.gradient }
 																		data-testid="line-gradient"
 																	>

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

@@ -10,7 +10,7 @@ import { DataContext } from '@visx/xychart';
 import merge from 'deepmerge';
 import { useContext, useRef, useEffect, useState, useMemo } from 'react';
 import { useGlobalChartsTheme } from '../../../providers';
-import { isSafari } from '../../../utils';
+import { isSafari, resolveCssVariable } from '../../../utils';
 import LineChartAnnotationLabelWithPopover, {
 	POPOVER_BUTTON_SIZE,
 } from './line-chart-annotation-label-popover';
@@ -159,6 +159,11 @@ 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.
+	const resolveColor = ( value?: string ): string | undefined =>
+		value ? resolveCssVariable( value ) ?? value : value;
+
 	// Measure the label height once after initial render
 	useEffect( () => {
 		if ( labelRef.current?.getBBox ) {
@@ -264,8 +269,14 @@ const LineChartAnnotation: FC< LineChartAnnotationProps > = ( {
 	return (
 		<g data-testid={ testId }>
 			<Annotation x={ x } y={ y } dx={ dx } dy={ dy }>
-				<Connector { ...styles?.connector } />
-				{ subjectType === 'circle' && <CircleSubject { ...styles?.circleSubject } /> }
+				<Connector { ...styles?.connector } stroke={ resolveColor( styles?.connector?.stroke ) } />
+				{ subjectType === 'circle' && (
+					<CircleSubject
+						{ ...styles?.circleSubject }
+						fill={ resolveColor( styles?.circleSubject?.fill ) }
+						stroke={ resolveColor( styles?.circleSubject?.stroke ) }
+					/>
+				) }
 				{ subjectType === 'line-vertical' && (
 					<LineSubject
 						min={ yMax }
@@ -301,6 +312,8 @@ const LineChartAnnotation: FC< LineChartAnnotationProps > = ( {
 							title={ title }
 							subtitle={ subtitle }
 							{ ...styles?.label }
+							anchorLineStroke={ resolveColor( styles?.label?.anchorLineStroke ) }
+							backgroundFill={ resolveColor( styles?.label?.backgroundFill ) }
 							{ ...labelPosition }
 							horizontalAnchor={ getHorizontalAnchor( subjectType, isFlippedHorizontally ) }
 							verticalAnchor={ getVerticalAnchor(

package/src/charts/private/grid-control/grid-control.module.scss

@@ -1,10 +1,7 @@
-// Variables
-$grid-line-color: #d7d6d6;
-
 .grid-control {
 
 	:global(.visx-line) {
-		stroke: $grid-line-color;
+		stroke: var(--wpds-color-stroke-surface-neutral, #dbdbdb);
 		stroke-width: 1px;
 		shape-rendering: crispEdges;
 	}

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(--wpds-color-fg-content-neutral-weak, #6d6d6d);
+	color: var(--wpds-color-fg-content-neutral-weak, #707070);
 }